CSS Variables

Overview

CSS custom properties are the runtime layer of Byteion's token system. JavaScript token files (packages/tokens/*.js) and the Tailwind preset (tailwind.preset.cjs) are build-time layers that generate utility class mappings. The CSS variables in packages/core/theme/variables.css are resolved by the browser at render time — change a variable and every utility that references it updates instantly.

These variables power all semantic utility classes:

How variables map to utilities

The Tailwind preset reads each CSS variable and maps it to a set of utility classes. The most common mappings are:

HSL format

All color CSS variables store raw HSL channel values — the hue saturation% lightness% triplet without the hsl() function wrapper. This format is required for Tailwind's <alpha-value> syntax, which powers utilities like bg-primary/50:

/* Correct — raw HSL channels */
--primary: 217 91% 60%;

/* Incorrect — hsl() wrapper breaks alpha utilities */
--primary: hsl(217 91% 60%);

/* Incorrect — hex cannot be used with alpha-value syntax */
--primary: #3b82f6;

Color variables (light)

All light-mode color variables, declared on :root and [data-theme="light"]. Each background token has a matching foreground token for text contrast:

:root, [data-theme="light"] {
 /* Surfaces */
 --background: 0 0% 100%;
 --foreground: 240 10% 3.9%;
 --card: 0 0% 100%;
 --card-foreground: 240 10% 3.9%;
 --popover: 0 0% 100%;
 --popover-foreground: 240 10% 3.9%;
 --muted: 240 4.8% 95.9%;
 --muted-foreground: 240 3.8% 43%;
 --accent: 240 4.8% 95.9%;
 --accent-foreground: 240 5.9% 10%;

 /* Brand */
 --primary: 217 91% 60%;
 --primary-foreground: 0 0% 100%;
 --secondary: 240 4.8% 95.9%;
 --secondary-foreground: 240 5.9% 10%;

 /* Feedback */
 --success: 160 84% 30%;
 --success-foreground: 0 0% 100%;
 --warning: 32 92% 36%;
 --warning-foreground: 0 0% 100%;
 --danger: 350 89% 47%;
 --danger-foreground: 0 0% 100%;
 --info: 189 94% 28%;
 --info-foreground: 0 0% 100%;

 /* Chrome */
 --border: 240 5.9% 90%;
 --input: 240 5.9% 90%;
 --ring: 217 91% 60%;
}

Dark mode variables

The .dark and [data-theme="dark"] selectors override the same variable names with dark-appropriate HSL values. Component classes never change — bg-background and text-foreground re-resolve because the variables they reference have changed:

.dark, [data-theme="dark"] {
 --background: 240 10% 3.9%;
 --foreground: 0 0% 98%;
 --card: 240 6% 10%;
 --card-foreground: 0 0% 98%;
 --popover: 240 6% 10%;
 --popover-foreground: 0 0% 98%;
 --muted: 240 3.7% 15.9%;
 --muted-foreground: 240 5% 64.9%;
 --accent: 240 3.7% 15.9%;
 --accent-foreground: 0 0% 98%;

 --primary: 217 91% 60%;
 --primary-foreground: 0 0% 100%;
 --secondary: 240 3.7% 15.9%;
 --secondary-foreground: 0 0% 98%;

 --border: 240 3.7% 15.9%;
 --ring: 217 91% 60%;
}

Brand colors (--primary, --ring) stay the same across modes — only surfaces, foregrounds, borders, and muted elements swap. For persisted toggling and system preference fallback, see the Dark Mode page.

Spacing variables

Spacing tokens control padding, margin, and gap utilities. They are consumed by the Tailwind preset and mapped to classes like p-md, gap-sm, and space-y-lg:

:root {
 --spacing-sm: 0.5rem;  /* 8px */
 --spacing-md: 1rem;    /* 16px */
 --spacing-lg: 1.5rem;  /* 24px */
}

These are legacy aliases consumed by the preset. The full spacing scale (inset, stack, surface groups) is defined in packages/tokens/spacing.js and mapped through the Tailwind preset.

Radius variables

Semantic radius tokens target specific component families. Each is backed by a rounded-* utility class:

:root {
 --radius-sm: 0.25rem;     /* Tight — small decorative elements */
 --radius-md: 0.375rem;    /* Default fallback */
 --radius-lg: 0.5rem;      /* Relaxed fallback */
 --radius-button: 0.5rem;  /* Buttons */
 --radius-input: 0.5rem;   /* Inputs, selects, textareas */
 --radius-badge: 9999px;   /* Badges, tags, pills */
 --radius-card: 0.75rem;   /* Cards, panels */
 --radius-panel: 1rem;     /* Sidebars, drawer panels */
 --radius-overlay: 1.25rem; /* Modals, dialogs, popovers */
}

Shadow variables

25 shadow tokens cover elevation, component states, and glow effects. Common variables:

See the Shadows page for the full elevation scale and all state / glow / dark tokens.

Z-index

Named z-index layers order overlapping UI elements consistently:

:root {
 --z-dropdown: 50;  /* Dropdown menus and popovers */
 --z-modal: 60;     /* Modal dialogs and backdrops */
 --z-toast: 70;     /* Toast notifications */
 --z-tooltip: 80;   /* Tooltips (highest layer) */
}

Motion

Duration variables control timing; easing variables control animation feel:

:root {
 /* Duration */
 --motion-fast: 120ms;   /* Hover / focus micro-interactions */
 --motion-normal: 200ms; /* Component transitions (default) */
 --motion-slow: 320ms;   /* Overlays, drawers, larger transitions */

 /* Easing */
 --easing-default: cubic-bezier(0.4, 0, 0.2, 1); /* Standard UI motion */
 --easing-in: cubic-bezier(0.4, 0, 1, 1);        /* Element entering viewport */
 --easing-out: cubic-bezier(0, 0, 0.2, 1);       /* Element leaving viewport */
}

Border and focus variables

:root {
 --border-width-sm: 1px;   /* Default border */
 --border-width-md: 2px;   /* Accent / active borders */
 --focus-ring-width: 2px;  /* Focus ring thickness */
 --focus-ring-offset: 2px; /* Space between ring and element */
}

Customization

Override any variable in your own CSS file. Load your overrides after the Byteion defaults so they take precedence:

@import '@byteion/core/theme/variables.css';
@import './brand-theme.css'; /* Your overrides */

:root {
 --primary: 270 100% 50%;
 --primary-foreground: 0 0% 100%;
 --ring: 270 100% 50%;
}

Override only what you need — the rest inherits Byteion's defaults. Always update foreground pairs when changing background tokens, and test contrast after changes.

Scoped theme variables

Scope variables under a [data-theme] selector to support multiple brands in a single codebase. Useful for white-label SaaS, client dashboards, theme previews, documentation examples, and template marketplaces:

[data-theme="purple"] {
 --primary: 270 100% 50%;
 --primary-foreground: 0 0% 100%;
 --ring: 270 100% 50%;
}

Apply the theme by setting data-theme="purple" on <html> or any container. Brand themes compose with .dark for multi-tenant dark mode support.

Do and Don't

Related

• Theming Guide — How to customize variables for a brand
• Dark Mode — How light / dark values swap
• Colors — Semantic and scale color tokens
• Shadows — Elevation and component shadow tokens