Design Tokens That Scale (Without Getting Mushy)

February 6, 2026

AI SUMMARY

Use a tiny set of semantic tokens: `background.main/soft`, `text.main/sub/muted`, `border.soft`, and `brand`. Map them to CSS variables on `html.light`/`html.dark`, then reference them via Tailwind colors. Keep borders extremely subtle and reserve the brand color for metadata accents.

Maria Santos

Design Lead

View author page

Share this article

On this page

Great documentation blogs look “clean” because everything is token-driven and low-noise.

Token strategy

We intentionally keep the token set small:

background.main, background.soft
text.main, text.sub, text.muted
border.soft
brand

Why “soft borders” matter

When borders are too strong, the UI becomes a spreadsheet. The goal is to have frames that are visible only when you’re looking for them.

Tailwind mapping

We map CSS variables to Tailwind colors so components stay readable:

// tailwind.config.cjs
colors: &#123;
  background: &#123;
    main: "rgb(var(--c-background-main) / <alpha-value>)",
    soft: "rgb(var(--c-background-soft) / <alpha-value>)",
  &#125;,
&#125;