가이드

사이트를 리빌드하나요? 먼저 디자인 시스템을 추출하세요

리빌드, 리브랜딩, 새 프레임워크로의 이전은 디자인 시스템이 조용히 사라지는 순간이에요. 색상은 오래된 CSS에, 타입 스케일은 누군가의 머릿속에, 버튼 상태는 아무도 열고 싶어 하지 않는 컴포넌트에 남아 있죠.

무엇이든 바꾸기 전에 현재 사이트를 DESIGN.md로 추출하세요. 새 빌드를 위한 기준이 문서로 남고, 팀과 코딩 에이전트 모두 읽을 수 있어요.

대상 독자: 리빌드, 리브랜딩, 마이그레이션을 계획하는 팀. 업데이트: .

이 가이드에서 얻는 것

  • 리빌드의 첫 줄을 작성하기 전에 커밋한 현재 사이트의 DESIGN.md.
  • 파일이 담은 것과 담지 못한 것에 대한 명확한 파악.
  • 직접 확인할 항목의 체크리스트: 에셋, 상태, 모션, 브레이크포인트, 로그인이 필요한 페이지.
  • 작업이 끝났을 때 새 사이트를 이전 사이트와 비교하는 방법.

이럴 때 하세요

  • 프레임워크 이전. 모습은 같고 스택만 새로워요. DESIGN.md가 있으면 코딩 에이전트가 오래된 스타일시트를 읽는 대신 정확한 값으로 컴포넌트를 다시 만들어요.
  • 리브랜딩. 이전 시스템을 먼저 기록해 두면, 어떤 색상, 폰트, 반경이 바뀌고 어떤 게 남는지 정확히 알 수 있어요.
  • 인수인계. 새 에이전시나 새 팀이 코드베이스 투어 대신, 오늘의 사이트 모습을 설명하는 파일 하나를 받아요.

단계

  1. 무엇이든 바꾸기 전에 실제 사이트 추출하기

    Design Extractor 홈페이지에 프로덕션 URL을 붙여 넣고 Pro 추출을 실행하세요. 공개 페이지여야 해요. 추출은 방문자처럼 페이지를 불러오기 때문에 localhost와 로그인이 필요한 페이지는 작동하지 않아요.

  2. 기준으로 커밋하기

    새 저장소에 DESIGN.md로 저장하고 리빌드를 시작하기 전에 커밋하세요. 이제 이 파일이 그날의 사이트 모습을 기록해요.

  3. Known Gaps 섹션 읽기

    파일 끝에는 추출에서 담지 못한 항목이 나열되어 있어요. 거기 있는 모든 항목은 직접 확인해야 해요.

  4. DESIGN.md에 담을 수 없는 것 확인하기

    에셋, 로그인 후 화면, 모션, 그리고 아래의 다른 항목들이에요. 확인하면서 파일에 메모를 추가하세요.

  5. 파일을 기준으로 만들기

    Claude Code와 Cursor 가이드처럼 코딩 에이전트에게 파일을 알려 주고, 새 화면마다 파일과 비교해 리뷰하세요.

Stripe에서 파일이 담은 것

무엇을 받게 되는지 보려면 갤러리의 Stripe DESIGN.md를 보세요. Pro 추출로 stripe.com의 페이지 5개를 캡처했어요: /nl, /nl/pricing, /nl/products, /nl/newsroom/news/stripe-openai-instant-checkout, /nl/contact/sales. 여러분의 사이트를 추출해도 같은 구조가 나와요.

색상토큰 21개, 각각 역할 포함
타이포그래피Sohne의 스타일 17개
반경토큰 10개
간격토큰 62개
컴포넌트HTML과 CSS로 된 레시피 71개: 44개는 실제 페이지와의 대조 확인 통과, 27개는 flagged 또는 확인 불가, 각각 이유 포함
섹션Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts, Responsive Behavior, Iteration Guide, Known Gaps

파일이 놓쳤다고 밝힌 것

파일은 자신의 한계를 솔직하게 밝혀요. Known Gaps 섹션의 항목 11개 중 처음 5개:

Stripe DESIGN.md의 끝부분에서 원문 그대로 옮겼어요.
## Known Gaps

- **Many recipes did not reproduce exactly.** `button-primary` (84% pixel match), `card` (78%), `card-2` (94%), `promo-banner` (77%) and `skip-link` (0%; it is visually hidden until focused) are approximations. So are several header and footer recipes (`header-landing`, `header-inner-2` timed out, `footer-landing`, `footer-inner`, `footer-inner-2`).
- **Some recipes could not be judged at all.** `stat` and `stat-2` were not verifiable, because page media covered most of the element.
- **Some elements were never visible.** `footer-landing`, `header-inner` and `logo-strip-item` were not visible when verification ran, so their values come from computed styles only.
- **No section rhythm was measured.** `sectionRhythm` is empty, so vertical spacing between page sections and the inner padding of large cards is described only qualitatively.
- **No `base` spacing step was published.** The evidence frequency (4px, 8px, 12px, 16px and 24px most common) suggests a 4px-derived grid, but it is not a verified token.

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

여러분의 파일에는 그 파일만의 목록이 있을 거예요. 아래 확인 작업의 할 일 목록으로 활용하세요.

직접 확인할 것

항목파일이 놓칠 수 있는 이유할 일
로고, 아이콘, 이미지DESIGN.md는 파일이 아니라 스타일을 설명해요.현재 코드베이스에서 내보내 새 코드베이스와 함께 보관하세요.
로그인 후 화면추출은 공개 페이지만 볼 수 있어요.더 촘촘한 표나 사이드바처럼 앱이 마케팅 사이트와 어떻게 다른지 정리하세요.
상태hover와 focus는 추출 중 확인된 곳에서 기록되지만, pressed, disabled, error 상태는 기록되지 않는 경우가 많아요.폼과 버튼을 직접 눌러 보고 빠진 상태를 기록하세요.
모션전환과 애니메이션은 기껏해야 글로 설명돼요.현재 CSS에서 지속 시간과 이징을 기록하세요.
브레이크포인트추출은 데스크톱과 모바일 너비를 캡처해요.태블릿 레이아웃을 확인하고 열이 바뀌는 지점을 기록하세요.
샘플 밖의 템플릿Pro는 주요 페이지를 약 5개 샘플링해요.문서나 결제 페이지처럼 모습이 다른 페이지는 따로 추출하세요.

리빌드 후

새 사이트가 공개되면 다시 추출해 두 파일을 비교하세요. 바뀌지 않은 토큰은 모습이 유지되었다는 뜻이고, 바뀐 토큰은 계획한 리브랜딩이거나 고쳐야 할 어긋남이에요.

일반 텍스트 diff로도 바뀐 hex 값과 크기를 볼 수 있어요. Google의 @google/design.md 패키지에는 두 버전을 토큰 단위로 비교하는 diff 명령도 있어요. 형식과 도구는 DESIGN.md 설명 페이지에서 다뤄요. 작업 중에 파일을 직접 편집했다면 DESIGN.md 검사기로 확인하세요.

FAQ

리빌드 전에 디자인 시스템 추출하기: 자주 묻는 질문

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

아니요. DESIGN.md는 스타일을 설명하는 텍스트 파일이에요: 색상, 타이포그래피, 간격, 반경, HTML과 CSS로 된 컴포넌트 레시피. 로고, 아이콘, 일러스트, 사진은 현재 코드베이스나 디자인 파일에서 내보내 함께 보관하세요.

아니요. 추출은 방문자처럼 URL로 페이지를 불러오기 때문에, 로그인이 필요한 페이지, localhost, 사설 네트워크의 페이지는 지원하지 않아요. 공개 사이트를 추출하고, 로그인 후 화면이 어떻게 다른지는 따로 적어 두세요.

Pro는 사이트의 주요 페이지를 약 5개 샘플링하고, 찾은 내용을 DESIGN.md 하나로 합쳐요. 문서 페이지나 결제 페이지처럼 중요한 템플릿이 빠져 있다면 그 페이지의 URL도 추출해 두 파일을 비교하세요.

새 사이트가 공개되면 추출해서 두 파일을 비교하세요. Google의 @google/design.md 패키지에는 DESIGN.md의 두 버전을 토큰 단위로 비교하는 diff 명령이 있고, 일반 텍스트 diff로도 바뀐 hex 값과 크기를 볼 수 있어요.

바꾸기 전에 사이트를 기록해 두세요

프로덕션 URL을 붙여 넣으세요. Pro 추출은 주요 페이지를 샘플링해 DESIGN.md 하나를 돌려줘요.

현재 사이트의 DESIGN.md 추출하기

관련 가이드

모든 DESIGN.md 가이드 보기