bootstrap-color-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bootstrap 6 color system

Bootstrap 6 颜色系统

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.

Bootstrap 6 的颜色遵循一套固定的处理流程：少量

oklch()

色相值会生成完整的色阶，部分色阶被赋予语义角色，组件只会读取这些角色——绝不会直接使用色相值。自定义颜色意味着要选择正确的层级进行修改，因此首先要确定你的任务属于哪一层。

Workflow

工作流程

Step 1: Locate the layer you need to change

步骤1：确定你需要修改的层级

The pipeline, with the file that owns each stage:

Base hues —
```
scss/_colors.scss
```
defines 16 hues as
```
oklch()
```
scalars and collects them in
```
$colors
```
.
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
```
.
Theme colors —
```
scss/_theme.scss
```
maps semantic names (
```
primary
```
,
```
danger
```
, …) onto those scale tokens, one role at a time.
Root tokens —
```
scss/_root.scss
```
emits every theme role as
```
--<name>-<role>
```
(
```
--danger-bg-subtle
```
) plus the layer color tokens.

Theme classes —

scss/helpers/_theme-colors.scss

outputs

.theme-<name>

@layer helpers

, remapping

--<name>-<role>

onto the generic

--theme-<role>

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.

整个处理流程及每个阶段对应的文件如下：

基础色相 —
```
scss/_colors.scss
```
中定义了16个色相作为
```
oklch()
```
标量值，并将它们收集在
```
$colors
```
变量中。
色阶 — 同一个文件通过
```
color-mix()
```
从每个色相衍生出
```
025
```
–
```
975
```
的色阶，生成
```
--blue-500
```
、
```
--red-200
```
等变量并挂载到
```
:root
```
上。
主题色 —
```
scss/_theme.scss
```
将语义名称（
```
primary
```
、
```
danger
```
等）逐一映射到这些色阶token上，每个名称对应一个角色。
根token —
```
scss/_root.scss
```
将每个主题角色生成为
```
--<名称>-<角色>
```
格式的变量（如
```
--danger-bg-subtle
```
）以及层级颜色token。

主题类 —

scss/helpers/_theme-colors.scss

在

@layer helpers

中输出

.theme-<名称>

类，将

--<名称>-<角色>

重新映射到通用的

--theme-<角色>

变量上。

组件与工具类 — 读取
```
--theme-*
```
变量（带有中性色兜底）以及层级token。没有任何组件会直接读取原始色相值。

将任务对应到相应层级：修改品牌蓝色属于第1阶段，新增语义色属于第3阶段，调整单个组件样式属于组件token范畴（参见

bootstrap-component

skill），而应用中的一次性微调则属于运行时CSS变量覆盖。

Step 2: Base hues and scales

步骤2：基础色相与色阶

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.

每个色相都是一个单独的

oklch()

值，作为色阶中500号的基准：

scss

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

这16个色相分别是 blue、indigo、violet、purple、pink、red、orange、amber、yellow、lime、green、teal、cyan、brown、gray、pewter，另外还有

$white

和

$black

。

$colors

通过

defaults()

收集这些色相，因此映射表是合并而非替换的。

色阶是自动生成的，而非手动挑选的。每个色相在

$color-mix-space

指定的颜色空间（

lab

）中，向

$tint-color

（

var(--white)

）混合生成

025、050、100、200、300、400

号浅色色阶，向

$shade-color

（

var(--black)

）混合生成

600、700、800、900、950、975

号深色色阶。修改一个色相，它的整个色阶都会重新生成。

通过合并到

$colors

中来添加新的色相——你会自动获得它的完整色阶，以及所有基于

$colors

构建的颜色工具类：

scss

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

浅色与深色的百分比（

$color-tints

、

$color-shades

）、混合空间以及混合目标都可以用同样的方式配置。单个色阶可以通过

$color-tokens

覆盖。

混合操作特意基于

var(--white)

var(--black)

进行：这样可以让输出的CSS中保留

color-mix()

的动态计算，而不会被CSS压缩器扁平化为静态的

lab()

值。

Step 3: Theme colors

步骤3：主题色

$theme-colors

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.

scss/_theme.scss

中的

$theme-colors

定义了8种语义色——

primary

、

accent

、

success

、

danger

、

warning

、

info

、

inverse

、

secondary

——每种颜色都包含9个角色的嵌套映射：

角色	用途
`base`	品牌原色，其他角色都基于它衍生
`bg`	实色背景，例如实心按钮或徽章
`bg-subtle`	浅色调表面，用于提示框、浅按钮、标注等
`bg-muted`	比 subtle 深一级的背景
`fg`	浅色背景上的文字颜色
`fg-emphasis`	浅色背景上的高对比度强调文字
`contrast`	位于 `base` / `bg` 之上的文字和图标颜色
`border`	浅色表面上的边框颜色
`focus-ring`	焦点轮廓颜色

大多数角色都是

light-dark(…)

成对的值，每个值都是对色阶token的

var()

引用，而非固定颜色值：

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)
),

这个映射会生成两部分内容：一是挂载在

:root, :host

上的

--danger-fg

格式的token，二是

.theme-danger

类，它将这些token赋值给通用的

--theme-fg

、

--theme-bg-subtle

等变量。这种间接层正是核心意义所在——基于

--theme-*

编写的组件只需一套规则，就能支持所有现有和未来的颜色。

在嵌套的子树上使用

.theme-reset

可以将这些

--theme-*

token重置为

initial

，让子元素恢复到组件的默认样式。

primary

、

success

和

danger

这三个键是必需的；其他代码（链接、焦点环、表单状态、选中控件等）都会读取它们的token。重命名或删除它们会导致构建失败。

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

步骤4：背景、前景与边框的层级颜色

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.

中性色表面不属于

$theme-colors

的范畴。

scss/_theme.scss

中有三个独立的映射表来管理它们：

```
$theme-bgs
```
→ 对应
```
--bg-body
```
、
```
--bg-1
```
到
```
--bg-4
```
（对比度依次升高的表面），以及
```
--bg-white
```
、
```
--bg-black
```
、
```
--bg-transparent
```
。
```
$theme-fgs
```
→ 对应
```
--fg-body
```
、
```
--fg-1
```
到
```
--fg-4
```
（强调程度依次降低）。

$theme-borders

→ 对应

--border-body

、

--border-subtle

、

--border-muted

、

--border-emphasized

。

在组件token中将这些用作无主题时的兜底值：例如

var(--theme-bg-subtle, var(--bg-1))

、

var(--theme-border, var(--border-color))

。注意

--border-color

是

$root-tokens

中一个独立的全局token——即组件的默认边框颜色——和这里的

--border-*

系列是不同的。

和

$theme-colors

不同，这些都是扁平映射，因此很容易扩展新增的表面层级。所有四个映射表都通过

defaults()

合并，因此只需传入你要修改的键即可。

Step 5: Color modes

步骤5：颜色模式

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.

Bootstrap 6 不会为每种模式重新声明变量。每个自适应token都是一个

light-dark()

成对值，CSS会根据继承的

color-scheme

值来解析它：

```
:root, :host
```
设置了
```
color-scheme: light dark
```
，因此默认模式跟随系统偏好。
```
[data-bs-theme="dark"]
```
和
```
[data-bs-theme="light"]
```
会在对应子树上设置
```
color-scheme
```
，强制使用指定模式。它可以作用于任何元素，支持嵌套，且无需JavaScript。

因此切换模式只需设置一个属性，而编写自适应颜色只需使用

light-dark()

，无需编写暗色模式的覆盖代码块。

对于

light-dark()

无法覆盖的场景，有两个mixin可用：

scss

// 非颜色值无法通过 light-dark() 处理
@include color-mode(dark, $root: true) {
  --shadow-strength: 2.4;
}

color-mode($mode, $root)

会遵循

$color-mode-type

配置，该配置默认为

"media-query"

（输出

@media (prefers-color-scheme: …)

媒体查询）；将其设置为

"data"

则会输出

[data-bs-theme="…"]

选择器。当你始终需要使用媒体查询时，可以使用

color-scheme($name)

这个简单的媒体查询包装器。

自定义模式的工作方式相同：添加你自己的

[data-bs-theme="blue"]

选择器，然后在其中覆盖token即可。

Step 6: Compile-time overrides

步骤6：编译时覆盖

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.

使用

defaults()

构建的映射表——包括

$colors

、

$color-tokens

、

$root-tokens

、

$theme-colors

、

$theme-bgs

、

$theme-fgs

、

$theme-borders

，以及所有组件的

$*-tokens

——都会合并。只需传入你要修改的键，传入

null

则可以删除某个键。

嵌套的主题色映射只会合并一层。要修改内置主题的某个角色，需要传入该主题的完整子映射。如果传入部分子映射，会替换掉该主题的其他角色。

调整现有主题色最简单的方式还是修改上一层——改色相，所有衍生的内容都会自动更新：

scss

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

要添加或重新设计主题色，可以通过主入口传入部分

$theme-colors

映射。

defaults()

会保留内置的主题色。除非你要替换整个子映射，否则请保留

primary

、

success

和

danger

这三个键：

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)
    )
  )
);

如果你只是想多一个主题色，且不需要对应的工具类，可以跳过Sass配置，直接自己写类。组件只关心

--theme-*

token：

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

就可以在所有支持主题的组件上使用了。代价是：工具类和

--brand-*

根token是从

$theme-colors

生成的，因此

.bg-brand

和

var(--brand-bg)

不会存在。

Step 7: Runtime overrides

步骤7：运行时覆盖

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.

每个token都是CSS自定义属性，因此大多数颜色修改根本不需要重新编译：

css

/* 全局 — 如果在影子根中使用样式表，需要在 :host 上重复设置 */
:root,
:host {
  --bs-primary-bg-subtle: #eef2ff;
}

/* 单个子树 */
.marketing-hero {
  --bs-theme-bg-subtle: #eef2ff;
}

Sass中的token名称是不带前缀的（如

--primary-bg-subtle

）。Bootstrap的发布版和CDN CSS会通过PostCSS添加

--bs-

前缀，因此覆盖官方发布的CSS时请使用

--bs-*

格式，如果你自己编译源码，则使用不带前缀的名称。

运行时覆盖适合用于单页面或多租户主题定制；编译时配置则用于修改系统的默认值。

Step 8: Functions and utilities

步骤8：函数与工具类

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)

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

), and opacity is a numeric ladder on the same class names —

.fg-50

.bg-70

.border-30

, in steps of 10.

Reach for

.theme-*

instead when you want a whole element themed rather than one property recolored.

scss/_theme.scss

中提供了用于读取颜色映射的辅助函数，主要在生成工具类时使用：

```
theme-color-values($role)
```
— 返回颜色名称到对应角色原始值的扁平映射。

theme-color-refs($role)

— 同上，但返回的是

var(--<名称>-<角色>)

格式的引用。

```
theme-token-refs($map, $prefix)
```
— 对应层级颜色映射的等效函数。

theme-opacity-values($var, $fallback)

— 使用

color-mix()

和

transparent

混合生成的透明度阶梯。

scss/_functions.scss

中的

color-contrast($background)

使用WCAG对比度算法返回浅色、深色或黑色的前景色。它仅适用于Sass颜色值，不支持

var()

引用，因此用于构建时的色板和生成类——运行时的对比度需求由

$theme-colors

中的

contrast

角色负责。

生成的工具类遵循角色命名规则：每个主题色都对应

.fg-primary

、

.fg-emphasis-primary

、

.fg-contrast-primary

、

.bg-primary

、

.bg-subtle-primary

、

.bg-muted-primary

、

.border-primary

和

.border-subtle-primary

等类。层级颜色也有对应的工具类（

.bg-1

到

.bg-4

、

.fg-1

到

.fg-4

、

.border-subtle

），同一类名还支持数值透明度阶梯——如

.fg-50

、

.bg-70

、

.border-30

，步长为10。

如果你想要为整个元素设置主题，而不仅仅是修改单个属性的颜色，请使用

.theme-*

类。

Step 9: Verify

步骤9：验证

```
npm run css-lint
```
, then
```
npm run css
```
.
Grep the compiled
```
dist/css/bootstrap.css
```
for the tokens you expected (
```
--bs-primary-bg-subtle
```
,
```
--bs-slate-500
```
) to confirm they were emitted.
Check both color modes: OS preference,
```
data-bs-theme="dark"
```
, and a nested
```
data-bs-theme="light"
```
inside it.
Verify contrast for any new theme color — at minimum
```
contrast
```
on
```
bg
```
, and
```
fg
```
on
```
bg-subtle
```
, in both modes.
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).

先运行
```
npm run css-lint
```
，再运行
```
npm run css
```
。
在编译后的
```
dist/css/bootstrap.css
```
中搜索你预期的token（如
```
--bs-primary-bg-subtle
```
、
```
--bs-slate-500
```
），确认它们已被输出。
检查两种颜色模式：系统偏好模式、
```
data-bs-theme="dark"
```
模式，以及在其中嵌套
```
data-bs-theme="light"
```
的情况。
验证所有新主题色的对比度——至少要检查两种模式下
```
bg
```
上的
```
contrast
```
文字对比度，以及
```
bg-subtle
```
上的
```
fg
```
文字对比度。
如果你在
```
$colors
```
或
```
$theme-colors
```
中添加或删除了条目，请确认生成的工具类和
```
.theme-*
```
类也相应变化，并且
```
npm run docs-build
```
仍能通过（文档会根据这些映射渲染色板）。