CSS框架Primer Design System应用_构建开发者风格的UI

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，是设计契约的一部分。