SuperAPI AI Directory

component-architecture

General & other

View repository

Updated 10-16 09:30

About this skill

Component Architecture

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. 单一职责
   一个组件做一件事
  1. Explicit props, avoid prop drilling More than 3 levels of passing down → use Context / state management

  2. Composition over Configuration <Card><Card.Header /></Card> is better than <Card title="..." footer="..." actions={[...]} />

  3. Data flows top-down, events flow bottom-up Unidirectional data flow

  4. Designing the API matters more than the internal implementation The API is a contract; you can change the implementation but not the API

  5. Controlled vs uncontrolled must be clear Form components provide both modes

  6. Accessibility by default Not an afterthought (see a11y skill for details)

  7. 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

  1. prop drilling 5+ levels——use Context / state library
  2. God Component——a single component of 1000 lines
  3. State at the wrong level——used by child components but placed at the very top
  4. useState initialization is a synchronous function——repeated execution
  5. useEffect syncing props to state——use props directly
  6. server state in Redux——use TanStack Query
  7. No Storybook——no way to do visual regression
  8. Directly modifying component library source code——upgrade hell
  9. Abusing forwardRef / memo——over-optimization
  10. Not distinguishing controlled / uncontrolled——confusing usage
  11. Container writing UI details——breaks layering
  12. Dogmatic Atomic Design——forcing five layers is impractical
  13. a11y as an afterthought——huge refactoring cost
  14. 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