uikit

uikit

AI 生成的 UI 有一种标志性风格。三个相同的功能卡片、紫色渐变、深灰色 slate-900 背景上的 Inter 字体、Hero 区域里用 div 搭出的假仪表盘、内容并非序列却在上方标着 01 / 02 / 03 的小标题。这些都不是 bug，也没有测试能捕捉到它们。它们是默认选项，因为模型没有理由选择其他方案。

uikit 正是为此而来。它提供约束，让 UI 决策成为这个项目的决策；它还会指出这些惯常特征，让人们有意识地避开它们，而不是无意间复现它们。

整个技能围绕一个理念展开：只有在没有其他约束决定选项时，才需要运用品味。 记录了设计系统的项目会保持一致性。已有上线组件的项目会遵循既有模式。全新项目则会从自身主题中汲取鲜明的设计观点。它们都不会采用默认选项。这就是优先级阶梯，其他所有章节都遵循它。

uikit 不是什么

• 不是设计系统记录工具。 DESIGN.md 只有一个负责人，而不是这个技能。uikit 会读取它，但绝不写入，因为一个既创造品味又记录品味的技能，无法诚实地履行这两项职责。
• 不是品味库。 不附带调色板、字体搭配或风格目录。包含 161 种调色板的查找表，恰恰会让所有基于它进行设计的项目最终看起来都一样。
• 不是代码审查员。 是否符合约定、是否正确、是否完整，属于通用审查的职责。uikit 的审查仅针对视觉和交互层面。
• 不是关卡。 预检会评估自己的输出，但绝不会让构建失败。品味不是通过或失败的检查项；会因此失败的构建，依赖的是无法证伪的标准。

何时触发

根据请求选择模式，读取该模式的文件，然后遵循其中的说明。此根目录中的所有内容适用于每种模式，模式文件不会重复这些内容。

• build。 “构建此页面”“添加设置界面”“让它看起来更好”“设计引导流程”，或实现步骤交付的任何 UI 工作。生成 UI。模式 build → 阅读 modes/build.md，然后遵循其中的说明。
• audit。 “这看起来像 AI 生成的吗”“审查我们的 UI”“为什么感觉像模板”“检查前端有没有粗制滥造”。只读检查。绝不写入任何内容。 模式 audit → 阅读 modes/audit.md，然后遵循其中的说明。
• mockup。 “绘制这个界面的模型”“给我看看这个会是什么样”“给我看看这个界面的几个方案”“绘制三个版本的模型”。生成图像；仅在用户要求代码时才生成代码。不写入源代码。模式 mockup → 阅读 modes/mockup.md，然后遵循其中的说明。

如果请求明确属于其中一种模式，直接执行。只有请求确实可能属于不同模式时才询问（例如“看看仪表盘”），因为 audit 不会改动内容，而 build 会编辑源代码。如果 mockup 请求还提到“用代码”“HTML”或“组件”，则按 build 处理。

在此技能中编写的每条交接说明都使用规程式语气：每句话只包含一条指令，使用主动语态和现在时，不使用比喻。

优先级阶梯

四个级别。取第一个匹配的级别，并在编写任何代码之前说明是哪一个。 较低级别绝不会覆盖较高级别；它只填补较高级别未规定的部分。

级别	匹配条件	约束内容
1. DESIGN.md	仓库根目录存在 DESIGN.md	其中的令牌就是调色板、字体比例、间距和圆角半径。到此为止。其「应该做」和「不应该做」就是 UI 文案的语气规则。
2. 已交付的组件	存在组件目录、components.json 或令牌配置位置（@theme、:root 自定义属性、主题配置）	现有的 Button 就是 Button。阅读三四个真实组件，并匹配它们的组合方式、命名和间距习惯。
3. 主题自身的世界	以上两项都不匹配，但可通过 README、上下文文件、路由名称、领域模型或正在构建的实际事物了解产品	产品的材料、词汇和产物。印刷店的工具不应该看起来像对冲基金的工具。
4. 技术栈默认值	从零开始，且主题确实不明	下方的默认方案，并明确说它是默认值，而不是选择。

独特性真正来自第 3 级。 它不是来自风格词汇，而是来自主题本身：它的工具、材料、行话，以及使用者已经在处理的产物。这是一口其他项目都无法取用的深井，正因如此，最终成果才不会流于泛泛。

各级别允许采用的标志性元素

级别规定标志性元素可以取材于何处，设计判断则说明标志性元素是什么：

• 第 1–2 级。 组合方式、交互和动效。令牌是固定的，不能随意改动。发挥空间在布局、界面的表现方式，以及静止时的样子。
• 第 3–4 级。 调色板、字体和网格也可以发挥。没有任何固定项，因此标志性元素可以体现在结构上。

第 1 或第 2 级搭配第 3 级调色板，是这项技能可能造成的破坏性最大的情况：一个格格不入的组件，出现在你到来之前始终保持一致的代码库里。

设计判断

五个明确声明的词，在编写任何代码之前说出来。 这很简单，却能阻止模型直接跳到默认美学上，因为只有把选择明确说出来，别人才有机会反驳。

Design read · surface: product · audience: internal ops staff · rung: 2 (shipped components)
· signature: the dirty state, where each changed row shows its old value struck through until Save
· density: compact

词	取值	用意
界面类型	product 或 marketing	两者的粗糙感特征截然不同；这会筛选目录中的样式
受众	自由文本，具体明确	“每天在这里待 6 小时的内部运营人员”意味着不同于“用 8 秒做决定的初次访客”的信息密度
级别	1–4，附上匹配项	声明当前生效的约束，以及标志性元素可以取材于何处
标志性元素	让人记住此界面的那个元素，以及它的材质	见下文
密度	compact、comfortable、spacious	唯一真正能独立于级别变化的维度

标志性设计

**每个界面只设一个元素，恰好一个。**如果有人被问到屏幕是什么样的，会用它来描述。周围的一切都应保持克制、有序，因此大胆的设计只放在一个地方，并删去所有与需求无关的装饰。

**标志性设计必须建立在已确定的行为之上。**先阅读计划、议题或请求。其中指定的每项行为（保存操作、确认步骤、字段、流程顺序）都必须按要求实现；标志性设计则体现在规范未明确的部分：呈现方式、反馈、布局、动效。若某个标志性设计构想会改变已指定的行为，就应在交接说明中将其作为建议，并选择一个合适的标志性设计来实现。

这里刻意没有将其表述为“冒一次创意风险”。要求大胆时，模型会检索自己所见过的大胆设计，而检索到的是所有大胆设计的平均值。如今这意味着三种风格之一：暖奶油色（接近 #F4F1EA），搭配高对比度衬线字体和赤陶色点缀；近黑色，搭配单一的亮酸绿或朱红色点缀；或采用报纸版式，配以极细分隔线、零圆角和密集分栏。这三种风格都适合某些需求，但如果不论主题是什么都使用它们，就不算做出了选择。

“说出这个屏幕最让人记住的一点”没有可回归的平均值。它也是唯一能通过上线前检查的做法：检查可以确认是否恰好存在一个标志性设计，以及其设计素材是否符合声明的级别要求，但无法检查是否真的承担了风险。

示例：

• **级别 2：规范中指定了保存操作的设置页面。**默认输出：卡片、左侧标签／右侧切换开关的行，右下角显示“保存更改”。正确，却令人过目即忘。标志性设计：未保存状态。每个已更改的行都在新值旁边显示删除线标记的旧值，保存栏则统计待保存的更改。无需新增 token，保存功能也仍然完全符合规范。只有在规范未规定保存模式时，自动保存才会是更鲜明的标志性设计；在这里，它应作为建议写入交接说明。
• **级别 3：为一家凸版印刷店设计的预约工具。**默认输出：Inter、slate-900、三张功能卡片、紫罗兰色 CTA。标志性设计：价格表就是一张字体样张，按实际字号展示文字，沿基线网格左对齐，并采用取自纸张和油墨的配色方案。

切勿因设计判断而停滞

**这是声明，不是访谈。**在级别 3 或 4 时，如果主题不明确，就根据代码库所呈现的内容推断并说明推断结果，绝不要停下来提问。明确说明的错误判断胜过正确却停滞：uikit 会在无人值守的流水线中运行，没有人可以回答问题，而明确说明的判断正是审阅者可以纠正的内容。只有在用户显然在线，且请求本身含糊不清时，才提问。

反俗套清单

纪律本身就是重点，并且应贯穿整份清单。只有同时满足以下条件，一项俗套迹象才值得列出：可以表述为一条禁令，并在旁边给出正确替代方案；Agent 还能够在不渲染任何内容的情况下检查自己的输出。上限为**约 30 条，通过增删替换来严格控制：每增加一条，就必须删除一条。**这样的清单很容易膨胀成上百条的核对表，没人会认真逐项检查；没人检查的核对表只是一种装饰。只能通过取舍来改进、而不是只会不断增长的限长清单，胜过无所不包的清单。

适用范围标签：P 产品 · M 营销 · B 两者

视觉与 CSS

	禁止	应改为
B	将紫罗兰色／紫色渐变用作强调色，放在主视觉区或主要 CTA 上	使用项目自身的强调色；达到第 3–4 档时，选择主题实际暗示的颜色
B	标题使用渐变文字	使用纯色；标题需要强调时，优先调整字重或字号
B	不假思索地使用毛玻璃效果：在半透明白色卡片上叠加 backdrop-blur	使用带有真实边框的不透明表面
B	每个表面都加投影	阴影用来表示层级；处于正常文档流中的卡片不应有阴影
B	所有元素都用 rounded-2xl／rounded-3xl	采用统一的圆角风格，并遵循系统规范
B	装饰性状态圆点，例如没有绑定任何状态的脉冲绿色圆点	将其绑定到真实状态，否则就删除

排版

	禁止	应改为
B	将 Inter（或裸用系统字体栈）搭配 slate-900 作为全部字体设计	有意识地指定展示字体和正文字体；让字体处理成为设计的一部分，而不是单纯的内容载体
M	每个标题上方都放眉题／引导标签	删除；如果章节需要上下文，就让标题承担这个作用
M	在并非序列的内容上使用 01 / 02 / 03 编号标记	仅在顺序是读者需要了解的信息时使用
B	界面文案中使用破折号	改用句号、逗号，或拆成两个句子。这条规则适用于屏幕上的文案，不适用于仓库中的文字
B	将全大写、字间距拉大的微型标签散布各处作为纹理	统一标签样式，仅在确实需要标签时使用

布局

	禁止	应改为
B	三张等宽的功能卡片	按真实数量和实际重要程度呈现；有四项功能就显示四张卡片
M	每个章节都居中，一路使用 max-w + mx-auto + text-center	灵活调整对齐方式；居中留给真正值得居中的内容
M	使用 Scroll ↓ 提示或弹跳的 V 形箭头	删除；内容延伸到首屏之外就能起到提示作用
M	装饰性的细线网格或点状背景	删除；结构应表达真实信息，而非装饰
M	沿章节侧边旋转排列的竖排文字	删除
M	地区／天气／当地时间信息条	删除，除非产品确实与时间或地点相关

内容与文案

	禁止	应改为
B	使用 “Jane Doe”／“John Smith” 作为占位人物	使用产品领域中的姓名，或展示真实的空状态
M	使用 “Acme Inc / Company Name” 标志行	展示真实客户；在有真实客户之前，删除该章节
M	编造指标（“99.99% uptime”、“10,000+ users”、“2M requests”）	使用真实数据，否则就不写数字
B	使用 Lorem ipsum	使用真实文案；信息未知时，写最简短的真实句子
M	使用虚构引言和图库头像制作推荐语卡片	在有真实内容之前，删除该章节

虚构产品

	禁止	应改为
M	用 div 搭建仪表板或应用截图	使用真实截图、嵌入式实时组件，或者什么都不放
M	在模拟图外套一层假的浏览器界面	同上；假的窗口框架是这份清单中最容易识破的标志

产品界面状态缺失

这些状态的缺失，就相当于产品端的紫色渐变：因为没人设计它们，只是生成结果如此。

	禁止	应改为
P	列表或表格在行数为零时不显示任何内容	展示空状态，说明对应对象，并提供创建对象的操作
P	没有加载状态	使用符合真实布局的骨架屏，或带标签的加载区域
P	没有错误状态	说明发生错误的内容，以及恢复操作
P	图标按钮没有可访问名称	添加 aria-label；图标含义不明显时，再添加工具提示
P	用 “Invalid input” 作为验证文案	说明限制条件和修正方法，例如：“密码需要至少 12 个字符”
P	禁用控件却不说明原因	说明禁用原因，否则就不要禁用
P	破坏性操作没有确认步骤，也无法撤销	添加确认步骤，或提供撤销功能；通常撤销功能更好

无障碍底线

这不是检查结果，而是底线。每次构建都会自动满足这些要求，不会专门提示；audit 会报告已发布界面中任何不符合要求的部分：

• 每个交互元素都要有可见的 :focus-visible 样式。移除焦点环时，绝不能不提供替代样式。
• 任何动画效果都要遵循 prefers-reduced-motion。安装了 motionkit 时，它会说明精简后的版本保留了哪些内容。
• 文本和有意义的非文本内容都要达到 WCAG AA 对比度。
• 优先使用语义化元素，而不是 ARIA：button 始终优于带有 role="button" 和点击处理程序的 div。
• 每个控件都要有标签，每张图片都要有 alt（装饰性图片应有意使用空 alt=""）。
• 所有内容都要能通过键盘访问和操作，Tab 顺序要合理；模态框打开时要限制焦点，关闭时要恢复焦点。
• 粗指针设备上的触控目标尺寸不得小于 44px。

技术栈层

Tailwind v4 和 shadcn/ui 的正确性规则见 stack.md。项目使用 Tailwind 或 shadcn/ui 时，请阅读该文件；使用其他技术栈时，请完全跳过。

移动端层

让手机上的 Web 应用表现得像已安装应用一样所需的修复（悬停状态残留、点击闪光、100vh、输入框缩放、安全区域、过度滚动、触控轴）见 mobile.md。界面要在手机上运行 → 阅读 mobile.md，然后按其要求处理；仅面向桌面的界面请完全跳过。

自我审查

始终执行的书面预检

默认执行的预检，也是无头 CI 和受限虚拟机中实际会运行的预检。根据以下内容检查输出：

1. 目录，按声明的界面类型筛选。
2. 无障碍底线，全部检查。
3. 两项标志性检查：标志性元素必须恰好有一个，且其材质必须符合声明的等级。
4. 移除一件装饰物检查。发布前，审视已构建的内容并去掉一样东西。几乎总有一处不符合需求的装饰，而且通常在最后比在一开始更容易看出来。

说明你修复了什么、保留了什么，并给出理由。这是审查，不是门槛，绝不会阻止构建。

像素检查，可选执行

仅在用户明确要求时执行（“看看效果”“截图并检查”）。有图可看时，一图胜千言。

按以下顺序使用现有资源：环境提供的浏览器自动化工具 · 已安装的无头浏览器，或项目中已有的测试自动化设置。将其指向渲染成本最低的对象：静态文件、组件预览路由，或用户已启动的开发服务器。

先通过 evaluate 调用读取事实（文本、计算样式、元素数量），再进行其他操作。默认不带图片截图。只有进行视觉判断时才使用图片；用户必须看到图片时，将其保存到文件。

绝不安装浏览器。绝不启动未经允许的开发服务器。绝不填充种子数据。 uikit 的要求远低于完整端到端工具：需要的是渲染结果，而不是驱动经过身份验证的流程。

明确说明限制

没有浏览器、无法渲染、没有文件系统：这些都是正常情况，不是错误。报告结果时要同时说明限制，绝不要把书面预检说成未通过的截图检查：

已构建 SettingsPanel.tsx 和 SettingsRow.tsx。根据产品目录和无障碍底线完成预检，结果合格。未进行视觉检查，因为此环境不提供浏览器自动化功能。

绝不要声称进行了实际上并未进行的视觉检查。明明无人查看，却报告 UI 已验证，远不如如实报告尚未验证。

完全没有文件系统（例如基于浏览器的 Agent）时，请将每个组件放入标注了预期路径的围栏代码块中，照常说明设计思路，并列出用户需要自行运行的命令。

说明

• 梯度优先于品味。 当记录在案的系统与你更好的想法发生冲突时，以系统为准，并将更好的想法作为建议写入交接说明。一致性能不断积累；一次性的改进则不会。
• 组合优先于创造。 优先使用现有组件，其次扩展现有组件，最后才考虑新建组件；每一步都要说明理由。
• 绝不编造数据。 不真实的数字、名称、徽标或引言，即使作为占位内容也不能发布。占位数据往往会留存到生产环境，而编造指标最容易让人出丑。
• 遵循项目现有惯例。 如果代码仓库有自己的组件模式、文件布局或样式方案，就应遵循；uikit 会说明遵循了哪种惯例。
• 界面文案写在这里，其他文字写在别处。 uikit 负责界面中的字符串。代码仓库中的说明文字、文档和 README 应由通用文案流程处理，也就是在已安装时使用 humankit。
• 不会提交更改。 更改会保持未暂存状态，以便在提交步骤中统一整理。