web-design-system

Web Design System

构建能够让产品更一致的最小系统。优先采用组件可用的语义契约，而不是大量装饰性数值。

选择模式

• 提取：产品的视觉风格一致，但缺少文档时使用。
• 协调：多种模式相互冲突时使用。
• 创建：新产品尚无既定 UI 语言时使用。
• 扩展：功能需要系统尚未提供的状态或组件时使用。

工作流

1. 检查框架、CSS 策略、主题文件、基础组件、组件库、图标集和代表性页面。
2. 梳理重复出现的数值和模式。区分有意的变化与意外的偏差。
3. 修改代码前，将原始数值映射到语义角色。例如：blue-600 -> action-primary，而不是“替换所有蓝色”。
4. 定义最精简的令牌层级：
   • 基础令牌：颜色、字体、间距、圆角、边框、阴影、动效；
   • 语义令牌：背景、表面、文本、边框、操作、焦点和状态；
   • 仅在组件确有需要时，定义组件令牌。
5. 说明组件结构、变体、尺寸和状态行为。纳入内容约束，而不只描述外观。
6. 定义响应式行为和密度规则，不要凭空创建特定设备的重复项。
7. 编码无障碍默认规范：语义元素、名称、标签、可见焦点、键盘行为、对比度、错误、目标尺寸和减少动态效果。
8. 在现有样式机制中实现。避免并行的令牌系统。
9. 迁移一个有代表性的组件或页面，并在安全的前提下移除已被取代的数值。
10. 验证浅色／深色主题、核心状态、窄／宽布局，以及至少一个真实的内容压力场景。

系统规则

• 根据用途命名令牌，而非当前外观。
• 保留基础样式的灵活使用方式，但让正确的用法更简单。
• 不要强迫所有区域都使用卡片。
• 不要只通过颜色表达状态。
• 保持组件 API 精简；优先组合，而不是不断增加变体。
• 除非既有模式损害可用性、无障碍性或可维护性，否则应予以保留。
• 在未来贡献者可能重新引入不一致的地方，记录相关决策。

交付约定

提供：

1. 模式和审查 - 现有内容、冲突和待完成事项。
2. 令牌映射 - 现有数值 -> 语义角色 -> 实现位置。
3. 组件约定 - 结构、变体、状态、内容限制、响应式行为。
4. 迁移范围 - 如需修改代码，至少包含一个实际组件。
5. 验证证据 - 已测试的主题、状态、视口和例外情况。

参考资料

定义或审查令牌和组件状态时，请阅读 references/token-checklist.md。