vite-shadcn-tailwind4

在使用 Tailwind CSS v4 的 **Vite** 项目中初始化 shadcn/ui 的协议。 此技能专用于 Vite，原因如下： - Vite 的解决方案式 `tsconfig.json`（引用模式） - 必须使用 `@tailwindcss/vite` 插件 - CSS 入口文件约定（`src/index.css`）

对于 Next.js、Remix 或其他框架，必须使用相应的 shadcn 安装指南。

<question_tool>

• 分批提问规则：仅对 2 个或更多相关问题使用；单个问题请使用普通文本。
• 语法限制：标题最多 12 个字符，标签为 1-5 个词，默认选项标注 (Recommended)。
• 用途：在运行 shadcn CLI 前，确认组件选择、样式偏好和可选的 AI 元素。 </question_tool>

## 第 1 步：验证前置条件 检查项目是否已准备就绪： - 必须存在 `vite.config.ts`。 - `package.json` 必须包含 `tailwindcss`（v4+）和 `@tailwindcss/vite`。 - 必须配置 TypeScript。

如果缺少前置条件，必须先帮助用户设置 Tailwind v4。

## 第 2 步：修复 TypeScript 别名 如果路径未配置在根目录的 `tsconfig.json` 中，shadcn CLI 就会失败。Vite 使用带引用的解决方案式配置，但 shadcn 无法解析这种配置。

操作：必须更新 tsconfig.json，使其包含 compilerOptions：

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

## 第 3 步：验证 Vite 配置 必须确认 `vite.config.ts` 中包含 Tailwind 插件和路径别名：

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

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

## 第 4 步：初始化 Shadcn 必须指示用户运行： ```bash npx shadcn@latest init ```

建议使用以下设置：

• 样式：New York
• 基础颜色：Neutral 或 Zinc
• CSS 变量：是

必须等待用户确认后再继续。

## 第 5 步：添加组件 必须指示用户运行： ```bash npx shadcn@latest add ```

建议指示用户选择所有组件（输入 a，然后按 Enter）。

必须等待用户确认后再继续。

## 第 6 步：添加扩展（可选） 如果用户需要 AI 元素，必须指示他们运行： ```bash npx shadcn@latest add @ai-elements/all ```

建议指示他们对所有覆盖提示都回答 NO。

必须等待用户确认后再继续。

## 第 7 步：安装缺少的依赖项 CLI 可能会遗漏依赖项。必须检查 `package.json`，并安装所有缺少的依赖项。

必需的软件包：

• tw-animate-css（devDep）- tailwindcss-animate 的 v4 替代项
• tailwind-merge（dep）- 供 cn() 工具函数使用
• clsx（dep）- 供 cn() 工具函数使用
• class-variance-authority（dep）- shadcn 组件所用

如果缺少任何依赖项，必须运行：

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

## 第 8 步：清理 CSS，使其符合 v4 规范 必须重写 `src/index.css`，使其符合严格的 v4 结构：

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

如果存在，必须移除以下内容：

• @media (prefers-color-scheme) 块
• 重复的 @theme 块（仅保留 @theme inline）
• @config 指令

## 第 9 步：验证设置 必须运行类型检查以发现问题： ```bash npm run lint ```

在标记设置完成前，必须修复所有 TypeScript 错误。