Atlassian DESIGN.md 글을 보고 제일 먼저 든 생각은 이거였다. 이제 DESIGN.md가 “구글이 던진 재미있는 포맷”에서 끝나는 게 아니라, 실제 디자인 시스템을 가진 회사들이 AI UI 작업에 어떻게 붙일지 실험하는 단계로 넘어갔다. 4월에 구글 DESIGN md가 오픈소스 되자 UI 판이 달라졌다를 썼을 때는 포맷 자체가 화제였다. 이번에는 조금 다르다. 포맷이 아니라 운영 방식이 보인다.
Atlassian은 자기들 디자인 시스템, MCP 서버, AI 스킬을 같이 놓고 DESIGN.md가 어디에 맞고 어디서 부족한지 테스트했다. 이게 중요한 이유는 단순하다. AI UI 작업에서 진짜 문제는 “모델이 UI를 못 그린다”가 아니라, 팀이 가진 시각적 판단 기준이 모델에게 안정적으로 전달되지 않는다는 데 있었기 때문이다.
포맷보다 중요한 건 컨텍스트가 이동한다는 점
디자인 시스템이 채팅 밖으로 나온다
AI 코딩 도구로 화면을 만들다 보면 이상한 장면을 자주 본다. 같은 프로젝트인데도 한 번은 SaaS 대시보드처럼 나오고, 다음 번엔 스타트업 랜딩처럼 나온다. 버튼 색도 흔들리고, 카드 간격도 흔들리고, 문장 톤도 매번 달라진다. 사용자가 “우리 서비스 느낌으로”라고 말해도 모델 입장에서는 그게 거의 빈칸이다.
DESIGN.md의 핵심은 그 빈칸을 파일로 줄이는 데 있다. 색상 토큰, 타입 스케일, 간격, 컴포넌트 규칙 같은 값만 넣는 게 아니라, 왜 그 값을 써야 하는지까지 마크다운으로 같이 남긴다. 그러면 에이전트가 단순히 색상표를 읽는 게 아니라, 이 색은 어떤 상황에서만 쓰고, 이 버튼은 어떤 강조 단계인지까지 힌트를 얻는다.
이건 생각보다 실무적이다. Figma 파일이나 디자인 시스템 문서는 사람에게는 좋지만, 코딩 에이전트에게는 매번 잘게 설명해줘야 한다. 반대로 DESIGN.md는 처음부터 에이전트가 읽기 쉬운 단일 컨텍스트 파일을 목표로 한다. 그래서 채팅에 흩어진 취향 피드백을 프로젝트 자산으로 고정하는 느낌이 있다.
MCP와 붙으면 더 이상 문서만은 아니다
Atlassian 사례에서 재밌는 지점은 DESIGN.md를 고립된 문서로만 보지 않았다는 점이다. 자기들 MCP 서버와 AI 스킬 흐름에 같이 넣고 테스트했다. 여기서부터 이야기가 달라진다. 문서 하나를 읽고 끝나는 게 아니라, 에이전트가 디자인 시스템 리소스를 조회하고, 필요한 맥락을 가져오고, 화면 생성 규칙을 더 안정적으로 적용하는 구조가 된다.
나는 이게 AGENTS.md나 프로젝트 룰 파일이 퍼진 흐름과 닮았다고 본다. 처음엔 “모델에게 지침 좀 넣어두자”로 시작하지만, 어느 순간 CI, 리뷰, 자동화, 에이전트 실행 환경과 연결된다. DESIGN.md도 비슷하게 갈 가능성이 있다. 그냥 예쁜 설명서가 아니라, AI UI 작업의 입력 계약서가 되는 쪽이다.
Atlassian 실험이 현실적인 이유
만능 해결책이라고 말하지 않는다
이 글이 좋았던 건 과장하지 않는다는 점이다. Atlassian은 DESIGN.md가 디자인 시스템 전체를 대체한다고 말하지 않는다. 오히려 MCP 서버, AI 스킬, 기존 디자인 시스템 도구 사이에서 어디에 들어가야 하는지 보는 쪽에 가깝다.
이게 맞다. DESIGN.md 하나로 컴포넌트 문서, 접근성 정책, 실제 디자인 검토, 사용자 흐름 판단이 전부 해결되지는 않는다. 특히 큰 조직에서는 디자인 시스템이 이미 코드, 패키지, 문서, 토큰, Figma 라이브러리로 나뉘어 있다. 파일 하나가 그걸 갑자기 통합하긴 어렵다.
다만 작은 팀이나 개인 프로젝트에서는 얘기가 달라진다. 지금 당장 브랜드 시스템이 거대하지 않아도, 반복되는 UI 취향을 한 파일에 정리하는 것만으로 AI 초안 품질이 꽤 달라질 수 있다. 개발자가 매번 “좀 더 밀도 있게”, “카드는 덜 둥글게”, “관리자 화면처럼” 같은 말을 반복하지 않아도 된다.
AI UI의 병목이 프롬프트에서 운영 규칙으로 이동한다
요즘 AI UI 작업을 보면 많은 사람이 프롬프트를 더 잘 쓰려고만 한다. 물론 프롬프트도 중요하다. 그런데 팀 단위로 보면 더 큰 병목은 프롬프트 문장력이 아니라 기준의 재사용성이다. 한 번 잘 나온 화면을 다음 작업에도 이어가려면, 그 판단을 어딘가에 남겨야 한다.
DESIGN.md는 이 지점에서 의미가 있다. “이번 프롬프트가 좋았다”를 넘어서 “우리 팀 UI는 이런 밀도와 이런 대비를 기본값으로 둔다”를 남길 수 있다. 그러면 새 페이지를 만들 때마다 미감이 리셋되는 문제가 줄어든다. AI가 디자이너를 대체한다는 얘기보다, AI에게 줄 기본 업무 환경을 만든다는 얘기에 더 가깝다.
그래도 바로 도입할 때 조심할 것
없는 디자인 시스템을 만들어주지는 않는다
여기서 착각하면 안 되는 게 있다. DESIGN.md는 디자인 시스템을 기록하고 전달하는 포맷이지, 없는 취향을 자동으로 만들어주는 제품은 아니다. 색상, 타이포그래피, 컴포넌트 단계, 여백 기준이 팀 안에서 아직 정리되지 않았다면 파일은 금방 비어버린다.
그래서 처음부터 거창하게 전사 표준을 만들려고 하면 실패할 가능성이 높다. 나는 오히려 작은 화면 하나로 시작하는 게 낫다고 본다. 예를 들어 관리자 대시보드 한 장, 블로그 카드 목록 한 장, 가입 폼 한 장 정도다. 그 화면에서 반복되는 색, 버튼, 카드, 입력창, 경고 상태만 적어도 다음 생성 결과가 꽤 안정된다.
자동화 전에 검증 루프가 필요하다
또 하나는 검증이다. AI가 DESIGN.md를 읽었다고 해서 항상 규칙을 잘 지킨다는 보장은 없다. 그래서 실제 프로젝트에서는 디자인 파일을 넣고 끝내는 게 아니라, 결과 화면을 캡처하고, 토큰 위반이나 접근성 문제를 확인하고, 사람이 한 번 더 보는 루프가 필요하다.
구글 쪽 포맷이 lint, diff, export 같은 방향을 같이 가져가는 것도 이 때문이다. 디자인을 코드처럼 비교하고 검증하려는 흐름이다. 결국 좋은 DESIGN.md는 문서라기보다 테스트 가능한 기준에 가까워져야 한다. 그래야 AI가 만든 UI가 “그럴듯함”을 넘어 팀 기준 안에 들어왔는지 볼 수 있다.
지금 팀에서 해볼 만한 적용 순서
첫 파일은 짧아도 된다
내가 지금 팀에 적용한다면 이렇게 갈 것 같다. 첫째, 현재 가장 자주 만드는 화면 유형을 하나 고른다. 둘째, 그 화면에서 절대 흔들리면 안 되는 규칙만 적는다. 셋째, AI 에이전트에게 같은 요구사항을 DESIGN.md 없이 한 번, 넣고 한 번 다시 시켜본다. 넷째, 차이가 실제로 보이는 규칙만 남긴다.
처음 파일은 길 필요가 없다. 오히려 짧아야 쓸 수 있다. 색상 5개, 폰트 2개, 간격 4개, 버튼 3단계, 카드 규칙 몇 줄이면 충분하다. 중요한 건 “멋진 문서”가 아니라 다음 작업에서 다시 먹히는 기준이다.
운영팀 관점에서는 UI 룰도 런북이 된다
개발 운영 쪽에서 보면 이 흐름이 꽤 익숙하다. 장애 대응 런북, 코드 스타일, PR 규칙, 에이전트 지침 파일이 하는 일이 전부 비슷하다. 사람이 매번 설명하지 않아도 같은 판단을 반복하게 만드는 것. DESIGN.md는 그 사고방식을 UI 쪽으로 가져오는 파일이다.
그래서 Atlassian 실험은 단순한 디자인 뉴스보다 조금 더 크게 보인다. AI UI 작업이 장난감 단계를 지나면, 결국 필요한 건 더 긴 프롬프트가 아니라 재사용 가능한 운영 기준이다. DESIGN.md는 그 기준을 사람이 읽고, 에이전트도 읽고, 언젠가는 자동 검증까지 걸 수 있는 형태로 만들려는 시도다.
참고한 원문
- Atlassian의 DESIGN.md 실험 글
- Google Labs DESIGN.md 저장소
- Google Stitch DESIGN.md 문서
- Atlassian Design System의 DESIGN.md 예시
지금 단계에서 내 결론은 단순하다. DESIGN.md는 AI UI를 자동으로 예쁘게 만들어주는 마법 파일은 아니다. 대신 팀이 이미 갖고 있는 취향과 규칙을 에이전트가 계속 잊어버리지 않게 붙잡아주는 파일이다. 그리고 그 정도만 해도 실무에서는 꽤 크다. 특히 작은 팀, 개인 프로젝트, 에이전트로 화면 초안을 자주 뽑는 팀이라면 이제 프롬프트를 더 길게 쓰기 전에 이 파일부터 짧게 만들어보는 게 낫다.