Theming

djust ships with a three-registry theming system that separates colors, design language, and the cohesive bundles of both. 70+ packs are available out of the box — Dracula, Catppuccin, Nord, Tokyo Night, Vercel, Bauhaus, the djust.org and docs.djust.org house themes — and any of them can be active at runtime per request, persisted in the user's session.

This section is a tour of the system. Each page is self-contained:

Settings — LIVEVIEW_CONFIG['theme'], every key with defaults and examples.
Tokens — every CSS variable djust emits and what each one paints.
CSS Frameworks — the FrameworkAdapter abstraction, the four shipped adapters (Bootstrap 4 / 5, Tailwind, plain), the class-name registry, and the Bootstrap bridge that maps theme tokens onto .btn-primary / .form-control.
Tailwind — composing brand aliases inside @theme so utility classes resolve through djust's runtime tokens.
Authoring a pack — the minimum viable preset + design system + pack, with registration.
extra_css_vars — project-specific knobs the standard token set doesn't model.
Runtime switching — the {% theme_panel %} widget, programmatic API, session persistence, cookie scoping for shared domains.
Structure vs. style — what does NOT belong in a theme pack (and the failure mode if you put it there).
Recipes — single-page override, page-level theme, brand-color swap without authoring a pack.
Troubleshooting — color leaks, "why is my page unstyled when I switch packs," and the debug checklist.

The three registries

ThemePreset      ─►  colors only (light + dark mode tokens)
DesignSystem     ─►  typography, layout, surfaces, icons, animation,
                     interaction — everything except colors
ThemePack        ─►  the cohesive bundle: a preset + a design system +
                     pattern/illustration choices

You can mix and match: a dracula preset paired with the editorial design system gives you "Dracula at a magazine layout." The shipped packs combine the two into named products (e.g. pack='docs' is the docs.djust.org house theme — a warm editorial dark preset paired with a minimal-borders design system that favors Geist headings + JetBrains Mono labels).

What's in the box

70+ theme packs in djust.theming.themes covering professional, playful, minimal, bold, elegant, and retro categories.
Light + dark mode for every shipped pack. The active mode is user-controllable and persists in the session.
A shadcn-style token vocabulary with djust extensions for success, warning, info, link, code, selection, brand, and three numbered surface_N levels for landing-page layering. Every token is an HSL triplet, so hsl(var(--primary) / 0.5) works for opacity.
A theme panel ({% theme_panel %}) — gear-icon dropdown with mode toggle and pack picker, ready to drop into any layout.
A dev-panel Theming tab that lists every registered pack, shows the active token table, and lets you swap packs at runtime for visual regression testing.

When to use which lever

Situation	Reach for
"I want to use a different shipped pack."	Settings
"I want my brand color across all pages without authoring a full pack."	Recipes — brand override
"I want to ship my own pack to npm-style users."	Authoring a pack
"I have project-specific named knobs that no shipped pack would model."	`extra_css_vars`
"I want users to switch packs and modes at runtime."	Runtime switching
"My layout breaks when I switch packs."	Troubleshooting and Structure vs. style

Theming

The three registries

What's in the box

When to use which lever

See also