Most people do one of two things. They use the DESIGN.md exactly as-is and end up with a product that looks like someone else's. Or they start changing everything at once and end up with something incoherent.

There is a better way. Change one thing at a time. Start with color. Here is the exact process.

Start with one thing: the primary color

Do not touch fonts. Do not touch spacing. Do not touch anything in the component guidelines. Change only the primary color first.

Then look at the output. Does it feel right? If it does, you might be done. If it feels like something is still off, now you can investigate further.

This sounds obvious but most people do not do it. They swap the color, change the font, tweak the spacing, and then have no idea which of those changes caused the issue they are looking at.

The 3 rules of color customization

Rule 1: Keep the same value/saturation relationship

If the original primary was a highly saturated indigo, your replacement should also be highly saturated. If it was a muted blue-gray, your replacement should be muted. The vibrancy of your primary sets the vibrancy of the whole palette.

Rule 2: Test on-primary contrast at 4.5:1

Your primary is used for buttons and interactive elements. Text sits on top of it. That text needs to be 4.5:1 contrast against the primary or you have an accessibility failure. Use the WebAIM contrast checker. White (#FFFFFF) works on anything darker than about #767676.

Rule 3: Update hover and active states proportionally

Primary-hover should be 8-10% darker than primary. If you picked a dark primary, your hover will be very dark. That is fine. Do not invent a new color — just darken what you have.

Here is what the color section looks like after a proper swap:

colors:
  primary: "#4F46E5"        # your brand color
  on-primary: "#FFFFFF"     # text on top of primary
  primary-hover: "#4338CA"  # 8% darker than primary
  background: "#0A0A0A"
  surface: "#111111"
  surface-2: "#1A1A1A"
  text: "#F4F4F5"
  text-muted: "#A1A1AA"
  border: "#27272A"
  accent: "#4F46E5"         # same as primary
  success: "#16A34A"        # do not touch
  danger: "#DC2626"         # do not touch
  warning: "#D97706"        # do not touch

How to swap fonts

The font roles in DESIGN.md are: display, heading, body, code. Keep those four roles. Just change the font-family values.

Do not change font sizes, weights, or letter-spacing when you swap the font. Those values were chosen to work with the original font. If you change the font and the sizes at the same time, you will not know what caused any problems.

typography:
  display:
    fontFamily: "'Geist', system-ui, sans-serif"   # swap this
    fontSize: "48px"                                # keep this
    fontWeight: 600                                 # keep this
    lineHeight: 1.1                                 # keep this
    letterSpacing: "-0.03em"                        # keep this
  heading:
    fontFamily: "'Geist', system-ui, sans-serif"   # swap this
    fontSize: "24px"
    fontWeight: 600
    lineHeight: 1.3
    letterSpacing: "-0.02em"
  body:
    fontFamily: "'Geist', system-ui, sans-serif"   # swap this
    fontSize: "15px"
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: "0em"
  code:
    fontFamily: "'JetBrains Mono', monospace"      # swap this separately
    fontSize: "13px"
    fontWeight: 400
    lineHeight: 1.5

One more thing: code font is a separate decision. Most design systems use Inter or Geist for UI and JetBrains Mono or Fira Code for code. Those are two different choices and should be made independently.

Spacing: only touch the base value

The spacing scale (4, 8, 12, 16, 24, 32, 48, 64, 96) is built on a base unit. Most systems use 4px. If you want your UI to feel tighter, go to 3px. If you want more breathing room, go to 5px.

Do not change the ratios. The whole scale should scale together.

spacing:
  base: "4px"      # change this to 3px for tighter, 5px for looser
  scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]  # keep the ratios

What NOT to customize

Semantic colors: success, danger, warning. Leave them alone.

These are universal. Green means success. Red means danger. Yellow means warning. Your users know this. AI tools know this. If you change danger to orange because orange is your brand color, the AI will use your brand color for error states and it will look wrong.

The semantic colors are not your brand. They are communication infrastructure. Treat them like road signs.

The test

After you make changes, run this exact prompt with your updated DESIGN.md:

Using the DESIGN.md in my project, build a dashboard page with a sidebar nav, a stats grid showing 4 metrics, and a recent activity table.

Look at the output. Does everything feel coherent? Does the sidebar use the right surface color? Do the buttons use the primary color? Does the table use the right border and muted text colors?

If something looks off, trace it back to the token. Is the border color too light? Find where border is defined. Is the card background wrong? Check surface. Every visual problem maps to a token. Fix the token, not the generated code.

That is the whole system. Change one thing, test it, change the next thing.

Find a starting point

Browse the catalog, find a design system that is close to what you want, and customize from there.

Browse the catalog