# Vite Shadcn Tailwind4

> Initialize shadcn/ui + Tailwind CSS v4 in Vite projects (Vite-specific, not Next.js/Remix). Use proactively for Vite project setup, shadcn component installation, or Tailwind v4 configuration. Examples: - user: "Setup shadcn in my Vite project" → install deps, configure tailwind v4 CSS-first, init shadcn, verify components work - user: "Add shadcn to existing Vite app" → check existing config, install CLI, add components.json, update CSS imports - user: "Use Tailwind v4 with shadcn" → configure @import with @theme, remove v3 config, setup custom tokens - user: "Create Vite + React + shadcn project" → scaffold Vite, install shadcn, configure theme, add sample components

- Skill: `jal-co/vite-shadcn-tailwind4` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jal-co/vite-shadcn-tailwind4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jal-co/vite-shadcn-tailwind4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jal-co (https://skillmd.com/u/jal-co)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jal-co/vite-shadcn-tailwind4

---


<overview>

Protocol for initializing shadcn/ui with Tailwind CSS v4 in a **Vite** project.

</overview>

<constraints>

This skill is Vite-specific due to:
- Vite's solution-style `tsconfig.json` (references pattern)
- `@tailwindcss/vite` plugin requirement
- CSS entry file conventions (`src/index.css`)

For Next.js, Remix, or other frameworks, MUST use their respective shadcn installation guides.

</constraints>

<guidelines>

## Question Tool Usage

- **Batching Rule**: MUST use only for 2+ related questions; single questions use plain text.
- **Syntax Constraints**: header MUST be max 12 chars, labels MUST be 1-5 words, SHOULD mark defaults with `(Recommended)`.
- **Purpose**: Clarify component selection, style preferences, and optional AI elements before running shadcn CLI.

</guidelines>

<workflow>

<phase name="verify-prerequisites">

## Step 1: Verify Prerequisites

Check that the project is ready:
- `vite.config.ts` MUST exist.
- `package.json` MUST contain `tailwindcss` (v4+) and `@tailwindcss/vite`.
- TypeScript MUST be configured.

If prerequisites are missing, MUST help the user set up Tailwind v4 first.

</phase>

<phase name="fix-typescript-aliases">

## Step 2: Fix TypeScript Aliases

The shadcn CLI fails if paths aren't in the root `tsconfig.json`. Vite uses a solution-style config with references, but shadcn doesn't parse those.

**Action**: MUST update `tsconfig.json` to include `compilerOptions`:

```json
{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

</phase>

<phase name="verify-vite-config">

## Step 3: Verify Vite Config

MUST confirm `vite.config.ts` has the Tailwind plugin and path alias:

```ts
import tailwindcss from "@tailwindcss/vite";
import path from "path";

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});
```

</phase>

<phase name="initialize-shadcn">

## Step 4: Initialize Shadcn

MUST instruct the user to run:
```bash
npx shadcn@latest init
```

SHOULD recommend these settings:
- Style: New York
- Base Color: Neutral or Zinc
- CSS Variables: Yes

**MUST wait for user confirmation before continuing.**

</phase>

<phase name="add-components">

## Step 5: Add Components

MUST instruct the user to run:
```bash
npx shadcn@latest add
```

SHOULD instruct them to select all components (`a` then Enter).

**MUST wait for user confirmation before continuing.**

</phase>

<phase name="add-extensions">

## Step 6: Add Extensions (Optional)

If user wants AI elements, MUST instruct them to run:
```bash
npx shadcn@latest add @ai-elements/all
```

SHOULD instruct them to answer **NO** to all overwrite prompts.

**MUST wait for user confirmation before continuing.**

</phase>

<phase name="install-missing-dependencies">

## Step 7: Install Missing Dependencies

The CLI MAY miss dependencies. MUST check `package.json` and install any missing.

**Required packages**:
- `tw-animate-css` (devDep) - v4 replacement for `tailwindcss-animate`
- `tailwind-merge` (dep) - used by `cn()` utility
- `clsx` (dep) - used by `cn()` utility
- `class-variance-authority` (dep) - used by shadcn components

**MUST run if any are missing**:
```bash
npm install tailwind-merge clsx class-variance-authority
npm install -D tw-animate-css
```

</phase>

<phase name="clean-css">

## Step 8: Clean CSS for v4 Compliance

MUST rewrite `src/index.css` to match strict v4 structure:

```css
@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:is(.dark *));

@theme inline {
  /* Variable mappings: --color-X: var(--X); */
}

:root {
  /* Token definitions using oklch() */
}

.dark {
  /* Dark mode tokens using oklch() */
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}
```

MUST remove these if present:
- `@media (prefers-color-scheme)` blocks
- Duplicate `@theme` blocks (keep only `@theme inline`)
- `@config` directives

</phase>

<phase name="verify-setup">

## Step 9: Verify Setup

MUST run typecheck to catch any issues:
```bash
npm run lint
```

MUST fix any TypeScript errors before marking setup complete.

</phase>

</workflow>