DESIGN.md
디자인 시스템을 에이전트가 읽는 파일 규격
npx @google/design.md lint DESIGN.md코딩 에이전트에게 시각 정체성을 설명하는 파일 형식과 그 검사 도구입니다. 파일 하나에 기계가 읽는 디자인 토큰을 앞머리 YAML 로 넣고, 그 값이 왜 그런지와 어떻게 쓰는지를 마크다운 산문으로 덧붙입니다. 색과 서체, 모서리, 간격, 컴포넌트를 정해진 자리에 적어 두면 에이전트가 매번 다시 묻지 않고 같은 규칙으로 화면을 만듭니다. CLI 는 규격 준수와 끊어진 토큰 참조를 검사하고 WCAG 대비율까지 계산해 JSON 으로 돌려줍니다. 두 판을 비교해 토큰과 산문이 어떻게 달라졌는지 뽑는 명령도 있습니다.
판단
이럴 때 씁니다
- 에이전트가 만드는 화면이 매번 다른 색과 서체로 나올 때
- 디자인 토큰을 저장소 안에 두고 기계와 사람이 같이 읽게 하고 싶을 때
- 디자인 시스템이 바뀔 때 무엇이 달라졌는지 기록으로 남겨야 할 때
이럴 땐 쓰지 마세요
- 이미 토큰 관리 체계가 자리 잡았다면 형식을 하나 더 들일 이유가 적습니다
- 실제 스타일 코드를 만들어 주지는 않습니다
- 규격이 0.x 단계라 항목이 더 바뀔 수 있습니다
차별점
- 기계용 토큰과 사람용 근거를 한 파일에 함께 둡니다.
- 검사 결과를 에이전트가 바로 처리할 JSON 으로 돌려줍니다.
- 두 판을 비교해 토큰과 산문의 변화를 함께 잡습니다.
워크플로
- 01저장소 최상단에 파일을 만듭니다.
- 02앞머리 YAML 에 색과 서체, 간격, 컴포넌트 토큰을 적습니다.
- 03그 아래 산문으로 각 값의 의도와 사용 규칙을 씁니다.
- 04검사 명령으로 규격 준수와 대비율을 확인합니다.
- 05디자인이 바뀌면 비교 명령으로 달라진 부분을 뽑습니다.
주요 명령
| 명령 | 설명 |
|---|---|
npx @google/design.md lint DESIGN.md | 규격 준수와 끊어진 토큰 참조, 대비율을 검사합니다. |
npx @google/design.md diff DESIGN.md DESIGN-v2.md | 두 판의 토큰과 산문 차이를 뽑습니다. |
함정
설치 전에 확인하세요
- 토큰만 적고 산문을 비우면 에이전트가 값을 언제 쓸지 판단하지 못합니다. 형식이 산문을 함께 요구하는 이유입니다.
- 검사 결과가 JSON 으로 나오고 파일이 없거나 읽히지 않으면 종료 코드 2 로 끝납니다. 자동화에 붙일 때 이 값을 봐야 합니다.
- 규격 버전이 0.x 입니다. 판이 올라가면 항목이 바뀔 수 있으니 파일에 규격 버전을 함께 적어 두는 편이 낫습니다.
- 대비율 검사는 접근성 기준 충족 여부를 알려 주지만 실제 화면의 겹침이나 상태 변화까지 보지는 않습니다.
비교
디자인 토큰 도구는 값을 여러 플랫폼용 코드로 바꿔 내보내는 데 집중합니다. 이쪽은 값을 바꾸는 대신 에이전트가 읽을 설명 계층을 규격으로 만들었습니다. 그래서 기존 토큰 파이프라인을 대체하지 않고 그 앞에 얹는 성격입니다.
최근 변경
0.4.0 에서 없는 파일을 읽을 때 스택 추적 대신 정리된 오류 메시지와 JSON 을 종료 코드 2 로 내보내도록 바뀌었습니다.