atomic-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Atomic Design System

原子设计系统

Build production-ready design systems using Atomic Design methodology.

使用原子设计方法论构建可用于生产环境的设计系统。

Critical Rule: Figma Is Source of Truth

核心规则：Figma是唯一可信源

ALWAYS extract and implement from Figma exactly. Never guess design values.

必须严格从Figma中提取并实现设计。绝不猜测设计参数。

Figma-First Workflow (Required)

Figma优先工作流（强制要求）

EXTRACT FROM FIGMA (Mandatory)
- Use Figma MCP: get_code_connect_map / get_node
- Copy specs: colors, spacing, typography, effects
- Document ALL extracted values
COMPARE WITH EXISTING
- Check current tokens/*.json
- If Figma differs -> UPDATE tokens (Figma wins always)
IMPLEMENT EXACTLY
- Match Figma specs 1:1
- No rounding, no improvements, no creative freedom

从Figma提取（必须执行）
- 使用Figma MCP：get_code_connect_map / get_node
- 复制规格参数：颜色、间距、排版、特效
- 记录所有提取的参数值
与现有内容对比
- 检查当前tokens/*.json文件
- 若Figma内容不同 -> 更新tokens（始终以Figma为准）
严格实现
- 1:1匹配Figma规格
- 不得四舍五入、不得自行优化、无创作自由

Zero Deviation Policy

零偏差原则

Forbidden	Correct
Round 13px to 12px	Use exact 13px
Change #3B82F6 to #3F85F7	Use exact #3B82F6
Add shadow not in Figma	No shadow if not designed
Improve spacing	Exact spacing from Figma

禁止行为	正确做法
将13px四舍五入为12px	使用精确的13px
将#3B82F6改为#3F85F7	使用精确的#3B82F6
添加Figma中未定义的阴影	若未设计则不添加阴影
优化间距	使用Figma中的精确间距

When to Use

使用场景

Trigger	Action
Create a component	Extract from Figma -> Build
Style element	Check Figma specs -> Apply
Build page/form/layout	Switch to atomic-page-builder
Extract tokens	Use this skill

触发条件	操作
创建组件	从Figma提取 -> 构建
样式化元素	查看Figma规格 -> 应用
构建页面/表单/布局	切换至atomic-page-builder
提取令牌	使用此技能

Figma MCP Commands

Figma MCP 命令

typescript

figma.get_node(file_key, node_id)        // Get component specs
figma.get_code_connect_map(file_key, node_id)  // Get code snippets
figma.get_styles(file_key, style_type)   // Get styles
figma.get_local_variables(file_key)      // Get design tokens

typescript

figma.get_node(file_key, node_id)        // Get component specs
figma.get_code_connect_map(file_key, node_id)  // Get code snippets
figma.get_styles(file_key, style_type)   // Get styles
figma.get_local_variables(file_key)      // Get design tokens

Design Tokens

设计令牌

Need	File	Key Values
Colors	tokens/colors.json	semantic.primary, semantic.error
Typography	tokens/typography.json	semantic.heading-1, semantic.body
Spacing	tokens/spacing.json	semantic.component-padding
Components	tokens/components.json	button.variants, input.states
Breakpoints	tokens/breakpoints.json	md: 768px, lg: 1024px

需求	文件	关键值
颜色	tokens/colors.json	semantic.primary, semantic.error
排版	tokens/typography.json	semantic.heading-1, semantic.body
间距	tokens/spacing.json	semantic.component-padding
组件	tokens/components.json	button.variants, input.states
断点	tokens/breakpoints.json	md: 768px, lg: 1024px

Token Usage

令牌使用

css

/* DO: Use semantic names */
color: var(--color-primary);
padding: var(--spacing-component-padding);

/* DON'T: Use primitives directly */
color: var(--blue-500);  /* Wrong */
padding: 16px;           /* Wrong */

css

/* DO: Use semantic names */
color: var(--color-primary);
padding: var(--spacing-component-padding);

/* DON'T: Use primitives directly */
color: var(--blue-500);  /* Wrong */
padding: 16px;           /* Wrong */

Atomic Hierarchy

原子层级结构

PAGES      -> Dashboard, Settings, UserProfile
TEMPLATES  -> DashboardLayout, AuthLayout
ORGANISMS  -> Header, Sidebar, Form, DataTable
MOLECULES  -> FormField, SearchBar, Card, NavItem
ATOMS      -> Button, Input, Typography, Icon
TOKENS     -> colors, typography, spacing (FROM FIGMA)

Level	Rule	Example
Atom	Uses ONLY tokens	Button uses color/spacing tokens
Molecule	Combines 2+ Atoms	FormField = Label + Input + ErrorText
Organism	Combines Molecules + Atoms	Header = Logo + NavItems + UserMenu
Template	Layout structure, no content	DashboardLayout
Page	Template + real content	Dashboard

PAGES      -> Dashboard, Settings, UserProfile
TEMPLATES  -> DashboardLayout, AuthLayout
ORGANISMS  -> Header, Sidebar, Form, DataTable
MOLECULES  -> FormField, SearchBar, Card, NavItem
ATOMS      -> Button, Input, Typography, Icon
TOKENS     -> colors, typography, spacing (FROM FIGMA)

层级	规则	示例
原子	仅使用令牌	Button使用颜色/间距令牌
分子	组合2个及以上原子	FormField = 标签 + 输入框 + 错误文本
有机体	组合分子 + 原子	Header = Logo + 导航项 + 用户菜单
模板	布局结构，无实际内容	DashboardLayout
页面	模板 + 真实内容	Dashboard

Core Rules

核心规则

1. Props = Content Only

1. 仅传递内容相关Props

typescript

// Correct
interface ButtonProps {
  children: ReactNode;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
}

// Wrong - Visual props exposed
interface ButtonProps {
  backgroundColor?: string;  // NO
  fontSize?: string;         // NO
}

typescript

// Correct
interface ButtonProps {
  children: ReactNode;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
}

// Wrong - Visual props exposed
interface ButtonProps {
  backgroundColor?: string;  // NO
  fontSize?: string;         // NO
}

2. All Styles Encapsulated

2. 所有样式封装

css

.button {
  background: var(--color-primary);
  padding: var(--spacing-button-padding-y) var(--spacing-button-padding-x);
  font-size: var(--font-size-button);
}

css

.button {
  background: var(--color-primary);
  padding: var(--spacing-button-padding-y) var(--spacing-button-padding-x);
  font-size: var(--font-size-button);
}

3. Responsive Built-In

3. 内置响应式支持

css

.card { padding: var(--spacing-4); }  /* Mobile */
@media (min-width: 768px) { .card { padding: var(--spacing-6); } }  /* Tablet */
@media (min-width: 1024px) { .card { padding: var(--spacing-8); } } /* Desktop */

css

.card { padding: var(--spacing-4); }  /* Mobile */
@media (min-width: 768px) { .card { padding: var(--spacing-6); } }  /* Tablet */
@media (min-width: 1024px) { .card { padding: var(--spacing-8); } } /* Desktop */

4. Accessibility Required

4. 必须满足无障碍要求

tsx

<button
  aria-label={iconOnly ? label : undefined}
  aria-busy={loading}
  aria-disabled={disabled}
>

tsx

<button
  aria-label={iconOnly ? label : undefined}
  aria-busy={loading}
  aria-disabled={disabled}
>

Workflow: Create New Component

交付前检查清单

Step 0: Extract from Figma (Mandatory)

—

Step 1: Classify Level

参考文档

Is component breakable into smaller parts?
  No  -> ATOM
  Yes -> What does it compose?
    Only Atoms      -> MOLECULE
    Molecules+Atoms -> ORGANISM

文件	阅读场景
tokens/*.json	需要特定令牌值时
references/figma-design-fidelity.md	Figma提取指南
references/design-deviation-rules.md	零偏差原则
references/atomic-hierarchy.md	组件示例
references/component-templates.md	可复制粘贴的模板
references/responsive-patterns.md	响应式模式

Step 2: Create Files

—

src/design-system/atoms/Button/
  Button.tsx          # Component + Props
  Button.module.css   # All styles (tokens only)
  Button.test.tsx     # Tests
  index.ts            # Export

—

Step 3: Implement Pattern

—

tsx

/**
 * @figma https://figma.com/file/xxx/Design-System?node-id=123
 * @extracted 2024-01-15
 * All values from Figma - DO NOT MODIFY without designer approval.
 */
import styles from './Button.module.css';

interface ButtonProps {
  children: ReactNode;
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  onClick?: () => void;
}

export const Button = ({ children, variant = 'primary', size = 'md', disabled, onClick }: ButtonProps) => (
  <button className={clsx(styles.button, styles[variant], styles[size])} disabled={disabled} onClick={onClick}>
    {children}
  </button>
);

—

Checklist Before Delivery

—

References

—

File	When to Read
tokens/*.json	Need specific token values
references/figma-design-fidelity.md	Figma extraction guide
references/design-deviation-rules.md	Zero deviation policy
references/atomic-hierarchy.md	Component examples
references/component-templates.md	Copy-paste templates
references/responsive-patterns.md	Responsive patterns

—