Theming
Customize Neura's appearance to match your project's identity
Overview
We've meticulously designed Neura to look great out of the box, however, every project has its own identity.
You can customize the appearance through the Vite plugin configuration, CSS variables, or by publishing component views.
Semantic Colors Configuration
The easiest way to customize Neura's colors is through the
neuraKit Vite plugin. Define semantic colors by mapping them to Tailwind color names:
// vite.config.js
import neuraKit from './vendor/neura-ui/neura-kit/vite-plugin-neura-kit.js';
export default defineConfig({
plugins: [
neuraKit({
colors: {
primary: 'blue',
secondary: 'slate',
success: 'green',
warning: 'amber',
danger: 'red',
info: 'cyan',
}
}),
// ... other plugins
],
});
Available color mappings include all Tailwind colors:
red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, and gray scales (slate, gray, zinc, neutral, stone).
How it works
When you configure semantic colors, Neura generates complete color scales (50-950) in the OKLCH color space and injects them as CSS variables. This ensures perceptually uniform color gradients and excellent dark mode support across all components.
Semantic Color Usage
Once configured, semantic colors are available throughout all Neura components:
Primary callout adapts to your configured primary color.
<!-- Buttons automatically use your configured colors -->
<neura::button variant="primary">Primary</neura::button>
<neura::button variant="danger">Danger</neura::button>
<!-- Callouts, inputs, and other components also adapt -->
<neura::callout variant="success">...</neura::callout>
<neura::input /> <!-- Focus ring uses primary color -->CSS Variables
Neura uses CSS variables for theming, making it easy to customize colors, spacing, typography, and other design tokens.
You can override these variables in your
resources/css/app.css file within the @theme or :root blocks:
@theme inline {
/* Typography */
--font-sans: 'Instrument Sans', ui-sans-serif, system-ui, sans-serif;
--font-mono: ui-monospace, 'Cascadia Code', monospace;
/* Primary Colors */
--color-primary: var(--color-neutral-900);
--color-primary-fg: var(--color-white);
--color-secondary: var(--color-neutral-600);
--color-secondary-fg: var(--color-white);
--color-muted: var(--color-neutral-100);
--color-muted-fg: var(--color-neutral-600);
--color-accent: var(--color-neutral-100);
--color-accent-fg: var(--color-neutral-900);
/* Border Radius */
--radius-sm: 0.125rem;
--radius-field: 0.25rem;
--radius-md: 0.375rem;
--radius-box: 0.5rem;
--radius-lg: 0.75rem;
--radius-xl: 1rem;
--radius-2xl: 1.5rem;
--radius-full: 9999px;
/* Popup Variables */
--popup-round: 0.75rem;
--popup-padding: 1rem;
/* Spacing Scale */
--spacing-xs: 0.25rem;
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--spacing-lg: 1.5rem;
--spacing-xl: 2rem;
--spacing-2xl: 3rem;
}Publishing Component Views
To customize individual components, you can publish their Blade views into your project:
php artisan vendor:publish --tag=neura-kit-views
This will copy all Neura component views to
resources/views/vendor/neura-kit.
You can then modify these views to match your design requirements.
Customizing Colors
Neura includes a comprehensive color palette with full color scales for all standard colors. You can customize any color by overriding its variables. All colors use the OKLCH color space for better perceptual uniformity:
@theme inline {
/* Override primary colors */
--color-primary: var(--color-blue-600);
--color-primary-fg: var(--color-white);
/* Customize specific color scales */
--color-blue-50: oklch(0.978 0.014 254.604);
--color-blue-100: oklch(0.953 0.028 254.901);
--color-blue-500: oklch(0.623 0.214 259.815);
--color-blue-600: oklch(0.546 0.245 262.881);
--color-blue-900: oklch(0.370 0.149 265.028);
}
Available color scales include:
neutral, slate, zinc, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, and rose. Each scale includes shades from 50 to 950.
Dark Mode Customization
Dark mode colors are automatically adjusted, but you can customize them by targeting the
.dark class:
@layer base {
.dark {
color-scheme: dark;
/* Dark mode primary colors */
--color-primary: var(--color-white);
--color-primary-fg: var(--color-neutral-900);
--color-secondary: var(--color-neutral-400);
--color-secondary-fg: var(--color-neutral-900);
--color-muted: var(--color-neutral-900);
--color-muted-fg: var(--color-neutral-400);
--color-accent: var(--color-neutral-800);
--color-accent-fg: var(--color-neutral-100);
}
}Typography Customization
Customize fonts by overriding the typography variables:
@theme inline {
--font-sans: 'Your Sans Font', ui-sans-serif, system-ui, sans-serif;
--font-mono: 'Your Mono Font', ui-monospace, monospace;
}Spacing and Radius Customization
Adjust spacing scales and border radius values to match your design system:
@theme inline {
/* Custom spacing scale */
--spacing-xs: 0.25rem;
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--spacing-lg: 1.5rem;
--spacing-xl: 2rem;
--spacing-2xl: 3rem;
/* Custom border radius */
--radius-sm: 0.125rem;
--radius-field: 0.375rem;
--radius-box: 0.75rem;
--radius-lg: 1rem;
/* Popup customization */
--popup-round: 1rem;
--popup-padding: 1.5rem;
}Best Practices
Do
- Use CSS variables for consistent theming across components
- Override variables in the
@themeblock to leverage Tailwind's theme integration - Use OKLCH color format for better color consistency and accessibility
- Publish only the components you need to customize
- Test your customizations in both light and dark modes
- Keep your customizations organized and documented
Don't
- Don't modify Neura's core files directly
- Don't publish all components if you only need to customize a few
- Don't forget to test accessibility when changing colors
- Don't break component functionality when customizing views
- Don't remove existing color scales unless you're replacing them with your own