Installation & Customization

Installation

The theme is part of the @ontopix/nuxt-layer-ui package, published to AWS CodeArtifact.

1. Install the package

pnpm add @ontopix/nuxt-layer-ui

2. Add as a Nuxt layer

export default defineNuxtConfig({
  extends: ['@ontopix/nuxt-layer-ui']
})

3. Import the CSS

@import "tailwindcss";
@import "@nuxt/ui";

The layer automatically provides:

• nuxt.config.ts with global ui.theme configuration (colors, defaultVariants)
• app.config.ts with per-component slots and defaultVariants
• ontopix.css with color mode CSS variable overrides

What gets merged

Nuxt layers merge configuration bottom-up. The @ontopix/nuxt-layer-ui layer sets the baseline, and your application's own config files take precedence:

@ontopix/nuxt-layer-ui/nuxt.config.ts    ← layer baseline
  + your-app/nuxt.config.ts              ← your overrides win

@ontopix/nuxt-layer-ui/app.config.ts     ← layer baseline
  + your-app/app.config.ts               ← your overrides win (deep merge)

Customizing in Your App

Override global defaults

In your app's nuxt.config.ts, override the global color and size baseline:

export default defineNuxtConfig({
  extends: ['@ontopix/nuxt-layer-ui'],
  ui: {
    theme: {
      defaultVariants: {
        color: 'neutral',  // All components default to neutral
        size: 'sm'         // All components default to small
      }
    }
  }
})

Override per-component defaults

In your app's app.config.ts, override any component's slots or defaultVariants:

export default defineAppConfig({
  ui: {
    button: {
      defaultVariants: {
        variant: 'outline'  // Override just this variant
      }
    },
    card: {
      slots: {
        root: 'rounded-xl shadow-lg'  // Override slot classes
      }
    }
  }
})

Nuxt UI deep-merges app.config.ts, so you only need to specify the properties you want to change.

Override color modes

Add CSS custom properties in your app's stylesheet to override color mode tokens:

@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-primary: var(--color-mycustom-500);
}

.dark {
  --ui-primary: var(--color-mycustom-400);
}

Customizing at the Source

If you maintain the stylebook, you can change the theme at the YAML source level.

Source files

Change global baseline

Edit the defaults key in brand/theme/components.yaml:

defaults:
  color: neutral    # Change from primary to neutral
  size: sm          # Change from md to sm

Change per-component defaults

Edit the component entry in brand/theme/components.yaml:

button:
  defaultVariants:
    color: primary
    variant: outline    # Change from solid to outline

Change color mode shades

Edit brand/theme/color_modes.yaml:

colors:
  primary:
    light: 600    # Darker shade in light mode
    dark: 300     # Lighter shade in dark mode

Rebuild

After editing YAML sources, rebuild to regenerate the package:

stylebook build

Architecture Reference

Three configuration layers

Component types

Most Nuxt UI components are slot-based — their theme defines named slots (root, base, content, etc.) each with Tailwind CSS classes. A few components like link and kbd are flat-base — they have a single base string instead of a slots object.

The stylebook handles both types automatically in its templates.