颜色

AdminLTE 4 只用了 Bootstrap 5.3 的主题色来给自己做样式 —— primary、success、danger、warning、info、secondary、light、dark —— 除此之外没别的。这让 adminlte.css 保持得很小，但仪表盘的一行组件里经常想要不止五种色调，而且 AdminLTE 3 的老用户还惦记着 .bg-navy、.bg-teal 和那些侧边栏皮肤。

dist/css/adminlte-colors.css 就是答案，而且是按需启用的：多加载一个样式表（gzip 后约 8 kB），就会以 --bs-* token 的形式加入十四种颜色，外加 Bootstrap 为自己主题色生成的那一整套类系列 —— 而且还能让其中任意一个成为你的 primary。对于不加载它的项目来说，什么都不变。更喜欢 AdminLTE 3 原封不动的颜色？还有一个专门的样式表 —— 见下面的两套调色板。

所有颜色、皮肤和组件套装都能在 颜色演示页面上现场试用 —— 那里还有一个给你自己品牌色用的检查器。

获取样式表

把它加载在 adminlte.css 之后。它只添加类，不会覆盖 adminlte.css 里的任何东西。

<link rel="stylesheet" href="css/adminlte.css" />
<link rel="stylesheet" href="css/adminlte-colors.css" />

来自 CDN（请注明在生产环境中测试的精确版本）：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/admin-lte@4.9.1/dist/css/adminlte-colors.min.css" />

从 npm，使用打包工具：

import "admin-lte/dist/css/adminlte.min.css"
import "admin-lte/dist/css/adminlte-colors.min.css"

或者你自己编译 —— Sass 入口是 src/scss/adminlte-colors.scss，添加自己的颜色也是走这个入口（见下文）。另外还生成了一个 RTL 版本（adminlte-colors.rtl.css），是为了跟其他 CSS 保持形式上的对称；这个样式表里没有任何依赖方向的规则，所以两个文件在哪个方向下都能用。

两种调色板

你可以选择为 4.4 重新设计过的那套颜色（也就是本页面的默认值，见下文），或者AdminLTE 3 原封不动的原版颜色。它们以两个文件的形式发布，定义的是同一批类名、只是取值不同，所以只要在 adminlte.css 之后加载其中一个就行：

两者输出的类系列完全一样（.bg-*、.text-bg-*、.text-*、.border-*、.link-*、.bg-gradient-*、.card-*、.callout-*、.direct-chat-*，以及带深色模式变体的 token），所以本页面讲的任何内容对两者都适用。演示页面可以让你在两者之间实时切换：颜色演示和主题自定义都有一个调色板切换开关。

<!-- either the designed palette … -->
<link rel="stylesheet" href="css/adminlte-colors.css" />
<!-- ……或者 AdminLTE 3 的原始版本，两者不要同时使用 -->
<link rel="stylesheet" href="css/adminlte-colors-v3.css" />

AdminLTE 3 的原版颜色，以及每种颜色配白色文字能达到的对比度 —— 其中好几种都低于 WCAG AA 对正文要求的 4.5:1，跟 v3 里一模一样；这就是保持原样的代价：

让 v3 的颜色通过 AA

data-lte-contrast="aa" 能修好这八种颜色，而且一个取值都不用动。 v3 的规则给八种颜色配了白色文字，而这八种颜色对正文来说都达不到 WCAG AA 的 4.5:1。这个属性只把这八种翻成能达到标准的深色文字，每一个背景色都保持一个字节不变：

<html lang="en" data-lte-contrast="aa">

这里只列出比值，而不是把它们渲染出来，因为把不达标的组合渲染出来，就等于在本页面上放了同样通不过这项检查的文字 —— 去 颜色演示 页面把开关打开，就能在真实组件上看到两者并排对比。它覆盖了调色板在自己颜色上绘制文字的所有地方：.text-bg-*、.bg-gradient-*、.card-* 头部、.direct-chat-*，以及 data-lte-primary 生成的按钮、徽章和胶囊文字。有三件事值得了解：

• 必须用纯黑。 AdminLTE 3 自己的深墨色 #1f2d3d 在这八种颜色里只有两种能达到 4.5:1 —— teal 和 cyan。其余的都需要纯黑，也就是 aa 用的那个。本来就配深色文字的那些颜色（lime、orange、yellow）继续用 #1f2d3d，不动它们。
• 翻转过的颜色要搭配 data-bs-theme="light"。 承载这八种颜色之一的侧边栏或头部现在用的是深色文字，所以它的导航链接也应该跟着变：<nav class="app-header navbar navbar-expand text-bg-lightblue" data-bs-theme="light">。演示页面在开关打开时会帮你处理好这件事。
• .text-lightblue 和 .link-lightblue 是另一个问题。 那些是把颜色当作文字画在页面背景上，而这八种颜色在那里同样也不够。改用 emphasis token 吧 —— .text-lightblue-emphasis 这类写法来自 --bs-lightblue-text-emphasis，也就是把这个颜色调暗 60% 之后的结果，在浅色背景上能看清。

这个属性对两个样式表都有效；在重新设计的那套调色板上，它什么都不输出，因为那里的每种颜色按构造就配白色文字达到了 AA —— 所以把它留在你的标记里没有任何开销（#6110）。

v3 那个样式表是用和设计版同一套 Sass 构建的 —— src/scss/adminlte-colors-v3.scss 把 $lte-palette 设成了 v3 的 map，并把 $lte-palette-contrast 设为 "yiq" —— 所以 $lte-palette-custom、$lte-palette-aliases 以及下面其余的那些对它也同样适用。它的皮肤预设来自 AdminLTE 2：彩色头部配 v3 的深色侧边栏（text-bg-gray-dark，也就是 sidebar-dark-* 那个确切的背景），或者配白色侧边栏：

调色板

九种彩色加上五种中性色，用于界面外观。它们每一种配白色文字的对比度都能达到 4.5:1 或更好，所以 .text-bg-*、小方盒、徽章和彩色侧边栏读起来都是一致的 —— 不用再逐个颜色去纠结“这个是不是得用深色文字？”。

这些颜色是按它们本身是什么来命名的，而不是照搬 Bootstrap $colors 里的名字（blue、purple、red……）。那些名字和主题色有重叠，所以有意不生成对应的类；如果你想拿原始值，Bootstrap 定义的 --bs-blue、--bs-purple……这些变量依然还在。

你能得到什么

对于每一种颜色 <name>，这个样式表会输出跟 Bootstrap 为主题色输出的那套一模一样的形态，所以透明度修饰符和深色模式的表现完全如你所料：

让其中某个颜色成为你的 primary

Bootstrap 在构建时会把 $primary 编译进它的组件里：.btn-primary 出厂时带的是 --bs-btn-bg: #0d6efd，而不是 var(--bs-primary)。所以光覆盖那个 token，只会重绘 .text-primary 和 .bg-primary，而每个按钮、分页和复选框还是蓝色的 —— 这就是过去皮肤看起来只应用了一半的原因（#6107）。

两个颜色样式表都把这些组件重新接到变量上，只要一个属性就能让它们指向某个调色板颜色：

<html lang="en" data-lte-primary="teal">

不加这个属性的话什么都不变，而且它对任何容器都有效 —— 页面的某一块区域也能拥有自己的 primary。跟着这个颜色一起变的还有：

Bootstrap 自己的主题色也能用 —— data-lte-primary="danger" 完全不需要调色板颜色。有两样东西是故意保持 Bootstrap 蓝色的：.table-primary 的条纹和悬停色调，以及开关选中时那个以 data-URI 形式画出来的滑块。

如果品牌色不在调色板里，就自己设置 token，同时保留那个属性：

[data-lte-primary="brand"] {
  --bs-primary: #7a5af8;
  --bs-primary-rgb: 122, 90, 248;
  /* 可选 —— 不设置的话，悬停色阶会用 color-mix() 计算出来 */
  --lte-primary-hover: #6849e6;
  --lte-primary-active: #5b3fd1;
  /* 浅色品牌色配深色文字 */
  --lte-primary-color: #fff;
}

用 Sass 的话，一行就够了 —— $lte-palette-custom: ("brand": #7a5af8)（见添加你的品牌色）—— 然后 data-lte-primary="brand" 就会自动为你生成，色阶和对比文字都一并搞定。

要挑一个配白色文字的颜色：Bootstrap 里选中复选框内的对勾是白色的，而且没法通过 CSS 改色。设计版调色板里每种颜色都符合要求；而 v3 调色板里，lime、yellow 和 orange 则不行。

皮肤 —— 给侧边栏和头部上色

在 AdminLTE 4 里，所谓“皮肤”并不是一个专门的类：它就是侧边栏和头部上的一个背景工具类加上 data-bs-theme。data-bs-theme="dark" 会给出浅色的导航链接和品牌文字；"light" 则给出深色的。由于每种调色板颜色都配白色文字，所以彩色的侧边栏或头部总是搭配 dark 来用：

<!-- header -->
<nav class="app-header navbar navbar-expand text-bg-sky" data-bs-theme="dark">…</nav>

<!-- sidebar -->
<aside class="app-sidebar text-bg-navy shadow" data-bs-theme="dark">…</aside>

每个预设还会写明它配套的 data-lte-primary，这样按钮的颜色就能和界面外观对上。后台仪表盘通常会把它们的外观分成四大类，这些预设就是照着这个来分的。每个缩略图都是真家伙的微缩版 —— 包括侧边栏、头部，以及与之搭配的两个点缀色。颜色演示页面点一下就能把任意预设应用到它自己身上；主题自定义页面也能做到同样的事，而且之后还能自由地混搭侧边栏、导航栏和页脚（它的取色器把调色板列在 “Extended palette” 下面）。

bg-body、bg-body-secondary 和 bg-body-tertiary 是 Bootstrap 自带的表面工具类 —— 它们会跟随元素的 data-bs-theme，这就是为什么“Default”会是一个深色侧边栏。每一个 text-bg-* 和 bg-gradient-* 条目都需要 adminlte-colors.css。

仪表盘配色组 —— 一行组件上该放哪四种颜色

给一排小方盒挑四种颜色，往往是调色板最容易翻车的地方。下面这些四色组合是按色相关系来选的，而不是凭口味挑的；你可以直接照用，也可以拿它们当起点。

添加你的品牌色

用 Sass（推荐）：在导入入口之前设置 $lte-palette-custom，你的颜色就能获得和内置颜色一模一样的全部 token、工具类和组件钩子。如果你复用了已有的名字，就会覆盖内置的那个值。

// your-adminlte.scss
$lte-palette-custom: (
  "brand": #0f766e,      // 新颜色 → .bg-brand, .text-bg-brand, .card-brand, …
  "sky":   #0369a1       // 将出厂颜色重新调至蓝色
);
@import "admin-lte/src/scss/adminlte-colors";

这还会生成 data-lte-primary="brand"，所以 <html data-lte-primary="brand"> 就能把 Bootstrap 那些 primary 组件变成你的品牌色，并且带上正确的悬停色阶和对比文字。

To ship only your colours (drop the fourteen), set $lte-palette itself instead:

$lte-palette: (
  "brand": #0f766e,
  "brand-dark": #134e4a,
  "brand-warm": #b45309
);
@import "admin-lte/src/scss/adminlte-colors";

还有两个可调项：

• $lte-palette-aliases —— 额外的名字，用来生成和某个已有条目相同的类。AdminLTE 3 的项目可以把旧类名找回来：("lightblue": "sky", "maroon": "pink")。
• $lte-palette-min-contrast-ratio —— 当 Bootstrap 的 color-contrast() 为 .text-bg-*、.bg-gradient-* 和 .card-* 头部挑选自动文字颜色时，所要求的对比度。默认是 4.5（WCAG AA 对正文的要求）。如果某个自定义颜色配白色达不到这个值，文字就会翻成黑色；3（WCAG AA 对大号文字和 UI 组件的要求）是另一个站得住脚的设置。
• $lte-palette-contrast —— 可选 "wcag"（默认）或 "yiq"，后者是 Bootstrap 4 / AdminLTE 3 用的亮度规则（$lte-palette-yiq-threshold: 150，深色文字为 #1f2d3d）。v3 那个样式表用的就是 "yiq"；如果你想让自定义调色板也按 v3 的方式来挑文字颜色，就把它设成 "yiq"。

怎么挑一个能用的品牌色。 唯一要紧的一点，就是白色文字放在它上面能达到 4.5:1 —— 这才能保证 .text-bg-brand、小方盒和带品牌的侧边栏清晰可读，也是演示页面上的无障碍检查关卡所校验的东西。大多数品牌蓝、绿、紫都能过关；亮橙色、黄色和青色则不行。演示页面上的检查器会报出对比度，给出一个只调暗到刚好达标的同色相版本，当你的色相和已有颜色重叠时会提醒你，还会打印出对应的 Sass 代码片段。

不用 Sass，直接基于预构建的 CSS，你依然可以手写一种颜色。下面就是一个名字的完整写法：

:root, [data-bs-theme="light"] {
  --bs-brand: #0f766e;
  --bs-brand-rgb: 15, 118, 110;
  --bs-brand-text-emphasis: #062f2c;
  --bs-brand-bg-subtle: #cfe4e2;
  --bs-brand-border-subtle: #9fc8c5;
}
[data-bs-theme="dark"] {
  --bs-brand-text-emphasis: #6fada8;
  --bs-brand-bg-subtle: #031816;
  --bs-brand-border-subtle: #094742;
}
.bg-brand      { --bs-bg-opacity: 1; background-color: rgba(var(--bs-brand-rgb), var(--bs-bg-opacity)) !important; }
.text-bg-brand { color: #fff !important; background-color: rgba(var(--bs-brand-rgb), var(--bs-bg-opacity, 1)) !important; }
.text-brand    { --bs-text-opacity: 1; color: rgba(var(--bs-brand-rgb), var(--bs-text-opacity)) !important; }
.border-brand  { --bs-border-opacity: 1; border-color: rgba(var(--bs-brand-rgb), var(--bs-border-opacity)) !important; }
.card-brand, .bg-brand, .text-bg-brand {
  --lte-card-variant-bg: #0f766e; --lte-card-variant-bg-rgb: 15, 118, 110;
  --lte-card-variant-color: #fff; --lte-card-variant-color-rgb: 255, 255, 255;
}

这套调色板是怎么设计出来的

这十四个值不是手工挑出来的，而是生成出来的。scripts/palette.mjs 是在 OKLCH 里把它们推导出来的 —— OKLCH 是 Tailwind v4 和 Radix 用来构建各自调色板的那种感知均匀色彩空间 —— 依据的是三条规则：

npm run palette 会依据那些目标值重新生成这张图；npm run palette -- --check（以及单元测试）会校验对比度和色相间隔，并确认 Sass map 和演示数据是一致的。

无障碍与深色模式

• 重新设计的那套调色板里，每种颜色配白色文字都能达到 4.5:1（最低的是 4.6:1），所以 .text-bg-* 从不需要为某个颜色单独开例外，用到它们的演示页面也都能通过 axe 检查关卡。
• v3 那套调色板是历史版本，它十八种颜色里有八种，配上 v3 当初给它们指定的文字颜色，达不到 4.5:1。data-lte-contrast="aa" 会把正好这八种翻过来 —— 见让 v3 的颜色通过 AA。
• 实色工具类（.bg-*、.text-bg-*）在两种颜色模式下都一样，Bootstrap 自己的那些也是如此。而 subtle 系列的 token —— 以及随之而来的 .callout-* —— 会针对 data-bs-theme="dark" 翻转，用的推导方式和 Bootstrap 给 .alert-* 用的是同一套。
• 彩色背景上的 .text-* 和 .link-* 得你自己负责，跟用 Bootstrap 主题色时一模一样。

从 AdminLTE 3 迁移

v3 的扩展颜色有 lightblue、navy、olive、lime、fuchsia、maroon，再加上 Bootstrap 4 的那套命名调色板，其中好几种配白色文字的对比度都低于 4:1。新调色板保留了有用的那些名字（navy、olive、fuchsia），其余的则重做了：

想让现有标记继续能用，有两种办法：加载 adminlte-colors-v3.css，这样每个 v3 名字都会带着原始取值回来（见两套调色板）；或者用重新设计的那套调色板，加上一行别名配置 $lte-palette-aliases: ("lightblue": "sky", "maroon": "pink");。