必须用 map-merge 增量合并 $theme-colors，否则直接赋值会清空 Bootstrap 默认色导致样式失效；需同步定义 "brand" 字符串键、$brand-rgb、对比色变量及 CSS 变量，且声明顺序须在 functions 后、bootstrap 前。
直接在 sass 入口文件里用 map-merge 扩展 $theme-colors，别覆盖、别漏衍生变量、别跳过 $*-rgb。
为什么不能直接赋值 $theme-colors: ("brand": #2563eb)
这会清空 Bootstrap 原有的 primary、secondary 等全部默认色，导致 .btn-primary、.text-success 全部失效。Sass 变量不是“追加”，而是“替换”——必须用 map-merge 增量合并。
- 错误写法：
$theme-colors: ("brand": #2563eb); - 正确写法：
$theme-colors: map-merge($theme-colors, ("brand": #2563eb)); - 键名必须是字符串：
"brand"✅，brand❌（Sass 编译报错）
新增颜色后哪些类能直接用
只要 $theme-colors 里加了 "brand"，Bootstrap 的循环逻辑会自动为所有支持主题色的工具类生成对应版本：
-
.text-brand、.bg-brand、.border-brand -
.text-sm-brand、.bg-lg-brand（前提是responsive: true已启用） -
.btn-brand、.btn-outline-brand（但注意：边框/文字对比色不自动适配，见下一条） -
.alert-brand、.badge-brand等组件级类也同步可用
为什么 .btn-outline-brand 边框还是灰色
因为 btn-outline-* 的边框和文字色由 $theme-color-contrast-light 和 $theme-color-contrast-dark 控制，这两个是硬编码阈值（非动态计算），不会随你新加的 brand 自动调整。
- 结果就是：即使
brand是深蓝#2563eb，.btn-outline-brand文字仍可能是浅灰，边框仍是默认灰 - 解决办法：手动重定义对应 CSS 变量，例如在
:root中加：--bs-btn-outline-brand-color: #2563eb;、--bs-btn-outline-brand-border-color: #2563eb; - 或者更彻底：在 Sass 中复写
$theme-color-contrast-dark等变量（需理解其作用域和依赖链）
别漏掉 -rgb 和强调色变量
Bootstrap 5.3+ 大量使用 var(--bs-brand-rgb) 构造透明背景、渐变、阴影等。只加 "brand": #2563eb 不够，必须同步提供 brand-rgb 值，否则 bg-gradient、text-emphasis 类会降级或出错。
- 推荐写法：
$brand: #2563eb;<br>$brand-rgb: 37, 99, 235;<br>$theme-colors: map-merge($theme-colors, (<br> "brand": $brand,<br> "brand-rgb": $brand-rgb<br>));
- 还要补上
brand-text-emphasis、brand-bg-subtle等（如果项目用到深色模式或 subtle 背景） - 这些变量必须在
@import "bootstrap/scss/functions"之后、@import "bootstrap/scss/bootstrap"之前声明，否则不生效
真正麻烦的不是加一个颜色，而是让这个颜色在所有上下文（按钮、文本、背景、边框、响应式、深色模式、CSS 变量、Sass 函数）里都表现一致——漏掉任意一环，就会在某个角落突然“变灰”或“看不见”。
