Design Tokens

Design tokens are the shared variables that define the UI system. They act like a contract between design and implementation, so components stay consistent and themeable as the system grows.

On this site, tokens help keep styling aligned across:

• the portfolio UI
• the component library
• the documentation site (Starlight)

Palette vs semantic tokens

There are two layers of color values:

• Palette tokens: raw color steps (ex: --color-french-blue-500)
• Semantic tokens: intent-based tokens components use (ex: --primary, --background)

Palette tokens

Palette tokens represent raw color steps (like the French Blue scale). They’re useful for building the system, but components should rarely reference them directly.

Example:

--color-french-blue-50: oklch(...);
--color-french-blue-500: oklch(...);
--color-french-blue-950: oklch(...);

Semantic tokens

Semantic tokens describe intent. These are what components should use.

They’re mapped differently in light and dark mode, so components adapt automatically without needing separate styles.

Example:

--background: oklch(...);
--foreground: oklch(...);

--primary: oklch(...);
--primary-foreground: oklch(...);

--accent: oklch(...);
--accent-foreground: oklch(...);

--muted: oklch(...);
--muted-foreground: oklch(...);

--border: oklch(...);
--ring: oklch(...);

Token usage rules

A few defaults that keep things consistent:

Components use semantic tokens (—background, —border) instead of palette values.

Palette tokens are for building the system and creating mappings (light/dark), not for day-to-day component styling.

If a component needs a new value, add a semantic token instead of hardcoding a one-off color.

Notes

Tokens are only useful when they reduce decision-making.

If a component needs special casing to “look right,” that’s usually a signal the semantic layer is missing something, not that the component should go off-script.