design-mdlisted

# design-md 스킬 프로젝트 루트에 **`DESIGN.md`** 한 파일을 생성한다. 이 파일은 브랜드의 시각 언어를 AI 코딩 에이전트가 **참조 가능한 결정값**으로 기술한 디자인 시스템의 단일 진실 원천(SSOT)이다. > **왜 DESIGN.md가 필요한가** — LLM은 세션마다 콜드 스타트라 브랜드 제약을 기억하지 못한다. "기존 스타일에 맞춰줘"는 > 매번 문맥에 우연히 들어온 예시에서 규칙을 *추론*할 뿐이라 UI 생성마다 색·간격·컴포넌트가 흔들린다. 규칙을 파일에 박아 > UI 생성 전에 읽히면, 출력 기준선이 "못 쓸 결과물"에서 "약간 손보면 쓸 결과물"로 올라간다. 이 포맷은 Google Labs의 > `design.md` 스펙이 형식 표준을 정의하고, VoltAgent·oh-my-design 같은 커뮤니티 라이브러리가 실제 예시를 배포하며 사실상 > 표준이 됐다. > **CLAUDE.md / AGENTS.md와의 역할 분리** — AGENTS.md/CLAUDE.md는 "프로젝트를 **어떻게 빌드**하나"(코딩 대상), > DESIGN.md는 "**어떻게 보이고 느껴져야** 하나"(디자인 대상)를 담당한다. 둘은 겹치지 않는다. ## 이 스킬의 정체성 — "현실 기술" (열망 금지) 대부분의 DESIGN.md 도구는 대화로 취향을 물어 *열망적* 디자인 시스템을 만든다. **이 스킬은 반대로, 기존 코드에서 실제로 쓰이는 값을 먼저 추출한다.** DESIGN.md의 최대 실패 모드가 "문서↔코드 드리프트"(문서엔 있는데 코드엔 없는 값을 에이전트가 믿고 엉뚱한 UI를 생성)이기 때문이다. 고치고 싶은 리디자인이 아니라 **레포의 실제 상태**를 기술한다 — 그래야 에이전트가 문서를 믿고 만든 UI가 기존 코드와 어긋나지 않는다. ## 작성 원칙 (사람용 디자인 문서와 다른 점) 사람용 문서는 근거·감성을 길게 서술해도 되지만, AI용은 **결정론적으로 참조 가능**해야 한다. 다섯 원칙: 1. **선택지가 아니라 결정 + 사용 조건을 준다.** 옵션을 주면 생성마다 다르게 쓴다. 값 하나를 박고 "언제 쓰고, 언제 절대 안 쓰는지"까지 규정한다. 예: `primary-900 — 화면 최고 강조 액션에만, 한 뷰에 2개 금지`. 2. **값 + 의도를 함께.** hex만도, 원칙만도 실패한다. `#5A67D8`를 던지지 말고 `#5A67D8 — Primary CTA, active links`처럼 값에 역할을 붙인다. 3. **용도별로 명명한다.** `font-size: 3rem` 나열이 아니라 `Hero h1 = 64px`. 에이전트는 이름→용도 매핑으로 어디에 쓸지 결정한다. 4. **Don'ts를 반드시, 구체적으로.** 여러 실험에서 don'ts가 do's보다 정확도를 더 크게 올렸다. "cool gray 금지", "serif display에 bold 금지"처럼 **구체적 행동 금지**로 쓴다. "깔끔하게" 같은 일반 긍정문은 실패한다. 5. **현실을 쓴다.** 위