UI-Skills：让 AI Agent 构建更好界面的约束规范

导语

随着 AI Agent 在代码生成领域的应用越来越广泛，一个显著的问题逐渐浮现：不同 AI 生成的界面代码风格差异巨大，质量参差不齐。**UI-Skills** 应运而生——这是一套专门为 AI Agent 设计的 UI 约束规范，通过明确的规则指导 AI 生成高质量、一致且可访问的用户界面。

UI-Skills 是什么？

UI-Skills 是一套”固执己见”（Opinionated）的 UI 约束规范，旨在帮助 AI Agent 构建更好的用户界面。它覆盖了从前端技术栈选择到具体实现细节的完整指南，确保 AI 生成的代码遵循最佳实践。

核心价值

• **一致性**：统一的代码风格和架构模式
• **可访问性**：内置 A11y 最佳实践
• **性能优化**：避免常见的性能陷阱
• **可维护性**：清晰的组件结构和命名规范

技术栈规范

UI-Skills 对技术栈有明确要求，这种约束确保了代码质量和一致性：

样式系统

• **必须**优先使用 Tailwind CSS 默认值（间距、圆角、阴影）
• **必须**使用 `cn` 工具函数（`clsx` + `tailwind-merge`）处理类名逻辑
• **应该**使用 `tw-animate-css` 处理入场和微动画

动画库

• **必须**使用 `motion/react`（原 framer-motion）处理 JavaScript 动画
• **禁止**混用多种动画库

组件库

• **必须**使用无障碍组件原语处理键盘和焦点行为（`Base UI`、`React Aria`、`Radix`）
• **必须**优先使用项目现有组件
• **禁止**在同一交互面混用不同的原语系统
• **应该**新项目优先选择 `Base UI`

核心约束规则

组件使用规则

✅ 必须为纯图标按钮添加 aria-label

✅ 必须使用 AlertDialog 处理破坏性操作

✅ 必须在操作位置旁显示错误信息

❌ 禁止手动重建键盘或焦点行为（除非明确要求）

❌ 禁止在 input/textarea 阻止粘贴操作

布局约束

✅ 必须使用 h-dvh 替代 h-screen

✅ 必须为固定元素预留安全区域（safe-area-inset）

✅ 应该使用 size-x 替代 w-x + h-x（正方形元素）

✅ 必须使用固定的 z-index 分层（禁止任意 z-x）

动画约束

✅ 只能动画合成器属性（transform、opacity）

✅ 入场动画应该使用 ease-out

✅ 必须遵守 prefers-reduced-motion

❌ 禁止动画布局属性（width、height、margin、padding）

❌ 禁止交互反馈超过 200ms

❌ 禁止动画大型图片或全屏表面

排版规范

✅ 标题必须使用 text-balance

✅ 正文必须使用 text-pretty

✅ 数据必须使用 tabular-nums

✅ 密集 UI 应该使用 truncate 或 line-clamp

❌ 禁止修改 letter-spacing（除非明确要求）

性能约束规则

UI-Skills 特别关注性能问题，避免 AI 生成低效代码：

❌ 禁止动画大型 blur() 或 backdrop-filter 表面

❌ 禁止在动画外使用 will-change

❌ 禁止用 useEffect 处理可用渲染逻辑表达的内容

设计约束规则

❌ 禁止使用渐变（除非明确要求）

❌ 禁止使用紫色或多彩渐变

❌ 禁止使用光晕效果作为主要交互指示器

✅ 应该使用 Tailwind 默认阴影

✅ 必须为空状态提供明确的下一步操作

✅ 应该每个视图限制使用一种强调色

与 Claude Skills 的关系

UI-Skills 可以作为 **Claude Skills** 的一种特殊形式使用：

1. **作为全局 Skill**：将 UI-Skills 规则存放在 `~/.claude/skills/ui-skills/`

2. **项目级 Skill**：在项目根目录 `.claude/skills/` 创建 UI 约束规则

3. **自定义扩展**：基于 UI-Skills 创建项目特定的 UI 约束

Claude Skill 示例

name: ui-skills-constraints

description: 强制执行 UI-Skills 约束规范的代码生成规则

UI 约束规则

动画规则

• 只动画 transform 和 opacity
• 交互反馈不超过 200ms
• 遵守 prefers-reduced-motion

组件规则

• 使用 Radix 或 Base UI 原语
• 为图标按钮添加 aria-label
• 破坏性操作使用 AlertDialog

禁止事项

• 禁止使用 h-screen，使用 h-dvh
• 禁止阻止 input 中的粘贴操作
• 禁止在布局属性上使用动画

实际应用场景

场景一：Claude Code 代码生成

当使用 Claude Code 生成前端代码时，UI-Skills 确保生成的代码：

• 遵循 Tailwind CSS 最佳实践
• 使用正确的组件原语
• 避免常见的性能和可访问性问题

场景二：团队规范统一

在团队开发中，UI-Skills 作为 AI 辅助开发的约束规范：

• 新成员快速了解团队 UI 规范
• AI 生成的代码与团队风格一致
• 减少 Code Review 的样式规范讨论

场景三：组件库开发

开发组件库时，UI-Skills 提供：

• 组件 API 设计指导
• 无障碍功能实现标准
• 性能优化基准

快速开始

1. 创建 Claude Skill

全局 Skill

mkdir -p ~/.claude/skills/ui-skills

cd ~/.claude/skills/ui-skills

创建 SKILL.md 文件

cat > SKILL.md << ‘EOF’

name: ui-skills

description: 执行 UI-Skills 约束规范

UI-Skills 约束规范

[在此处粘贴完整的 UI-Skills 规则]

EOF

2. 集成到项目

项目级 Skill

mkdir -p .claude/skills

cp ~/.claude/skills/ui-skills/SKILL.md .claude/skills/

3. 在 Claude Code 中使用

你：使用 TailwindCSS 创建一个登录表单

Claude：[自动遵循 UI-Skills 约束生成代码]

• 使用 Base UI 的 TextField 组件
• 添加 aria-label 和错误处理
• 使用 h-dvh 而非 h-screen
• 避免使用渐变和光晕效果

总结

UI-Skills 通过一套明确的约束规范，解决了 AI 生成前端界面代码时的质量和一致性问题。它不仅是一份规则文档，更是一种”Agent 友好”的设计系统思想。

**适用场景**：

• ✅ 使用 Claude Code 辅助前端开发
• ✅ 团队需要统一的 UI 规范
• ✅ 组件库和设计系统开发
• ✅ 追求可访问性和性能优化

**核心理念**：通过明确的约束，让 AI Agent 生成更好的界面代码。

**相关资源**：

• 官网：https://www.ui-skills.com/
• Claude Skills 文档：https://docs.anthropic.com/
• Tailwind CSS：https://tailwindcss.com/