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/)에 둔다. 아래 순서로 쓸 수 있는 첫 도구를 쓴다.
- 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으로 실행한다.
- REA(Chrome을
--remote-debugging-port=9222로 띄웠을 때): list_browser_targets → capture_web_screenshot(보이는 화면) → inspect_web_page(DOM·리소스 목록). 페이지 JS를 실행하지 않으므로, 계산된 스타일 대신 스타일시트 URL을 받아 CSS 변수와 글꼴을 읽는다.
- 브라우저 도구(Claude in Chrome, 내장 브라우저): 화면 단위로 스크린샷을 찍는다.
- 셋 다 없으면 사용자에게 스크린샷을 받는다.
지키는 것:
- 로그인해야 보이는 페이지, robots·약관이 막는 페이지, 개인 정보가 보이는 화면은 캡처하지 않는다.
- 참고 사이트의 로고·이미지·문구·독자 아이콘은 가져오지 않는다. 가져오는 것은 비율·계층·간격·색 관계 같은 원칙이다. 색 값을 그대로 쓰려면 사용자에게 확인한다.
- 캡처 파일은 git에 올려도 되는 것만 둔다. 크면
.gitignore에 넣고 design.md에 출처만 적는다.
3. 디자인 시스템이 주어졌을 때
- 문서 링크는 열어 읽고(context7이 그 라이브러리를 알면 그쪽), 패키지는 설치된 버전의 테마·토큰 파일을 직접 읽는다. Figma는 연결된 도구가 있으면 쓰고, 없으면 사용자에게 내보낸 토큰이나 스크린샷을 받는다.
- design.md의 토큰은 그 시스템의 이름을 그대로 쓴다(예:
--primary, theme.palette.primary.main). 새 토큰을 만들기 전에 시스템에 같은 것이 있는지 본다.
- 참고 사이트와 시스템이 부딪히면 시스템이 이긴다. 충돌은 design.md
## 우려 사항에 적는다.
4. 뽑아내기
캡처 이미지는 직접 보고, styles.json의 숫자로 확인한다.
5. design.md 쓰기
references/design-template.md 형식으로 쓴다. 토큰은 구현에 바로 옮길 수 있게 CSS 변수나 Tailwind theme 이름으로 적는다. 화면별 상태(빈·로딩·오류·권한 없음)를 빠뜨리지 않는다.
사용자에게 보여 주고 승인받으면 제목 아래에 승인: YYYY-MM-DD를 적고 커밋한다. 그다음 writing-plans에서 화면 Task마다 따를 design.md 절을 적는다. 구현 뒤에는 같은 뷰포트로 스크린샷을 찍어 design.md와 비교한다. impeccable을 켠 프로젝트면 마감 점검은 impeccable에 맡긴다.
1---2name: design-md3description: 화면 작업의 디자인 문서(design.md, 프로젝트 전체면 DESIGN.md)를 만들 때 사용. 참고 사이트 URL·스크린샷을 캡처해 색·글꼴·간격·모서리·컴포넌트 패턴을 뽑거나, 주어진 디자인 시스템(링크·패키지·Figma·기존 DESIGN.md)을 기준으로 삼아 토큰과 화면 규칙을 정한다. Triggers - design.md, 디자인 문서, 이 사이트처럼, 레퍼런스 캡처, 디자인 참고, 디자인 시스템 반영, 스타일 가이드.4metadata:5 source: https://skillmd.com/skills/jh941213/design-md6---78# design-md: 참고·디자인 시스템 → design.md910`spec.md`가 동작과 구조를 정한다면, `design.md`는 보이는 모습을 정한다. 이 스킬은 참고 자료를 실제로 캡처하고 측정해서, 구현자가 그대로 옮길 수 있는 토큰과 규칙으로 바꾼다. 감으로 "모던하게"라고 쓰지 않는다.1112## 1. 입력 확인 (한 번에 묻는다)1314- **범위**: 이번 화면만이면 작업 폴더의 `docs/work/<날짜>-<주제>/design.md`. 프로젝트 전체 디자인 시스템이면 루트 `DESIGN.md`. 루트 `DESIGN.md`가 이미 있으면 그것을 따르고, 이번 화면에서 달라지는 것만 쓴다.15- **참고 사이트**: URL 1~3개, 각각에서 무엇을 가져올지(톤, 레이아웃, 타이포, 색, 특정 컴포넌트).16- **디자인 시스템**: 문서 링크, 패키지(shadcn/ui, MUI, Ant Design, Chakra, Tailwind 테마 등), Figma 링크, 토큰 파일, 기존 DESIGN.md. 있으면 **이것이 기준**이다. 참고 사이트는 톤과 레이아웃에만 쓴다.17- **스크린샷·이미지**: 사용자가 준 파일은 그대로 참고 자료로 쓴다.1819아무것도 없으면 spec.md와 intent.md에서 방향 형용사 세 개를 제안하고 고르게 한다.2021## 2. 캡처 (참고 URL이 있을 때)2223참고 자료는 `docs/work/<주제>/design-refs/`(DESIGN.md면 `docs/design-refs/`)에 둔다. 아래 순서로 쓸 수 있는 첫 도구를 쓴다.24251. **Playwright**(가장 정확): 이 스킬의 `scripts/capture.mjs`.26 ```27 node "<이 스킬 폴더>/scripts/capture.mjs" <url> --out docs/work/<주제>/design-refs28 ```29 - 데스크톱 1440px로 최대 6장, 모바일 390px로 최대 4장을 화면 단위로 찍는다. 스크롤하면서 나타나는 섹션도 찍힌다.30 - `<host>-styles.json`에는 CSS 변수, 주요 요소(body·h1~h3·p·a·button·input·카드·nav)의 계산된 스타일, 많이 쓴 색·글꼴·글자 크기·간격·모서리가 담긴다.31 - Playwright는 이 하네스의 의존성이 아니다. 프로젝트에 없어서 스크립트가 종료 코드 2로 끝나면, 사용자에게 묻고 `npm i -D playwright`를 한다. 번들 브라우저가 없으면 설치된 Chrome으로 실행한다.322. **REA**(Chrome을 `--remote-debugging-port=9222`로 띄웠을 때): `list_browser_targets` → `capture_web_screenshot`(보이는 화면) → `inspect_web_page`(DOM·리소스 목록). 페이지 JS를 실행하지 않으므로, 계산된 스타일 대신 스타일시트 URL을 받아 CSS 변수와 글꼴을 읽는다.333. **브라우저 도구**(Claude in Chrome, 내장 브라우저): 화면 단위로 스크린샷을 찍는다.344. 셋 다 없으면 사용자에게 스크린샷을 받는다.3536지키는 것:37- 로그인해야 보이는 페이지, robots·약관이 막는 페이지, 개인 정보가 보이는 화면은 캡처하지 않는다.38- 참고 사이트의 로고·이미지·문구·독자 아이콘은 가져오지 않는다. 가져오는 것은 비율·계층·간격·색 관계 같은 원칙이다. 색 값을 그대로 쓰려면 사용자에게 확인한다.39- 캡처 파일은 git에 올려도 되는 것만 둔다. 크면 `.gitignore`에 넣고 design.md에 출처만 적는다.4041## 3. 디자인 시스템이 주어졌을 때4243- 문서 링크는 열어 읽고(context7이 그 라이브러리를 알면 그쪽), 패키지는 설치된 버전의 테마·토큰 파일을 직접 읽는다. Figma는 연결된 도구가 있으면 쓰고, 없으면 사용자에게 내보낸 토큰이나 스크린샷을 받는다.44- design.md의 토큰은 그 시스템의 이름을 그대로 쓴다(예: `--primary`, `theme.palette.primary.main`). 새 토큰을 만들기 전에 시스템에 같은 것이 있는지 본다.45- 참고 사이트와 시스템이 부딪히면 시스템이 이긴다. 충돌은 design.md `## 우려 사항`에 적는다.4647## 4. 뽑아내기4849캡처 이미지는 직접 보고, `styles.json`의 숫자로 확인한다.5051- **방향**: 형용사 세 개와 하지 않을 것 세 개.52- **색**: 역할별로 정한다(배경·표면·테두리·본문·보조 글자·주색·주색 위 글자·성공·경고·위험). 값은 많이 쓴 색과 CSS 변수에서 가져온다.53- **대비**: 글자·배경 짝마다 확인한다. 본문은 AA 4.5:1 이상이어야 하고, 미달이면 고친 값을 제안한다.54 ```55 node "<이 스킬 폴더>/scripts/capture.mjs" contrast <글자색> <배경색>56 ```57- **타이포**: 글꼴 집합과 크기 단계(많이 쓴 크기 5~7개), 줄 높이, 굵기.58- **간격·모서리·그림자**: 기본 단위(많이 쓴 간격이 4나 8의 배수인지)와 단계, 모서리 값(아주 큰 값은 알약 모양), 그림자 두세 단계.59- **컴포넌트**: 버튼(주·보조·텍스트), 입력, 카드, 내비, 표. 각각의 크기와 상태(hover·focus·disabled·loading)를 적는다.60- **레이아웃**: 최대 폭, 그리드·열, 섹션 간격, 브레이크포인트, 모바일에서 바뀌는 것.6162## 5. design.md 쓰기6364`references/design-template.md` 형식으로 쓴다. 토큰은 구현에 바로 옮길 수 있게 CSS 변수나 Tailwind theme 이름으로 적는다. 화면별 상태(빈·로딩·오류·권한 없음)를 빠뜨리지 않는다.6566사용자에게 보여 주고 승인받으면 제목 아래에 `승인: YYYY-MM-DD`를 적고 커밋한다. 그다음 `writing-plans`에서 화면 Task마다 따를 design.md 절을 적는다. 구현 뒤에는 같은 뷰포트로 스크린샷을 찍어 design.md와 비교한다. impeccable을 켠 프로젝트면 마감 점검은 impeccable에 맡긴다.