design-md · DESIGN.md 디자인 계약 워크플로우

design-md · DESIGN.md 디자인 계약 워크플로우은(는) 무엇을 하나요?

「디자인 결정」을 분산된 스타일 코드에서 추출하여 DESIGN.md로 정리합니다. 이는 AI 에이전트와 사람 모두가 읽을 수 있는 디자인 계약입니다. 이 스킬은 완전한 폐쇄 루프를 제공합니다:

연구(선택적 네트워킹) → 정제(extract) → 생성(scaffold) → 코드에 적용 → 검증(verify) → CI 게이트

DESIGN.md는 Google Stitch에서 제안한 개념입니다: 프로젝트 루트 디렉토리에 있는 순수 텍스트 디자인 시스템 문서로, 이를 읽은 모든 AI 코딩 에이전트가 일관된 시각적 UI를 생성할 수 있습니다. AGENTS.md는 "어떻게 구축할지"를, DESIGN.md는 "어떻게 보일지"를 담당합니다.

디렉토리 구조

위치	용도
scripts/wcag.py	WCAG 2.1 대비 엔진: tokens.css / design-tokens.json을 파싱하고, 규칙에 따라 페어링을 자동으로 계산(텍스트 4.5:1, UI 3:1)하며, 종료 코드를 CI 게이트로 직접 사용할 수 있음
scripts/extract.py	임의 URL에서 디자인 토큰 초안 추출(색상 순위 / 폰트 스택 / 모서리 둥글기), tokens-draft.json + DESIGN.draft.md 스켈레톤 생성
scripts/scaffold.py	토큰 JSON으로부터 tokens.css(이중 형식 토큰) + tailwind.extend.js + preview.html 시각적 카탈로그 + 대비 보고서를 한 번에 생성
scripts/fetch_ref.py	awesome-design-md에서 참조 DESIGN.md를 가져옴(84개 브랜드, raw → gh api 이중 채널 폴백)
scripts/research.py	DeepSeek Search/Fetch를 사용한 네트워크 연구(유료 직결, 기본적으로 비활성화됨: 사용자의 명시적 동의 후 --yes-billing 필요; 키는 로컬 파일/환경 변수에서 읽으며, 절대 표시되지 않음)
references/spec.md	DESIGN.md 파일 규격: frontmatter + YAML 토큰 + 11개 섹션 본문 + 작성 규칙
references/lessons.md	교훈 모음집: 이중 형식 토큰, 알파 희석 함정, accent 분할, 데이터 계약 등(실제 프로덕션 감사 결과)
references/research.md	DeepSeek Search/Fetch API 사용법 + awesome-design-md 참조 라이브러리 목차(84개 slug 전체)
references/verify.md	검증 체크리스트 + CI 연결 템플릿(npm script / GitHub Actions)
templates/design-tokens.example.json	바로 실행 가능한 입력 예제(이중 테마, 모두 AA 통과), 이를 기준으로 수정

빠른 시작

# 0) 환경: python3 ≥ 3.9, 표준 라이브러리만 사용
python3 scripts/wcag.py --help

# 1) 연구(선택 사항): 참조 사이트에서 토큰 초안 추출
python3 scripts/extract.py --url https://example.com --out-dir ./design-draft
#    → design-draft/tokens-draft.json + design-draft/DESIGN.draft.md

# 2) 잘 알려진 브랜드의 DESIGN.md를 참조용으로 가져오기(영감용, 표절 금지)
python3 scripts/fetch_ref.py --list                 # 84개 slug 확인
python3 scripts/fetch_ref.py --slug linear.app      # → ./DESIGN.reference-linear.app.md

# 2b) (선택 사항) DeepSeek 네트워크 연구 – 유료 직결(5위안/1000회 성공 요청), 기본적으로 비활성화됨:
#     사용자가 명시적으로 동의한 경우에만 --yes-billing을 사용하여 실행; 키는 로컬 파일에서 제공되며, 대화/로그에 절대 표시되지 않음
python3 scripts/research.py --yes-billing check     # 키 확인(기본 경로: %USERPROFILE%\.deepseek\api_key 읽음)
python3 scripts/research.py --yes-billing search --query "fintech dashboard design site:dribbble.com" --count 8

# 3) 전체 토큰 프로젝트 생성(정리된 tokens JSON을 입력으로 사용)
python3 scripts/scaffold.py --tokens my-tokens.json --out ./design-out
#    → tokens.css / design-tokens.json / tailwind.extend.js / preview.html / contrast-report.txt

# 4) 검증(독립 실행 또는 CI 연결 가능)
python3 scripts/wcag.py --tokens ./design-out/tokens.css     # CSS 입력
python3 scripts/wcag.py --tokens ./design-out/design-tokens.json   # JSON 입력
python3 scripts/wcag.py --pair "#E6E9EF:#0A0C10:4.5"         # 단일 쌍 hex 빠른 확인

표준 워크플로우(에이전트 실행 순서)

1. 요구사항 파악: 프로젝트 현재 상태(DESIGN.md / tokens / 컴포넌트 라이브러리 유무)를 읽고, 테마 방향(다크 모드 우선? 브랜드 색상? 업종 톤 – 금융/개발자 도구/의료…)을 명확히 함.
2. 연구(선택 사항): references/research.md의 방법을 사용하여 디자인 연구 수행 – DeepSeek Search로 참조 사이트 검색(유료 직결 및 기본적으로 비활성화됨: 먼저 사용자에게 비용 안내를 표시하고 명시적 동의를 얻은 후에만 --yes-billing을 사용; 동의가 없으면 항상 내장된 크롤링 사용), DeepSeek Fetch / 내장 크롤링으로 페이지를 Markdown으로 변환하여 세부 분석; awesome-design-md에서 동일 업종의 DESIGN.md를 1-3개 가져와 참조.
3. 정제/초안 작성: extract.py로 초안 생성 → references/spec.md의 11개 섹션 구조에 따라 수동/에이전트가 역할을 병합("200회 등장하는 #5e6ad2"를 "브랜드 주 색상, CTA 및 포커스 링에 사용"으로 변경).
4. 생성: 표준 토큰 JSON으로 정리 → scaffold.py가 전체 프로젝트 파일 세트 생성(사용자에게 효과를 보여주는 미리보기 페이지 포함).
5. 적용: tokens.css / tailwind 매핑을 프로젝트에 연결; 컴포넌트는 DESIGN.md §4의 컴포넌트 규칙에 따라 구현.
6. 검증: wcag.py가 모두 통과 + references/verify.md 체크리스트의 각 항목 확인; CI에 게이트 연결(verify.md 템플릿 참조).
7. 반복: 색상 값 변경 시 → 반드시 wcag.py 재실행, 시각적 감에 의존하지 않음; 디자인 결정 변경 사항은 DESIGN.md에 기록(버전 주석).

하드 규칙(반드시 준수)

1. 대비는 시각적 감각에 의존하지 않음: 모든 색상 변경 시 wcag.py 실행. 텍스트 ≥4.5:1, UI 컨트롤/테두리 ≥3:1.
2. 이중 형식 토큰: 모든 색상은 --x(hex)와 --x-rgb(채널) 두 가지로 동시에 출력해야 함. 그렇지 않으면 Tailwind 불투명도 수정자가 조용히 실패함(자세한 내용은 lessons.md #1 참조).
3. bg-{warn}/10과 같은 알파 희석을 밝은 배경으로 사용하지 않음 – 밝은 배경은 독립적인 토큰(--warn-soft)이어야 함. 실제 테스트 결과, 희석 방식은 밝은 테마에서 대비가 오히려 악화됨.
4. 브랜드 색상은 두 가지로 분할: --accent(텍스트/링크)와 --accent-solid(단색 배경 버튼). 동일한 값이 "어두운 배경 위의 밝은 텍스트"와 "흰색 텍스트 아래의 어두운 배경"이라는 두 가지 ≥4.5:1 조건을 동시에 만족할 수 없음.
5. 상호작용 가능한 경계에는 --border-strong 사용(3:1), --border는 장식적 구분에만 사용.
6. Known Gaps를 정직하게 표시: 추출되지 않은 항목(양식 오류 상태, 밝은 버전, 독점 폰트 대체)은 DESIGN.md에 사실대로 기록하고, 완전한 것처럼 가장하지 않음.
7. 참조 ≠ 표절: awesome-design-md의 분석 대상은 각 브랜드의 공개 CSS 특성입니다. 인용 시에는 그들의 "방법"(계층, 리듬, 트레이드오프)을 읽고, 브랜드 정체성을 가장하지 마십시오. 상업 프로젝트의 경우 상표 및 폰트 라이선스에 주의하십시오.

보안

• API 키를 절대 표시하지 않음. 키 해석 순서: --key-file → 환경 변수 DEEPSEEK_API_KEY → 환경 변수 DEEPSEEK_API_KEY_FILE → 기본 파일 %USERPROFILE%\.deepseek\api_key(사용자가 터미널에서 직접 생성하도록 권장하며, 키는 대화/로그를 거치지 않음). research.py의 모든 출력은 sk-*** 마스킹 처리.
• 과금 보호(기본적으로 비활성화됨, 2026-10 기준): DeepSeek Search/Fetch는 직결 과금 API(각 5위안/1000회 성공 요청; 계정 수준 Search 100 QPS / Fetch 25 QPS). research.py가 --yes-billing (또는 환경 변수 DEEPSEEK_BILLING_CONSENT가 1이 아님) 없이 실행되면 직접 거부(exit 3) – 에이전트는 먼저 사용자에게 비용을 설명하고 명시적 동의를 얻은 후에만 플래그를 추가할 수 있음; opencode 등의 종량제 환경은 기본적으로 동의되지 않은 것으로 간주.
• 키가 설정되지 않은 경우, docstring에서 말하는 "반드시 네트워크 필요"를 가정하지 않음 – extract.py는 로컬 urllib 크롤링을 사용하며, DeepSeek은 단지 개선 사항일 뿐입니다.
• 크롤링은 robots.txt와 접근 빈도를 준수함; extract.py는 기본적으로 최대 5개의 스타일시트를 크롤링하며, 각각 512KB 제한.

다른 기능과의 관계

• awesome-design-md(VoltAgent, MIT): 84개 실제 사이트의 DESIGN.md 분석 모음. 이 스킬은 fetch_ref.py를 통해 한 번에 가져와 사용할 수 있으며; 이는 "참조 자료 라이브러리"이고, 이 스킬은 "워크플로우 엔진"입니다.
• DeepSeek Search/Fetch: https://api.deepseek.com/v1/tools/search|fetch. 디자인 연구 단계의 실시간 웹 검색 및 본문 크롤링(site:/lang:/after: 구문 포함). 요청당 과금(5위안/1000회 성공 요청 – "200 반환 및 결과가 비어 있지 않은" 경우에만 과금되며, 실패/시간 초과/빈 결과는 과금되지 않음). 계정 수준 속도 제한 Search 100 QPS / Fetch 25 QPS(초과 시 429 반환, research.py는 자동으로 백오프 및 재시도). 이 스킬은 scripts/research.py로 래핑된 호출을 제공합니다(키는 절대 표시되지 않음; 기본적으로 비활성화됨 – 사용자의 명시적 동의와 --yes-billing 필요, §보안 참조).
• Google Stitch 공식 lint(선택 사항): npx @google/design.md lint DESIGN.md.