Design Tokens

Overview

Design tokens are the atomic values that power every visual aspect of Byteion. They are the single source of truth for colors, spacing, typography, shadows, borders, and motion. Instead of hardcoding values like #3b82f6 or 0.5rem, components reference semantic tokens like bg-primary and spacing values like p-md. This ensures visual consistency across every screen and enables systematic re-theming without touching component markup.

Why this exists

Without tokens, changing a brand color requires searching for every occurrence of bg-blue-500 and text-blue-600 across 50+ components. With tokens, you change one CSS variable (--primary) and every component that references it updates simultaneously. This is not just about efficiency — it ensures that the entire system responds to a change in a predictable, consistent way. Tokens also create a shared vocabulary between designers and developers: when a designer says "use the primary color", the developer reaches for bg-primary, not bg-blue-500.

System philosophy

Token layers

Tokens exist in three layers, each serving a distinct role:

Token types

Byteion defines three categories of tokens, each with a different purpose and audience:

Naming system

Tokens follow a consistent naming pattern:

Categories

Practical usage

Developers use tokens through Tailwind utility classes. Always prefer semantic and component tokens over raw scale steps in shared components:

<!-- Button using semantic tokens -->
<button class="inline-flex items-center gap-2 rounded-button bg-primary px-md py-sm text-primary-foreground shadow-button hover:bg-primary/90">
  Save changes
</button>

<!-- Card using surface and component tokens -->
<div class="rounded-card border border-border bg-card shadow-card">
  <div class="p-surface-card">
    <h3 class="font-semibold text-foreground">Card title</h3>
    <p class="text-muted-foreground mt-2">Card body content goes here.</p>
  </div>
</div>

<!-- Badge using component tokens -->
<span class="inline-flex items-center rounded-badge bg-primary/10 px-inset-xs py-0.5 text-xs font-medium text-primary">
  Active
</span>

Behind the scenes

Each utility class is backed by a CSS variable. The / <alpha-value> syntax enables Tailwind's opacity modifier (bg-primary/50):

/* Semantic color mapping */
.bg-primary {
  background-color: hsl(var(--primary) / <alpha-value>);
}
.text-primary-foreground {
  color: hsl(var(--primary-foreground) / <alpha-value>);
}
.bg-card {
  background-color: hsl(var(--card) / <alpha-value>);
}

/* Component token mapping */
.rounded-card {
  border-radius: var(--radius-card);
}
.shadow-card {
  box-shadow: var(--shadow-card);
}
.rounded-button {
  border-radius: var(--radius-button);
}

/* Spacing mapping */
.px-md {
  padding-left: var(--spacing-md, 1rem);
  padding-right: var(--spacing-md, 1rem);
}

Color CSS variables store raw HSL channel values (hue saturation% lightness%) without the hsl() wrapper. This is required for Tailwind's alpha-value syntax:

:root {
  /* Correct — raw HSL channels enable bg-primary/50 */
  --primary: 217 91% 60%;
  --primary-foreground: 0 0% 100%;

  /* Component tokens store full values */
  --radius-card: 0.75rem;
  --shadow-card: 0 1px 3px 0 rgb(0 0 0 / 0.04), 0 1px 2px -1px rgb(0 0 0 / 0.04);
}

Semantic vs scale tokens

Choosing the right token type depends on context:

Avoid using raw scale steps (e.g. bg-primary-500) everywhere in application UI unless the purpose is clear. Prefer bg-primary so that a brand theme override of --primary flows through automatically.

Do and Don't

Customization

Override tokens by redefining CSS variables in your project. This is the recommended approach for white-label theming because it requires no component markup changes:

/* Override semantic tokens for a white-label theme */
:root {
  --primary: 270 100% 50%;
  --primary-foreground: 0 0% 100%;
  --radius-card: 0.75rem;
  --shadow-card: 0 4px 12px rgb(0 0 0 / 0.08);
}

Each layer serves a different customization scenario:

• CSS variables — Runtime customization. Change at the :root level for immediate visual updates. Best for multi-brand or white-label themes.
• JS tokens — Build-time source. Edit the token files in packages/tokens/ when you need to change the foundation of the system.
• Tailwind preset — Maps both into utility classes. Extend the preset to add new tokens or override existing mappings.

To add entirely new tokens, extend the Tailwind preset:

const byteionPreset = require('@byteion/core/preset');

module.exports = {
  presets: [byteionPreset],
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
      },
    },
  },
};

For advanced multi-brand theme setup, see the Theming Guide.

Relationship to components

Every Byteion component uses tokens internally. Components never hardcode values — they reference semantic and component tokens throughout:

When you change a token, every component that uses it updates. Change --primary and all primary buttons, links, focus rings, and active indicators update simultaneously. Change --radius-card and every card across the application adopts the new rounding — no markup changes needed.

Developer tips

Common mistakes

Production usage tips

Related

• CSS Variables — Complete reference of all CSS custom properties
• Theming Guide — Multi-brand and advanced theme setup
• Colors — Color token system and palette
• Spacing — Spacing scale reference
• Shadows — Shadow token reference
• Tailwind Preset — Preset configuration details