DESIGN.md 인터페이스

AI 에이전트에게 브랜드 분위기, 시각 규칙, 레이아웃 철학을 전달하는 상위 디자인 문서

AI가 토큰과 컴포넌트 명세를 읽는다고 해서 곧바로 "그 브랜드다운 화면"을 만들 수 있는 것은 아닙니다.

토큰은 값의 체계이고, 컴포넌트 명세는 조합 규칙입니다. 하지만 분위기, 밀도, 미학적 금지선, 시각적 철학은 그 둘만으로 충분히 전달되지 않는 경우가 많습니다.

DESIGN.md는 그 간극을 메우는 문서입니다. 이 책에서는 이를 AI가 읽는 시각 규칙 인터페이스로 다룹니다.

왜 토큰과 컴포넌트 명세만으로는 부족한가

계층	잘하는 것	놓치기 쉬운 것
토큰	색상, 간격, 타이포 값의 일관성	브랜드 분위기, 긴장감, 공간 철학
컴포넌트 명세	variant, slot, 상태 모델, 조합 규칙	화면 전체의 밀도, 장면 전환 감각
`DESIGN.md`	톤, 조형 원칙, 금지선, 레이아웃 성격	값의 정밀한 enforcement 자체

즉 DESIGN.md는 토큰을 대체하는 문서가 아니라, 토큰과 컴포넌트 명세 위에서 에이전트의 고수준 시각 판단을 조정하는 문서입니다.

Stitch가 보여준 핵심

Google Stitch는 DESIGN.md를 AGENTS.md의 디자인 대응물에 가깝게 설명합니다. 핵심 메시지는 단순합니다.

README는 사람이 프로젝트를 이해하는 문서
AGENTS.md는 코딩 에이전트가 프로젝트를 구현하는 규칙
DESIGN.md는 디자인 에이전트가 프로젝트의 look and feel을 이해하는 규칙

Stitch 문서에서 특히 중요한 부분은 dual representation입니다. 사람이 읽는 markdown과, 도구가 enforcement에 쓰는 structured tokens가 함께 존재합니다.

이 구조는 Stitch를 쓰지 않아도 유효합니다. 핵심은 다음입니다.

사람은 markdown을 다듬고
시스템은 tokens와 component spec으로 enforcement하고
에이전트는 두 계층을 함께 읽는다

`DESIGN.md`는 무엇이고 무엇이 아닌가

문서	독자	역할	대체하면 안 되는 것
`README.md`	사람	제품/프로젝트 개요	구현 규칙, 시각 규칙
`AGENTS.md` / `CLAUDE.md`	코딩 에이전트	구현 원칙, 파일 경계, 실행 규칙	디자인 시스템 자체
token spec	사람 + 도구 + 에이전트	시맨틱 값 체계	브랜드 톤 설명
component spec	사람 + 도구 + 에이전트	컴포넌트 선택/조합 규칙	전체 미학 방향
`DESIGN.md`	사람 + 디자인 에이전트 + 코딩 에이전트	톤, 레이아웃 감각, 시각적 guardrail	토큰 저장소, prop API 문서

DESIGN.md를 "vibe 문서" 정도로 낮게 두면 효과가 약합니다. 반대로 토큰을 다 빼고 DESIGN.md만 남기면 너무 모호해집니다.

좋은 구조는 항상 상위 규칙은 DESIGN.md, 정밀 규칙은 tokens/spec입니다.

권장 섹션 구조

Stitch의 기본 포맷과 awesome-design-md의 실전 확장을 합치면, 실무적으로는 아래 정도가 가장 안정적입니다.

섹션	목적	빠지면 생기는 문제
`Overview`	분위기, 밀도, 성격 설명	AI가 너무 일반적인 UI를 생성
`Colors`	주요 색상과 역할	브랜드 색이 decorative 수준으로만 쓰임
`Typography`	폰트, 위계, 무게감	카피와 제목의 인상이 흔들림
`Elevation`	깊이와 표면 규칙	카드/패널의 시각적 위계가 불안정
`Components`	버튼, 입력, 카드 등 핵심 atom 스타일	컴포넌트별 조형이 제각각
`Layout Principles`	spacing, grid, whitespace 철학	화면은 맞지만 브랜드 감각이 다름
`Do's and Don'ts`	금지선과 가드레일	AI가 기술적으로 맞지만 어색한 UI를 생성
`Responsive Behavior`	축소/확장 원칙	모바일에서 성격이 무너짐
`Agent Prompt Guide`	agent가 바로 참조할 요약 규칙	실전 사용성이 떨어짐

실무에서는 이 모든 섹션을 한 번에 채우기보다, Overview + Colors + Typography + Components + Do's and Don'ts부터 시작하는 편이 좋습니다.

권장 문서 계층

DESIGN.md                  # 브랜드/시각 규칙의 상위 문서
AGENTS.md                  # 구현 규칙, 참조 우선순위, 작업 가드레일
tokens/
  colors.tokens.json       # 시맨틱 색상
  spacing.tokens.json      # 간격, 반경, 그림자
components/
  button.spec.md           # variant, 상태, 사용 기준
  card.spec.md
docs/
  patterns/
    dashboard-layout.md    # 화면 수준 조합 패턴

추천 precedence는 아래와 같습니다.

component spec
token spec
DESIGN.md의 component/layout guidance
DESIGN.md의 overview/mood text

즉 DESIGN.md는 방향을 정하고, tokens/spec는 충돌 시 최종 제약을 제공합니다.

최소 `DESIGN.md` 템플릿

# Design System

## Overview
신뢰감 있고 밀도 높은 B2B 대시보드.
장식보다 정보 구조를 우선하며, 차분한 대비와 또렷한 위계를 사용한다.

## Colors
- **Primary** (#2665fd): 주요 CTA, 활성 상태
- **Secondary** (#6074b9): 보조 액션, 보조 강조
- **Surface** (#f7f8fa): 기본 배경과 카드 표면
- **On-surface** (#101828): 본문 텍스트
- **Error** (#d92d20): 오류, 위험한 액션

## Typography
- **Headline Font**: Pretendard
- **Body Font**: Pretendard
- **Label Font**: JetBrains Mono

헤드라인은 semi-bold, 본문은 regular 14-16px.
라벨은 12px medium, 대문자 남용 금지.

## Elevation
깊이는 강한 그림자보다 border contrast로 표현한다.
카드는 1px outline과 미세한 surface 차이로 구분한다.

## Components
- **Buttons**: 반경 10px, primary는 채움, secondary는 outline
- **Inputs**: 1px border, 에러 상태는 텍스트와 border가 함께 변함
- **Cards**: 그림자 최소화, 제목과 메타데이터 대비를 명확히 유지

## Layout Principles
- 8px 기반 spacing scale
- 섹션 간 간격은 카드 내부보다 명확히 크게 유지
- 정보 밀도는 높되 터치 타깃은 40px 이상 유지

## Do's and Don'ts
- Do: primary color는 한 화면의 핵심 액션에만 집중 사용
- Do: 숫자, 상태, 액션의 위계를 간격과 타이포로 먼저 구분
- Don't: 장식용 gradient를 카드 내부에 남용
- Don't: sharp corner와 rounded corner를 혼합

## Responsive Behavior
- 모바일에서는 2열 카드를 1열로 줄이고, 밀도보다 가독성을 우선
- 테이블은 축약 카드로 전환하되 상태 색상은 유지

## Agent Prompt Guide
- "enterprise dashboard", "calm contrast", "border-led hierarchy"
- avoid glossy marketing gradients
- prefer structured lists, tables, metrics, restrained motion

레퍼런스를 가져오는 올바른 방식

awesome-design-md 같은 컬렉션은 가치가 큽니다. 다만 그대로 복제하는 문서가 아니라 추상화 재료로 써야 합니다.

좋은 활용	나쁜 활용
여러 사이트의 layout density, typography tension, border/shadow 철학을 비교	특정 브랜드의 색/카피/구조를 거의 그대로 복제
팀의 house style vocabulary를 만드는 출발점으로 사용	"이 사이트처럼 만들어줘"를 영구 운영 방식으로 사용
`Do/Don't`, layout, depth 같은 패턴을 추출	시맨틱 토큰 없이 시각 취향만 복사

즉 컬렉션은 시각 규칙 샘플 라이브러리로 쓰고, 최종 문서는 항상 내 제품의 DESIGN.md로 수렴해야 합니다.

언제 `DESIGN.md`가 load-bearing인가

신호	의미
AI가 토큰은 지키는데 화면 인상이 계속 흔들린다	상위 시각 규칙 계층이 부족함
디자이너가 “값은 맞는데 우리답지 않다”를 반복한다	분위기·금지선 문서화가 필요
여러 agent가 각자 다른 layout density를 만든다	`Overview`와 `Layout Principles`가 약함
brand refresh 이후 컴포넌트보다 화면 철학이 먼저 바뀐다	`DESIGN.md`가 중심 변경점이 되어야 함

반대로 팀 규모가 작고 컴포넌트 수가 적으며 brand differentiation이 약한 초기 단계라면, 토큰과 간단한 component docs만으로도 충분할 수 있습니다.

흔한 안티패턴

안티패턴	왜 문제인가	교정 방식
`DESIGN.md`를 무드보드 설명문처럼만 씀	enforcement 가능한 규칙으로 연결되지 않음	colors, components, do/don't를 최소 포함
토큰 없이 `DESIGN.md`만 둠	vague guidance가 쌓여 출력 편차가 커짐	시맨틱 토큰과 component spec를 함께 운영
특정 레퍼런스 사이트를 그대로 복붙	브랜드 정체성이 외주화됨	공통 패턴만 추출해 자사 vocabulary로 재작성
`AGENTS.md`와 충돌하는데 우선순위가 없음	에이전트가 분위기 규칙과 구현 규칙 사이에서 흔들림	precedence를 문서에 명시

참고 자료

AI가 토큰과 컴포넌트 명세를 읽는다고 해서 곧바로 "그 브랜드다운 화면"을 만들 수 있는 것은 아닙니다.

DESIGN.md는 그 간극을 메우는 문서입니다. 이 책에서는 이를 AI가 읽는 시각 규칙 인터페이스로 다룹니다.

왜 토큰과 컴포넌트 명세만으로는 부족한가

계층	잘하는 것	놓치기 쉬운 것
토큰	색상, 간격, 타이포 값의 일관성	브랜드 분위기, 긴장감, 공간 철학
컴포넌트 명세	variant, slot, 상태 모델, 조합 규칙	화면 전체의 밀도, 장면 전환 감각
`DESIGN.md`	톤, 조형 원칙, 금지선, 레이아웃 성격	값의 정밀한 enforcement 자체

즉 DESIGN.md는 토큰을 대체하는 문서가 아니라, 토큰과 컴포넌트 명세 위에서 에이전트의 고수준 시각 판단을 조정하는 문서입니다.

Stitch가 보여준 핵심

Google Stitch는 DESIGN.md를 AGENTS.md의 디자인 대응물에 가깝게 설명합니다. 핵심 메시지는 단순합니다.

README는 사람이 프로젝트를 이해하는 문서
AGENTS.md는 코딩 에이전트가 프로젝트를 구현하는 규칙
DESIGN.md는 디자인 에이전트가 프로젝트의 look and feel을 이해하는 규칙

Stitch 문서에서 특히 중요한 부분은 dual representation입니다. 사람이 읽는 markdown과, 도구가 enforcement에 쓰는 structured tokens가 함께 존재합니다.

이 구조는 Stitch를 쓰지 않아도 유효합니다. 핵심은 다음입니다.

사람은 markdown을 다듬고
시스템은 tokens와 component spec으로 enforcement하고
에이전트는 두 계층을 함께 읽는다

`DESIGN.md`는 무엇이고 무엇이 아닌가

문서	독자	역할	대체하면 안 되는 것
`README.md`	사람	제품/프로젝트 개요	구현 규칙, 시각 규칙
`AGENTS.md` / `CLAUDE.md`	코딩 에이전트	구현 원칙, 파일 경계, 실행 규칙	디자인 시스템 자체
token spec	사람 + 도구 + 에이전트	시맨틱 값 체계	브랜드 톤 설명
component spec	사람 + 도구 + 에이전트	컴포넌트 선택/조합 규칙	전체 미학 방향
`DESIGN.md`	사람 + 디자인 에이전트 + 코딩 에이전트	톤, 레이아웃 감각, 시각적 guardrail	토큰 저장소, prop API 문서

DESIGN.md를 "vibe 문서" 정도로 낮게 두면 효과가 약합니다. 반대로 토큰을 다 빼고 DESIGN.md만 남기면 너무 모호해집니다.

좋은 구조는 항상 상위 규칙은 DESIGN.md, 정밀 규칙은 tokens/spec입니다.

권장 섹션 구조

Stitch의 기본 포맷과 awesome-design-md의 실전 확장을 합치면, 실무적으로는 아래 정도가 가장 안정적입니다.

섹션	목적	빠지면 생기는 문제
`Overview`	분위기, 밀도, 성격 설명	AI가 너무 일반적인 UI를 생성
`Colors`	주요 색상과 역할	브랜드 색이 decorative 수준으로만 쓰임
`Typography`	폰트, 위계, 무게감	카피와 제목의 인상이 흔들림
`Elevation`	깊이와 표면 규칙	카드/패널의 시각적 위계가 불안정
`Components`	버튼, 입력, 카드 등 핵심 atom 스타일	컴포넌트별 조형이 제각각
`Layout Principles`	spacing, grid, whitespace 철학	화면은 맞지만 브랜드 감각이 다름
`Do's and Don'ts`	금지선과 가드레일	AI가 기술적으로 맞지만 어색한 UI를 생성
`Responsive Behavior`	축소/확장 원칙	모바일에서 성격이 무너짐
`Agent Prompt Guide`	agent가 바로 참조할 요약 규칙	실전 사용성이 떨어짐

실무에서는 이 모든 섹션을 한 번에 채우기보다, Overview + Colors + Typography + Components + Do's and Don'ts부터 시작하는 편이 좋습니다.

권장 문서 계층

DESIGN.md                  # 브랜드/시각 규칙의 상위 문서
AGENTS.md                  # 구현 규칙, 참조 우선순위, 작업 가드레일
tokens/
  colors.tokens.json       # 시맨틱 색상
  spacing.tokens.json      # 간격, 반경, 그림자
components/
  button.spec.md           # variant, 상태, 사용 기준
  card.spec.md
docs/
  patterns/
    dashboard-layout.md    # 화면 수준 조합 패턴

추천 precedence는 아래와 같습니다.

component spec
token spec
DESIGN.md의 component/layout guidance
DESIGN.md의 overview/mood text

즉 DESIGN.md는 방향을 정하고, tokens/spec는 충돌 시 최종 제약을 제공합니다.

최소 `DESIGN.md` 템플릿

# Design System

## Overview
신뢰감 있고 밀도 높은 B2B 대시보드.
장식보다 정보 구조를 우선하며, 차분한 대비와 또렷한 위계를 사용한다.

## Colors
- **Primary** (#2665fd): 주요 CTA, 활성 상태
- **Secondary** (#6074b9): 보조 액션, 보조 강조
- **Surface** (#f7f8fa): 기본 배경과 카드 표면
- **On-surface** (#101828): 본문 텍스트
- **Error** (#d92d20): 오류, 위험한 액션

## Typography
- **Headline Font**: Pretendard
- **Body Font**: Pretendard
- **Label Font**: JetBrains Mono

헤드라인은 semi-bold, 본문은 regular 14-16px.
라벨은 12px medium, 대문자 남용 금지.

## Elevation
깊이는 강한 그림자보다 border contrast로 표현한다.
카드는 1px outline과 미세한 surface 차이로 구분한다.

## Components
- **Buttons**: 반경 10px, primary는 채움, secondary는 outline
- **Inputs**: 1px border, 에러 상태는 텍스트와 border가 함께 변함
- **Cards**: 그림자 최소화, 제목과 메타데이터 대비를 명확히 유지

## Layout Principles
- 8px 기반 spacing scale
- 섹션 간 간격은 카드 내부보다 명확히 크게 유지
- 정보 밀도는 높되 터치 타깃은 40px 이상 유지

## Do's and Don'ts
- Do: primary color는 한 화면의 핵심 액션에만 집중 사용
- Do: 숫자, 상태, 액션의 위계를 간격과 타이포로 먼저 구분
- Don't: 장식용 gradient를 카드 내부에 남용
- Don't: sharp corner와 rounded corner를 혼합

## Responsive Behavior
- 모바일에서는 2열 카드를 1열로 줄이고, 밀도보다 가독성을 우선
- 테이블은 축약 카드로 전환하되 상태 색상은 유지

## Agent Prompt Guide
- "enterprise dashboard", "calm contrast", "border-led hierarchy"
- avoid glossy marketing gradients
- prefer structured lists, tables, metrics, restrained motion

레퍼런스를 가져오는 올바른 방식

awesome-design-md 같은 컬렉션은 가치가 큽니다. 다만 그대로 복제하는 문서가 아니라 추상화 재료로 써야 합니다.

좋은 활용	나쁜 활용
여러 사이트의 layout density, typography tension, border/shadow 철학을 비교	특정 브랜드의 색/카피/구조를 거의 그대로 복제
팀의 house style vocabulary를 만드는 출발점으로 사용	"이 사이트처럼 만들어줘"를 영구 운영 방식으로 사용
`Do/Don't`, layout, depth 같은 패턴을 추출	시맨틱 토큰 없이 시각 취향만 복사

즉 컬렉션은 시각 규칙 샘플 라이브러리로 쓰고, 최종 문서는 항상 내 제품의 DESIGN.md로 수렴해야 합니다.

언제 `DESIGN.md`가 load-bearing인가

신호	의미
AI가 토큰은 지키는데 화면 인상이 계속 흔들린다	상위 시각 규칙 계층이 부족함
디자이너가 “값은 맞는데 우리답지 않다”를 반복한다	분위기·금지선 문서화가 필요
여러 agent가 각자 다른 layout density를 만든다	`Overview`와 `Layout Principles`가 약함
brand refresh 이후 컴포넌트보다 화면 철학이 먼저 바뀐다	`DESIGN.md`가 중심 변경점이 되어야 함

반대로 팀 규모가 작고 컴포넌트 수가 적으며 brand differentiation이 약한 초기 단계라면, 토큰과 간단한 component docs만으로도 충분할 수 있습니다.

흔한 안티패턴

안티패턴	왜 문제인가	교정 방식
`DESIGN.md`를 무드보드 설명문처럼만 씀	enforcement 가능한 규칙으로 연결되지 않음	colors, components, do/don't를 최소 포함
토큰 없이 `DESIGN.md`만 둠	vague guidance가 쌓여 출력 편차가 커짐	시맨틱 토큰과 component spec를 함께 운영
특정 레퍼런스 사이트를 그대로 복붙	브랜드 정체성이 외주화됨	공통 패턴만 추출해 자사 vocabulary로 재작성
`AGENTS.md`와 충돌하는데 우선순위가 없음	에이전트가 분위기 규칙과 구현 규칙 사이에서 흔들림	precedence를 문서에 명시

DESIGN.md 인터페이스

왜 토큰과 컴포넌트 명세만으로는 부족한가

Stitch가 보여준 핵심

`DESIGN.md`는 무엇이고 무엇이 아닌가

권장 섹션 구조

권장 문서 계층

최소 `DESIGN.md` 템플릿

레퍼런스를 가져오는 올바른 방식

언제 `DESIGN.md`가 load-bearing인가

흔한 안티패턴

관련 장 연결

참고 자료

목차

DESIGN.md 인터페이스

왜 토큰과 컴포넌트 명세만으로는 부족한가

Stitch가 보여준 핵심

`DESIGN.md`는 무엇이고 무엇이 아닌가

권장 섹션 구조

권장 문서 계층

최소 `DESIGN.md` 템플릿

레퍼런스를 가져오는 올바른 방식

언제 `DESIGN.md`가 load-bearing인가

흔한 안티패턴

관련 장 연결

참고 자료

목차