Atlassian의 DESIGN.md 공개 — 이식 가능한 디자인 컨텍스트를 실전 테스트하며 얻은 교훈

AI가 만드는 UI는 왜 다 비슷해질까? Atlassian이 자사 디자인 시스템을 AI에 그대로 흘려보내는 단일 파일을 공개하면서 들쑤셔진 진짜 문제는 "기능은 작동하는데 브랜드가 없는 slop"이었습니다. DESIGN.md는 그 slop 문제를 풀기 위해 태어났지만, 실전 적용에서 예상 못한 비용과 한계도 함께 드러났습니다.

AI UI의 "slop" 문제 — 왜 모든 결과가 비슷하게 보일까

AI가 UI를 생성하면 그라디언트 버튼, 대문자 제목, 일반적인 카드 레이아웃, 군더더기 호버 애니메이션이 끝없이 반복됩니다. 기능은 작동하지만 의도된 디자인 결정이 빠진 출력물 — 디자인 커뮤니티는 이를 slop이라 부릅니다. 원인은 명확합니다. AI는 학습 데이터의 평균값으로 기본 출력하기 때문에, 브랜드·컴포넌트·패턴에 대한 컨텍스트가 없으면 "Generic in, generic out"이 됩니다.

Atlassian 디자인 시스템 팀은 이 문제를 AI 시대의 컨텍스트 엔진 부족으로 정의하고, ADS MCP 서버와 구조화된 AI skills로 에이전트에 풍부한 디자인 컨텍스트를 제공해 왔습니다. 수천 명의 제품 빌더가 생성하는 결과물의 정확도와 토큰 비용을 동시에 잡은 인프라였죠.

DESIGN.md란 무엇인가 — 한 파일에 디자인 시스템의 "의도"를 담다

DESIGN.md는 Google의 Stitch 디자인 도구를 위해 설계된 오픈소스 Markdown 포맷입니다. GitHub 저장소에 명세가 공개되어 있고, 핵심 아이디어는 단순합니다.

• 기계 판독용 디자인 토큰과 사람/에이전트가 읽는 디자인 근거(rationale) 두 부분으로 구성
• 프로덕션에서 디자인 시스템이 작동하는 전체 기술 명세가 아니라 의도(intent) 만 담음
• 프롬프트에 파일을 통째로 넣으면 생성 결과물이 자사 제품처럼 보이기 시작

흥미로운 점은 "무엇이 아닌가"를 명시했다는 겁니다. 코드 라이브러리, 코딩 표준용 linter, Figma의 상세 디자인 명세는 포함하지 않습니다. 의도를 포착하는 포맷이지 시스템 전체의 사양서가 아니라는 게 PHILOSOPHY.md에 적혀 있습니다.

Team '26 키노트 데모에서 검증된 효과

한 달 전 Anaheim에서 마무리된 Team '26 키노트가 첫 실전 시험대였습니다. 한 데모에서 Figma Make가 Teamwork Graph로 대시보드를 생성했는데, 내부 MCP 서버나 도구 없이 한 번에 디자인 언어를 정렬하는 게 목표였습니다.

DESIGN.md를 적용하니 일반적인 slop이 색상·간격·형태·타이포그래피에 기대값을 사용하고, 컴포넌트에 시스템 정렬된 elevation을 적용하는 인식 가능한 Atlassian 결과물로 전환됐습니다. Tailwind·Shadcn 같은 공통 라이브러리를 커스터마이징해 UI를 처음부터 생성하는 데도 적합했고, 원샷 프로토타입에서 양호한 성능을 보였습니다.

프로덕션 적용에서 드러난 3가지 한계

데모와 프로덕션은 다른 문제입니다. 사용자 로그인 화면 같은 단순 작업에서 DESIGN.md를 유일한 디자인 가이드로 쓰면 토큰 약 92% 추가 소비, 더 긴 생성 시간, 실행 간 토큰 변동 약 2.7배가 관측됐습니다. 단, 이 수치는 모델·프롬프트·디자인 시스템·환경에 따라 달라진다는 점은 기억해 둘 필요가 있습니다.

한계 1 — 컨텍스트가 온디맨드가 아니라 한 번에 전달된다

MCP 서버는 ads_plan 같은 tool call로 특정 컴포넌트에 대한 지침만 온디맨드로 가져옵니다. 수백 개 아이콘과 방대한 시맨틱 디자인 토큰에서 불필요한 항목 로딩을 피하는 거죠. 반면 DESIGN.md는 매번 전체를 로드하기 때문에 시작부터 높은 비용과 느린 응답이 발생하고, 적은 턴에서 컨텍스트가 잘리면 정확도도 떨어집니다.

한계 2 — 파일을 짧게 유지하면 컨텍스트가 손실된다

디자인 시스템은 수천 개 뷰와 Figma 파일, 프론트엔드 컴포넌트의 공유 언어를 압축한 복잡한 대상입니다. 온디맨드 MCP와 skills는 약 2.5 MB 지침으로 증류되지만, DESIGN.md는 한 번에 로드되므로 훨씬 더 축소해야 합니다. Atlassian 결과물은 80 KB, 약 19,800 LLM 토큰(frontmatter 제외 약 10,700)으로 커뮤니티 예시 대비 큰 편이었습니다.

50개 이상 컴포넌트의 사용 지침 상당 부분과 기초 지침을 대폭 축소하고, 저사용 디자인 토큰 일부를 삭제한 결과였죠. 컨텍스트가 빠지면 프로덕션 품질을 노리는 에이전트는 정확도가 떨어지거나, 명세에 없는 사용 지침을 찾으려 컴포넌트 구현을 직접 읽기 시작합니다.

한계 3 — 명세가 디자인 시스템 내부를 노출한다

DESIGN.md는 디자인 시스템을 산문으로 재작성한 이식형 스냅샷입니다. 확립된 프로덕션 환경에서는 이 정보가 오히려 에이전트를 기술 부채 생성으로 유도합니다. 버튼의 backgroundColor·textColor·borderColor를 읽고 해석하기보다 기존 컴포넌트를 import해 쓰는 편이 낫습니다.

// ❌ DESIGN.md가 유도하는 안티패턴


// ✅ 권장 — 기존 컴포넌트 import
import Button from '@atlaskit/button';

공유 컴포넌트를 쓰면 버튼을 한 곳에서 바꿀 때 코드베이스 전체에 반영되고, 리뷰와 유지보수가 쉬워집니다. MCP 서버와 skills는 재구현 안내가 아니라 기존 시스템 사용 설명서 역할을 하고, 토큰 소비 없이 코딩 표준을 강제하는 lint 규칙과 결합할 때 비로소 긍정적 피드백 루프가 생깁니다.

DESIGN.md가 가장 빛을 발하는 4가지 시나리오

DESIGN.md는 만능이 아닙니다. 기존 디자인 시스템 도구가 사용 불가하거나 비실용적인 환경에서 특히 가치 있습니다.

• 고수준 예술적 방향 — 시스템의 시각적 방향과 느낌만 집중해 문서화하는 용도. 다만 frontmatter는 이미 코드베이스에 있는 내용을 중복할 수 있어 주의가 필요합니다.
• 익숙하지 않은 환경에서의 빠른 프로토타이핑 — blue-sky 프로토타이핑이나 신규 도구 테스트 시 전체 기술 스택이나 기존 컴포넌트 제약 없이 온브랜드 UI를 만들 수 있습니다.
• 디자인 도구와의 상호운용성 — 일부 AI 도구는 디자인 언어에 맞춰진 사전 제작 컴포넌트를 커스터마이징해 UI를 조립합니다. DESIGN.md가 이런 도구에 적합한 수준의 지침을 제공합니다.
• 적응형 UI를 위한 고객 테마링 — 리포트·차트·대시보드 등 동적 인터페이스가 필요한 제품에서 고객이 자사 브랜드를 쉽게 기술하도록 지원합니다. 관리자나 브랜드 팀이 업무 도구에 업로드하는 옵션으로 구상할 수 있습니다.

시작하기 — 표준을 쓰는 게 아니라 만드는 쪽에 서라

Atlassian은 자사 DESIGN.md 파일을 atlassian.design/DESIGN.md에 공개하면서 한 발 더 나갔습니다. 표준에 반응하는 게 아니라 형성하는 쪽에 서겠다는 의도였죠. Atlassian 파일은 현재 표준과 일부 차이가 있고, 컴포넌트 렌더링용 비표준 속성을 포함합니다. 표준이 테마링을 미지원해 별도 다크 모드 변형을 함께 제공합니다.

정리 — 슬롭을 줄이려면 컨텍스트 엔진을 설계하라

DESIGN.md는 디자인 시스템의 이식형 스냅샷으로서 유용하지만, 풍부한 디자인 시스템 도구의 대체재는 아닙니다. 에이전트가 MCP나 skills를 지원하면 더 낮은 비용으로 더 나은 결과를 얻을 수 있고, DESIGN.md는 크로스 플랫폼 이식·고객 테마링·blue-sky 프로토타이핑에서 의미 있는 향상을 제공합니다.

핵심 교훈은 이겁니다. 디자인 시스템이 AI에 가독 가능해질 때 전체 생태계가 이익을 얻는다는 것. 그리고 그 가독성을 단일 파일로 환원하려 하면 비용과 정확도 트레이드오프가 따라온다는 것. 가장 좋은 출발점은 자사 디자인 시스템에서 AI 컨텍스트 엔진을 별도 파이프라인으로 운영하는 것이고, DESIGN.md는 그 파이프라인의 산출물 중 하나로 보는 게 맞습니다.