Guide

Rebuilding your site? Extract its design system first

A rebuild, a rebrand or a move to a new framework is when a design system quietly gets lost. The colors live in old CSS, the type scale in someone's head, the button states in a component nobody wants to open.

Extract your current site as a DESIGN.md before you change anything. You get a written baseline for the new build, one your team and your coding agent can both read.

Written for teams planning a rebuild, rebrand or migration. Updated .

What you'll get

  • A DESIGN.md of your current site, committed before the first line of the rebuild.
  • A clear view of what the file captured and what it did not.
  • A checklist of what to verify by hand: assets, states, motion, breakpoints and pages behind a login.
  • A way to compare the new site with the old one when you are done.

When to do this

  • A framework move. Same look, new stack. The DESIGN.md lets your coding agent rebuild components with the exact values instead of reading old stylesheets.
  • A rebrand. Capture the old system first, so you know exactly which colors, fonts and radii change and which stay.
  • A handover. A new agency or a new team gets one file that describes how the site looks today, instead of a tour of the codebase.

Steps

  1. Extract the live site before you change anything

    Paste your production URL on the Design Extractor home page and run a Pro extraction. It must be a public page: the extraction loads it like a visitor, so localhost and pages behind a login do not work.

  2. Commit it as the baseline

    Save it as DESIGN.md in the new repository and commit it before the rebuild starts. It now records how the site looked on that day.

  3. Read the Known Gaps section

    The end of the file lists what the run could not capture. Every item there is something to check by hand.

  4. Check what a DESIGN.md cannot hold

    Assets, logged-in screens, motion and the other items below. Add notes to the file as you go.

  5. Build against it

    Point your coding agent to the file, as the Claude Code and Cursor guide shows, and review each new screen against it.

What the file captured on Stripe

To see what you get, look at the Stripe DESIGN.md in the gallery. Its Pro run captured 5 pages of stripe.com: /nl, /nl/pricing, /nl/products, /nl/newsroom/news/stripe-openai-instant-checkout, /nl/contact/sales. A run on your own site produces the same structure.

Colors21 tokens, each with its role
Typography17 styles in Sohne
Radii10 tokens
Spacing62 tokens
Components71 recipes in HTML and CSS: 44 passed the check against the live page, 27 flagged or not checkable, each with the reason
SectionsOverview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts, Responsive Behavior, Iteration Guide, Known Gaps

What it says it missed

The file is honest about its limits. The first 5 of 11 items in its Known Gaps section:

From the end of Stripe's DESIGN.md, as written.
## 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.

Extracted from Stripe's public website, not official brand guidelines. Read the full Stripe DESIGN.md

Your own file will have its own list. Treat it as your to-do list for the checks below.

What to check by hand

ItemWhy the file may miss itWhat to do
Logo, icons, imagesA DESIGN.md describes styles, not files.Export them from the current codebase and keep them with the new one.
Logged-in screensThe extraction only sees public pages.List how the app differs from the marketing site, such as denser tables or a sidebar.
StatesHover and focus are recorded where the run saw them; pressed, disabled and error states often are not.Click through forms and buttons and note the missing states.
MotionTransitions and animations are described in words at most.Note durations and easing from the current CSS.
BreakpointsThe run captures a desktop and a mobile width.Check the tablet layout and note where columns change.
Templates outside the samplePro samples around five key pages.Extract any page that looks different, such as docs or checkout, on its own.

After the rebuild

When the new site is live, extract it again and compare the two files. Unchanged tokens mean the look survived; changed ones are either the rebrand you planned or drift to fix.

Any text diff shows the changed hex values and sizes. Google's @google/design.md package adds a diff command that compares two versions token by token; the DESIGN.md explainer covers the format and its tooling. If you edit the file by hand along the way, check it with the DESIGN.md Validator.

FAQ

Extract your design system before a rebuild: questions

Short answers to what people ask before they try this.

No. A DESIGN.md is a text file that describes styles: colors, typography, spacing, radii and component recipes in HTML and CSS. Export the logo, icons, illustrations and photos from your current codebase or design files and keep them next to it.

No. The extraction loads the page from its URL like a visitor would, so pages behind a login, on localhost or on a private network are not supported. Extract the public site, and write down how the logged-in screens differ.

Pro samples the key pages of the site, around five, and merges what it finds into one DESIGN.md. If an important template is not among them, such as a docs page or a checkout, extract that page's URL as well and compare the two files.

Extract the new site once it is live and compare the two files. Google's @google/design.md package has a diff command that compares two versions of a DESIGN.md token by token, and any text diff shows changed hex values and sizes.

Capture your site before you change it

Paste your production URL. A Pro extraction samples its key pages and returns one DESIGN.md.

Get a DESIGN.md of your current site

Related guides

See all DESIGN.md guides