name: atomic-design-fundamentals user-invocable: false description: 当应用Atomic Design方法论来组织UI组件为夸克、原子、分子、有机体、模板和页面时使用。核心原则和层级结构。 allowed-tools:

Bash
Read
Write
Edit
Glob
Grep

原子设计基础

掌握Brad Frost的Atomic Design方法论（扩展了夸克），用于构建可扩展、可维护的基于组件的用户界面。此技能涵盖了现代设计系统的核心层级、原则和组织策略。

概述

Atomic Design是一种受化学启发的设计系统创建方法。正如原子结合形成分子，分子结合形成有机体，UI组件遵循类似的层级结构。我们使用夸克（设计令牌的子原子级）扩展此结构：

夸克 - 设计令牌（颜色、间距、排版比例、阴影）
原子 - 基本构建块（按钮、输入框、标签）
分子 - 原子组协同工作（搜索表单、卡片）
有机体 - 复杂的UI部分（页眉、页脚、侧边栏）
模板 - 页面级布局，无实际内容
页面 - 模板填充实际代表内容

六个阶段

0. 夸克

子原子级构建块——设计令牌和原始值，供原子使用。夸克本身不是UI组件；它们是定义设计语言的原始值。

示例：

颜色令牌（primary-500, neutral-100）
间距比例（4px, 8px, 16px）
排版令牌（字体大小、粗细、行高）
边框半径
阴影定义
动画时长和缓动函数
断点

特点：

纯值，非视觉组件
不能从其他级别导入
定义设计语言
启用主题和一致性
设计决策的单一来源

1. 原子

界面的最小功能UI单元。原子使用夸克进行样式设计，但不能进一步分解而不失去意义。

示例：

按钮
输入字段
标签
图标
排版元素（标题、段落）
颜色样本
头像

特点：

自包含和独立
无业务逻辑
高度可重用
接受样式属性
尽可能框架无关

2. 分子

原子组合作为单元协同工作。分子有单一责任，但由多个原子组成。

示例：

搜索表单（输入框 + 按钮）
表单字段（标签 + 输入框 + 错误消息）
媒体对象（头像 + 文本）
卡片标题（图标 + 标题 + 操作按钮）
导航链接（图标 + 文本）

特点：

仅由原子组成
单一目的或功能
跨上下文可重用
可能有最小内部状态

3. 有机体

界面的复杂、独立部分。有机体代表可独立存在的不同部分。

示例：

页眉（logo + 导航 + 用户菜单）
页脚（链接 + 社交图标 + 版权）
产品卡片（图片 + 标题 + 价格 + 加入购物车）
评论部分（头像 + 内容 + 操作）
侧边栏导航

特点：

由分子和原子组成
代表不同UI部分
可能包含业务逻辑
上下文特定但可重用

4. 模板

页面级布局，定义内容结构而无实际内容。模板展示页面的骨架结构。

示例：

博客文章模板（页眉 + 内容区域 + 侧边栏 + 页脚）
仪表板布局（导航 + 主要内容 + 小部件）
产品页面布局（画廊 + 详情 + 相关产品）
落地页结构

特点：

由有机体组成
定义页面结构
使用占位内容
建立内容层级

5. 页面

模板的具体实例，填充实际、代表内容。页面是用户实际看到和交互的。

示例：

具有实际英雄内容的主页
带有真实产品数据的详情页
带有实际用户信息的用户资料
带有真实文章内容的博客文章

特点：

模板填充真实内容
代表实际用户体验
用于测试和验证
可能揭示设计问题

目录结构

标准结构

src/
  quarks/                    # 设计令牌
    index.ts
    colors.ts
    spacing.ts
    typography.ts
    shadows.ts
    borders.ts
  components/
    atoms/
      Button/
        Button.tsx
        Button.test.tsx
        Button.stories.tsx
        index.ts
      Input/
      Label/
      Icon/
    molecules/
      SearchForm/
      FormField/
      Card/
    organisms/
      Header/
      Footer/
      ProductCard/
    templates/
      MainLayout/
      DashboardLayout/
    pages/
      HomePage/
      ProductPage/

替代扁平结构

src/
  quarks/
    colors.ts
    spacing.ts
    typography.ts
  components/
    atoms/
      Button.tsx
      Input.tsx
      Label.tsx
    molecules/
      SearchForm.tsx
      FormField.tsx
    organisms/
      Header.tsx
      Footer.tsx
    templates/
      MainLayout.tsx
    pages/
      HomePage.tsx

基于功能的混合结构

src/
  quarks/                    # 共享设计令牌
    index.ts
    colors.ts
    spacing.ts
  features/
    products/
      components/
        atoms/
        molecules/
        organisms/
      templates/
      pages/
    checkout/
      components/
        atoms/
        molecules/
        organisms/
  shared/
    components/
      atoms/
      molecules/

组件命名约定

文件命名

# PascalCase用于组件文件
Button.tsx
SearchForm.tsx
ProductCard.tsx

# Index文件用于清洁导入
index.ts

# 测试文件
Button.test.tsx
Button.spec.tsx

# 故事文件（Storybook）
Button.stories.tsx

组件命名

// 原子 - 简单、描述性名称
Button
Input
Label
Avatar
Icon

// 分子 - 动作或组合为基础的名称
SearchForm
FormField
MediaObject
NavItem

// 有机体 - 部分或功能为基础的名称
Header
Footer
ProductCard
CommentSection
UserProfile

// 模板 - 布局焦点名称
MainLayout
DashboardLayout
AuthLayout

// 页面 - 页面特定名称
HomePage
ProductDetailPage
CheckoutPage

导入模式

桶导出

// src/components/atoms/index.ts
export { Button } from './Button';
export { Input } from './Input';
export { Label } from './Label';
export { Icon } from './Icon';

// src/components/molecules/index.ts
export { SearchForm } from './SearchForm';
export { FormField } from './FormField';

// src/components/index.ts
export * from './atoms';
export * from './molecules';
export * from './organisms';

使用

// 从桶文件清洁导入
import { Button, Input, Label } from '@/components/atoms';
import { SearchForm, FormField } from '@/components/molecules';
import { Header, Footer } from '@/components/organisms';

// 或从统一桶导入
import { Button, SearchForm, Header } from '@/components';

组合规则

严格层级

夸克     -> 使用方：原子、分子、有机体、模板、页面
原子      -> 使用方：分子、有机体、模板、页面
分子      -> 使用方：有机体、模板、页面
有机体    -> 使用方：模板、页面
模板      -> 使用方：页面
页面      -> 不被其他组件使用

有效组合

// 原子使用夸克进行样式设计
import { colors, spacing } from '@/quarks';

const Button = styled.button`
  background: ${colors.primary[500]};  {/* 夸克 */}
  padding: ${spacing.md};              {/* 夸克 */}
`;

// 分子仅使用原子
const SearchForm = () => (
  <form>
    <Input placeholder="搜索..." />  {/* 原子 */}
    <Button>搜索</Button>            {/* 原子 */}
  </form>
);

// 有机体使用分子和原子
const Header = () => (
  <header>
    <Logo />                           {/* 原子 */}
    <Navigation />                     {/* 分子 */}
    <SearchForm />                     {/* 分子 */}
    <UserMenu />                       {/* 分子 */}
  </header>
);

// 模板使用有机体
const MainLayout = ({ children }) => (
  <div>
    <Header />                         {/* 有机体 */}
    <main>{children}</main>
    <Footer />                         {/* 有机体 */}
  </div>
);

无效组合（反模式）

// 错误：原子从分子导入
// atoms/Button.tsx
import { FormField } from '../molecules'; // 错误！

// 错误：分子从有机体导入
// molecules/SearchForm.tsx
import { Header } from '../organisms'; // 错误！

// 错误：无理由跳过级别
// organisms/Header.tsx
import { MainLayout } from '../templates'; // 错误！

设计令牌集成

令牌结构

// design-tokens/colors.ts
export const colors = {
  primary: {
    50: '#e3f2fd',
    100: '#bbdefb',
    500: '#2196f3',
    900: '#0d47a1',
  },
  neutral: {
    0: '#ffffff',
    100: '#f5f5f5',
    900: '#212121',
  },
};

// design-tokens/spacing.ts
export const spacing = {
  xs: '4px',
  sm: '8px',
  md: '16px',
  lg: '24px',
  xl: '32px',
};

// design-tokens/typography.ts
export const typography = {
  fontFamily: {
    sans: 'Inter, system-ui, sans-serif',
    mono: 'Fira Code, monospace',
  },
  fontSize: {
    xs: '12px',
    sm: '14px',
    base: '16px',
    lg: '18px',
    xl: '24px',
  },
};

在原子中使用令牌

import { colors, spacing, typography } from '@/design-tokens';

const Button = styled.button`
  background-color: ${colors.primary[500]};
  padding: ${spacing.sm} ${spacing.md};
  font-family: ${typography.fontFamily.sans};
  font-size: ${typography.fontSize.base};
`;

最佳实践

1. 从原子开始

从下向上构建设计系统：

// 1. 先定义核心原子
const Button = ({ variant, size, children }) => { ... };
const Input = ({ type, placeholder }) => { ... };
const Label = ({ htmlFor, children }) => { ... };

// 2. 组合成分子
const FormField = ({ label, ...inputProps }) => (
  <div>
    <Label>{label}</Label>
    <Input {...inputProps} />
  </div>
);

// 3. 从分子构建有机体
const LoginForm = () => (
  <form>
    <FormField label="邮箱" type="email" />
    <FormField label="密码" type="password" />
    <Button>登录</Button>
  </form>
);

2. 属性向下流动

// 原子接收原始属性
interface ButtonProps {
  variant: 'primary' | 'secondary';
  size: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

// 分子通过展开接收原子属性
interface SearchFormProps {
  onSubmit: (query: string) => void;
  inputProps?: Partial<InputProps>;
  buttonProps?: Partial<ButtonProps>;
}

// 有机体接收领域特定属性
interface HeaderProps {
  user?: User;
  onLogout: () => void;
  navigation: NavItem[];
}

3. 避免原子中的业务逻辑

// 错误：原子包含业务逻辑
const PriceButton = ({ productId }) => {
  const price = useProductPrice(productId); // 错误！
  return <Button>${price}</Button>;
};

// 正确：原子接收处理后的数据
const PriceButton = ({ price, onClick }) => (
  <Button onClick={onClick}>${price}</Button>
);

// 业务逻辑存在于有机体或更高层级
const ProductCard = ({ productId }) => {
  const { price } = useProduct(productId);
  return <PriceButton price={price} onClick={handleBuy} />;
};

4. 记录组件用途

/**
 * 按钮 - 用于用户操作的原子组件
 *
 * @level 原子
 * @example
 * <Button variant="primary" size="md">点击我</Button>
 */
export const Button: React.FC<ButtonProps> = ({ ... }) => { ... };

/**
 * 搜索表单 - 带提交按钮的搜索输入
 *
 * @level 分子
 * @composition 输入框, 按钮
 * @example
 * <SearchForm onSubmit={(query) => search(query)} />
 */
export const SearchForm: React.FC<SearchFormProps> = ({ ... }) => { ... };

常见陷阱

1. 过度原子化

// 错误：过于细粒度 - 不必要的原子
const ButtonText = ({ children }) => <span>{children}</span>;
const ButtonContainer = ({ children }) => <div>{children}</div>;

// 正确：适当粒度
const Button = ({ children }) => (
  <button className="btn">{children}</button>
);

2. 不足原子化

// 错误：一个组件中包含太多内容
const MegaForm = () => (
  <form>
    <div><label>姓名</label><input /></div>
    <div><label>邮箱</label><input /></div>
    <div><label>消息</label><textarea /></div>
    <button>提交</button>
  </form>
);

// 正确：适当分解
const ContactForm = () => (
  <form>
    <FormField label="姓名" type="text" />
    <FormField label="邮箱" type="email" />
    <TextAreaField label="消息" />
    <Button type="submit">提交</Button>
  </form>
);

3. 循环依赖

// 错误：原子从分子导入
// atoms/Icon.tsx
import { IconButton } from '../molecules'; // 创建循环依赖！

// 正确：保持导入向下流动
// molecules/IconButton.tsx
import { Icon } from '../atoms';
import { Button } from '../atoms';

4. 命名不一致

// 错误：命名模式不一致
atoms/btn.tsx
atoms/InputField.tsx
atoms/text-label.tsx

// 正确：一致PascalCase
atoms/Button.tsx
atoms/Input.tsx
atoms/Label.tsx

何时使用此技能

设置新设计系统
组织现有组件库
让团队成员熟悉原子设计
审计组件结构
规划组件架构
创建设计系统文档
重构单体组件

原子设计基础

概述

六个阶段

0. 夸克

1. 原子

2. 分子

3. 有机体

4. 模板

5. 页面

目录结构

标准结构

替代扁平结构

基于功能的混合结构

组件命名约定

文件命名

组件命名

导入模式

桶导出

使用

组合规则

严格层级

有效组合

无效组合（反模式）

设计令牌集成

令牌结构

在原子中使用令牌

最佳实践

1. 从原子开始

2. 属性向下流动

3. 避免原子中的业务逻辑

4. 记录组件用途

常见陷阱

1. 过度原子化

2. 不足原子化

3. 循环依赖

4. 命名不一致

何时使用此技能

相关技能

资源

文档

书籍

工具