AI로 프론트엔드를 만들 때 가장 자주 보이는 실패는 코드가 아니라 감각에서 납니다. 버튼은 둥글고, 카드는 떠 있고, 그라데이션은 과하고, 어디서 본 듯한 대시보드가 나옵니다. 기능은 대충 맞는데 제품의 얼굴은 사라지는 상태입니다. Atlassian은 이 문제를 “AI UI slop”이라고 부릅니다.
Atlassian이 공개한 DESIGN.md 실험 글 ↗은 그래서 흥미롭습니다. 단순히 “디자인 토큰을 Markdown으로 적자”는 이야기가 아니라, AI 코딩 에이전트에게 디자인 시스템의 값과 의도를 어떻게 읽힐 것인가에 대한 실전 보고서에 가깝습니다.
먼저 결론부터 말하면, DESIGN.md는 MCP나 전용 스킬을 대체하는 만능 디자인 시스템 포맷이 아닙니다. 대신 Claude Code, Cursor, Stitch, Figma Make 같은 서로 다른 환경에 “우리 제품은 이렇게 보여야 한다”는 최소한의 디자인 컨텍스트를 휴대용 파일로 넘기는 데 강합니다.
2026-07-01 · Atlassian 공식 글, Google design.md README, design.md PHILOSOPHY, Atlassian DESIGN.md 스냅숏 기준입니다. design.md 포맷은 아직 alpha입니다.
이 글에서 다루는 내용:
- DESIGN.md가 무엇을 담는 파일인가
- Atlassian이 왜 MCP와 스킬이 있는데도 DESIGN.md를 테스트했는가
- 실제 실험에서 DESIGN.md가 어디까지 효과가 있었고, 어디서 비용이 커졌는가
- 우리 팀이 쓴다면 어떤 용도로 보는 게 현실적인가
DESIGN.md는 디자인 시스템의 압축 파일입니다
Google design.md README ↗는 DESIGN.md를 “coding agent에게 시각적 정체성을 설명하기 위한 포맷”으로 설명합니다. 구조는 단순합니다.
- 위쪽 YAML frontmatter에는 색상, 타이포그래피, spacing, radius, component 같은 기계가 읽기 좋은 디자인 토큰을 둡니다.
- 아래쪽 Markdown 본문에는 색을 왜 이렇게 쓰는지, 레이아웃은 어떤 밀도를 지향하는지, 어떤 UI 패턴을 피해야 하는지 같은 디자인 rationale을 적습니다.
Atlassian이 공개한 파일도 이 구조를 따릅니다. version, revision, theme, name 같은 메타데이터와 함께 색상, 타이포그래피, spacing, rounded 토큰이 들어 있고, 본문에는 Atlassian Design System을 에이전트가 어떻게 해석해야 하는지에 대한 설명이 이어집니다.
중요한 건 DESIGN.md가 Figma 파일이나 컴포넌트 문서 전체의 대체물이 아니라는 점입니다. Google의 PHILOSOPHY 문서 ↗는 토큰 값이 렌더링 지시문이라기보다 컨텍스트에 가깝고, 오히려 구체적인 prose가 가장 중요하다고 말합니다. “modern, clean, premium” 같은 추상 형용사보다 “어떤 화면에서 어떤 밀도와 대비를 유지해야 하는가”가 더 도움이 된다는 뜻입니다.
이 관점은 Google Stitch와 vibe design 흐름과도 맞닿아 있습니다. AI가 화면을 만들 때 필요한 건 멋진 프롬프트 하나가 아니라, 제품이 이미 축적한 디자인 언어를 모델이 읽을 수 있는 형태로 바꾸는 일입니다.
Atlassian은 이미 MCP와 스킬을 갖고 있었습니다
Atlassian 사례가 흥미로운 이유는 “디자인 컨텍스트가 전혀 없는 팀이 Markdown 파일 하나로 해결했다”가 아니기 때문입니다. Atlassian은 이미 Atlassian Design System을 에이전트에게 전달하기 위해 structured content model을 만들고, 그 위에 ADS MCP 서버와 AI 스킬을 운영하고 있었습니다.
MCP와 스킬의 장점은 온디맨드입니다. 에이전트가 버튼을 만들어야 하면 버튼 관련 guidance만 가져오고, 토큰이 필요하면 필요한 토큰만 조회합니다. Atlassian 글에서는 ads_plan 같은 도구를 예로 들며, 모든 아이콘과 모든 semantic token을 한 번에 컨텍스트에 넣지 않아도 된다는 점을 강조합니다.
그럼에도 DESIGN.md를 테스트한 이유는 이식성 때문입니다. 모든 도구가 Atlassian 내부 MCP를 쓸 수 있는 것은 아닙니다. 어떤 환경에서는 파일 하나를 붙여 넣거나 프로젝트 루트에 두는 방식이 가장 빠릅니다. DESIGN.md는 이 상황에서 “최소한의 브랜드 감각과 UI 패턴을 전달하는 portable context”가 됩니다.
flowchart TD
A[사용자 요청] --> B{디자인 컨텍스트 방식}
B --> C[DESIGN.md]
B --> D[MCP / AI Skill]
C --> E[토큰과 디자인 의도를 한 번에 읽음]
D --> F[필요한 컴포넌트와 토큰만 조회]
E --> G[프로토타입 / 낯선 도구 / 고객별 테마]
F --> H[프로덕션 코드 / 기존 컴포넌트 사용 / 린트]이건 Claude Code Memory에서 다룬 CLAUDE.md와 닮았습니다. CLAUDE.md가 프로젝트의 개발 맥락을 에이전트에게 알려주는 파일이라면, DESIGN.md는 제품의 시각적 맥락을 알려주는 파일입니다. 둘 다 핵심은 “사람이 알고 있는 암묵지를 모델이 읽을 수 있게 만드는 것”입니다.
프로토타입에서는 효과가 바로 보였습니다
Atlassian은 Team ‘26 keynote에서 Figma Make로 Teamwork Graph 기반 대시보드를 만드는 데 DESIGN.md를 붙여 테스트했습니다. 결과는 단순한 default 출력보다 Atlassian의 색, 간격, 형태, 타이포그래피, elevation에 훨씬 가까웠다고 설명합니다.
이 장면에서 DESIGN.md의 장점이 잘 보입니다. 내부 MCP가 없는 도구, 빠르게 화면 방향을 잡아야 하는 프로토타입, 고객별 브랜드가 필요한 대시보드 같은 곳에서는 완전한 컴포넌트 API보다 “어떤 느낌을 유지해야 하는지”가 먼저 필요합니다.
특히 AI가 만든 UI가 자꾸 일반적인 SaaS 대시보드처럼 흐를 때, DESIGN.md는 모델의 기본 취향을 제품의 취향으로 끌어당기는 역할을 합니다. 이것만으로도 초기 탐색 단계에서는 충분히 가치가 있습니다.
프로덕션 코드에서는 MCP와 스킬이 더 강했습니다
다만 Atlassian의 프로덕션 코드베이스 테스트에서는 DESIGN.md의 한계도 분명했습니다. Atlassian은 같은 로그인 화면 작업을 여러 컨텍스트 방식으로 비교했습니다. 공식 글의 표를 요약하면 이렇습니다.
| 컨텍스트 방식 | 디자인 컨텍스트 반영 | 평균 토큰 | 평균 시간 | 평균 턴 |
|---|---|---|---|---|
| 없음 | 약 5% | 4.20M | 6분 19초 | 43.0 |
| ADS MCP | 약 80% | 3.75M | 5분 01초 | 35.1 |
| ADS Skill | 약 80% | 4.43M | 5분 23초 | 36.0 |
| DESIGN.md | 약 30% | 7.21M | 6분 46초 | 45.3 |
Atlassian도 이 결과가 논문식 벤치마크는 아니라고 선을 긋습니다. 그래도 실무 신호는 명확합니다. 파일 하나로 모든 디자인 컨텍스트를 한 번에 주입하면 편하지만, 프로덕션 코드에서는 토큰 비용과 탐색 비용이 커질 수 있습니다.
이 차이는 Figma MCP와 AI 에이전트 디자인에서 다룬 문제와도 연결됩니다. 프로덕션에서는 디자인을 “분위기”로만 전달하면 부족합니다. 기존 컴포넌트, 접근성 규칙, lint rule, 패키지 import 방식, 금지 패턴까지 함께 전달되어야 합니다.
Atlassian은 특히 세 가지 한계를 짚습니다.
첫째, DESIGN.md는 all-at-once 방식입니다. 에이전트가 지금 필요한 컴포넌트가 버튼 하나뿐이어도 파일에 담긴 토큰과 설명을 크게 읽을 수 있습니다. 반면 MCP는 필요한 guidance만 가져올 수 있습니다.
둘째, 파일을 짧게 만들수록 중요한 사용 가이드가 빠집니다. Atlassian의 DESIGN.md는 약 80KB, 약 19,800 tokens 규모입니다. frontmatter를 제외해도 약 10,700 tokens입니다. 하지만 내부 MCP와 스킬은 약 2.5MB 규모의 guidance를 필요할 때 압축해서 전달합니다. 공개 DESIGN.md를 만들기 위해 50개 이상의 컴포넌트 사용 가이드와 낮은 사용 빈도의 토큰을 줄였다는 점도 중요합니다.
셋째, DESIGN.md는 에이전트가 컴포넌트를 “가져다 쓰는” 대신 “다시 만드는” 방향으로 흐르게 할 수 있습니다. 실제 프로덕션에서는 @atlaskit/button 같은 기존 컴포넌트를 import해 쓰는 것이 맞는데, 디자인 외형만 설명하면 모델이 비슷한 버튼을 직접 구현할 수 있습니다. 그래서 Atlassian은 MCP/스킬과 함께 디자인 시스템 ESLint rule을 조합해 품질을 보완한다고 설명합니다.
그래서 어디에 써야 할까
DESIGN.md는 “AI 프론트엔드 개발의 새 표준”이라기보다 “디자인 컨텍스트의 휴대용 최소 단위”로 보는 게 정확합니다.
잘 맞는 용도는 다음과 같습니다.
- 낯선 도구에서 빠르게 브랜드 감각을 맞춰야 하는 프로토타입
- 고객별 테마나 white-label UI처럼 제품별 변주가 필요한 화면
- Figma Make, Stitch, Claude Code, Cursor 등 서로 다른 도구에 같은 디자인 방향을 전달해야 하는 상황
- 디자인 시스템 전체를 연결하기 어려운 외부 협업 또는 실험 환경
반대로 프로덕션 코드에서는 DESIGN.md만으로 충분하지 않습니다. 기존 컴포넌트 사용법, 패키지 import, 접근성 규칙, 테스트, lint, 금지 패턴은 MCP나 스킬, 문서 검색, 정적 분석 규칙으로 보강해야 합니다. Atlassian의 실험에서도 가장 안정적인 결과는 DESIGN.md가 아니라 ADS MCP와 ADS Skill 쪽이었습니다.
실무적으로는 이렇게 나누는 편이 좋습니다.
DESIGN.md: 제품의 시각적 언어와 디자인 의도를 빠르게 전달하는 파일MCP: 필요한 컴포넌트 문서와 토큰을 작업 중에 조회하는 도구AI Skill: 반복 작업 절차와 팀 규칙을 압축해 전달하는 실행 지침lint/test: 모델이 실수해도 자동으로 잡아내는 품질 게이트
이 조합이 중요한 이유는 AI가 더 많은 UI를 만들수록 “그럴듯한 화면”과 “우리 제품다운 화면”의 차이가 커지기 때문입니다. 디자인 시스템은 사람만 읽는 문서에서, 에이전트가 실행 중에 참조하는 인터페이스로 바뀌고 있습니다.
DESIGN.md는 CLAUDE.md의 디자인 버전입니다
개발자 입장에서 가장 쉬운 비유는 CLAUDE.md입니다. 프로젝트 루트의 CLAUDE.md가 코드베이스의 구조, 명령어, 금지 사항, 선호 패턴을 알려준다면, DESIGN.md는 UI의 색, 밀도, 형태, 컴포넌트 철학, 피해야 할 분위기를 알려줍니다.
다만 둘 다 파일 하나로 끝나지는 않습니다. 좋은 CLAUDE.md가 테스트와 CI를 대체하지 않듯, 좋은 DESIGN.md도 디자인 시스템과 컴포넌트 문서를 대체하지 않습니다. 대신 에이전트가 첫 화면을 엉뚱한 방향으로 시작하지 않게 해주는 초깃값입니다.
Atlassian의 공개가 의미 있는 이유는 여기 있습니다. AI가 코드를 쓰는 시대에는 디자인 시스템도 사람이 보는 문서, Figma에 갇힌 토큰, 웹사이트의 컴포넌트 예시만으로는 부족합니다. 모델이 읽고, 도구가 조회하고, lint가 검증할 수 있는 형태로 디자인 지식이 재구성되어야 합니다.
DESIGN.md는 그중 가장 가볍고 이식성 높은 형식입니다. 프로토타입에는 바로 쓸 수 있고, 프로덕션에는 MCP와 스킬로 이어지는 입구가 됩니다. 이제 프론트엔드 팀이 물어야 할 질문은 “AI가 화면을 만들 수 있나”가 아니라 “AI가 우리 제품의 디자인 언어를 제대로 읽고 있나”에 가까워졌습니다.