Star5

/ Docs

Theme tokens

Every color, radius, font, and transition in Zyra UI is a CSS custom property, organized in layered tiers — primitives, per-theme raw tokens, semantic tokens, dimension tokens, and per-component tokens. Override the semantic layer and everything downstream — including per-component tokens — follows automatically. Prefer to see them applied live? Open the theming page →

Tier 0 — Primitives

Raw palette values. Identical across all five themes and never read by components directly — every other tier derives from (or replaces) these.

Cyan scale
--zyra-color-cyan-50--zyra-color-cyan-100--zyra-color-cyan-200--zyra-color-cyan-300--zyra-color-cyan-400--zyra-color-cyan-500--zyra-color-cyan-600--zyra-color-cyan-700--zyra-color-cyan-800--zyra-color-cyan-900--zyra-color-cyan-950

Per-theme tokens (raw)

Defined once per theme file with identical names and different values — this is what actually changes when you switch between dark, light, ocean, amber, and rose. See it live on the theming page.

Surfaces
--zyra-color-bg-app--zyra-color-bg-panel--zyra-color-bg-surface--zyra-color-bg-raised
Borders
--zyra-color-border--zyra-color-border-hover--zyra-color-border-strong
Text
--zyra-color-text--zyra-color-text-muted--zyra-color-text-dim--zyra-color-text-inverse--zyra-color-surface-inverse
Glow (RGB channels)
--zyra-color-glow
Accent
--zyra-color-accent--zyra-color-accent-hover--zyra-color-accent-muted--zyra-color-accent-border--zyra-focus-ring
Secondary / tertiary accents
--zyra-color-accent-secondary--zyra-color-accent-secondary-muted--zyra-color-accent-secondary-border--zyra-color-accent-tertiary--zyra-color-accent-tertiary-muted--zyra-color-accent-tertiary-border
Status (raw)
--zyra-color-success / -muted / -border--zyra-color-warning / -muted / -border--zyra-color-danger / -muted / -border / -text--zyra-color-info / -muted / -border
Shadows
--zyra-shadow-sm--zyra-shadow-md--zyra-shadow-accent--zyra-shadow-glow
Buttons (raw)
--zyra-color-btn-primary-text--zyra-color-btn-ghost-hover-bg
Inputs (raw)
--zyra-color-input-bg--zyra-color-input-border--zyra-input-shadow-focus
Cards (raw)
--zyra-color-card-bg--zyra-color-card-border--zyra-color-card-section-bg--zyra-card-shadow--zyra-card-elevated-shadow--zyra-card-focus-ring
Misc
--zyra-color-code-bg--zyra-color-overlay-bg--zyra-color-scrollbar-thumb-base / -track-base--zyra-color-tooltip-bg / -text / -border--zyra-tooltip-shadow--zyra-color-toast-bg / -border--zyra-color-spinner-inverse-track / -head--zyra-color-pill-active-bg--zyra-pill-active-shadow--zyra-color-preview-stage-bg--zyra-color-glass-bg--zyra-color-header-glass-bg--zyra-header-backdrop-base--zyra-header-shadow-base

Tier 1 — Semantic

Role-based aliases over the per-theme raw tokens above. This is the layer components read from and the layer you should override — everything downstream follows automatically.

Canvas / background
--zyra-color-background--zyra-color-background-elevated
Surface
--zyra-color-surface--zyra-color-surface-subtle--zyra-color-surface-inset--zyra-color-surface-dropdown--zyra-color-overlay-scrim
Foreground / text
--zyra-color-foreground--zyra-color-foreground-muted--zyra-color-foreground-subtle
Brand / primary
--zyra-color-primary--zyra-color-primary-hover--zyra-color-primary-subtle--zyra-color-primary-border
Border
--zyra-color-border-color--zyra-color-border-strong-color
Status
--zyra-color-success-foreground / -subtle / -border-color--zyra-color-warning-foreground / -subtle / -border-color--zyra-color-danger-foreground / -subtle / -border-color--zyra-color-info-foreground / -subtle / -border-color
"On" roles (content over a filled bg)
--zyra-color-on-brand--zyra-color-on-success--zyra-color-on-warning--zyra-color-on-danger--zyra-color-on-info
Focus
--zyra-ring

Tier 2 — Dimension

Typography, shape, motion, spacing, and z-index. Theme-invariant — identical values across all five themes.

Typography
--zyra-font-display--zyra-font-body--zyra-font-mono
Radius
--zyra-radius-xs--zyra-radius-sm--zyra-radius-md--zyra-radius-lg--zyra-radius-xl--zyra-radius-2xl--zyra-radius-full
Motion — easing
--zyra-ease-standard--zyra-ease-spring
Motion — duration
--zyra-duration-fast--zyra-duration-moderate--zyra-duration-base--zyra-duration-slow
Motion — transition (duration + easing)
--zyra-transition-fast--zyra-transition-moderate--zyra-transition-base--zyra-transition-slow--zyra-transition-spring
Spacing
--zyra-space-1 … --zyra-space-6--zyra-space-8--zyra-space-10--zyra-space-12--zyra-space-16--zyra-space-20
Z-index
--zyra-z-base--zyra-z-raised--zyra-z-dropdown--zyra-z-sticky--zyra-z-overlay--zyra-z-modal--zyra-z-tooltip--zyra-z-toast

Tier 3 — Component

Per-component namespaced aliases over the semantic and dimension tiers, grouped the same way the component library itself is organized. Implementation detail — override the semantic tier upstream instead.

Actions — Button
--zyra-color-btn-primary-bg / -border / -hover-bg--zyra-color-btn-secondary-bg / -text / -border / -hover-bg / -hover-border--zyra-color-btn-ghost-text / -hover-bg / -hover-text--zyra-color-btn-danger-bg / -text / -border / -hover-bg / -hover-text / -hover-border--zyra-color-btn-outline-hover-bg / -hover-border--zyra-btn-disabled-opacity--zyra-btn-focus-ring
Navigation — Header
--zyra-header-bg / -border / -border-width--zyra-header-padding-x / -gap--zyra-header-height / -height-sm / -height-lg--zyra-header-burger-size / -burger-radius--zyra-header-z-index--zyra-header-glass-bg / -backdrop / -shadow--zyra-header-divider-color / -divider-width
Navigation — Sidebar
--zyra-color-sidebar-bg / -border--zyra-color-sidebar-heading / -text / -text-hover / -text-active--zyra-color-sidebar-hover-bg / -active-bg--zyra-color-sidebar-badge-bg / -badge-text
Navigation — Drawer
--zyra-color-drawer-bg / -text / -border--zyra-drawer-width / -max-width / -padding--zyra-drawer-nav-item-gap / -section-gap / -footer-gap--zyra-drawer-shadow
Navigation — Tabs
--zyra-color-tabs-text / -text-hover / -text-active--zyra-color-tabs-border / -indicator--zyra-color-tabs-badge-bg / -badge-text / -badge-active-bg / -badge-active-text--zyra-color-tabs-pill-active-bg--zyra-tabs-pill-active-shadow
Forms — Checkbox / Radio
--zyra-color-checkbox-bg / -border / -checked-bg / -checked-border / -mark--zyra-checkbox-focus-shadow--zyra-color-radio-bg / -border / -checked-border / -checked-bg / -dot--zyra-radio-focus-shadow
Forms — Switch / Toggle
--zyra-color-switch-track-off / -track-on--zyra-switch-ring--zyra-color-toggle-border / -bg-on / -fg-on--zyra-toggle-ring
Forms — Form-field
--zyra-field-label-font--zyra-color-field-label-color / -required-mark / -icon-color--zyra-color-field-bg / -border / -filled-bg / -focus-border--zyra-field-focus-shadow--zyra-color-field-hint-color / -counter-color / -counter-warn / -counter-error--zyra-color-field-success-color / -error-color--zyra-field-success-shadow / -error-shadow
Forms — Select
--zyra-color-select-text / -placeholder / -icon--zyra-color-select-bg / -border / -filled-bg / -focus-border--zyra-select-focus-shadow--zyra-color-select-panel-bg / -panel-border--zyra-select-panel-shadow
Forms — Slider / File upload
--zyra-color-slider-track / -fill / -thumb / -thumb-ring / -text--zyra-color-file-upload-bg / -text / -border
Data display — Card & glow
--zyra-color-card-border / -hover-border--zyra-card-radius--zyra-card-focus-ring--zyra-color-glow-border / -glow-shadow / -glow-shadow-strong / -glow-surface
Data display — Avatar / Code block
--zyra-color-avatar-primary-end / -blue-end / -purple-end / -warm-end / -contrast--zyra-color-code-keyword / -tag / -attr / -string / -number / -comment / -punct
Data display — Carousel / Calendar
--zyra-color-carousel-bg / -text / -border--zyra-color-calendar-bg / -text / -border
Feedback — Progress
--zyra-color-progress-track-bg / -track-border / -label-color--zyra-color-progress-default / -success / -warning / -danger / -info
Overlay (generic — Drawer, Modal, Command Palette)
--zyra-overlay-bg--zyra-overlay-z-index--zyra-overlay-fade-duration
Utilities — Scroll area / Theme switch
--zyra-color-scrollbar-thumb / -thumb-hover / -track--zyra-color-theme-switch-bg / -bg-hover / -text / -border--zyra-color-theme-switch-panel-bg / -panel-shadow

What can I change?

Semantic and dimension tokens are the supported customization surface — override these and everything downstream follows. Primitives, per-theme raw tokens, and per-component tokens are implementation detail: they already derive from (or feed) the semantic layer, and their names can change between component updates.

✅ Safe to override

Semantic color (recommended)--zyra-color-background / -background-elevated--zyra-color-surface / -surface-subtle / -surface-inset--zyra-color-foreground / -foreground-muted / -foreground-subtle--zyra-color-primary / -primary-hover / -primary-subtle / -primary-border--zyra-color-border-color / -border-strong-color--zyra-color-success / warning / danger / info -foreground / -subtle / -border-color--zyra-ring
Dimension (shape, type, motion, space)--zyra-radius-xs … radius-2xl / radius-full--zyra-space-1 … space-20--zyra-font-body / display / mono--zyra-ease-standard / ease-spring--zyra-transition-fast / moderate / base / slow / spring

🚫 Internal — don't override directly

Primitives (raw palette)--zyra-color-cyan-50 … cyan-950
Per-theme raw tokens--zyra-color-bg-app / -accent / -text — swap themes instead of these directly
Component tokens (derived, per-component)--zyra-color-btn-primary-bg--zyra-color-checkbox-checked-bg--zyra-color-tabs-badge-bg--zyra-color-field-* / select-* / progress-* / header-* / sidebar-*

Override example

Set any semantic token after the Zyra import — no forking a theme file required.

/* global styles.css — override any token */
:root {
  --zyra-color-primary:       #7c3aed;
  --zyra-color-primary-subtle: #ede9fe;
  --zyra-radius-md:           6px;
  --zyra-font-body:           'Inter', sans-serif;
}