lint — 파일 검사

DESIGN.md 레포는 CLI(명령줄 도구)를 같이 제공해요. 그중 가장 먼저 배울 건 lint — 파일을 검사해서 문제를 찾아주는 명령이에요.

기본 사용법

# 파일 경로를 넘겨서 검사
npx @google/design.md lint DESIGN.md

# 포맷 지정 (현재는 json만)
npx @google/design.md lint --format json DESIGN.md

# 파이프로 넘기기 — 파일을 표준입력으로
cat DESIGN.md | npx @google/design.md lint -

마지막 줄의 -는 "파일 경로 대신 표준 입력(stdin)에서 받아"라는 관례예요. 다른 명령의 출력을 바로 넘길 때 편해요.

결과 종류 (severity) 3단계

error가 있을 때만 CI 빌드가 막힌다는 뜻이에요. warning은 쌓여도 릴리스를 막지 않아 실용적이에요.

결과 예시

{
  "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 }
}

findings는 발견한 문제들의 목록, summary는 몇 개씩 나왔는지 요약이에요. AI 도구가 이 JSON을 읽고 "에러 0, 경고 1 → 통과"를 판단할 수 있어요.

코드에서 직접 호출

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

const report = lint(markdownString);
report.findings;       // 발견한 문제들
report.summary;        // 개수 요약
report.designSystem;   // 파싱된 토큰 트리

Node 스크립트에서 파일 없이 문자열로 바로 호출할 수 있어요. designSystem은 이미 파싱된 토큰 트리라, AI 에이전트가 이걸 받아서 바로 UI를 만들 수 있어요.