/design-md

name: design-md
description: 화면 작업의 디자인 문서(design.md, 프로젝트 전체면 DESIGN.md)를 만들 때 사용. 참고 사이트 URL·스크린샷을 캡처해 색·글꼴·간격·모서리·컴포넌트 패턴을 뽑거나, 주어진 디자인 시스템(링크·패키지·Figma·기존 DESIGN.md)을 기준으로 삼아 토큰과 화면 규칙을 정한다. Triggers - design.md, 디자인 문서, 이 사이트처럼, 레퍼런스 캡처, 디자인 참고, 디자인 시스템 반영, 스타일 가이드.

design-md: 참고·디자인 시스템 → design.md

`spec.md`가 동작과 구조를 정한다면, `design.md`는 보이는 모습을 정한다. 이 스킬은 참고 자료를 실제로 캡처하고 측정해서, 구현자가 그대로 옮길 수 있는 토큰과 규칙으로 바꾼다. 감으로 "모던하게"라고 쓰지 않는다.

1. 입력 확인 (한 번에 묻는다)

• **범위**: 이번 화면만이면 작업 폴더의 `docs/work/<날짜>-<주제>/design.md`. 프로젝트 전체 디자인 시스템이면 루트 `DESIGN.md`. 루트 `DESIGN.md`가 이미 있으면 그것을 따르고, 이번 화면에서 달라지는 것만 쓴다.
• **참고 사이트**: URL 1~3개, 각각에서 무엇을 가져올지(톤, 레이아웃, 타이포, 색, 특정 컴포넌트).
• **디자인 시스템**: 문서 링크, 패키지(shadcn/ui, MUI, Ant Design, Chakra, Tailwind 테마 등), Figma 링크, 토큰 파일, 기존 DESIGN.md. 있으면 **이것이 기준**이다. 참고 사이트는 톤과 레이아웃에만 쓴다.
• **스크린샷·이미지**: 사용자가 준 파일은 그대로 참고 자료로 쓴다.

아무것도 없으면 spec.md와 intent.md에서 방향 형용사 세 개를 제안하고 고르게 한다.

2. 캡처 (참고 URL이 있을 때)

참고 자료는 `docs/work/<주제>/design-refs/`(DESIGN.md면 `docs/design-refs/`)에 둔다. 아래 순서로 쓸 수 있는 첫 도구를 쓴다.

1. **Playwright**(가장 정확): 이 스킬의 `scripts/capture.mjs`.

   node "<이 스킬 폴더>/scripts/capture.mjs" <url> --out docs/work/<주제>/design-refs

• 데스크톱 1440px로 최대 6장, 모바일 390px로 최대 4장을 화면 단위로 찍는다. 스크롤하면서 나타나는 섹션도 찍힌다.
• `<host>-styles.json`에는 CSS 변수, 주요 요소(body·h1~h3·p·a·button·input·카드·nav)의 계산된 스타일, 많이 쓴 색·글꼴·글자 크기·간격·모서리가 담긴다.
• Playwright는 이 하네스의 의존성이 아니다. 프로젝트에 없어서 스크립트가 종료 코드 2로 끝나면, 사용자에게 묻고 `npm i -D playwright`를 한다. 번들 브라우저가 없으면 설치된 Chrome으로 실행한다.

2. **REA**(Chrome을 `--remote-debugging-port=9222`로 띄웠을 때): `list_browser_targets` → `capture_web_screenshot`(보이는 화면) → `inspect_web_page`(DOM·리소스 목록). 페이지 JS를 실행하지 않으므로, 계산된 스타일 대신 스타일시트 URL을 받아 CSS 변수와 글꼴을 읽는다. 3. **브라우저 도구**(Claude in Chrome, 내장 브라우저): 화면 단위로 스크린샷을 찍는다. 4. 셋 다 없으면 사용자에게 스크린샷을 받는다.

지키는 것:

• 로그인해야 보이는 페이지, robots·약관이 막는 페이지, 개인 정보가 보이는 화면은 캡처하지 않는다.
• 참고 사이트의 로고·이미지·문구·독자 아이콘은 가져오지 않는다. 가져오는 것은 비율·계층·간격·색 관계 같은 원칙이다. 색 값을 그대로 쓰려면 사용자에게 확인한다.
• 캡처 파일은 git에 올려도 되는 것만 둔다. 크면 `.gitignore`에 넣고 design.md에 출처만 적는다.

3. 디자인 시스템이 주어졌을 때

• 문서 링크는 열어 읽고(context7이 그 라이브러리를 알면 그쪽), 패키지는 설치된 버전의 테마·토큰 파일을 직접 읽는다. Figma는 연결된 도구가 있으면 쓰고, 없으면 사용자에게 내보낸 토큰이나 스크린샷을 받는다.
• design.md의 토큰은 그 시스템의 이름을 그대로 쓴다(예: `--primary`, `theme.palette.primary.main`). 새 토큰을 만들기 전에 시스템에 같은 것이 있는지 본다.
• 참고 사이트와 시스템이 부딪히면 시스템이 이긴다. 충돌은 design.md `## 우려 사항`에 적는다.

4. 뽑아내기

캡처 이미지는 직접 보고, `styles.json`의 숫자로 확인한다.

• **방향**: 형용사 세 개와 하지 않을 것 세 개.
• **색**: 역할별로 정한다(배경·표면·테두리·본문·보조 글자·주색·주색 위 글자·성공·경고·위험). 값은 많이 쓴 색과 CSS 변수에서 가져온다.
• **대비**: 글자·배경 짝마다 확인한다. 본문은 AA 4.5:1 이상이어야 하고, 미달이면 고친 값을 제안한다.

  node "<이 스킬 폴더>/scripts/capture.mjs" contrast <글자색> <배경색>

• **타이포**: 글꼴 집합과 크기 단계(많이 쓴 크기 5~7개), 줄 높이, 굵기.
• **간격·모서리·그림자**: 기본 단위(많이 쓴 간격이 4나 8의 배수인지)와 단계, 모서리 값(아주 큰 값은 알약 모양), 그림자 두세 단계.
• **컴포넌트**: 버튼(주·보조·텍스트), 입력, 카드, 내비, 표. 각각의 크기와 상태(hover·focus·disabled·loading)를 적는다.
• **레이아웃**: 최대 폭, 그리드·열, 섹션 간격, 브레이크포인트, 모바일에서 바뀌는 것.

5. design.md 쓰기

`references/design-template.md` 형식으로 쓴다. 토큰은 구현에 바로 옮길 수 있게 CSS 변수나 Tailwind theme 이름으로 적는다. 화면별 상태(빈·로딩·오류·권한 없음)를 빠뜨리지 않는다.

사용자에게 보여 주고 승인받으면 제목 아래에 `승인: YYYY-MM-DD`를 적고 커밋한다. 그다음 `writing-plans`에서 화면 Task마다 따를 design.md 절을 적는다. 구현 뒤에는 같은 뷰포트로 스크린샷을 찍어 design.md와 비교한다. impeccable을 켠 프로젝트면 마감 점검은 impeccable에 맡긴다.