---
id: wiki-2026-0508-component-library-architecture
title: Component Library Architecture
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Design System Architecture, UI Library Design]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [components, design-system, react, shadcn, radix]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: react-radix-shadcn
---

# Component Library Architecture

## 매 한 줄
> **"매 unstyled headless primitives + 매 style layer + 매 composition API."**. 2026년 React component library 의 dominant model = Radix/Ark UI (headless behavior + a11y) + Tailwind/CSS variables (theming) + shadcn/ui (copy-not-install) + tokens (DTCG). MUI 5 의 monolithic theme 시대 → headless 시대로 매 shift.

## 매 핵심

### 매 3 layer architecture
1. **Behavior layer (headless)**: a11y, keyboard, focus, ARIA — Radix, Ark UI, React Aria.
2. **Style layer**: Tailwind, CSS-in-JS (vanilla-extract), CSS variables.
3. **Composition layer**: app-specific compositions of 1+2.

### 매 distribution model
- **Package install** (MUI, Chakra v3): npm install, version locked, hard to customize.
- **Copy-paste** (shadcn/ui): generator copies source into your repo, you own it, fully customizable.
- **Hybrid** (Radix + custom wrapper): primitives via npm, your styles in repo.

### 매 token system (DTCG / Style Dictionary)
- Primitive tokens (color.blue.500 = #3b82f6).
- Semantic tokens (color.action.primary = color.blue.500).
- Component tokens (button.bg.primary = color.action.primary).

### 매 응용
1. Internal design system (Vercel Geist, GitHub Primer).
2. Open-source kits (shadcn/ui, Mantine, Park UI).
3. White-label products (multi-brand 동일 codebase).
4. Cross-framework via Web Components (Spectrum Web Components).

## 💻 패턴

### Headless primitive (Radix)
```typescript
import * as Dialog from '@radix-ui/react-dialog';

export function ConfirmDialog({ open, onClose, onConfirm, children }: Props) {
  return (
    <Dialog.Root open={open} onOpenChange={onClose}>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
          <Dialog.Title className="text-lg font-semibold">Confirm</Dialog.Title>
          <Dialog.Description>{children}</Dialog.Description>
          <div className="mt-4 flex justify-end gap-2">
            <Dialog.Close className="btn-ghost">Cancel</Dialog.Close>
            <button className="btn-primary" onClick={onConfirm}>OK</button>
          </div>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

### shadcn-style copy-paste component
```typescript
// components/ui/button.tsx — owned by your repo
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium transition',
  {
    variants: {
      variant: {
        primary: 'bg-blue-600 text-white hover:bg-blue-700',
        ghost: 'hover:bg-gray-100',
      },
      size: {
        sm: 'h-8 px-3',
        md: 'h-10 px-4',
        lg: 'h-12 px-6',
      },
    },
    defaultVariants: { variant: 'primary', size: 'md' },
  },
);

type Props = React.ButtonHTMLAttributes<HTMLButtonElement>
  & VariantProps<typeof buttonVariants>;

export function Button({ className, variant, size, ...rest }: Props) {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      {...rest}
    />
  );
}
```

### Design tokens (DTCG JSON)
```json
{
  "color": {
    "blue": {
      "500": { "$value": "#3b82f6", "$type": "color" }
    },
    "action": {
      "primary": { "$value": "{color.blue.500}", "$type": "color" }
    }
  },
  "space": {
    "4": { "$value": "16px", "$type": "dimension" }
  }
}
```

### CSS variables driven theming
```css
:root {
  --color-primary: #3b82f6;
  --radius-md: 0.5rem;
}

[data-theme='dark'] {
  --color-primary: #60a5fa;
}

.btn-primary {
  background: var(--color-primary);
  border-radius: var(--radius-md);
}
```

### Polymorphic component (asChild pattern)
```typescript
import { Slot } from '@radix-ui/react-slot';

type Props = {
  asChild?: boolean;
} & React.HTMLAttributes<HTMLElement>;

export function Card({ asChild, ...rest }: Props) {
  const Comp = asChild ? Slot : 'div';
  return <Comp className="rounded-lg border p-4" {...rest} />;
}

// Usage:
<Card asChild>
  <a href="/post/1">Click me</a>
</Card>
```

### Storybook 8 + a11y addon
```typescript
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './button';

const meta: Meta<typeof Button> = {
  component: Button,
  parameters: { a11y: { test: 'error' } },
};
export default meta;

export const Primary: StoryObj<typeof Button> = {
  args: { children: 'Save', variant: 'primary' },
};
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Internal design system, full control | shadcn/ui copy-paste + Tailwind |
| Quick prototype, full kit | Mantine, Chakra v3 |
| Cross-framework | Lit + Web Components |
| Strong a11y 요구 | Radix or React Aria |
| Multi-brand white-label | Token-driven CSS variables |

**기본값**: React 19 + Radix primitives + Tailwind v4 + shadcn/ui structure + DTCG tokens.

## 🔗 Graph
- 부모: [[Component-Based Architecture (CBA)]] · [[Design Systems]]
- 변형: [[Component-Composition|Compound Components]] · [[Headless UI]]
- 응용: [[shadcn-ui]] · [[Radix UI]] · [[Storybook]]
- Adjacent: [[CSS_Architecture_and_Styling|Tailwind CSS]] · [[Design Tokens]] · [[A11y]]

## 🤖 LLM 활용
**언제**: starting design system, refactoring 중복 UI, multi-product/brand consolidation.
**언제 X**: 1-page landing site (overhead 큼), heavily 3D/canvas UI (HTML primitive 안 맞음).

## ❌ 안티패턴
- **Tightly styled primitives**: behavior + style 의 강결합 — replace 시 rewrite 필요.
- **Theme prop drilling**: 매 component 가 theme prop 받음 — CSS variables 로.
- **No tokens**: hex color 직접 사용 — token system 부재 시 multi-brand 불가.
- **Locked-in vendor library**: MUI v3→v5 같은 대규모 breaking change — headless + own styles 가 안전.

## 🧪 검증 / 중복
- Verified (shadcn/ui docs 2026 / Radix UI / DTCG W3C draft / React 19 docs).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — 3-layer model + shadcn/Radix/DTCG 패턴 |