브랜드 가이드의 독자는 AI, DESIGN.md를 토큰 YAML 2층으로 바꾼 이유

브랜드 가이드를 공들여 썼는데, 정작 그 문서를 가장 자주 읽는 건 제가 아니라 AI였어요. 블로그 카드, SNS 썸네일, 앱 화면 시안을 AI에게 맡기면서 매번 DESIGN.md를 통째로 붙여 넣었거든요. 그런데 돌려 보니 결과가 그때그때 달랐어요. 같은 문서를 줬는데 어떤 날은 파란 계열, 어떤 날은 초록 계열이 나왔죠.

산문 가이드가 AI에게 약한 이유

직접 만들어 보니 문제는 문서의 정성이 아니라 형식이었어요. "차분하고 신뢰감 있는 파랑"이라는 문장은 사람에게는 충분해도 AI에게는 추측할 여지가 너무 넓어요. 게다가 문서가 길수록 매 요청마다 토큰을 잡아먹고, 이미 만들어 둔 컴포넌트를 두고 새로 그리는 일도 생겼어요.

그래서 DESIGN.md를 2층 구조로 바꿨어요. 위층은 YAML로 쓴 시맨틱 토큰, 아래층은 마크다운으로 쓴 사용규칙이에요.

위층: 시맨틱 토큰 5개면 시작돼요

토큰은 이름부터 의미를 담아요. primary, secondary, surface, on-surface, error 이렇게 5개로 시작했어요. 컴포넌트 정의에서는 색 값을 다시 적지 않고 {colors.primary}처럼 참조만 해요.

colors:
  primary: "oklch(0.45 0.09 250)"
  surface: "oklch(0.98 0.005 250)"
  error: "oklch(0.55 0.15 25)"
components:
  button.primary.bg: "{colors.primary}"

적용해 봤더니 AI가 색을 추측하지 않고 토큰 이름을 골라 쓰기 시작했어요. 원시값, 시맨틱, 컴포넌트 3층만 유지하고 토큰을 수십 개로 늘리지는 않았어요. 1인 브랜드가 관리할 수 있는 양이 아니니까요.

아래층: 토큰마다 사용규칙 1줄

토큰 이름만 있으면 언제 쓰는지를 또 추측해요. 그래서 토큰마다 규칙을 딱 1줄씩 붙였어요. "primary는 강조용, 한 화면에 1회", "글꼴 굵기는 한 화면에 2종까지", "간격은 8px 배수만". Do보다 Don't가 더 잘 먹혀서, 카드 한쪽에만 두꺼운 띠를 두는 식의 금지 패턴도 함께 적었어요.

테스트해 보면 이 1줄들이 산문 한 페이지보다 결과를 더 안정적으로 잡아 줘요.

1인 브랜드에서 달라진 것

콘텐츠를 혼자 만들면 채널마다 톤이 흔들리기 쉬워요. 플랜씨(plan-c) 계산기 소개 카드와 플랜비(plan-b) 앱 화면 시안이 같은 토큰을 참조하게 하니, 어디서 봐도 한 브랜드로 읽혀요. 문서를 매번 전량 주입하지 않고 필요한 층만 불러오니 요청도 가벼워졌고요.

옮겨 보니 브랜드 가이드는 읽는 사람이 바뀌면 형식도 바뀌어야 하더라고요. 지금 가이드가 산문뿐이라면, 색 토큰 5개와 규칙 1줄씩부터 떼어 내 보세요. 그 두 층이 다음 시안의 톤을 지켜 줄 거예요.