Skip to content
Tutorials Center
My learning

Topics

Lesson 44 of 58 ยท Customizing

Building a Custom Theme

Design a reusable Bootstrap 5.3 theme: pick a palette that passes contrast, set fonts, radius and shadows, add custom components and keep it versioned.

You now know the three tools for changing Bootstrap: CSS variables, Sass and color modes. A theme is what you get when you use them in an organized way: a small, documented set of design decisions (a palette, type, shape, depth) mapped onto Bootstrap, plus a few custom components, packaged so that every page of a site or every project of a team looks related.

This lesson builds a complete theme called Harbor from scratch, using only CSS so every step runs in the live editor. The same decisions translate directly to Sass variables if you prefer to compile.

Start with decisions, not code

Before writing any CSS, write down the choices. A theme has five groups of decisions:

Group Question Bootstrap hook
Palette What is the brand color, and what are the neutrals? --bs-primary*, --bs-body-bg, --bs-body-color, --bs-border-color
Typography Which fonts, which base size? --bs-body-font-family, --bs-body-font-size, heading rules
Shape Sharp, soft or very round? --bs-border-radius*
Depth Flat or layered with shadows? --bs-box-shadow*
Behavior Light only, or light and dark? data-bs-theme and a dark block

Everything in the table can be set without touching Bootstrap's files. The theme is a separate layer that sits on top.

flowchart TB
  B["Bootstrap CSS<br/>(pinned version)"] --> T["theme/tokens.css<br/>your --hb-* decisions"]
  T --> O["theme/overrides.css<br/>maps tokens onto --bs-* and .btn-*"]
  O --> K["theme/components.css<br/>hb-callout, hb-stat, ..."]
  K --> P["Your pages<br/>+ a few utility classes"]

Load order is the architecture: each layer builds on the one above.

Step 1: the palette

A good palette is small: one brand color, a ramp of neutrals for backgrounds and text, and the semantic colors (success, warning, danger) you already have. The hard part is not beauty but contrast. Text must be readable against its background: the WCAG accessibility guideline asks for a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text.

You can check a palette with code before you build anything. This script computes the ratio for the pairs the theme will use:

JS Check the Harbor palette for contrast

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The brand teal #0f766e passes with white text (about 5.5:1), so a white-on-teal button is fine. The bright amber #f59e0b fails with white text (about 2.2:1), so the theme will not use it for that purpose. Finding that out here is far cheaper than finding it in a user complaint.

Step 2: tokens and overrides

Create one block of tokens: your own variables, namespaced so they never collide with Bootstrap's (--hb- for Harbor). Then a second block that maps the tokens to Bootstrap's variables.

Two details are easy to get wrong:

  1. Bootstrap defines the light values on :root, [data-bs-theme=light]. If you override only :root, a light region nested in a dark page keeps Bootstrap's defaults. Use the same selector pair as Bootstrap.
  2. Any variable you override for light mode must also be overridden for dark mode. Your light :root block comes after Bootstrap's own dark block in the cascade, so otherwise the dark page would receive your light values.

Component variants such as .btn-primary use their own fixed variables, so the theme also re-maps those, as you saw in the CSS variables lesson.

The Harbor theme on a sample page

Try the toggle: because every override has a dark twin, both modes look deliberate. Notice what you did not write: a rule for the navbar, the table, the pagination. The variables carried the theme to them.

Check the badge, not only the hero. After you re-map the brand color, scroll through every component you use (forms, tables, pagination, dropdowns) in both modes. A few details, such as the blue focus ring on some form controls, may still use fixed values and need their own line.

Step 3: fonts

Pick system font stacks first. They load instantly, look native on each platform and need no network request. Bootstrap's own default stack is system-ui, -apple-system, "Segoe UI", Roboto, .... For personality, change the heading font only and keep the body readable, as Harbor does with a serif stack on headings.

If you do load a web font on your own site, link it in the <head> with font-display: swap (most font services add this through a URL parameter) and keep a fallback stack so the page is readable before the font arrives:

CSS
:root {
  --bs-body-font-family: "Inter", system-ui, -apple-system, "Segoe UI", sans-serif;
}

Limit yourself to two families and three weights. Every extra file slows the first paint.

Step 4: custom components that speak Bootstrap

Bootstrap will not have every component you need. When you add your own, follow Bootstrap's pattern instead of inventing a new one:

  1. Prefix the class (hb-callout) so it never clashes with Bootstrap or a third-party library.
  2. Expose variables on the component class (--hb-callout-bg) and read them in the rules, exactly like .btn and .card do.
  3. Default to Bootstrap's variables (var(--bs-border-radius)), so the component follows the theme and the color mode.
  4. Make variants change only variables, as .btn-primary does.
A custom callout with its own variable API

Because the callout only reads --bs-* variables, it works in dark mode without a single [data-bs-theme] rule of its own. That is the payoff of the pattern.

Naming and file structure

A theme that lives in one 900-line file stops being maintainable. Split it by purpose:

TEXT
theme/
  tokens.css        # --hb-* decisions: palette, fonts, radii (the only file designers edit)
  overrides.css     # maps tokens onto --bs-* and .btn-primary etc.
  components.css    # .hb-callout, .hb-stat, ...
  CHANGELOG.md      # what changed in each version

With Sass, the split is _variables.scss (your overrides before Bootstrap's variables), _custom.scss (components after Bootstrap) and one entry file that imports them in order.

Naming rules that save pain later:

  • One prefix for everything you own: classes hb-*, variables --hb-*. Never create classes that start with btn- or variables that start with --bs- unless you are deliberately overriding Bootstrap.
  • Name tokens by role, not by value. --hb-brand is still correct after a rebrand; --hb-teal is not.
  • No !important in the theme. Utilities already carry it, and the variable approach rarely needs more.
  • Prefer overriding variables over rewriting rules. A rule you copy from Bootstrap is a rule you must re-check at every upgrade.

Versioning the theme

A theme is a product with its own releases:

  1. Pin Bootstrap. Use an exact version in package.json or in the CDN URL ([email protected]), and write the compatible version in the theme's header comment, as Harbor does.
  2. Give the theme a semantic version. Changing a token value is a minor or patch change. Renaming or removing a token or class is a major change, because other pages depend on it.
  3. Keep a changelog. One line per change, with a note about anything pages must update.
  4. Upgrade deliberately. When Bootstrap releases a new version, bump it in a branch, read the release notes, then look at one page for each component type in both color modes before merging.
  5. Prefer composition to forking. If you only ever change variables and add prefixed components, an upgrade is mostly a version bump. If you copy and edit Bootstrap's rules, every upgrade becomes a merge.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the Harbor theme write its light overrides on :root, [data-bs-theme=light] instead of just :root?

    Bootstrap defines light values on both :root and [data-bs-theme=light]. Matching both selectors keeps nested light regions themed.
  2. 2. You override --bs-primary-bg-subtle for light mode only. What happens in dark mode?

    Your later light rule can win over Bootstrap's earlier dark block for the root element. Provide a dark twin for each override.
  3. 3. Which pair would your contrast check reject for normal text?

    Normal text needs at least 4.5:1. White on bright amber is far below that.
  4. 4. What is the Bootstrap-style way to add a custom component?

    A prefix avoids clashes, own variables allow variants and tweaks, and defaults taken from --bs-* make it follow the theme and color mode.
  5. 5. A designer renames the brand color from teal to purple. Which token name survives best?

    Name tokens by role. A role name stays true when the value changes.

Summary

  • A theme is a documented set of decisions (palette, type, shape, depth, modes) layered on top of a pinned Bootstrap version.
  • Check text and background pairs for contrast (4.5:1 for normal text) before building the palette.
  • Map your own --hb-* tokens onto --bs-* variables and the button variant variables; always provide the dark twin and use :root, [data-bs-theme=light] for light.
  • Prefer system font stacks; limit extra families and weights.
  • Build custom components with a prefix, their own variables, --bs-* defaults and variants that change only variables.
  • Split tokens, overrides and components into files, name by role, and version the theme with a changelog.

Next lesson: Accessibility in Bootstrap.