Back to Details

design-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design System

设计系统

Build, evolve, or audit a design system. Stack-agnostic in principle. Implementation is stack-specific (Figma, Storybook, code library, etc.) but the structure and governance principles transfer.
This skill is for building the system. For applying a system to specific pages or components, use 
design-standards
. For brand visual identity, use 
brand-identity
.
构建、演进或审核设计系统。原则上与技术栈无关。具体实现则取决于技术栈（Figma、Storybook、代码库等），但结构和治理原则是通用的。
此技能用于构建系统本身。若要将系统应用于特定页面或组件，请使用
design-standards
；若涉及品牌视觉识别，请使用
brand-identity
。

When to use

使用场景

  • Building a design system from scratch
  • Auditing an existing system for gaps or fragmentation
  • Defining design tokens at the system level
  • Structuring a component library
  • Establishing contribution and governance models
  • Migrating from ad-hoc components to a documented system
  • 从零开始构建设计系统
  • 审核现有系统，查找缺口或碎片化问题
  • 在系统层面定义design tokens
  • 搭建组件库结构
  • 建立贡献与治理模型
  • 从零散组件迁移到规范化的文档化系统

When NOT to use

非适用场景

  • Designing a single page or component (use 
    design-standards
    )
  • Brand identity work (use 
    brand-identity
    )
  • Component-level frontend implementation (use 
    frontend-component-build
    )
  • Pure design documentation for marketing (use 
    brand-style-guide
    )
  • 设计单个页面或组件（请使用
    design-standards
    ）
  • 品牌识别相关工作（请使用
    brand-identity
    ）
  • 组件级前端实现（请使用
    frontend-component-build
    ）
  • 纯营销类设计文档（请使用
    brand-style-guide
    ）

Required inputs

必要输入

  • The brand identity (tokens, voice, imagery direction)
  • The product surfaces the system needs to support (web, mobile, marketing, app, internal tools)
  • The team and its working tools (Figma, code framework, doc platform)
  • Existing components, even if undocumented
  • Constraints (accessibility requirements, performance targets, browser support)
If brand identity is undefined, run 
brand-identity
first.
  • 品牌识别体系（tokens、品牌调性、视觉方向）
  • 系统需要支持的产品载体（网页、移动端、营销物料、应用、内部工具）
  • 团队及其使用的工具（Figma、代码框架、文档平台）
  • 现有组件（即使未文档化）
  • 约束条件（无障碍要求、性能目标、浏览器支持范围）
若品牌识别体系未定义，请先执行
brand-identity
。

The framework: 5 layers

框架：5层结构

A complete design system has five layers, stacked. Each layer feeds the layer above.
完整的设计系统包含5个层级，层层递进，下层为上层提供支撑。

1. Foundations (tokens)

1. 基础层（tokens）

The atomic decisions. Color, type, spacing, radius, shadow, motion, breakpoints.
Why this layer matters:
  • Tokens are the source of truth for everything above
  • Token changes propagate everywhere automatically
  • Without tokens, the system has no foundation
Output:
  • A documented token set (see 
    design-standards/references/design-tokens-template.md
    )
  • Token implementation in code (CSS variables, JS objects, Style Dictionary, etc.)
  • Token implementation in Figma (variables and styles)
  • A primer doc explaining what tokens to use when
Common patterns:
  • Two-tier tokens: base tokens (raw values) + semantic tokens (named uses). Example: 
    color-blue-600
    (base) + 
    color-text-link
    (semantic). Components reference semantic tokens. Theme changes update semantic tokens, not base.
原子级决策，包含颜色、字体、间距、圆角、阴影、动效、断点。
该层级的重要性：
  • Tokens是所有上层内容的唯一可信来源
  • Token的变更会自动同步到所有相关内容
  • 没有tokens，系统就失去了核心基础
输出：
  • 已文档化的token集合（参考
    design-standards/references/design-tokens-template.md
    ）
  • 代码中的token实现（CSS变量、JS对象、Style Dictionary等）
  • Figma中的token实现（变量和样式）
  • 说明文档，解释不同场景下应使用的token
常见模式：
  • 双层token结构：基础token（原始值）+ 语义化token（命名用途）。示例：
    color-blue-600
    （基础）+ 
    color-text-link
    （语义化）。组件引用语义化token，主题变更时仅更新语义化token，而非基础token。

2. Elements (atoms)

2. 元素层（atoms）

The smallest functional building blocks. Buttons, inputs, labels, badges, icons, links, dividers.
Per element, document:
  • Visual variants (primary, secondary, ghost, etc.)
  • Size variants (small, medium, large)
  • States (default, hover, focus, active, disabled, error, loading)
  • Anatomy (the parts that make up the element)
  • Spacing and proportions
  • Accessibility (keyboard support, screen reader behavior, ARIA)
  • Code usage (props, examples)
Output:
  • Element library in Figma
  • Element components in code
  • Per-element documentation
最小的功能构建块，包括按钮、输入框、标签、徽章、图标、链接、分割线。
每个元素需文档化：
  • 视觉变体（主样式、次样式、幽灵样式等）
  • 尺寸变体（小、中、大）
  • 状态（默认、悬停、聚焦、激活、禁用、错误、加载中）
  • 组成结构（构成元素的各个部分）
  • 间距与比例
  • 无障碍支持（键盘操作、屏幕阅读器行为、ARIA规范）
  • 代码用法（属性、示例）
输出：
  • Figma中的元素库
  • 代码中的元素组件
  • 每个元素的单独文档

3. Components (molecules + organisms)

3. 组件层（molecules + organisms）

Combinations of elements that form recognizable UI patterns. Cards, alerts, modals, navigation, forms, data tables, headers, footers.
Per component:
  • Composition (which elements it uses)
  • Variants and configurations
  • Use cases (when to reach for this vs. an alternative)
  • Layout behavior (responsive, contained, full-bleed)
  • Anti-patterns (when NOT to use it)
Output:
  • Component library
  • Per-component documentation with usage guidance
元素组合而成的可识别UI模式，包括卡片、提示框、模态框、导航栏、表单、数据表格、页头、页脚。
每个组件需文档化：
  • 组成结构（使用了哪些元素）
  • 变体与配置项
  • 使用场景（何时选择此组件而非其他替代方案）
  • 布局行为（响应式、容器化、全屏）
  • 反模式（禁止使用的场景）
输出：
  • 组件库
  • 包含使用指南的组件文档

4. Patterns (templates)

4. 模式层（模板）

Larger structures that combine components. Sign-in flow, settings page, dashboard layout, marketing page sections.
Per pattern:
  • The structure and components used
  • The user journey it supports
  • Layout grid and spacing
  • Responsive behavior
  • Variants (e.g., "with sidebar," "fullscreen," "modal")
Output:
  • Pattern library or page templates
  • Documentation showing complete examples
组件组合而成的大型结构，包括登录流程、设置页面、仪表盘布局、营销页面模块。
每个模式需文档化：
  • 结构与使用的组件
  • 支持的用户旅程
  • 布局网格与间距
  • 响应式表现
  • 变体（如“带侧边栏”、“全屏”、“模态框式”）
输出：
  • 模式库或页面模板
  • 展示完整示例的文档

5. Documentation and governance

5. 文档与治理层

How the system gets used, contributed to, and maintained.
Documentation includes:
  • Getting started guide for new team members
  • How to use vs. how to extend
  • Contribution model
  • Versioning policy
  • Migration paths when breaking changes happen
  • Decision log for major system choices
Governance includes:
  • Who owns the system (a team or rotation)
  • How new components get proposed and approved
  • How conflicts get resolved
  • How the system evolves vs. stays stable
  • Cadence of review and updates
系统的使用、贡献与维护规则。
文档包含：
  • 新成员入门指南
  • 使用与扩展的区别说明
  • 贡献模型
  • 版本控制策略
  • 重大变更时的迁移路径
  • 系统重大决策日志
治理包含：
  • 系统所有者（团队或轮值制）
  • 新组件的提案与审批流程
  • 冲突解决机制
  • 系统演进与稳定性的平衡规则
  • 审核与更新的周期

Workflow

工作流程

For a new design system

新建设计系统

  1. Inventory the existing UI. Screenshot every component, button, form, modal across the product. The list of distinct UI patterns is your starting scope.
  2. Identify the duplicates. Same component built 5 different ways across the product. These are your high-value consolidation targets.
  3. Define foundations. Token set, with both base and semantic layers. Document each.
  4. Audit elements. From the inventory, identify the actual elements (buttons, inputs, etc.) and reduce variants to a managed set.
  5. Build the element library. Figma + code. Document each element.
  6. Identify priority components. The 10 to 15 components that appear most often. Build those first.
  7. Document patterns. Page-level templates that show the system in use.
  8. Establish governance. Owner, contribution model, review cadence.
  9. Roll out. Migrate existing surfaces to the system progressively.
  1. 盘点现有UI：截取产品中所有组件、按钮、表单、模态框的截图。不同UI模式的列表就是你的初始范围。
  2. 识别重复项：同一组件在产品中有5种不同实现方式，这些是优先整合的高价值目标。
  3. 定义基础层：包含基础和语义化双层结构的token集合，并为每个token编写文档。
  4. 审核元素：从盘点结果中识别实际元素（按钮、输入框等），将变体精简为可管理的集合。
  5. 构建元素库：同时完成Figma和代码实现，并为每个元素编写文档。
  6. 确定优先组件：选择出现频率最高的10-15个组件，优先构建。
  7. 文档化模式：编写展示系统实际应用的页面级模板文档。
  8. 建立治理机制：确定所有者、贡献模型、审核周期。
  9. 逐步推广：将现有产品载体逐步迁移到新系统。

For an existing design system audit

现有设计系统审核

  1. Inventory what exists. What's documented, what's in Figma, what's in code, what's actually used in production.
  2. Map gaps. Where the system is incomplete. Where teams build outside the system because the system can't serve their need.
  3. Map fragmentation. Where the system has divergent implementations (Figma vs. code, web vs. mobile, multiple teams).
  4. Identify decay. Components that have drifted from the documented standard.
  5. Prioritize fixes. Foundation gaps first. High-use component drift second. Rarely-used component cleanup last.
  6. Plan rollout. Major changes need migration paths.
  1. 盘点现有内容：已文档化的内容、Figma中的资源、代码中的实现、生产环境中实际使用的内容。
  2. 查找缺口：系统不完善的地方，以及团队因系统无法满足需求而自行构建内容的场景。
  3. 分析碎片化问题：系统存在不一致实现的场景（Figma与代码不一致、网页与移动端不一致、多团队实现不一致）。
  4. 识别偏离情况：组件与文档标准不符的情况。
  5. 确定修复优先级：优先修复基础层缺口，其次修复高频使用组件的偏离问题，最后清理极少使用的组件。
  6. 规划推广：重大变更需要制定迁移路径。

Failure patterns

常见失败模式

  • Building the system before the brand is set. Tokens depend on brand. Set brand first.
  • Atoms-up extreme. Spending 6 months on tokens and elements before producing components anyone uses. Ship components people need; refine tokens iteratively.
  • One-person system. A system without governance fails as soon as the original designer leaves. Establish ownership early.
  • Stale documentation. A system with code that's diverged from the docs is worse than no system. Synchronize or kill the docs.
  • Versioning everything. Treating every component as needing a major version. Most components evolve in place. Reserve versioning for breaking changes.
  • Adopting "atomic design" dogmatically. Atoms / molecules / organisms is a useful mental model, not a rigid taxonomy. Don't argue about whether something is a molecule or an organism.
  • Building in a vacuum. A system designed without input from the teams using it gets ignored. Co-design with consumers.
  • No deprecation path. Old components linger in code forever because no one knows it's safe to remove them. Document deprecation explicitly.
  • Token explosion. Defining 200 color tokens for a brand with 10 colors. Discipline. Most products need fewer tokens than they have.
  • 品牌未确定就构建系统：Tokens依赖品牌，需先确定品牌。
  • 极端原子化优先：花费6个月时间在tokens和元素上，却未产出任何人能用的组件。先交付用户需要的组件，再迭代优化tokens。
  • 单人维护的系统：没有治理机制的系统，一旦原设计师离开就会失效。需尽早确定所有权。
  • 文档过时：代码与文档不一致的系统比没有系统更糟糕。要么同步更新文档，要么废弃文档。
  • 过度版本化：将每个组件都视为需要大版本更新。大多数组件可逐步演进，仅对重大变更进行版本控制。
  • 教条式采用atomic design：Atoms/molecules/organisms是有用的思维模型，而非严格的分类规则。无需纠结某个内容属于molecule还是organism。
  • 闭门造车：未征求使用团队意见设计的系统会被忽略。需与用户团队协同设计。
  • 无废弃路径：旧组件因无人确认是否可删除而长期留在代码中。需明确文档化废弃规则。
  • Token泛滥：为只有10种颜色的品牌定义200个颜色token。需保持克制，大多数产品需要的token数量远少于实际定义的数量。

Output format

输出格式

A design system has multiple deliverables. Typically:
  • Documentation site (Notion, dedicated site, GitHub Pages, Storybook addon, etc.)
  • Figma library (or equivalent design tool)
  • Code library (npm package, monorepo workspace, copy-paste components)
  • Decision log (system-level decisions and the reasoning)
  • Roadmap and changelog
For a design system audit, output is a markdown report at 
design-system-audit.md
:
  1. Inventory of what exists (foundations, elements, components, patterns)
  2. Gap analysis
  3. Fragmentation analysis
  4. Drift analysis
  5. Prioritized remediation plan
  6. Governance recommendations
设计系统包含多个交付物，通常包括：
  • 文档站点（Notion、专属站点、GitHub Pages、Storybook插件等）
  • Figma库（或其他同类设计工具库）
  • 代码库（npm包、单体仓库工作区、可复制粘贴的组件）
  • 决策日志（系统级决策及其理由）
  • 路线图与变更日志
设计系统审核的输出为
design-system-audit.md
格式的Markdown报告，包含：
  1. 现有内容盘点（基础层、元素层、组件层、模式层）
  2. 缺口分析
  3. 碎片化分析
  4. 偏离分析
  5. 优先级修复计划
  6. 治理建议

Reference files

参考文件

  • references/system-architecture.md
     - The four-layer model (tokens, primitives, patterns, templates) and how to decide where new work belongs.
  • references/system-audit-template.md
     - Template for auditing an existing design system.
  • references/governance-playbook.md
     - Contribution model, ownership, and decision process for an active system.
  • references/system-architecture.md
     - 四层模型（tokens、基础元素、模式、模板）及如何确定新工作的归属层级。
  • references/system-audit-template.md
     - 现有设计系统审核模板。
  • references/governance-playbook.md
     - 活跃系统的贡献模型、所有权及决策流程。