Token contract
Zentauri UI exposes theme controls as CSS variables prefixed with --zui-. Component class strings include hardcoded fallbacks, so a missing override still renders with the library default.
The global token source is src/design-system/tokens.ts. This docs page reads those exported constants and shows the foundation tokens that component variables use as their fallback layer.
How the --zui-* contract resolves
The token system resolves in three layers: component-scoped variables first, shared global variables second, and literal fallbacks last. That lets teams theme a whole product through :root and .dark while still making precise exceptions for one component slot or appearance.
Preview appearances and copy variables
Use the token playground to switch between appearance presets, preview how buttons, badges, alerts, and inputs inherit the variables, and copy the CSS override block into an app theme.
Override globals first
Set brand, foreground, surface, border, status, and palette variables on :root and .dark to create a full product theme. Component variables such as --zui-button-default-bg remain available for exceptions on each component preview page, but most teams can theme broad surfaces with the smaller global token set.
Theming strategy
Start with global tokens for brand colors, status colors, surfaces, borders, focus rings, ring offsets, shadows, and shared radius. Then override component-level variables on each component page when you need appearance-specific colors, borders, shadows, or hover states.
Keep light and dark values paired so Tailwind scans both class variants and your theme remains predictable across mode changes.
Common use cases
- Set one brand color palette across every interactive primitive.
- Generate broad light and dark themes without hand-authoring component variables.
- Use component-specific variables only when a single component needs a custom override.
- Set brand focus-ring colors across every interactive primitive.
- Align light and dark mode ring offsets with an app shell background.
- Standardize large-radius surfaces without editing component source.
- Document a product theme for downstream teams that vendor components with the CLI.
FAQ
Are these the only CSS variables Zentauri UI supports?
No. This page focuses on global tokens from src/design-system/tokens.ts. Component pages include their own CSS variable sections for component-specific appearances, slots, and states. Component tokens still win when both are set.
Do I need to override dark variables?
Only when your dark theme should differ from the shipped fallback. Dark tokens use the same name with -dark appended.
Where should overrides live?
Place broad theme overrides on :root and .dark, or scope them to a wrapper class when a product surface needs a local theme.
Should I override global tokens or component tokens?
Start with global tokens for brand, foreground, surface, border, status, and palette values. Add component-level overrides only for deliberate exceptions such as a custom button appearance or a special alert tone.