atomic-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Atomic Design

原子设计

Value: Simplicity and communication. Building UI from small, named, composable pieces makes the interface understandable to everyone on the team and prevents the complexity that comes from monolithic components.

核心价值： 简洁性与可沟通性。通过小型、具名、可组合的单元构建UI，能让团队所有人都理解界面结构，同时避免单体组件带来的复杂度。

Purpose

目标

Teaches how to organize UI components into a hierarchy of increasing complexity: atoms, molecules, organisms, and templates. Each level has clear responsibilities and composition rules. The outcome is a component system where every piece is reusable, testable in isolation, and named in a shared vocabulary.

指导如何将UI组件组织为复杂度递增的层级结构：Atoms（原子）、Molecules（分子）、Organisms（有机体）和Templates（模板）。每个层级都有明确的职责和组合规则。最终形成的组件系统中，每个单元都可复用、可独立测试，且采用团队共用的命名体系。

Practices

实践方法

Build Bottom-Up Through Four Levels

自底向上构建四个层级

Start with the smallest reusable elements and compose upward. Never skip a level.

The four levels:

Atoms: Indivisible UI elements. A button, an input, a label, an icon. One visual element, one responsibility. Atoms reference design tokens for all visual properties (color, spacing, typography).
Molecules: Small groups of atoms functioning as a unit. A form field (label + input + error message). A search bar (input + button + icon). One interaction pattern per molecule.
Organisms: Complex components composed of molecules and atoms that form a distinct section of the interface. A navigation header, a complete form, a data table. One feature area per organism.
Templates: Page-level layouts that arrange organisms into a complete view. A dashboard template, a list-detail template. Templates define structure and content slots, not specific data.

Example:

Atom: Button, Input, Label, ErrorMessage
Molecule: FormField (Label + Input + ErrorMessage)
Organism: LoginForm (FormField + FormField + Button)
Template: AuthPage (Header + LoginForm + Footer)

Do:

Start with atoms when building new UI
Name components by what they ARE, not what data they show
Keep atoms under 50 lines, molecules under 100

Do not:

Build organisms directly from raw markup -- extract atoms first
Create a molecule that does not compose atoms from your system
Skip to templates before organisms exist

从最小的可复用元素开始，逐步向上组合。切勿跳过任何层级。

四个层级：

Atoms： 不可拆分的UI元素。如按钮、输入框、标签、图标。每个原子对应一个视觉元素，承担单一职责。原子的所有视觉属性（颜色、间距、排版）均引用设计令牌（design tokens）。
Molecules： 由多个原子组合而成的小型功能单元。如表单字段（标签+输入框+错误提示）、搜索栏（输入框+按钮+图标）。每个分子对应一个交互模式。
Organisms： 由分子和原子组合而成的复杂组件，构成界面中独立的功能区块。如导航头部、完整表单、数据表格。每个有机体对应一个功能区域。
Templates： 页面级布局，将有机体组合为完整视图。如仪表板模板、列表详情模板。模板定义结构和内容插槽，而非具体数据。

示例：

Atom: Button, Input, Label, ErrorMessage
Molecule: FormField (Label + Input + ErrorMessage)
Organism: LoginForm (FormField + FormField + Button)
Template: AuthPage (Header + LoginForm + Footer)

正确做法：

构建新UI时从原子开始
按组件的本质命名，而非其展示的数据
原子代码不超过50行，分子不超过100行

错误做法：

直接用原生标记构建有机体——先提取原子
创建未使用系统内原子的分子
未完成有机体就直接构建模板

Keep Components Presentational

保持组件的展示性

Components render UI. They receive data as props. They do not fetch data, manage business logic, or hold application state.

Pass all data through props or equivalent
Emit events for user actions -- do not handle side effects
Separate data containers from presentational components

Example:

Presentational (good):
  UserCard({ name, email, avatar }) -> renders UI

Container (separate):
  UserCardContainer() -> fetches data, passes to UserCard

Do not:

Put API calls inside atoms, molecules, or organisms
Couple a component to a specific data source
Mix rendering logic with business logic in the same component

组件仅负责渲染UI。通过props接收数据，不处理数据请求、业务逻辑或应用状态管理。

所有数据均通过props或等效方式传递
用户操作触发事件，不处理副作用
将数据容器组件与展示组件分离

示例：

Presentational (good):
  UserCard({ name, email, avatar }) -> renders UI

Container (separate):
  UserCardContainer() -> fetches data, passes to UserCard

错误做法：

在原子、分子或有机体中嵌入API调用
将组件与特定数据源绑定
在同一组件中混合渲染逻辑与业务逻辑

Use Design Tokens for All Visual Properties

所有视觉属性使用设计令牌

Extract every design decision (colors, spacing, typography, shadows, radii) into named tokens. Components reference tokens, never raw values.

Define tokens as the first step of any new design system
Every color, spacing value, and font size in a component must come from a token
Changing a token updates every component that references it

Example:

css

/* Tokens */
--color-primary: #0066cc;
--spacing-sm: 8px;
--spacing-md: 16px;

/* Component uses tokens, not values */
.button { background: var(--color-primary); padding: var(--spacing-sm); }

Do not:

Hard-code
```
#0066cc
```
or
```
8px
```
in any component
Create one-off token names for single components
Define tokens that are never used (tokens should earn their place)

将所有设计决策（颜色、间距、排版、阴影、圆角）提取为具名令牌。组件引用令牌，而非直接使用原始值。

启动新设计系统时，首先定义设计令牌
组件中的所有颜色、间距、字号必须引用令牌
修改令牌会自动更新所有引用该令牌的组件

示例：

css

/* Tokens */
--color-primary: #0066cc;
--spacing-sm: 8px;
--spacing-md: 16px;

/* Component uses tokens, not values */
.button { background: var(--color-primary); padding: var(--spacing-sm); }

错误做法：

在任何组件中硬编码
```
#0066cc
```
或
```
8px
```
等值
为单个组件创建专属令牌名称
定义从未被使用的令牌（令牌需具备实际用途）

Compose, Do Not Inherit

组合而非继承

Build complex components by nesting simpler ones. Do not extend base components through class inheritance or deep prop-forwarding chains.

Pass children or slots to compose layout
Keep the component tree flat -- prefer siblings over deep nesting
When you need a variant, compose a new molecule from atoms rather than adding flags to an existing molecule

Do:

```
IconButton = Icon + Button
```
(composition)
```
Card > CardHeader + CardBody
```
(slots)

Do not:

```
FancyButton extends Button
```
(inheritance)
A single Button component with 15 variant props

通过嵌套简单组件来构建复杂组件。不要通过类继承或深层props转发链扩展基础组件。

通过子元素或插槽实现布局组合
保持组件树扁平化——优先使用同级组件而非深层嵌套
如需变体，通过原子组合新的分子，而非在现有分子中添加标记

正确做法：

```
IconButton = Icon + Button
```
（组合方式）
```
Card > CardHeader + CardBody
```
（插槽方式）

错误做法：

```
FancyButton extends Button
```
（继承方式）
单个Button组件包含15个变体props

Enforcement Note

执行说明

This skill provides advisory guidance on component organization. It cannot mechanically prevent an agent from skipping levels or hard-coding design values. On harnesses with plugin support, enforcement plugins can lint for token usage and validate component hierarchy. On harnesses without enforcement, the agent follows these practices by convention. If you observe the agent building organisms from raw markup, point it out. For available enforcement plugins, see the Harness Plugin Availability table.

本技能提供组件组织的指导性建议，无法机械阻止Agent跳过层级或硬编码设计值。在支持插件的开发环境中，可通过执行插件检查令牌使用情况并验证组件层级。在不支持插件的环境中，Agent将遵循这些约定实践。若发现Agent直接用原生标记构建有机体，请及时指出。关于可用的执行插件，可查看Harness插件可用性表格。

Verification

验证

Dependencies

依赖

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

domain-modeling: Read models from the domain define what data components receive as props.
tdd-cycle: Test components in isolation at each level -- atom tests, molecule tests, organism tests.
event-modeling: Wireframes from event modeling sessions identify which components are needed.

Missing a dependency? Install with:

npx skills add jwilger/agent-skills --skill tdd-cycle

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

domain-modeling： 领域建模中定义的模型，决定组件通过props接收的数据结构。
tdd-cycle： 在每个层级独立测试组件——原子测试、分子测试、有机体测试。
event-modeling： 事件建模会话中的线框图可确定所需组件。

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

npx skills add jwilger/agent-skills --skill tdd-cycle