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

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에 가독 가능해질 때 전체 생태계가 이익을 얻음

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

요약

핵심 포인트

배경 - AI UI의 "slop" 문제

DESIGN.md 개요

무엇인가 (What it is)

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

자체 DESIGN.md 구축

Team '26에서의 테스트

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

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

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

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

DESIGN.md가 가장 유용한 경우

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

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

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

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

시작하기 및 표준 기여

결론

댓글과 토론

댓글

배경 - AI UI의 "slop" 문제

DESIGN.md 개요

무엇인가 (What it is)

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

자체 DESIGN.md 구축

Team '26에서의 테스트

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

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

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

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

DESIGN.md가 가장 유용한 경우

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

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

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

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

시작하기 및 표준 기여

결론

댓글과 토론