References: Brad Frost "Atomic Design", Dan Abramov "Presentational and Container Components", Kent C. Dodds "Compound Components", Adam Wathan "Inversion of Control".
Applicable Scenarios
- Designing component trees and split granularity
- Improving reuse rate / building design systems
- Component API design
- Component state encapsulation strategy
- React / Vue / Angular / Svelte framework paradigms
Core Principles
1. 单一职责
一个组件做一件事
-
Explicit props, avoid prop drilling More than 3 levels of passing down → use Context / state management
-
Composition over Configuration
<Card><Card.Header /></Card>is better than<Card title="..." footer="..." actions={[...]} /> -
Data flows top-down, events flow bottom-up Unidirectional data flow
-
Designing the API matters more than the internal implementation The API is a contract; you can change the implementation but not the API
-
Controlled vs uncontrolled must be clear Form components provide both modes
-
Accessibility by default Not an afterthought (see a11y skill for details)
-
Minimize state If it can be derived from props, don't store it as state
## Atomic Design 五层
```text
┌─────────────────────────────────────┐
│ Pages(页面) │
│ 例:UserProfilePage / OrderListPage │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ Templates(模板) │
│ 例:DashboardLayout / AuthLayout │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ Organisms(生物体) │
│ 例:Header / Sidebar / OrderList │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ Molecules(分子) │
│ 例:FormField / SearchBar / UserCard │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ Atoms(原子) │
│ 例:Button / Input / Icon / Label │
└─────────────────────────────────────┘
Container / Presentation Pattern
Container(容器):
- 管理状态 / 调用 API / 业务逻辑
- 不写 UI 细节
- 命名:UserListContainer
Presentation(展示):
- 纯 UI / 无状态(或仅 UI 状态)
- 接收 props,emit 事件
- 易测试 / 易复用 / Storybook 友好
- 命名:UserList
// Presentation:纯 UI
interface UserListProps {
users: User[];
isLoading: boolean;
onUserClick: (id: number) => void;
}
export function UserList({ users, isLoading, onUserClick }: UserListProps) {
if (isLoading) return <Skeleton count={5} />;
if (users.length === 0) return <EmptyState />;
return (
<ul>
{users.map(user => (
<li key={user.id} onClick={() => onUserClick(user.id)}>
{user.name}
</li>
))}
</ul>
);
}
// Container:业务逻辑
export function UserListContainer() {
const { data, isLoading } = useQuery({ queryKey: ['users'], queryFn: fetchUsers });
const navigate = useNavigate();
return (
<UserList
users={data ?? []}
isLoading={isLoading}
onUserClick={(id) => navigate(`/users/${id}`)}
/>
);
}
Compound Components Pattern
// 用法(用户写)
<Tabs defaultValue="orders">
<Tabs.List>
<Tabs.Trigger value="orders">订单</Tabs.Trigger>
<Tabs.Trigger value="products">商品</Tabs.Trigger>
</Tabs.List>
<Tabs.Panel value="orders"><OrderList /></Tabs.Panel>
<Tabs.Panel value="products"><ProductList /></Tabs.Panel>
</Tabs>
// 实现:用 Context 共享状态
const TabsContext = createContext<TabsContextValue | null>(null);
export function Tabs({ children, defaultValue }: TabsProps) {
const [value, setValue] = useState(defaultValue);
return (
<TabsContext.Provider value={{ value, setValue }}>
<div data-tabs>{children}</div>
</TabsContext.Provider>
);
}
Tabs.List = function TabsList({ children }) {
return <div role="tablist">{children}</div>;
};
Tabs.Trigger = function TabsTrigger({ value, children }) {
const ctx = useContext(TabsContext);
return (
<button
role="tab"
aria-selected={ctx.value === value}
onClick={() => ctx.setValue(value)}
>
{children}
</button>
);
};
Tabs.Panel = function TabsPanel({ value, children }) {
const ctx = useContext(TabsContext);
return ctx.value === value ? <div role="tabpanel">{children}</div> : null;
}
Headless Pattern
不提供样式,只提供逻辑和无障碍:
- Radix UI(React)
- Headless UI(React/Vue)
- React Aria
- Melt UI(Svelte)
- Bits UI(Svelte)
- Kobalte(Solid)
优势:
- 100% 自定义样式
- 无障碍由库保证
- 不与设计系统冲突
劣势:
- 需要自己写样式
- 学习曲线
// 用 Radix Dialog
import * as Dialog from '@radix-ui/react-dialog';
export function ConfirmDialog({ children, onConfirm }) {
return (
<Dialog.Root>
<Dialog.Trigger asChild>{children}</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay className="overlay" />
<Dialog.Content className="content">
<Dialog.Title>确认</Dialog.Title>
<Dialog.Description>...</Dialog.Description>
<button onClick={onConfirm}>确认</button>
<Dialog.Close>取消</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
React Component Paradigm
// 1. 函数组件(推荐)
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
variant?: 'primary' | 'secondary' | 'danger';
size?: 'sm' | 'md' | 'lg';
isLoading?: boolean;
}
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
({ variant = 'primary', size = 'md', isLoading, children, className, ...props }, ref) => {
return (
<button
ref={ref}
className={cn(buttonVariants({ variant, size }), className)}
disabled={isLoading || props.disabled}
{...props}
>
{isLoading && <Spinner />}
{children}
</button>
);
}
);
Button.displayName = 'Button';
// 2. 自定义 Hook 抽逻辑
function useUserList() {
const [filter, setFilter] = useState('');
const { data, isLoading } = useQuery({
queryKey: ['users', filter],
queryFn: () => fetchUsers({ filter }),
});
return { users: data ?? [], isLoading, filter, setFilter };
}
// 3. memo 避免不必要重渲染(仅当真有性能问题)
export const ExpensiveItem = memo(function ExpensiveItem({ item }) {
return <div>...</div>;
});
Vue 3 Component Paradigm
<!-- Button.vue -->
<script setup lang="ts">
interface Props {
variant?: 'primary' | 'secondary' | 'danger';
size?: 'sm' | 'md' | 'lg';
isLoading?: boolean;
disabled?: boolean;
}
const props = withDefaults(defineProps<Props>(), {
variant: 'primary',
size: 'md',
});
const emit = defineEmits<{
click: [event: MouseEvent];
}>();
</script>
<template>
<button
:class="['btn', `btn-${variant}`, `btn-${size}`]"
:disabled="isLoading || disabled"
@click="emit('click', $event)"
>
<Spinner v-if="isLoading" />
<slot />
</button>
</template>
<!-- 组合式函数(Composables,Vue 的 Hook)-->
<script setup lang="ts">
import { useUserList } from '@/composables/useUserList';
const { users, isLoading, filter } = useUserList();
</script>
<!-- composables/useUserList.ts -->
<script lang="ts">
import { ref, computed } from 'vue';
import { useQuery } from '@tanstack/vue-query';
export function useUserList() {
const filter = ref('');
const { data, isLoading } = useQuery({
queryKey: ['users', filter],
queryFn: () => fetchUsers({ filter: filter.value }),
});
return {
users: computed(() => data.value ?? []),
isLoading,
filter,
};
}
</script>
Angular Component Paradigm
// button.component.ts
@Component({
selector: 'app-button',
standalone: true,
imports: [CommonModule],
template: `
<button
[class]="'btn btn-' + variant() + ' btn-' + size()"
[disabled]="isLoading() || disabled()"
(click)="onClick.emit($event)"
>
<app-spinner *ngIf="isLoading()" />
<ng-content />
</button>
`,
})
export class ButtonComponent {
variant = input<'primary' | 'secondary'>('primary');
size = input<'sm' | 'md' | 'lg'>('md');
isLoading = input(false);
disabled = input(false);
onClick = output<MouseEvent>();
}
Svelte 5 Component Paradigm
<!-- Button.svelte -->
<script lang="ts">
interface Props {
variant?: 'primary' | 'secondary' | 'danger';
size?: 'sm' | 'md' | 'lg';
isLoading?: boolean;
onclick?: (e: MouseEvent) => void;
children: any;
}
let {
variant = 'primary',
size = 'md',
isLoading = false,
onclick,
children,
}: Props = $props();
</script>
<button class="btn btn-{variant} btn-{size}" disabled={isLoading} {onclick}>
{#if isLoading}<Spinner />{/if}
{@render children()}
</button>
Component Directory Structure
推荐:feature-based + 共享组件分离
src/
├── components/ ← 跨业务的通用组件
│ ├── ui/ ← 原子组件(Button, Input, Card)
│ ├── layout/ ← 布局组件
│ └── feedback/ ← Toast, Modal, Skeleton
├── features/ ← 业务模块(领域驱动)
│ ├── orders/
│ │ ├── components/ ← 仅订单用到的组件
│ │ ├── hooks/ ← useOrder, useOrderList
│ │ ├── api/ ← API 调用
│ │ ├── types.ts
│ │ └── OrderListPage.tsx
│ └── products/
│ └── ...
├── pages/ ← 路由页面(薄)
├── lib/ ← 工具函数
└── App.tsx
Component API Design
1. Props 命名
- 布尔:is/has/can 前缀
- 事件:on 前缀(onClick / onSubmit)
- 字符串枚举:明确选项(variant: 'primary' | 'secondary')
2. 默认值
- 提供合理默认
- 不要全部 required
3. 受控 vs 非受控
提供两种模式:
<Input value={x} onChange={fn} /> // 受控
<Input defaultValue="x" /> // 非受控
4. forwardRef
原子组件应该转发 ref
5. ...rest props
原子组件应允许传递 HTML 属性
<Button {...props} />
State Encapsulation Principles
状态从上往下放:
局部 state(一个组件用) → useState 在该组件
父子共享 → 提到父组件
跨组件 → Context / 状态管理库
服务端数据 → TanStack Query / SWR
不要:
- useState 然后只 setState 一次(用 props)
- useEffect 同步 props 到 state(直接用 props)
- 把 server state 放 Redux(用 React Query)
Workflow
1. 看设计稿 → 拆分 Atomic Design 五层
↓
2. 列原子组件清单(Button / Input / Icon ...)
↓
3. 看是否复用现有组件库(不要重造轮子)
↓
4. 组件 API 设计(先 README 再写代码)
↓
5. 实现 + Storybook story
↓
6. 单元测试 + 集成测试 + 视觉测试
↓
7. 检查 a11y(键盘 + 屏幕阅读器)
↓
8. 性能(memo 必要时 / 懒加载)
↓
9. 文档(API + 用法示例)
Supporting Templates
templates/component-design-template.md— component design document (API + state + reuse + testing + a11y)
Quality Self-Check
□ 单一职责(一个组件做一件事)
□ Props 类型完整(TypeScript)
□ 默认值合理
□ 受控 / 非受控明确
□ forwardRef(原子组件)
□ ...rest 透传
□ a11y 完整(角色 / 键盘 / 屏幕阅读器)
□ 状态最小化
□ 命名清晰
□ Storybook story 覆盖主要状态
□ 测试覆盖
□ 不深嵌套(< 3 层 prop drilling)
□ 不滥用 memo / useCallback
□ Loading / Empty / Error 状态完整
Common Pitfalls
- prop drilling 5+ levels——use Context / state library
- God Component——a single component of 1000 lines
- State at the wrong level——used by child components but placed at the very top
- useState initialization is a synchronous function——repeated execution
- useEffect syncing props to state——use props directly
- server state in Redux——use TanStack Query
- No Storybook——no way to do visual regression
- Directly modifying component library source code——upgrade hell
- Abusing forwardRef / memo——over-optimization
- Not distinguishing controlled / uncontrolled——confusing usage
- Container writing UI details——breaks layering
- Dogmatic Atomic Design——forcing five layers is impractical
- a11y as an afterthought——huge refactoring cost
- Components not documented——team reinvents each on their own
Collaboration with Other Skills
上游:
ui-ux-designer 工作流 → 设计稿 / 状态 / 流程
api-designer → API 契约(影响数据组件)
下游:
state-management → 全局状态
styling-system → 样式
forms-validation → 表单组件
data-fetching → 数据组件
testing-frontend → 测试覆盖
accessibility-implementation → a11y 实现
Related References
- Project root
references/frontend-component-libraries.md— component library selection - Project root
references/frontend-frameworks-2026.md— framework comparison - ui-ux-designer workflow atomic-design / component-states skill