ko-design-md: Instructions file for Claude Code

ko-design-md

한국 브랜드의 디자인 시스템을 Stitch v0.1 마크다운(services/{slug}.md)으로 정리한 오픈 카탈로그. TanStack Start 사이트(getdesign.kr)가 이를 서빙하고, /design-md 스킬(.claude/skills/design-md)이 새 항목 온보딩 파이프라인을 자동화한다. 패키지 매니저는 pnpm (npm 금지).

검증 커맨드 (CI 게이트와 동일)

pnpm typecheck && pnpm lint && pnpm format:check
pnpm test               # vitest — .claude/ 하위는 제외됨
pnpm validate:catalog   # services/*.md 전수: frontmatter·섹션 순서·OKLCH·인용 무결성
pnpm validate:previews  # public/preview/*/ 전수: 구조 block + 반응형 휴리스틱 warn
pnpm tokens:check       # services/*.tokens.json 이 소스 md 와 일치하는지 (drift 게이트)
pnpm audit:oklch        # OKLCH↔병기 hex 일치 + 프리뷰가 md 정의와 어긋나지 않는지
pnpm check:last-updated # 이 브랜치가 바꾼 services/*.md 의 last_updated 가 최신인지
pnpm validate:spec      # 로컬 진단용 출력. 실제 게이트는 pnpm test 안의
                        # google-designmd-corpus.test.ts (같은 공식 린터를 vitest 로)
pnpm build              # build:og + vite build

단일 파일 검사: pnpm validate:draft <file.md> [--slug X --expected-logo <url> --lang ko], pnpm validate:previews --slug <slug> --verbose. 스킬 파이프라인은 이 검증기를 author→reviewer 사이 기계 게이트(Stage 6a2/9a2)로 실행한다.

카탈로그 정책 (위반은 CI가 block)

• 토큰은 frontmatter 에 산다. colors: · typography: · spacing: · rounded: 맵이 Google DESIGN.md 형태다. 이 네 섹션의 본문 yaml 펜스는 폐기된 형태로, 추출기가 폴백으로만 읽는다 — 카탈로그 20개 전부 이전돼 토큰 섹션의 펜스는 0개다. 그룹은 ## 라벨 주석 행이 열고(사이드카 group), 토큰별 단서는 그 줄의 트레일링 # 주석이 나른다(사이드카 note — 기계 소비자에게 닿는 유일한 경로).
• 다만 본문 펜스가 전부 사라진 건 아니다. 40개가 남아 있고 의도된 것이다 — ## Elevation & Depth 아래 22개 · ## Components 의 스펙 16개 · ## Motion 2개. 그 22개가 전부 shadow 는 아니다 — 5개가 이징·duration 맵이고(### Motion 둘 · ### Animation 하나 · 하위 헤딩 없이 둘), 나머지 17개가 shadow·elevation 이다. 즉 모션 토큰은 두 헤딩에 갈려 있으니 ## Motion 만 세면 7개 중 2개만 잡는다. 사이드카(ServiceTokens)에도 스펙의 토큰 맵에도 이들을 담을 자리가 없어서 본문에 남는다. 컴포넌트 스펙 펜스는 컴포넌트 이름 아래로 한 단계 중첩해서 쓴다 — 린터가 frontmatter 와 모든 본문 펜스를 한 네임스페이스로 병합하므로, 0열 키가 두 펜스에 겹치면 그 문서 전체가 0토큰이 된다(wanted 가 키 7개 충돌로 그랬다).
• 색상 토큰 값은 OKLCH만. frontmatter colors: 맵의 name: oklch(...) 형식. 원본 hex는 # #FAFAFA 트레일링 주석이나 같은 줄 (≈ oklch(...)) 병기로만 기록.
• 값을 인용하지 말 것 — 이제 block 이다(quoted-token-value). 인용하면 audit:oklch 와 드리프트 검사가 그 토큰을 못 보고 둘 다 통과를 보고한다. 벌거벗은 #FF0038 은 YAML 이 주석으로 읽어 애초에 무효라, 인용형이 hex 를 쓸 수 있는 유일한 철자였고 그래서 정확히 그것이 잡혀야 했다. 참조("{colors.x}")와 따옴표로 시작하는 폰트 스택만 인용한다.
• frontmatter 는 진짜 YAML 파서를 통과해야 한다(frontmatter-yaml-invalid, block). buildDoc 의 손수 만든 파서는 스스로 밝히듯 무효 입력에서 조용히 열화하고 나머지 게이트는 정규식이라, 인용 없는 폰트 스택 하나가 문서 전체를 0토큰으로 만들어도 아무도 몰랐다(실제로 7개 항목에서 났다).
• frontmatter sources == ## References (순서·내용 동일). 이 중복은 의도된 자기완결 포맷이다 — 제거하거나 한쪽만 고치지 말 것. 인용은 [src:N] 정수 인덱스.
• 인용은 존재가 아니라 내용 일치. [src:N]이 가리키는 소스가 실제로 그 주장을 담고 있어야 한다 (리뷰어의 의미적 스팟체크 대상).
• logo는 https://getdesign.kr/logos/*.{svg,png,webp,avif} 절대 URL (파일이 사이트 밖으로 복사돼도 유효해야 함). 프리뷰 HTML 안에서는 반대로 site-relative /logos/....
• 10개 Stitch 표준 섹션은 상대 순서 유지 (사이 비표준 섹션 추가는 허용).
• 테마별 팔레트는 이름을 갈라 쓴다 (bg-canvas / dark-bg-canvas). 한 이름을 두 값으로 선언하면 어느 쪽이 정본인지 알 수 없어 프리뷰 대조가 그 토큰에서 꺼진다. 관례는 dark- 접두다(codeit 78개·seed-design 109개). wanted가 21개를 충돌시켜 대조 22건을 잃고 있었다.
• Dimension 값은 0이어도 단위를 붙인다 — tracking: 0 이 아니라 0em.