UI Skills

在使用 Claude、Cursor 或其他 AI 编程助手生成用户界面时，你是否曾遇到以下问题？

• 生成的代码混用多种 UI 组件库，导致维护困难；
• 动画滥用或性能不佳，影响用户体验；
• 忽略无障碍（a11y）要求，键盘导航失效；
• 使用 h-screen 导致移动端安全区域被遮挡；
• 颜色、间距、阴影随意定义，破坏设计一致性。

为解决这些问题，UI Skills 应运而生——它不是组件库，也不是框架，而是一套精简、明确、可执行的约束规范，专门用于指导 AI 智能体生成更高质量、更一致、更可维护的前端界面代码。

什么是 UI Skills？

UI Skills 是一套源于真实开发痛点的规则集合。每一条“必须”“禁止”“应该”，都来自作者在与 AI 协作构建 UI 时反复踩坑后的总结。它的目标很明确：让 AI 生成的界面代码更接近专业前端工程师的标准。

目前，UI Skills 已支持 Claude Code、Cursor、OpenCode 等主流 AI 编程平台，并可通过命令行工具直接集成到项目审查流程中。

快速安装与使用

安装只需一行命令：

curl -fsSL https://ui-skills.com/install | bash

使用方式有两种：

• 在对话中输入 /ui-skills，后续所有 UI 相关生成将自动遵循规范；
• 对现有代码进行审查：

  /ui-skills review src/
  

  工具会逐行检查违规项，并提供：

  • 违规代码片段
  • 为何重要（一句话说明）
  • 具体修复建议（含可替换代码）

核心约束概览

UI Skills 覆盖从技术栈到视觉设计的完整链路，以下是关键规则摘要：

技术栈

• 必须 使用 Tailwind CSS 默认配置，避免随意覆盖；
• 必须 用 cn()（结合 clsx + tailwind-merge）管理动态类名；
• 动画优先使用 motion/react（原 Framer Motion），微交互可搭配 tw-animate-css。

组件与无障碍

• 所有涉及焦点、键盘操作的元素，必须 基于 Base UI、React Aria 或 Radix 等无障碍基元；
• 禁止 在同一界面混用多个基元系统；
• 纯图标按钮必须 添加 aria-label；
• 禁止 手动重写键盘行为——除非明确要求。

交互细节

• 破坏性操作（如删除）必须 通过 AlertDialog 确认；
• 加载状态应使用结构性骨架屏，而非简单 spinner；
• 禁止 使用 h-screen，改用 h-dvh 以适配移动安全区域；
• 错误提示必须 出现在用户操作附近；
• 禁止 禁用 input 或 textarea 的粘贴功能。

动画原则

• 默认禁止动画，除非用户明确要求；
• 仅允许对 transform 和 opacity 进行动画；
• 禁止 动画 width、height、margin 等布局属性；
• 交互反馈动画不得超过 200ms；
• 必须 尊重 prefers-reduced-motion 用户偏好；
• 循环动画在离开视口时必须暂停。

排版与布局

• 标题用 text-balance，段落用 text-pretty；
• 数字展示必须 使用 tabular-nums（等宽数字）；
• 密集布局中应 使用 truncate 或 line-clamp 防止溢出；
• 禁止 随意调整 letter-spacing；
• 方形元素应 使用 size-*，而非重复写 w-* h-*；
• z-index 必须 遵循预设层级比例，禁止随意使用 z-50 这类魔法值。

性能与设计

• 禁止 对大范围 backdrop-filter 或 blur() 进行动画；
• 禁止 滥用 will-change；
• 禁止 用 useEffect 实现本可通过渲染逻辑表达的状态；
• 禁止 使用渐变（尤其紫色或多色渐变）；
• 发光效果不得 作为主要操作指引；
• 阴影应优先使用 Tailwind 默认比例；
• 空状态必须 提供清晰的下一步操作；
• 每个视图的强调色应限制为一种；
• 新颜色引入前，优先复用现有主题令牌。