Theme
Component theme defaults and color mode configuration for Nuxt UI. Defines per-component defaultVariants, slot overrides, and light/dark color mode shade mappings for the Ontopix design system.
The theme system provides a single source of truth for all Nuxt UI component defaults. Values flow through the stylebook build pipeline into app.config.ts (component defaults) and ontopix.css (color mode overrides).
Package
The theme is distributed as part of the @ontopix/nuxt-layer-ui package. This Nuxt layer provides:
nuxt.config.ts— Globalcolorandsizedefaults viaui.theme.defaultVariants(build-time)app.config.ts— Per-componentslotsanddefaultVariantsoverrides (runtime)ontopix.css— Color mode CSS variable overrides for light/dark themes
When you install @ontopix/nuxt-layer-ui as a Nuxt layer, these files are automatically merged into your application — no manual copying required.
How It Works
Theme data is authored in brand/theme/*.yaml and flows through the stylebook build pipeline:
brand/theme/*.yaml → brand.json → Jinja2 templates → @ontopix/nuxt-layer-ui
The Nuxt UI theming system has two complementary configuration layers:
| Layer | File | Scope | When |
|---|---|---|---|
| Global defaults | nuxt.config.ts | color and size for all components | Build-time (module option) |
| Component overrides | app.config.ts | Any variant, per component | Runtime (app config merge) |
| Color modes | ontopix.css | CSS variables for light/dark | Runtime (CSS cascade) |
For installation and customization details, see Installation & Customization.
Global Defaults
The build-time baseline applied to all Nuxt UI components:
| Property | Value |
|---|---|
color | neutral |
size | md |
Component Defaults
Per-component overrides configured at runtime. Each component can define slots (Tailwind CSS class defaults), variants and compoundVariants (variant-specific overrides), and defaultVariants (variant prop defaults). Only actual overrides are listed — components not shown here use NuxtUI defaults.
Components with Custom Variants
| Component | Default Variants |
|---|---|
alert | variant=subtle |
banner | color=prominent |
chip | color=prominent, size=xl |
contentToc | highlightColor=navigation |
Slot-Based Components
14 components have Tailwind CSS slot class definitions providing a baseline for customization.
Icons
Custom Icon Collection
The layer registers a custom Iconify collection named ontopix via icon.customCollections in nuxt.config.ts. This makes brand SVGs available as standard icons throughout any consuming Nuxt app.
| Icon Name | Usage | Description |
|---|---|---|
i-ontopix-spinner | Loading indicators | Ontopix target ring — animated for loading states |
i-ontopix-logo | Brand mark | Ontopix logo (target + arrow) |
These icons use currentColor fill, so they inherit the parent element's text color like any other Iconify icon.
Icon Overrides
The theme overrides Nuxt UI's default icon set. Icons using the i-ontopix-* prefix come from the custom collection above.
| Key | Icon |
|---|---|
arrowDown | i-lucide-arrow-down |
arrowLeft | i-lucide-arrow-left |
arrowRight | i-lucide-arrow-right |
arrowUp | i-lucide-arrow-up |
caution | i-lucide-circle-alert |
check | i-lucide-check |
chevronDoubleLeft | i-lucide-chevrons-left |
chevronDoubleRight | i-lucide-chevrons-right |
chevronDown | i-lucide-chevron-down |
chevronLeft | i-lucide-chevron-left |
chevronRight | i-lucide-chevron-right |
chevronUp | i-lucide-chevron-up |
close | i-lucide-x |
copy | i-lucide-copy |
copyCheck | i-lucide-copy-check |
dark | i-lucide-moon |
drag | i-lucide-grip-vertical |
ellipsis | i-lucide-ellipsis |
error | i-lucide-circle-x |
external | i-lucide-arrow-up-right |
eye | i-lucide-eye |
eyeOff | i-lucide-eye-off |
file | i-lucide-file |
folder | i-lucide-folder |
folderOpen | i-lucide-folder-open |
hash | i-lucide-hash |
info | i-lucide-info |
light | i-lucide-sun |
loading | i-ontopix-spinner |
menu | i-lucide-menu |
minus | i-lucide-minus |
ontopix | i-ontopix-logo |
panelClose | i-lucide-panel-left-close |
panelOpen | i-lucide-panel-left-open |
plus | i-lucide-plus |
reload | i-lucide-rotate-ccw |
search | i-lucide-search |
stop | i-lucide-square |
success | i-lucide-circle-check |
system | i-lucide-monitor |
tip | i-lucide-lightbulb |
upload | i-lucide-upload |
warning | i-lucide-triangle-alert |
Color Modes
Color mode overrides are rendered as CSS custom properties in :root (light) and .dark scopes.
Semantic Colors
| Color | Light Shade | Dark Shade |
|---|---|---|
brand | 600 | 400 |
error | 600 | 400 |
info | 600 | 400 |
navigation | 600 | 400 |
neutral | 600 | 400 |
paper | 400 | 400 |
phase-active | 600 | 400 |
phase-archived | 500 | 500 |
phase-done | 600 | 400 |
phase-expired | 600 | 400 |
phase-failed | 600 | 400 |
phase-idle | 600 | 400 |
phase-queued | 600 | 400 |
phase-retry | 600 | 400 |
polarity-mixed | 600 | 400 |
polarity-negative | 600 | 400 |
polarity-neutral | 500 | 400 |
polarity-positive | 600 | 400 |
primary | 600 | 400 |
prominent | 600 | 400 |
quality-bad | 600 | 400 |
quality-excellent | 600 | 400 |
quality-good | 600 | 400 |
quality-insufficient | 600 | 400 |
quality-none | 500 | 500 |
quality-perfect | 600 | 400 |
quality-regular | 600 | 400 |
secondary | 600 | 400 |
space | 800 | 600 |
success | 600 | 400 |
warning | 600 | 400 |
UI Tokens
| Token | Light | Dark |
|---|---|---|
--ui-bg | paper-100 | space-900 |
--ui-bg-accented | paper-400 | space-600 |
--ui-bg-aside | paper-200 | space-950 |
--ui-bg-elevated | paper-300 | space-700 |
--ui-bg-inverted | paper-900 | space-100 |
--ui-bg-muted | paper-200 | space-800 |
--ui-border | paper-300 | space-700 |
--ui-border-accented | paper-400 | space-600 |
--ui-border-inverted | paper-800 | space-200 |
--ui-border-muted | paper-300 | space-700 |
--ui-text | paper-800 | space-200 |
--ui-text-dimmed | paper-400 | space-600 |
--ui-text-highlighted | paper-950 | space-50 |
--ui-text-inverted | paper-100 | space-900 |
--ui-text-muted | paper-500 | space-500 |
--ui-text-toned | paper-600 | space-400 |
Global Tokens
| Token | Light | Dark |
|---|---|---|
--ui-radius |
Component Showroom
Browse the Ontopix theme applied to Nuxt UI components across different categories: