audit-uiux-design-system

UI 设计系统审计技能

自由度：混合 — 步骤 0–3、5–6 [HIGH freedom]；步骤 4 Playwright 截图 [LOW freedom — run exactly]。执行任何浏览器步骤前，请先阅读 protocol-browser-anti-stall。仅审计断点 → audit-responsive。

推理方法

1. 观察 — 引用令牌文件、原始十六进制值或截图
2. 解读 — 这是系统令牌、一次性样式，还是 AI 痕迹？
3. 分类 — 令牌泄漏 / 重复组件 / 缺失状态 / 模板化 / 正确
4. 严重性 — 核心原语使用原始颜色 = P0；缺少悬停状态 = P1；圆角小问题 = P2

示例

观察： Button.tsx 使用 bg-[#3B82F6]；--primary 已在 globals.css 中定义。 解读： 该原语绕过了令牌 SSOT；深色模式无法切换此颜色。 分类： 核心原语的令牌泄漏。 严重性： P0 — 每个按钮都使用硬编码的十六进制值。 发现： Button.tsx | 颜色令牌 | P0 | 替换为 bg-primary。

报告前自我审查 [LOW freedom — do not skip]

1. 先看令牌 — 不要另造一套比例
2. 提供证据 — .playwright-mcp/ 下的截图或引用的类名
3. 严重性有依据 — P0 = 核心原语脱离令牌体系或对比度不可用
4. 交给正确负责人 — 桌面布局线性化 → audit-responsive；WCAG 键盘操作 → audit-accessibility
5. 精心设计 — 不要提出会让模板更加千篇一律的建议

避免模板化

建议必须明确指出要避免什么，而不是让人凭审美判断。在该领域研究获奖网站；调整节奏（不要全部使用相同的 py-16）；为每个控件定义独特的悬停 / 焦点 / 激活 / 禁用状态；定义个性化令牌（圆角、字体风格）。需要指出的默认做法 — 根据初稿采用的做法扩展此列表：每个区块的内边距都相同、通用或紫色渐变、默认采用三张等宽卡片 / 三列图标-标题-描述布局、奶油色或灰白色页面背景、标题中的斜体强调词、"01/02/03" 编号区块标签、等宽字体标签、所有按钮都采用药丸形、只使用 Inter/Roboto 作为字体风格、Lorem 空状态、统一的圆角、未经适配的图库素材。

---

步骤 0：自动检测设计系统

0a. 检测 CSS 框架

信号	技术
tailwindcss v3 + tailwind.config.*	Tailwind CSS v3
tailwindcss v4 + CSS 中的 @theme	Tailwind CSS v4
*.module.css 文件	CSS Modules
styled-components 或 @emotion/styled	CSS-in-JS
@chakra-ui/react	Chakra UI
@mui/material	Material UI
@mantine/core	Mantine

0b. 检测组件库

Glob: **/components/ui/*.tsx → shadcn/ui
Glob: **/components/ui/*.vue → Vue component lib
Glob: **/components/ui/*.svelte → Svelte component lib
Grep: "from '@radix-ui" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'lucide-react" glob "*.{ts,tsx}" output_mode "count"
Grep: "from '@heroicons" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'react-icons" glob "*.{ts,tsx}" output_mode "count"

0c. 查找设计令牌

Glob: **/tailwind.config.*
Glob: **/app/globals.css
Glob: **/styles/tokens.*
Glob: **/theme.*
Grep: "--primary|--secondary|--accent|--muted" glob "*.css"

阅读令牌来源，提取：颜色、间距、字体排版、圆角、阴影。

0d. 发现禁用模式

Grep: "NEVER|FORBIDDEN|DO NOT" glob "**/*README*" -i

0e. 记录发现

DESIGN SYSTEM DISCOVERY:
- CSS framework: [Tailwind v3/v4 / CSS Modules / Styled Components / etc.]
- Component library: [shadcn/ui / Radix / MUI / Chakra / custom]
- Icon library: [Lucide / Heroicons / react-icons / mixed]
- Token source: [file path]
- Colors defined: [count]
- Typography scale: [list]
- Spacing base: [4px / 8px / etc.]
- Border radius: [list]
- Shadow levels: [list]
- Dark mode: [YES — class/media / NO]
- Forbidden patterns: [list from README]

---

步骤 1：研究设计系统最佳实践

1a. Context7 — 组件库文档

context7:resolve-library-id
{
 "libraryName": "<DETECTED_COMPONENT_LIBRARY>",
 "query": "component variants accessibility patterns"
}

然后使用解析出的 ID 获取文档。也要获取 CSS 框架文档。

1b. Firecrawl — 设计系统标准

firecrawl:firecrawl_search
{
 "query": "<COMPONENT_LIBRARY> design system audit token compliance best practices [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

其他查询：

主题	查询
令牌合规性	design token audit <CSS_FRAMEWORK> consistency
组件模式	<FRAMEWORK> component modularity composition patterns
深色模式	<CSS_FRAMEWORK> dark mode implementation best practices

1c. Firecrawl — 获奖参考网站

firecrawl:firecrawl_search
{
 "query": "<PRODUCT_TYPE> website design award Awwwards Muzli [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

firecrawl:firecrawl_search
{
 "query": "<PRODUCT_TYPE> SaaS UI design inspiration unique not generic [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

抓取 2–3 个出色网站，考察网格变化、标志性动效、字体风格和强调色逻辑。

---

步骤 2：令牌合规性审计

2a. 颜色令牌

规则	标准	检查方法
语义化命名	primary、secondary、destructive、muted、accent	组件中没有原始 hex/rgb 值
CSS 变量	hsl(var(--primary)) 或 oklch()	所有颜色都引用变量
前景色配对	每种背景色都有对应的 *-foreground	保持文本对比度
深色模式	所有令牌都有深色变体	.dark 类或 @media
状态颜色	定义 success、warning、error、info	在提醒、徽章和 Toast 中保持一致

查找违规项：

Grep: "(#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\([^v])" glob "*.tsx"
Grep: "\[(#|rgb|hsl)" glob "*.tsx"

2b. 排版令牌

规则	标准
字体系列	主题中最多使用 2-3 种字体系列
字号比例	保持一致（text-sm、text-base、text-lg）
字重比例	使用有限的字重（font-normal、font-medium、font-semibold、font-bold）
标题层级	h1 > h2 > h3 的视觉权重和 DOM 顺序均依次递减
不使用任意字号	已有 text-sm 时，不使用 text-[14px]

Grep: "text-\[" glob "*.tsx"
Grep: "font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)" glob "*.tsx" output_mode "count"

2c. 间距令牌

规则	标准
基本单位	4px 网格（Tailwind 默认值）
间距一致	相同场景使用相同间距
不使用任意值	已有 p-3 时，不使用 p-[13px]

Grep: "(p|m|gap|space)-\[" glob "*.tsx"

2d. 边框、圆角、阴影

Grep: "rounded-\[" glob "*.tsx"
Grep: "shadow-" glob "*.tsx" output_mode "count"

---

第 3 步：组件模块化审计

3a. 组件健康度

规则	标准
单一职责	一个组件 = 一个用途
可组合	小组件可组合成更大的组件
可复用	相同 UI = 各处使用相同组件
属性一致	所有组件都统一使用 variant、size、disabled、className
变体模式	使用 cva() 或类似方法定义样式变体

3b. 查找重复组件

Grep: "<button " glob "*.tsx" — raw buttons outside ui/ (should use Button)
Grep: "<input " glob "*.tsx" — raw inputs (should use Input)
Grep: "<select " glob "*.tsx" — raw selects
Grep: "<a " glob "*.tsx" — raw anchors (should use Link)

排除 components/ui/*——这些是合理的基础组件。

3c. 检查组件一致性

Grep: "function (Button|Input|Modal|Dialog|Card)" glob "*.tsx" output_mode "files_with_matches"

3d. 混用图标库

Grep: "from .lucide-react" glob "*.tsx" output_mode "count"
Grep: "from .@heroicons" glob "*.tsx" output_mode "count"
Grep: "from .react-icons" glob "*.tsx" output_mode "count"

---

第 4 步：实时视觉验证（playwright-cli）

4a. 导航并截图

PW="npx --yes @playwright/cli@latest"
$PW -s=ds-audit open --headed "http://localhost:<PORT>/<ROUTE>"
sleep 2
$PW -s=ds-audit snapshot                                              # verify content rendered
$PW -s=ds-audit screenshot --filename ".playwright-mcp/ds-<route>.png"  # visual evidence
$PW -s=ds-audit console                                               # check for errors

4b. 逐页检查

检查项	方法
令牌合规性	截图——检查颜色、间距是否不一致
组件复用	快照——是否使用了共享的基础组件？
控制台错误	console——水合错误、缺少 CSS 变量
布局偏移	交互前后分别拍摄快照
深色模式	切换深色模式，重新截图并比较

4c. 响应式检查

在三个视口下测试：

• 桌面端（1440px）
• 平板端（768px）
• 移动端（375px）

4d. 视觉无障碍

检查项	方法
颜色对比度	文本为 4.5:1，大号文本/UI 为 3:1——根据令牌配对值计算（使用单行脚本或 DevTools 无障碍面板）；截图可确认正在使用哪组配对，但无法测量对比度
焦点环	使用 Tab 键逐个浏览元素，确认焦点指示器清晰可见
语义化 HTML	`Grep: "
替代文本	运行 `Grep: "<(img

---

第 5 步：微交互与用户反馈

5a. 微交互覆盖审计

检查每个交互元素：

元素	预期反馈	缺失时的 AI 痕迹
按钮	悬停：颜色变化并微妙调整阴影。激活：按下时缩放至 scale(0.98)。加载中：微调器替换标签，或显示行内指示器	扁平，没有状态变化——感觉毫无响应
链接	悬停：下划线动画或颜色过渡，而非瞬间切换	颜色瞬间跳变，没有过渡
卡片（可点击）	悬停：上浮（translateY + 阴影增强）。不只是颜色变化	只有颜色变化，或完全没有悬停效果
输入框	聚焦：环形动画或边框颜色过渡。不只是轮廓切换	浏览器默认轮廓，没有自定义聚焦样式
切换按钮/开关	状态切换有动画，而非瞬间变化。通过缓动营造触觉感	状态瞬间跳变
下拉菜单/菜单	打开/关闭时有滑动或淡入淡出效果，而非瞬间出现/消失	瞬间弹出，没有过渡
Toast/通知	进入时滑动并淡入，退出时淡出。自动关闭时显示进度	瞬间出现/消失
模态框/对话框	背景淡入 + 内容缩放/滑动。退出时反向播放。不是瞬间出现	瞬间出现，令人突兀
标签页	活动指示器滑向新标签页，而非瞬间跳转	颜色瞬间切换
工具提示	稍作延迟（200-300ms）后淡入。鼠标移动时不要闪烁	瞬间出现、闪烁、没有延迟

在代码中查找：

Grep: "transition-all|transition-colors|transition-opacity|transition-transform" glob "*.tsx" output_mode "count"
Grep: "hover:|group-hover:|focus-visible:" glob "*.tsx" output_mode "count"
Grep: "animate-|animation-|@keyframes|framer-motion|motion\." glob "*.tsx" output_mode "count"
Grep: "scale-|translate-|rotate-" glob "*.tsx" output_mode "count"

5b. 交互状态完整性

确认每个交互元素都具备所有状态：

States checklist per component:
□ Default (resting)
□ Hover (mouse over)
□ Focus-visible (keyboard navigation)
□ Active/pressed (during click)
□ Disabled (grayed, not clickable, cursor-not-allowed)
□ Loading (async action in progress)
□ Error (validation failed, destructive context)
□ Success (completed action)

查找缺失的状态：

Grep: "focus-visible:|focus:" glob "*.tsx" output_mode "count"
Grep: "active:|pressed" glob "*.tsx" output_mode "count"
Grep: "disabled:|cursor-not-allowed|opacity-50" glob "*.tsx" output_mode "count"

5c. 视觉节奏与个性审计

有意的多样性与千篇一律的重复：

模式	精心设计的感觉	模板化的感觉
区块间距	根据内容类型变化（主视觉区：宽裕；表单：紧凑；CTA：宽敞）	每个区块都使用相同的 py-16
字体对比	标题与正文之间有较大差异（例如，48px → 16px）。混合使用不同字重	递增缩放，到处使用相同字重
强调色使用	谨慎使用强调色来突出重点，而不是应用于每个元素	每个按钮、链接、图标都使用主色
布局变化	每个区块采用不同布局（左侧文字/右侧图片、全宽、侧边栏）	重复使用相同的三列卡片网格
圆角	有意采用不同样式（标签使用胶囊形、卡片使用圆角、数据表使用直角）	所有元素都使用相同的 rounded-lg
阴影深度	使用多个阴影层级构建空间层次	所有元素都使用相同阴影，或完全没有阴影
留白	不对称边距营造视觉流动感和阅读节奏	完全对称、机械式的间距

---

第 6 步：动画和深色模式

动画

规则	标准
持续时间尺度	150ms（微交互）、200ms（悬停）、300ms（进入）、500ms（复杂动画）——不要全部相同
缓动	进入时使用 ease-out，退出时使用 ease-in，状态变化时使用 ease-in-out——不要全部使用 ease-in-out
减少动态效果	使用 motion-safe: 前缀或 prefers-reduced-motion
不造成布局偏移	过渡不会导致 CLS
交错效果	列表项、卡片网格以交错延迟动画进入，而不是同时出现

Grep: "duration-[0-9]+" glob "*.tsx" output_mode "count"
Grep: "transition-" glob "*.tsx" output_mode "count"
Grep: "prefers-reduced-motion|motion-safe|motion-reduce" glob "*.tsx"
Grep: "stagger|delay-\[|animation-delay" glob "*.tsx" output_mode "count"

深色模式

规则	标准
所有令牌都切换	CSS 变量在深色模式下改变
不使用硬编码颜色	不要使用 bg-white、text-black——使用语义令牌
边框清晰可见	两种模式下都清晰可见
对比度	浅色和深色模式都符合 WCAG 标准
不是事后补充	深色模式应经过专门设计，而不是简单反转。阴影变为辉光，边框变得微妙

Grep: "(bg-white|bg-black|text-white|text-black)" glob "*.tsx" output_mode "count"

---

输出模板

## UI Design System Audit Report

**Date:** [date]
**Framework:** [detected]
**CSS:** [Tailwind v3/v4 / CSS Modules / etc.]
**Component library:** [shadcn / Radix / MUI / custom]
**Pages Audited:** [count]
**Issues Found:** [count]

---

### Design Token Compliance

| Token Category | Defined | Violations | Status |
|----------------|---------|------------|--------|
| Colors | [count] | [count] raw hex/rgb | [pass/warn/fail] |
| Typography | [count] | [count] arbitrary sizes | [pass/warn/fail] |
| Spacing | [count] | [count] arbitrary values | [pass/warn/fail] |
| Radii | [count] | [count] arbitrary radii | [pass/warn/fail] |
| Shadows | [count] | [count] inconsistent | [pass/warn/fail] |

---

### Component Health

| Component | Used In | Variants | Issues |
|-----------|---------|----------|--------|
| Button | [N] files | [N] | [notes] |
| Input | [N] files | [N] | [notes] |
| Card | [N] files | [N] | [notes] |

---

### Duplicate / Redundant Components

| Pattern | Locations | Recommendation |
|---------|-----------|----------------|
| Raw `<button>` | [files] | Use `<Button>` from `components/ui` |
| Custom modal | [file] | Use `<Dialog>` from `components/ui` |

---

### Visual Accessibility

| Criteria | Status | Issues |
|----------|--------|--------|
| Color contrast | [pass/warn/fail] | [details] |
| Focus indicators | [pass/warn/fail] | [details] |
| Alt text | [pass/warn/fail] | [details] |
| Semantic HTML | [pass/warn/fail] | [details] |

---

延伸阅读

• 微交互覆盖及更多内容