토큰이 정답, 본문은 이유
둘이 어긋났을 때 누구를 믿을지 정해둔 규칙
원문 발췌 · L8–8
A DESIGN.md file contains two parts: An optional YAML frontmatter, and a markdown body. The YAML front matter contains machine-readable design tokens. The markdown body sections provide human-readable design rationale and guidance. Prose may use descriptive color names (e.g., "Midnight Forest Green") that correspond to systematic token names (e.g., `primary`). The tokens are the normative values; the prose provides context for how to apply them.앞 챕터에서 파일이 "YAML 토큰 + 마크다운 본문" 두 층으로 나뉜다고 했어요. 이번엔 둘의 내용이 서로 어긋났을 때 어느 쪽을 믿을지 정해둔 규칙을 봐요. 한 줄 결론은 — 토큰이 이깁니다.
왜 이 규칙이 필요한가
본문에는 이렇게 적혀 있어요: "브랜드 컬러는 따뜻한 오렌지를 써요."
그런데 YAML 토큰은: primary: "#DC143C" (크림슨 빨강)
둘이 안 맞네요. 왜? 디자이너가 값을 빨강으로 바꿨는데 본문 설명은 수정을 안 했거든요. 이때 AI 코딩 도구는 어느 쪽을 보고 UI를 만들어야 할까요?
- 본문을 믿으면 → 오렌지 버튼이 나와요. 하지만 최근에 정해진 값은 빨강이라, 디자이너는 "왜 내 값이 반영 안 됐지?" 하게 돼요.
- 토큰을 믿으면 → 빨강 버튼. 본문 설명이 낡은 걸 나중에 고치면 돼요.
스펙은 토큰을 믿는다고 못 박아뒀어요. 본문(= 사람이 쓴 글)은 시간이 지나면 낡기 쉬우니까, 낡을 수 있는 쪽은 참고용으로, 정확한 값은 토큰에서 가져가라는 거예요.
별명과 공식 이름이 같은 걸 가리킨다
L8Prose may use descriptive color names (e.g., "Midnight Forest Green") that correspond to systematic token names (e.g., primary).
본문에서는 "한밤의 숲 녹색"처럼 분위기를 살린 별명을 마음껏 써도 돼요. 대신 토큰(YAML)에서는 primary같은 공식 이름을 쓰고, 두 이름이 같은 색을 가리킨다는 걸 AI가 알 수 있도록 둘을 가까이 배치해요.
본문에 "보스턴 클레이", "골든 리트리버 오렌지" 같은 별명을 자유롭게 써요. 그리고 토큰에는 primary, secondary처럼 역할을 드러내는 공식 이름을 써요. 둘을 연결해 주는 가장 쉬운 방법은 본문 문장에 괄호로 hex를 한 번 더 적어주는 것이에요.
- **Primary (#1A1C1E):** 헤드라인·본문에 쓰는 깊은 먹색.
- **Tertiary (#B8422E):** "보스턴 클레이" — 주요 액션(버튼)에만.AI가 "보스턴 클레이 = #B8422E = tertiary"라는 고리를 바로 잡을 수 있어요.
왜 굳이 이렇게 역할을 나눴을까 — AI 입장에서
AI가 DESIGN.md를 읽고 UI를 만들 때, 보통 토큰과 본문을 같이 봐요. 이때:
- 본문이 풍부하면 → 만들어지는 결과가 풍부해져요. "이 색은 주요 액션에만" 같은 지시가 있으면 AI가 무분별하게 색을 뿌리지 않아요.
- 토큰이 정확하면 → 구현이 정확해져요. hex가 토큰에 박혀 있으니 AI가 값을 추측하다 틀릴 일이 없어요.
역할을 반대로 두면 어떻게 될까요? 예를 들어 hex 값을 본문에만 길게 설명으로 적으면, AI가 글 속에서 hex를 뽑아내다가 헛것을 만들어낼(환각할) 위험이 생겨요. "따뜻한 오렌지 계열"이라는 문장만 보고 AI가 멋대로 #FF7F00을 만들어 버리는 식이죠. 토큰에 정확한 값을 박아두면 이 여지를 없애요.
"기계에게는 정확한 값, 사람에게는 풍부한 설명." 같은 정보를 두 번 적지 말고, 어느 게 진짜 정답이고 어느 게 이유 설명인지를 "위에 YAML / 아래 본문"이라는 위치 자체로 구분해요. 이 아이디어는 API 문서·AI용 시스템 프롬프트·팀 내부 가이드 설계에도 그대로 옮겨 쓸 수 있어요.
체크리스트
- 토큰과 본문이 어긋날 때 어느 쪽이 이기는지, 그리고 그 이유를 말할 수 있다
- 이 우선순위가 왜 "엇박자 방지"에 도움 되는지 설명할 수 있다
- 별명(감성 이름)과 공식 이름(
primary)을 연결하는 관행(괄호에 hex 병기)을 안다 - 같은 "기계용·사람용 층 나누기" 패턴을 쓸 만한 상황을 하나 떠올릴 수 있다