Theming
Bullframe themes through CSS custom properties and build choice. Override --bf-* tokens
after the stylesheet; do not fork the framework or invent theme classes.
When to use
Brand colour or type, a dark or system-prefers page, a short custom.css on top of one
base build, or any task that changes appearance without new component CSS.
Inputs to gather
Brand primary colour (and a hover/focus sibling), optional font stacks, light / dark /
system preference, and whether overrides are global (:root) or scoped to a class.
Rules
- Link exactly one base build. Dark is
bullframe-dark.css; OS-follows isbullframe-system-default.css(or the classless equivalents). Do not stack two bases. - Override tokens, not selectors. Set
--bf-blue,--bf-blue-light,--bf-focus-ring-color, grays, and font stacks. Links, primary buttons and focus rings follow those tokens. - Load project CSS after Bullframe. Prefer a
<style>block or onecustom.csslink. Keep it to token overrides plus a few layout or type rules. - Scope when the brand is not site-wide: put the overrides on a class such as
.brand, not on every page. - Replaced blues must clear WCAG AA contrast (4.5:1) on the page background. The shipped blues already do; a replacement has to match that bar.
- Do not add a theme-toggle script to get dark mode. Pick a
-darkor-system-defaultbuild instead. - Leave the HTML alone when tokens suffice. Prefer element styles and utilities over
restyling
.bf-btnselectors unless a token cannot reach the property.
Recipe
- Choose the build from
bullframe-core(light, dark, or system; class-based or classless). - Emit the page scaffold.
- Add a token block on
:rootor a brand scope class. - If a few layout rules are needed, keep them in the same stylesheet and name them for
the project, not as fake
.bf-*classes. - Check contrast on primary buttons, links and body text.
Example
examples/branded.html is a class-based page with a scoped brand
class: teal primary tokens, serif headings, and no second Bullframe build.
Expected output
One HTML file that links exactly one Bullframe stylesheet, overrides only real --bf-*
tokens from api.json, and needs no JavaScript for theming.
Failure modes
- Linking
bullframe.cssandbullframe-dark.csstogether. - Inventing
.bf-theme,.bf-theme-toggleor.bf-dark-mode. - Hard-coding
#0f766eon buttons instead of setting--bf-blue. - Dropping contrast below AA when swapping the primary colour.
- A large custom stylesheet that reimplements grid, spacing or type scales.
Do not
- Do not write a theme toggle for OS dark mode; use a
-system-defaultbuild. - Do not put token overrides in a stylesheet loaded before Bullframe.
- Do not rebuild the framework from source for a colour change.
- Do not set
outline: none; tune--bf-focus-ring-*instead.


