---
name: bootstrap-color-system
description: Work with Bootstrap 6's color system in Sass and CSS. Use when customizing colors, adding or overriding theme colors, working with color modes, or using the color scales, semantic tokens, and theme classes.
guide: /customize/color
title: bootstrap-color-system
canonical_url: https://skilld.dev/gh/twbs/bootstrap/bootstrap-color-system
last_updated: 2026-11-20T08:03:55.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install twbs/bootstrap/bootstrap-color-system`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/bootstrap-color-system`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/twbs/bootstrap/bootstrap-color-system) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/bootstrap-color-system`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/bootstrap-color-system --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/bootstrap-color-system --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Bootstrap 6 color system

Bootstrap 6 colors flow through a fixed pipeline: a handful of `oklch()` hues become full scales, a subset of those scales gets semantic roles, and components read the roles — never the hues. Customizing colors means picking the right layer to change, so start by identifying which one your task belongs to.

## Workflow

- [ ] Step 1: Locate the layer you need to change
- [ ] Step 2: Base hues and scales
- [ ] Step 3: Theme colors
- [ ] Step 4: Layer colors for backgrounds, foregrounds, and borders
- [ ] Step 5: Color modes
- [ ] Step 6: Compile-time overrides
- [ ] Step 7: Runtime overrides
- [ ] Step 8: Functions and utilities
- [ ] Step 9: Verify

---

## Step 1: Locate the layer you need to change

The pipeline, with the file that owns each stage:

1. **Base hues** — `scss/_colors.scss` defines 16 hues as `oklch()` scalars and collects them in `$colors`.
2. **Color scales** — the same file derives steps `025`–`975` from each hue with `color-mix()`, emitting `--blue-500`, `--red-200`, and so on into `:root`.
3. **Theme colors** — `scss/_theme.scss` maps semantic names (`primary`, `danger`, …) onto those scale tokens, one role at a time.
4. **Root tokens** — `scss/_root.scss` emits every theme role as `--<name>-<role>` (`--danger-bg-subtle`) plus the layer color tokens.
5. **Theme classes** — `scss/helpers/_theme-colors.scss` outputs `.theme-<name>` in `@layer helpers`, remapping `--<name>-<role>` onto the generic `--theme-<role>`.
6. **Components and utilities** — read `--theme-*` (with a neutral fallback) and the layer tokens. Nothing reads a raw hue.

Match the task to the layer: a different brand blue is stage 1, a new semantic color is stage 3, restyling one component is a component token (see the `bootstrap-component` skill), and a one-off tweak in an app is a runtime CSS variable override.

---

## Step 2: Base hues and scales

Each hue is a single `oklch()` value that anchors step 500:

```scss
$blue: oklch(60% 0.24 240) !default;
```

The 16 hues are blue, indigo, violet, purple, pink, red, orange, amber, yellow, lime, green, teal, cyan, brown, gray, and pewter, plus `$white` and `$black`. `$colors` collects them through `defaults()`, so the map merges rather than replaces.

Scales are generated, not hand-picked. Every hue is mixed toward `$tint-color` (`var(--white)`) for steps `025 050 100 200 300 400` and toward `$shade-color` (`var(--black)`) for `600 700 800 900 950 975`, in the `$color-mix-space` color space (`lab`). Change a hue and its whole scale re-derives.

Add a hue by merging into `$colors` — you get its full scale and any color utilities built from `$colors` automatically:

```scss
@use "bootstrap/scss/bootstrap" with (
  $colors: (
    "slate": oklch(55% 0.04 250),
  )
);
```

Tint and shade percentages (`$color-tints`, `$color-shades`), the mixing space, and the mix targets are all configurable the same way. Individual steps can be overridden through `$color-tokens`.

Mixing happens against `var(--white)` / `var(--black)` on purpose: it keeps `color-mix()` live in the output instead of letting the CSS minifier flatten it into static `lab()` values.

---

## Step 3: Theme colors

`$theme-colors` in `scss/_theme.scss` defines eight semantic colors — `primary`, `accent`, `success`, `danger`, `warning`, `info`, `inverse`, `secondary` — each a nested map of nine roles:

| Role | What it's for |
| --- | --- |
| `base` | The raw brand color the rest is derived from |
| `bg` | Solid background, e.g. a solid button or badge |
| `bg-subtle` | Tinted surface for alerts, subtle buttons, callouts |
| `bg-muted` | One step stronger than subtle |
| `fg` | Text on a subtle surface |
| `fg-emphasis` | Higher-contrast text on a subtle surface |
| `contrast` | Text and icons sitting on `base` / `bg` |
| `border` | Borders on subtle surfaces |
| `focus-ring` | Focus outline color |

Most roles are `light-dark(…)` pairs, and every value is a `var()` reference to a scale token rather than a literal color:

```scss
"danger": (
  "base": var(--red-500),
  "fg": light-dark(var(--red-600), var(--red-400)),
  "bg-subtle": light-dark(var(--red-100), var(--red-900)),
  "border": light-dark(var(--red-300), var(--red-600)),
  "contrast": var(--white)
),
```

The map produces two things: `--danger-fg`-style tokens on `:root, :host`, and a `.theme-danger` class that assigns them to the generic `--theme-fg`, `--theme-bg-subtle`, and friends. That indirection is the whole point — a component written against `--theme-*` supports every color, current and future, with one rule.

Use `.theme-reset` on a nested subtree to set those `--theme-*` tokens to `initial` and return children to their component defaults.

The `primary`, `success`, and `danger` keys are required; other code (links, focus rings, form states, checked controls) reads their tokens. Renaming or removing them breaks the build.

---

## Step 4: Layer colors for backgrounds, foregrounds, and borders

Neutral surfaces don't live in `$theme-colors`. Three separate maps in `scss/_theme.scss` cover them:

- `$theme-bgs` → `--bg-body`, `--bg-1` through `--bg-4` (increasingly contrasty surfaces), plus `--bg-white`, `--bg-black`, `--bg-transparent`.
- `$theme-fgs` → `--fg-body`, `--fg-1` through `--fg-4` (decreasing emphasis).
- `$theme-borders` → `--border-body`, `--border-subtle`, `--border-muted`, `--border-emphasized`.

Use these as the *unthemed* fallbacks in component tokens: `var(--theme-bg-subtle, var(--bg-1))`, `var(--theme-border, var(--border-color))`. Note that `--border-color` is a separate global token in `$root-tokens` — the default border color for components — distinct from this `--border-*` family.

Unlike `$theme-colors`, these are flat maps, which makes them easy to extend with an extra surface step. All four maps merge through `defaults()`, so pass only the keys you are changing.

---

## Step 5: Color modes

Bootstrap 6 does not redeclare variables per mode. Every adaptive token is a `light-dark()` pair, and CSS resolves it from the inherited `color-scheme`:

- `:root, :host` sets `color-scheme: light dark`, so the default is whatever the OS prefers.
- `[data-bs-theme="dark"]` and `[data-bs-theme="light"]` set `color-scheme` on that subtree, forcing a mode. It works on any element, nests, and needs no JavaScript.

So switching modes is a matter of setting one attribute, and authoring adaptive colors is a matter of using `light-dark()` instead of writing a dark-mode override block.

Two mixins exist for the cases `light-dark()` can't cover:

```scss
// Non-color values can't go through light-dark()
@include color-mode(dark, $root: true) {
  --shadow-strength: 2.4;
}
```

`color-mode($mode, $root)` honors the `$color-mode-type` config, which defaults to `"media-query"` (emitting `@media (prefers-color-scheme: …)`); set it to `"data"` to emit `[data-bs-theme="…"]` selectors instead. `color-scheme($name)` is the plain media-query wrapper when you always want the query.

Custom modes work the same way: add your own `[data-bs-theme="blue"]` selector and override tokens inside it.

---

## Step 6: Compile-time overrides

Maps built with `defaults()` — `$colors`, `$color-tokens`, `$root-tokens`, `$theme-colors`, `$theme-bgs`, `$theme-fgs`, `$theme-borders`, and every component `$*-tokens` — **merge**. Pass only the keys you're changing, and pass `null` to remove one.

Nested theme-color maps merge one level deep. To change one role of a built-in theme, pass the whole sub-map for that theme. A partial sub-map replaces the theme's other roles.

Retuning an existing theme color is still easiest one layer down — change the hue and everything derived from it follows:

```scss
@use "bootstrap/scss/bootstrap" with (
  $blue: oklch(58% 0.21 250)
);
```

To add or restyle a theme color, pass a partial `$theme-colors` map through the main entrypoint. `defaults()` keeps the built-ins. Keep `primary`, `success`, and `danger` unless you replace their whole sub-map:

```scss
@use "bootstrap/scss/bootstrap" with (
  $theme-colors: (
    "brand": (
      "base": var(--indigo-500),
      "fg": light-dark(var(--indigo-600), var(--indigo-400)),
      "fg-emphasis": light-dark(var(--indigo-800), var(--indigo-300)),
      "bg": var(--indigo-500),
      "bg-subtle": light-dark(var(--indigo-100), var(--indigo-900)),
      "bg-muted": light-dark(var(--indigo-200), var(--indigo-800)),
      "border": light-dark(var(--indigo-300), var(--indigo-600)),
      "focus-ring": light-dark(color-mix(in oklch, var(--indigo-500) 50%, var(--bg-body)), color-mix(in oklch, var(--indigo-500) 75%, var(--bg-body))),
      "contrast": var(--white)
    )
  )
);
```

When all you want is *one more* theme color without utilities, skip the Sass config and write the class yourself. Components only care about the `--theme-*` tokens:

```scss
@layer helpers {
  .theme-brand {
    --theme-base: var(--purple-500);
    --theme-bg: var(--purple-500);
    --theme-bg-subtle: light-dark(var(--purple-100), var(--purple-900));
    --theme-fg: light-dark(var(--purple-600), var(--purple-400));
    --theme-border: light-dark(var(--purple-300), var(--purple-600));
    --theme-contrast: var(--white);
  }
}
```

`.theme-brand` then works on every theme-aware component. The trade-off: utilities and `--brand-*` root tokens are generated from `$theme-colors`, so `.bg-brand` and `var(--brand-bg)` won't exist.

---

## Step 7: Runtime overrides

Every token is a CSS custom property, so most color changes need no recompile at all:

```css
/* Global — repeat on :host if you adopt the stylesheet in a shadow root */
:root,
:host {
  --bs-primary-bg-subtle: #eef2ff;
}

/* One subtree */
.marketing-hero {
  --bs-theme-bg-subtle: #eef2ff;
}
```

Token names are written **unprefixed** in Sass (`--primary-bg-subtle`). Bootstrap's dist and CDN CSS run PostCSS to add the `--bs-` prefix, so use `--bs-*` when overriding the shipped CSS and unprefixed names when you compile the source yourself.

Runtime overrides are the right tool for per-page or per-tenant theming; compile-time config is for changing the system's defaults.

---

## Step 8: Functions and utilities

Helpers in `scss/_theme.scss` for reading across the color maps, mostly used when generating utilities:

- `theme-color-values($role)` — flat map of color name to the raw value of that role.
- `theme-color-refs($role)` — same, but as `var(--<name>-<role>)` references.
- `theme-token-refs($map, $prefix)` — the equivalent for the layer color maps.
- `theme-opacity-values($var, $fallback)` — an opacity ladder built with `color-mix()` against `transparent`.

`color-contrast($background)` in `scss/_functions.scss` returns a light, dark, or black foreground using the WCAG contrast algorithm. It works on Sass color values, not `var()` references, so it's for build-time swatches and generated classes — the `contrast` role in `$theme-colors` is the runtime answer.

The generated utilities follow the role names: `.fg-primary`, `.fg-emphasis-primary`, `.fg-contrast-primary`, `.bg-primary`, `.bg-subtle-primary`, `.bg-muted-primary`, `.border-primary`, and `.border-subtle-primary`, for every theme color. The layer colors get the same treatment (`.bg-1` through `.bg-4`, `.fg-1` through `.fg-4`, `.border-subtle`). Opacity is a numeric ladder in steps of 10, and follow the role names: `.fg-opacity-50`, `.bg-opacity-70`, `.border-opacity-30`.

Reach for `.theme-*` instead when you want a whole element themed rather than one property recolored.

---

## Step 9: Verify

1. `npm run css-lint`, then `npm run css`.
2. Grep the compiled `dist/css/bootstrap.css` for the tokens you expected (`--bs-primary-bg-subtle`, `--bs-slate-500`) to confirm they were emitted.
3. Check both color modes: OS preference, `data-bs-theme="dark"`, and a nested `data-bs-theme="light"` inside it.
4. Verify contrast for any new theme color — at minimum `contrast` on `bg`, and `fg` on `bg-subtle`, in both modes.
5. If you added or removed entries in `$colors` or `$theme-colors`, confirm the generated utilities and `.theme-*` classes changed accordingly, and that `npm run docs-build` still passes (the docs render swatches from these maps).
