Shadcn UI 组件设计规范

解决什么问题

shadcn/ui 的代码是可复制的，但设计决策不可复制。团队常见困境是：每个组件都抄了，但间距、字号、色值各写各的，最终一套 UI 里出现三种灰、两种圆角、四套间距节奏。结果就是在 review 时反复争论"这个该用 14 还是 16"，而不是讨论产品逻辑。

另一个更隐蔽的问题是组件规则缺失。有了一个 Button 组件，不等于有了按钮规范：hover 和 focus-visible 的样式差多少？loading 态要不要保留图标？键盘用户按 Tab 过去时焦点环是否可见？空状态和超长文案如何布局？这些没有约束，每个实现者就各自发挥，最后看起来像多个项目拼在一起。

它如何工作

这个技能扮演的是设计规范作者的角色，产出的是可直接进代码库的指引文档，而不是营销文案。它按固定工作流展开：

• 先说意图：每条规则之前用一句话陈述设计意图，避免后面出现"看起来不对"这种无法执行的反馈。
• 先定令牌：在讨论组件之前先固化基础约束。这套规范的排版层级是 12/14/16/20/24/32，字体为 Geist（正文与展示）和 Fira Code（等宽），字重覆盖 100 到 900；间距只有 4/8/12/16/24/32 六个档位；语义色令牌包括 primary、success、warning、danger、surface、text。
• 再写组件规则：逐个组件定义 anatomy、variants、states 和交互行为。要求的交互状态包括 default、hover、focus-visible、active、disabled、loading、error，并分别覆盖键盘、指针和触摸三条输入路径。
• 附上验收标准：可访问性要求必须是可测试的。规范对齐 WCAG 2.2 AA，强调键盘优先交互和可见焦点态，不写"体验良好"这类无法在 review 中判定的话。
• 清理不一致 UI：给出反模式和迁移说明，帮助既有组件收敛到同一套规则。
• 收尾 QA 清单：最后输出一份能在 code review 中逐条执行的检查表。

输出结构是固定的：上下文与目标、令牌与基础、组件级规则、可访问性要求、文案与语气标准、反模式、QA 清单。

适用边界

这是一个写作型技能，不负责安装依赖、修改系统权限、创建持久化任务或下载内容。它给出的代码片段和命令默认只作参考，只有在你明确要求执行且目标范围清楚时才会运行。

外部写入操作——发送、发布、删除、付款、部署——都会先展示目标和影响，等你确认后再做。凭据只用于你指定的对应官方服务，不回显、不记录、不转发。

要注意的是，规范是 opinionated 的：间距只有六个档位、色板是固定的几个语义值。如果你的项目视觉语言与它差异较大，强行套用会把你现有组件推倒重来。这种情况下更适合抽取它的规则结构和验收标准写法，而不是直接采纳全部令牌值。

输出约束

规范用 must 标注不可协商的规则，用 should 标注推荐项。每条 Do 规则必须配至少一个具体的 Don't 示例。禁止依赖"和谐""优雅"这类模糊形容词立规，每条规则都要锚定到令牌、阈值或具体示例。当美观与可访问性冲突时，优先可访问性，并明确标出冲突点。

获取使用帮助和更多实用 Skill，请关注公众号「简诗 AI」，或在 SkillHub 搜索「简诗 AI」。