밤티 화면을 끊는 DESIGN.md 적용 가이드

추석 AI 부트캠프 하루 6시간 만에
AI 기초부터 나만의
서비스까지 완성 이번 연휴를 기회로 삼으세요일정 보기 ↗

Quick Start

DESIGN.md 는 화면이 어떻게 보여야 하는지를 적은 마크다운 파일입니다. 색·글꼴·버튼 같은 컴포넌트 값과 하지 말아야 할 것을 적어 두면, 코딩 에이전트가 그 기준대로 화면을 만듭니다. VoltAgent 의 awesome-design-md 저장소에는 Claude·Stripe·Linear·Notion 등 브랜드별 DESIGN.md 가 70개 넘게 모여 있습니다.

1. STEP 1에서 브랜드 파일을 고릅니다.
2. STEP 2에서 프로젝트 폴더에 넣습니다.
3. STEP 3에서 클로드에게 그 파일대로 만들게 합니다.
4. STEP 4에서 lint 로 파일을 점검합니다.

STEP 1 · 3분브랜드 DESIGN.md 를 고른다

이 단계에서는 만들 화면과 분위기가 가까운 브랜드를 고릅니다. 저장소 README 의 Collection 목록이나 getdesign.md 의 카탈로그에서 브랜드를 열면, 미리보기(Live Preview)로 그 파일이 그린 화면을 먼저 볼 수 있습니다. 각 파일에는 Visual Theme, Color Palette & Roles, Typography Rules, Component Stylings, Do's and Don'ts 같은 절이 들어 있습니다.

따뜻하고 글 중심 → claude · 어두운 제품 화면 → linear.app · 결제·금융 → stripe · 문서·생산성 → notion

성공하면 미리보기 화면이 만들고 싶은 분위기와 비슷한 브랜드 하나가 정해집니다.

STEP 2 · 1분프로젝트 폴더에 넣는다

이 단계에서는 고른 파일을 프로젝트 루트에 둡니다. getdesign.md 의 Usage 에 나온 명령을 프로젝트 폴더에서 실행하면 DESIGN.md 가 바로 생깁니다. 저장소의 design-md/<브랜드>/DESIGN.md 를 직접 복사해도 됩니다.

npx getdesign@latest add claude

성공하면 터미널에 ✓ DESIGN.md inspired by claude installed → DESIGN.md 가 뜨고 폴더에 DESIGN.md 가 생깁니다.

STEP 3 · 2분클로드에게 그 파일대로 만들게 한다

이 단계에서는 막연한 형용사 대신 파일을 기준으로 지목합니다. 먼저 읽게 하고, 파일에 없는 값은 새로 만들지 말라고 적는 편이 결과가 안정적입니다.

프로젝트 루트의 DESIGN.md 를 먼저 끝까지 읽어줘. 색·글꼴·간격·버튼 모양은 이 파일에 적힌 값만 쓰고, Do's and Don'ts 절의 금지 항목은 지켜줘.
만들 화면: 카페 원두 구독 랜딩 페이지. 첫 화면에 제목 한 줄, 원두 사진 자리, 구독 버튼 하나.

성공하면 보라 그라데이션 대신 파일에 적힌 색과 글꼴로 만든 화면이 나옵니다.

STEP 4 · 1분design.md lint 로 파일을 점검한다

이 단계에서는 파일 자체에 빠진 값이나 약한 대비가 없는지 봅니다. 구글의 design.md 는 DESIGN.md 형식 명세와 CLI 를 함께 제공하며, lint 는 깨진 토큰 참조와 WCAG 대비를 JSON 으로 알려 줍니다.

npx @google/design.md lint DESIGN.md

성공하면 findings 목록이 나옵니다. 2026년 9월 22일에 Claude 파일을 돌렸을 때는 오류 0개·경고 19개였고, 흰 글씨 코랄 버튼의 대비가 3.28:1 로 WCAG AA 기준 4.5:1 보다 낮다고 짚었습니다.

알아 둘 한계

• 파일들은 공개 사이트의 CSS 값을 분석한 것이며 해당 브랜드의 공식 디자인 시스템이 아닙니다. 로고와 브랜드 이름은 그대로 쓰지 않는 편이 안전합니다.
• 저장소 README 배지는 73개, 폴더는 74개로 표기가 다릅니다. 이 글은 2026년 9월 22일 기준입니다.
• lint 경고는 참고용입니다. 대비 경고가 나온 조합은 실제 화면에서 글자 크기와 함께 다시 확인합니다.

FAQ

DESIGN.md 는 Claude Code 에서만 쓰나요? 아닙니다. README 는 코딩 에이전트와 Google Stitch 가 읽는 파일이라고 설명합니다.

브랜드 파일을 섞어 써도 되나요? 한 프로젝트에는 한 파일을 기준으로 두는 편이 일관됩니다. 바꾸고 싶은 값은 파일 안에서 직접 고칩니다.

공식 참고 자료

• VoltAgent/awesome-design-md
• getdesign.md — Claude
• google-labs-code/design.md

설치 명령과 lint 출력은 2026년 9월 22일에 임시 폴더에서 직접 실행해 확인한 내용입니다.