Customization

This page explains how to change the panel's primary color, dark mode, appearance options, fonts and corners.

Quick example

/* resources/css/acun-ui.css, at the end of the file */
@theme {
    --color-brand-600: #0f766e;
}

All brand-* shades are derived from this single value. Buttons, links, the selected menu item and focus rings change together. To see the change, npm run dev must be running, or build with npm run build.

Colors, the type scale, shadows and corners are defined in the @theme block of the panel.css file in @acunsoft/acun-ui-core. The components use Tailwind's own color names (gray, zinc, emerald…), and these values override those scales. You can change any of them with your own @theme block. Write the block after the @import '@acunsoft/acun-ui-core'; line.

A primary color picked by the user

The user picks the color with the color picker in the appearance panel (acun:brand-color-picker). You can also set a color with the layout's brand-color prop or with brand_color in the configuration:

<acun:layout.sidebar brand-color="green" …>

The preset colors are the palette's colors: default (#696bfe), green (#42d697), red (#fe696a), yellow (#f9c74f), blue (#45b8f4), gray (#8592a3) and dark (#2b2c40). Any #rrggbb value works too.

With a preset color, the primary button is drawn with that color's own button shades: background, border, hover and shadow. Because these colors are light, links, the selected menu item and the focus ring use a readable, darker shade of the same color. The same happens when a light custom color is chosen.

Color scales

The current values are in the site's Design system section, under Colors.

Dark mode

Dark mode is turned on by the dark class on the <html> tag. Components adapt to it with dark: classes; use dark: classes in your own markup too.

Layouts apply the user's preference (light, dark, system) before the first paint, so there's no white flash while the page opens. The acun:theme-toggle in the top bar and the appearance panel change the preference. The layout's theme prop provides the value stored on the server.

Appearance options

In the theme, put the props on the <acun:layout.sidebar> tag in resources/views/layouts/admin/vertical.blade.php. semi-dark, sidebar-mode and navbar-mode exist only in the vertical layout.

Default settings

Instead of writing the options on every layout, define the application's defaults once in config/acun-ui.php:

'layout' => [
    'theme' => 'system',      // light | dark | system
    'brand_color' => 'blue',  // a preset color name or #rrggbb
    'skin' => 'bordered',     // default | bordered
    'customizer' => true,     // appearance panel
],

These are defaults. The user's choice always takes precedence: the choice made in the appearance panel and stored in the browser, or a preference saved to the account that you pass to the layout as a prop. A setting left as null uses the package default. The Reset to defaults button in the appearance panel also returns to these values.

The theme already has the configuration file. If you installed without the theme, create it with php artisan vendor:publish --tag=acun-ui-config. Every key is on the Configuration page.

Settings for a single page

A single page can force its own appearance. For example, a wide editor page can collapse the menu, and a presentation page can hide the top bar:

@extends('layouts.admin.vertical')

@php(\Acun\Ui\Support\Layout::page(['sidebar_mode' => 'collapsed', 'navbar_mode' => 'static']))

@section('content')
    …
@endsection

You can make the same call in a controller or in a Livewire component's mount() method. The keys are the same as in config/acun-ui.php: theme, brand_color, skin, semi_dark, sidebar_mode, navbar_mode, customizer, theme_toggle. An unknown key throws an error.

The value set by the page takes precedence over everything else for that request. It doesn't change the user's stored preference and doesn't apply on the next page. When the user leaves such a page with wire:navigate, Acun UI reloads the page from scratch, so the user's own settings come back. You don't need to add any code to the page.

Order of precedence:

1. Layout::page()
2. The user's preference: a layout prop or the value stored in the browser
3. config/acun-ui.php
4. The package default

Fonts and corners

@theme {
    --font-sans: 'Plus Jakarta Sans', ui-sans-serif, system-ui, sans-serif;
    --font-mono: 'JetBrains Mono', ui-monospace, monospace;
    --radius-sm: 0.5rem; /* corner radius of all components */
}

The default fonts are Public Sans (text) and DM Mono (code and numbers). The CSS, JavaScript and build page explains how to load a new font.

--radius-sm is the theme's overall corner radius. The components depend on this value, so a single line switches you to a sharp or a soft look.

Changing a component

Start with the props and the class attribute: the classes you pass are merged with the component's own classes.

<acun:card class="border-2 border-brand-600">…</acun:card>

If you need to change the markup permanently, copy the component's file from the package. Put the copy in your application's resources/views/components/ui/ folder with the same name; Laravel uses the copy in the application first. For example, a copy of button.blade.php replaces the <acun:button> tag.

Warning

A copied component doesn't receive package updates and fixes. Do this only when you really need to, and after updating, compare your copy with the version in the package.

Learn more

• Layouts: layout files and saving preferences to the account.
• Configuration: every key of the config/acun-ui.php file.
• CSS, JavaScript and build: the CSS file and fonts.