개요
YAML 디자인 토큰과 Markdown 설명을 결합한 디자인 형식을 정의합니다. 유효성 검사와 차이 비교를 위한 명령줄 도구를 제공하여 코딩 에이전트가 디자인 시스템을 지속적으로 이해할 수 있게 합니다.
README 미리보기
# DESIGN.md\n\nA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.\n\n## The Format\n\nA DESIGN.md file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells them *why* those values exist and how to apply them.\n\n```md\n---\nname: Heritage\ncolors:\n primary: "#1A1C1E"\n secondary: "#6C7278"\n tertiary: "#B8422E"\n neutral: "#F7F5F2"\ntypography:\n h1:\n fontFamily: Public Sans\n fontSize: 3rem\n body-md:\n fontFamily: Public Sans\n fontSize: 1rem\n label-caps:\n fontFamily: Space Grotesk\n fontSize: 0.75rem\nrounded:\n sm: 4px\n md: 8px\nspacing:\n sm: 8px\n md: 16px\n---\n\n## Overview\n\nArchitectural Minimalism meets Journalistic Gravitas. The UI evokes a\npremium matte finish — a high-end broadsheet or contemporary gallery.\n\n## Colors\n\nThe palette is rooted in high-contrast neutrals and a single accent color.\n\n- **Primary (#1A1C1E):** Deep ink for headlines and core text.\n- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.\n- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.\n- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.\n```\n\nAn agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.\n\n## Getting Started\n\nValidate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.\n\n```bash\nnpx @google/design.md lint DESIGN.md\n```\n\n```json\n{\n "findings": [\n {\n "severity": "warning",\n "path": "components.button-primary",\n "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 FAQ (5)
문제 해결@google/design.md의 css-tailwind 내보내기에서 git diff --check를 실패하게 만드는 불필요한 후행 개행을 어떻게 수정하나요?
@google/design.md@0.3.0에서 serializeTailwindV4()는 이미 후행 개행 하나를 추가하지만, CLI는 console.log()를 사용하므로 개행이 하나 더 추가됩니다. css-tailwind 내보내기 출력에서 console.log(output)을 process.stdout.write(output)으로 교체하여 익스포터를 수정하세요. 수정 사항이 포함된 릴리스가 제공될 때까지 내보낸 후 생성된 파일을 정규화하세요:
./node_modules/.bin/designmd export --format css-tailwind DESIGN.md \
| perl -0pe 's/\n+\z/\n/' > out.css파일이 정확히 하나의 개행으로 끝나는지 확인하세요:
python3 -c "from pathlib import Path; b=Path('out.css').read_bytes(); print(len(b)-len(b.rstrip(b'\\n')))"예상 결과는 1입니다. 이렇게 하면 git diff --check와 같은 엄격한 공백 검사가 체크인된 생성 CSS에서 실패하는 것을 방지할 수 있습니다.
how_toDESIGN.md에서 디자인 토큰을 네이티브 CSS custom properties로 내보내려면 어떻게 해야 하나요?
css-vars 내보내기 형식을 사용하세요:
npx @google/design.md export --format css-vars DESIGN.md > design.tokens.css이 명령은 CSS 사용자 정의 속성을 포함하는 :root 블록을 생성합니다. 예시:
:root {
--color-primary: #1A1C1E;
--spacing-md: 16px;
}모든 변수에 네임스페이스 접두사를 추가하려면 --prefix를 사용하세요:
npx @google/design.md export --format css-vars --prefix ds DESIGN.md > design.tokens.css다크 테마 및 미디어 쿼리 변형은 초기 구현에 포함되지 않았으며, PR #109에서 지원이 추가되었습니다.
informational양자 컴퓨팅을 쉽게 설명하면 무엇인가요?
일반 컴퓨터는 1(켜짐) 또는 0(꺼짐) 상태인 비트를 사용합니다. 양자 컴퓨터는 결과가 측정될 때까지 중첩(superposition)이라고 하는 결합된 상태로 존재할 수 있는 큐비트를 사용합니다. 이를 통해 양자 컴퓨터는 특정 복잡한 계산에서 여러 가능성을 한 번에 탐색할 수 있지만, 단순히 일반 컴퓨터의 더 빠른 버전은 아닙니다.
문제 해결@google/design.md lint를 실행할 때 발생하는 "raw.match is not a function" 오류는 어떻게 해결하나요?
이 충돌은 DESIGN.md의 spacing 값이 unit: 8과 같은 YAML 비문자열 값일 때 @google/design.md@0.2.0에서 발생합니다. 런타임 타입 가드 수정이 포함된 v0.3.0으로 업그레이드하세요. 임시 해결 방법으로 모든 치수 값을 따옴표로 묶으세요:
spacing:
unit: "8"
"1": "4px"따옴표 없이 unit: 8 또는 unit: 8px를 사용하는 대신 unit: "8px"를 사용하세요.
문제 해결Color와 Dimension 타입 정의를 spec-config.yaml에서 데이터 주도 방식으로 만들려면 어떻게 해야 하나요?
v0.4.0으로 업그레이드하세요. 이 버전에서는 원시 타입이 spec-config.yaml에서 렌더링됩니다. 변경 사항을 수동으로 적용하는 경우, 다음 예시와 같이 types 섹션을 추가하세요:
types:
Color:
description: "A color value is any valid CSS color string."
formats:
- "Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA"
- "Named colors: red, cornflowerblue, transparent"
- "Functional: rgb(), rgba(), hsl(), hsla(), hwb()"
- "Wide-gamut: oklch(), oklab(), lch(), lab()"
- "Mixing: color-mix(in srgb, ...)"
note: "All color values are internally converted to sRGB for WCAG contrast checking."
Dimension:
description: "A dimension value is a string with a unit suffix."
units: [px, em, rem]그런 다음 spec.mdx에서 정적으로 작성된 Color 및 Dimension 설명 텍스트를 제거하고, typography_properties를 렌더링하는 방식과 동일하게 spec-config.yaml의 types를 순회하도록 spec 생성기를 업데이트하세요. spec-config 및 spec-generator 테스트를 실행하여 출력을 확인하세요.