google-labs-code/design.md

DESIGN.md

코딩 에이전트에게 시각적 아이덴티티를 설명하기 위한 형식 명세입니다. DESIGN.md는 에이전트에게 디자인 시스템에 대한 지속적이고 구조화된 이해를 제공합니다.

형식

DESIGN.md 파일은 기계가 읽을 수 있는 디자인 토큰(YAML front matter)과 사람이 읽을 수 있는 디자인 근거(markdown 산문)를 결합합니다. 토큰은 에이전트에게 정확한 값을 제공합니다. 산문은 그 값이 존재하는 이유와 적용 방법을 알려줍니다.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## 개요

건축적 미니멀리즘과 저널리즘적 위엄의 만남. UI는 프리미엄 무광 마감 — 고급 브로드시트 또는 현대 갤러리를 연상시킵니다.

## 색상

팔레트는 고대비 중성색과 단일 악센트 색상에 기반합니다.

- **Primary (#1A1C1E):** 헤드라인과 핵심 텍스트를 위한 진한 잉크.
- **Secondary (#6C7278):** 테두리, 캡션, 메타데이터를 위한 정교한 슬레이트.
- **Tertiary (#B8422E):** "Boston Clay" — 상호작용의 유일한 동인.
- **Neutral (#F7F5F2):** 순수한 흰색보다 부드러운 따뜻한 석회암 기반.

이 파일을 읽는 에이전트는 Public Sans의 진한 잉크 헤드라인, 따뜻한 석회암 배경, Boston Clay 클릭 유도 버튼이 있는 UI를 생성합니다.

시작하기

DESIGN.md를 명세에 대해 검증하고, 끊어진 토큰 참조를 잡아내고, WCAG 대비비를 확인하고, 구조적 결과를 표면화합니다 — 모두 에이전트가 조치할 수 있는 구조화된 JSON으로 출력됩니다.

npx @google/design.md lint DESIGN.md

{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

디자인 시스템의 두 버전을 비교하여 토큰 수준 및 산문 회귀를 감지합니다:

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

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

명세

전체 DESIGN.md 명세는 docs/spec.md에 있습니다. 다음은 간략한 참조입니다.

파일 구조

DESIGN.md 파일은 두 개의 계층으로 구성됩니다:

1. YAML front matter — 기계가 읽을 수 있는 디자인 토큰, 파일 상단에 --- 구분선으로 구분됩니다.
2. Markdown 본문 — ## 섹션으로 구성된 사람이 읽을 수 있는 디자인 근거.

토큰은 규범적 값입니다. 산문은 이를 적용하는 방법에 대한 맥락을 제공합니다.

토큰 스키마

version: <string>          # 선택 사항, 현재: "alpha"
name: <string>
description: <string>      # 선택 사항
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

토큰 유형

섹션 순서

섹션은 ## 제목을 사용합니다. 생략할 수 있지만, 존재하는 경우 다음 순서로 나타나야 합니다:

|:--|:--------|:--------|

| 2 | Colors | |

| 4 | Layout | Layout & Spacing |

| 6 | Shapes | |

| 8 | Do's and Don'ts | |

컴포넌트 토큰

컴포넌트는 이름을 하위 토큰 속성 그룹에 매핑합니다:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

유효한 컴포넌트 속성: backgroundColor, textColor, typography, rounded, padding, size, height, width.

변형(hover, active, pressed)은 관련 키 이름을 가진 별도의 컴포넌트 항목으로 표현됩니다.

알 수 없는 콘텐츠에 대한 소비자 동작

CLI 참조

설치

npm install @google/design.md

Windows에서는 셸(PowerShell, 일부 터미널)이 @를 특별하게 처리하는 경우 패키지 이름을 따옴표로 묶으세요:

npm install "@google/design.md"

또는 직접 실행합니다 (항상 공개 npm 레지스트리에서 확인):

npx @google/design.md lint DESIGN.md

Windows/PowerShell에서는 이 직접 형식이 출력을 생성하지 않거나 (또는 DESIGN.md를 Markdown 편집기에서 열 수 있습니다) design.md bin 이름의 .md 접미사가 명령 확인 중 Windows Markdown 파일 연결과 충돌하기 때문입니다. 점 없는 designmd 별칭을 대신 사용하세요 — -p로 npx를 패키지에 지정한 다음 designmd를 호출하세요:

npx -p @google/design.md designmd lint DESIGN.md

designmd 심은 동일한 진입점으로 확인되며 모든 플랫폼에서 동일하게 작동합니다.

npm error ENOVERSIONS ("@google/design.md에 사용 가능한 버전이 없습니다")

CLI는 @google/design.md로 npm에 게시됩니다. ENOVERSIONS는 거의 항상 npm이 공개 레지스트리를 쿼리하지 않음을 의미합니다 (.npmrc의 사용자 정의 registry=, 이 패키지를 동기화하지 않은 회사 미러, 또는 @google 범위에 대해 잘못 구성된 @google:registry).

유효한 레지스트리를 확인하세요:

npm config get registry

인터넷에서 정상적으로 설치하려면 https://registry.npmjs.org/여야 합니다. 구성을 수정한 후, 오래된 404가 캐시된 경우 npm cache clean --force로 다시 시도하세요.

모든 명령은 파일 경로 또는 stdin의 경우 -를 허용합니다. 출력은 기본적으로 JSON입니다.

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

>

```jsonc

// package.json

{

"scripts": {

"design:lint": "designmd lint DESIGN.md"

}

}

```

lint

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 -

오류가 발견되면 종료 코드 1, 그렇지 않으면 0.

diff

두 DESIGN.md 파일을 비교하고 토큰 수준 변경 사항을 보고합니다.

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

회귀가 감지되면 종료 코드 1 ("이후" 파일에 더 많은 오류 또는 경고가 있는 경우).

export

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

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

spec

DESIGN.md 형식 명세를 출력합니다 (에이전트 프롬프트에 명세 컨텍스트를 주입하는 데 유용).

npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json

린팅 규칙

린터는 구문 분석된 DESIGN.md에 대해 9개의 규칙을 실행합니다. 각 규칙은 고정된 심각도 수준의 결과를 생성합니다.

프로그래매틱 API

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

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);       // Finding[]
console.log(report.summary);        // { errors, warnings, info }
console.log(report.designSystem);   // Parsed DesignSystemState

디자인 토큰 상호 운용성

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

• Tailwind v3 config (JSON) — npx @google/design.md export --format json-tailwind DESIGN.md — tailwind.config.js용 theme.extend JSON 객체를 내보냅니다. --format tailwind는 하위 호환 별칭입니다.
• Tailwind v4 theme (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 버전입니다. 명세, 토큰 스키마 및 CLI는 활발히 개발 중입니다. 형식이 성숙함에 따라 변경이 예상됩니다.

D

[...생략...]