Creating design tokens for Hygraph

A perceptual color palette tells you which colors exist. It doesn't tell you which one to pick. That's the job of design tokens, and Baukasten didn't have good ones.

What wasn't working

Our old setup had a few recurring problems:

• Core colors were used directly in designs. A name like gray-500 gives no clue where it belongs, so designers couldn't tell primary-400 from primary-500 and made arbitrary choices.
• Every design needed a color check, because non-semantic names were so error-prone.
• Semantic names only existed at component level, which meant far too many tokens with far too long names.
• No CSS custom properties, so theming was hard. On top of that, our CSS-in-JS setup wasn't supported in React Server Components.

Goals

We set ourselves a short list:

1. A clear token taxonomy where the name explains where the token is used.
2. Avoid component-specific tokens unless a design consideration truly outweighs system thinking.
3. The same names in Figma and in code, so design and engineering share one language.
4. Keep it simple, with no useless parts.

Two layers, not three

Many systems use three layers: core tokens hold values, semantic tokens point at core tokens, and component tokens point at both. We dropped the third.

Component tokens look tidy at first and become a maintenance burden fast. Nate Baldwin, who created Adobe Spectrum, has written about Spectrum growing to more than 210,000 tokens in an 18MB JSON file. Material 3, Atlassian, Polaris and Loom's Lens all use semantic tokens only. So did we.

A naming convention

Every token follows one template: property, context, variant, state.

By the time it shipped, the template had settled into four families: bg, fg-text, fg-icon and border, plus fg-link for links. A few real examples:

States live on the background

Most background tokens come with state variants (hover, pressed, selected and disabled), and they always move in the same direction.

Text works differently. Our rule: state is always shown by the background, except for disabled. A button's label stays the same color whether it's hovered or pressed, so text tokens have no hover or pressed variants. Links are the one exception: they have no container to change, so fg-link-base-hover exists and fg-text-base-hover doesn't.

Instead of states, text gets a strength scale. Everything down to muted passes AA on white:

Surfaces

Surfaces are background colors that give designers flexibility for containers. They're numbered by depth, so bg-surface-1 is barely off-white and bg-surface-90 is almost black. A separate bg-surface-dark-* set stays dark in every theme. We needed it for the data grid.

Accent colors, more than a dozen hues like teal, olive and rose, exist too, but only for pills and schema field icons. They're deliberately kept out of everything else.

How it ships

Tokens are CSS custom properties on :root, stored as RGB channels. Each one becomes a Tailwind utility with exactly the same name, so the class in code is the token in Figma:

:root {
  --bg-primary: 93 87 225;
  --bg-primary-hover: 70 64 185;
  --fg-text-base: 52 58 85;
}
 
.bg-primary {
  --tw-bg-opacity: 1;
  background-color: rgba(var(--bg-primary) / var(--tw-bg-opacity, 1));
}

Because values are channels, any token can take an opacity without a new variable, and switching themes means swapping one set of custom properties.

The result

Baukasten now has around 240 color tokens, and none of them is tied to a single component. Designers pick colors by role instead of by shade, engineers write the same names in their classes, and the name itself says where a color belongs.