How the admin panel re-skins and re-shapes itself. Governed by
docs/specs/theming.md; this file is the working reference.
Semantic design tokens only. No raw Tailwind palette classes
(bg-white, text-blue-600), no color literals (hex/rgb/oklch) in
className or styles, and no physical direction utilities (ml-, pl-,
left-, text-left, rounded-l*, border-l*) — use logical ones (ms-,
ps-, start-, text-start, rounded-s*, border-s*). Enforced by bun run lint:theme
(part of bun run lint / bun run test:lint, so it runs in every
composer test gate)
over resources/js/{layouts,components,pages,hooks} and every
app-modules/*/resources/js (color rules also cover resources/js/lib and
the app.tsx/ssr.tsx entry points; the vendored shadcn components in
resources/js/components/ui are covered too). Structural sizes come from tokens too:
--header-height and --content-max-width (boxed layout). A genuinely-directional exception is silenced
with // theme-lint-allow-next-line <rule> on the line above.
Defined in resources/css/app.css (Tailwind v4 @theme + CSS variables on
:root / .dark), following the shadcn/ui convention:
- Color roles:
background,foreground,card(-foreground),popover(-foreground),primary(-foreground),secondary(-foreground),muted(-foreground),accent(-foreground),destructive(-foreground),success(-foreground),overlay,border,input,ring,chart-1…chart-5, and thesidebar-*set. - Structural tokens: radius, fonts, row density and the shell's dimensions. The full list, with what each one drives, is the README's "Styling and layout" table.
Charts consume var(--chart-*) (grid/axes via border/muted-foreground);
lucide icons inherit currentColor. If a needed role has no token, add a
token to the contract — never inline a color. New tokens (and new layout
options) are shell-level API changes and are reviewed like one.
- Appearance:
light/dark/systemper user. Dark mode is the.darkclass on<html>(class strategy — same mechanism as presets, not a second system). - Presets ship as pure token-override blocks in
resources/css/themes/(ember.css,contrast.css), scoped to:root[data-theme='<name>']with a.darkcompanion block. Each keeps WCAG AA onforeground/backgroundandprimary-foreground/primary. Adding a preset: the step-by-step recipe is in the README's "Styling and layout" section. - Persistence: cookies (
appearance,theme,layout; js-readable, unencrypted) for guests and first paint; mirrored tousers.appearance/users.theme/users.layoutwhen authenticated viaPATCH settings/preferences.HandleAppearancestamps<html>server-side (class,data-theme,dir) so there is no flash of the wrong theme, andHandleInertiaRequestsshares the resolved values as props.
App\Modules\Data\LayoutConfigData (generated to TS, shared as the layout
prop) — enumerated options only, no free-form layout:
| Option | Values |
|---|---|
nav_placement |
sidebar-left · sidebar-right · topbar |
sidebar_variant |
sidebar · floating · inset |
sidebar_collapsible |
offcanvas · icon · none |
content_width |
fluid · boxed |
header |
sticky · static |
direction |
ltr · rtl (unset, it follows the locale: Arabic is rtl) |
AdminLayout is the single interpreter of this config (sidebar variants
via the shadcn Sidebar primitive, whose side is logical: sidebar-left is
the reading start, so the right in rtl; the topbar variant composed from
shadcn primitives; Radix DirectionProvider wired from direction). No
page, component, or module may branch on layout config — modules render
into the content region and are layout-agnostic.
useThemePreference() (resources/js/hooks/use-appearance.tsx) exposes
appearance, theme, layout and their setters; setters stamp the root
element immediately, write cookies, and persist server-side when
authenticated. Toggles live in the shell header (ThemeSettingsMenu) and
the command palette (appearance, preset, nav placement, sidebar collapse).
Modules consume tokens; they never define colors/fonts/radii/shadows, override root tokens, inject global CSS, read layout config, or position themselves relative to the shell. The theme-lint gate covers module frontend code with the same rules.
Database-driven white-label theming will inject token values as an inline CSS-variable block overriding the active preset (spatie/laravel-settings). Keep presets as pure token-value blocks and never couple a component to a preset name so this stays a drop-in.
Everything brand-specific is tagged @branding; rg -n "@branding" lists it.
To make Atrium yours:
| What | Where |
|---|---|
| Product name (sidebar, tab title, auth and error pages, mail) | APP_NAME in .env — no code change |
| Logo mark | resources/js/components/app-logo-icon.tsx (keep currentColor) |
| Favicons | public/favicon.svg, public/favicon.ico, public/apple-touch-icon.png |
| Colours and fonts | Tokens in resources/css/app.css (or a preset in resources/css/themes/); web fonts in resources/views/app.blade.php, whose first-paint background must match --background |
| Auth pages pitch and artwork | resources/js/layouts/auth-layout.tsx (tagline, highlights) and resources/js/components/auth/atrium-hall-art.tsx |
| Error pages (403, 404, 429, 500, 503) | resources/js/pages/error.tsx (copy); rendered by AppServiceProvider::renderErrorPage() |
| Emails | Already branded: the logo from Settings → General (or APP_NAME), the support address in the footer, light and dark. resources/views/vendor/mail/html/{layout,header,message}.blade.php and text/message.blade.php override Laravel's; everything else falls back to its defaults. Colours: the dark-mode block in layout.blade.php, mirroring your dark tokens (mail apps need hex) |
Brand copy lives in lang/<locale>.json like every other string, so it is
translated the same way.