ui-review

UI 设计审查

适用场景

当你需要审查 UI 代码是否符合设计系统规范、无障碍要求和最佳实践时，使用此技能。

不适用场景

• 仅处理无障碍问题 → 使用 /ss-a11y
• 检查 Nielsen UX 启发式原则 → 使用 /ss-audit
• 快速自动检查 → 使用 /ss-lint
• 非 UI 代码（数据获取、业务规则）

审查文件：$ARGUMENTS

此检查清单针对上游 StyleSeed 约定。请先确认项目实际使用的设计系统；字体、间距、圆角规则以及引用的 CLAUDE.md/VISUAL-CRAFT.md 都是项目约定，并非通用的无障碍要求，而且此处未附带这些文件。若相关上下文不可用，请标记出来，不要将这些约定强加给其他项目。

检查清单

1. 设计令牌合规性

• 不使用硬编码的十六进制颜色（使用语义令牌：text-foreground、bg-brand 等）
• Tailwind 间距不使用硬编码的 px 值（使用 p-6，而不是 p-[24px]）
• 阴影使用 CSS 变量（shadow-[var(--shadow-card)]）
• 边框圆角遵循规格（rounded-md、rounded-lg、rounded-2xl）

2. 组件约定

• 使用 data-slot 属性
• 使用 cn() 合并 className
• Props 使用 React.ComponentProps<> 进行类型声明
• 支持通过 className prop 覆盖样式
• 使用命名导出（组件不使用默认导出）
• 不使用仅用于添加 className 的包装组件

3. 无障碍（a11y）

• 优先将 44x44 CSS 像素作为指针目标尺寸的设计目标；WCAG 2.2 AA SC 2.5.8 要求尺寸为 24x24 或符合适用例外，因此较小的控件并不会自动构成 AA 违规（W3C）
• 所有交互元素都设有 focus-visible 样式
• 在需要时使用恰当的 aria-* 属性
• 颜色对比度符合 WCAG AA（正文文本为 4.5:1，大号文本为 3:1）
• 动画遵循 prefers-reduced-motion 设置
• 图片包含 alt 文本
• 表单输入框具有关联标签

4. 移动端最佳实践

• 不出现水平溢出
• 交互元素之间留有适合触控的间距
• 为带刘海的设备处理安全区域插入值
• 文本字号 >= 12px，以确保可读性
• 可滚动容器设置了 -webkit-overflow-scrolling: touch

5. 性能

• 避免不必要的重新渲染（使用稳定引用，并在需要时进行记忆化）
• 对屏幕外图片进行延迟加载（在有益时）；不要自动延迟加载首屏关键图片或 LCP 图片
• 对大型组件进行代码拆分

6. 排版

• 使用 Pretendard/Inter 字体栈
• 字号取自 14 级字号规格（10-48px，参见 CLAUDE.md）
• 使用恰当的字重（400、500、600、700）
• 展示文本（36-48px）：leading-none + tracking-[-0.02em]
• 标题文本（18-24px）：leading-snug + tracking-[-0.01em]
• 正文文本（14-17px）：leading-normal（不使用自定义字距）
• 大写说明文字（10-13px）：tracking-[0.05em] 或 tracking-wide
• 展示文本或标题文本不设置 line-height: 1.5（过于宽松）

7. 间距一致性

• 所有间距值都是 6px 的倍数（p-1.5、p-3、p-6 等）
• 不使用任意间距（p-5=20px、gap-3.5=14px 均不符合规范）
• 使用 size-* 简写，而不是 w-* h-*
• 使用 ms-*/me-*，而不是 ml-*/mr-*（逻辑属性）
• 动效过渡使用设计令牌（duration-[var(--duration-fast)]）

8. 一致性（VISUAL-CRAFT.md §C0 ——“每个轴一个选择”法则）

UI 看起来像“AI 生成”的最大原因不是丑的部分——而是混杂的 部分。检查下面每个轴在全系统内是否只使用一个值；把混用标记为真正 的问题，而不是吹毛求疵。

• 一种圆角个性——锐利（0-4px）或柔和（8-12px）或胶囊形，应用于每个卡片/按钮/输入框/模态框。不要混用（例如一个 rounded-none 面板配 rounded-full 按钮）。
• 一种强调色用于交互强调（+ 仅语义红/绿/琥珀）——不是两个或更多相互竞争的强调色。
• 不用 emoji 作为 UI 图标（🚗🧺⭐ 作为列表/导航/状态/分类标记）——它们会注入许多不受控的色相；使用一套 currentColor 的线性图标。
• 状态颜色 = 严重程度，而非装饰——正常/OK/“보통”状态是中性灰色（非彩色）；颜色只标记少数需要关注的行的状态；相同值 → 相同颜色。
• 无装饰性色相——收藏星标、分类圆点、头像使用强调色或灰色，而不是每个都用一种新颜色。
• 一种阴影语言——相同光照方向，相同尺度/色调；不要一些黑色 + 一些带色调，一些上照 + 一些下照。
• 整个文件一种图标族 / 填充模式 / 描边粗细。
• 嵌套圆角法则——圆角容器内的元素使用 inner = outer − padding，而不是相同圆角（会外凸）。
• 一致的控制高度——按钮、输入框、选择框共享一组高度（例如 40px）。
• 错误/状态绝不能仅依赖颜色（也要图标 + 文本）。

输出格式

提供：

1. 评分：通过 / 需要改进 / 不通过
2. 问题：列出每个违规项及 file:line 引用
3. 修复：为每个问题给出具体的代码更改

示例

用户请求：

审查 UI 代码的设计系统合规性、可访问性和最佳实践。

限制

• 仅当任务明确匹配其上游来源和本地项目上下文时，才使用此技能。
• 在应用更改之前，验证命令、生成的代码、依赖项、凭据和外部服务行为。
• 不要将示例视为针对特定环境的测试、安全审查或对破坏性或高成本操作的用户批准的替代品。