Design md

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. 현실을 쓴다. 위 "현실 기술" 원칙. 스캔으로 실제 값을 뽑고, 못 채운 것만 대화로 보완한다.

---

실행 절차

Step 1: 대상 파악 + 모드 판별 (하이브리드)

먼저 대상 프로젝트 루트를 정한다(인자가 있으면 그 경로, 없으면 현재 작업 디렉터리 — git rev-parse --show-toplevel 폴백 pwd).

그다음 스타일 소스가 있는지 훑어 브라운필드(코드 있음)/그린필드(코드 없음)를 판별한다:

# 스타일 소스 존재 여부 스캔 (있으면 브라운필드 = 스캔 우선)
ls tailwind.config.* 2>/dev/null
find . -path ./node_modules -prune -o \( -name '*.css' -o -name '*.scss' -o -name 'theme.*' -o -name 'tokens.*' \) -print 2>/dev/null | head
grep -rEl ':root|--[a-z].*:|font-family|styled|createTheme|StyleSheet.create' src app 2>/dev/null | head

• 하나라도 잡히면 브라운필드 → Step 2의 스캔을 돌려 실제 값을 추출하고, 빈 축만 대화로 보완한다.
• 아무것도 없으면 그린필드 → Step 2 스캔을 건너뛰고 곧바로 대화 중심(Step 2의 "대화 보완")으로 디자인 시스템을 정의한다.

기존에 DESIGN.md가 이미 있으면 Read로 읽어 덮어쓸지/보강할지를 사용자에게 확인한다 — 기존 결정을 임의로 지우지 않는다.

Step 2: 값 추출 (스캔 우선, 부족분만 대화)

목표는 필수 6축(브랜드 톤·컬러·타이포·스페이싱/레이아웃·컴포넌트·Do/Don't)을 채우는 것이다. 축별 구체 grep 패턴과 무엇을 뽑을지는 references/section-spec.md를 읽어 따른다. 요지만 옮기면:

• 컬러: :root 커스텀 프로퍼티, tailwind.config theme.colors, hex/rgb/hsl 리터럴을 grep해 실제 쓰이는 색과 빈도를 뽑는다. 값만이 아니라 역할(어디에 쓰이나)을 코드 맥락에서 읽는다.
• 타이포: font-family, @font-face, next/font, fontFamily, 반복되는 font-size/fontSize 스케일을 뽑아 용도별로 정리한다.
• 스페이싱/레이아웃: 베이스 단위(4/8px), 반복 padding/margin 값, max-width, 그리드/컨테이너를 뽑는다.
• 컴포넌트: 버튼·인풋·카드·모달의 실제 스타일(radius·padding·height·shadow)을 절대값으로 뽑는다.

스캔의 핵심은 "빈도와 역할"이다. 코드에 색이 40개 있어도 전부 토큰이 아니다. 자주·의미 있게 쓰인 값을 골라 시맨틱 토큰(primary/surface/ink…)으로 승격하고, 일회성 값은 버린다. 판단이 서지 않으면 사용자에게 묻는다.

대화 보완: 스캔으로 못 채운 축(예: 브랜드 톤·personality, Don'ts, 접근성 의도)은 AskUserQuestion으로 좁힌다. 한 번에 다 펼치지 말고 빈 축을 하나씩 물어 확정한다. 그린필드면 이 대화가 주 입력이 된다.

Step 3: DESIGN.md 작성

templates/DESIGN.template.md를 뼈대로 쓴다. 이 파일은 2부 구성이다:

1. YAML frontmatter — 기계가 파싱할 토큰(colors/typography/spacing/rounded/components). Google design.md 스펙 형식.
2. Markdown body — 사람이 읽을 근거 + 사용 규칙. VoltAgent 9섹션 헤더를 따른다.

필수 6섹션은 반드시 채운다 (하나라도 비면 저장하지 않는다):

섹션	무엇을
Overview / Visual Theme	브랜드 personality·타깃·톤 3~5문장 (모호 케이스의 판단 기준)
Colors	토큰마다 값 + 역할 + "언제 쓰고 언제 금지" (표)
Typography	서체·스케일·weight를 용도별(display/body/label/caption)로
Spacing & Layout	베이스 단위 + 스케일(xs~xl), 그리드·max-width
Components	버튼·인풋·카드를 radius·padding·height·shadow 절대값으로
Do's & Don'ts	구체적 행동 규칙. 정확도 최대 레버 — 절대 생략 금지

권장 섹션(값이 있으면 추가): Depth & Elevation · Responsive Behavior · Accessibility. 선택: Motion · Known Gaps.

값 granularity와 섹션별 상세 형식·예시는 references/section-spec.md, Don'ts 예문은 references/dos-and-donts-bank.md를 참고한다.

인라인 토큰만, 거대 JSON 통째 금지. DESIGN.md에는 압축된 시맨틱 토큰 표(이름+값+역할)만 인라인한다. 원시 토큰 덤프를 통째로 붙이지 않는다 — DESIGN.md는 매 요청마다 전량 로드되므로, 부풀면 토큰을 크게 낭비한다(성숙 프로덕션에서 특히 비싸다). 값+규칙의 압축 구조가 이 파일의 가치다.

Step 4: 자체 점검 게이트 (저장 직전)

저장 전 아래를 확인한다. 하나라도 실패하면 고친 뒤 저장한다:

• 필수 6섹션이 모두 채워졌는가 (특히 Do's & Don'ts가 비어 있지 않은가)
• 각 토큰에 값 + 역할/사용조건이 붙었는가 (값만 나열된 칸이 없는가)
• 값이 구체적인가 (hex·px·절대값 — "부드러운 회색" 같은 추상 표현이 아님)
• 현실을 기술했는가 — 스캔으로 뽑은 값이면 실제 코드와 일치하는가, 대화로 정한 값이면 열망이 아니라 합의된 값인가
• YAML frontmatter의 토큰과 body의 표가 서로 어긋나지 않는가

Step 5: 저장 + 참조 줄 안내 (⚠️ 반드시)

DESIGN.md를 프로젝트 루트에 Write한다 (<root>/DESIGN.md). 코드 옆에 둬야 SSOT가 레포 밖으로 새지 않는다.

그다음 가장 중요한 마무리 — DESIGN.md는 자동으로 읽히지 않는다. CLAUDE.md/AGENTS.md에 참조 줄을 걸어야 실제로 참조된다. 이걸 빠뜨리면 파일이 있어도 에이전트가 무시한다. 아래 줄 추가를 제안하고, 사용자가 동의하면 반영한다:

## 디자인
UI를 생성·수정하기 전 항상 프로젝트 루트의 `DESIGN.md`를 읽고 그 토큰·규칙을 따른다.

대상은 상황별로 갈린다:

• 기존 CLAUDE.md가 있으면 → 거기에 Edit로 추가.
• 없고 AGENTS.md가 있으면 → 거기에 Edit로 추가.
• 둘 다 없으면(그린필드에서 흔하다) → AGENTS.md를 새로 만들어 이 줄을 넣자고 제안하고, 동의 시 Write로 생성한다. DESIGN.md만 있고 앵커가 없으면 자동 로드가 안 돼 무용지물이므로, "안내만" 하고 끝내지 않는다 — 그린필드에서 preview는 적극 만들면서 참조 앵커를 안 거는 비대칭을 피한다.

동의가 없으면 이 줄을 그대로 보여주며 "직접 넣어달라"고 안내한다. 저장한 DESIGN.md 경로와 이 참조 줄 처리 결과를 함께 보고한다.

Step 6: preview.html 조건부 생성 (시각 레퍼런스)

DESIGN.md는 텍스트라 사람이 "이게 온-브랜드인가"를 눈으로 보기 어렵다. preview.html은 그 값을 한 화면에 렌더한 시각 레퍼런스 보드다(스와치·타입스케일·스페이싱 바·컴포넌트 갤러리 + 라이트/다크 토글). 항상 만들지는 않는다 — 이미 렌더되는 실앱이 있으면 대체로 중복이기 때문이다. 아래 트리거로 판단한다:

• 그린필드(Step 1에서 볼 실앱이 없다고 판별) → preview가 유일한 시각화다. 생성을 권장한다.
• 브라운필드(실앱 있음) → 기본은 생성하지 않고, 공유·육안검증용으로 만들지 옵션으로 제안한다.
• 사용자가 "미리보기/preview 만들어줘"라고 명시하면 모드와 무관하게 만든다.

참조-줄과 같은 제안 → 동의 시 생성 패턴이다. 동의하면 templates/preview.template.html을 뼈대로, 방금 저장한 DESIGN.md의 값을 채워 <root>/preview.html로 Write한다. 채우는 방법·섹션별 규칙·자기완결 제약·다크 토글 처리는 references/preview-spec.md를 읽어 따른다. 핵심만 옮기면:

• 자기완결 — 외부 폰트·CSS·JS·CDN을 절대 참조하지 않는다(모두 인라인). 오프라인에서 그대로 열려야 한다.
• 값 100% 일치 — preview는 DESIGN.md의 시각화일 뿐이다. hex·px·서체를 임의로 바꾸지 않는다.
• 다크 토글, 열망 금지 — DESIGN.md에 다크 팔레트가 있으면 그 값으로 스왑, 없으면 토글이 페이지 배경(크롬)만 전환해 같은 브랜드 색을 밝은/어두운 주변에서 대조하게 한다. 없는 다크 색을 지어내지 않는다.

저장 후 "브라우저로 preview.html을 열어 확인하라"고 안내한다. 커밋·push는 하지 않는다.

Step 7: 확장 안내 (토큰 파일 — 아직 생성하지 않음)

이 스킬은 DESIGN.md + (조건부) preview.html까지 생성한다. 토큰 파일은 아직 만들지 않고, 필요 조건이 보이면 사용자에게 옵션으로만 안내한다 (템플릿에도 주석 슬롯으로 표시돼 있다):

• 토큰 파일 — 빌드 파이프라인(Tailwind/Style Dictionary 등)이 감지되면 DTCG JSON 정본($value/$type)을 보편 코어로 두고, 감지된 주력 스택용 소비판(웹=--ds-* CSS·Tailwind, 네이티브=Kotlin/Swift 등)을 붙여 emit하는 게 유용하다. DTCG JSON은 플랫폼 중립이라 iOS↔Android처럼 CSS를 공유 못 하는 네이티브에서 특히 값이 크다.

토큰 파일을 아직 자동 생성하지 않는 이유: 성숙 프로덕션에서 DESIGN.md에 원시 토큰을 통째로 인라인하면 매 요청마다 토큰을 크게 과소비하고, 에이전트가 기존 컴포넌트를 재사용하지 않고 재생성하는 기술부채가 생긴다는 실측 보고가 있다. 그래서 코어(DESIGN.md)는 가볍게 두고, 소비판 토큰 파일은 빌드 파이프라인이 실제로 감지될 때만 별도 emit하는 게 맞다.

---

주의사항

• DESIGN.md + (조건부) preview.html까지 생성한다. 토큰 파일은 아직 만들지 않는다(조건 보이면 안내만). 코드 (컴포넌트 등)를 수정하지 않는다 — Write는 DESIGN.md·preview.html에, Edit는 CLAUDE.md/AGENTS.md 참조 줄 추가에만 쓴다.
• preview.html은 조건부·동의 후. 항상 만들지 않는다 — 그린필드면 권장, 브라운필드면 옵션 제안. 자기완결(외부 참조 0)이며 값은 DESIGN.md와 일치해야 하고, 없는 다크 팔레트를 지어내지 않는다.
• 필수 6섹션 강제. 특히 Do's & Don'ts가 없으면 저장하지 않는다 — 이게 AI 정확도의 최대 레버다.
• 현실 기술, 열망 금지. 브라운필드면 스캔 값이 실제 코드와 일치해야 한다. 못 채운 축만 대화로 보완한다.
• 참조 줄 안내를 빠뜨리지 않는다. DESIGN.md는 자동 로드되지 않으므로, CLAUDE.md/AGENTS.md 참조가 없으면 무용지물이다.
• 기존 DESIGN.md를 임의로 덮어쓰지 않는다. 있으면 보강/덮어쓰기를 사용자에게 확인한다.
• 커밋·push는 하지 않는다. 저장까지만 하고, 커밋 여부는 사용자가 프로젝트 규약대로 판단한다.