本文由 莫潇羽@源码七号站（www.fuyuan7.com）撰写，转载请注明出处。

快速摘要

核心结论：ui-skills 是一套面向设计工程师的 AI 编码智能体技能集合，它不生产组件，而是把界面实现与审查中的经验约束转化为 AI 可以理解和执行的规则层。 截至 2026 年 7 月，该项目在 GitHub 上已收获超过 3.7k Stars，并在 Claude Code、Cursor、GitHub Copilot、Codex 等主流 AI 编码工具中均可使用。它的核心价值在于：当你用 AI 生成前端代码时，ui-skills 会作为"质检员"确保代码符合基线规范、无障碍标准、元数据完整性和动画性能要求。整个项目共包含六个技能模块（baseline-ui、fixing-accessibility、fixing-metadata、fixing-motion-performance 四个核心审查模块，加上 improve-ui 综合改进技能和 ui-skills-root 路由入口），覆盖了从前端开发到交付审查的全链路。新手友好：只需一行 npx ui-skills start 就能启动交互式技能路由，AI 会自动匹配当前任务最合适的规则集。

简单说，这套工具解决的是 AI 编程领域最尴尬的问题——AI 能写代码，但写出来的东西往往"能跑但不专业"。 ui-skills 就是给 AI 装上了一套"专业设计师的审美标准和工程规范"。

想看完整拆解，往下翻。

一、AI 写前端代码的困境与 Skills 时代的到来

2026 年，用 AI 写前端代码早已不是什么新鲜事。Claude Code、Cursor、GitHub Copilot、OpenAI Codex——这些工具几乎成了每个前端开发者的标配。我自己（莫潇羽@源码七号站）日常开发中至少有 60% 的代码是 AI 辅助生成的。

但问题也很明显：AI 生成的代码能跑，但质量参差不齐。

同一个团队的三个开发者，用同一个 AI 工具写同一个页面，产出的代码风格可能天差地别。有人用的 Tailwind 间距是 p-4，有人随手写了 p-3.5；有人严格用了 Radix UI 的无障碍组件原语，有人直接写了个裸 <button>；有人做的动画丝滑顺畅只动了 transform 和 opacity，有人一上来就改 width 改 height，页面帧率直接掉到个位数。

这些不是"代码能不能运行"的问题，而是"代码够不够专业"的问题。前者 AI 已经解决得差不多了，后者才是 2026 年真正卡住团队的瓶颈。

1.1 从 Prompt 工程到 Skills 工程

回顾 AI 编程的发展，大概可以划三条线：

• 2023 到 2024 年：Prompt Engineering 时代。 大家研究怎么给 AI 下指令，怎么措辞才能让输出更准。"请用 Tailwind CSS 写一个响应式导航栏"——这就是典型的 Prompt。
• 2025 年：Context Engineering 时代。 大家发现光有好指令不够，还得给 AI 配足够的上下文。项目结构、技术栈、代码风格指南，能塞进上下文窗口的都往里塞。
• 2026 年：Skills Engineering 时代。 上下文越塞越多，窗口总有上限。于是 Skills 出现了——它不是一次性的指令，而是可复用、可组合、可跨工具共享的专业知识包。

这个演进的方向很清晰：从"单次沟通"走向"长期记忆"，从"人指挥 AI"走向"AI 自动遵循规范"。

Prompt 是你跟 AI 说的一句话。Skills 是你跟 AI 建立的长期协作关系。你用 AI 写了上百个页面，Prompt 的方式意味着你每次都要重复告诉 AI"用 Radix UI、别自己写焦点逻辑、动画只用 transform 和 opacity"。Skills 的方式是——把这些规则写成一套标准化的技能文件，AI 每次干活前自动加载，你只需要说"干活"——干净利落，一步到位。

Anthropic 在 2025 年 10 月正式发布了 Agent Skills 概念，同年 12 月将 Skills 规范开源为开放标准。到 2026 年年中，这个标准已经被 Claude Code、Cursor、OpenAI Codex、GitHub Copilot、Windsurf、Cline 等主流工具全面支持。GitHub 上的 Skills 官方仓库 anthropics/skills 收获了超过 12 万 Stars，社区的技能生态彻底爆发。

1.2 前端开发为什么最需要 Skills

在所有编程领域里，前端可以说是最需要 Skills 的。原因很简单：前端开发的主观判断项太多了。

后端写接口，有明确的输入输出规范，有 Swagger 文档，有单元测试——对错很清晰。前端呢？间距是 16px 还是 18px？按钮圆角是 6px 还是 8px？表单的错误提示放在输入框上面还是下面？焦点环要不要有？什么颜色？多粗？

这些事情没有绝对的对错，但有"专业"和"业余"的区别。一个经验丰富的设计工程师能一眼看出业余代码的问题，但 AI 不会——除非你把这些经验"喂"给它。

这就是 ui-skills 这类项目诞生的背景。它不是组件库，不是脚手架，而是一套编码了设计工程经验的可执行规则。它告诉 AI："动画只能动 transform 和 opacity"、"破坏性操作必须弹 AlertDialog 确认"、"固定元素要尊重 safe-area-inset"——这些都是资深前端设计师的肌肉记忆，现在被固化成 AI 能理解的技能文件。

二、Agent Skills 到底是什么：从 Prompt 到 Skills 的范式跃迁

聊了这么多 Skills，还没仔细说清楚它到底是什么。这一节我们掰开揉碎来讲。

2.1 Prompt 和 Skill 的本质差距

用一个表格来对比，会更直观：

一句话总结：Prompt 是建议，Skill 是约束。 AI 可以忽略 Prompt 里的某些建议，但 Skill 里标记为 MUST 的规则，AI 必须遵守。

2.2 Skills 的三大核心机制

Skills 之所以能比 Prompt 更进一步，靠的是三个关键设计：

机制一：封装性。 一个 Skill 是一个独立的文件夹，里面通常包含：

• SKILL.md：技能的核心描述、触发条件、执行步骤
• 可选的脚本文件（Python/Bash/JS）
• 可选的模板文件和数据文件
• 可选的子规则文件

所有跟这个技能相关的知识、逻辑、工具，全部封装在一起。AI 加载这个 Skill 时，一次性获得完整的"专业能力包"。

机制二：渐进式披露。 这是 Skills 最巧妙的设计。AI 不会一上来就把整个 SKILL.md 的全部内容都读进上下文窗口。第一步只加载技能的元数据（名称和简介），判断这个技能跟当前任务是否相关。确定相关后，才加载详细指令。如果技能还包含子规则，也是用到哪个加载哪个。

这就解决了一个关键矛盾：知识越详细越好，但上下文窗口越大越贵。 渐进式披露让 Skills 可以在不过度消耗上下文的前提下，携带非常详细的专业知识。

机制三：跨工具兼容。 Anthropic 在 2025 年 12 月将 Skills 规范开源后，Cursor、Codex、Windsurf 等工具都基于同一套 SKILL.md 格式来加载技能。这意味着你为 Claude Code 写的 Skill，拿到 Cursor 上大概率也能直接用。对社区来说，这极大地降低了技能的维护成本和复用门槛。

2.3 2026 年 Skills 生态数据一览

截至 2026 年 7 月，Skills 生态已经相当成熟。以下是一些关键数据（注意：这些数字变化非常快，以下为写稿时的近似情况，请以各平台实时数据为准）：

Skills 已经从开发者圈层渗透到了普通职场用户。有大量非技术用户用 Skills 做旅行规划、PPT 制作、邮件整理——但这种"出圈"并不意味着 Skills 变得浅薄了，恰恰相反，它说明这套机制的可扩展性足够强，既可以承载高精尖的工程规范，也可以处理日常办公任务。

对前端开发者来说，值得关注的是：在 Skills 生态中，面向前端/设计/UI 的技能是增长最快的品类之一。 Anthropic 官方的 frontend-design、Vercel 的 react-best-practices、以及本文的主角 ui-skills，构成了设计工程技能的三驾马车。

三、深入 SKILL.md：标准化的"技能说明书"怎么运作

Skills 的技术核心是 SKILL.md 这个文件。理解它的结构，你就理解了 Skills 是怎么让 AI "变专业"的。

3.1 SKILL.md 的基本结构

一个标准的 SKILL.md 文件由两部分组成：

第一部分：YAML Frontmatter（元数据头）

---
name: baseline-ui
description: >
  Enforces an opinionated UI baseline to prevent AI-generated interface slop.
  Use when building new components, reviewing UI code, or cleaning up an interface.
---

这部分告诉 AI："这个技能叫什么、干嘛用的、什么时候该加载它。" AI 在渐进式披露的第一步，就是扫描这个元数据头来判断技能是否匹配当前任务。

第二部分：Markdown 正文（指令与规则）

元数据之后是详细的 Markdown 正文，包含具体的规则、约束、执行步骤和示例代码。这部分只在 AI 确定加载该技能后才会被完整读取。

一个典型的规则条目长这样：

## Animation

-  MUST only animate `transform` and `opacity` — never `width`, `height`, 
  `top`, `left`, or other layout-triggering properties
-  SHOULD use `motion/react` for declarative animations
-  NEVER use `setTimeout` for animation sequencing — use `animate` API or 
  `motion/react` orchestration instead

3.2 YAML Frontmatter 的关键字段

下面是一个更完整的 frontmatter 示例，列出了常用字段：

---
name: my-skill-name
description: >
  A clear description of what this skill does and when the agent should use it.
  Be specific about the trigger conditions.
version: 1.0.0
author: your-name
tags:
  - frontend
  - tailwindcss
  - accessibility
dependencies:
  - radix-ui
  - motion/react
platforms:
  - claude-code
  - cursor
  - codex
---

其中 name 和 description 是必填的。description 的写法非常讲究——它决定了 AI 能不能在恰当的时机正确触发这个 Skill。写得太宽泛，技能会被误触发；写得太窄，该触发时又触发不了。

3.3 为什么 SKILL.md 成了"行业标准"

Anthropic 在 2025 年 10 月推出 Agent Skills 时，选择了一个非常聪明的策略：用 Markdown 作为技能描述语言，而不是发明一套新 DSL。

这个决策带来了几个好处：

1. 学习成本为零。 Markdown 是程序员最熟悉的书写格式，不需要额外学习。
2. 版本管理友好。 Markdown 是纯文本，Git diff 天然支持，做 Code Review 和版本对比都很方便。
3. 人和 AI 都能读。 人打开 SKILL.md 可以直接阅读和理解规则，AI 解析起来也没有障碍。
4. 生态扩散快。 因为门槛低，社区贡献者的参与度极高。ui-skills 本身就是一个很好的例子——它完全由社区驱动，每个技能模块都是独立的 SKILL.md 文件。

到 2026 年，SKILL.md 格式已经被 Anthropic 和 OpenAI 两个阵营广泛接受。虽然两者在前端 matter 的字段命名上有些微小差异（比如 Anthropic 用 description，OpenAI Codex 的格式里也完全兼容），但核心结构和理念 99% 一致。这意味着社区开发者可以"一次编写，到处运行"——这是 Skills 生态能快速膨胀的关键基础。

3.4 一个最小可用的 SKILL.md 示例

为了让你对 SKILL.md 有个直观感受，这里模拟一个简化版的"组件间距规范"技能：

---
name: spacing-standards
description: >
  Enforce consistent spacing rules using Tailwind CSS default scale.
  Use when building or reviewing layout components.
---

# Spacing Standards

## Rules

-  MUST use Tailwind default spacing scale (0, 1, 2, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96)
-  NEVER use arbitrary spacing values like `p-[13px]` or `m-[7px]`
-  SHOULD use `gap` instead of `margin` for flex/grid children spacing
-  SHOULD prefer `space-y-*` for vertical rhythm in stacked content

## Rationale

Using the default spacing scale ensures visual consistency across the entire
application. Arbitrary values make the design system unpredictable and harder
to maintain.

这个文件不到 30 行，但它编码了一条经验丰富的设计师会在 Code Review 时反复强调的规范。把它丢给 AI，AI 就会在生成和审查代码时自动遵循。

接下来，我们正式进入 ui-skills 的世界，看看它是怎么把这个思路做到极致的。

四、ui-skills 项目全景：设计工程师的 AI 技能军火库

4.1 作者与项目背景

ui-skills 的创建者是 Julien Thibeaut（GitHub ID: ibelick），一位在 GitHub 上拥有超过 1600 位粉丝的开发者。他的作品列表里还有 prompt-kit（AI 应用核心构建块）和 motion-primitives（动画界面 UI 套件），看得出来，他一直在"设计工程 × AI 工具"这个交叉领域深耕。

ui-skills 诞生的契机其实很朴素：Julien 发现，AI 生成的 UI 代码虽然能跑，但总有一种说不清的"廉价感"。间距不对、色彩不统一、焦点管理缺失、动画卡顿——这些问题单个看都不致命，但堆在一起，整个产品的质感就差了一大截。

于是他开始系统性地整理自己在设计工程中积累的规范，把它们写成 SKILL.md 文件，让 AI 在生成代码时自动加载。这就是 ui-skills 的起点。

4.2 项目定位：规则层，不是组件库

这是理解 ui-skills 最关键的一点：它不是一个 UI 组件库。 它不包含任何 React 组件、Vue 组件或 CSS 文件。

ui-skills 是一个规则层。你可以把它想象成一位坐在 AI 旁边的资深设计师——AI 写代码，ui-skills 在旁边说："这里间距不对，用 Tailwind 的标准值"，"这个按钮没有 aria-label，屏幕阅读器用户没法用"，"这个动画改 width 了，换成 transform 做"。

它的定位决定了它跟 shadcn/ui、Radix UI、Ant Design 这些组件库不是竞争关系，而是互补关系。你用 shadcn/ui 写组件，用 ui-skills 确保你写出来的组件符合最佳实践。

4.3 npm 注册信息与获取方式

ui-skills 已经发布在 npm 上（注意：npm 上存在一个同名但无关的 @springernature/ui-skills 包，本文讨论的 npx ui-skills CLI 命令来自 ibelick/ui-skills 项目），通过 npx ui-skills 即可使用。项目的 GitHub 仓库地址是 https://github.com/ibelick/ui-skills，官网是 ui-skills.com。

下面是写稿时（2026 年 7 月）项目的一些关键数据：

4.4 技能路由：AI 的"智能调度"怎么工作

ui-skills 的另一个聪明设计是技能路由（Skill Routing）。

当你运行 npx ui-skills start 时，系统会启动一个交互式界面，让你选择当前任务类型。选完之后，ui-skills 不会一股脑把所有技能都丢给 AI，而是根据任务类型精准匹配最合适的技能集。

这个设计的价值在于：避免上下文窗口浪费。 如果你只是在做一个简单的按钮组件，AI 不需要知道元数据管理的全部规则。如果你在修动画性能，AI 不需要加载无障碍审计的完整技能。技能路由就像一个智能调度员，只加载当前任务真正需要的规则。

路由逻辑大致如下（用 Mermaid 图来直观展示）：

graph TD
    A[npx ui-skills start] --> B{选择任务类型}
    B -->|构建新组件| C[加载 baseline-ui]
    B -->|审查现有代码| D{审查什么方面?}
    B -->|修复特定问题| E{什么问题?}
    D -->|基础质量| C
    D -->|无障碍| F[加载 fixing-accessibility]
    D -->|元数据| G[加载 fixing-metadata]
    D -->|动画性能| H[加载 fixing-motion-performance]
    D -->|综合审查| I[加载 improve-ui]
    E -->|动画卡顿| H
    E -->|SEO 问题| G
    E -->|无障碍缺陷| F
    C --> J[AI 按规则生成/审查代码]
    F --> J
    G --> J
    H --> J
    I --> J

这里想特别提一下 ui-skills-root 这个技能——它是所有技能的入口和总览。如果你的任务目标很清晰，可以直接指定技能；如果不确定该用哪个，ui-skills-root 会帮你做判断。这个设计跟网络协议里的"默认路由"很像，确保了各种场景下都有兜底逻辑。

五、核心技能模块逐一拆解（四个审查模块 + improve-ui）

这一节是全文的重头戏。我们把 ui-skills 的四个核心技能模块一个一个拆开看——每个模块的规则长什么样、解决了什么问题、实际怎么用。

5.1 baseline-ui：UI 基线的"地基标准"

baseline-ui 是 ui-skills 技能体系的地基。它的定位是：防止 AI 生成"廉价感"界面。 所谓"廉价感"，就是那种一看就是 AI 写的、间距忽大忽小、色彩随意搭配、排版毫无节奏的界面。

baseline-ui 从八个维度对 UI 代码进行约束：

技术栈约束

-  MUST use Tailwind CSS for all styling
-  MUST use Radix UI, Base UI, or React Aria as accessible component primitives
-  NEVER use raw HTML elements when an accessible primitive exists
-  SHOULD use `motion/react` for animations

这里特别值得说的一个规则是：禁止用裸 HTML 元素替代已有无障碍组件原语。 举个例，你写了一个 <button> 标签，功能上完全没问题，但它缺少 Radix UI Button 自带的 focus-visible 样式、键盘事件处理和 ARIA 属性。baseline-ui 会标记这个为违规——不是因为你写错了，而是因为有更好的选择。

排版规范

-  MUST use Tailwind's default font-size scale (text-xs, text-sm, text-base, 
  text-lg, text-xl, text-2xl, etc.)
-  NEVER use arbitrary font-size values like text-[15px]
-  SHOULD limit line-height to 1.5-1.75 for body text
-  SHOULD maintain a consistent typographic scale across headings

Tailwind 默认的字号体系是经过精心设计的，text-sm（0.875rem/14px）和 text-base（1rem/16px）之间的跳跃是经过大量可读性研究验证的。随手写一个 text-[15px] 看似"差不多"，但它破坏了整个字号体系的节奏感。baseline-ui 替你把这些问题都拦住了。

布局约束

-  MUST use `h-dvh` instead of `h-screen` for full-height layouts
-  MUST respect `safe-area-inset` for fixed/absolute positioned elements
-  SHOULD use CSS Grid for page-level layouts, Flexbox for component-level
-  NEVER use negative margins for layout positioning

h-screen vs h-dvh 这个区别，很多人可能不知道。100vh 在移动端浏览器上会因为地址栏的显示/隐藏而产生布局跳动——地址栏出现时页面高度变小，地址栏收起时变大。dvh（dynamic viewport height）就是为了解决这个问题引入的。ui-skills 直接把这个最佳实践写成强制规则，AI 想不遵守都不行。

safe-area-inset 是另一个容易被忽略的点。iPhone 的刘海屏、底部 Home Indicator 区域，如果固定定位的元素不考虑 safe-area，内容就会跟系统 UI 重叠。

色彩与设计规范

-  MUST use Tailwind's semantic color tokens (bg-primary, text-secondary, etc.)
  rather than raw color values
-  NEVER use heavy blur effects (backdrop-blur-xl, blur-2xl) without performance 
  consideration
-  SHOULD avoid arbitrary gradient combinations — use predefined gradient utilities
-  MUST ensure contrast ratio ≥ 4.5:1 for normal text, ≥ 3:1 for large text

色彩相关有一条我很认同：禁止不经性能考量就使用重度模糊效果。 backdrop-blur 在低端设备上会严重拖累渲染性能，很多设计师在 Figma 里随手加一个模糊就觉得很美，但到了真实设备上就变成性能灾难。baseline-ui 把这个写进规则，相当于在代码生成阶段就杜绝了这个问题。

交互模式

-  MUST use `AlertDialog` for any destructive action (delete, remove, reset)
-  NEVER manually manage focus — use the focus management from accessible primitives
-  SHOULD provide visual feedback (hover, active, focus-visible) for all 
  interactive elements
-  SHOULD implement keyboard navigation for all interactive components

"破坏性操作必须弹 AlertDialog 确认"——这条规则看起来是常识，但在 AI 生成的代码里，直接绑一个 onClick={handleDelete} 而没有确认弹窗的情况比比皆是。baseline-ui 把这类"常识"固化为强制规则，减少了大量 Code Review 时的低级发现。

下面用一张表来总结 baseline-ui 的八个维度：

5.2 fixing-accessibility：无障碍审计的"自动化质检"

如果 baseline-ui 管的是"好不好看"，那 fixing-accessibility 管的就是"能不能用"——这里的"能不能用"，指的是所有用户，包括依赖屏幕阅读器、键盘导航、语音控制的用户。

fixing-accessibility 会系统地审计以下方面：

ARIA 属性完整性

-  MUST provide `aria-label` or `aria-labelledby` for all interactive elements 
  without visible text
-  MUST use appropriate `role` attributes for custom components
-  NEVER use `aria-hidden="true"` on focusable elements
-  SHOULD use `aria-describedby` to provide additional context for complex inputs

这里有一个经典的坑：图标按钮。比如一个只有 SVG 图标的关闭按钮，如果不用 aria-label="关闭"，屏幕阅读器用户完全不知道这个按钮是干嘛的。fixing-accessibility 会逐个扫描这类元素，把缺失的 ARIA 属性标出来。

键盘导航

-  MUST ensure all interactive elements are reachable via Tab key
-  MUST implement arrow key navigation for composite components (tabs, menus, grids)
-  NEVER trap focus without providing an escape mechanism
-  SHOULD provide skip-to-content link for long pages

键盘导航是无障碍的基石。很多前端开发者自己用鼠标用得飞起，完全没意识到有些组件键盘根本操作不了。fixing-accessibility 会模拟键盘导航路径，检查每个交互元素是否可达。

焦点管理

-  MUST maintain a visible focus indicator (focus-visible ring) on all 
  interactive elements
-  MUST move focus appropriately after modal open/close, page navigation
-  NEVER use `outline: none` without providing an alternative focus style
-  SHOULD use `:focus-visible` instead of `:focus` for focus styling

outline: none 是最常见的无障碍违规——开发者觉得默认的焦点环"丑"，就给它去掉了，然后也不提供替代样式。结果就是键盘用户完全不知道当前焦点在哪里，这跟把门拆了却不安把手是一个道理。

语义化 HTML

-  MUST use semantic HTML elements (nav, main, article, aside, etc.)
-  MUST use proper heading hierarchy (h1 > h2 > h3, no skipping levels)
-  MUST associate form labels with inputs using `htmlFor` or nesting
-  SHOULD use `fieldset` + `legend` for grouped form elements

下表列出了 fixing-accessibility 审计的核心检查项：

5.3 fixing-metadata：页面元数据的"SEO 守护者"

fixing-metadata 是一个针对性很强的技能——它只检查页面的 <head> 区域和元数据配置。这个技能特别适合在上线前做最后一轮检查。

Open Graph 与社交分享

-  MUST include `og:title`, `og:description`, `og:image`, and `og:url` meta tags
-  MUST provide `og:image:width` and `og:image:height` for faster social preview
-  SHOULD include `twitter:card` for Twitter/X sharing preview
-  SHOULD provide `og:type` appropriate to the page type

很多人不知道 og:image:width 和 og:image:height 这两个属性，但它们在社交平台上的加载速度影响很大。如果不提供尺寸，社交平台需要先下载图片才能确定布局，导致预览卡片闪烁。

SEO 关键元数据

-  MUST include a unique, descriptive `<title>` for every page
-  MUST include `<meta name="description">` on all indexable pages
-  MUST include `<meta name="viewport">` with correct content
-  SHOULD include canonical URL to prevent duplicate content issues
-  SHOULD include `<meta name="robots">` where appropriate

Favicon 与 PWA

-  MUST include favicon links (at minimum: 32x32 PNG + SVG)
-  SHOULD include apple-touch-icon for iOS home screen
-  SHOULD include webmanifest for PWA-capable applications
-  SHOULD include theme-color meta tag

fixing-metadata 的检查逻辑不复杂，但它覆盖的是最容易在开发过程中被遗忘的细节。用莫潇羽自己的话说：这些检查项每一个都不难，难的是每次都记得做。有了 fixing-metadata，这就是一键搞定的事。

5.4 fixing-motion-performance：动画性能的"帧率警察"

fixing-motion-performance 是四个核心技能里技术含量最高的一个。它关注的是动画和过渡效果的渲染性能——简单说，就是确保你的动画不会让页面掉帧。

核心规则：只动合成器属性

这是 fixing-motion-performance 最重要的一条规则，也是前端动画性能优化的"第一原理"。

浏览器的渲染流水线大致分四步：样式计算 → 布局 → 绘制 → 合成。 不同的 CSS 属性触发不同的流水线阶段：

• 改 width/height/margin/padding：触发全部四个阶段（最贵）
• 改 color/background-color：触发布局后的三个阶段
• 改 transform/opacity：只触发合成阶段（最便宜）

fixing-motion-performance 强制执行：

-  MUST only animate `transform` and `opacity` for motion effects
-  NEVER animate `width`, `height`, `top`, `left`, `margin`, `padding`, 
  or `border-width`
-  SHOULD use `will-change` for elements that will animate, but remove it 
  after animation ends
-  SHOULD use `transform: translateZ(0)` or `will-change: transform` to 
  promote elements to their own compositor layer

下面用伪代码来演示一个典型的"违规→修复"过程：

##  违规代码
.card {
  transition: width 0.3s ease;
}
.card:hover {
  width: 320px; /* 触发完整渲染流水线 */
}

##  修复方案
.card {
  transition: transform 0.3s ease;
}
.card:hover {
  transform: scaleX(1.1); /* 只触发合成阶段 */
}

布局抖动检测

另一个重要的检查点是布局抖动（Layout Thrashing）。当 JavaScript 代码在同一个帧内交替进行读取布局属性和写入布局属性的操作时，浏览器会被迫反复重新计算布局，导致严重的性能问题。

-  NEVER read layout properties (offsetWidth, offsetHeight, getBoundingClientRect)
  immediately after writing layout properties in the same frame
-  SHOULD batch DOM reads and writes separately
-  SHOULD use requestAnimationFrame for visual updates

滚动关联动画

-  NEVER attach expensive operations (getBoundingClientRect, offsetTop reads) 
  to scroll event handlers without throttling
-  SHOULD use passive scroll listeners (`{ passive: true }`)
-  SHOULD consider using Intersection Observer for scroll-triggered animations
  instead of scroll event listeners

Intersection Observer 替代 scroll 事件监听是过去两年一个重要的性能优化趋势。scroll 事件每秒可能触发几十上百次，而 Intersection Observer 是浏览器原生优化的异步 API，性能开销小得多。

下面把五个技能模块做一个横向对比总结：

5.5 improve-ui：不只是查问题，还能给改进方案

improve-ui 是 ui-skills 的一个特殊技能——它的定位不是"找违规"，而是"提改进建议"。它的工作流程是：

1. 审计一个已有的产品界面
2. 对照该界面自身的设计系统，找出不一致的地方
3. 将发现的问题写成自包含的实施计划，交给另一个 AI Agent 执行

跟 baseline-ui 的区别在于：baseline-ui 是对照一套固定的标准做审查，improve-ui 是对照产品已有的设计系统做审查。比如你的设计系统规定按钮圆角是 6px，但某个页面上有个 8px 圆角的按钮——baseline-ui 不会管这个（因为 6px 和 8px 都在 Tailwind 标准值里），但 improve-ui 会标记为"设计系统漂移"。

这个技能特别适合在项目中期使用——产品已经迭代了一段时间，各种"例外情况"慢慢积累，设计系统开始走样。improve-ui 帮你把这些漂移一个个揪出来。

六、CLI 工具与安装上手：从零到跑通全流程

ui-skills 提供了多种安装和使用方式，从"一行命令零安装体验"到"深度集成到项目工作流"，覆盖了不同阶段的需求。这一节我们逐一讲清楚。

6.1 最快体验：npx 一行命令

如果你是第一次接触 ui-skills，推荐先用 npx 跑一下，不需要安装任何东西：

npx ui-skills start

敲下这行命令之后，系统会启动一个交互式界面，大致长这样（模拟输出）：

? What would you like to do?
❯ Build a new component
  Review existing code
  Fix a specific issue
  Improve UI quality

? What's your tech stack?
❯ React + Tailwind CSS
  Next.js + Tailwind CSS
  Vue + Tailwind CSS
  Other

选择任务类型和技术栈后，ui-skills 会自动加载对应的技能集。整个过程的耗时基本上就是下载 npm 包的几秒钟（首次运行），之后就是即时响应。

其他常用的 npx 命令一览：

# 查看所有可用命令
npx ui-skills

# 查看技能分类
npx ui-skills categories

# 列出特定分类下的技能
npx ui-skills list --category motion

# 获取单个技能的完整上下文（规则+示例+说明）
npx ui-skills get baseline-ui

npx ui-skills get baseline-ui 这个命令很实用——它直接把 baseline-ui 的全部规则输出到终端，你可以复制粘贴到 AI 工具的对话里，也可以在 Code Review 时当 checklist 用。

6.2 安装到项目中：团队协作的首选

如果你想把 ui-skills 作为团队的长期工具，推荐安装到项目里：

npx ui-skills init

执行后，ui-skills 会在项目根目录下创建 .skills/ 文件夹，把技能文件下载到本地。同时会在支持的工具中注册命令，比如在 Claude Code 中注册 /baseline-ui、/fixing-accessibility 等命令。

安装后的目录结构大致是这样：

your-project/
├── .skills/
│   ├── baseline-ui/
│   │   └── SKILL.md
│   ├── fixing-accessibility/
│   │   └── SKILL.md
│   ├── fixing-metadata/
│   │   └── SKILL.md
│   ├── fixing-motion-performance/
│   │   └── SKILL.md
│   ├── improve-ui/
│   │   └── SKILL.md
│   └── ui-skills-root/
│       └── SKILL.md
├── src/
├── package.json
└── ...

安装到项目的最大好处是版本锁定——团队所有人都用同一套规则，不会出现"我的 ui-skills 跟你的规则不一样"的情况。而且 .skills/ 文件夹可以纳入 Git 版本管理，规则的变更可以走 PR + Code Review 流程。

6.3 单独安装某个技能

如果你只需要某个特定技能（比如只要 baseline-ui，其他暂时用不上），可以单独安装：

npx skills add https://github.com/ibelick/ui-skills --skill baseline-ui

执行后只有 baseline-ui 的 SKILL.md 会下载到本地。这种"按需安装"的方式特别适合"我先试试某一个，好用再加别的"的渐进式探索。

6.4 手动下载：最灵活的方式

如果你不想走 CLI，也可以手动下载单个 SKILL.md 文件：

curl -o SKILL.md https://github.com/ibelick/ui-skills/raw/main/skills/baseline-ui/SKILL.md

然后把这个文件放到你的 AI 工具的 skills 文件夹里。不同工具的 skills 文件夹位置不太一样，但思路都一样——只要 AI 工具能找到这个文件，它就能加载。

6.5 各 AI 工具平台的安装差异

不同 AI 编码工具的安装方式有细微差别，下面列一个对照表：

6.6 一个完整的实操流程演示

假设你现在有一个 React + Tailwind CSS + shadcn/ui 构建的 Dashboard 页面，你想用 ui-skills 做一次全面审查。完整流程如下：

步骤一：启动技能路由

npx ui-skills start

在交互界面中选择"Review existing code" → 选择文件 → 选择审查维度（这里选"综合审查"）。

步骤二：AI 加载对应技能后，运行审查指令

在 AI 工具中（以 Claude Code 为例）：

请用 baseline-ui 和 fixing-accessibility 技能审查 src/components/Dashboard.tsx，
输出违规片段、影响说明与具体修复方案。

步骤三：AI 输出结构化的审查报告

AI 会逐项列出代码中不符合规范的地方，按严重程度分类，并给出修复建议。

步骤四：根据报告逐项修复

开发者可以按 Priority 从高到低依次修复。

整个过程不需要开发者手动一条条去对照规范文档——AI 加 ui-skills 帮你全做了。你只需要做出"要不要修"的决策和"怎么修更符合业务逻辑"的判断。

七、在主流 AI 工具中集成 ui-skills：Claude Code / Cursor / Copilot 全覆盖

上一节提到了各工具的安装差异，这一节我们深入讲讲在每种工具中 ui-skills 的具体使用方式和最佳实践。

7.1 Claude Code 中的集成

Claude Code 是 Anthropic 官方的终端 AI 编码工具，也是 Skills 生态的"原住民"。在 Claude Code 中集成 ui-skills 最简单：

安装：

/skill add ibelick/ui-skills

使用——在对话中直接调用命令：

/baseline-ui

然后告诉 Claude 你要干什么：

/baseline-ui 审查 src/components/UserProfile.tsx

Claude Code 会自动加载 baseline-ui 的完整规则，逐行检查 UserProfile.tsx 是否合规。输出格式也是标准化的：

## UI Skills 审查结果

###  Critical Violations
`UserProfile.tsx:42` - 使用了 `h-screen` → 应替换为 `h-dvh`
  影响：移动端浏览器地址栏会导致布局跳动
  修复：将 `className="h-screen"` 改为 `className="h-dvh"`

###  Warnings
`UserProfile.tsx:78` - 自定义圆角值 `rounded-[9px]` → 建议使用 `rounded-lg`(8px) 或 `rounded-xl`(12px)
  影响：与设计系统的圆角体系不一致
  修复：选择最接近的标准值

###  Summary
Critical: 1件 / Warning: 1件

7.2 Cursor 中的集成

Cursor 的 Skills 支持方式跟 Claude Code 略有不同。在 Cursor 中，你可以把 SKILL.md 的内容放到 .cursorrules 文件中，或者直接在项目根目录创建 .skills/ 文件夹。

Cursor 会读取这些规则文件，在 Agent 模式下自动应用。如果你想让 Cursor 在每次生成代码时都遵循 baseline-ui 的规范，就把 baseline-ui 的 SKILL.md 内容