App Configuration

The app.config.ts file is the central configuration point for theming in the Design System Dashboard. It integrates with Nuxt UI to provide a powerful and flexible theming system.

File Location

app/
└── app.config.ts

Basic Structure

import * as components from '#layers/design-system/app/assets/css/themes'

export default defineAppConfig({
  ui: {
    ...components,
    colors: {
      // Semantic color mappings
    },
    icons: {
      // Icon mappings
    },
  },
})

Configuration Options

Component Themes

The configuration imports all component themes from the design system layer:

import * as components from '#layers/design-system/app/assets/css/themes'

export default defineAppConfig({
  ui: {
    ...components, // Spreads all component themes
  },
})

This imports:

button - Button component theme
card - Card component theme
badge - Badge component theme
modal - Modal component theme
input - Input component theme
dashboardSidebarCollapse - Sidebar collapse theme
dashboardPanel - Dashboard panel theme
navigationMenu - Navigation menu theme

Semantic Colors

Define semantic color mappings that link to brand colors:

colors: {
  primary: 'brand-blue',
  secondary: 'brand-purple',
  accent: 'brand-yellow',
  success: 'brand-green',
  warning: 'brand-orange',
  error: 'brand-red',
  info: 'brand-blue-sky',
  neutral: 'brand-grey',
}

Semantic colors map to the brand color palettes defined in app/assets/css/settings/colors.css. Each brand color includes shades from 50 to 950.

Icon Configuration

Map semantic icon names to actual icon identifiers:

icons: {
  panelOpen: 'i-heroicons:arrow-small-right-solid',
  panelClose: 'i-heroicons:arrow-small-left-solid',
}

Complete Example

Here’s the default app.config.ts configuration:

import * as components from '#layers/design-system/app/assets/css/themes'

export default defineAppConfig({
  ui: {
    ...components,
    colors: {
      primary: 'brand-blue',
      secondary: 'brand-purple',
      accent: 'brand-yellow',
      success: 'brand-green',
      warning: 'brand-orange',
      error: 'brand-red',
      info: 'brand-blue-sky',
      neutral: 'brand-grey',
    },
    icons: {
      panelOpen: 'i-heroicons:arrow-small-right-solid',
      panelClose: 'i-heroicons:arrow-small-left-solid',
    },
  },
})

Customization Examples

Override Semantic Colors
Override Component Defaults
Extend Component Themes
Add Custom Icons

Change which brand colors map to semantic meanings:

export default defineAppConfig({
  ui: {
    ...components,
    colors: {
      primary: 'brand-purple',    // Use purple instead of blue
      secondary: 'brand-blue',    // Swap blue to secondary
      accent: 'brand-orange',     // Use orange for accent
      success: 'brand-green',
      warning: 'brand-yellow',
      error: 'brand-red',
      info: 'brand-blue-sky',
      neutral: 'brand-grey',
    },
  },
})

Customize default variants for components:

export default defineAppConfig({
  ui: {
    ...components,
    
    // Override button defaults
    button: {
      ...components.button,
      defaultVariants: {
        color: 'secondary',
        variant: 'soft',
        size: 'lg',
      },
    },
    
    // Override badge defaults
    badge: {
      ...components.badge,
      defaultVariants: {
        color: 'primary',
        variant: 'solid',
        size: 'md',
      },
    },
    
    colors: {
      primary: 'brand-blue',
      secondary: 'brand-purple',
      accent: 'brand-yellow',
      success: 'brand-green',
      warning: 'brand-orange',
      error: 'brand-red',
      info: 'brand-blue-sky',
      neutral: 'brand-grey',
    },
  },
})

Add custom slots or variants to components:

export default defineAppConfig({
  ui: {
    ...components,
    
    card: {
      ...components.card,
      slots: {
        ...components.card.slots,
        body: 'p-6 sm:p-8',        // Custom padding
        footer: 'border-t pt-4',   // Add footer slot
      },
      variants: {
        ...components.card.variants,
        elevated: {
          true: 'shadow-xl',       // Add elevated variant
        },
      },
    },
    
    modal: {
      ...components.modal,
      slots: {
        ...components.modal.slots,
        header: 'min-h-auto',
        title: 'text-2xl font-bold', // Larger title
        close: 'text-primary hover:text-primary/75',
      },
    },
    
    colors: {
      primary: 'brand-blue',
      secondary: 'brand-purple',
      accent: 'brand-yellow',
      success: 'brand-green',
      warning: 'brand-orange',
      error: 'brand-red',
      info: 'brand-blue-sky',
      neutral: 'brand-grey',
    },
  },
})

Extend the icon configuration:

export default defineAppConfig({
  ui: {
    ...components,
    icons: {
      panelOpen: 'i-heroicons:arrow-small-right-solid',
      panelClose: 'i-heroicons:arrow-small-left-solid',
      // Add custom icon mappings
      search: 'i-heroicons:magnifying-glass',
      close: 'i-heroicons:x-mark',
      check: 'i-heroicons:check',
      warning: 'i-heroicons:exclamation-triangle',
      info: 'i-heroicons:information-circle',
    },
    colors: {
      primary: 'brand-blue',
      secondary: 'brand-purple',
      accent: 'brand-yellow',
      success: 'brand-green',
      warning: 'brand-orange',
      error: 'brand-red',
      info: 'brand-blue-sky',
      neutral: 'brand-grey',
    },
  },
})

Integration with Nuxt Config

The app.config.ts works alongside nuxt.config.ts to configure the complete theme system.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  
  ui: {
    theme: {
      colors: ['primary', 'secondary', 'accent', 'info', 'success', 'warning', 'error'],
    },
  },
  
  css: ['#layers/design-system/app/assets/css/main.css'],
})

The colors array in nuxt.config.ts must include all semantic color names you define in app.config.ts for Nuxt UI to generate the necessary CSS utilities.

Using Configuration in Components

Accessing Colors

<template>
  <UButton color="primary">Primary Button</UButton>
  <UButton color="secondary">Secondary Button</UButton>
  <UBadge color="success">Success</UBadge>
</template>

Accessing Icons

<script setup>
const appConfig = useAppConfig()
</script>

<template>
  <UIcon :name="appConfig.ui.icons.panelOpen" />
  <UIcon :name="appConfig.ui.icons.panelClose" />
</template>

Accessing Component Themes

<script setup>
const appConfig = useAppConfig()
const buttonDefaults = appConfig.ui.button.defaultVariants
</script>

TypeScript Support

For TypeScript support, you can extend the app config types:

// types/app-config.d.ts
declare module '@nuxt/schema' {
  interface AppConfigInput {
    ui?: {
      colors?: {
        primary?: string
        secondary?: string
        accent?: string
        success?: string
        warning?: string
        error?: string
        info?: string
        neutral?: string
      }
      icons?: Record<string, string>
    }
  }
}

export {}

Best Practices

Import Component Themes

Always spread the component themes at the beginning of your ui configuration:

ui: {
  ...components,
  // Your customizations
}

Define Semantic Colors

Use semantic color names (primary, secondary, etc.) consistently throughout your application instead of brand color names.

Preserve Existing Configuration

When overriding component themes, spread the existing configuration to avoid losing default behavior:

button: {
  ...components.button,
  // Your overrides
}

Keep Icons Centralized

Define all icon mappings in app.config.ts to maintain consistency across your application.

The app.config.ts works with several other configuration files:

nuxt.config.ts - Nuxt UI module configuration
app/assets/css/settings/colors.css - Brand color definitions
app/assets/css/settings/variables.css - CSS custom properties
app/assets/css/themes/index.ts - Component theme exports
app/assets/css/themes/components/*.ts - Individual component themes

Get Started

Components

Theming

Guides

File Location

Basic Structure

Configuration Options

Component Themes

Semantic Colors

Icon Configuration

Complete Example

Customization Examples

Integration with Nuxt Config

nuxt.config.ts

Using Configuration in Components

Accessing Colors

Accessing Icons

Accessing Component Themes

TypeScript Support

Best Practices

Next Steps

Color System

Customization Guide

Build docs developers (and LLMs) love

Get Started

Components

Theming

Guides

​File Location

​Basic Structure

​Configuration Options

​Component Themes

​Semantic Colors

​Icon Configuration

​Complete Example

​Customization Examples

​Integration with Nuxt Config

​nuxt.config.ts

​Using Configuration in Components

​Accessing Colors

​Accessing Icons

​Accessing Component Themes

​TypeScript Support

​Best Practices

​Related Files

​Next Steps

Color System

Customization Guide

Build docs developers (and LLMs) love

File Location

Basic Structure

Configuration Options

Component Themes

Semantic Colors

Icon Configuration

Complete Example

Customization Examples

Integration with Nuxt Config

nuxt.config.ts

Using Configuration in Components

Accessing Colors

Accessing Icons

Accessing Component Themes

TypeScript Support

Best Practices

Related Files

Next Steps