Skip to main content
The Design System Dashboard provides multiple ways to customize the appearance of your application, from global theme configuration to component-level overrides.

​
Component Theme Structure

Component themes are organized using a slot-based system that allows granular control over styling. Each component theme is defined in app/assets/css/themes/components/.

​
Theme File Structure

Component themes use a standardized structure with slots, variants, and compound variants: 
export default {
  slots: {
    base: ['...'], // Base element classes
    label: '...', // Child element classes
  },
  variants: {
    color: { /* color options */ },
    size: { /* size options */ },
    variant: { /* style variants */ },
  },
  compoundVariants: [
    // Combinations of variants
  ],
  defaultVariants: {
    color: 'primary',
    size: 'md',
  },
}

​
Customizing Component Themes

The recommended approach is to extend component themes through app.config.ts. This allows you to override specific aspects while preserving defaults.
// app.config.ts
import * as components from '#layers/design-system/app/assets/css/themes'

export default defineAppConfig({
  ui: {
    ...components,
    
    // Override button theme
    button: {
      defaultVariants: {
        color: 'secondary',
        size: 'lg',
      },
    },
    
    // Override card theme
    card: {
      slots: {
        body: 'p-6 sm:p-8', // Increase padding
      },
    },
  },
})

​
Customizing Colors

​
Changing Semantic Colors

Update semantic color mappings in app.config.ts: 
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'brand-purple',   // Change from brand-blue
      secondary: 'brand-blue',   // Change from brand-purple
      accent: 'brand-orange',    // Change from brand-yellow
      success: 'brand-green',
      warning: 'brand-yellow',
      error: 'brand-red',
      info: 'brand-blue-sky',
      neutral: 'brand-grey',
    },
  },
})

​
Adding Custom Brand Colors

Define new brand colors in app/assets/css/settings/colors.css: 
@theme static {
  /* Your custom brand color */
  --color-brand-teal-50: #f0fdfa;
  --color-brand-teal-100: #ccfbf1;
  --color-brand-teal-200: #99f6e4;
  --color-brand-teal-300: #5eead4;
  --color-brand-teal-400: #2dd4bf;
  --color-brand-teal-500: #14b8a6;
  --color-brand-teal-600: #0d9488;
  --color-brand-teal-700: #0f766e;
  --color-brand-teal-800: #115e59;
  --color-brand-teal-900: #134e4a;
  --color-brand-teal-950: #042f2e;
}
Then register it in nuxt.config.ts: 
export default defineNuxtConfig({
  ui: {
    theme: {
      colors: [
        'primary', 
        'secondary', 
        'accent', 
        'info', 
        'success', 
        'warning', 
        'error',
        'teal', // Add your custom color
      ],
    },
  },
})

​
Available Components for Customization

The following components have theme files available for customization:
  • button - Button component with multiple variants
  • card - Card container component
  • badge - Badge and label component
  • modal - Modal dialog component
  • input - Input field component
  • dashboard-sidebar-collapse - Collapsible sidebar component
  • dashboard-panel - Dashboard panel component
  • navigation-menu - Navigation menu component

​
Example: Button Variants

The button component supports multiple variants and colors: 
variants: {
  color: {
    primary: '',
    secondary: '',
    success: '',
    info: '',
    warning: '',
    error: '',
    neutral: '',
  },
  variant: {
    solid: '',
    outline: '',
    soft: '',
    subtle: '',
    ghost: '',
    link: '',
    icon: 'p-2 rounded-full inline-flex items-center justify-center',
  },
}

​
Compound Variants

Compound variants combine multiple variant properties: 
compoundVariants: [
  {
    color: 'primary',
    variant: 'solid',
    class: 'text-inverted bg-primary hover:bg-primary/75',
  },
  {
    color: 'primary',
    variant: 'outline',
    class: 'ring ring-inset ring-primary/50 text-primary hover:bg-primary/10',
  },
]

​
Customizing Icons

Configure icon mappings in app.config.ts: 
export default defineAppConfig({
  ui: {
    icons: {
      panelOpen: 'i-heroicons:arrow-small-right-solid',
      panelClose: 'i-heroicons:arrow-small-left-solid',
      // Add more icon mappings
    },
  },
})

​
Best Practices

Always prefer app.config.ts for project-wide theme customizations. This keeps your changes centralized and easier to maintain.
When customizing component themes, spread the existing configuration to preserve defaults:
button: {
  ...components.button,
  defaultVariants: {
    ...components.button.defaultVariants,
    size: 'lg',
  },
}
Reference semantic colors (primary, secondary, etc.) instead of brand colors in components. This makes theme switching easier.
Always test your customizations in both light and dark modes to ensure proper contrast and visibility.

​
Next Steps

App Config Reference

Detailed app.config.ts configuration options

Color System

Learn about the color system and brand palette

Build docs developers (and LLMs) love

Get started for freeTalk to us