# Component specifications — an AI-readable blueprint

> Props schemas, state machines, slot composition, and Spec as Data

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

---

[Design systems in the AI era](/en/courses/design-systems) 2. Component specifications & accessibility 4 / 15

# Component specifications — an AI-readable blueprint

Props schemas, state machines, slot composition, and Spec as Data
Concept 33 XP 7 min

컴포넌트 명세는 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를 파생시켜 드리프트를 막는다

[Previous](/en/courses/design-systems/lessons/ds-l1-quiz) Got it · Continue

---

Site guide for agents: https://learning.reopt.ai/llms.txt · Sitemap: https://learning.reopt.ai/sitemap.xml · Contact: https://learning.reopt.ai/contact