# 컴포넌트 명세 — AI가 읽는 청사진

> Props 스키마·상태 머신·슬롯 합성·Spec as Data

- Canonical: https://learning.reopt.ai/courses/design-systems/lessons/ds-l2-spec
- Language: ko-KR
- HTML: https://learning.reopt.ai/courses/design-systems/lessons/ds-l2-spec

---

[AI 시대의 디자인 시스템](/courses/design-systems) 2. 컴포넌트 명세 & 접근성 4 / 15

# 컴포넌트 명세 — AI가 읽는 청사진

Props 스키마·상태 머신·슬롯 합성·Spec as Data
개념 학습 33 XP 7분

컴포넌트 명세는 AI가 따라 읽는 컴포넌트 사용 청사진 입니다. Props 스키마, 상태 모델, 합성 패턴을 분명히 정의해 두어야 AI가 올바른 코드를 생성합니다.

- Props 스키마 — 타입·제약·기본값
- 상태 모델 — 상태 머신으로 표현
- 합성 패턴 — Compound Component와 슬롯
- 접근성 — ARIA·키보드 규칙
- 예시 — 기본/고급 코드 샘플

## Props: 타입으로 의도 표현

Literal Union·Discriminated Union으로 타입을 좁히고, @ai-hint (선택 기준)와 @default (기본값) 주석을 붙이면 AI가 상황에 맞는 Props를 고릅니다. 예: variant가 가장 중요한 액션이면 default , 되돌릴 수 없으면 destructive .

## 상태 모델 — 상태 머신

가능한 상태와 전이 규칙을 상태 머신으로 정의하면 무효한 전이를 막을 수 있습니다. 예: idle → loading → success/error , error → loading (재시도), idle ↔ disabled .

## 슬롯 기반 합성

| 슬롯 | required | allowedTypes | maxCount |
| header | false | Card.Header | 1 |
| content | true | Card.Content | 1 |
| footer | false | Card.Footer | 1 |

Card 슬롯 스키마 예시 — 필수/허용 타입/최대 개수를 데이터로 명시

## Spec as Data

단일 소스 of Truth = ComponentMeta ComponentMeta (TS/JSON) 하나만 진실로 두고, 여기서 MDX 문서·PropsTable·MCP 리소스·lint 규칙을 파생시키면 문서-코드 드리프트 를 막습니다. Zod/JSON Schema로 빌드 타임에 필수 필드·enum·제약을 검증하세요.
핵심 정리

- 컴포넌트 명세 = Props 스키마 + 상태 모델 + 합성 패턴 + 접근성 + 예시
- @ai-hint·@default 주석과 Discriminated Union으로 AI의 선택 기준·제약을 명시한다
- ComponentMeta를 단일 소스로 두고 문서·MCP 리소스·lint를 파생시켜 드리프트를 막는다

[이전](/courses/design-systems/lessons/ds-l1-quiz) 이해했어요 · 계속

---

에이전트용 사이트 안내: https://learning.reopt.ai/llms.txt · 사이트맵: https://learning.reopt.ai/sitemap.xml · 문의: https://learning.reopt.ai/contact