vite-shadcn-tailwind4

igorwarzocha/vite-shadcn-tailwind4

Design

About

SKILL.md

Protocol for initializing shadcn/ui with Tailwind CSS v4 in a **Vite** project. 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, You MUST use their respective shadcn installation guides.

- **Batching Rule**: You MUST use only for 2+ related questions; single questions use plain text. - **Syntax Constraints**: header max 12 chars, labels 1-5 words, mark defaults with `(Recommended)`. - **Purpose**: Clarify component selection, style preferences, and optional AI elements before running shadcn CLI. ## 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, You MUST help the user set up Tailwind v4 first.

## 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: You MUST update tsconfig.json to include compilerOptions:

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

## Step 3: Verify Vite Config You MUST confirm `vite.config.ts` has the Tailwind plugin and path alias:

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

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

## Step 4: Initialize Shadcn You MUST instruct the user to run: ```bash npx shadcn@latest init ```

You SHOULD recommend these settings:

Style: New York
Base Color: Neutral or Zinc
CSS Variables: Yes

You MUST wait for user confirmation before continuing.

## Step 5: Add Components You MUST instruct the user to run: ```bash npx shadcn@latest add ```

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

You MUST wait for user confirmation before continuing.

## Step 6: Add Extensions (Optional) If user wants AI elements, You MUST instruct them to run: ```bash npx shadcn@latest add @ai-elements/all ```

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

You MUST wait for user confirmation before continuing.

## Step 7: Install Missing Dependencies The CLI MAY miss dependencies. You 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

You MUST run if any are missing:

npm install tailwind-merge clsx class-variance-authority
npm install -D tw-animate-css

## Step 8: Clean CSS for v4 Compliance You MUST rewrite `src/index.css` to match strict v4 structure:

@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;
  }
}

You MUST remove these if present:

@media (prefers-color-scheme) blocks
Duplicate @theme blocks (keep only @theme inline)
@config directives

## Step 9: Verify Setup You MUST run typecheck to catch any issues: ```bash npm run lint ```

You MUST fix any TypeScript errors before marking setup complete.

SKILL.md

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

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

## 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: You MUST update tsconfig.json to include compilerOptions:

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

## Step 3: Verify Vite Config You MUST confirm `vite.config.ts` has the Tailwind plugin and path alias:

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

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

## Step 4: Initialize Shadcn You MUST instruct the user to run: ```bash npx shadcn@latest init ```

You SHOULD recommend these settings:

Style: New York
Base Color: Neutral or Zinc
CSS Variables: Yes

You MUST wait for user confirmation before continuing.

## Step 5: Add Components You MUST instruct the user to run: ```bash npx shadcn@latest add ```

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

You MUST wait for user confirmation before continuing.

## Step 6: Add Extensions (Optional) If user wants AI elements, You MUST instruct them to run: ```bash npx shadcn@latest add @ai-elements/all ```

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

You MUST wait for user confirmation before continuing.

## Step 7: Install Missing Dependencies The CLI MAY miss dependencies. You 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

You MUST run if any are missing:

npm install tailwind-merge clsx class-variance-authority
npm install -D tw-animate-css

## Step 8: Clean CSS for v4 Compliance You MUST rewrite `src/index.css` to match strict v4 structure:

@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;
  }
}

You MUST remove these if present:

@media (prefers-color-scheme) blocks
Duplicate @theme blocks (keep only @theme inline)
@config directives

## Step 9: Verify Setup You MUST run typecheck to catch any issues: ```bash npm run lint ```

You MUST fix any TypeScript errors before marking setup complete.