Skip to main content
ICVOSS DJANGO PACKAGE REGISTRY

Documentation

  1. The package index
  2. django-brickwork
  3. Adoption quickstart

Adoption quickstart

A short "start here" for a Django developer bringing brickwork into an app. It orients you and then routes you to the guide that actually has the detail: docs/INTEGRATION.md for wiring plumbing, or docs/ADOPTION.md for migrating an existing UI onto it. This page is deliberately thin; do not look here for the wiring steps themselves.

What brickwork is

Beautiful by default. Frontend your Django site fast, confident it delivers an excellent experience across devices. brickwork is the server-rendered Django interface foundation: brand-agnostic tokens, shells, components, Theme profiles and copyable pages you own, on Tailwind 4 (CSS-first), Alpine 3 and HTMX 2. Django is its only hard runtime dependency. It is not a Django-admin skin: it is for your hand-built interfaces across public sites, product applications, data-heavy operations, documentation, editorial publishing and transactional journeys. Quote shipping coverage from docs/POSITIONING.md; do not claim every interface-system archetype is done.

Mechanism: pin the foundation; own the pages; Theme with --bw-* (L1 to L4). Rebranding is token-first: every visual value is a --bw-* custom property, so you rebrand by overriding tokens, never by touching component classes (docs/BRANDING.md).

Prerequisites

  • Django 6.0 or later. brickwork uses core {% partialdef %} template partials with no compatibility shim; there is no pre-6.0 path.
  • Python 3.12 or later.
  • Alpine 3 (plus @alpinejs/focus) and, if you want the interaction contracts, htmx 2.0 or later, both provided by your own frontend build. brickwork registers against your Alpine instance; it never calls Alpine.start() itself.

Install

From public PyPI:

uv add django-brickwork             # or: pip install django-brickwork

INSTALLED_APPS = [
    "brickwork",
    "brickwork.marketing",  # optional: public-site shell, see below
    # ...
]

The marketing surface is a second, opt-in app: add brickwork.marketing alongside brickwork, never in place of it. Its templates live under their own brickwork_marketing/ namespace, so the marketing shell is brickwork_marketing/shell/marketing.html, not brickwork/shell/marketing.html (that path does not exist). This is deliberate: a consumer who never adds it gets output byte-identical to a bare brickwork install, and the separate namespace means the two apps version independently and neither shadows the other.

The optional [htmx] extra (django-htmx>=1.28) is not required: brickwork inlines the HX-Request header check itself and only uses the richer request.htmx surface when you already run django-htmx. Add the extra only if you want that.

The fastest path: emit a starter project

Once brickwork is installed, the fastest way to a running starter site is manage.py startsite, not the manual wiring below:

django-admin startproject mysite .   # or use an existing project
python manage.py startsite myproject
cd myproject
python manage.py runserver

That emits a small, complete project: settings wired for brickwork and brickwork.marketing, a brand token file with the seven load-bearing tokens plus a contrast-verified --bw-color-fg-on-accent, a validated nav config, and three real pages (a marketing landing page, an app dashboard, a docs home) each with the view that supplies its context. Open http://127.0.0.1:8000/ to inspect the populated pages, then adapt their content and composition to your product. The emitted pages are starting examples, not visual acceptance of the site you build.

The emitted project is yours outright from the moment it is written. There is no update command and nothing here reaches back into it later (ADR-095): it is the same one-time copy the example pages already are (ADR-056), automated. Edit anything in it, starting with static/pages/brand.css. The rest of this page, and INTEGRATION.md, cover the same seams by hand for a project that already has its own settings and routing to wire brickwork into, rather than starting from nothing.

A first taste of re-skinning (L1 Recolour)

Seven load-bearing colour tokens start an L1 Brickwork Theme (THEME.md): base-theme derives the hover shades, subtle tints, muted foregrounds, status tiers and component roles from these values, live in the browser, with no rebuild. That is recolour, not a full brand; add fonts (L2), material axes (L3), and rhythm (L4) when you need them.

/* your brand.css, loaded after brickwork's tokens.css */
:root {
  --bw-color-surface: oklch(0.99 0.003 90);
  --bw-color-fg:      oklch(0.24 0.02 270);
  --bw-color-border:  oklch(0.90 0.008 270);
  --bw-color-accent:  oklch(0.55 0.20 265);
  --bw-color-danger:  oklch(0.55 0.19 25);
  --bw-color-success: oklch(0.56 0.14 150);
  --bw-color-warning: oklch(0.68 0.15 75);
}
[data-theme="dark"] {
  --bw-color-surface: oklch(0.22 0.015 270);
  --bw-color-fg:      oklch(0.93 0.01 90);
  --bw-color-border:  oklch(0.34 0.015 270);
  --bw-color-accent:  oklch(0.68 0.17 265);
  --bw-color-danger:  oklch(0.65 0.18 25);
  --bw-color-success: oklch(0.66 0.13 150);
  --bw-color-warning: oklch(0.72 0.14 80);
}

Load order is load-bearing and fails silently: your brand stylesheet must load after brickwork's, or your overrides lose the cascade.

These seven are the L1 load-bearing minimum, not the whole theme story. --bw-color-fg-on-accent is authored per theme, never derived, and must be verified at 4.5:1 against its own accent: white is not a safe default, the safe value flips with the accent's lightness, and a dark theme with a light accent is the common case that inverts the intuition. --bw-color-surface-inverse is conditional too, needed only when your ink is not the inverse surface. See BRANDING.md's fg-on-accent section for the worked failure.

Where to go next

  • Starting from nothing: run manage.py startsite, above. It is the fastest path to a running starter project and is where a new consumer should start.
  • Building a new screen, or a project with no existing UI kit to displace: go straight to docs/INTEGRATION.md. It is the seam-by-seam cookbook: settings and static, the nav config, the context processor, a worked HTMX form (the 422 loop and the success redirect), and the chrome/body boundary for pages with app-owned JavaScript.
  • Migrating an existing app off a hand-built shell or component kit: go to docs/ADOPTION.md. It is the strangle guide: moving cluster by cluster, keeping the old kit alive alongside brickwork until the last screen moves, with the wrinkles a real cutover hits (multi-host projects, asset-pipeline coexistence, a second component framework in the content block).
  • Copyable pages to start from: the src/brickwork/examples/ tree ships 50 examples (22 pages, 28 sections), plus a separate document skeleton. They compose shipped tokens and components; the date range picker also supplies its own scoped token-based CSS. See Example pages in the README for how to use one.
  • Token reference: docs/DESIGN.md is the authoritative list of every --bw-* token, its default, and its derivation rule.
  • Brickwork Theme: docs/THEME.md defines L1 to L4 profiles on --bw-*. A portable brand documentation pack: docs/brand-pack.md binds measured identity prose to a --bw-* override delta, PROFILE level, and a preview path; copy the fictional northline skeleton to start.
  • Own Vite + Tailwind layout utilities: INTEGRATION.md §1.3 and examples/vite-tailwind/; sync the projection with manage.py sync_brickwork_projection instead of copying from site-packages.
  • Re-skinning the whole site: docs/BRANDING.md takes the seven tokens above further: dark mode, the four theme axes, and dynamic per-tenant or per-user theming.
  • Visual quality bar (maintainers): docs/VISUAL-BAR.md stamps the Tailwind UI kit panel and scorecard brickwork must meet; it is not a consumer wiring guide.

Accessibility

Accessibility is tested, not asserted by design: CI blocks every push on an axe-core WCAG 2.2 AA scan across 178 documents (132 hand-maintained fixtures plus 46 catalogue documents, being 22 archetypes and 1 skeleton, each x light and dark themes), plus a no-JS floor suite, keyboard suites, mobile-overflow checks, and pixel-level composited contrast measurement. See README.md for detail, including why the automated gate has a known ceiling and what closes the gap.

Documentation