design-system

设计系统

概述

实现大规模视觉一致性的唯一事实来源，是设计与工程之间共享的语言。涵盖令牌架构、主题基础设施、组件 API 模式、无障碍合规性和治理工作流。

设计系统不只是组件库。它们整合令牌、模式、文档和贡献流程，让团队一次构建、一次维护。

快速参考

领域	模式	要点
令牌层级	基础 > 语义 > 组件	组件中绝不直接引用基础令牌；语义层可应用主题
深色模式	通过 data-theme 切换语义令牌	使用米白色／深灰色，而非纯白色／纯黑色
多品牌主题	按品牌覆盖语义令牌	运行时通过 CSS 自定义属性应用
Tailwind v4	CSS 中的 @theme 代码块（无配置文件）	以 CSS 为先的配置取代 tailwind.config.js
CVA 变体	使用 cva() 组合变体和尺寸	通过 VariantProps 实现类型安全；搭配 cn() 工具
复合组件	Modal.Header、Modal.Body 子部分	优先组合而非配置；通过共享上下文管理隐式状态
无头 UI	Radix 原语 + Tailwind 类	内置无障碍支持；样式由你自行提供
焦点管理	所有控件使用 focus-visible:ring-2	2px 实线轮廓并带偏移；仅在键盘操作时显示
减少动态效果	prefers-reduced-motion 媒体查询	将所有过渡和动画的持续时间设为接近零
Style Dictionary	将 JSON 令牌转换为 CSS/iOS/Android	outputReferences: true 可保留令牌链
Storybook	Stories + autodocs + a11y addon	内置无障碍审查的可视化文档
治理	对令牌和组件采用语义化版本控制	破坏性更改 = 移除属性／令牌；次要版本 = 新增内容

常见错误

错误	正确模式
在组件中使用基础令牌（blue-500）	引用映射到基础令牌的语义令牌（interactive-primary）
交互元素缺少焦点状态	为每个按钮、链接和输入框添加 focus-visible:ring-2
正文文本使用 gray-400	使用 gray-600 或更深的灰色，以达到 WCAG AA 4.5:1 对比度
不同层之间的令牌相互循环引用	令牌只沿单一方向流动：基础 > 语义 > 组件
忽略 prefers-reduced-motion	将所有动画放在减少动态效果的媒体查询中
悬停时使用 scale() 变换	使用 translateY(-1px) 和阴影变化，避免布局偏移
在组件文件中硬编码十六进制颜色／px 值	所有视觉值都应来自语义令牌或组件令牌
为主题覆盖使用深层 CSS 嵌套	在语义层覆盖 CSS 自定义属性
页面加载时主题闪烁（FOUC）	在 <head> 中注入同步主题脚本，在 body 渲染前执行
使用没有分层的扁平令牌列表	按基础、语义和组件层级组织令牌

委派

• 审查代码库中应使用设计令牌的硬编码值：使用 Explore Agent
• 将组件库迁移到基于设计令牌的设计系统：使用 Task Agent
• 规划多品牌主题架构：使用 Plan Agent
• 审查组件的无障碍合规性：使用 Task Agent

如果有 motion 技能，请将动画令牌集成和动态设计模式委派给它。

参考资料

• 设计令牌 — 三层层级、CSS 自定义属性、TypeScript 定义、命名约定
• 主题 — 深色模式、主题提供程序、多品牌、Tailwind v4、SSR 闪烁预防
• 颜色与字体排版 — 60-30-10 规则、对比度要求、字体级别、流式字体排版
• 组件架构 — CVA 变体、复合组件、无头 UI、多态渲染
• 无障碍 — WCAG 合规性、键盘导航、ARIA 模式、屏幕阅读器测试
• 动态效果与布局 — 动画令牌、减少动态效果、间距网格、海拔系统
• 工具 — Style Dictionary、Storybook、组件测试、视觉回归
• 治理 — 版本控制、弃用、贡献工作流、组件生命周期
• 故障排除 — 常见问题、深色模式修复、令牌泛滥、交付前检查清单