design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design System

设计系统

Value: Communication -- a documented design system creates shared vocabulary for every visual decision. When philosophy is explicit and tokens are named, contributors extend the system consistently without guessing at intent.

价值： 沟通——一份文档化的设计系统为所有视觉决策创建了共享的词汇表。当设计理念明确且令牌命名规范时，贡献者可以一致地扩展系统，无需猜测设计意图。

Purpose

目标

Facilitates collaborative creation of a design system specification. Produces an artifact at

docs/design-system.pen

(if Pencil MCP is available) or

docs/design-system.html

(single-file fallback) that documents philosophy, tokens, and the full component hierarchy from atoms through templates.

协助协作创建设计系统规范。生成一份规范文档，若Pencil MCP可用则保存为

docs/design-system.pen

，否则使用单文件回退格式

docs/design-system.html

，文档内容包含设计理念、设计令牌以及从原子到模板的完整组件层级结构。

Practices

实践规范

Detect Artifact Format

检测文档格式

Check whether the

mcp__pencil__get_editor_state

tool is available.

Present: Use
```
.pen
```
format. Follow
```
references/pencil-workflow.md
```
.
Absent: Use HTML format. Follow
```
references/html-artifact.md
```
.

Decide the format before starting any design work. Do not switch formats mid-process.

检查是否提供

mcp__pencil__get_editor_state

工具。

已提供： 使用
```
.pen
```
格式。遵循
```
references/pencil-workflow.md
```
规范。
未提供： 使用HTML格式。遵循
```
references/html-artifact.md
```
规范。

在开始任何设计工作前确定格式，过程中不得切换格式。

Follow the Seven-Phase Collaborative Process

遵循七阶段协作流程

You MUST follow

references/design-phases.md

for the full methodology. Each phase completes before the next begins.

Phases at a glance:

Philosophy & Constraints -- Brand, principles, accessibility, responsive strategy, constraints. Every subsequent decision traces here.
Design Tokens -- Color, typography, spacing, radii, elevation, motion, breakpoints, opacity. Each token cites a philosophy principle.
Atoms -- Indivisible elements (buttons, inputs, labels, icons). Each documents states and references only tokens.
Molecules -- Functional units composed of atoms (form fields, search bars). Documents composition and interaction.
Organisms -- Distinct UI sections composed of molecules and atoms (headers, forms, data tables). Documents layout behavior.
Templates -- Page layouts arranging organisms. Defines structure, content slots, and breakpoint behavior.
Artifact Assembly -- Compile into the chosen format with philosophy as the first section.

必须遵循

references/design-phases.md

中的完整方法论。完成前一阶段后才能进入下一阶段。

阶段概览：

设计理念与约束 —— 品牌、原则、无障碍设计、响应式策略、约束条件。后续所有决策均需追溯至此。
设计令牌（Design Tokens） —— 颜色、排版、间距、圆角、层级、动效、断点、透明度。每个令牌需关联对应的设计理念原则（例如：
```
P1
```
）。
原子（Atoms） —— 不可拆分的元素（按钮、输入框、标签、图标）。每个元素需记录状态，且仅引用设计令牌。
分子（Molecules） —— 由原子组成的功能单元（表单字段、搜索栏）。记录组合方式与交互逻辑。
有机体（Organisms） —— 由分子和原子组成的独立UI区块（页头、表单、数据表格）。记录布局行为。
模板（Templates） —— 排列有机体的页面布局。定义结构、内容插槽和断点行为。
文档组装 —— 将内容编译为选定格式，设计理念作为第一部分。

Facilitate, Do Not Assume

引导协作，而非主观假设

You are a facilitator, not a stenographer. Ask probing questions at each phase. Challenge choices that conflict with stated philosophy. Use

references/facilitation-questions.md

for question banks.

Do not assume visual preferences -- ask
Do not skip ahead when the user gives a partial answer -- probe deeper
If event model wireframes exist in
```
docs/event_model/
```
, use them to identify required components, but still confirm with the user
Present token proposals informed by the philosophy and ask for adjustments

你是协作引导者，而非记录员。在每个阶段提出深入问题。挑战与既定设计理念冲突的选择。可参考

references/facilitation-questions.md

中的问题库。

不要主观假设视觉偏好——主动询问
用户给出部分答案时，不要跳过后续步骤——深入探究
若
```
docs/event_model/
```
中存在事件模型线框图，可用于识别所需组件，但仍需与用户确认
根据设计理念提出令牌方案，并请求用户调整

Enforce Philosophy Traceability

确保设计理念可追溯

Every design decision traces back to the philosophy.

Tokens cite which philosophy principle they serve (e.g.,
```
P1
```
)
Atoms reference which tokens they use
Molecules document which atoms they compose
Organisms document which molecules and atoms they compose
Templates document which organisms they arrange

If a token cannot cite a principle, either the token is unnecessary or the philosophy is incomplete. Resolve before proceeding.

Do:

Define philosophy before any visual decisions
Use only token references in components -- never raw values
Complete each phase before starting the next
Verify traceability at every level
Refer to
```
references/token-categories.md
```
for comprehensive token guidance

Do not:

Make technology decisions (CSS framework, component library) -- those belong in architecture-decisions
Skip the philosophy phase or treat it as optional
Use raw color codes, pixel values, or font names in components
Design multiple phases simultaneously
Proceed with gaps -- if something is undefined, ask

每个设计决策都必须追溯到设计理念。

令牌需标注其服务的设计理念原则
原子引用所使用的令牌
分子记录其组成的原子
有机体记录其组成的分子和原子
模板记录其排列的有机体

如果某个令牌无法关联到设计理念原则，要么该令牌是多余的，要么设计理念不完整。需解决后再继续。

正确做法：

在做出任何视觉决策前定义设计理念
组件中仅使用令牌引用——绝不使用原始值
完成前一阶段后再进入下一阶段
在每个层级验证可追溯性
参考
```
references/token-categories.md
```
获取全面的令牌指导

禁止做法：

做出技术决策（CSS框架、组件库）——这些属于架构决策范畴
跳过设计理念阶段或视其为可选步骤
在组件中使用原始颜色代码、像素值或字体名称
同时设计多个阶段
存在未定义内容时继续推进——若有不明确之处，主动询问

Enforcement Note

执行说明

This skill provides advisory guidance. The agent tracks phase state and halts if the philosophy phase is skipped or if raw values are used instead of token references in components. It cannot mechanically prevent all violations but will flag traceability gaps when detected. If you observe the agent skipping a phase or using hard-coded values, point it out.

本技能提供指导性建议。Agent会跟踪阶段状态，若跳过设计理念阶段或在组件中使用原始值而非令牌引用，将暂停流程。它无法机械地阻止所有违规行为，但会在检测到可追溯性缺口时发出警告。若你发现Agent跳过阶段或使用硬编码值，请指出问题。

Verification

验证

After completing work guided by this skill, verify:

Philosophy documented with named principles before any components
Tokens defined for all visual categories (color, typography, spacing, radii, elevation, motion, breakpoints, opacity)
Every token cites a philosophy principle
Atoms reference only tokens (no raw values)
Molecules compose only atoms from the catalog
Organisms compose only molecules and atoms from the catalog
Templates arrange only organisms from the catalog
All component states documented (default, hover, focus, disabled, error as applicable)
Wireframe fields mapped to components if event model exists

Artifact exists at

docs/design-system.pen

docs/design-system.html

Philosophy is the first section in the artifact

If any criterion is not met, revisit the relevant phase before proceeding.

完成本技能指导的工作后，需验证以下内容：

在任何组件设计前，已记录带有命名原则的设计理念
为所有视觉类别（颜色、排版、间距、圆角、层级、动效、断点、透明度）定义了令牌
每个令牌均关联了设计理念原则
原子仅引用令牌（无原始值）
分子仅使用组件库中的原子组成
有机体仅使用组件库中的分子和原子组成
模板仅排列组件库中的有机体
所有组件状态均已记录（默认、悬停、聚焦、禁用、错误等适用状态）
若存在事件模型，线框图字段已映射到组件

文档已保存为

docs/design-system.pen

或

docs/design-system.html

设计理念是文档的第一部分

若有任何一项未满足，需重新处理相关阶段后再继续。

Dependencies

依赖关系

This skill works standalone. For enhanced workflows, it integrates with:

event-modeling: Wireframes from event modeling sessions identify which components the design system must include. Run event-modeling first for best results.
architecture-decisions: The design system specification informs technology decisions for UI implementation (CSS framework, component library, build tooling). Run design-system before architecture-decisions.
atomic-design: The design system specification provides the token definitions, component catalog, and hierarchy that atomic-design implements in code.
tdd: Token values and component specifications become testable contracts -- visual regression tests verify token compliance.

Missing a dependency? Install with:

npx skills add jwilger/agent-skills --skill event-modeling

本技能可独立使用。为增强工作流程，它可与以下技能集成：

event-modeling： 事件建模会话生成的线框图可确定设计系统必须包含的组件。建议先运行event-modeling。
architecture-decisions： 设计系统规范为UI实现的技术决策（CSS框架、组件库、构建工具）提供依据。建议先运行design-system，再运行architecture-decisions。
atomic-design： 设计系统规范提供令牌定义、组件库和层级结构，供atomic-design在代码中实现。
tdd： 令牌值和组件规范成为可测试的契约——视觉回归测试可验证令牌合规性。

缺少依赖？可通过以下命令安装：

npx skills add jwilger/agent-skills --skill event-modeling