가이드

Claude Code와 Cursor가 웹사이트 디자인에 맞는 UI를 만들게 하기

코딩 에이전트에게 “깔끔한 설정 페이지”를 요청하면 평범한 페이지가 나와요. 마음에 드는 사이트에서 가져온 DESIGN.md를 주면, 추측하는 대신 그 사이트의 실제 색상, 타입 스케일, 반경, 컴포넌트 규칙으로 만들어요.

이 가이드는 갤러리에 있는 Linear 파일을 예시로, Claude Code와 Cursor에서의 전체 과정을 보여 줘요.

대상 독자: AI 코딩 에이전트로 개발하는 개발자. 업데이트: .

이 가이드에서 얻는 것

  • 마음에 드는 사이트의 DESIGN.md를 에이전트가 읽을 수 있는 저장소에 저장.
  • 모든 UI 작업이 이 파일에서 시작하도록 Claude Code용 CLAUDE.md 안내와 Cursor용 프로젝트 규칙.
  • 에이전트가 비슷한 추측값 대신 정확한 값을 쓰도록 토큰 이름을 명시한 프롬프트.
  • 에이전트가 벗어난 부분을 잡아내는 간단한 리뷰 절차.

스크린샷보다 DESIGN.md가 나은 이유

스크린샷은 에이전트에게 추측할 픽셀만 줘요. 분위기는 대충 맞추지만 값은 틀려요. 비슷한 파란색, 몇 픽셀 어긋난 반경, 비슷해 보여서 고른 폰트. 새 화면마다 다시 추측하기 때문에 앱이 조금씩 흐트러져요.

DESIGN.md는 정확한 값을 줘요. 이 파일은 Google의 DESIGN.md 사양을 따라요. 맨 위의 YAML 프런트매터에는 토큰(hex 색상, 폰트 패밀리와 크기, 반경, 컴포넌트)이 있고, 그 아래 Markdown은 각 값이 어디에 쓰이는지 설명해요. 이 형식이 처음이라면 DESIGN.md란 무엇인지 읽어 보세요.

단계

  1. 만들려는 것과 비슷한 느낌의 인터페이스를 가진 사이트 고르기

    큰 히어로가 있는 랜딩 페이지보다 밀도가 비슷한 제품 화면이 더 잘 맞아요. 대시보드를 만든다면 대시보드가 있는 제품을 고르세요. 먼저 DESIGN.md 갤러리를 확인하세요. 파일이 이미 있을 수도 있어요.

  2. DESIGN.md 받기

    갤러리 페이지에서 복사하거나, Design Extractor 홈페이지에 URL을 붙여 넣고 Pro 추출을 실행하세요. Pro는 사이트의 주요 페이지를 샘플링하며, 추출에는 최소 1분이 걸려요.

  3. 저장소 루트에 DESIGN.md로 저장하기

    README.md, AGENTS.md 옆에 두고 커밋하세요. 그러면 모든 브랜치와 모든 팀원의 에이전트가 같은 파일을 읽어요.

  4. 에이전트에게 파일 알려 주기

    Claude Code라면 CLAUDE.md에, Cursor라면 프로젝트 규칙에 짧은 안내를 추가하세요. 코드 블록은 아래에 있어요.

  5. 파일의 용어로 UI 요청하기

    프롬프트에서 토큰과 컴포넌트 이름(primary, body-md, 버튼 레시피)을 언급하고, 찾지 못한 값은 지어내지 말고 목록으로 알려 달라고 요청하세요.

  6. 파일과 비교해 결과 리뷰하기

    변경 사항을 받아들이기 전에 색상, 폰트, 반경, 상태를 DESIGN.md와 비교해 확인하세요.

실전 예시: Linear

갤러리의 Linear DESIGN.md는 linear.app에서 5개 페이지를 캡처한 Pro 추출로 만들었어요. 파일에는 색상 토큰 17개, 타입 스타일 16개, 반경 12개가 들어 있어요. 에이전트는 이걸로 작업해요.

색상

타이포그래피

hero-displayDesign is intelligence made visibleInter Variable72px / 510 / 1
display-lgDesign is intelligence made visibleInter Variable64px / 510 / 1
display-mdDesign is intelligence made visibleInter Variable48px / 510 / 1
heading-lgDesign is intelligence made visibleInter Variable32px / 590 / 1.15
title-mdDesign is intelligence made visibleInter Variable20px / 590 / 1.35
body-lgDesign is intelligence made visibleInter Variable17px / 400 / 1.6

모양

xs · 2px
sm · 4px
sm-2 · 4.4625px
md · 5px
md-2 · 6px
lg · 8px
lg-2 · 9px
xl · 12px

Linear DESIGN.md에서 렌더링한 처음 12개 색상, 6개 타입 스타일, 8개 반경이에요. 견본을 클릭하면 hex 값이 복사돼요.

파일 앞부분 발췌: 색상 17개 중 8개, 타입 스타일 16개 중 2개, 반경 12개 중 4개. 에이전트가 그대로 가져다 쓰는 정확한 값이에요.
---
name: Linear
colors:
  primary: "#5E6AD2"
  canvas: "#08090A"
  surface: "#121414"
  surface-raised: "#1C1C1F"
  ink: "#F7F8F8"
  ink-secondary: "#D0D6E0"
  muted: "#8A8F98"
  subtle: "#62666D"
typography:
  hero-display:
    fontFamily: Inter Variable
    fontSize: 72px
    fontWeight: 510
    lineHeight: 1
    letterSpacing: -1.584px
  body-lg:
    fontFamily: Inter Variable
    fontSize: 17px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: normal
rounded:
  xs: 2px
  sm: 4px
  sm-2: 4.4625px
  md: 5px
---

Linear 공개 웹사이트에서 추출한 것으로, 공식 브랜드 가이드라인이 아니에요. Linear DESIGN.md 전체 읽기

파일이 모습을 설명하는 방식

토큰 아래의 설명은 각 값이 어디에 쓰이는지 에이전트에게 알려 줘요. 이렇게 시작해요:

Linear's marketing surface reads like the product itself: a near-black Void canvas (canvas, #08090A) with charcoal panels stacked a half-step lighter, fenced by 1px hairlines rather than shadows. The mood is engineering-grade and restrained. Realistic product UI mockups, a customer logo strip and Berkeley Mono micro-labels ("FIG 0.1") stand in for illustration. Nothing shouts; the page earns attention through precision.

파일이 에이전트에게 주는 규칙

Do's and Don'ts 섹션은 모습을 규칙으로 바꿔요. 처음 몇 가지는 다음과 같아요:

해야 할 것

  • Reserve Linear Indigo (primary, #5E6AD2) for focus and interactive accents. Every measured focus state is a 1px solid #5E69D1 outline with a 2px offset.
  • Shape every button as a pill with rounded.full. button-ghost, button-ghost-2 and button-ghost-3 all measure 9999px.
  • Keep control heights on the observed ladder: button-ghost and button-ghost-2 at 32px, button-ghost-4 at 29px, button-ghost-3 at 24px, and sidebar-nav-item and the icon buttons at 28px.

하지 말아야 할 것

  • Don't use weights other than 400, 510 and 590, and never substitute a static 600 or 700 for heading-lg or title-md.
  • Don't add a third typeface. Inter Variable carries everything, and Berkeley Mono is limited to micro figure labels.
  • Don't use accent-blue, danger or success for marketing chrome; they belong inside product mockups.

컴포넌트

파일에는 HTML과 CSS로 된 컴포넌트 레시피 30개가 있어요. 그중 13개는 실제 페이지와의 대조 확인을 통과했고, 나머지는 통과하지 못했거나 확인할 수 없었던 이유가 파일에 적혀 있어요. 전체 파일은 약 276,000자이며, 대부분이 레시피예요. 그래서 프롬프트에 붙여 넣는 대신 에이전트에게 파일을 가리키는 거예요.

에이전트에게 파일 알려 주기

대부분의 에이전트는 DESIGN.md를 스스로 열지 않아요. 에이전트가 이미 불러오는 지침에 몇 줄만 추가하면 해결돼요. Claude Code에서는 저장소 루트의 CLAUDE.md에 다음을 추가하세요:

## Design
Follow DESIGN.md in the repository root for every UI change.
Use its color, typography, rounded and component tokens instead of inventing values.
Before you build a button, card or input, read its recipe in the Components section.

Cursor에서는 프로젝트 규칙을 추가하세요. 다음을 .cursor/rules/design.mdc로 저장하면, alwaysApply 덕분에 프로젝트의 모든 요청에 적용돼요:

---
description: Follow DESIGN.md for every UI change
alwaysApply: true
---
Follow DESIGN.md in the repository root for every UI change.
Use its color, typography, rounded and component tokens instead of inventing values.
Before you build a button, card or input, read its recipe in the Components section.

지침에 파일을 붙여 넣지 말고 가리키세요. Pro DESIGN.md에는 사이트에서 고른 모든 컴포넌트의 레시피가 담겨 있어서 길고, 에이전트는 UI 작업을 할 때만 필요해요.

토큰을 활용하는 프롬프트

파일과 토큰 이름을 명시하고, 에이전트에게 추측할 이유 대신 빠져나갈 길을 주세요. 아래 프롬프트는 이 가이드를 위해 Linear의 실제 토큰 이름으로 작성했어요. 작업 내용은 여러분의 것으로 바꾸세요.

Claude Code

Build a pricing page with three plan cards. Follow DESIGN.md:
- use primary (#5E6AD2) only where the file says it belongs
- set headings in hero-display and body copy in body-lg
- reuse the button-ghost recipe for the plan buttons, with its hover and focus states
- start the plan cards from the card recipe
List any value you could not find in DESIGN.md instead of inventing one.

Cursor

@DESIGN.md Restyle the settings form in src/app/settings to match this file.
Take colors, type and radii from the tokens and inputs and buttons from the component recipes.
Keep the existing layout and logic, and list any value you could not find in the file.

Cursor에서는 @DESIGN.md로 파일을 채팅에 첨부할 수 있어요. 작업이 주로 모습에 관한 것이라면 규칙에 더해 도움이 돼요.

결과는 어떤 모습이어야 할까요? 대략 이 카드와 비슷해요. 이 페이지가 토큰으로 직접 그린 카드예요. 값이 어떤 역할을 하는지 보여 줄 뿐, 에이전트가 만든 결과물은 아니에요.

다음 릴리스 계획하기

모든 작업, 일정, 결정을 한곳에 모아 팀이 제때 출시할 수 있게 해요.

시작하기영업팀 문의
이 페이지가 Linear의 토큰으로 그린 일러스트예요: canvas #08090A, ink #F7F8F8, primary #5E6AD2, button-ghost.rounded 9999px. 코딩 에이전트가 만든 결과물이 아니며, 폰트는 기기에 설치되어 있을 때만 표시돼요.

에이전트가 만든 결과 리뷰하기

  • 색상. diff에서 hex 값을 검색하세요. 모든 값이 DESIGN.md에 있어야 해요. 새로운 값이 있다면 보통 에이전트가 추측한 거예요.
  • 폰트. 많은 브랜드가 배포할 수 없는 상용 폰트를 써요. 파일의 Typography 섹션에는 보통 오픈 소스 대체 폰트가 적혀 있어요. 에이전트가 아무 대체 폰트가 아니라 그 폰트를 불러왔는지 확인하세요.
  • 반경과 간격. 버튼과 카드는 모든 곳에 8px 같은 기본값이 아니라 파일의 rounded 토큰을 써야 해요.
  • 상태. hover와 focus 스타일은 각 컴포넌트 레시피에 포함되어 있어요. Tab 키로 페이지를 이동하며 포커스 링을 확인하세요.
  • flagged 레시피. 파일에서 레시피가 flagged로 표시되어 있다면, 그 형태는 근사치예요. 해당 컴포넌트를 실제 사이트와 비교하세요.

DESIGN.md를 직접 편집했다면, 에이전트가 다시 읽기 전에 무료 DESIGN.md 검사기로 확인하세요.

FAQ

Claude Code와 Cursor에서 웹사이트 디자인 맞추기: 자주 묻는 질문

시도해 보기 전에 많이 묻는 질문에 짧게 답해 드려요.

아니요. 저장소 루트에 DESIGN.md로 한 번 저장하고, Claude Code라면 CLAUDE.md에서, Cursor라면 프로젝트 규칙에서 이 파일을 가리키세요. 작업이 인터페이스와 관련되면 에이전트가 파일을 읽어요. 컴포넌트 레시피가 담긴 Pro DESIGN.md는 길기 때문에, 파일을 가리키는 방식이 프롬프트를 짧게 유지해 줘요.

아니요, 그게 목표도 아니에요. 에이전트는 사이트의 토큰(색상, 타입, 반경), 컴포넌트 레시피, 규칙을 받아요. 레이아웃, 콘텐츠, 기능은 여러분의 것으로 유지돼요. 실제 사이트와의 대조 확인을 통과하지 못한 레시피는 파일에 flagged로 표시되어 있으니, 근사치로 생각하세요.

네. 저장소의 파일을 읽을 수 있는 에이전트라면 모두 DESIGN.md를 쓸 수 있어요. AGENTS.md나 .github/copilot-instructions.md처럼 에이전트가 이미 읽는 지침에서 이 파일을 가리키거나, 프롬프트에서 파일 이름을 언급하세요.

네. 모든 갤러리 페이지에 복사할 수 있는 전체 DESIGN.md가 있어요. 갤러리 파일은 각 브랜드의 공개 웹사이트에서 추출한 것으로, 공식 브랜드 가이드라인이 아니에요. 갤러리에 없는 사이트라면 홈페이지에 URL을 붙여 넣고 추출을 실행하세요.

마음에 드는 사이트의 DESIGN.md를 받아 보세요

공개 URL을 붙여 넣으세요. Pro 추출은 사이트의 주요 페이지를 샘플링해 에이전트가 읽을 수 있는 DESIGN.md를 돌려줘요.

웹사이트에서 DESIGN.md 추출하기

관련 가이드

모든 DESIGN.md 가이드 보기