| name | design-md |
| description | 프로젝트 루트의 DESIGN.md(디자인 시스템 단일 소스 오브 트루스)를 만들고 유지한다. 웹 패키지(packages/web)에서 색상, 타이포, 간격, 테마, 컴포넌트 스타일, 다크모드, 디자인 토큰, Tailwind 설정 등 **UI 외형과 관련된 어떤 변경 요청이든** 받으면 반드시 이 스킬을 먼저 트리거해서 DESIGN.md를 먼저 업데이트하고 사용자 확인을 받은 뒤에 실제 코드를 수정한다. "버튼 색 바꿔줘", "폰트 키워줘", "다크모드 톤 조정", "카드 radius 좀 둥글게", "primary 컬러를 파랑으로" 같은 요청은 겉보기엔 단순 CSS 수정이지만 전부 디자인 시스템 변경이므로 이 스킬이 관여해야 한다. DESIGN.md가 아직 없으면 이 스킬이 프로젝트를 스캔해 초안을 만든다. Google Stitch DESIGN.md(2026 오픈소스) 스펙을 따른다. |
DESIGN.md Skill
이 스킬은 "디자인을 바꾸기 전에 디자인 시스템 문서를 먼저 바꾼다" 는 단순한 규율을 강제한다.
UI 코드는 DESIGN.md의 반영물이어야 하고, 그 반대가 되면 프로젝트 전체의 디자인 일관성이 서서히 무너진다.
이 스킬이 언제 동작해야 하나
트리거 조건 (아래 중 하나라도 해당하면 무조건 이 스킬을 먼저 따른다):
packages/web/** 경로의 .vue/.ts/.css 파일에서 외형·스타일을 바꾸는 요청- 색상 팔레트, 브랜드 컬러, 시맨틱 컬러(success/error 등) 변경
- 폰트 패밀리·크기·무게·라인하이트 변경
- 간격 스케일(spacing scale), 컨테이너 max-width, 그리드 규칙 변경
- 모서리 둥글기(radius), 그림자(shadow), 경계선(border) 규칙 변경
- 다크모드/라이트모드 토큰 변경, 테마 토글 동작
- Tailwind 설정(
@theme, tailwind.config), DaisyUI 테마 변경
- 버튼·카드·인풋·모달 같은 공용 컴포넌트의 외형 변경
- "전체적인 디자인 톤을 …로 바꾸고 싶다" 같은 거시적 요청
트리거하지 말 것:
- 단순 버그 수정(레이아웃 깨짐 복구 등) — 기존 규칙을 지키러 가는 중임
- 특정 페이지의 일회성 레이아웃만 만지는 요청(공용 컴포넌트 아님)
- 백엔드/로직/데이터 변경
애매하면 사용자에게 "이 변경은 디자인 시스템 전체에 영향이 있나요, 아니면 이 화면 한정인가요?" 한 줄 질문하고 결정한다.
워크플로우
Phase 0. DESIGN.md 존재 확인
프로젝트 루트(/Users/dongkyl/git/non-tech-ui-poc-workshop/DESIGN.md)에 파일이 있는지 먼저 확인.
- 있으면 → Phase 2로 이동
- 없으면 → Phase 1(초안 생성) 먼저 진행
Phase 1. DESIGN.md 초안 생성 (최초 1회)
DESIGN.md가 없는 상태에서 사용자가 디자인 변경을 요청했다는 건, 지금이 디자인 시스템을 문서화할 적기라는 뜻이다.
- 프로젝트 스캔 — 아래 위치를 읽어 현재 디자인 상태를 파악:
packages/web/nuxt.config.ts, packages/web/app.vue, packages/web/assets/css/*packages/web/app/components/** 중 공용처럼 보이는 파일 3~5개AGENTS.md, packages/web/AGENTS.md — 이미 문서화된 규칙이 있을 수 있음
- Stitch 공식 스펙 재확인 —
references/spec.md를 읽고 8개 섹션 순서·YAML frontmatter 스키마를 숙지한다.
- 실전 예시 참고 —
references/example.md를 읽고 Tailwind·다크모드 매핑 표처럼 프로젝트에 유용한 패턴을 흡수한다.
- 초안 작성 — 아래 "문서 구조" 섹션의 순서를 그대로 따른다. 확신이 없는 값은 비우지 말고 코드에서 실제로 쓰이는 값을 그대로 옮겨 적는다.
- 사용자 확인 — 초안을 간략히 요약해서 보여주고 "이대로 DESIGN.md로 저장하고 원래 요청하신 변경을 반영할까요?" 물어본다. 승인 시 Phase 2로.
Phase 2. 변경 요청 반영 (매번)
사용자가 디자인 변경을 요청했다.
-
영향 범위 식별 — 변경이 DESIGN.md의 어느 섹션(Colors? Typography? Components?)과 어떤 토큰을 건드리는지 명시한다.
-
DESIGN.md 먼저 Edit — YAML frontmatter의 토큰 값과 Markdown 본문의 설명·표를 둘 다 갱신한다. 둘이 어긋나면 AI 에이전트가 혼동한다.
-
사용자 확인:
"DESIGN.md를 다음과 같이 수정했습니다. 맞다고 확인해 주시면 이 규칙에 맞춰 실제 코드(packages/web/...)를 업데이트하겠습니다."
사용자 승인 전에는 웹 패키지 코드를 절대 수정하지 않는다. 이 순서를 뒤집으면 DESIGN.md는 "사후 기록"이 되고 점점 현실과 멀어진다.
-
코드 반영 — 승인 후 DESIGN.md에 적힌 토큰/규칙과 일치하는 방향으로만 수정한다. 변경 중 DESIGN.md에 없는 새 토큰이 필요하면 잠시 멈추고 Phase 2의 1~3단계를 다시 돈다.
-
시각 검증(가능하면) — 프론트엔드 변경은 타입 체크·테스트로는 부족하다. 개발 서버가 이미 떠 있다면 chrome-devtools-mcp 스킬로 라이트/다크 양쪽에서 화면을 확인한다. 없으면 "브라우저 확인은 불가능해서 수행하지 않았다"고 솔직히 보고한다.
Phase 3. 정합성 체크 (선택)
주기적으로, 혹은 "DESIGN.md랑 실제 코드가 일치하는지 봐줘" 같은 요청이 오면:
- DESIGN.md 토큰과
packages/web/**에서 실제 등장하는 Tailwind 클래스를 비교
- 드리프트(예: DESIGN.md엔
blue-500인데 코드엔 blue-400이 섞여 있음) 발견 시 고치지 말고 리포트만 한다. 어느 쪽을 맞출지는 사용자가 결정한다.
문서 구조 (Google Stitch DESIGN.md 스펙 기반)
DESIGN.md는 YAML frontmatter(머신 리더블 토큰) + Markdown 본문(사람과 AI가 모두 읽는 설명) 의 조합이다.
섹션 순서 (필요 없는 섹션은 생략 가능, 단 순서는 유지)
- Overview (또는 "Brand & Style") — 브랜드 성격, 타깃, UI가 줘야 할 감정
- Colors — 팔레트 + 역할 + Hex/Tailwind 매핑
- Typography — 타이포 레벨(headline/body/label 등)과 스타일 값
- Layout (또는 "Layout & Spacing") — 그리드, 브레이크포인트, 간격 스케일
- Elevation & Depth — 그림자 또는 평면 디자인의 위계 표현 방법
- Shapes — 모서리 둥글기 규칙
- Components — 공용 컴포넌트(버튼·칩·인풋 등)의 스타일 토큰
- Do's and Don'ts — 실전 가드레일
YAML Frontmatter 스키마 (필수 루트 필드는 name)
---
version: alpha
name: <프로젝트 이름>
description: <한 줄 설명, 선택>
colors:
<token-name>: '#RRGGBB'
typography:
<token-name>:
fontFamily: <string>
fontSize: <Dimension, px|em|rem>
fontWeight: <number>
lineHeight: <Dimension | number>
letterSpacing: <Dimension, 선택>
rounded:
<scale-level>: <Dimension>
spacing:
<scale-level>: <Dimension | number>
components:
<component-name>:
backgroundColor: '{colors.primary}'
textColor: '{colors.neutral}'
rounded: '{rounded.md}'
padding: 12px
---
토큰 참조 규칙: {path.to.token} 중괄호로 감싸고, 대부분의 그룹에서는 프리미티브 값만 참조한다. components 내부에서는 복합 값({typography.body-md})도 허용된다.
Dimension: px, em, rem 단위만.
컴포넌트 변형(variant): button-primary, button-primary-hover, button-primary-active처럼 하이픈으로 상태를 이어 붙여 별도 키로 정의한다.
Markdown 본문 규칙
- 각 섹션은
## (h2)로 연다. 문서 상단에 # (h1) 제목을 둬도 되지만 섹션으로 파싱되지 않는다.
- 중복
## 헤딩 금지 — 파서가 거부한다(예: ## Colors 두 번).
- 산문은 왜 이 색을/폰트를 쓰는지 맥락을 설명한다. 값 자체는 토큰이 정답이지만, 의도는 산문에만 담긴다.
- 프로젝트가 Tailwind/DaisyUI처럼 프레임워크 특화 매핑을 가진다면, 본문에 표로 "토큰 → Tailwind 클래스 → Hex" 매핑을 반복해 둔다. 중복이지만 AI가 훨씬 잘 쓴다.
상세 스펙과 전체 예시는 references/spec.md. Tailwind 프로젝트용 스타일 팁은 references/example.md.
이 프로젝트의 실제 적용
- DESIGN.md 위치:
/Users/dongkyl/git/non-tech-ui-poc-workshop/DESIGN.md (프로젝트 루트, 고정)
- 주된 소비 패키지:
packages/web/ (Nuxt 4 + TailwindCSS + DaisyUI 구성일 가능성이 높음 — Phase 1에서 실제 확인)
- 관련 문서:
AGENTS.md, packages/web/AGENTS.md가 이미 있다면 중복을 만들지 말고 DESIGN.md에서 "구현·프로젝트 셋업은 AGENTS.md 참고"라고 한 줄 링크한다. DESIGN.md는 "토큰과 규칙"까지다.
- 트리거 대상이 아닌 패키지:
packages/workshop/, packages/asset-generator/ — 이들은 별도 도메인이므로 이 스킬 범위 밖이다.
자주 빠지는 함정
- "작은 색 하나만 바꾸는데 굳이?" — 디자인 시스템은 작은 누수부터 무너진다. 토큰 변경이면 크기 무관하게 이 스킬을 돈다.
- "사용자가 급해 보이니 코드부터 바꾸자" — 그렇게 쌓이면 DESIGN.md가 유명무실해진다. "지금 이 순서로 진행할게요"라고 짧게 안내하고 절차를 지킨다.
- YAML과 Markdown 본문 불일치 — 둘 다 바꿨는지 저장 직전 한 번 더 확인한다. 한쪽만 바뀐 상태는 가장 위험한 상태다.
- 컴포넌트 구현 코드 복붙 — DESIGN.md는 토큰·규칙까지다. 실제
.vue 코드는 packages/web/app/components/**에 둔다.
- 기존 값 삭제 — 값을 "변경"해 달라는 요청에 새 값을 추가만 하면 두 값이 공존한다. 이전 값을 명확히 제거한다.
참고 파일
| 파일 | 언제 읽나 |
|---|
references/spec.md | Phase 1 시작 시, 또는 스키마·섹션 순서가 헷갈릴 때 — Stitch 공식 스펙 |
references/example.md | Phase 1 시작 시 — Tailwind·다크모드 매핑 패턴이 필요할 때 |
