코딩 에이전트에게 “예쁜 UI”를 맡기면 결과는 매번 조금씩 달라진다. 같은 브랜드인데도 버튼 색, 여백, 타이포가 세션마다 흔들린다. google-design-2026 작업에서 붙잡은 질문은 단순했다. 디자인을 에이전트가 다시 읽을 수 있는 하나의 문서로 고정할 수 있는가?

이 글은 Google의 DESIGN.md 형식과, 그 스펙을 Tailwind 테마·토큰으로 옮긴 로컬 워크플로를 정리한 회고다. 제품 출시 공지가 아니라, 실제로 무엇을 남기고 무엇을 버렸는지에 초점을 둔다.

DESIGN.md가 하려는 일

DESIGN.md는 시각 아이덴티티를 코딩 에이전트에게 설명하기 위한 포맷이다. 파일은 두 층으로 나뉜다.

1. YAML 프론트매터 — 색, 타이포, rounded, spacing, 컴포넌트 토큰처럼 기계가 읽을 값
2. 마크다운 본문 — 그 값이 *왜* 존재하는지, 어디에 쓰고 어디에 쓰지 않는지

공식 README의 요지는 명확하다. 토큰은 정확한 값을 주고, 산문은 적용 방식을 준다. 에이전트가 이 파일을 읽으면 “딥 잉크 헤드라인 + 따뜻한 석회 배경 + 단일 액센트 CTA”처럼 한 세트의 판단으로 UI를 맞출 수 있다.

철학 문서가 더 강하게 말하는 지점도 있다. 문장(의도)의 질이 숫자 정밀도보다 생성 품질을 좌우한다. “모던하고 신뢰감 있는 프리미엄” 같은 형용사 나열보다, “오래된 대학의 대학원 세미나 유인물”처럼 구체적 참조 한 줄이 여백·잉크·장식 금지를 함께 실어 나른다. 무엇을 빼는지가 캐릭터를 만든다.

로컬에서 한 일 (워크플로)

로컬 design.md 모노레포는 CLI·린터·예시(DESIGN.md + Tailwind config + DTCG JSON)를 한곳에 두었다. 실무에서 반복한 흐름은 대략 이렇다.

1. 의도 먼저 쓰기 — Overview에 참조 세계와 Don’ts를 적는다.
2. 토큰을 프론트매터에 고정 — primary/secondary/neutral, 타입 스케일, spacing.
3. npx @google/design.md lint — 깨진 참조, 구조, WCAG 대비 등을 JSON finding으로 받는다.
4. Tailwind로보내기 — 예시처럼 tailwind.config / design tokens JSON으로 옮겨 유틸리티가 같은 이름을 쓰게 한다.
5. diff로 회귀 감지 — 토큰·산문 변경이 “조용한 브랜드 붕괴”인지 확인한다.

중요한 운영 규칙 하나: 토큰을 “렌더 명령서”로 과대 해석하지 않는다. 스펙 쪽 관점도 토큰은 맥락이고, 산문이 디자인이다. Tailwind는 그 맥락을 빌드 타임에 붙잡는 다리일 뿐이다.

잘 된 점

• 세션 간 드리프트가 줄었다. 에이전트에게 “이 DESIGN.md를 따르라”고 하면, 색·타입의 중심이 문서에 남는다.
• 리뷰 언어가 생겼다. “느낌이 다르다” 대신 lint finding·token diff로 말할 수 있다.
• 예시 세트(예: Atmospheric Glass)가 온보딩을 짧게 만든다. DESIGN.md → Tailwind → DTCG JSON이 한 폴더에 있으면 설명 비용이 떨어진다.

깨진 점 / 주의

• 형용사만 채운 DESIGN.md는 무용하다. lint를 통과해도 산문이 비면 결과물은 다시 중간값 UI로 돌아간다.
• 컴포넌트 토큰을 Tailwind에 전부 밀어 넣으면 유틸리티 철학과 충돌한다. 예시 README도 컴포넌트 토큰은 JSON 쪽에 두고, Tailwind는 프리미티브에 집중하는 편을 택한다.
• 에이전트는 Don’ts를 잊기 쉽다. 산문에 금지를 쓰고, 체크리스트로 한 번 더 고정하는 편이 안전하다.
• 이 글은 Google 공식 제품 로드맵을 대변하지 않는다. 로컬에서 스펙을 읽고 적용해 본 작업 노트다.

다음에 남길 체크리스트

1. Overview에 구체적 참조 세계가 있는가.
2. 색·타입·spacing 토큰 이름이 산문과 같은 어휘인가.
3. lint를 돌렸고, 대비·깨진 참조를 처리했는가.
4. Tailwind theme이 프론트매터와 이름 단위로 맞는가.
5. 변경 시 diff로 회귀를 남겼는가.

디자인을 “예쁜 스크린샷”이 아니라 에이전트가 다시 실행할 수 있는 계약으로 두는 것. DESIGN.md → lint → Tailwind 연결은 그 계약을 짧고 검증 가능하게 만드는 한 가지 방법이었다.