Theming and layout

Build-time branding

Consumer SCSS imports the public Sass entry once:

@use '@agon/atrium/theme' with (
  $brand-primary: #4ea6bb,
  $sidebar-width: 284px,
  $rail-width: 78px,
  $content-width: 1440px,
  $surface-radius: 14px
);

Other public defaults are in the installed package’s styles/_settings.scss (maintained at src/atrium/styles/_settings.scss): font family, dark/light surfaces, sidebar/background colors, and semantic status colors. Configure variables with @use … with, not by editing a generated CSS file. The package uses Bootstrap 5.3.8’s Sass entry, then explicit cascade layers: bootstrap, tokens, components, utilities.

Build-time appearance and settings panel

Use the dedicated appearance build configuration guide to set default colors, layout, language, and time zone, remove the customizer, choose preference persistence, and produce separate deployment profiles. Sass branding remains independent of these settings.

Brand logo

The default Agon Partners Innovation logo uses a square 0 0 64 64 viewBox with its original teal and white colors. The shared brand-logo.html partial fills the existing 40 × 40 CSS-pixel sidebar mark, including the collapsed rail and mobile drawer. Showcase authentication pages use a 48 × 48 mark. Its aspect ratio remains square in both color modes and RTL layouts.

The brand link takes its accessible name from brand.name, while the SVG is decorative. For application-specific branding, provide your own mark in your application-owned shell/authentication templates and update public/favicon.svg, regenerate the 16-, 32-, and 48-pixel variants in public/favicon.ico, and change both favicon URL revisions in index.html. Preserve the SVG viewBox and scale both display dimensions together.

Runtime tokens

Semantic CSS variables include --brand-primary-rgb, --accent-rgb, --accent, --accent-contrast, --accent-hover-contrast, --accent-text, --bg, --sidebar-bg, --surface, --surface-raised, --surface-inset, --surface-hover, --text, --muted, --subtle, --border, --radius, and semantic status text colors. Bootstrap body/card/button variables are mapped to these values.

Dark/light colors are selected by data-bs-theme on <html>. The OS preference is followed when the user selects system mode. Palette changes use data-palette. Brand (brand) follows the consumer’s $brand-primary, including its first swatch and color inputs. The default is the logo’s teal, #4ea6bb. Blue, violet, and green remain runtime presets. The compiled --brand-primary-rgb token supplies comma-separated sRGB channels. Presets override --accent-rgb, and --accent resolves those channels to a CSS color. Status colors stay semantically distinct from the brand accent.

The customizer also offers a native color selector and a hex field. Hex values accept three or six digits, with or without #, and normalize to lowercase six-digit values. Selecting a native color applies it immediately. Commit the hex field with Enter or by leaving the field. Invalid input shows a localized message and leaves the applied color and saved preference unchanged. A valid custom color selects the custom palette and persists across reloads. Primary buttons choose contrasting black or white text, including hover states. Custom accent text is adjusted for light and dark surfaces.

Appearance preferences are scoped to the application’s namespace. A saved preset or custom color takes precedence over later Sass changes. Select Brand to return to the current compiled brand color. Reset to defaults restores the configured build palette and custom accent. With the supplied defaults, this selects Brand and clears the custom accent. The former orange preference automatically falls back to the build palette. Invalid stored custom colors also fall back to the configured build accent. To add another preset, update its CSS token rule, store allowlist, translated label, and customizer option.

The light theme uses darker status/identity text for readable contrast. Do not apply a bright chart accent directly to small text on a white background without checking its contrast.

<meta name="theme-color" content="#080a0d" /> in each application’s index.html suggests a color for supporting browser interface elements, such as mobile toolbars. It does not set page backgrounds, the primary accent, or the color picker. Browser support and presentation vary, so changing it may have no visible effect on desktop. See the MDN reference.

The supplied static value matches Atrium’s default dark background. It remains application-owned and does not automatically follow the customizer. Change it independently when branding your application. Use Sass for the default page accent and the customizer for a saved user preference.

Layout preferences

Preference	Values	Behavior
`contentWidth`	fluid, contained	Full available width or centered maximum width
`sidebarLayout`	pinned, docked, scroll	Viewport-sticky rail, inset floating rail, or document-scrolling sidebar
`headerLayout`	pinned, docked, scroll	Sticky topbar, inset floating topbar, or document-scrolling header
`collapsed`	boolean	Desktop icon rail. Mobile retains a full drawer
`density`	comfortable, compact	Card gaps, table rows, and content spacing
`direction`	ltr, rtl	Document direction and mirrored directional styles

Long component submenus scroll inside the navigation area. Sidebar branding and footer controls remain available in expanded, docked, and mobile layouts. The scroll layout continues with the document.

Pinned and docked layouts apply independently to the sidebar and header. On narrow screens, the sidebar becomes a focus-trapped drawer regardless of desktop placement. A backdrop or Escape closes it, and route changes close it automatically.

RTL build

Both applications configure postcss-rtlcss in combined mode. Direction-neutral shared rules use logical CSS properties. The processor supplies [dir] variants for Bootstrap’s physical left/right rules and directional transforms, so one CSS file supports live RTL switching. Keep this PostCSS configuration in your generated application.

RTL is a layout capability, separate from localization. English, French, German, and Italian dictionaries are complete. Add an Arabic/Hebrew dictionary and allowed locale before offering that language. Avoid hand-reversing DOM order or directional rules already handled by the compiler.

Extending components

Add product styles after the shared Sass entry, ideally in your own @layer components block. Use semantic tokens to keep light/dark modes synchronized. A new data provider belongs in the consuming app until it proves useful across projects. Move its behavior, markup, and styles into the shared package together when generalizing it.

Native component surfaces

Map chrome and local vector geometry, console toolbars, terminal colors, and video controls share Atrium tokens. Map overrides are scoped above the lazily imported, unlayered Leaflet stylesheet. Resize observers keep native maps and terminals fitted when layouts or visible panels change. Remote desktop pixels and video content retain their source appearance. Console viewports remain left-to-right inside an RTL shell, while their toolbars follow the document direction.

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