DESIGN.md — AI 디자인 에이전트가 읽는 디자인 시스템 한 장
Figma·노션·PDF에 흩어진 색·폰트·간격을 YAML+마크다운 한 장에. Stitch·Cursor·Claude Code가 매 화면 같은 룰로 만들어요.
에반
무료
스킬 소개
AI 디자인 에이전트가
매번 다른 화면을 뱉어내요?
DESIGN.md 한 장이면 톤이 잠겨요.
Stitch, Cursor, Claude Code, v0.
AI 도구로 화면을 뽑을 때마다 색도 다르고, 폰트 크기도 다르고,
모서리 둥근 정도도 다 다르게 나와요.
이 스킬은 Google Stitch 팀이 만든 DESIGN.md 규격을 한국어로 풀어 주고,
바로 복붙해서 쓸 수 있는 템플릿과 @google/design.md CLI 사용법까지 정리해 둔 한 묶음이에요.
받아서 프로젝트 루트에 두면, 그때부터 AI가 같은 룰로 그려요.
이런 적, 한 번쯤은 있죠.
"버튼 다섯 개만 다시 만들어 줘."
Stitch에 시켰는데, 첫 화면은 민트, 두 번째 화면은 짙은 초록, 세 번째 화면은 갑자기 파랑이 나와요.
똑같은 프롬프트인데 결과가 매번 달라요.
Figma에는 컬러 토큰, 노션에는 가이드, 메일에는 로고 png. 거기에 디자이너 머릿속의 "이건 좀 부드러운 느낌으로요"까지.
그걸 AI 에이전트에 매번 다시 통역해 줘야 해요.
AI가 매번 다른 화면을 뽑는 게 아니라, 내가 매번 다른 룰을 주고 있던 거예요.
왜 매번 톤이 달라져요?
AI 디자인 에이전트는 "이 프로젝트가 어떤 톤이다"를
코드 어딘가에서 찾아 읽으려 해요. 그런데 그 한 장이 없어요.
결국 매 화면마다 프롬프트 안에 색 hex, 폰트 크기, 둥근 정도를 다시 풀어 적어야 해요.
한두 번이면 참는데, 매 화면이 그러니까 본 작업보다 통역이 길어져요.
디자인 시스템 한 장이다."
그래서 DESIGN.md가 나왔어요.
Google Stitch 팀이 정의한 평문 형식이에요.
README.md가 사람을 위한 거라면, AGENTS.md는 코딩 에이전트용,
DESIGN.md는 디자인 에이전트가 읽는 한 장이에요.
두 층 구조예요. 위쪽 YAML 머리말에는 hex 색, 폰트 속성, 간격 스케일이 토큰으로 들어가고,
아래 마크다운 본문에는 "왜 이 색을 골랐는지" 같은 설명이 들어가요.
AI는 위쪽을 보고 그리고, 사람은 아래쪽을 읽고 합의해요. 디자인이 진화하면 같이 자라는 살아있는 문서예요.
들이면 뭐가 좋은데요?
막연한 약속 말고, 다섯 가지만 콕 짚어 볼게요.
-
AI가 매번 같은 톤으로 그려요.
Stitch, Cursor, Claude Code, v0 같은 도구가 프로젝트 루트의 DESIGN.md를 읽어요. "이 색 써 줘"를 매 프롬프트마다 다시 적지 않아도 같은 결과가 나와요.
-
디자이너와 개발자가 같은 단어를 써요.
토큰 이름이 한 장에 박혀 있어요.
colors.primary-60이 곧 hex이고, 곧 Tailwind 클래스예요. "그 민트 말고 좀 더 어두운 민트요"가 사라져요. -
새 화면 시작이 빨라져요.
"이 프로젝트 분위기로 새 결제 화면 그려 줘"라고만 던지면 AI가 본문을 읽고, 토큰을 들고, 일관된 화면을 한 번에 뱉어요.
-
Tailwind, DTCG로 한 번에 내보내요.
@google/design.md export명령으로 Tailwind config과 DTCG JSON을 뽑아요. 디자인 시스템 한 장을 코드 여러 형식으로 옮길 때 손이 안 묶여요. -
화면 톤 사고가 사전에 잡혀요.
CLI 린터가 깨진 토큰 참조, WCAG 명도비 미달, 외톨이 토큰을 미리 잡아요. 배포 전에 "그 버튼 글씨 안 보이는데요"가 줄어요.
누가 쓰면 좋아요?
안에 뭐가 들어 있어요?
DESIGN.md 한 장은 정해진 8개 섹션으로 채워요.
이 스킬은 그 8개를 한국어로 풀고, 각 섹션을 바로 복붙할 수 있는 템플릿으로 만들어 뒀어요.
타깃과 감정, 톤을 짧게 적어요. "따뜻한 갈색의 동네 카페 앱, 친근하고 둥근 느낌" 한 줄이면 충분해요. 이 단락이 아래 모든 토큰의 근거가 돼요.
관례는 primary · secondary · tertiary · neutral 4계열. 각 계열은 0부터 100까지 톤 스케일을 가질 수 있어요. 전부 sRGB hex로 적어요. 예: "#1A1C1E".
역할 + 크기 변형으로 이름을 정해요. headline-large, body-medium, label-small 같은 식. 각 토큰은 fontFamily, fontSize, fontWeight, lineHeight, letterSpacing을 묶은 객체예요.
몇 칼럼, 어떤 거터, 어떤 간격 단위를 쓰는지 적어요. spacing은 보통 4px, 8px, 12px 같은 단계로 토큰화해서 AI가 여백을 즉흥적으로 정하지 않게 막아요.
버튼·카드·모달의 상하 위계를 그림자 단계로 표현해요. elevation-1, elevation-2 같은 토큰으로 묶고, 본문에는 "왜 얇게 유지하는지"를 한 줄 적으면 좋아요.
rounded.sm, rounded.md, rounded.full 같은 단계로 적어요. 버튼·카드·아바타가 어느 단계를 쓰는지 컴포넌트 섹션에서 다시 가리켜요.
위에서 정의한 토큰을 참조해서 컴포넌트를 정의해요. 참조는 {colors.primary-60}처럼 중괄호 경로로 적어요. AI가 같은 컴포넌트를 매번 같은 모양으로 그려요.
"primary 위에 secondary 텍스트를 쓰지 마세요" 같은 한 줄짜리 규칙. 본문 마지막에 짧게 묶어 두면, AI의 자유 분방한 시도를 막아 줘요.
이렇게 쓰면 돼요.
DESIGN.md를 만드는 길은 세 갈래예요.
셋 중 하나로 시작하고, 나머지 단계는 같아요.
-
한 줄 설명으로 AI에게 맡기기.
Stitch 같은 도구에 "따뜻한 동네 카페 앱, 부드럽고 둥근 느낌" 한 줄을 던져요.
AI가 8개 섹션을 알아서 채워 줘요. 이 스킬에 든 한국어 프롬프트 예시를 그대로 복붙해도 돼요. -
브랜드 자산에서 뽑기.
기존 사이트 URL이나 로고 이미지가 있으면 그걸 입력으로 줘요.
AI가 거기서 팔레트와 폰트, 분위기를 추출해 초안을 만들어요.
이 스킬 안에는 추출 결과를 다듬는 체크리스트가 들어 있어요. -
손으로 직접 적기.
위 YAML 머리말 + 아래 마크다운 본문 구조만 지키면 돼요.
별도 문법은 없어요. 동봉된 빈 템플릿 한 장을 그대로 채워 가면 30분 안에 첫 버전이 나와요. -
CLI로 검증하고 내보내기.
터미널에서
npx @google/design.md lint로 깨진 토큰 참조와 명도비를 잡아요.
npx @google/design.md export --format tailwind로 Tailwind config을,--format dtcg로 DTCG JSON을 뽑을 수 있어요.
Node.js 18 이상이면 별도 설치 없이 실행돼요.
파일만 두고 CLI 없이 쓰는 것도 가능해요. AI 도구는 마크다운만 있어도 읽어요.
린터가 잡아 주는 8가지.
npx @google/design.md lint 한 줄이면 결과가 JSON으로 나와요.
배포 전에 토큰이 깨졌는지, 글씨가 안 보이는지 미리 잡아 줘요.
-
broken-ref · error
토큰 참조가 실제로 정의돼 있지 않을 때 잡아요. 유일한 error 등급이라 빌드 전에 무조건 고쳐야 해요.
-
missing-primary · warning
colors 섹션에 primary 이름이 없으면 경고해요. AI가 보통 primary부터 찾기 때문에 이 이름이 비면 톤이 흔들려요.
-
contrast-ratio · warning
컴포넌트의 배경과 글씨 명도비가 WCAG AA 4.5:1 미만이면 경고해요. 배포 전에 글씨 안 보이는 사고가 미리 잡혀요.
-
orphaned-tokens · warning
정의는 했지만 어떤 컴포넌트도 참조하지 않는 토큰을 짚어 줘요. 쓰지 않는 토큰이 쌓이면 시스템이 점점 흐려져요.
-
missing-typography · warning
colors는 있는데 typography 토큰이 비어 있을 때 알려 줘요. 글씨 룰이 없으면 AI가 폰트 크기를 즉흥적으로 정해요.
-
section-order · warning
8개 섹션 순서가 정규(overview → colors → typography → layout → elevation → shapes → components → do/don't)에서 벗어나면 경고해요.
-
missing-sections · info
spacing이나 rounded 같은 선택 섹션이 비어 있을 때 정보 등급으로 알려 줘요. 큰 프로젝트에선 채우면 일관성이 올라가요.
-
token-summary · info
섹션별 토큰 개수를 요약해 줘요. "color 토큰만 38개 쌓였네"처럼 시스템이 비대해지는 징후를 감지할 수 있어요.
자주 묻는 질문.
npm install @google/design.md 또는 npx @google/design.md ...로 실행해요. 파일만 두고 쓰는 거라면 설치 자체가 필요 없어요. 지울 땐 DESIGN.md 파일만 삭제하면 끝이에요.npx @google/design.md export --format tailwind로 Tailwind config을, --format dtcg로 DTCG JSON을 뽑아요. 어느 쪽이든 DESIGN.md 한 장이 진실의 근원이 돼요.- 완전히 자유로운 일러스트 위주 화면을 만드는 분. 토큰화가 큰 도움이 안 돼요.
- 한 화면짜리 정적 홍보 페이지만 필요한 분. 8섹션 작성이 좀 과해요.
- 이미 사내 토큰 시스템이 단단하게 박혀 있는 큰 팀. 마이그레이션 비용이 더 클 수 있어요.
구매 후 첫 결과물까지
가이드에서 준비물을 확인하고, 내 자료로 첫 작업을 시작해 보세요.
구매한 스킬의 사용 가이드 열기
결제 완료 화면이나 내 라이브러리에서 사용 가이드를 열어 주세요. 필요한 계정과 준비할 자료부터 확인해요.
스킬을 받아 가이드대로 설정하기
스킬 소스 링크를 열고 함께 제공되는 안내에 따라 설정해 주세요.
내 자료로 작은 작업 하나 해보기
처음에는 주제나 자료 하나로 시작해요. 원하는 결과의 형태를 구체적으로 정하고, 완성된 결과가 내 업무에 맞는지 확인해 주세요.
막힌 부분은 스킬룸에서 질문하기
하려던 작업과 멈춘 단계, 오류 메시지를 구매자 커뮤니티에 남겨 주세요. 다음 작업을 할 때도 내 라이브러리에서 가이드로 돌아올 수 있어요.
첫 요청 예시
“DESIGN.md — AI 디자인 에이전트가 읽는 디자인 시스템 한 장 스킬로 첫 작업을 해보고 싶어. 필요한 자료와 설정을 먼저 알려주고, 작은 작업 하나부터 도와줘.”
커뮤니티
구매자 전용 커뮤니티
질문하면 판매자가 답하고, 업데이트가 먼저 오고, 다른 구매자들의 결과가 쌓이는 곳이에요.
- 판매자에게 직접 질문하고 피드백 받기
- 스킬 업데이트 소식 받기
- 버그 신고 · 미래 기능 요청
- 다른 구매자들의 활용 사례 보기
구매 안내
구매 전 준비 사항과 지원 기준을 한곳에서 확인해 주세요.
구매 전에 확인해 주세요
- 받는 자료
스킬 소스 링크
구매한 자료는 내 라이브러리에서 열 수 있어요.
- 사용 환경
스킬을 실행할 AI 에이전트와 계정이 필요해요.
지원하는 에이전트와 준비할 서비스는 상품 설명에서 확인해 주세요.
- 추가 이용료
외부 AI 서비스는 별도 구독료나 사용료가 필요할 수 있어요.
필요한 요금제와 예상 사용량이 궁금하면 구매 전에 판매자에게 물어보세요.
보증 · 지원 정책
어떤 환경에서 검증했고, 언제까지 고쳐 주는지 먼저 밝힙니다.
- 동작 보증 대상
- Claude Code · Codex 기준으로 검증했습니다. 그 밖의 에이전트·CLI 에서는 동작을 보증하지 않습니다.
- 무상 패치 기간
- 업로드일(2026년 5월 11일)로부터 1년 — 2027년 5월 11일까지. 이 기간에 모델·CLI 변경으로 스킬이 동작하지 않으면 무상으로 고쳐 드립니다.
- 서비스 제공 기간
- 결제 즉시 다운로드로 제공되며, 결제일로부터 11개월간 [내 라이브러리]에서 다시 내려받고 열람하실 수 있습니다. 이 기간이 지나면 다운로드·열람 제공이 종료됩니다.
- 기간 내 미수정 시
- 무상 패치 기간 안에 고치지 못하면 남은 기간에 비례해 환불합니다.
- 마지막 동작 검증
- 2026년 9월 17일(스킬 최종 수정일)
