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

• AI가 생성하는 UI가 브랜드 정체성 없이 일반화되는 "slop" 문제를 해결하기 위한 이식 가능한 Markdown 포맷으로, 디자인 시스템의 핵심 요소를 한 파일에 담아 프롬프트에 포함하는 방식
• DESIGN.md는 기계 판독용 디자인 토큰과 사람·에이전트가 읽는 디자인 근거(rationale) 의 두 부분으로 구성, 시스템의 전체 기술 명세가 아닌 의도(intent) 를 담음
• Team '26 키노트 데모에서 Figma Make 대시보드 생성에 적용한 결과, 색상·간격·형태·타이포그래피가 Atlassian 시스템에 맞게 정렬되며 원샷 프로토타입에서 양호한 성능
• 다만 프로덕션 코드베이스에서는 자체 MCP 서버·skills 대비 토큰 약 92% 추가 소비, 생성 시간 증가, 실행 간 토큰 소비 변동 약 2.7배로 효율 저하
• 이식성·간결성이라는 고유 강점은 크로스 플랫폼 이식, 고객 테마링, 신규 환경 프로토타이핑에 가치 있으며, 풍부한 디자인 시스템 도구의 대체가 아닌 보완재로 자리매김

배경 - AI UI의 "slop" 문제

• AI가 UI를 생성하면 그라디언트 버튼, 대문자 제목, 일반적 카드 레이아웃, 불필요한 호버 애니메이션 등 결과물이 비슷해지는 경향, 기능은 작동하나 시각적 정체성이 결여됨
• 디자인 커뮤니티는 이런 결과물을 "slop" 으로 지칭, 기능적이지만 의도된 디자인 결정이 없는 출력물
• 원인은 브랜드·컴포넌트·패턴에 대한 컨텍스트 부재로, AI가 학습 데이터 평균값으로 기본 출력 → "Generic in, generic out"
• Atlassian 디자인 시스템 팀은 AI 시대를 위한 컨텍스트 엔진 구축 중이며, ADS MCP 서버와 상세 AI skills를 통해 에이전트에 풍부한 디자인 컨텍스트 제공
  • 이를 통해 AI 토큰 비용 절감과 수천 명의 제품 빌더가 생성하는 결과물의 정확도·품질 향상 확인

DESIGN.md 개요

• Google이 자사 Stitch 디자인 도구를 위해 설계한 오픈소스 Markdown 포맷, 팀의 브랜드와 UI 패턴을 담은 이식형 스냅샷
• 파일에 포함해 프롬프트에 넣으면 생성 결과물이 자사 제품처럼 보이기 시작하는 단순한 작동 원리

• 무엇인가 (What it is)

  • 디자인 시스템의 핵심 요소만 기술한 이식형 Markdown 파일
  • 첫 부분은 기계 판독용으로 디자인 토큰 나열
  • 둘째 부분은 사람·에이전트 판독용으로 색상·간격·레이아웃·elevation·컴포넌트 등 디자인 근거 기술

• 무엇이 아닌가 (What it isn't)

  • 프로덕션에서 디자인 시스템이 작동하는 전체 기술 명세나 시스템의 완전한 세부 정보가 아님
  • 기존 코드 라이브러리, 코딩 표준 유지용 linter, Figma의 상세 디자인 명세는 포함하지 않음
  • 명세는 이 포맷을 시스템의 전체 세부가 아닌 의도(intent) 포착으로 규정

자체 DESIGN.md 구축

• Atlassian은 MCP 서버, 구조화된 콘텐츠 파이프라인, 다양한 에이전트 skills를 통해 디자인 시스템을 AI 소비용으로 준비해 온 상태
• MCP·에이전트 skills를 구동하는 동일한 구조화 콘텐츠 파이프라인에서 자체 DESIGN.md 생성
• 일반적인 vibe coding 도구에서 포맷 테스트, 기존 가이드에 없던 흔한 실수에 대해 더 엄격한 지침 추가

Team '26에서의 테스트

• 한 달 전 Anaheim에서 마무리된 Team '26 키노트 데모가 적합한 테스트 사례로 활용됨
• 키노트의 한 데모에서 Figma Make가 Teamwork Graph를 사용해 맞춤형 대시보드 생성, 내부 MCP 서버·도구에 의존하지 않고 한 번에 디자인 언어 정렬을 목표
• DESIGN.md 적용 시 일반적 "slop"에서 색상·간격·형태·타이포그래피에 기대값을 사용하고 컴포넌트에 시스템 정렬된 elevation을 적용하는 등 인식 가능한 Atlassian 결과물로 전환
• 파일의 고수준 지침·명세는 Tailwind, Shadcn 같은 공통 라이브러리를 커스터마이징해 UI를 처음부터 생성하는 데 적합

프로덕션 적용 시 트레이드오프

• 프로덕션 코드베이스는 기존 토큰·컴포넌트 라이브러리, 엄격한 lint 규칙과 타입 검사가 적용된 환경으로 처음부터 만드는 격리 환경과 크게 다름
• 사용자 로그인 화면 같은 단순 작업에서 DESIGN.md를 유일한 디자인 가이드로 사용 시 토큰 약 92% 추가 소비, 더 오랜 생성 시간, 실행 간 토큰 소비 변동 약 2.7배 기록
  • 단, 이 결과는 결정적이지 않으며 모델·프롬프트·디자인 시스템·환경·컨텍스트 품질에 따라 달라질 수 있음을 명시

• 한계 1 - 컨텍스트가 온디맨드가 아닌 한 번에 전달

  • MCP 서버는 ads_plan 같은 tool call로 특정 컴포넌트에 대한 지침만 온디맨드로 가져옴
  • 수백 개 아이콘, 방대한 시맨틱 디자인 토큰 등 무거운 부분에서 불필요한 항목 로딩을 방지
  • DESIGN.md는 매번 전체를 로드해 시작부터 높은 비용·느린 응답, 적은 턴에서 컨텍스트 잘림 발생으로 정확도 저하 가능

• 한계 2 - 파일을 짧게 유지하면 컨텍스트 손실

  • 디자인 시스템은 수천 개 뷰·Figma 파일·프론트엔드 컴포넌트의 공유 언어를 압축한 복잡한 대상
  • 온디맨드 MCP·skills는 약 2.5 MB 지침으로 증류, DESIGN.md는 한 번에 로드되므로 훨씬 더 축소 필요
  • 결과 파일은 80 KB, 약 19,800 LLM 토큰(frontmatter 제외 약 10,700)으로 커뮤니티 예시 대비 큰 편
  • 이 크기를 맞추기 위해 50개 이상 컴포넌트의 사용 지침 상당 부분 제거, 기초 지침 대폭 축소, 저사용 디자인 토큰 일부 삭제
  • 컨텍스트 누락으로 프로덕션 품질을 목표로 하는 에이전트는 정확도가 떨어지거나 스스로 컨텍스트 수집, 명세에 없는 사용 지침을 찾으려 컴포넌트 구현을 직접 읽는 경향 관찰

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

  • DESIGN.md는 디자인 시스템을 산문으로 재작성한 이식형 스냅샷으로, 시스템을 처음부터 복제 구현하기 위한 원칙·명세·지침 제공 목적
  • 확립된 프로덕션 환경에서는 이 정보가 불필요하거나 에이전트를 기술 부채(tech debt) 생성으로 유도, 특히 컴포넌트에서 두드러짐
  • 버튼 스타일링 전체 세부(backgroundColor, textColor, borderColor 등)를 읽고 해석하기보다 기존 컴포넌트를 import해 사용하는 편이 바람직
    • 예: import Button from '@atlaskit/button'; 후 <Button appearance="primary" spacing="compact" />
  • 공유 컴포넌트 사용은 유지보수에 필수, 버튼을 한 곳에서 변경하면 코드베이스 전체에 반영되고 코드 리뷰·유지보수가 쉬워짐
  • DESIGN.md는 코드 지침을 의도적으로 제외하고 재구현 명세만 제공해, 테스트에서 기존 시스템 사용보다 컴포넌트를 재생성하는 경향이 더 큼
  • MCP 서버·skills는 기술 기반에 근거해 더 나은 추상화 수준 제공, 재구현 안내가 아닌 기존 시스템 사용 설명서 역할
  • 이를 토큰 소비 없이 코딩 표준을 강제하는 lint 규칙과 결합해 에이전트에 긍정적 피드백 루프 형성

DESIGN.md가 가장 유용한 경우

• 고수준 예술적 방향 (High-level artistic direction)

  • 가장 단순한 DESIGN.md는 시스템의 시각적 방향·느낌에 집중, 이를 문서화하지 않았다면 유용한 산출물
  • 단, frontmatter는 이미 코드베이스에 있는 내용을 중복

• 익숙하지 않은 환경에서의 빠른 프로토타이핑

  • blue-sky 프로토타이핑이나 신규 도구 테스트 시 전체 기술 스택 구성이나 기존 컴포넌트 제약 부담 없이 온브랜드 UI 생성 지원

• 디자인 도구와의 상호운용성 (Interoperability)

  • 일부 AI 도구는 디자인 언어에 맞춰진 사전 제작 컴포넌트를 커스터마이징해 UI를 조립, DESIGN.md가 이런 도구에 적합한 수준의 지침 제공

• 적응형 UI를 위한 고객 테마링 (Customer theming)

  • 리포트·차트·대시보드 등 동적 인터페이스 생성이 필요한 제품에서 고객이 자사 브랜드를 쉽게 기술하도록 지원, AI 출력이 고객 브랜드처럼 느껴지게 함
  • 관리자나 브랜드 팀이 업무 도구에 업로드하는 옵션으로 구상 가능
• 이들의 공통점은 기존 디자인 시스템 출력이 사용 불가하거나 비실용적인 환경에서의 에이전트 생성 UI라는 범위

시작하기 및 표준 기여

• Atlassian은 표준에 반응하기보다 형성하고자 자사 DESIGN.md 파일을 atlassian.design/DESIGN.md에 공개
• 자사 파일은 현재 표준과 일부 차이, 컴포넌트 렌더링용 비표준 속성 포함, 표준이 테마링을 미지원해 별도 다크 모드 변형 제공
• GitHub에 피드백 공유, 일부 제안이 이미 명세에 반영됨, 업계 전반의 동참 권장

결론

• DESIGN.md는 디자인 시스템의 스냅샷으로서 유용한 이식 포맷이나, 더 풍부한 디자인 시스템 도구의 대체재는 아님
• 에이전트가 MCP나 skills를 지원하면 더 낮은 비용으로 더 나은 결과 제공
• 크로스 플랫폼 이식, 고객 테마링, blue-sky 프로토타이핑에서는 잘 구조화된 DESIGN.md가 의미 있는 향상 제공
• 디자인 시스템이 AI에 가독 가능해질 때 전체 생태계가 이익을 얻음