必须用 map-merge() 增量扩展 $theme-colors 并保留所有默认键名，否则工具类失效；新增颜色需手动补充对比色变量并启用相关模块。
直接改 $theme-colors 是唯一能全局生效、不破坏按钮悬停/禁用/深色模式逻辑的方式；硬编码覆盖 CSS 类或漏掉衍生变量，第二天就会发现 .btn-primary 文字看不清、.alert-warning 边框消失、.text-info 在深色模式下还是白底黑字。
为什么不能直接赋值 $theme-colors: ("brand": #2563eb)
这会彻底清空 Bootstrap 原有全部主题色键（"primary"、"success"、"danger" 等），导致所有依赖它们的类失效：.btn-primary 变灰、.border-success 消失、.alert-danger 不再渲染。Sass 编译器不会报错，但生成的 CSS 里根本找不到这些类的规则。
必须用 map-merge() 增量扩展：
$theme-colors: map-merge($theme-colors, ("brand": #2563eb, "navy": #1e3a8a));- 键名必须加引号：
"brand"✅，brand❌（Sass 会当成未定义变量） - 必须在
@import "bootstrap/scss/functions";之后、@import "bootstrap/scss/variables";之前执行
$theme-colors 里哪些键名是强制保留的
Bootstrap 工具类和组件循环（按钮、alert、badge、form-check）只认固定键名。删掉或拼错任何一个，对应类就完全失效：
-
"primary"：必须存在，否则.btn-primary、.text-primary、.bg-primary全部不工作 -
"secondary"、"success"、"danger"、"warning"、"info"、"light"、"dark"同理 - 键名大小写敏感，且不能带空格或连字符：
"my-blue"❌，"myblue"✅（但建议用语义名如"indigo"）
新增颜色后哪些工具类自动生效，哪些要手动处理
只要 $theme-colors 合并时机正确、键名合法，以下类会自动生成：
-
.text-brand、.bg-brand、.border-brand、.link-brand -
.btn-brand、.btn-outline-brand、.alert-brand -
.badge-brand、.list-group-item-brand
但这些不会自动出现：
-
.shadow-brand：因为$enable-shadows默认为false，且阴影工具类需单独启用模块 -
.text-brand-emphasis：需手动扩展$theme-colors-emphasismap（它默认只含"primary"和"secondary"） -
.btn-brand-focus或自定义伪类：底层靠button-variant()生成，不支持新增状态名
为什么 .btn-outline-brand 边框还是灰色
轮廓按钮的边框和文字色由 color-contrast($value) 计算得出，而该函数依赖 $theme-color-contrast-dark 和 $theme-color-contrast-light 这两个阈值变量——它们是硬编码的黑白判断逻辑，**不会随你新加的颜色自动适配**。
解决方法是为新颜色显式补充对比色变量：
$brand-rgb: 37, 99, 235;-
$brand-text-emphasis: #000;（深色文字） -
$brand-bg-subtle: #e0f2fe;（浅背景） - 同时确保
$enable-emphasis-colors为true
否则 .btn-outline-brand 悬停时可能变成不可读的灰底灰字，或者在深色模式下直接消失。
