refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,216 @@
|
||||
---
|
||||
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 패턴 |
|
||||
Reference in New Issue
Block a user