• Vibrant Depth Design Language
• CSS Architecture
• Design Tokens (@theme)
  • Color Scales
  • Usage in Tailwind Classes
  • Usage as CSS Custom Properties
• Customizing Colors
  • Overriding the Primary Palette
  • Examples of Brand Color Palettes
  • Customizing Feedback Colors
• Font Customization
  • Changing Fonts
  • Loading Fonts
• Border Radius
  • Examples
• Shadows
  • Glow Effects
  • Disabling Glow Effects
• Glass Morphism
  • Usage
  • Customizing Glass
  • Disabling Glass Morphism
• Animations
  • Animation Utility Classes
  • Customizing Animation Speed
  • Disabling Animations
• Legacy Compatibility Layer
• Creating Custom Theme Presets
  • Defining a Preset
  • Using a Preset
  • Dynamic Theme Switching
• Component-Level Overrides
• Next Steps

Vibrant Depth Design Language#

Aura UI follows a design language called Vibrant Depth. It moves beyond flat design by introducing layered visual cues that create a sense of depth and hierarchy:

• Gradients -- Subtle color transitions on primary elements (buttons, badges, active states)
• Glow effects -- Soft colored shadows that make interactive elements feel elevated
• Glass morphism -- Translucent panels with backdrop blur for overlays, modals, and dropdowns
• Micro-animations -- Purposeful transitions on hover, focus, and state changes
• Layered shadows -- Multiple shadow layers that create realistic depth

These effects are implemented through Tailwind CSS 4 @theme tokens and CSS custom properties, making them fully customizable.

CSS Architecture#

Aura UI's styles are organized into several CSS files, all imported from the main entry point aura.css:

For Pro, aura-pro.css imports components/sidebar-residual.css (sidebar transitions, accordion chevrons, toast progress bars, etc.).

You only need to import the entry points in your app.css -- the internal files are loaded automatically.

Design Tokens (@theme)#

Aura UI defines its design tokens inside a Tailwind CSS 4 @theme block. These tokens are available as Tailwind utilities (e.g., bg-aura-primary-500, text-aura-surface-900) and as CSS custom properties.

Color Scales#

Colors use a numeric scale (50--950) following Tailwind conventions:

/* In aura.css — these are the defaults */
@theme {
    /* PRIMARY (Deep Blue / Indigo) */
    --color-aura-primary-50:  #eef6ff;
    --color-aura-primary-100: #dbeafe;
    --color-aura-primary-200: #bfdbfe;
    --color-aura-primary-300: #93c5fd;
    --color-aura-primary-400: #60a5fa;
    --color-aura-primary-500: #6366f1;
    --color-aura-primary-600: #4f46e5;
    --color-aura-primary-700: #4338ca;
    --color-aura-primary-800: #3730a3;
    --color-aura-primary-900: #312e81;
    --color-aura-primary-950: #1e1b4b;

    /* SECONDARY (Teal/Cyan) */
    --color-aura-secondary-50:  #ecfeff;
    --color-aura-secondary-500: #06b6d4;
    --color-aura-secondary-600: #0891b2;
    /* ... full 50-900 scale */

    /* SURFACES (Light mode — warm whites to dark grays) */
    --color-aura-surface-0:   #ffffff;
    --color-aura-surface-50:  #f8fafc;
    --color-aura-surface-100: #f1f5f9;
    --color-aura-surface-200: #e2e8f0;
    --color-aura-surface-300: #cbd5e1;
    --color-aura-surface-400: #94a3b8;
    --color-aura-surface-500: #64748b;
    --color-aura-surface-600: #475569;
    --color-aura-surface-700: #334155;
    --color-aura-surface-800: #1e293b;
    --color-aura-surface-900: #0f172a;
}

Feedback colors follow the same pattern:

Usage in Tailwind Classes#

Since these are registered via @theme, they generate Tailwind utilities automatically:

<div class="bg-aura-primary-500 text-white">Primary background</div>
<div class="bg-aura-surface-50 text-aura-surface-900">Card surface</div>
<div class="border-aura-surface-200">Subtle border</div>

Usage as CSS Custom Properties#

You can also reference them directly in CSS:

.my-element {
    background: var(--color-aura-primary-500);
    color: var(--color-aura-surface-0);
}

Customizing Colors#

Overriding the Primary Palette#

To change the primary color to your brand, override the @theme tokens after importing aura.css:

/* resources/css/app.css */
@import 'tailwindcss';
@source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php';
@import './vendor/aura-ui/aura.css';

/* Override primary palette */
@theme {
    --color-aura-primary-50:  #eff6ff;
    --color-aura-primary-100: #dbeafe;
    --color-aura-primary-200: #bfdbfe;
    --color-aura-primary-300: #93c5fd;
    --color-aura-primary-400: #60a5fa;
    --color-aura-primary-500: #3b82f6;
    --color-aura-primary-600: #2563eb;
    --color-aura-primary-700: #1d4ed8;
    --color-aura-primary-800: #1e40af;
    --color-aura-primary-900: #1e3a8a;
    --color-aura-primary-950: #172554;
}

This changes every primary-colored component across the entire library.

Examples of Brand Color Palettes#

/* Ocean theme (Teal) */
@theme {
    --color-aura-primary-500: #14b8a6;
    --color-aura-primary-600: #0d9488;
    --color-aura-primary-700: #0f766e;
    /* ... override the full 50-950 scale for best results */
}

/* Sunset theme (Orange/Rose) */
@theme {
    --color-aura-primary-500: #f97316;
    --color-aura-primary-600: #ea580c;
    --color-aura-primary-700: #c2410c;
}

/* Forest theme (Green) */
@theme {
    --color-aura-primary-500: #22c55e;
    --color-aura-primary-600: #16a34a;
    --color-aura-primary-700: #15803d;
}

Tip: For the best visual consistency, override the full 50--950 scale. Use a tool like UI Colors to generate a complete palette from a base color.

Customizing Feedback Colors#

Override the semantic colors used by alerts, badges, and form validation:

@theme {
    --color-aura-success-500: #22c55e;
    --color-aura-success-600: #16a34a;
    --color-aura-warning-500: #eab308;
    --color-aura-warning-600: #ca8a04;
    --color-aura-danger-500: #e11d48;
    --color-aura-danger-600: #be123c;
    --color-aura-info-500: #3b82f6;
    --color-aura-info-600: #2563eb;
}

Font Customization#

Aura UI defines two font families as @theme tokens:

Changing Fonts#

Override the font tokens in your @theme block:

@theme {
    --font-aura-sans: 'Plus Jakarta Sans', ui-sans-serif, system-ui, sans-serif;
    --font-aura-mono: 'Fira Code', ui-monospace, monospace;
}

Loading Fonts#

Include font files via a CDN in your layout:

<link rel="preconnect" href="https://fonts.bunny.net">
<link href="https://fonts.bunny.net/css?family=inter:400,500,600,700|jetbrains-mono:400,500" rel="stylesheet" />

Or self-host them for better performance:

/* resources/css/fonts.css */
@font-face {
    font-family: 'Inter';
    src: url('/fonts/inter-variable.woff2') format('woff2');
    font-weight: 100 900;
    font-display: swap;
}

@font-face {
    font-family: 'JetBrains Mono';
    src: url('/fonts/jetbrains-mono-variable.woff2') format('woff2');
    font-weight: 100 800;
    font-display: swap;
}

Border Radius#

Aura UI uses namespaced border radius tokens. Override them to change the feel of all components:

@theme {
    --radius-aura-xs:   4px;
    --radius-aura-sm:   6px;
    --radius-aura-md:   8px;
    --radius-aura-lg:   12px;
    --radius-aura-xl:   16px;
    --radius-aura-2xl:  24px;
    --radius-aura-full: 9999px;
}

Examples#

/* Sharp / minimal design */
@theme {
    --radius-aura-xs:   0px;
    --radius-aura-sm:   2px;
    --radius-aura-md:   4px;
    --radius-aura-lg:   6px;
    --radius-aura-xl:   8px;
    --radius-aura-2xl:  12px;
}

/* Soft / pill design */
@theme {
    --radius-aura-xs:   8px;
    --radius-aura-sm:   10px;
    --radius-aura-md:   14px;
    --radius-aura-lg:   20px;
    --radius-aura-xl:   28px;
    --radius-aura-2xl:  9999px;
}

Shadows#

Aura UI uses layered shadows with namespaced tokens to create the Vibrant Depth effect:

@theme {
    --shadow-aura-xs:  0 1px 2px rgba(0, 0, 0, 0.04);
    --shadow-aura-sm:  0 1px 2px rgba(0, 0, 0, 0.06), 0 1px 3px rgba(0, 0, 0, 0.1);
    --shadow-aura-md:  0 4px 6px rgba(0, 0, 0, 0.04), 0 2px 4px rgba(0, 0, 0, 0.06), 0 0 0 1px rgba(0, 0, 0, 0.02);
    --shadow-aura-lg:  0 10px 15px rgba(0, 0, 0, 0.08), 0 4px 6px rgba(0, 0, 0, 0.04), 0 0 0 1px rgba(0, 0, 0, 0.02);
    --shadow-aura-xl:  0 20px 25px rgba(0, 0, 0, 0.1), 0 8px 10px rgba(0, 0, 0, 0.04);
    --shadow-aura-2xl: 0 25px 50px rgba(0, 0, 0, 0.15);
}

Glow Effects#

The glow effect on interactive elements is controlled via the compatibility layer in variables-compat.css. The glow intensity and per-color glow shadows are defined as CSS custom properties:

:root {
    /* Global glow intensity (0 to 1) */
    --aura-glow-intensity: 0.15;

    /* Per-color glow shadows */
    --aura-glow-primary: 0 0 0 3px rgba(99, 102, 241, var(--aura-glow-intensity)),
                         0 0 15px rgba(99, 102, 241, calc(var(--aura-glow-intensity) * 0.5));
    --aura-glow-success: 0 0 0 3px rgba(16, 185, 129, var(--aura-glow-intensity)),
                         0 0 15px rgba(16, 185, 129, calc(var(--aura-glow-intensity) * 0.5));
    /* ... same pattern for danger, warning, info, secondary */
}

To make glows stronger or subtler, override --aura-glow-intensity:

:root {
    /* Stronger glow */
    --aura-glow-intensity: 0.3;

    /* No glow */
    --aura-glow-intensity: 0;
}

In dark mode, glow intensity is automatically increased to 0.25 for better visibility.

Disabling Glow Effects#

:root {
    --aura-glow-intensity: 0;
}
.dark {
    --aura-glow-intensity: 0;
}

Glass Morphism#

Glass morphism effects are provided as @utility classes that you can apply to any element. They are defined in base/glass.css:

All glass utilities automatically adapt in dark mode (switching to dark backgrounds with low-opacity white borders).

Usage#

<div class="aura-glass rounded-lg p-6">
    Frosted glass panel
</div>

<div class="aura-glass-subtle">
    Lighter glass effect
</div>

Customizing Glass#

Since glass effects are defined as @utility rules with hardcoded values, customize them by overriding the utility in your app.css:

/* After importing aura.css */
@utility aura-glass {
    background: rgba(255, 255, 255, 0.6);
    backdrop-filter: blur(16px) saturate(1.8);
    -webkit-backdrop-filter: blur(16px) saturate(1.8);
    border: 1px solid rgba(255, 255, 255, 0.3);
}

Disabling Glass Morphism#

For a fully opaque design:

@utility aura-glass {
    background: white;
    backdrop-filter: none;
    -webkit-backdrop-filter: none;
    border: 1px solid var(--color-aura-surface-200);
}
.dark .aura-glass {
    background: var(--color-aura-surface-0);
    border-color: rgba(255, 255, 255, 0.08);
}

Animations#

Aura UI components include micro-animations for hover, focus, and state transitions. Animation durations are controlled via @theme tokens:

@theme {
    --animate-duration-fast:   100ms;
    --animate-duration-normal: 150ms;
    --animate-duration-slow:   250ms;
}

Easing curves are also defined as tokens:

@theme {
    --ease-aura-out:    cubic-bezier(0.16, 1, 0.3, 1);
    --ease-aura-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
    --ease-aura-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
}

Animation Utility Classes#

Aura UI provides @utility animation classes in base/keyframes.css:

Customizing Animation Speed#

@theme {
    /* Faster animations */
    --animate-duration-fast:   50ms;
    --animate-duration-normal: 100ms;
    --animate-duration-slow:   150ms;

    /* Or slower, more dramatic */
    --animate-duration-fast:   150ms;
    --animate-duration-normal: 250ms;
    --animate-duration-slow:   400ms;
}

Disabling Animations#

Aura UI respects the prefers-reduced-motion media query automatically. To disable animations globally:

@theme {
    --animate-duration-fast:   0ms;
    --animate-duration-normal: 0ms;
    --animate-duration-slow:   0ms;
}

Legacy Compatibility Layer#

The compat/variables-compat.css file maps @theme tokens to legacy --aura-* CSS custom properties. This layer exists for backward compatibility and is also used by the Pro package's sidebar and other components internally.

Key mappings include:

You can use either the @theme tokens or the legacy --aura-* variables in your custom CSS. The @theme tokens are preferred because they generate Tailwind utility classes.

Creating Custom Theme Presets#

You can create reusable theme presets as separate CSS files and swap them dynamically.

Defining a Preset#

/* resources/css/themes/corporate.css */
@theme {
    --color-aura-primary-500: #2563eb;
    --color-aura-primary-600: #1d4ed8;
    --color-aura-primary-700: #1e40af;
}

:root {
    --aura-glow-intensity: 0.08;
}

@theme {
    --animate-duration-fast:   75ms;
    --animate-duration-normal: 100ms;
    --animate-duration-slow:   200ms;
}

/* resources/css/themes/playful.css */
@theme {
    --color-aura-primary-500: #d946ef;
    --color-aura-primary-600: #c026d3;
    --color-aura-primary-700: #a21caf;
}

:root {
    --aura-glow-intensity: 0.25;
}

Using a Preset#

Import the preset after the Aura UI base styles:

/* resources/css/app.css */
@import 'tailwindcss';
@source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php';
@import './vendor/aura-ui/aura.css';
@import './themes/corporate.css';

Dynamic Theme Switching#

You can switch themes at runtime by toggling a class on the <html> element:

<html class="theme-corporate" x-data="{ theme: 'corporate' }" :class="'theme-' + theme">

.theme-corporate {
    --color-aura-primary-500: #2563eb;
    --color-aura-primary-600: #1d4ed8;
    --color-aura-primary-700: #1e40af;
}

.theme-playful {
    --color-aura-primary-500: #d946ef;
    --color-aura-primary-600: #c026d3;
    --color-aura-primary-700: #a21caf;
}

<x-aura::select label="Theme" x-model="theme">
    <x-aura::select.option value="corporate">Corporate</x-aura::select.option>
    <x-aura::select.option value="playful">Playful</x-aura::select.option>
</x-aura::select>

Note: For dynamic switching via CSS classes, use plain :root / .theme-* selectors (not @theme) because @theme values are resolved at build time.

Component-Level Overrides#

If you need to customize a specific component without affecting others, use Tailwind utility classes directly:

<!-- Override button gradient for a specific instance -->
<x-aura::button
    class="bg-gradient-to-r from-emerald-500 to-teal-600 hover:from-emerald-600 hover:to-teal-700"
>
    Custom Button
</x-aura::button>

<!-- Override card surface -->
<x-aura::card class="bg-slate-50 dark:bg-slate-800 border-slate-200 dark:border-slate-700">
    <x-aura::card.title>Custom Card</x-aura::card.title>
</x-aura::card>

For broader component-level customization, publish the individual Blade view and edit the template directly. See Configuration for details.

Next Steps#

• Dark Mode -- Set up light/dark theme switching
• Configuration -- Other configuration options
• Upgrading -- Keep Aura UI updated