Design.md: 사람과 에이전트를 위한 하나의 디자인 표준 파일
1. 도입 배경 및 문제점
AI 에이전트의 한계: 코딩 에이전트에게 화면 작성을 요청하면 브랜드 정체성이 없는 범용 컴포넌트(Material, shadcn 등)를 사용합니다.
- 디자인 정보의 파편화 : 브랜드 디자인 시스템이 Figma, 프레젠테이션 슬라이드, 디자이너의 머릿속에만 존재하여 AI가 빌드 시점에 이를 읽어올 수 없기 때문입니다.
- 해결책 : 코드 저장소 루트에 AI와 사람이 모두 읽을 수 있는 단일 평문 파일(DESIGN.md)을 두어 표준으로 삼는 것입니다.
2. DESIGN.md 파일의 두 가지 구조
하나의 파일 내에서 머신과 사람이 필요한 정보를 구분하여 제공합니다.
- 상단 (YAML 토큰 - Machine) : 머신이 해석하는 규격화된 수치값입니다. 색상 헥사 코드, 타이포그래피 스케일, 여백(spacing), 모서리 곡률(radii) 등을 정의합니다.
- 하단 (Markdown Prose - Human & Agent Intent) : 사람이 이해하는 디자인 맥락과 의도입니다. 특정 색상을 사용하는 이유, 가이드라인, 렌더링 시 고려해야 할 규칙(Do's & Don'ts) 등을 기술합니다.
- 핵심 원칙 : 본문 설명과 상단 토큰 데이터가 충돌할 경우 토큰(Token) 값이 우선합니다.
3. 구성하는 8가지 섹션
- Overview: 브랜드 성격, 타깃 사용자, 감성적 톤앤매너
- Colors: 메인 및 서브 컬러 팔레트
- Typography: 타이포 단계별 세팅 (9~15개 범주)
- Layout: 그리드 모델 및 여백(Spacing) 토큰
- Elevation & Depth: 시각적 위계 (그림자, 테두리 등)
- Shapes: 모서리 곡률 토큰
- Components: 버튼, 입력창, 칩 등 요소별 상세 스타일
- Do’s and Don’ts: 지켜야 할 가이드라인 및 주의사항
4. 실무 활용 및 관리 방법
- 역할 기반 이름 설정 (Semantic Naming): bigRedButton처럼 외형을 딴 이름이 아닌 button.primary처럼 역할을 나타내는 이름을 사용해야 브랜딩 변경에도 지속 가능합니다.
- 코드베이스 동의 및 버전 관리 : README.md 옆 저장소 루트에 배치하여 Pull Request(PR)를 통해 변경 사항을 검토 및 기록합니다.
- 자동화 검비 및 변환 : 구글에서 제공하는 CLI 도구 등을 활용해 WCAG 대비율 검사(접근성 린팅), 디프(diff) 비교, Tailwind 및 W3C 토큰 포맷 변환 등을 자동화할 수 있습니다.
