design

设计技能

版本： 1.0 来源： 设计标准

不容妥协的设计与用户界面标准。这些不是偏好，而是要求。

问题

AI Agent 生成的 UI 看起来似乎合理，却前后不一致。每次会话都会选择略有不同的间距、标题级别、元素类型和状态处理方式，导致相似组件给人的感觉不统一：这里的卡片使用 <h3>，那里却使用 <h4>；一个地方的按钮有悬停状态，另一个地方却没有。这些标准确保每个 UI 元素都遵循相同的设计语言，无论由哪次会话构建。

使用方式

• 构建者： 编写任何 HTML、CSS 或 JSX 之前，请阅读 ## Builder Checklist。设计令牌的使用和语义化 HTML 是约束，而非建议。
• 重构者： 使用 ## Enforced Rules 查找设计违规。阅读说明性章节，了解正确的元素选择和令牌用法。
• 两者： 说明性章节是权威标准。清单和规则表是对相同内容的精简呈现。

---

范围与边界

此技能涵盖：

• 设计系统理念与原则
• 设计令牌的使用与执行
• 语义化 HTML 模式（元素选择）
• CSS 格式与质量规则
• 组件状态（悬停、焦点、激活、禁用）
• 布局理念（Grid 与 Flexbox 的选择）
• 响应式设计原则与断点
• 高端 UI 理念与反模式

由其他技能负责：

• web-accessibility：深入的 WCAG 合规性、屏幕阅读器模式、ARIA 用法、键盘导航
• web-css：CSS 架构、文件组织、命名约定（BEM）、深色模式实现

在以下情况下使用此技能： 需要设计原则、令牌执行或语义化 HTML 指导时。 在以下情况下使用 web-accessibility： 需要 WCAG 合规性、屏幕阅读器支持或焦点管理时。 在以下情况下使用 web-css： 需要 CSS 组织、变量架构或响应式实现细节时。

---

核心原则

1. 用户优先 — 优先考虑用户需求、工作流和易用性
2. 精益求精 — 每个 UI 元素都要精准、精致
3. 速度与性能 — 加载迅速、交互灵敏
4. 简洁明了 — 界面清爽，标签含义明确
5. 专注高效 — 帮助用户快速达成目标
6. 一致性 — 全程采用统一的设计语言
7. 无障碍访问（WCAG AA） — 面向所有用户的包容性设计
8. 明确的默认设置 — 周到的默认设置可减少决策疲劳

---

设计系统（唯一事实来源）

关键规则

1. 始终使用设计令牌 — 绝不使用硬编码值
2. 所有值均来自 styles/global.css — CSS 变量的唯一事实来源
3. 不使用魔法数字 — 每种颜色、间距和尺寸都使用 CSS 变量

示例

/* ✅ Correct - Uses design tokens */
.button {
  padding: var(--space-sm) var(--space-md);
  font-size: var(--font-size-body);
  background: var(--color-primary);
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow-sm);
}

/* ❌ Wrong - Hardcoded values */
.button {
  padding: 8px 16px;           /* Use var(--space-sm) var(--space-md) */
  font-size: 14px;             /* Use var(--font-size-body) */
  background: #3B82F6;         /* Use var(--color-primary) */
  border-radius: 4px;          /* Use var(--radius-sm) */
}

设计系统包含的内容

• 完整的调色板（中性色、语义色、深色模式）
• 完整的字体排版比例（字体、字号、字重、行高）
• 间距系统（以 4px 为基准）
• 边框圆角
• 阴影
• Z-index 层级
• 动画时长与缓动函数
• 图标尺寸
• 断点值

---

语义化 HTML

必须遵循的做法

1. 使用语义化标签：<header>、<nav>、<main>、<article>、<section>、<footer>
2. 操作用按钮（<button>），导航用链接（<a>）
3. 表单使用 <form>、<label>、<input>、<select>、<textarea>
4. 列表使用 <ul>、<ol>、<li>（不要用带项目符号的 div）
5. 标题遵循层级顺序：<h1> → <h2> → <h3>（不可跳级）
6. 图片应有描述性 alt 文本
7. 表格数据使用恰当的表格标记

示例

<article class="product-card">
  <header>
    <h2>Product Name</h2>
  </header>
  <img src="..." alt="Product description">
  <p>Product description goes here.</p>
  <footer>
    <button type="button">Add to Cart</button>
  </footer>
</article>


<div class="prd-crd">
  <div class="hdr">
    <div class="ttl">Product Name</div>
  </div>
  <div class="img"></div>
  <div class="btn">Add to Cart</div>
</div>

---

HTML 简洁性

标题用于构建结构

标题（<h1>-<h6>）用于定义文档结构，而非视觉样式。

<h3>Sale Price</h3>  


<p class="price-label">Sale Price</p>

避免类名臃肿

元素应使用 1-3 个类名。超过 4 个就需要警惕——应合并为一个语义化类名。

<button class="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus:ring-2">
  Submit
</button>


<button class="btn btn--primary">
  Submit
</button>

不使用内联样式

HTML 描述结构，CSS 负责呈现。将两者分开。

// ❌ Bad - Inline styles
<div style={{ marginTop: '16px', padding: '8px' }}>

// ✅ Good - CSS class
<div className="card-section">

唯一例外： 运行时计算出的真正动态值。即便如此，也优先使用 CSS 自定义属性。

---

CSS 质量

格式规则

1. 每行一个属性
2. 使用设计令牌（CSS 变量），不要使用硬编码值
3. 按逻辑顺序排列属性：定位 → 盒模型 → 排版 → 视觉 → 动画
4. 使用描述性类名（BEM 或语义化命名）
5. 规则集之间留出充足间距
6. 为复杂部分添加注释

示例

/* ✅ Good - Human-readable */
.product-card {
  display: flex;
  flex-direction: column;
  gap: var(--space-md);
  padding: var(--space-lg);
  background-color: var(--color-neutral-50);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
}

.product-card:hover {
  box-shadow: var(--shadow-md);
  transform: translateY(-2px);
  transition: all var(--duration-fast) var(--easing-standard);
}

---

组件状态（必需）

所有交互式组件都必须具备以下五种状态：

状态	要求	示例
默认	基础外观	普通按钮
悬停	鼠标悬停时提供视觉反馈	背景颜色变深
激活	按下时提供视觉反馈	轻微缩小
焦点	清晰的焦点指示器（键盘导航）	outline: 2px solid var(--color-focus); outline-offset: 2px;
禁用	视觉上有明显区别且不可交互	灰显、低不透明度

---

布局理念

CSS Grid 与 Flexbox

布局需求	工具	示例
页面结构	Grid（命名区域）	页眉、侧边栏、主体、页脚
分区布局	Grid（命名区域）	双列内容、表单布局
组件结构	Grid（命名区域）	卡片内部布局、模态框布局
导航项	Flexbox	顶部导航项、菜单项
图库／流动项目	Flexbox	图片网格、卡片图库、标签列表

结构布局默认使用 Grid。 需要项目流动、分布或换行时使用 Flexbox。

使用命名区域的 Grid（主要布局方法）

#app-layout {
  display: grid;
  grid-template-columns: 200px 1fr;
  grid-template-areas:
    "header header"
    "sidebar main"
    "footer footer";
  gap: var(--space-md);
}

#header { grid-area: header; }
#sidebar { grid-area: sidebar; }
#main { grid-area: main; }
#footer { grid-area: footer; }

留白

• 使用充足的负空间来提升清晰度
• 使用设计令牌保持间距一致

---

无障碍性（WCAG AA）

必需标准

1. 颜色对比度

   • 普通文本：至少 4.5:1
   • 大号文本（18px 及以上）：至少 3:1

2. 键盘导航

   • 所有功能都可通过键盘使用
   • Tab 顺序合理
   • 焦点指示器清晰可见

3. 屏幕阅读器支持

   • 使用恰当的 ARIA 标签
   • 使用语义化 HTML
   • 为导航提供跳过链接

4. 表单标签

   • 所有输入项都有关联标签
   • 错误消息与输入项关联

尊重用户偏好

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

---

响应式设计

移动优先断点

/* Mobile: 0-767px (base styles, no media query needed) */

/* Tablet: 768px and up */
@media (min-width: 768px) { }

/* Desktop: 1024px and up */
@media (min-width: 1024px) { }

/* Large Desktop: 1280px and up */
@media (min-width: 1280px) { }

绝不使用： @media (max-width: ...)——始终使用 min-width（移动优先）

容器最大宽度

• 移动端：100%（带内边距）
• 平板端：768px
• 桌面端：1024px
• 大屏：1280px

---

高端 UI 理念

我们遵循 S 级 SaaS 标准（Stripe、Airbnb、Linear）：

• 精致的排版与恰到好处的间距
• 高级感配色方案与微妙渐变
• 有目的的动画（150–300ms）
• 令人愉悦的微交互
• 对细节一丝不苟

目标： 让每个界面都显得高级。注重微妙精致，而非浮夸效果。

---

反面模式（切勿这样做）

反面模式	问题	改进方式
浮动标签	令人困惑	将标签放在输入项上方
内联验证	令人厌烦	在失焦或提交时验证
通用错误消息	缺乏帮助	提供具体且可执行的错误信息
将关键信息放在工具提示中	容易被忽略	直接显示
禁用按钮却不作解释	令人沮丧	说明禁用原因
自定义滚动条	用户体验不一致	使用系统滚动条
在桌面端使用汉堡菜单	隐藏导航	在桌面端显示完整导航

---

构建者检查清单

在编写受此技能约束的 UI 代码之前，请根据这些限制核对你的计划。构建者在编写代码前阅读本节；重构者则使用“强制规则”表和完整说明。

设计系统

• 所有值都使用设计令牌
• 不使用魔法数字或硬编码颜色
• 设计系统是唯一事实来源

语义化 HTML

• 适当使用语义化标签
• 操作使用按钮，导航使用链接
• 遵循标题层级
• 为所有图片添加替代文本

CSS

• 格式易于阅读
• 全面使用设计令牌
• 属性顺序合理

组件状态

• 已实现默认状态
• 已实现悬停状态
• 已实现激活状态
• 已实现焦点状态
• 已实现禁用状态

无障碍

• 颜色对比度符合 WCAG AA 标准
• 键盘导航可正常使用
• 已通过屏幕阅读器测试
• 焦点指示器清晰可见
• 表单标签齐全

响应式

• 采用移动优先的方法
• 使用标准断点
• 适用于所有屏幕尺寸

避免反模式

• 不使用浮动标签
• 不使用内联验证
• 不使用通用错误提示
• 关键内容不使用工具提示
• 禁用的按钮均有说明
• 不使用自定义滚动条
• 桌面端不显示汉堡菜单

---

强制规则

这些规则由 check.js（clean-team）以确定性方式检查。更新这些标准时，请同步更新对应的 check.js 规则，反之亦然。

规则 ID	严重级别	检查内容
no-inline-style	错误	HTML 中的 style="..." 属性
no-jsx-inline-style	警告	JSX 中的 style={{...}}
button-type-required	错误	不带 type 属性的 <button>
doctype-required	错误	缺少 <!DOCTYPE html>
max-classes	警告	元素上的类超过 4 个

---

参考资料

• references/semantic-html.md — 完整的语义化 HTML 指南
• references/css-formatting.md — CSS 最佳实践
• references/accessibility-guide.md — WCAG AA 合规指南
• references/responsive-breakpoints.md — 响应式设计模式

资源文件

• assets/component-states-checklist.md — 状态实现指南
• assets/anti-patterns.md — 反模式详细说明
• assets/layout-examples.md — CSS Grid 和 Flexbox 示例

脚本

• scripts/validate_design_tokens.py — 检查硬编码值
• scripts/check_accessibility.py — 基础无障碍验证