shadcn-tailwind-ui

shadcn + Tailwind UI

共享沟通规范

遵循 TW 简明语言与指导规则：首次使用术语时加以说明，保持用户选择的新人/入门/熟练/老手等级，并在每个等级都说明必要的更改和错误。Soul 和 prose 模式绝不会停用这项基准要求。

插件运行时

当此 Skill 通过插件、云主机或远程机器运行时，请在开始时阅读插件执行契约，并在执行特定于主机的命令前，完成主机、工具和持久化检查。遵守此 Skill 的适用范围、授权和验收门槛。

编写 UI 前，使用 $consult-tavernweave-library 和 shadcn-tailwind-ui 路由加载 A0、响应式/CSS 指南以及候选设计/动效参考。选择库或视觉方向并不代表获准安装依赖或覆盖现有配置。

在现有 React 代码库中开展实现工作时使用此技能。引入新内容前，保留项目的框架、包管理器、组件约定、设计令牌和已安装的 shadcn 组件。

设计和评审时遵循共享的前端设计质量 标准。主动研究相关先例，根据用户意图构思协调一致的整体设计，并在有帮助时通过视觉方式说明。默认应用 Awwwards 质量标准，移除无意义的短文案或装饰性英文文本。在请求范围内沿用项目已有的设计方向。

适用范围

• React、Vite 和 Next.js 应用。
• 基于 Radix UI primitives 的 shadcn/ui 组件。
• Tailwind CSS 工具类、语义令牌、响应式布局、深色模式和减少动效设置。
• 产品 UI，例如表单、对话框、导航、表格、设置、仪表板，以及空白/错误/加载状态。

此技能不提供字体、图片、画布设计、海报生成或第三方组件源代码。重新分发此技能前，请阅读 provenance.md。

工作流

1. 修改前检查项目：
   • 阅读 package.json、锁文件、components.json、CSS 入口文件和现有 UI 组件。
   • 检测 React 框架、Tailwind 主版本、路径别名、图标库、表单技术栈和包管理器。
   • 检查用户已有的更改，避免盲目替换配置或生成的组件。
2. 复用当前系统：
   • 优先使用已安装的 shadcn 组件，而非另外实现一套自定义基础组件。
   • 复用语义颜色、间距、圆角、排版和动效令牌。
   • 仅当行为或重复使用的变体确有需要时，才在本地扩展组件。
3. 先实现结构，再添加装饰：
   • 使用语义化 HTML，并保持标题顺序合理。
   • 提供标签、描述、错误关联、可见焦点、键盘操作，以及稳定的加载/错误/空白状态。
   • 使用基于 Radix 的基础组件组合对话框、菜单、标签页、选择器和弹出层，而非重新实现焦点管理。
4. 采用移动端优先的样式设计：
   • 从支持的最小视口开始，再添加少量断点覆盖规则。
   • 有意识地设置换行、min-w-0、溢出规则和内容约束。
   • 支持浅色/深色主题、200% 缩放、减少动效、长文本和触控目标。
5. 在真实项目中验证：
   • 在最小且有效的范围内运行项目的类型检查、lint、测试和构建。
   • 检查仅用键盘导航、焦点返回、表单错误、响应式断点、深色模式和减少动效。
   • 检查渲染后的 DOM 和计算布局；构建成功本身并不能证明 UI 行为正确。

组件规则

• 操作使用 Button，导航使用链接；不要为普通 div 元素添加点击行为。
• 每个输入框都需要无障碍名称。将错误和描述与对应的输入框关联。
• 仅图标控件必须有无障碍标签和可见的焦点状态。
• 破坏性操作需要措辞清晰，并根据影响程度进行确认。
• 对话框必须有标题、焦点限制、Escape 键处理，并在关闭后将焦点返回触发控件。
• 优先使用语义化令牌类，例如 bg-background、text-foreground 和 text-muted-foreground，而不是零散的字面颜色值。
• 避免在运行时拼接 Tailwind 类片段，因为编译器无法发现这些片段。请使用完整类名或显式 safelist。
• 遵循 prefers-reduced-motion；不能只通过动效传达状态。

Tailwind 配置安全性

优先使用项目现有配置。Tailwind 版本各不相同：在决定使用 JavaScript/TypeScript 配置还是以 CSS 为先的 @theme 自定义之前，请查阅已安装版本的官方文档。

对于有意使用配置文件的项目，scripts/generate_tailwind_config.py 是一个带防护措施的辅助工具：

# Default TypeScript format; dry run prints the proposed file and writes nothing.
python <skill-root>/scripts/generate_tailwind_config.py --framework react --format typescript --colors brand:#2563eb

# ESM JavaScript: tailwind.config.js with export default.
python <skill-root>/scripts/generate_tailwind_config.py --framework nextjs --format esm --write

# CommonJS: tailwind.config.cjs with module.exports; explicitly replace an existing file.
python <skill-root>/scripts/generate_tailwind_config.py --framework nextjs --format commonjs --force

tailwind.config.ts 请选择 typescript，tailwind.config.js 请选择 esm，tailwind.config.cjs 请选择 commonjs。与项目现有的模块模式保持一致；不要仅为适配生成器而更改 package.json。所选格式会同时决定默认扩展名和导出语法。只有 --force 可以覆盖文件。使用前请审查打印出的方案，并保留项目专属的内容路径、插件和令牌。

安装 shadcn 组件

将 shadcn CLI 视为会修改项目的工具：

1. 确认 components.json 和包管理器。
2. 检查所请求的组件是否已存在或有本地修改。
3. 固定或确认适用于项目的 CLI 版本。
4. 运行最小的 add 命令；默认不要使用 --all。
5. 审查生成的差异并运行项目检查。

未经用户明确授权，绝不要覆盖本地修改过的组件。

参考资料

• react-ui-checklist.md：精简的实现与验收清单。
• provenance.md：此干净衍生版本的来源与许可边界。