颜色

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/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 之后加载其中一个就行：

文件	你能得到什么	文字颜色规则
dist/css/adminlte-colors.css	在 OKLCH 里设计的 14 种颜色 —— orange、amber、olive、teal、sky、indigo、violet、fuchsia、pink、navy、steel、slate、graphite、midnight —— 每一种配白色文字都清晰可读，排布时也考虑到了要跟 Bootstrap 的主题色相邻	Bootstrap 5 的 color-contrast()，4.5:1
dist/css/adminlte-colors-v3.css	18 种 AdminLTE 3 颜色 —— lightblue、navy、olive、lime、fuchsia、maroon、blue、indigo、purple、pink、red、orange、yellow、green、teal、cyan、gray、gray-dark —— 取值和 3.2 版本构建时一样	AdminLTE 3 的规则（Bootstrap 4 YIQ）：lightblue、olive、teal、cyan 等配白色；lime、orange、yellow 配深色

两者输出的类系列完全一样（.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 那个样式表是用和设计版同一套 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 为主题色输出的那套一模一样的形态，所以透明度修饰符和深色模式的表现完全如你所料：

你能得到	示例	备注
Token	--bs-teal, --bs-teal-rgb	另外在两种颜色模式下都有 --bs-teal-bg-subtle、--bs-teal-border-subtle、--bs-teal-text-emphasis
背景	.bg-teal, .bg-teal.bg-opacity-25	变量结构和 .bg-primary 一样
背景 + 对比文字	.text-bg-teal	白色文字；组件用的就是这个
渐变	.bg-gradient-teal	AdminLTE 3 里的那个类；8 种主题色也会一并输出（.bg-gradient-primary……）。Bootstrap 可组合的 .bg-teal.bg-gradient 效果完全一样
文字、边框、链接	.text-teal, .border-teal, .link-teal	可搭配 .text-opacity-*、.border-opacity-*、.link-underline-*
卡片	.card-teal, .card-outline.card-teal, .card.text-bg-teal	喂的是和主题色卡片同一套 --lte-card-variant-* 变量
标注块	.callout-teal	淡色背景、强调色文字 —— 深色模式下会翻转
直聊	.direct-chat-teal
组件	.small-box.text-bg-teal, .info-box.text-bg-teal, .badge.text-bg-teal, .progress-bar.bg-teal	这些本来就能通过 .text-bg-* / .bg-* 自己上色，所以不用额外输出什么
按钮	.btn.text-bg-teal, .btn.bg-gradient-teal	会带上悬停 / 激活状态的色阶，免得看起来像没反应的死按钮

让其中某个颜色成为你的 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。跟着这个颜色一起变的还有：

跟着变的	具体内容
按钮	.btn-primary、.btn-outline-primary（悬停、激活和禁用状态的色阶和 Bootstrap 自己的完全一致）、.btn-link
链接	a、.link-primary、.btn-link、分页链接 —— 在深色模式下带 Bootstrap 的深色模式色调
工具类和 token	--bs-primary、--bs-primary-rgb、subtle / emphasis 那一组三个、.text-primary、.bg-primary、.border-primary、.text-bg-primary、.alert-primary、.list-group-item-primary、.accordion
表单	.form-control / .form-select 的焦点圈和聚焦边框、.form-check-input:checked、不确定状态的复选框、.form-range 的滑块手柄
组件	.nav-pills .nav-link.active、.pagination .active、.progress-bar、.list-group-item.active、.dropdown-item.active、--bs-focus-ring-color
AdminLTE	.card-primary（以及 .card-outline）、.direct-chat-primary、.toast-primary、带 .bg-primary 的 .small-box/.info-box

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 检查关卡。
• 实色工具类（.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 3	现在
bg-lightblue	text-bg-sky	同一色相，取值调到白色文字能过关
bg-maroon	text-bg-pink
bg-navy / bg-olive / bg-fuchsia	名字不变	取值重新设计过
bg-lime	—	不存在能配白色文字的 lime；改用 text-bg-olive 或 Bootstrap 的 text-bg-warning
bg-purple, bg-teal, bg-orange, bg-indigo …	text-bg-violet, text-bg-teal, text-bg-orange, text-bg-indigo	见调色板表格
sidebar-dark-primary, navbar-light …	text-bg-* + data-bs-theme	见上文的皮肤
bg-gradient-*	bg-gradient-*	保留了，调色板和主题色都能用

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