Edit foundations without breaking them

Colour ramps, semantic aliases and per-theme values all depend on each other. Edit them in the right order and one fix won't undo another.

Where the values live

Foundations is where every raw value in your system lives. Components, modules, pages and the generated documentation all read from it. Change a value here and it moves everywhere that references it, including places you forgot about.

There are nine tabs:

Most of your editing time goes into the first three. The rest are small scales you'll set once and rarely touch.

Light and dark values

Colour tokens hold one value per theme. The Light and Dark buttons in the Colors toolbar ("Edit light mode values", "Edit dark mode values") flip which set you're editing. The editor also tells you which mode you're in, so you don't fix dark mode by accident while looking at light.

Only colours change between themes. As the editor puts it: "Your components do not change between themes. Only the colours they resolve to." A button has the same radius, padding and type in both themes. What moves is the colour each token resolves to.

That brings a gotcha. Fixing a hex in light mode does nothing to dark mode. When you correct a contrast problem in one theme, switch and check the other before you move on. Dark mode is a second theme explains why it's built this way.

Ramps and aliases in practice

Colour has two layers.

Primitive ramps are the palette. Each hue (primary, secondary, neutral, success, warning, danger, info) is a ladder of steps: 0, 50, 100 and so on up to 900, then 1000. Low steps are light, high steps are dark.

Semantic tokens are the roles: background, surface, foreground, primary, border, ring, the status colours and so on. Each one points at a ramp step, separately for each theme. In light mode background points at neutral-50. In dark mode it points at neutral-1000.

:root {
  /* the palette: declared once */
  --neutral-50: #f7f7f8;
  --neutral-900: #18181b;
  --neutral-1000: #0b0b0d;

  /* the roles, dark theme */
  --background: var(--neutral-1000);
  --primary: var(--primary-400);
}

[data-theme="light"] {
  /* same roles, different steps */
  --background: var(--neutral-50);
  --foreground: var(--neutral-900);
  --primary: var(--primary-500);
}

This changes how you should edit.

Edit a hue, not a dozen hexes. If primary is slightly too cold, don't nudge twelve swatches one by one. Open Refine palette from the button at the end of the Colors header, give Primary the hex you want, and apply. The whole ladder is rebuilt from it, the steps stay evenly spaced, and every alias pointing into it follows. One step off? In the same dialog, click that step on its ladder and set it there, against its neighbours. Asking Ask Flash to "Make the primary colors warmer" does the same thing as a patch you can review.

When one role looks wrong, it's usually the pointer. Dark-mode borders too faint? The neutral step is probably fine. border is pointing one step too close to the background. Changing that step's hex would also change everything else that uses it.

Re-check contrast after hand edits. Generated systems check text and fill pairs against WCAG AA: 4.5:1 for body text, 3:1 for large text and UI fills. Your manual edits get no such check. Open Ask Flash with {{⌘K}} and run "Check my text contrast for accessibility" when you're done. Contrast in practice covers the numbers.

Lock what's finished

Open a token and click the lock (Lock token). A locked token shows a lock mark, and it can't be edited or renamed until you click the lock again. Refine palette skips locked swatches, so you can lock the exact brand primary and still shift the rest of the ramp around it.

[!NOTE] A token lock guards against your own stray clicks in this browser. It isn't a permission. To stop teammates editing, give them the Viewer role. It's also different from Lock on a project card in the Dashboard, which stops the whole system from being deleted.

Add tokens

On every tab except Colors, the Add token button in the toolbar adds a single token. Colors works through the group instead: open a colour group's menu and choose Add tokens, "Add one colour, or a whole set of lighter and darker shades." Take the shades option when you're adding a new hue. You get a ladder that matches the others instead of one orphan swatch.

Token names have to be unique across the whole system, not just within a tab. The editor tells you if a name is already taken.

Fonts

In Typography, the font picker has three sections: Fonts in use, then Google Fonts grouped by category, with a search box on top ("Search fonts…").

• Any Google font by name. Type the family name. If it's not in the list, it appears under Any Google font and loads from Google Fonts when you pick it.
• Your own files. Upload takes .woff, .woff2, .ttf and .otf. Use it for licensed webfonts that Google doesn't host.

Change the family on a type token and every style using that token follows. If you use the Figma plugin, install the same fonts on your machine before building the file. Otherwise the build falls back to Inter. See keeping a Figma file in sync.

A safe editing order

Foundations depend on each other, and editing in the wrong order means doing some work twice.

1. Colour first. Everything reads it, and contrast checks are only meaningful once the palette is settled.
2. Type second. Font choice changes how big text feels, so sizes and line heights come after the family.
3. Spacing third. Padding and gaps should relate to your body size and line height. Set them after type, not before.
4. Radius and shadow fourth. They're finishing decisions and they look different at different densities, so set them once spacing is right.
5. Motion last. It's invisible in a static review. Tune it when everything else has stopped moving.

After each step, open Components and look at a button, an input and a card. Those three show most mistakes. Then lock what you're happy with and move to the next tab.

When the foundations feel right, Ask Flash prompts that change real tokens covers the faster route for broad changes, and getting your tokens into code takes you the rest of the way.