核心用法
本 Skill 为纯文档型配置指南，帮助开发者在项目中快速应用 shadcn/ui 的默认 Neutral（黑白灰）主题体系。核心流程包括：
1. 规划阶段：明确视觉需求，检查现有 globals.css、tailwind.config.ts、components.json 及暗黑模式配置状态，识别覆盖风险和版本兼容性问题。
2. 变量注入：将完整的 OKLCH 色彩变量写入 :root（浅色模式）和 .dark（深色模式），涵盖 background、foreground、card、popover、primary、secondary、muted、accent、destructive、border、input、ring 等核心语义化变量，以及 chart-1 至 chart-5 图表色和 sidebar 专属变量。
3. Tailwind 集成：针对 Tailwind v4 使用 @theme inline 指令注册变量为颜色类；针对 Tailwind v3 则扩展 tailwind.config.ts 的 theme.colors，注意 v3 使用 HSL 格式。
4. 暗黑模式配置：提供 Next.js（next-themes）、Nuxt、SvelteKit 等框架的暗黑模式切换实现代码，包含 ThemeProvider 包装和 ThemeToggle 组件示例。
5. 组件应用：严格遵循 background/foreground 配对规则，使用 bg-primary + text-primary-foreground 等工具类，禁止硬编码任意颜色值。
显著优点
- 官方规范：完全对齐 shadcn/ui 最新设计系统，确保与 50+ 官方组件（Button、Card、Dialog、Sidebar 等）无缝兼容。
- 现代色彩空间：采用 OKLCH 替代传统 HSL，感知均匀性更好，明暗对比更自然，且已通过 Tailwind v4 原生支持。
- 完整双模式：Light/Dark 两套色板经过精心调校，primary 在深色模式下自动反转为浅灰，无需额外维护条件类。
- 语义化命名：background/foreground、muted/accent/destructive 等抽象层级清晰，便于团队协作和主题扩展。
- 零依赖：纯 CSS 变量方案，无额外运行时开销，无第三方依赖引入。
潜在缺点与局限性
- 版本敏感：Tailwind v3 与 v4 配置方式差异显著（HSL vs OKLCH、config 文件 vs @theme 指令），需准确识别项目版本，否则会导致样式失效。
- 覆盖风险：直接应用可能覆盖用户已有的自定义主题变量，强制规划阶段的「现状调查」不可或缺。
- 定制灵活性有限：Neutral 主题以黑白灰为基调，若品牌需鲜明主色，需手动覆盖 primary 等变量，本 Skill 未提供动态主题生成能力。
- 无自动检测：Skill 本身不包含自动扫描项目配置的功能，依赖用户或 Agent 手动执行规划步骤。
适合的目标群体
- 使用 shadcn/ui 构建新项目的 React/Next.js 开发者
- 需要统一设计系统、消除硬编码颜色的既有项目维护者
- 希望快速获得专业级 Light/Dark 双模式配色方案的团队
- 学习现代 CSS 变量与 Tailwind 集成最佳实践的前端工程师
使用风险
- 配置误用风险：若混淆 Tailwind 版本配置，可能导致样式解析失败或构建错误。
- 主题冲突风险：未充分调查现有配置即执行，可能意外覆盖用户自定义的 brand colors。
- 视觉回归风险：大面积变量替换后，需人工验证各组件在双模式下的实际渲染效果，自动化测试难以覆盖视觉细节。
- 维护责任：主题配置属于基础设施变更，建议纳入版本控制并通知团队成员，避免后续开发中出现「颜色失效」困惑。