프롬프트 인터페이스
When to/NOT to Use, Props 테이블, Minimal→Complex 예시 중심의 컴포넌트 문서 포맷과 JSON 메타데이터·MCP 서버로 AI가 정확한 컴포넌트를 선택하게 하는 문서화 전략.
핵심 요약
- 프롬프트 친화적 문서는 구조화·명시성·예시 중심·관계성을 갖춰야 AI가 컴포넌트를 제대로 골라 조합합니다.
- 컴포넌트 문서는 Summary, When to Use / When NOT to Use(대안 명시), Props(Required/Optional), Variants, Examples(Minimal→Complex), Accessibility, Related로 구성합니다.
- 예시는 바로 복사해 쓸 수 있어야 하고, 최소·기본 변형·조합·엣지 케이스를 골고루 제공합니다.
- DESIGN.md(화면/브랜드), component docs(컴포넌트), token docs(값)는 AI가 던지는 질문이 서로 달라, 셋을 함께 운영해야 화면 분위기와 UI 조합이 둘 다 흔들리지 않습니다.
- JSON 메타데이터와 MCP 서버(get_component·find_component·get_token)로 컨텍스트를 노출하고, Figma·Storybook·Panda CSS·shadcn/skills MCP로 디자인-코드 통합을 자동화합니다.
AI 에이전트는 프롬프트로 받은 컨텍스트를 바탕으로 코드를 만듭니다. 디자인 시스템 문서를 프롬프트 친화적으로 구조화해야 AI가 맞는 컴포넌트를 고르고 알맞게 조합합니다.
프롬프트 친화적 문서의 특징
컴포넌트 문서 구조
AI 최적화 문서 포맷
# {ComponentName}
## Summary
{1-2문장 요약. AI가 컴포넌트 선택 시 참조}
## When to Use
- {유스케이스 1}
- {유스케이스 2}
## When NOT to Use
- {안티패턴 1} → Use {대안}
- {안티패턴 2} → Use {대안}
## Props
### Required
| Prop | Type | Description |
| ------ | ------ | ----------- |
| {prop} | {type} | {설명} |
### Optional
| Prop | Type | Default | Description |
| ------ | ------ | --------- | ----------- |
| {prop} | {type} | {default} | {설명} |
## Variants
| Variant | When to Use | Visual |
| ------- | ----------- | ------ |
| {name} | {용도} | {설명} |
## Examples
### Minimal
\`\`\`tsx
<Component prop="value">Content</Component>
\`\`\`
### With Options
\`\`\`tsx
<Component variant="secondary" size="large" disabled={false}>
Content
</Component>
\`\`\`
## Composition
{다른 컴포넌트와 조합 패턴}
## Accessibility
- {ARIA 요구사항}
- {키보드 패턴}
## Related
- `{AlternativeComponent}`: {언제 대신 사용}
- `{ComposedComponent}`: {함께 사용하는 패턴}실제 예시: Button 문서
# Button
## Summary
사용자 액션을 트리거하는 클릭 가능한 요소.
폼 제출, 대화상자 확인, 액션 실행에 사용.
## When to Use
- 폼 제출 (`type="submit"`)
- 대화상자 내 확인/취소 액션
- 즉시 실행되는 액션 (삭제, 저장 등)
## When NOT to Use
- 다른 페이지로 이동 → Use `Link`
- 토글 상태 전환 → Use `Toggle` or `Switch`
- 드롭다운 메뉴 트리거 → Use `MenuButton`
## Props
### Required
| Prop | Type | Description |
| -------- | --------- | ----------------------- |
| children | ReactNode | 버튼 레이블 또는 아이콘 |
### Optional
| Prop | Type | Default | Description |
| ---------- | ------------------------------------------------------------ | --------- | -------------------------------- |
| variant | 'default' \| 'destructive' \| 'outline' \| 'ghost' \| 'link' | 'default' | 시각적 스타일 |
| size | 'default' \| 'sm' \| 'lg' \| 'icon' | 'default' | 버튼 크기 |
| disabled | boolean | false | 비활성화 상태 |
| loading | boolean | false | 로딩 상태 (스피너 표시) |
| type | 'button' \| 'submit' \| 'reset' | 'button' | HTML button type |
| aria-label | string | - | 접근성 레이블 (아이콘 버튼 필수) |
## Variants
| Variant | When to Use |
| ----------- | ------------------------- |
| default | 주요 액션, CTA |
| destructive | 삭제, 위험한 액션 |
| outline | 보조 액션, 취소 |
| ghost | 최소 강조, 툴바 |
| link | 인라인 텍스트 링크 스타일 |
## Examples
### Minimal
\`\`\`tsx
<Button>저장</Button>
\`\`\`
### Form Submit
\`\`\`tsx
<Button type="submit" loading={isSubmitting}>
{isSubmitting ? '저장 중...' : '저장'}
</Button>
\`\`\`
### Destructive Action
\`\`\`tsx
<Button variant="destructive" onClick={handleDelete}>
삭제
</Button>
\`\`\`
### Icon Button
\`\`\`tsx
<Button size="icon" aria-label="설정 열기">
<SettingsIcon />
</Button>
\`\`\`
## Composition
### Button Group
\`\`\`tsx
<div className="flex gap-2">
<Button variant="outline">취소</Button>
<Button>확인</Button>
</div>
\`\`\`
### With Icon
\`\`\`tsx
<Button>
<PlusIcon className="mr-2 h-4 w-4" />
추가
</Button>
\`\`\`
## Accessibility
- Enter/Space로 활성화
- disabled 시 `aria-disabled="true"` 자동 적용
- 아이콘 전용 버튼은 `aria-label` 필수
## Related
- `Link`: 페이지 네비게이션
- `IconButton`: 아이콘 전용 버튼 (aria-label 강제)
- `MenuButton`: 드롭다운 메뉴 트리거
- `Toggle`: 켜짐/꺼짐 상태 토글예시와 설명의 균형
예시 구성 원칙
// 좋은 예시 구조
// 1. 최소 예시 (Minimal)
// - 필수 props만 사용
// - 가장 흔한 유스케이스
<Button>저장</Button>
// 2. 기본 변형 (Basic Variations)
// - 각 variant/size 조합
// - 하나씩 독립적으로
<Button variant="outline">취소</Button>
<Button size="lg">큰 버튼</Button>
// 3. 조합 예시 (Composition)
// - 실제 UI 패턴
// - 다른 컴포넌트와 함께
<Card>
<Card.Content>내용</Card.Content>
<Card.Footer>
<Button variant="ghost">취소</Button>
<Button>확인</Button>
</Card.Footer>
</Card>
// 4. 엣지 케이스 (Edge Cases)
// - 로딩, 에러, 비활성화
// - 긴 텍스트, 아이콘
<Button loading disabled>
매우 긴 버튼 텍스트가 들어갈 때
</Button>설명 구성 원칙
## variant 선택 가이드
### default (기본)
주요 액션에 사용. 화면당 1-2개 권장.
```tsx
<Button>저장</Button>
```
### destructive (위험)
되돌릴 수 없는 액션에만 사용.
삭제, 계정 탈퇴 등.
⚠️ 일반 에러 표시에는 사용 금지.
```tsx
<Button variant="destructive">삭제</Button>
```
### outline (보조)
보조 액션, 취소 버튼에 사용.
primary 버튼과 함께 배치할 때 적합.
```tsx
<Button variant="outline">취소</Button>
```컨텍스트 주입용 문서 포맷
CLAUDE.md 연동 포맷
# Design System Quick Reference
## 컴포넌트 선택 가이드
### 버튼 계열
| 목적 | 컴포넌트 | 예시 |
| ----------- | -------------------------------- | ---------- |
| 폼 제출 | `<Button type="submit">` | 저장, 전송 |
| 위험 액션 | `<Button variant="destructive">` | 삭제 |
| 보조 액션 | `<Button variant="outline">` | 취소 |
| 페이지 이동 | `<Link>` | 더보기 |
| 상태 토글 | `<Toggle>` | 즐겨찾기 |
### 입력 계열
| 목적 | 컴포넌트 |
| ---------------- | ------------------ |
| 단일 행 텍스트 | `<Input>` |
| 다중 행 텍스트 | `<Textarea>` |
| 옵션 선택 (단일) | `<Select>` |
| 옵션 선택 (다중) | `<Combobox multi>` |
| 예/아니오 | `<Switch>` |
| 다중 선택 | `<Checkbox>` 그룹 |
### 피드백 계열
| 목적 | 컴포넌트 |
| ------------------- | --------------- |
| 성공/정보/경고/에러 | `<Alert>` |
| 짧은 피드백 | `<Toast>` |
| 확인 필요 | `<AlertDialog>` |
| 상세 정보 | `<Tooltip>` |JSON 메타데이터 포맷
{
"components": {
"Button": {
"summary": "사용자 액션 트리거",
"category": "interactive",
"variants": ["default", "destructive", "outline", "ghost", "link"],
"sizes": ["default", "sm", "lg", "icon"],
"useCases": ["form-submit", "dialog-action", "inline-action"],
"avoidFor": ["navigation", "toggle-state", "menu-trigger"],
"alternatives": {
"navigation": "Link",
"toggle-state": "Toggle",
"menu-trigger": "MenuButton"
}
}
}
}프로젝트 루트 시각 규칙 문서
컴포넌트 문서가 "무엇을 어떻게 조합하는가"를 다룬다면,
DESIGN.md는 "전체 화면이 어떤 인상을 줘야 하는가"를 다룹니다.
| 문서 | 설명 단위 | AI가 주로 참조하는 질문 |
|---|---|---|
DESIGN.md | 화면/브랜드/레이아웃 철학 | "이 프로젝트는 어떤 분위기와 밀도로 보여야 하나?" |
| component docs | 컴포넌트 단위 | "이 상황에서 Button과 Link 중 무엇을 써야 하나?" |
| token docs | 값 단위 | "primary, surface, outline 중 어떤 값을 써야 하나?" |
추천하는 구조는 다음과 같습니다.
DESIGN.md
components/
button.spec.md
card.spec.md
tokens/
colors.tokens.json
spacing.tokens.json루트 문서와 하위 문서가 던지는 질문이 다르다는 게 핵심입니다.
DESIGN.md가 없으면 AI가 컴포넌트는 맞게 고르는데 화면 분위기가 흔들리고,
component docs가 없으면 분위기는 맞는데 실제 UI 조합이 불안정해집니다.
DESIGN.md에 넣어야 할 최소 정보
# Design System
## Overview
조용하고 밀도 높은 B2B 운영 화면. 장식보다 정보 구조를 우선한다.
## Colors
- **Primary** (#2665fd): 주요 액션, 활성 상태
- **Surface** (#f7f8fa): 기본 표면
- **On-surface** (#111827): 본문 텍스트
## Typography
- **Headline Font**: Pretendard
- **Body Font**: Pretendard
## Components
- **Buttons**: 10px radius, primary는 채움, secondary는 outline
- **Cards**: 강한 shadow보다 border contrast 사용
## Do's and Don'ts
- Do: 한 화면의 핵심 CTA만 primary 사용
- Don't: glossy gradient나 heavy shadow 남용이 문서가 token schema를 대신하지는 않습니다.
오히려 DESIGN.md는 component docs와 token docs 위에서
에이전트의 시각적 해석 범위를 좁혀주는 상위 가드레일로 읽혀야 합니다.
DESIGN.md 자체의 역할과 구조는
DESIGN.md 인터페이스 장에서 따로 정리합니다.
MCP 서버 연동
MCP 도구 정의
// mcp/design-system-server.ts
const tools = [
{
name: 'get_component',
description: '컴포넌트 문서와 예시 조회',
inputSchema: {
type: 'object',
properties: {
name: {
type: 'string',
description: '컴포넌트 이름 (예: Button, Card)',
},
section: {
type: 'string',
enum: ['props', 'examples', 'accessibility', 'all'],
description: '조회할 섹션',
},
},
required: ['name'],
},
},
{
name: 'find_component',
description: '용도에 맞는 컴포넌트 검색',
inputSchema: {
type: 'object',
properties: {
purpose: {
type: 'string',
description: '사용 목적 (예: "form submit", "show error")',
},
},
required: ['purpose'],
},
},
{
name: 'get_token',
description: '디자인 토큰 값 조회',
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: '토큰 경로 (예: colors.primary, spacing.4)',
},
},
required: ['path'],
},
},
{
name: 'get_pattern',
description: 'UI 패턴 예시 조회',
inputSchema: {
type: 'object',
properties: {
name: {
type: 'string',
description: '패턴 이름 (예: login-form, data-table)',
},
},
required: ['name'],
},
},
]MCP 핸들러 구현
// mcp/handlers.ts
async function handleGetComponent(name: string, section = 'all') {
const component = await loadComponent(name)
if (section === 'all') {
return {
name: component.name,
summary: component.summary,
props: component.props,
examples: component.examples,
accessibility: component.accessibility,
related: component.related,
}
}
return component[section]
}
async function handleFindComponent(purpose: string) {
const index = await loadComponentIndex()
const matches = index.filter((c) => c.useCases.some((uc) => matchPurpose(uc, purpose)))
return matches.map((c) => ({
name: c.name,
summary: c.summary,
confidence: calculateConfidence(c, purpose),
}))
}Figma MCP 생태계
2025-2026년 Figma MCP 서버가 정식 출시되면서 디자인 시스템과 AI 코딩 도구 사이의 경계가 허물어지고 있습니다.
- Figma MCP 서버: Dev Mode에서 AI 코딩 도구(Cursor, Copilot, Claude Code)에 Figma 컨텍스트 제공. 코드용(
get_code_connect_snippet), 이미지용(get_image), 변수 정의용(get_variables) 3가지 도구 제공 - generate_figma_design 도구 (2026.02): Claude Code 전용 도구로, 브라우저의 라이브 UI를 캡처하여 편집 가능한 Figma 레이어로 변환
- Figma Codex (2026.02 베타): 양방향 MCP 서버로 캔버스와 코드베이스 간 유동적 이동 지원
- Storybook Design System MCP Server: 컴포넌트 매니페스트를 LLM 친화적 방식으로 노출 (개발 중)
- Panda CSS MCP 서버: 디자인 시스템의 토큰, 스타일 계층, 네이밍 규칙을 Model Context Protocol로 AI에 노출
MCP 기반 디자인-코드 통합
MCP 서버가 디자인 도구와 AI 코딩 도구를 이어주면서, 디자이너가 Figma에서 작업한 컴포넌트 명세가 AI 에이전트에게 실시간으로 전달됩니다. 프롬프트에 컨텍스트를 손으로 복사해 넣던 시대는 저물고 있습니다.
참고 링크
체크리스트
shadcn/skills — AI 에이전트 전용 컨텍스트
shadcn/ui CLI v4 (2026.3)
shadcn/ui CLI v4에서 **shadcn/skills**가 도입되었습니다. AI 코딩 에이전트에게 Radix UI와 Base UI
프리미티브 API, 컴포넌트 패턴, 레지스트리 워크플로우 컨텍스트를 자동으로 주입합니다.
덕분에 AI가 디자인 시스템 컴포넌트를 더 정확하게 만들어냅니다.