디자인 시스템 md 3-Layer 토큰 구조

논문 4편을 직접 비교한 결과 SUS를 대체할 수 있는 지표는 NASA-TLX와 UEQ가 가장 일관되게 나타났습니다. 디자인 시스템 md를 실제로 만들면서 Global-Alias-Component 구조를 적용하면 값과 의미, 사용처를 분리할 수 있어 브랜드 변경이나 다크모드 대응이 훨씬 수월해집니다. 틸노트 디자인 틸노트 디자인 시스템과 디지털청은 디자인 시스템을 AI가 읽는 방식으로 Markdown을 배포하며, DESIGN.md 형식은 토큰과 설계 근거를 함께 전달해 일관성을 유지하는 데 도움이 됩니다.
핵심 요약
디자인 시스템 md를 구축할 때 3-Layer 토큰 구조가 왜 필요한지, 접근성과 AI 참조성을 어떻게 확보하는지 실무 사례와 함께 정리했습니다.
목차
- 디자인 시스템 md는 왜 3-Layer 토큰 구조를 기본으로 삼는가?
- 값·의미·사용처를 나누는 이유
- 실제 적용 사례
- 디자인 시스템 md 구축 시 접근성 기준은 토큰 단계에서 어떻게 반영해야 하는가?
- 대비율 계산으로 토큰을 조정하는 단계
- Markdown으로 판단과 예외를 기록하는 방법
- DESIGN.md 형식은 AI가 디자인 시스템을 참조할 때 어떤 이점을 주는가?
- 분할 구조와 단일 파일의 차이
- AI 참조 실무에서의 효과
- 디지털청 디자인 시스템은 Markdown을 어떤 목적으로 배포했는가?
- DESIGN.md에서 YAML front matter는 어떤 정보를 담는가?
- 디자인 시스템에서 버튼을 먼저 만드는 이유는 무엇인가?
- 참고 자료
디자인 시스템 md는 왜 3-Layer 토큰 구조를 기본으로 삼는가?
틸노트 디자인에서 10개 시스템을 분석한 결과, Global-Alias-Component 구조는 원본 값과 의미, 실제 사용처를 분리해 브랜드 변경이나 다크 모드 대응을 크게 단순화합니다.
값·의미·사용처를 나누는 이유
버튼에 blue-700 같은 구체적인 색상값을 직접 연결하면 색이 바뀔 때마다 컴포넌트를 모두 수정해야 합니다. 대신 주요 버튼 배경 같은 역할 이름을 한 단계 거치면 값만 교체하면 됩니다.
실제 적용 사례
Atlassian과 Fluent, Ant Design은 Primitive/Global/Seed, Semantic/Alias/Map, Component/Control로 토큰을 3단계로 나눕니다. 이 구조 덕분에 화면 요소는 “나는 어떤 역할인가”만 알면 되고, 색상표나 다크 모드 값은 별도로 관리할 수 있습니다.
이름은 유지하고 값만 바꾸면 전체 시스템이 일관되게 업데이트됩니다.
디자인 시스템 md 구축 시 접근성 기준은 토큰 단계에서 어떻게 반영해야 하는가?
접근성 기준은 토큰 단계에서 대비율 계산을 통해 미리 반영하고, Markdown으로 설계 판단과 예외 규칙을 명시해야 합니다.

대비율 계산으로 토큰을 조정하는 단계
틸노트 디자인 틸노트 디자인 시스템에서는 WCAG AA 기준인 4.5:1을 목표로 gray-700과 gray-800을 조정했습니다. 원본 대비 gray-700은 56%에서 46%로 낮춰 4.61:1을 확보했고, gray-800은 49%에서 40%로 낮춰 5.74:1을 만들었습니다. 반면 amber-700은 흰 배경에서 1.80:1에 불과해 텍스트 사용을 금지하고 별도 토큰을 새로 만들었습니다.
Markdown으로 판단과 예외를 기록하는 방법
디지털청은 디자인 시스템을 AI가 읽에서는 Figma와 코드만으로는 전달하기 어려운 설계 판단을 Markdown으로 보완합니다. 프라이머리 버튼은 한 화면에 하나만 쓰고, 세컨더리 버튼이 과도하면 플로우 자체를 재검토하라는 예외 규칙을 글로 남겨 AI가 참조할 수 있게 했습니다.
토큰 단계에서 미리 대비율을 계산하고 Markdown으로 규칙을 남겨야 일관된 접근성을 유지할 수 있습니다.
DESIGN.md 형식은 AI가 디자인 시스템을 참조할 때 어떤 이점을 주는가?
DESIGN.md 형식은 AI가 디자인 시스템을 참조할 때 토큰과 설계 근거를 함께 제공해 일관성을 유지하는 데 가장 큰 이점을 줍니다. 디지털청은 디자인 시스템을 AI가 읽을 때 125개 파일을 MANIFEST.md로 정리해 필요한 문서만 골라 읽게 했습니다. 반면 DESIGN.md는 프로젝트 루트에 단일 파일로 두고 YAML front matter에 color, typography, spacing 토큰을 넣고 본문에 그 값을 선택한 이유를 적습니다.
분할 구조와 단일 파일의 차이
- 디지털청 방식은 컴포넌트별로 파일을 나누고 MANIFEST.md로 목차를 제공해 AI가 폼을 만들 때는 버튼·인풋 관련 문서만 참조하게 합니다.
- DESIGN.md는 한 파일 안에 모든 토큰과 근거를 담아 세션이 바뀌어도 같은 규칙을 반복 적용합니다.
AI 참조 실무에서의 효과
토큰은 AI 슬롭을 줄이고, 근거는 디자인 연속성을 지켜줍니다.
이 두 접근은 규모에 따라 선택할 수 있습니다. 작은 프로젝트에서는 DESIGN.md 하나로 충분하고, 대규모 시스템에서는 분할된 Markdown 세트가 더 효율적입니다.
디자인 시스템을 만들면서 고민이 많으셨다면 이번 기록이 조금이라도 도움이 되길 바래요. 실제로 3-Layer 구조를 적용해 보시면 유지보수가 훨씬 수월해질 거예요. 다음 글에서는 v1.0 구현 사례를 자세히 다뤄볼게요.
자주 묻는 질문
디지털청 디자인 시스템은 Markdown을 어떤 목적으로 배포했는가?
디지털청은 Markdown 세트를 AI가 참조할 수 있도록 배포하기 시작했어요. README에는 ‘주로 AI 참조용’이라고 명시되어 있으며, 125개의 파일을 MANIFEST.md로 정리해 AI가 필요한 문서만 골라 읽을 수 있게 구성했습니다. Figma와 코드로는 전달하기 어려운 설계 판단이나 예외 규칙을 글로 남겨 AI 협업을 지원하는 것이 목적입니다.
DESIGN.md에서 YAML front matter는 어떤 정보를 담는가?
각 Markdown 파일 상단의 YAML front matter에는 제목, 카테고리, 문서 유형, 변환 전 URL이 들어 있어요. 이 정보 덕분에 AI는 먼저 MANIFEST.md를 확인하고 필요한 카테고리의 파일만 선택적으로 참조할 수 있습니다. 단순한 텍스트 변환이 아니라 AI가 자료를 효율적으로 탐색할 수 있도록 구조화한 장치입니다.
디자인 시스템에서 버튼을 먼저 만드는 이유는 무엇인가?
버튼은 디자인 시스템의 종합 시험 역할을 하기 때문입니다. 색상 토큰, 텍스트 토큰, 간격 토큰, aria 속성, 키보드 접근성까지 거의 모든 결정이 한 번에 들어가기 때문에 버튼을 제대로 만들면 다른 컴포넌트로 패턴을 확장하기가 수월해집니다.
참고 자료
틸노트 디자인 틸노트 디자인 시스템 (feat. Design.md)tilnote.io
디자인 킬러 DESIGN.md 를 가장 잘 사용하는 워크플로우를 …tonylee.im
디지털청은 디자인 시스템을 AI가 읽도록 하기 시작했다. …note.com

자주 묻는 질문 (FAQ)
디지털청 디자인 시스템은 Markdown을 어떤 목적으로 배포했는가?
DESIGN.md에서 YAML front matter는 어떤 정보를 담는가?
디자인 시스템에서 버튼을 먼저 만드는 이유는 무엇인가?

끝까지 읽어주셔서 감사합니다.
오늘 글이 도움이 되셨다면 필요한 분께 '공유'해 주세요.
UX 논문 트렌드디자인 트렌드논문 요약AI·생성형 UX도구 리뷰


