Back to Details

design-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design System

设计系统

Overview

概述

Single source of truth for visual consistency at scale — a shared language between design and engineering. Covers token architecture, theming infrastructure, component API patterns, accessibility compliance, and governance workflows.
Design systems are not component libraries alone. They unify tokens, patterns, documentation, and contribution processes so teams build once and maintain once.
实现大规模视觉一致性的单一事实来源——是设计与开发团队之间的共享语言。涵盖令牌架构、主题基础设施、组件API模式、无障碍合规性以及规范管理工作流。
设计系统并非只是组件库，它将令牌、模式、文档和贡献流程统一起来，让团队实现一次构建、统一维护。

Quick Reference

快速参考

AreaPatternKey Points
Token hierarchyPrimitive > Semantic > ComponentNever reference primitives in components; semantic layer is themable
Dark modeSwap semantic tokens via 
data-theme
Use off-white/dark-gray, not pure white/black
Multi-brand themingOverride semantic tokens per brandApply via CSS custom properties at runtime
Tailwind v4
@theme
block in CSS (no config file)		CSS-first configuration replaces 
tailwind.config.js
CVA variants
cva()
for variant + size combinations		Type-safe with 
VariantProps
; pair with 
cn()
utility
Compound components
Modal.Header
, 
Modal.Body
sub-parts		Composition over configuration; shared context for implicit state
Headless UIRadix primitives + Tailwind classesAccessibility built-in; bring your own styles
Focus management
focus-visible:ring-2
on all controls		2px solid outline with offset; visible on keyboard only
Reduced motion
prefers-reduced-motion
media query		Near-zero duration for all transitions and animations
Style DictionaryJSON tokens to CSS/iOS/Android
outputReferences: true
preserves token chain
StorybookStories + autodocs + a11y addonVisual documentation with accessibility audit built in
GovernanceSemver for tokens and componentsBreaking = removed props/tokens; minor = new additions
领域模式核心要点
令牌层级基础层 > 语义层 > 组件层切勿在组件中直接引用基础层令牌；语义层支持主题定制
深色模式通过
data-theme
切换语义令牌		使用米白/深灰色，而非纯白/纯黑
多品牌主题按品牌覆盖语义令牌运行时通过CSS自定义属性生效
Tailwind v4CSS中的
@theme
代码块（无需配置文件）		CSS优先的配置方式替代
tailwind.config.js
CVA变体使用
cva()
实现变体+尺寸组合		通过
VariantProps
实现类型安全；搭配
cn()
工具函数使用
复合组件
Modal.Header
、
Modal.Body
子组件		优先组合而非配置；共享上下文实现隐式状态传递
无头UIRadix原生组件 + Tailwind类内置无障碍支持；自定义样式
焦点管理所有控件添加
focus-visible:ring-2
2px实线外框带偏移；仅在键盘操作时显示
减少动效
prefers-reduced-motion
媒体查询		所有过渡和动画设置近乎零时长
Style DictionaryJSON令牌转CSS/iOS/Android
outputReferences: true
保留令牌依赖链
Storybook故事页 + 自动文档 + 无障碍插件内置无障碍审计的可视化文档
规范管理令牌与组件使用语义化版本控制重大变更=移除属性/令牌；次要变更=新增功能

Common Mistakes

常见误区

MistakeCorrect Pattern
Primitive tokens in components (
blue-500
)		Reference semantic tokens (
interactive-primary
) that map to primitives
Skipping focus states on interactive elementsAdd 
focus-visible:ring-2
on every button, link, and input
Body text set to 
gray-400
Use 
gray-600
or darker to meet 4.5:1 WCAG AA contrast
Circular token references between layersTokens flow one direction: primitive > semantic > component
Ignoring 
prefers-reduced-motion
Wrap all animations in a reduced-motion media query
Using 
scale()
transforms for hover		Use 
translateY(-1px)
and shadow changes to avoid layout shift
Hardcoded hex/px values in component filesAll visual values come from semantic or component tokens
Deep CSS nesting for theme overridesOverride CSS custom properties at the semantic layer
Theme flash on page load (FOUC)Inject synchronous theme script in 
<head>
before body renders
Flat token list without layersOrganize into primitive, semantic, and component tiers
错误做法正确实践
组件中直接引用基础层令牌（如
blue-500
）		引用映射到基础层的语义令牌（如
interactive-primary
）
交互元素跳过焦点状态为所有按钮、链接和输入框添加
focus-visible:ring-2
样式
正文文本设为
gray-400
使用
gray-600
或更深色以满足WCAG AA级4.5:1对比度要求
令牌层之间循环引用令牌单向流转：基础层 > 语义层 > 组件层
忽略
prefers-reduced-motion
将所有动画包裹在减少动效媒体查询中
悬停效果使用
scale()
变换		使用
translateY(-1px)
和阴影变化避免布局偏移
组件文件中硬编码十六进制/像素值所有视觉值均来自语义层或组件层令牌
主题覆盖使用深层CSS嵌套在语义层通过CSS自定义属性覆盖样式
页面加载时主题闪烁（FOUC）在
<head>
中注入同步主题脚本，确保在页面渲染前加载
令牌列表无层级结构按基础层、语义层、组件层分类组织

Delegation

任务分工

  • Audit codebase for hardcoded values that should be tokens: Use 
    Explore
    agent
  • Migrate a component library to a token-based design system: Use 
    Task
    agent
  • Plan a multi-brand theming architecture: Use 
    Plan
    agent
  • Review accessibility compliance across components: Use 
    Task
    agent
If the 
motion
skill is available, delegate animation token integration and motion design patterns to it.
  • 审计代码库中应替换为令牌的硬编码值：使用Explore Agent
  • 将组件库迁移至基于令牌的设计系统：使用Task Agent
  • 规划多品牌主题架构：使用Plan Agent
  • 审核组件的无障碍合规性：使用Task Agent
若Motion技能可用，可将动画令牌集成和动效设计模式相关任务委托给该技能。

References

参考资料

  • Design Tokens — three-layer hierarchy, CSS custom properties, TypeScript definitions, naming conventions
  • Theming — dark mode, theme provider, multi-brand, Tailwind v4, SSR flash prevention
  • Color and Typography — 60-30-10 rule, contrast requirements, type scale, fluid typography
  • Component Architecture — CVA variants, compound components, headless UI, polymorphic rendering
  • Accessibility — WCAG compliance, keyboard navigation, ARIA patterns, screen reader testing
  • Motion and Layout — animation tokens, reduced motion, spacing grid, elevation system
  • Tooling — Style Dictionary, Storybook, component testing, visual regression
  • Governance — versioning, deprecation, contribution workflow, component lifecycle
  • Troubleshooting — common issues, dark mode fixes, token sprawl, pre-delivery checklist
  • 设计令牌 — 三层级结构、CSS自定义属性、TypeScript定义、命名规范
  • 主题系统 — 深色模式、主题提供者、多品牌适配、Tailwind v4、SSR闪烁问题解决
  • 色彩与排版 — 60-30-10法则、对比度要求、字体层级、流体排版
  • 组件架构 — CVA变体、复合组件、无头UI、多态渲染
  • 无障碍适配 — WCAG合规、键盘导航、ARIA模式、屏幕阅读器测试
  • 动效与布局 — 动画令牌、减少动效、间距网格、层级系统
  • 工具链 — Style Dictionary、Storybook、组件测试、视觉回归检测
  • 规范管理 — 版本控制、废弃流程、贡献工作流、组件生命周期
  • 故障排查 — 常见问题、深色模式修复、令牌冗余、交付前检查清单