new-api 前端 shadcn/ui 主题定制实践：CSS 变量、Tailwind 令牌与组件三层管线

new-api 前端 shadcn/ui 主题定制实践CSS 变量、Tailwind 令牌与组件三层管线【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api本篇技术指南以 new-api 仓库中内置的 shadcn/ui 定制文档.agents/skills/shadcn-ui/vendor/shadcn/customization.md为核心骨架结合 web/components.json 与 web/src/styles/theme.css 等真实实现完整讲解「CSS 变量 → Tailwind 工具类 → 组件」的主题管线、OKLCH 颜色变量体系、暗色模式切换机制、CLI 预设切换命令以及组件定制与更新检查的推荐顺序。读完后你可以独立完成 new-api 控制台前端的换肤、新增语义色、调整圆角与组件变体等定制工作。主题管线CSS 变量 → Tailwind 工具类 → 组件shadcn/ui 的定制模型只有三层理解它是一切自定义操作的前提CSS 变量定义在:root亮色模式和.dark暗色模式选择器下Tailwind将这些变量映射为工具类bg-primary、text-muted-foreground等组件使用这些工具类 —— 修改一个变量所有引用它的组件随之变化。new-api 的前端web/正是这一模型的直接落地且是 Tailwind v4 项目web/package.json 中tailwindcss为^4.3.2。其入口样式 web/src/styles/index.css 顶部按序引入 Tailwind、动画库与 shadcn 令牌文件再引入项目自有的theme.css与theme-presets.cssimport tailwindcss; import tw-animate-css; import shadcn/tailwind.css; import ./theme.css; import ./theme-presets.css;其中 web/src/styles/theme.css 完成了「第 1 层到第 2 层」的关键映射先用custom-variant dark (:is(.dark *));声明 class 驱动的暗色变体再用theme inline块把每个语义变量注册为 Tailwind 颜色令牌custom-variant dark (:is(.dark *)); theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --color-primary: var(--primary); --color-primary-foreground: var(--primary-foreground); /* ... 其余全部语义色 */ }也就是说只要你在:root/.dark里改掉--primarybg-primary、text-primary等工具类在全站自动生效无需触碰任何组件代码。body的基础外观同样由令牌驱动web/src/styles/index.cssbody { apply bg-background text-foreground has-[div[data-variantinset]]:bg-sidebar min-h-svh w-full; }项目侧的 shadcn 配置由 web/components.json 声明关键字段如下style为base-novaRadix 之外的 Base UI 基础库 nova 风格、tailwind.css指向src/styles/index.css、cssVariables为true、tailwind.config为空字符串v4 项目无配置文件、iconLibrary为hugeicons、组件别名ui指向/components/ui。此外项目通过.agents/skills/shadcn-ui/下的技能文档SKILL.md向 AI 助手注入这套项目上下文并在web/目录下执行bunx shadcnlatest info --json获取框架、Tailwind 版本、别名与已安装组件等权威信息。颜色变量体系与 OKLCH 色彩格式shadcn 约定每一组颜色遵循name/name-foreground命名基础变量用于背景-foreground用于该背景之上的文字与图标。原始文档给出的完整变量表如下定制时须按此语义对齐变量用途--background/--foreground页面背景与默认文字--card/--card-foreground卡片表面--primary/--primary-foreground主按钮与主要操作--secondary/--secondary-foreground次要操作--muted/--muted-foreground弱化 / 禁用态--accent/--accent-foreground悬停与强调态--destructive/--destructive-foreground错误与危险操作--border默认边框色--input表单输入框边框--ring焦点环颜色--chart-1~--chart-5图表 / 数据可视化--sidebar-*侧边栏专用颜色--surface/--surface-foreground次级表面颜色统一采用OKLCH表示--primary: oklch(0.205 0 0)三个分量依次是明度0–1、色度0 表示灰色、色相0–360。OKLCH 在感知均匀性上优于 HSL调整明度时色相不会漂移非常适合做亮 / 暗两套主题。对照 new-api 的实现可以看到该约定被严格执行且有所扩展。web/src/styles/theme.css 的:root块中除标准语义色外还定义了项目扩展令牌--success、--warning、--info、--neutral各带-foreground以及表格、骨架屏系列令牌:root { --radius: 1rem; --background: oklch(1 0 0); --foreground: oklch(0.145 0 0); --primary: oklch(0.692 0.141 243.716); --primary-foreground: oklch(1 0 0); /* ... */ --success: oklch(0.596 0.145 163.225); --warning: oklch(0.681 0.162 75.834); --chart-1: oklch(0.72 0.18 250); /* ... 共 5 个 chart 色 */ }值得注意的是几处「用变量推导变量」的技巧强调色不是硬编码而是--accent: color-mix(in oklch, var(--primary) 12%, var(--background))暗色下比例为 20%表格色用color-mix从前景色按 1.5%~16% 不同比例混合而来——换主色时这些派生色会自动跟随这是定制主题时值得借鉴的手法。对应的.dark块theme.css为全部令牌重定义了一组「OpenAI 风格的炭黑画布」取值例如--background: oklch(0.235 0 0)、--primary: oklch(0.54 0.142 248.516)并给--border、--input使用了带透明度的写法oklch(1 0 0 / 10%)。暗色模式class 驱动的切换机制文档给出的标准姿势是在根元素上切换.darkclassNext.js 项目通常配合next-themesimport { ThemeProvider } from next-themes ThemeProvider attributeclass defaultThemesystem enableSystem {children} /ThemeProvidernew-api 的web/是基于 rsbuild 的 SPA 而非 Next.js因此从源码结构看它自行实现了同一套 class 机制web/src/context/theme-provider.tsx 导出自定义ThemeProvider与useThemeHook核心逻辑为——主题取值限于dark | light | system默认system用户选择写入 Cookie键名vite-ui-theme有效期 1 年system时通过window.matchMedia((prefers-color-scheme: dark))解析出实际主题applyTheme()在document.documentElement上移除light/dark再添加解析后的值并监听系统外观变化实时跟随theme-provider.tsx在 web/src/main.tsx 中包裹整个应用。这与theme.css首行的custom-variant dark (:is(.dark *));以及:root/.dark双变量块严格对应JS 侧只负责换 classCSS 侧只负责换变量二者通过dark:变体解耦。next-themes仍保留在依赖列表中但主路径上生效的是上述自实现 Provider。使用 shadcn CLI 切换主题预设文档提供了通过 CLI 一键换肤的完整命令集预设码来自官方主题站点。在 new-api 中应先进入前端根目录web/再执行与 SKILL.md 的约定一致可用bunx替代npx# 应用一个预设码 npx shadcnlatest apply --preset a2r6bw # 位置参数简写同样有效 npx shadcnlatest apply a2r6bw # 切换到命名预设并覆盖已有组件 npx shadcnlatest apply --preset nova # 保留现有组件不覆盖 npx shadcnlatest init --preset nova --force --no-reinstall # 使用自定义主题 URL npx shadcnlatest apply --preset https://ui.shadcn.com/init?baseradixstylenovathemeblue...另一条等价路径是直接编辑 CSS 变量由于components.json中tailwind.css指向src/styles/index.css而真正承载取值的是 web/src/styles/theme.css 的:root/.dark两块手工调整这两处的 OKLCH 数值即可实现不重跑 CLI 的换肤且能精确控制每个语义色new-api 已扩展的 success/warning/info 等令牌也在此维护。添加自定义颜色Tailwind v4 与 v3 两条路径文档给出的完整流程分三步切记不要为此新建 CSS 文件一切写入npx shadcnlatest info输出的tailwindCssFilenew-api 中即web/src/styles/index.css所引入的主题文件第 1 步在主题文件中定义变量亮暗两套/* 1. Define in the global CSS file. */ :root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.28 0.07 46); } .dark { --warning: oklch(0.41 0.11 46); --warning-foreground: oklch(0.99 0.02 95); }第 2 步Tailwind v4在theme inline中注册。new-api 正是这条路径——theme.css中已有现成范例--warning与--warning-foreground就是按文档模板注册后直接在组件里使用的/* 2a. Register with Tailwind v4 (theme inline). */ theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }第 2 步Tailwind v3 备选当shadcn info报告的tailwindVersion为v3时改为在tailwind.config.js的theme.extend.colors注册// 2b. Register with Tailwind v3 (tailwind.config.js). module.exports { theme: { extend: { colors: { warning: oklch(var(--warning) / alpha-value), warning-foreground: oklch(var(--warning-foreground) / alpha-value), }, }, }, }alpha-value占位符让bg-warning/50这类透明度写法可用。第 3 步在组件中使用工具类// 3. Use in components. div classNamebg-warning text-warning-foregroundWarning/divnew-api 的扩展令牌success/warning/info/neutral在注册后同样可以直接以bg-success、text-warning-foreground形式出现在任意组件中这正是「改变量即改全组件」管线的直接收益。全局圆角一个 --radius 撑起整套刻度文档指出--radius全局控制圆角组件从它派生取值rounded-lgvar(--radius)rounded-mdcalc(var(--radius) - 2px)一类关系。new-api 采用了「乘数派生」的更完整版本在 theme.css 中把一个基础值展开成整档刻度--radius-lg: var(--radius); /* 基准档:root 中 --radius: 1rem */ --radius-sm: calc(var(--radius) * 0.6); --radius-md: calc(var(--radius) * 0.8); --radius-xl: calc(var(--radius) * 1.4); --radius-2xl: calc(var(--radius) * 1.8); /* ... 直至 --radius-4xl: calc(var(--radius) * 2.6) */因此只改:root与.dark下的--radius一个值全站的 sm~4xl 圆角刻度会等比联动是低成本的整体风格调整点。组件定制的推荐顺序从 variants 到包装组件文档给出的定制手段按优先级排列配套的逐条正误示例见 rules/styling.md在 new-api 的web/src/components/ui/下均有对应实践1. 优先使用内置 variants—— 大多数外观需求已被组件的cvaclass-variance-authority变体覆盖web/src/components/ui/button.tsx 即以const buttonVariants cva(...)定义Button variantoutline sizesm Click /Button2. 通过className叠加 Tailwind 类—— 布局与一次性微调不需要改组件源码Card classNamemx-auto max-w-md.../Card3. 给组件源码新增 variant—— 当某外观会被反复使用时直接编辑components/ui/下的源文件在 cva 变体表中加一行例如// components/ui/button.tsx warning: bg-warning text-warning-foreground hover:bg-warning/90,这与前述自定义色流程天然衔接令牌先注册variant 再消费。4. 组合出包装组件—— 将 shadcn/ui 原始组件组合为更高层的业务组件文档给出的ConfirmDialog示例AlertDialog 系列包装title/description/onConfirm展示了标准写法export function ConfirmDialog({ title, description, onConfirm, children }) { return ( AlertDialog AlertDialogTrigger asChild{children}/AlertDialogTrigger AlertDialogContent AlertDialogHeader AlertDialogTitle{title}/AlertDialogTitle AlertDialogDescription{description}/AlertDialogDescription /AlertDialogHeader AlertDialogFooter AlertDialogCancelCancel/AlertDialogCancel AlertDialogAction onClick{onConfirm}Confirm/AlertDialogAction /AlertDialogFooter /AlertDialogContent /AlertDialog ) }四个层级应逐级递进能用 variant 解决就不加 className能用 className 解决就不改源码确需固化才下沉到组件内部或包装层。更新已安装组件--diff 与 --dry-run 检查组件会随 shadcn 上游演进升级前先预览变更。文档给出的命令为npx shadcnlatest add button --diff配合--dry-run与--diff可以在更新前精确预览影响面npx shadcnlatest add button --dry-run # 查看所有受影响文件 npx shadcnlatest add button --diff button.tsx # 查看单个文件的差异完整的智能合并smart merge工作流说明在 vendored 的官方参考文档 official-shadcn-ui-workflow.md 的 Updating Components 一节命令的完整参考见 cli.md。由于升级会重写web/src/components/ui/下的源文件若你曾按上文「新增 variant」步骤改过组件合并时需以--diff输出核对本地定制是否丢失。小结new-api 的 shadcn/ui 定制体系可归纳为一条单向管线在:root/.dark中改 OKLCH 变量 → 经theme inline映射为 Tailwind 颜色令牌 → 组件与dark:变体自动消费。配套机制上class 驱动的暗色模式由自定义 ThemeProvider 管理Cookie 持久化 matchMedia 跟随系统--radius单值驱动全站圆角刻度组件定制遵循「内置 variants → className → 新增 variant → 包装组件」的递进顺序组件升级用--diff/--dry-run预览。掌握这些即可在不破坏组件生态的前提下对 web/ 前端做完整的换肤与视觉定制。【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考