공식 linter를 사용한 DESIGN.md 파일 검사 결과: 1,162개 확인

대부분의 DESIGN.md 파일은 디자인 값을 마크다운 본문에 유지하며, 도구가 확인할 수 있는 토큰 형태로 저장하지 않습니다. 공개 GitHub 리포지토리의 1,162개 DESIGN.md 파일 중 78.1%는 YAML 디자인 토큰이 없는데, 이 형식에서는 선택 사항으로 남아있지만, 그중 747개 파일은 여전히 본문 텍스트에 세 가지 이상의 헥스(hex) 색상을 명시하고 있습니다. 토큰을 가진 254개의 파일 중 88.6%는 해당 형식 자체의 linter를 통과하며 오류가 없었고, 경고가 없는 경우는 단지 8.3%에 불과합니다.

공개 GitHub 리포지토리에 있는 1,162개의 DESIGN.md 파일 중 디자인 토큰을 포함하는 254개 파일을 대상으로, 레지스트리에서 최신 버전으로 읽어와 해당 형식 자체의 linter(버전 0.4.0)로 검사한 결과입니다 (2026년 10월 4일). 하나의 파일이 여러 개의 결과를 보여줄 수 있습니다. 각 항목이 어떻게 계산되었는지는 'How we counted' 섹션에서 확인할 수 있습니다.

레지스트리가 공개 GitHub를 크롤링하여 자체적으로 카운트하고, 해당 형식의 리포지토리의 linter로 검사한 결과이며, 버전 0.4.0으로 고정되었고, 날짜는 2026년 10월 4일입니다.

두 가지 종류의 DESIGN.md

Google Labs에서 발표했으며 알파(alpha) 상태임을 표시하는 이 형식은 DESIGN.md를 두 부분으로 설명합니다: 정확한 디자인 토큰(색상, 타이포그래피, 모서리 둥글기, 간격 및 구성 요소)을 담는 선택적 YAML 프론트 매터와 이를 설명하는 마크다운 본문입니다. 토큰이 존재하는 경우, 레지스트리는 그것들이 규범적인 값(normative values)이라고 명시하고, 산문(prose)은 이들을 적용하기 위한 맥락(context)을 제공합니다.

이름에 'body'를 사용하는 대부분의 파일은 본문만 사용합니다. 1,162개 파일 중 908개(78.1%)는 YAML을 전혀 포함하고 있지 않으며, 이는 프론트 매터(front matter)나 감싸진 YAML 블록 형태로 존재하며 linter가 읽기도 합니다. 이 경우 linter의 유일한 발견 사항은 YAML 내용이 없다는 것입니다. 이는 허용되지만, 값들이 마크다운 본문으로 이동하게 만듭니다: 908개 파일 중 747개(82.3%)는 문장이나 팔레트 테이블 또는 인라인 코드에 세 가지 이상의 헥스 색상 이름을 명시합니다. 파일을 읽는 모델은 이 색상을 사용할 수 있지만, linter는 이를 확인할 수 없으며, 토큰을 CSS나 Tailwind 설정으로 변환하는 형식의 내보내기 명령(export command)도 이를 포함할 수 없습니다. 또한 많은 파일이 공유 템플릿입니다: 1,162개 파일은 단 715개의 고유한 내용을 가지고 있으므로, 이 중 447개는 여기에 계산된 다른 파일과 바이트 단위로 복사된 사본입니다.

토큰을 가진 파일에서 linter가 플래그하는 항목들

토큰이 있는 254개 파일은 대부분 파싱되며: 225개(88.6%)는 오류가 없습니다. 경고(Warnings)는 별개의 문제이며, 아무런 경고가 없는 파일은 21개에 불과합니다. 파일별로 가장 흔한 항목들은 다음과 같습니다:

• 어떤 구성 요소도 참조하지 않는 색상 (A color no component refers to): 103개 파일(40.6%)에서 발견되었습니다. 이 규칙은 구성 요소를 정의하는 파일에만 적용되며, primary나 surface와 같은 표준 색상 계열은 건너뛰므로, 구성 요소가 절대 사용하지 않는 추가 색상을 플래그합니다.
• 하나의 문자열로 작성된 타이포그래피 토큰 (A typography token written as one string): 81개 파일(31.9%)에서 발견되었습니다. 이 형식의 타이포그래피 타입은 fontFamily, fontSize, lineHeight와 같은 속성을 가진 객체입니다. linter 버전 0.4.0은 이러한 문자열을 문자당 하나의 경고로 보고하므로, 이 파일들은 한 가지 실수에 대해 수십 개의 경고를 가질 수 있습니다. 파일별로 계산하면 하나입니다.
• 낮은 대비 (Low contrast): 66개 파일(26.0%)에서 발견되었습니다. 배경색 위에 있는 텍스트 색상이 WCAG AA 최소 기준인 4.5:1 미만인 구성 요소입니다. linter가 확인하는 항목입니다.
• 형식이 정의하지 않은 구성 요소 하위 토큰 (A component sub-token the format does not define): 47개 파일(18.5%)에서 발견되었습니다.
• primary 색상이 없음 (No color named primary): 43개 파일(16.9%)에서 발견되었습니다. linter 메시지에 따르면 에이전트가 자체적으로 주요 색상(key colors)을 생성하게 되는데, 이는 팔레트의 일부를 파일의 통제권 밖에 두게 만듭니다.

오류들

29개의 파일(11.4%)이 최소한 하나의 오류를 가지고 있습니다. 가장 흔한 오류는 형식에서 허용하지 않는 치수이며, 이는 22개 파일에서 발생했습니다: 해당 형식의 치수는 px, em 또는 rem 단위가 붙은 숫자여야 하며, 줄 높이에 대한 normal이나 단순한 0 같은 값은 이 테스트를 통과하지 못합니다. 9개 파일은 linter가 CSS 색상으로 읽을 수 없는 색상을 가지고 있고, 4개 파일은 존재하지 않는 토큰을 참조하며, 1개 파일은 숫자가 아닌 글꼴 두께(font weight)를 가지고 있습니다.

DESIGN.md 자체 검사하기

linter는 npx로 실행되며 그 결과를 JSON 형식으로 출력하고, 각 결과에는 심각도(severity)와 메시지(message)가 포함됩니다. 다음은 주 색상(primary)이라는 이름이 없는 두 가지 색상과 줄 높이가 normal인 타이포그래피 토큰을 가진 빈 DESIGN.md 파일에서 추출된 이 두 필드만 보여주는 출력 예시입니다:

$ npx @google/[email protected] lint DESIGN.md | grep -E '"(severity|message)"'
      "severity": "error",
      "message": "'normal' is not a valid dimension."
...

이 명령어는 오류가 있을 경우 상태 코드 1로 종료되므로 CI에서 검사기로 사용하기에 적합합니다. 버전을 고정하는 것이 좋습니다. 이 형식은 알파(alpha) 버전이며, 규칙은 릴리스 간에 변경될 수 있습니다. 다른 프로젝트의 실제 DESIGN.md 파일은 DESIGN.md 페이지에 있으며, 해당 파일이 무엇을 위한 것인지에 대한 내용은 DESIGN.md란 무엇이고 에이전트가 어떻게 사용하는지에서 확인할 수 있습니다. GitHub의 DESIGN.md가 이미 레지스트리에 있는지, 그리고 그 감사 점수(audit grade)를 확인하려면 체커(checker)에 링크를 붙여넣으세요.

카운트 방법

카운트 방법

레지스트리는 공개 GitHub 저장소에서 에이전트 markdown을 수집하며, 콘텐츠의 SHA-256 해시를 통해 각 파일의 모든 버전을 저장합니다. 이는 핀 설치(pinned install)가 확인하는 방식과 동일합니다. 저희는 DESIGN.md라는 이름의 모든 파일을 가져와 각각의 최신 저장된 버전을 읽고, 그 바이트를 해시 값과 비교한 후, 복사본에 대해 포맷의 linter인 @google/design.md 패키지 버전 0.4.0을 실행했습니다. 파일이 토큰을 갖지 않는 경우는 linter가 YAML 콘텐츠를 찾지 못했다고 보고할 때이며, 텍스트 내에 세 개 이상의 서로 다른 여섯 자리 또는 세 자리 16진수 코드가 나타날 경우 헥스 색상 이름을 갖습니다. 결과는 파일을 기준으로 카운트됩니다: 파일은 해당 규칙이 제공하는 발견 건수가 아무리 많더라도 한 번만 카운트됩니다. 버전 0.4.0의 일부 발견 건수는 규칙 이름이 없습니다; 이들은 메시지를 통해 명명되며, 속성이 숫자인 타이포그래피 발견 건수(토큰이 문자열로 작성된 경우 발생)는 문자열 토큰으로 계산됩니다. 레지스트리는 에이전트 파일을 담고 있는 공개 저장소를 크롤링하며, GitHub 전체가 아니므로 공유 내용은 해당 저장소를 설명하는 것으로 읽어주세요.

출처 (Sources)

• google-labs-code/design.md: DESIGN.md 포맷, 그 명세 및 linter
• WCAG 2.2: 대비 (최소)

마지막 확인일: 2026년 10월 4일. 페이지: https://markdownregistry.com/blog/design-md-files-against-the-official-linter

첫 게시일은 markdownregistry이며, 여기서 카운트가 최신 상태로 유지되고 그 배경 데이터는 dotcomjack/state-of-agent-markdown에서 공개되어 있고, 월별 카운트는 레지스트리 보고서에 있습니다.