primer css 需通过 npm 安装并完整引入 primer.css 才能生效，直接 @import cdn 或子文件会导致自定义属性缺失；其组件无运行时逻辑，仅依赖约定 class 名；box/grid 类在 safari 15.6 前存在兼容问题，需降级处理。
Primer CSS 没装对，@import 就会静默失败
Primer 不是单个 CSS 文件，它由 @primer/css（npm 包）和底层的 @primer/primitives、@primer/octicons 等组成。直接在 HTML 里 @import 官网 CDN 链接，或者只引入 build/build.css，大概率样式不生效——因为 Primer 的组件依赖 CSS 自定义属性（--color-fg-muted 等）和层叠顺序，而这些必须通过官方构建流程注入。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 用 npm 安装：
npm install @primer/css，然后在入口 CSS 或 JS 中@import '@primer/css/dist/primer.css'; - 如果用 PostCSS，必须启用
postcss-import插件，否则@import不解析 - 别手动复制
dist/下某个子文件（如utilities/index.css），它不包含 primitives 变量定义，会导致颜色/间距类失效
用 Button 组件却渲染成普通 <button></button>，没样式？
Primer 没有运行时 React/Vue 组件库。所谓 “Button” 是一组合约好的 class 名：比如 btn + btn-primary + btn-sm。你写 <button>Click</button>，浏览器根本不知道这是啥——它只是个没定义的自定义标签。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 纯 HTML 场景：老老实实用
<button class="btn btn-primary">Click</button> - React 场景：自己封装
Button组件，内部返回带 primer class 的<button></button>，别试图复刻 Primer 的 JS 行为（它本身也不带 JS） - 注意 class 优先级：Primer 的
.btn:disabled样式依赖:disabled伪类，如果你用disabled={false}但没真正移除disabled属性，样式不会回退
Box 和 Grid 布局类在 Safari 15.6 以下表现异常
Primer 的 Box（box-border, px-3 等）和 Grid（col-6, grid-row）大量使用 CSS Grid 和现代 Flex 属性。Safari 15.6 之前对 grid-template-areas 和 gap 在 flex 容器中的支持不完整，会导致列宽错乱或间距消失。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 检查目标用户浏览器占比，若需兼容 Safari ≤15.4，避免用
col-*做主布局，改用float+width类（Primer 提供了float-left,w-25等降级类） -
gap类（如gap-3）在旧 Safari 中会被忽略，可加一层margin回退：class="d-flex gap-3 mt-n3"><div class="mt-3">...</div> - 不要依赖
grid-row的隐式行定位，显式写grid-row: 1更稳
主题切换卡顿，color-mode 切换后图标颜色滞后
Primer 的暗色模式靠 data-color-mode 属性 + CSS 自定义属性实现，但 octicons 图标是 SVG 内联写的，其 fill 值默认是硬编码（如 #24292f），不会响应 CSS 变量变化。所以切主题时文字变色了，图标还黑着。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有图标必须用
<svg class="octicon"></svg>形式引入，且确保 class 包含octicon，Primer 的 CSS 才会把fill覆盖为currentColor - 手动设置
data-color-mode后，要触发一次强制重绘：比如给根元素加个class再立刻移除，或调用getComputedStyle(document.documentElement).color - 别用 JS 直接改
style.color，这会覆盖currentColor继承链，图标又失联
Primer 的变量体系和 class 约定很细，但容错低——少一个 data-color-mode，或漏一个 octicon class，主题或图标就断连。这些不是 bug，是设计契约的一部分。
