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

> Clean Markdown view of GeekNews topic #30990. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=30990](https://news.hada.io/topic?id=30990)
- GeekNews Markdown: [https://news.hada.io/topic/30990.md](https://news.hada.io/topic/30990.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-07-01T09:39:01+09:00
- Updated: 2026-07-01T09:39:01+09:00
- Original source: [atlassian.com](https://www.atlassian.com/blog/ai-at-work/atlassians-design-md-is-here-what-we-learned-testing-portable-design-context-in-practice)
- Points: 10
- Comments: 0

## Topic Body

- 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 포맷](https://github.com/google-labs-code/design.md), 팀의 브랜드와 UI 패턴을 담은 이식형 스냅샷  
- 파일에 포함해 프롬프트에 넣으면 생성 결과물이 자사 제품처럼 보이기 시작하는 단순한 작동 원리  
- ## 무엇인가 (What it is)  
  - [디자인 시스템의 핵심 요소만 기술](https://stitch.withgoogle.com/docs/design-md/overview)한 이식형 Markdown 파일  
  - 첫 부분은 기계 판독용으로 **디자인 토큰** 나열  
  - 둘째 부분은 사람·에이전트 판독용으로 색상·간격·레이아웃·elevation·컴포넌트 등 **디자인 근거** 기술  
- ## 무엇이 아닌가 (What it isn't)  
  - 프로덕션에서 디자인 시스템이 작동하는 전체 기술 명세나 시스템의 완전한 세부 정보가 아님  
  - 기존 코드 라이브러리, 코딩 표준 유지용 linter, Figma의 상세 디자인 명세는 포함하지 않음  
  - 명세는 이 포맷을 시스템의 전체 세부가 아닌 [**의도(intent)** 포착](https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md)으로 규정  
  
### 자체 DESIGN.md 구축  
  
- Atlassian은 [MCP 서버](https://www.npmjs.com/package/%40atlaskit/ads-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**](https://atlassian.design/DESIGN.md)에 공개  
- 자사 파일은 현재 표준과 일부 차이, 컴포넌트 렌더링용 비표준 속성 포함, 표준이 테마링을 미지원해 [**별도 다크 모드 변형**](https://atlassian.design/DESIGN.short.md) 제공  
- GitHub에 피드백 공유, 일부 제안이 이미 명세에 반영됨, 업계 전반의 동참 권장  
  
### 결론  
  
- DESIGN.md는 디자인 시스템의 스냅샷으로서 유용한 이식 포맷이나, 더 풍부한 디자인 시스템 도구의 대체재는 아님  
- 에이전트가 MCP나 skills를 지원하면 더 낮은 비용으로 더 나은 결과 제공  
- 크로스 플랫폼 이식, 고객 테마링, blue-sky 프로토타이핑에서는 잘 구조화된 DESIGN.md가 의미 있는 향상 제공  
- 디자인 시스템이 AI에 가독 가능해질 때 전체 생태계가 이익을 얻음

## Comments



_No public comments on this page._