google-labs-code/design.md

코딩 에이전트(coding agents)에게 시각적 정체성(visual identity)을 설명하기 위한 형식 사양(format specification)입니다. DESIGN.md는 에이전트에게 디자인 시스템(design system)에 대한 지속적이고 구조화된 이해를 제공합니다.

DESIGN.md 파일은 기계가 읽을 수 있는 디자인 토큰(design tokens, YAML front matter)과 사람이 읽을 수 있는 디자인 근거(design rationale, markdown prose)를 결합합니다. 토큰은 에이전트에게 정확한 값을 제공합니다. 산문(Prose)은 왜 그러한 값이 존재하는지, 그리고 어떻게 적용해야 하는지를 알려줍니다.

---
name: Heritage
colors:
...

이 파일을 읽는 에이전트는 Public Sans 서체의 짙은 잉크색 헤드라인, 따뜻한 석회암 색상의 배경, 그리고 Boston Clay 색상의 콜 투 액션(call-to-action) 버튼을 가진 UI를 생성할 것입니다.

사양(spec)에 따라 DESIGN.md를 검증하고, 깨진 토큰 참조를 포착하며, WCAG 대비율(contrast ratios)을 확인하고, 구조적 발견 사항을 제시합니다. 이 모든 과정은 에이전트가 실행할 수 있는 구조화된 JSON 형식으로 제공됩니다.

npx @google/design.md lint DESIGN.md

{
"findings": [
{
...

토큰 수준 및 산문(prose)의 퇴보(regressions)를 감지하기 위해 디자인 시스템의 두 버전을 비교합니다:

npx @google/design.md diff DESIGN.md DESIGN-v2.md

{
"tokens": {
"colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
...

전체 DESIGN.md 사양은 docs/spec.md에 있습니다.

다음은 요약된 참조(reference)입니다.

DESIGN.md 파일은 두 개의 레이어로 구성됩니다:

YAML front matter— 파일 상단의 --- 구분자로 나뉘는 기계가 읽을 수 있는 디자인 토큰(design tokens).

Markdown body— ## 섹션으로 구성된 사람이 읽을 수 있는 디자인 근거(design rationale).

토큰은 규범적 값(normative values)입니다. 산문은 이를 어떻게 적용할지에 대한 맥락(context)을 제공합니다.

version: <string> # 선택 사항, 현재: "alpha"
name: <string>
description: <string> # 선택 사항
...

타입 (Type) | 형식 (Format) | 예시 (Example)

|---|---|---|
| Color | CSS 색상 값 모두 가능 (hex, rgb() , oklch() , 이름 등) | "#1A1C1E" , `

거의 항상 npm이 퍼블릭 레지스트리 (public registry)를 조회하지 않고 있음을 의미합니다 ( .npmrc 에 설정된 커스텀 registry= , 이 패키지를 동기화하지 않은 기업용 미러 (corporate mirror), 또는 @google 스코프 (scope)에 대해 잘못 설정된 @google:registry 등).

현재 적용된 레지스트리를 확인하세요:

npm config get registry

인터넷을 통한 일반적인 설치의 경우 https://registry.npmjs.org/ 여야 합니다. 설정을 수정한 후, 만약 오래된 404 오류가 캐시되었다면 npm cache clean --force를 사용하여 다시 시도하세요.

모든 명령은 파일 경로 또는 표준 입력 (stdin)을 위한 -를 허용합니다. 출력 기본값은 JSON입니다.

Windows 팁: npx를 통하지 않고 package.json 스크립트에서 CLI를 직접 호출할 때는 design.md 대신 designmd 별칭 (alias)을 사용하세요. 원래 바이너리 이름의 .md 접미사는 Windows의 명령 해석 시 Markdown 파일에 대한 파일 연결 (file association)과 혼동을 일으킵니다. designmd 심 (shim)은 동일한 엔트리포인트 (entrypoint)로 연결되며 모든 플랫폼에서 동일하게 작동합니다.

// package.json
{ "scripts": { "design:lint": "designmd lint DESIGN.md" } }

DESIGN.md 파일의 구조적 정확성을 검증합니다.

npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md
cat DESIGN.md | npx @google/design.md lint -

옵션 (Option)	타입 (Type)	기본값 (Default)	설명 (Description)
file	위치 인자 (positional)	필수 (required)	DESIGN.md 경로 (또는 stdin을 위한 -)
--format	json	json	출력 형식 (Output format)

오류가 발견되면 종료 코드 (Exit code) 1, 그렇지 않으면 0을 반환합니다.

두 개의 DESIGN.md 파일을 비교하고 토큰 수준 (token-level)의 변경 사항을 보고합니다.

npx @google/design.md diff DESIGN.md DESIGN-v2.md

옵션 (Option)	타입 (Type)	기본값 (Default)	설명 (Description)
before	위치 인자 (positional)	필수 (required)	"이전" DESIGN.md 경로
after	위치 인자 (positional)	필수 (required)	"이후" DESIGN.md 경로
--format	json	json	출력 형식 (Output format)

회귀 (regressions)가 감지되면 ( "이후" 파일에서 더 많은 오류 또는 경고가 발생한 경우) 종료 코드 1을 반환합니다.

DESIGN.md 토큰을 다른 형식으로 내보냅니다 (Export).

| 규칙 (Rule) | 심각도 (Severity) | 검사 항목 (What it checks) |
|---|---|---|
| `broken-ref` | error | 정의된 토큰으로 해결되지 않는 토큰 참조 (`{colors.primary}`)
| `missing-primary` | warning | 색상이 정의되어 있으나 `primary` 색상이 존재하지 않음 — 에이전트가 자동으로 생성함 |
| `contrast-ratio` | warning | 컴포넌트의 `backgroundColor` / `textColor` 쌍이 WCAG AA 최소 기준 (4.5:1) 미만임 |
| `orphaned-tokens` | warning | 색상 토큰이 정의되어 있으나 어떤 컴포넌트에서도 참조되지 않음 |
| `token-summary` | info | 각 섹션에 정의된 토큰의 개수 요약 |
| `missing-sections` | info | 다른 토큰이 존재함에도 선택적 섹션 (spacing, rounded)이 누락됨 |
| `missing-typography` | warning | 색상은 정의되어 있으나 타이포그래피 (typography) 토큰이 존재하지 않음 — 에이전트가 기본 폰트를 사용함 |
| `section-order` | warning | 섹션이 명세(spec)에 정의된 표준 순서와 다르게 나타남 |
| `unknown-key` | warning | 최상위 YAML 키가 알려진 스키마 키의 오타로 보임 (예: `colours:` → `colors:`); 커스텀 확장 키는 무시됨 |

린터 (Linter)는 라이브러리로도 사용할 수 있습니다:

import { lint } from '@google/design.md/linter';
const report = lint(markdownString);
console.log(report.findings); // Finding[]
...

DESIGN.md 토큰은 W3C 디자인 토큰 포맷 (Design Token Format)에서 영감을 받았습니다. `export` 명령은 토큰을 다른 형식으로 변환합니다:

**Tailwind v3 설정 (JSON)** — `npx @google/design.md export --format json-tailwind DESIGN.md` — `tailwind.config.js`를 위한 `theme.extend` JSON 객체를 생성합니다. `--format tailwind`는 하위 호환 가능한 별칭 (alias)입니다.

**Tailwind v4 테마 (CSS)** — `npx @google/design.md export --format css-tailwind DESIGN.md` — Tailwind v4의 CSS 변수 토큰 네임스페이스 (`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`)를 사용하는 CSS `@theme { ... }` 블록을 생성합니다.

**DTCG tokens.json (W3C Design Tokens Format Module)** — `npx @google/design.md export --format dtcg DESIGN.md`

DESIGN.md 포맷은 `alpha` 버전입니다.

. 사양 (spec), 토큰 스키마 (token schema), 그리고 CLI는 현재 활발히 개발 중입니다. 포맷이 성숙해짐에 따라 변경 사항이 발생할 수 있습니다.

이 프로젝트는 Google Open Source Software Vulnerability Rewards Program의 대상이 아닙니다.