---
title: "Theming"
slug: theming-overview
section: theming
order: 0
level: beginner
description: "How djust's theming system fits together: the three-registry model (preset / design system / pack), the shadcn-style token vocabulary, and what to reach for first."
---

# 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](/theming/settings/)** — `LIVEVIEW_CONFIG['theme']`, every key
  with defaults and examples.
- **[Tokens](/theming/tokens/)** — every CSS variable djust emits and what
  each one paints.
- **[CSS Frameworks](/theming/css-framework/)** — 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](/theming/tailwind/)** — composing brand aliases inside
  `@theme` so utility classes resolve through djust's runtime tokens.
- **[Authoring a pack](/theming/authoring-a-pack/)** — the minimum viable
  preset + design system + pack, with registration.
- **[`extra_css_vars`](/theming/extra-css-vars/)** — project-specific knobs
  the standard token set doesn't model.
- **[Runtime switching](/theming/runtime-switching/)** — the
  `{% theme_panel %}` widget, programmatic API, session persistence,
  cookie scoping for shared domains.
- **[Structure vs. style](/theming/structure-vs-style/)** — what does NOT
  belong in a theme pack (and the failure mode if you put it there).
- **[Recipes](/theming/recipes/)** — single-page override, page-level
  theme, brand-color swap without authoring a pack.
- **[Troubleshooting](/theming/troubleshooting/)** — color leaks, "why is
  my page unstyled when I switch packs," and the debug checklist.

## The three registries

```text
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](/theming/settings/) |
| "I want my brand color across all pages without authoring a full pack." | [Recipes — brand override](/theming/recipes/) |
| "I want to ship my own pack to npm-style users." | [Authoring a pack](/theming/authoring-a-pack/) |
| "I have project-specific named knobs that no shipped pack would model." | [`extra_css_vars`](/theming/extra-css-vars/) |
| "I want users to switch packs and modes at runtime." | [Runtime switching](/theming/runtime-switching/) |
| "My layout breaks when I switch packs." | [Troubleshooting](/theming/troubleshooting/) and [Structure vs. style](/theming/structure-vs-style/) |

## See also

- **[Components](/components/)** — components inherit theme tokens
  automatically; nothing extra to wire.
- **[CSS Frameworks (setup guide)](/guides/css-frameworks/)** — Tailwind /
  Bootstrap installation, build pipelines, and CI integration. The
  [Theming · CSS Frameworks](/theming/css-framework/) page above covers
  the framework *abstraction* (which adapter renders what).
- **[Hot View Replacement](/guides/hot-view-replacement/)** — token changes
  hot-reload in dev.
- **Source**: [`djust.theming`](https://github.com/djust-org/djust/tree/main/python/djust/theming)
  — registry, manager, generators, and the 70+ shipped packs.