Theming
Compose per-client brand identity across four orthogonal Theming Dimensions — Tokens, Atmospheres, Layout, Blueprints.
Theming is how a single component library renders as a different brand for every client. BDS answers "what is this thing and how does it behave?" in components; the Theming Tenet answers "what does it look like for this brand?" Clients never change components — they change theming decisions, composed across four orthogonal Theming Dimensions.
Theming is one of four Tenets of the system: Foundation, Theming, Motion, Content. If design tokens are the atoms, theming is the instrument that plays them in a different key.
Audience: primarily websites (Astro, Webflow) and any product surface that needs per-client branding. Foundation tokens are shared across product and websites; theming is where the per-client divergence happens.
The four Theming Dimensions
| Dimension | Decides | Lives in | Override per client? |
|---|---|---|---|
| Tokens | Color, type, spacing values | theme-{client}.css (@layer client-theme) | Required |
| Atmospheres | Ambient mood — grain, glow, vignettes, surface treatments | @brikdesigns/bds/atmospheres/{slug}.css | Optional — industry default can win |
| Layout Archetypes | Site-header and site-footer shape, plus scroll + drawer behavior | <SiteHeader> and <SiteFooter> from @brikdesigns/bds/blueprints-astro | Optional — industry default can win |
| Blueprints | Section composition — how a hero / services / testimonials slot is built | Authored in BDS, tagged by mood + industry | Authored centrally; clients pick |
Dimensions are independent. A client can redefine tokens, keep the industry's default atmosphere, swap to a non-default navigation archetype, and use the same blueprints another client uses — nothing cross-couples. Each Dimension has its own deep-dive page; the sections below summarize each and link out.
"Dimension" not "Layer". Older docs called these four "Layers" — confusing because CSS @layer is also called Layer (the bds-tokens / client-theme cascade). They're distinct concepts: a Theming Dimension is a what to decide; a CSS Layer is a where the decision's CSS lands. See Token Anatomy for the full six-concept disambiguation.
Tokens Dimension
The Tokens Dimension is the brand-value override. Every consuming project loads BDS canon first (@brikdesigns/bds/tokens.css — Foundations Library + Brik Brand Kit), then the per-client theme override (theme-{client}.css) in @layer client-theme which redefines the same semantic token names with brand values. Components never change.
Full architecture, import order, and the <html> switch table: The Cascade.
What a client brand overrides
Not every token is meant to vary per brand. The rule of thumb: tokens that carry brand identity are overridable; tokens that carry functional or accessibility meaning are not.
| Token group | Per-client override? | Notes |
|---|---|---|
Brand colors (--background-brand-primary, --text-brand-primary, --surface-brand-primary, --border-brand-primary) | Required | Core brand identity. |
Interaction states (--background-brand-primary-hover, --background-brand-primary-pressed) | Required if brand colors change | Defined at :root in gap-fills.css. If you change the brand color without overriding these, hover/press keep the default Poppy tint. |
Surfaces + page (--surface-primary, --surface-secondary, --page-primary) | Recommended | Tune neutrals to the brand. |
Font families (--font-family-heading, --font-family-body, --font-family-label) | Optional | Swap to match brand voice. |
Canonical status (--background/surface/text/border-positive/negative/warning) | Yes | First-class Figma variables. Override if the brand red/green/yellow clashes with the default. |
Extended status (--background-status-info/neutral/purple/orange) | No | Gap-fills using system colors with universal semantic meaning. |
Presence (--background-presence-online/away/busy/offline) | No — intentionally frozen | Shared chat/status semantics across products. |
| Shadows + overlay | No | Hardcoded rgba() values; not expected to vary per brand. |
Full override matrix and the minimal theme-{client}.css template: Client Themes.
Multi-brand within one client (scope-based binding)
Some clients carry multiple brand colors at once — Vale Partners has three audience verticals, brikdesigns.com has service lines. Instead of inventing role-specific canonical tokens (--background-land-primary, etc.), the system re-binds the same canonical tokens inside [data-audience=X] / [data-service=X] scopes. Components stay scope-blind — they keep referencing --background-brand-primary — while the page expresses N brand colors simultaneously. Adding an audience is one CSS block; canonical never grows. Full pattern: Client Themes → Per-audience scope binding.
Atmospheres Dimension
An atmosphere is a CSS overlay that sits on top of the Tokens Dimension to establish visual character — dark-luxury-editorial, soft-wellness, clean-clinical, etc. — without duplicating CSS per client. Atmospheres decorate surfaces (grain, glow, vignettes, spotlights); tokens decide the underlying values.
Industry packs declare a default atmosphere. A client site fetches a single theme artifact at build; the atmosphere cascades automatically. Clients can override the pack default by setting company_profiles.atmosphere in the portal.
Full vocabulary, previews per atmosphere, and composition rules: Atmospheres.
Layout Archetypes Dimension
The locked sets of site-header and site-footer patterns Brik builds from — e.g. nav: editorial-transparent, sidebar-rail, glass-floating; footer: directory, cta-anchored, compliance-heavy. Each industry pack declares a default archetype for both; consumer sites render the shapes via the BDS <SiteHeader> and <SiteFooter> components at build time.
Nav and footer are sibling vocabularies — paired but independent. They are orthogonal to atmosphere and blueprint: a dental client can keep the dental pack's default nav while picking a non-default atmosphere, swap the footer archetype for compliance reasons, and pull in the same section blueprints a real-estate client uses.
Full vocabularies, scroll + drawer behavior options, and per-industry defaults: Layout Archetypes. (Footer is v0.1 — <SiteFooter> render lands in blueprints-astro v0.2.)
Blueprints Dimension
Tokens answer how does it look. Blueprints answer how is it composed. A blueprint is a named layout + interaction pattern (e.g. hero_editorial, services_clinical_grid) that constrains how a section is built — structural slots, mood tags, industry tags, CSS hints. Blueprints are the layer AI mockup generators use to ground their output: they pick blueprints by mood and industry, then apply the active theme's tokens to render.
Blueprints sit inside the Theming Tenet because they make the same kind of decision as the other three Dimensions — a structural one that varies per brand and content direction. Authoring rules, mood → personality and mood → visual style bridges, and the full coverage matrix: Blueprints.
Brik's built-in themes
BDS ships three themes. The ThemeProvider component in consumer apps manages the body class and data-theme attribute; in Storybook the paintbrush toolbar does the same.
| Theme | Body class | <html data-theme> | Purpose |
|---|---|---|---|
| Brik (light) | theme-brand-brik | light | Default brand — poppy red on white, Poppins |
| Brik Dark | theme-brand-brik | dark | Brand in dark mode — poppy red on near-black |
| Client Sim | theme-brand-brik theme-client-sim | light | QA tool — Georgia / Verdana / Courier New reveal --font-family-* token misuse before a client theme does |
The eight numbered themes (theme-1 … theme-8) moved to the brik-website-themes repo in 2026-03. They are not part of the client project architecture and should not be referenced from consuming apps.
How Content feeds Theming
Industry packs (Content tenet) carry default theming decisions — one atmosphere + one navigation archetype per pack. The portal resolver reads the pack, applies those defaults, then lets the client-specific company_profile override each layer independently:
industry pack (BCS) ──▶ atmosphere default ──▶ client override?
└──▶ navigation archetype ──▶ client override?
└──▶ blueprint affinity tags ──▶ mockup generator picksThis is why Content and Theming are peer tenets that intentionally cross-link at this one seam: the content vocabulary selects which variants of each theming layer best fit the client's industry before the client brand even ships, and the client-specific theme only adjusts what genuinely needs to change.
Validation — prove a theme before shipping
Before a client brand goes live, test it in Storybook. Three checks:
- Contrast. Run the WCAG AA pair probe across body-on-page, body-on-surface, brand-text-on-page, inverse-on-brand-fill, muted, and secondary. Client themes should be added to the probe when they ship.
- Font-family correctness. Switch to Client Sim in the toolbar. Any component using the wrong
--font-family-*token (e.g. a heading using--font-family-body) becomes immediately visible because the three families are assigned distinct typefaces. - Interaction states. Hover every primary button. If the hover state stays Poppy red after a brand change, the client theme is missing
--background-brand-primary-hover.
Explore the Theming Dimensions
Client Themes
Tokens Dimension — override matrix and minimal theme-{client}.css template.
Atmospheres
Atmospheres Dimension — CSS overlays for editorial-luxury, cinematic, warm-soft, and more.
Layout Archetypes
Layout Archetypes Dimension — site-header and site-footer patterns, scroll + drawer behavior.
Blueprints
Blueprints Dimension — section composition tagged by mood + industry.
Related
- Foundation / Primitives — the token layer the brand theme overrides
- Content System — the vocabulary tenet that selects theming defaults
- Motion — the orthogonal motion tenet (CSS reveals → GSAP → Premium effects)
Naming Conventions
The vocabulary that keeps the system tight — title vs heading, label family, action vs button-label, axes, and the no-unclassed-wrappers rule.
Client Themes
The Tokens Theming Dimension — per-client semantic token overrides. Override matrix, minimal theme-{client}.css template, and interaction-state rules.