前端注册页面实战：axios+apifox模拟接口实现前后端联调
2026/10/3 2:58:43
- 前端
- 开发者工具
- 插件系统
【免费下载链接】scriptcat
ScriptCat, a browser extension that can execute userscript; 脚本猫，一个可以执行用户脚本的浏览器扩展
项目地址：https://gitcode.com/gh_mirrors/sc/scriptcat
ScriptCat（脚本猫）是一个可执行用户脚本的浏览器扩展，其选项页、弹窗、安装页等 UI 均基于 React 19 + shadcn/ui + Tailwind CSS v4 构建。本文围绕仓库中 docs/references/design-tokens.md 这一设计令牌（Design Tokens）参考文档展开，系统讲解 ScriptCat 全量色彩令牌的明暗取值、单一来源机制、Tailwind 工具类接入方式，以及阴影、滚动条等配套规范。读完本文，你将能够在新页面或新组件中正确地引用令牌、处理暗色模式、组织浮层层级，并理解bg-primary-background、ring-ring/50、bg-overlay等写法的底层原理。
一、设计令牌的单一来源与工作机制
1. 单一来源：src/index.css
ScriptCat 的所有色彩令牌只有一个事实来源：src/index.css。该文件通过三层结构完成明暗主题的声明与暴露：
:root块定义浅色（Light）值，例如--background: #fafafa、--primary: #1296db；.dark块覆盖暗色（Dark）值，例如--background: #1e1e1e、--primary: #3aacef，通过@custom-variant dark (&:is(.dark *));使 Tailwind 的dark:变体作用于.dark容器内的所有元素；@theme inline块把每一个--token暴露为 Tailwind 颜色（--color-*），从而让bg-<token>/text-<token>/border-<token>等工具类直接可用，且随主题自动切换——因为@theme inline中的--color-*值是var(--token)的引用，而不是硬编码的十六进制值。
主题类（.dark）由 src/pages/components/theme-provider.tsx 管理，并在 React 挂载之前由 src/pages/common.ts 预先设置到document.documentElement上，以避免首屏闪烁（见 docs/develop.md 的 UI 一节）。
2. 基本用法：四类工具类
| 用途 | 写法示例 |
|---|---|
| 背景 | bg-background、bg-card、bg-primary-background、bg-muted |
| 文字 | text-foreground、text-muted-foreground、text-primary、text-destructive |
| 边框 | border-border、border-destructive |
| 焦点环 | ring-ring（常用focus-visible:ring-ring/50） |
@layer base中还有一个全局重置：* { @apply border-border; }，意味着任何元素的默认边框颜色就是border令牌，无需逐个指定。
3. 不透明修饰符（Opacity modifiers）直接叠加
由于@theme inline暴露的是 CSS 变量，Tailwind v4 的透明度修饰符可直接作用于令牌：
bg-primary-background/90—— 实色主按钮的 hover 态（按钮源码见 src/pages/components/ui/button.tsx，默认态为bg-primary-background text-primary-foreground hover:bg-primary-background/90）；ring-destructive/20—— 错误输入的焦点环（aria-invalid:ring-destructive/20，见 button.tsx）；bg-input/30—— 表单输入的半透明填充；bg-overlay/20—— 图片预览的悬浮蒙层（见 ImagePreview.tsx）。
4. 硬性约束：永不硬编码颜色值
仓库的 UI 规范（docs/develop.md 的 UI 一节）明确要求：
- 不硬编码任何颜色值（No hard-coded colors）；
- 需要暗色专属微调时使用
dark:变体，例如dark:bg-...； - 明暗两个主题下都必须可用的变更，必须走令牌而不是字面量。
这一约束同样记录在 docs/references/design-patterns.md 的无障碍小节中（muted-foreground的对比度说明详见下文）。
二、基础表面与文字令牌
| Token / class | Light | Dark | Use |
|---|---|---|---|
background | #fafafa | #1e1e1e | 页面背景 |
foreground | #1a1a1a | #e5e5e5 | 主文字 |
card | #ffffff | #151515 | 卡片 / 表面 |
card-foreground | #1a1a1a | #e5e5e5 | 卡片上的文字 |
popover | #ffffff | #151515 | 浮层（下拉、tooltip、toast）表面 |
popover-foreground | #1a1a1a | #e5e5e5 | 浮层中的文字 |
overlay | rgb(0 0 0 / 0.5) | rgb(0 0 0 / 0.6) | 模态遮罩 —— Dialog / Sheet / AlertDialog 背景（用bg-overlay，永远不要硬编码bg-black/50） |
fg-secondary | #666666 | #b5b5b5 | 次级文字（比muted-foreground稍强） |
要点：
- 表面层级：
background（页面底）→card/popover（浮在页面上的表面）。暗色下card比background更深（#151515vs#1e1e1e），这是暗色模式分层的主要手段之一； - 遮罩统一走
bg-overlay：仓库中的 dialog.tsx、sheet.tsx、alert-dialog.tsx 三个浮层基元均使用fixed inset-0 z-50 bg-overlay实现遮罩； foreground与card-foreground在明暗两个主题下取值一致，因为它们都是"主文字"语义。
三、品牌主色（蓝色）
| Token / class | Light | Dark | Use |
|---|---|---|---|
primary | #1296db | #3aacef | 品牌文字、图标、边框、指示器与激活态强调；不是实色按钮填充 |
primary-background | #1296db | #0b84d8 | 实色主按钮/表面填充，与primary-foreground搭配；暗色更深、与primary色相统一，形成均衡的层级 |
primary-foreground | #ffffff | #ffffff | primary-background上的文字/图标 |
primary-hover | #0a7db8 | #1296db | 实色主按钮渐变/hover 端点（或用bg-primary-background/90） |
primary-light | #d6ecfa | #1e3040 | 柔和品牌晕染 —— 图标背景、chip 填充 |
设计要点：
primary与primary-background是两种语义：前者用于文字/图标/边框等"线条式强调"，后者才是实色填充。写实色按钮时应该用bg-primary-background，而不是bg-primary；primary-hover提供实色填充的渐变/hover 端点；实际上 shadcn 的 Button 组件用透明度方案hover:bg-primary-background/90实现 hover（见上文按钮源码），两种方式都受支持；- 源码细节：当前 src/index.css 的
:root中--primary-background实际值为#2b92ed（#1296db与#0a7db8之间的中间蓝），与文档表格所载的#1296db存在细微出入——令牌值的唯一事实来源是 src/index.css，修改任何颜色都应改 CSS 而非文档。
四、次级 / 柔和 / 强调背景：同一个灰，三种语义
遵循 shadcn 惯例，
secondary/muted/accent在这里共用同一个灰色值——语义不同，填充色相同。
| Token / class | Light | Dark | Use |
|---|---|---|---|
secondary | #f0f0f0 | #2a2a2a | 次级按钮 / 填充 |
secondary-foreground | #1a1a1a | #e5e5e5 | secondary 上的文字 |
muted | #f0f0f0 | #2a2a2a | 柔和背景（分组填充、占位符） |
muted-foreground | #767676 | #8a8a8a | 弱化 / 描述性文字。已按 AA 调校（在card/background上 ≥ 4.5:1）—— 保留给次级/大号文字，不要用于密集正文 |
accent | #f0f0f0 | #2a2a2a | hover / 选中背景（菜单项等） |
accent-foreground | #1a1a1a | #e5e5e5 | accent 上的文字 |
无障碍要点：
muted-foreground的 light 值#767676是从旧的#888888（对比度仅 3.5:1，正文不达标）专门上调而来，使其在#ffffff/#fafafa背景上达到 WCAG AA 的 ≥4.5:1（src/index.css中的注释对此有明确说明）；- 正因如此，
muted-foreground只应承担描述性/次级文字角色，密集正文请使用foreground或fg-secondary； toggle.tsx的 hover 态正是hover:bg-muted hover:text-muted-foreground，选中态为data-[state=on]:bg-accent>背景/文字：bg-background text-foreground；卡片用bg-card，浮层用bg-popover，全部避免字面量；- 主按钮：
bg-primary-background text-primary-foreground hover:bg-primary-background/90；次按钮走secondary系； - 危险操作：
bg-destructive text-destructive-foreground，错误输入aria-invalid:border-destructive aria-invalid:ring-destructive/20； - 焦点环：统一
focus-visible:ring-ring/50； - 模态遮罩：
bg-overlay（禁bg-black/50）；分类标签：bg-label-<hue>-bg text-label-<hue>-fg（经getNameAvatarTone哈希）； - 状态图标：实色
success/warning；状态徽章：success-bg/success-fg、warning-bg/warning-fg、skill-bg/skill-fg； - 滚动容器：加
.scrollbar-custom； - 浮层层级：raised 用
shadow-md+rounded-lg，overlay 用shadow-lg+rounded-xl，不越shadow-lg； - 明暗双主题验证：任何改动都必须在 light 与 dark 下各检查一次（含
muted-foreground的 AA 对比度约束）。
遵循这套令牌体系，ScriptCat 的 UI 即可在保持品牌统一（蓝色#1296DB系、紫色skill系、8 色调分类标签）的同时，让明暗主题切换完全由 CSS 变量驱动，不需要任何 JavaScript 干预或组件级特判。
赞
- 前端
- 开发者工具
- 插件系统
【免费下载链接】scriptcat
ScriptCat, a browser extension that can execute userscript; 脚本猫，一个可以执行用户脚本的浏览器扩展
项目地址：https://gitcode.com/gh_mirrors/sc/scriptcat
相关推荐
AstroWind 样式系统实战指南：基于 Tailwind CSS v4 的主题令牌、暗色模式与 shadcn/ui 兼容层
AstroWind 样式系统实战指南：基于 Tailwind CSS v4 的主题令牌、暗色模式与 shadcn/ui 兼容层 AstroWind 的整套样式体
前端UI组件FAST focusStrokeInner 设计令牌完全指南：聚焦描边的内层色彩体系与实战用法
FAST focusStrokeInner 设计令牌完全指南：聚焦描边的内层色彩体系与实战用法 导读 本文聚焦 @microsoft/fast componen
前端UI组件Sure 设计令牌体系：以 W3C DTCG JSON 为单一事实源驱动 Tailwind v4 主题
Sure 设计令牌体系：以 W3C DTCG JSON 为单一事实源驱动 Tailwind v4 主题 Sure 是一个开源的个人财务管理应用（Ruby on
金融科技后端前端移动开发桌面应用AI 应用
上一篇：Agent 工具调用不踩坑：capsule-react 两阶段派发与过期结果过滤机制解析
下一篇：3个简单步骤：如何用FontCenter彻底告别AutoCAD字体缺失烦恼
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考