Appearance build configuration

Set application defaults and settings-panel availability before building. The configuration becomes part of the generated artifact.

Configuration file

Each generated application owns appearance.config.mjs. Edit it before running yarn build, then serve that build with yarn preview. In this repository, the files are src/starter/appearance.config.mjs and src/showcase/appearance.config.mjs. The existing defaults remain unchanged until you edit the configuration.

export default {
  customizer: false,
  defaults: {
    theme: 'light',
    palette: 'custom',
    customAccent: '#4ea6bb',
    direction: 'ltr',
    contentWidth: 'contained',
    sidebarLayout: 'pinned',
    headerLayout: 'pinned',
    collapsed: false,
    density: 'comfortable',
    locale: 'fr',
    timeZone: 'Europe/Zurich'
  }
};

Disable the settings panel

customizer: false automatically ignores saved appearance preferences and prevents appearance writes to browser storage, even if persist: true is supplied. Existing saved preferences remain untouched and become available again in a later build with the customizer enabled. Each reload starts from the configured build defaults.

It removes the settings drawer, floating gear, user-menu Appearance item, and supplied page buttons from the compiled shell and lazy page templates. The header’s quick light/dark toggle and sidebar collapse button remain available. Application settings pages and domain-specific forms remain application-owned. To remove a custom launcher too, mark its enclosing element with data-atrium-customizer. The compiler removes these markers from enabled builds.

Saved preferences and reset behavior

persist: true is the default when the customizer is enabled. Valid saved preferences override the build defaults within the application’s namespace. New visitors and invalid or missing saved values use the configured defaults. Reset to defaults restores all configured values, including language and time zone. To apply new defaults to an existing browser, reset the preferences rather than expecting a rebuild to overwrite that user’s choices.

persist: false ignores saved appearance preferences and does not overwrite them. Every reload starts from the build defaults. Changes made through remaining controls last for the current page session. This optional switch also allows an enabled customizer to operate without saving choices. A disabled customizer always ignores saved appearance preferences, regardless of this switch.

Available defaults

The defaults object is partial. Omitted values use Atrium’s defaults below. Unknown settings, unsupported values, and a custom palette without a valid custom color fail the build with a configuration error.

Setting	Allowed values	Atrium default
`theme`	`dark`, `light`, `system`	`dark`
`palette`	`brand`, `custom`, `blue`, `violet`, `green`	`brand`
`customAccent`	Three- or six-digit hex, or empty when unused	Empty
`direction`	`ltr`, `rtl`	`ltr`
`contentWidth`	`fluid`, `contained`	`fluid`
`sidebarLayout`	`pinned`, `docked`, `scroll`	`pinned`
`headerLayout`	`pinned`, `docked`, `scroll`	`pinned`
`collapsed`	Boolean	`false`
`density`	`comfortable`, `compact`	`comfortable`
`locale`	`en`, `fr`, `de`, `it`	`en`
`timeZone`	Valid IANA time zone	`Europe/Zurich`

Build and runtime integration

The consumer’s Vite configuration passes this object to adminHtml({ root, routes, appearance }). Its main.js imports the validated virtual:atrium/appearance module and passes it to createAdmin({ ..., appearance }). Keep both connections when creating a manual integration. The same configuration supplies initial document attributes before JavaScript starts, including the loading screen’s light/dark mode. Saved preferences apply when the runtime initializes. There is no inline startup script.

Different deployment profiles

The supplied configuration is a plain object. Applications can select different objects using Vite’s build mode. For example, keep the default export and add this named export to the application’s appearance.config.mjs:

export const presentationAppearance = {
  customizer: false,
  persist: false,
  defaults: {
    theme: 'light',
    direction: 'ltr',
    contentWidth: 'contained',
    density: 'comfortable'
  }
};

In vite.config.mjs, import both objects:

import appearance, { presentationAppearance } from './appearance.config.mjs';

Inside the existing defineConfig(({ mode }) => ({ ... })) callback, replace the adminHtml plugin entry with:

adminHtml({
  root: fileURLToPath(new URL('.', import.meta.url)),
  routes,
  appearance: mode === 'presentation' ? presentationAppearance : appearance
})

From a generated application’s root, build and preview that profile:

yarn vite build --mode presentation
yarn preview

From this repository’s root, use the corresponding workspace command:

yarn workspace @agon/atrium-showcase exec vite build --mode presentation
yarn preview

The supplied shared build policy minifies this custom mode just like production. The development mode remains the readable diagnostic build. To retain several artifacts at once, pass separate output directories to Vite and preview the matching directory. Stop a foreground preview with Ctrl+C.

Rebuild each artifact with the intended configuration. Changing a source file or server environment after building does not change an already generated artifact. The supplied templates do not define environment-variable overrides for appearance. A consumer may implement its own mode selection in Vite without exposing deployment environment data to the browser.

Color and width ownership

Use palette: 'brand' to follow the application’s compiled $brand-primary Sass setting, or palette: 'custom' with customAccent to choose an explicit build color. Presets are available through blue, violet, and green. Semantic error and success colors remain distinct. See theming for Sass branding.

contentWidth: 'contained' selects the centered layout. Its maximum pixel width comes from the application’s $content-width Sass setting. fluid fills the available space. Sidebar and header placement, sidebar collapse, and density are independent options.

Verify a build

After changing the configuration, build and start the matching preview. Existing preview processes must serve that build’s output directory. Browser caches or saved preferences can otherwise make a correct configuration appear unchanged.

Open a fresh browser profile and verify the default color mode, accent, direction, and layout.
With persistence enabled, change a preference, reload, and confirm the saved value wins.
Use Reset to defaults and confirm all preferences return to the build configuration, including language and time zone.
With persistence disabled, change a preference and reload. Confirm the build defaults return and older saved appearance values remain untouched.
With the customizer disabled, verify previously saved appearance values have no effect and are not overwritten. Verify the floating gear, user-menu Appearance item, and page launch buttons are absent. The quick theme toggle and sidebar collapse control should still work for the current session.
Open a lazy page directly and navigate between pages to verify customizer controls remain absent there too.

The panel switch is a presentation feature. It does not enforce permissions or prevent application code from changing appearance. Consumer applications own authorization and any policy that requires a completely fixed interface.

Author

Laurent Declercq l.declercq@agon-innovation.ch

License

Unless otherwise stated all source code is licensed under LGPL 2.1 and has the following copyright:

© 2026, Agon Partners Innovation AG, All rights reserved.

The design material and the “Agon Ātrium” trademark is the property of their authors. Reuse of them without prior consent of their respective authors is strictly prohibited.

Version

Version: 20260921