shadcn/ui 与 HeroUI v3 的 Design Tokens 详细对比：语义、状态、尺度与主题覆盖

shadcn/ui Theming · HeroUI Theming

HeroUI Colors：用户提供的入口 · Default Theme Variables · Shared Theme Utilities

AI 参与说明（Agent：Codex）：本文通过 Context7、官方文档和固定提交的公开 CSS 源码整理，比较 shadcn/ui 与 HeroUI v3 的主题变量、基础尺度和组件状态，并给出网站设计的实践建议。资料核验日期为 2026-10-22；项目是否够用及选型建议属于基于这些证据的工程判断。执行入口 Codex Desktop；本轮模型完整标识与 reasoning effort 未取得任务级运行记录。中文正文按项目 humanizer-zh 编辑。

两家都能用 Tailwind 和组件样式完成常见界面；最值得比较的是设计决定放在哪里，以及修改时能否通过一个主题入口统一传播。 HeroUI v3 将更多表单与状态暴露为全局变量；shadcn/ui 的主题模板集中定义语义颜色和根圆角，许多状态、尺寸与风格选择保存在组件 Recipe 中。

本文依次比较语义与配色、状态派生、视觉尺度、专用角色、组件消费和主题修改。各节先对齐同一用途，再解释默认实现及改动成本；完整变量清单用于检索，不用总数推算设计能力。

阅读入口：变量与 class 分层 · 完整主表 · 组件状态对照 · 主题修改与示例 · Tailwind 完整索引。

比较范围与术语

本文固定比较 shadcn/ui 的 Theming 模板与 Nova Recipe、HeroUI v3.2.6 的开源默认样式，以及两者使用的 Tailwind CSS 4.3.3 基础主题。HeroUI v2、Native、Pro 和项目自行扩展的变量不计入默认清单。官方其他主题的色值可以不同，不能把某套配色推广为所有主题的默认值。

shadcn 部分采用官方推荐的 CSS variables 模式；它也允许生成直接使用 Tailwind 调色板类的组件。后者不以本文这组语义变量实现主题切换，应另查项目实际生成的 Recipe。shadcn：Without CSS Variables

本次源码快照：

shadcn/ui 组件由项目持有，已有项目未必已经采用当前文档中的全部变量和 Recipe；比较结果不能直接当作升级后会自动发生的变化。

CSS 自定义属性是实现 Design Token 的一种方式。一个属性也可能只是别名、中间计算值或组件内部变量；反过来，某种视觉状态可以由 Recipe 计算，并不一定拥有独立变量。DTCG Format 2025.10描述了 token 的值、类型和引用方式，但不能据此认定这两个库已经实现完整的 DTCG 交换格式。该文档属于 Community Group Report，并非 W3C Standard。

先把三层分开

讨论覆盖范围时，需要分别检查：

1. 基础尺度：颜色原值、字号、间距、尺寸、阴影、断点等。两者都大量承接 Tailwind，不能把这一层只算给某一方。
2. 语义角色：品牌强调、弱化文字、浮层、表单、成功或危险等。这是默认 token 体系最值得直接比较的部分。
3. 组件 Recipe：按钮如何变大、输入框如何显示错误、按下时是否缩放。很多细节写在组件样式中，未提升为全局 token。

例如 gap-4 表示从间距尺度取值；“表单行间距统一用多少”是项目规则；“按钮内部的图标间距取哪一档”属于组件 Recipe。这三件事相关，但不能互相替代。

变量、Utility class 与组件类：职责和来源分开看

token 保存设计值，class 将样式应用到元素；Tailwind 生成的 class 可以消费 shadcn 或 HeroUI 定义的 token。 因此，“来自 Tailwind”与“使用组件库的主题值”可以同时成立。下面将名称的职责与提供者分开对齐，范围仍是本文固定的 Tailwind v4 与两家源码快照。

例如 shadcn 的 --primary 经 @theme inline 的 --color-primary 注册后，bg-primary 使用 background-color: var(--primary)；text-primary 则把同一颜色用于文字。一个颜色可以服务多个 CSS 属性，也就对应多个 Utility。普通 :root 中仅有 --primary 声明，并不会自动注册 bg-primary。Tailwind：Theme Variables、引用其他变量

class 也不总是读取某个命名 token：

Theme Variable 声明的是可用设计值；Tailwind 再根据源码检测到的完整类名等构建输入生成相应规则，并非每声明一个颜色就把全部属性、状态和断点组合输出。Arbitrary values 还允许直接表达主题之外的值。因此，变量可以按固定文件穷举，class 更适合列出语法与代表例子。Tailwind：Utility classes、状态与条件、源码检测

最后，组件不必经过某个 Utility 才能读取 token。这两条路径都成立：

@apply 在构建时展开声明，不会把 bg-primary 再加进 DOM 的 class 属性。HeroUI 的 button--primary 也不意味着元素必须带上 bg-accent。两家都能组合 Utility 与具名组件规则，差异在 Recipe 的组织和 token 的消费位置，不能简化成“shadcn 用 class，HeroUI 用 token”。shadcn Button、Nova CSS、HeroUI Button 类名映射、Button CSS

覆盖范围对照

按本文固定源码，shadcn 的主题模板直接声明 32 个不同名称，加上 7 个圆角尺度输出，共 39 项；HeroUI 的默认变量文件声明 89 个不同名称，加上 8 个圆角尺度、21 个缓动、3 个动画和 2 个层叠参数，共 123 项。 这里统计的是指定文件暴露的全局命名入口，其中同时包含语义角色、派生状态、尺度输出和行为参数；39 / 123 不能解释为同一层级的基础设计值数量，更不能据此推算能力比例。

shadcn 的 32 项可以直接复核：18 个通用 UI 颜色 + 5 个图表色 + 8 个侧栏色 + 1 个根圆角。:root 声明这 32 项，.dark 覆写其中 31 个颜色，圆角沿用根值。它们不是 32 个 Primitive Token；18 个通用 UI 颜色本身也已按用途命名。本文固定清单的数字不推广为所有官方主题或已有项目必须遵循的变量总数。

下面的主表逐项列出两家的默认全局主题名称；Tailwind 桥接映射和原生主题变量分别放在文末附录，不打断后续机制比较。颜色对应按用途排列；— 只表示固定主题文件中没有独立同类名称，不能按功能缺失计分。相关外观可能已经由 Tailwind 或组件 Recipe 实现，也可以由项目扩展。

• 主表保留语义变量和尺度输出；接入 Tailwind 的桥接别名单独列在附录映射表，不与同一角色重复计数。
• 比较边界是 shadcn 的默认 Theming scaffold，以及 HeroUI 的 default/variables.css、shared/theme.css、base/base.css。两者共用的 Tailwind 调色板、字号、间距和断点另列在附录原生主题表；可选 Typeset、HeroUI Pro 和组件内部局部变量不混入默认全局主题。
• 对应不等于无损替换：primary 对 accent、muted-foreground 对 muted、input 对 field-border 都要结合组件检查。radius 行写出根值倍数，具体像素与组件选档见后文。

主表含 139 行：shadcn 的 39 个主题名称、HeroUI 的 123 个主题名称均已逐项列出。桥接表再覆盖其余 31 / 69 个别名，两张表合起来对应源码中的 70 / 192 个不同声明名，遗漏为 0。

证据入口：shadcn 默认主题源码、HeroUI 默认变量、共享映射、base.css。

数量与去重口径

数量可以统计，但必须固定文件范围、去重口径与层次。shadcn scaffold 有 70 个不同声明名：模板直接声明的 32 项、7 个圆角尺度输出，以及 31 个颜色桥接别名；去掉最后一类，就是上面的 39 个主题名称。

HeroUI 三份文件合计有 192 个不同声明名。其中 69 个只是同一角色接入 Tailwind 的别名：64 个颜色、3 个阴影、1 个表单圆角和 1 个表单边框宽度；去掉它们，得到 123 个主题名称。89 个默认变量中已经包含 accent-hover、accent-soft 等派生结果，不能将 89 解释为与 shadcn 模板同层的独立基础输入。比如 field-background 映射为 color-field，surface-shadow 映射为 shadow-surface，名字并非总是原名直接加前缀。

同一语义值在 light、dark 中重复声明，只计一次。focus 引用 accent、link 引用 foreground 这类用途不同的角色则保留，因为它们允许独立覆盖。颜色派生、圆角倍数和缓动曲线也保留为可检索名称；因此 123 不是“123 个互不相关的设计决定”。

仅看颜色，shadcn 是 31 个语义角色，HeroUI 是 64 个映射颜色角色，另有 white、black、snow、eclipse 四个基础色值。HeroUI 较长的总清单还包含 21 个缓动名称及滚动条等参数；不必将这些都理解为业务界面必须逐项配置的内容。默认变量的存在也不等于效果已经全局启用，例如 scrollbar 参数仍需要相应 Utility 或组件实际使用。

名称相同，语义可能不同

跨库迁移时，最容易出错的是逐字替换。

映射表是迁移起点，不是两套体系的无损一一对应。依据分别见 shadcn Token Convention 与 HeroUI Colors。

配对命名也不保证颜色自动匹配。--primary-foreground 是另一项主题输入；修改 --primary，不会由 shadcn 自动计算出合适的文字色。某些角色在默认主题中数值相同，也应保留各自名称：今天 card 与 popover 都是白色，不表示未来必须同步更改。

这里有三个容易漏掉的细节：

• --link 默认引用 --foreground，并非一定使用品牌蓝；--focus 默认引用 --accent，仍可独立覆盖。
• --segment 是具体部件角色。它不能与 --surface-secondary 合并，也不能把所有选中态都推给它。
• success、warning 的 foreground 默认使用深色 eclipse，accent、danger 则使用浅色 snow。状态色上的文字不应统一写死为白色。

上述角色说明依据 HeroUI Colors 和固定版本默认变量。--scrollbar-*、阴影、尺寸和动画参数在后文另列，不混进颜色角色。

默认视觉有何区别：深浅模式不是同一种反转

下面以固定文档中的 shadcn neutral 示例和 HeroUI 默认主题比较。数字仅代表这两个快照的取值；命名相同、某些值相同，都不要求主题始终保持相同外观。

shadcn 的 secondary、muted、accent 在此示例中都为 light oklch(0.97 0 0)、dark oklch(0.269 0 0)；secondary-foreground 与 accent-foreground 则为 light oklch(0.205 0 0)、dark oklch(0.985 0 0)。这些数值重合不应消除角色边界。HeroUI 的 surface-secondary、surface-tertiary 也是独立赋值的表面，不是从 surface 自动计算的一切层次。

证据：shadcn 固定主题、HeroUI 默认变量、Nova Input Recipe。

状态色怎样派生：透明度、混色和文字色是三件事

同一个 hover 需求，两家可以使用不同的计算规则和覆盖入口。先看并排关系，再核对 HeroUI 派生公式中的具体权重。

在本次 Nova 样式中，默认 Button 使用 bg-primary，hover 使用 bg-primary/80。Tailwind 将后者编译为 primary 与 transparent 的混合；它与 HeroUI 将 accent 混向 accent-foreground 的规则不同。把相同的蓝色分别填进两边，不会得到相同的 hover。

如果要把主按钮 hover 单独改成固定颜色，HeroUI 可以覆盖 --accent-hover；Nova 则没有默认的 --primary-hover 入口，需要修改 Button 的 hover Recipe，或者新增项目 token 并让 Recipe 引用。反过来，shadcn 把规则保存在项目源码里，组件某个特殊变体需要完全不同的状态时，可以直接修改它。两种方式的差别是统一变化的控制点放在哪里。Nova 样式

派生公式与深浅模式

以下取自同一份默认变量，A 表示 --accent，AF 表示 --accent-foreground，F 表示 --foreground；表内写法用于解释权重，不是可直接复制的 CSS。

success、warning、danger 的 soft 角色遵循类似结构，但不能假定比例完全一样。例如 light 的 warning-soft-foreground 使用 80% warning 与 70% foreground；danger 的 soft 背景在 dark 下仍是 15%，并非所有状态都沿用 accent 的 12%。需要精确复刻时应读对应公式，不能根据名字推算。默认变量源码、CSS Color 5：混色比例归一化

默认还有可选的 data-vibrant-palette="true" 分支，会将四组彩色 soft foreground 改为 92% 状态色与 8% foreground 的混色。它改变的是轻色背景上的文字表达，不是把整套主题所有颜色都增强饱和度；其选择器同时匹配 light/dark 标记，局部使用也要核对所在元素。对应实现

Derived colors do not guarantee accessible contrast. A token pair must be checked in the context where the component actually renders. 半透明 soft 背景、disabled opacity、文字大小和真实承载背景都参与结果；除了颜色，还要检查键盘、标签和状态说明。WCAG 2.2

圆角、边框、阴影与密度：相同类名并非相同尺度

圆角公式逐档对照

本次 shadcn Theming 的根值是 --radius: 0.625rem，HeroUI 是 --radius: 0.5rem。以下像素值假设根字号 16px；这是尺度比较，不是某个组件最终一定使用的半径。

旧 shadcn 教程里常见 radius - 4px、radius - 2px 的公式，与本文快照不同。已有项目需要查自己的 CSS，不能把当前文档公式当作已安装组件的事实。shadcn 固定主题、HeroUI 半径映射

组件仍会选择档位或限制上限：Nova 默认 Button 与 Input 都用 radius-lg，HeroUI Button 用 rounded-3xl，Input 用 rounded-field；HeroUI Card 还使用 min(32px, var(--radius-3xl))。因此，将两边 --radius 都设成 8px，不会让按钮、卡片和输入框获得相同圆角。需要比较的是 根值 × 尺度公式 × Recipe 选择。Nova、HeroUI Card

其他全局参数分别能做什么

这些是可控范围，不是所有参数都会随意传播到所有元素。例如 HeroUI Button 的 100ms 背景过渡和 250ms transform 仍写在组件里，改 easing 不会自动统一 duration。把 spacing 从 0.25rem 改成 0.2rem，也无法同比缩小那些直接写为 rem、px 或最小命中范围的值。HeroUI 默认变量、共享映射、状态 Utilities、base.css

排版、间距和动效到底算不算“有”

两者都有能力完成排版、留白、阴影与动效，区别是这些决策放在哪里。

shadcn 的核心主题清单没有把所有字号、间距、时长抽成网站级语义角色，但 Tailwind 尺度与组件 Recipe 已经在使用这些值。当前 shadcn/typeset 还提供独立的内容排版体系：body、heading、mono 字体，以及 size、leading、flow 三个主要阅读节奏控制点。它适合文档、文章、聊天内容，不能把 shadcn 概括成“没有排版体系”。

HeroUI 这两个主题文件也没有独立的 --font-*、--text-* 全套正文角色。它的主题页虽然把 typography 列入广义基础变量，但核对具体实现后，应将这里的能力归于 Tailwind 与组件 Recipe；不要据此推导出一个已经配置好的 display、heading、body、caption 产品排版规范。

图表与侧栏：专用角色及扩展方式

chart-1 至 chart-5 能让数据系列颜色跟随主题，图表配置引用它们后，深浅模式只需调整相应值。不过系列名、legend、单位、正负、阈值与顺序色阶仍属于图表设计。ChartConfig 还能为某个系列直接提供 color，或提供 light/dark 两个值；ChartStyle 将这些颜色写成局部 --color-系列名。因此默认五色既不是系列上限，也不是只能画五种数据。Chart 文档

sidebar 分组的价值在于隔离导航区域。正文 primary 改了，sidebar-primary 可以保持原值；sidebar-accent 则服务菜单的 hover/active 等强调。它不等于给 Card 增加第二档 surface，也不能与 chart 系列共用一套命名。HeroUI 核心主题没有这两组入口，需要项目按实际需求增加并让自建图表、侧栏消费。Sidebar 文档

token 怎样真正影响组件

前面的表比较命名与计算；这里沿着同一个控件追踪这些值怎样进入最终样式。shadcn 栏固定为 Nova，HeroUI 栏固定为 v3.2.6 默认样式。

HeroUI 当前没有统一的全局 *-pressed 颜色家族；Button 的局部变量不能泛化为所有组件共享的稳定契约。Nova 的 destructive Badge 也会用同一危险色组合轻色背景、hover 与 focus ring，说明状态外观可以在 Recipe 内表达。源码入口：Nova Recipe、HeroUI Button。

同一个 Button：逐个状态对照

以下 shadcn 栏固定为 Nova style；它不是所有历史 shadcn Button 的共同实现。HeroUI 栏固定为 v3.2.6 默认 Button。

hover:bg-primary/80 只改变背景的 alpha；disabled:opacity-50 会同时淡化整个按钮及其文字、图标。两者不能互换。Nova 的 ghost hover 还直接使用 muted，说明 Theming 的角色解释与某个 style 的实际选择需要分别检查。Nova Recipe、shadcn 基础 Button、HeroUI Button、HeroUI 状态 Utilities

因此，若需求是“所有可点击控件的 hover 都使用同一种算法”，还要检查哪些 Recipe 真正消费这组变量。HeroUI 有更多集中入口，也不是一个 token 能覆盖全部组件：outline Button 就有自己的 default 混色规则。

同一个 Input：逐个状态对照

field-border 默认 transparent，且边框宽度是 0px，所以仅修改边框颜色不一定能看见边框。要在全局给 HeroUI 输入控件加 1px 边框，应在根主题同时设置 --field-border-width: 1px 与 --field-border，再检查 hover/focus。与此相对，修改 shadcn 的 --input 是在改变输入边界角色；它并不是统一的输入背景开关。

映射中的 var(--field-border, var(--border)) 也不表示两个颜色叠加：field-border 已经存在且值为 transparent 时，就不会采用 border 的 fallback。同理，0px 是有效宽度，不会因为没有可见边框就自动退回通用的 1px。

HeroUI 的 field 系列也不会约束每个变体：上表的 secondary Input 改走 default 系列，是明确的 Recipe 选择。想让“所有表单都统一换一种背景”，必须先确定实际用了哪些 variants。shadcn Input、Nova 样式、HeroUI Input

主题修改：接入方式、覆盖范围与扩展成本

先比较共同的 Tailwind 接入，再比较相同修改需求在两家分别要改哪里；最后使用双份示例验证接线。

token 如何接入 Tailwind：两家共享机制，维护边界不同

在 Tailwind v4 中，运行时语义变量与 Utility 的主题名称是两层：

HeroUI 有一个容易按名字猜错的入口：--color-field 映射到 --field-background，因此对应的是 bg-field，不是自动生成 bg-field-background。阴影则是 --shadow-field → --field-shadow，生成 shadow-field。注册名与被引用的语义变量不必同名。HeroUI 共享映射

下面是两套体系机制相同的地方；这是说明映射的片段，分别放在各自已配置的主题文件里：

/* shadcn 项目 */
@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

/* HeroUI 已经提供此映射，此处仅展示对应关系。 */
@theme inline {
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
}

inline 让生成的 Utility 使用被引用的值，例如 background-color: var(--primary)，从而在消费元素的作用域中读取 primary。它不是把主题编译成固定颜色：运行时修改变量仍会影响组件。当前这些颜色值是完整的 oklch(...) 等 CSS color；不要照搬旧版 HSL 片段再套一层 hsl(var(--primary))。shadcn Theming、Tailwind：引用其他变量

主题覆盖的实际边界：全局、局部与组件级

全局换色与局部换色不是同一个 CSS 问题

全局主题切换时，两者都可以保留 Recipe，只改变语义值。HeroUI 默认 CSS 匹配 .light、.dark 及对应 data-theme；shadcn 常用 .dark 覆写。CSS 本身不会替应用保存用户偏好、处理系统模式或避免首屏闪烁，这些属于主题切换集成。HeroUI Theming

覆盖还受 cascade layer 影响。HeroUI 将默认样式组织在 theme、base、components、utilities 等层中；本文的全局覆盖示例放在 imports 后的普通 CSS 中。对于同一元素上匹配的普通声明，未分层声明优先于分层声明。因此只在未分层 :root 写 light 主色，可能同时压过包内根元素的 dark 默认值；应像示例那样补上对应 dark 覆盖。若把覆盖放回 layer，则要同时核对层顺序、选择器与源码顺序，不能只看“写在后面”。HeroUI CSS 层入口

局部主题还有一条关键限制：CSS custom properties containing references are resolved where they are declared; inheriting the result does not re-run the expression against a child’s overrides. 例如根部定义了 --accent-hover: color-mix(... var(--accent) ...)，子区域只覆盖 accent，它可能仍继承根部已经计算的 hover。@theme inline 解决 Utility 的引用入口，不会重新计算任意祖先层的派生变量。

若在现有 HeroUI 项目中增加一个局部品牌区域，下面这段应追加在样式导入之后；normal 与 hover 同时在区域内声明：

.brand-zone {
  --accent: oklch(0.55 0.18 260);
  --accent-foreground: oklch(0.99 0 0);
  --accent-hover: color-mix(
    in oklab, var(--accent) 90%, var(--accent-foreground) 10%
  );
}

这只覆盖 primary Button 所需的三项。如果区域内还用 accent-soft、focus 等派生角色，也应在该区域重声明相应依赖，或采用完整自定义主题；不能把这个片段称为完整品牌主题。CSS Variables：computed value 与继承、Tailwind inline 的适用范围

中间别名也要检查：当前 HeroUI Input 的 border-width 直接读取 --border-width-field，该别名再引用 field-border-width。在控件自身仅覆盖 --field-border-width，可能仍然继承根部已解析的别名；局部修改时应同时在该作用域重声明 --border-width-field: var(--field-border-width)。根主题上的全局覆盖可以正常传播。Input 源码、映射源码

shadcn 的 primary/80 通常直接在消费处引用 primary，没有额外的祖先 primary-hover 计算链。但只覆写颜色也不能隔离 .dark：外层 dark 仍可能让内层组件的 dark:* Recipe 命中。局部 light 区域、主题预览卡片和多品牌混排，需要同时核对变量作用域与 mode 选择器。

浮层还可能通过 Portal 挂到局部区域之外。若浮层 DOM 没有位于 .brand-zone 内，它不会因为触发按钮在里面就自动继承局部 token；应检查最终 DOM，并按组件能力将主题作用于实际浮层容器。这是 CSS 继承和组件挂载位置共同带来的工程约束。

覆盖 token、修改 Recipe，分别应该在什么时候用

HeroUI 的 --button-bg 等局部变量说明了当前 Recipe 的实现，但不应当成与 accent 同等级、保证长期稳定的公共契约。shadcn 的源码可直接修改，也意味着新增 token 后必须自己保证组件继续消费它：只声明 --primary-hover，不会自动替换已有 hover:bg-primary/80。

同一需求的双份扩展示例

目标是“品牌按钮有独立 hover，成功提示能随主题切换”。下面两段分别追加到已有 shadcn/Tailwind v4 项目和已有 HeroUI v3/Tailwind v4 项目的全局 CSS，不能把两段整体叠进同一项目。它们演示 token 与 Utility 的接线，不是两家 Button 的源码副本。

shadcn：新增变量并接入 Recipe

:root {
  --primary: oklch(0.55 0.18 260);
  --primary-foreground: oklch(0.99 0 0);
  /* 以下三项是本例的项目扩展。 */
  --primary-hover: oklch(0.48 0.17 260);
  --success: oklch(0.35 0.08 150);
  --success-foreground: oklch(0.99 0 0);
}

.dark {
  --primary: oklch(0.76 0.12 260);
  --primary-foreground: oklch(0.18 0.02 260);
  --primary-hover: oklch(0.82 0.10 260);
  --success: oklch(0.80 0.12 150);
  --success-foreground: oklch(0.18 0.02 150);
}

@theme inline {
  --color-primary-hover: var(--primary-hover);
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
}

.token-primary {
  @apply bg-primary text-primary-foreground hover:bg-primary-hover;
}

.token-success {
  @apply bg-success text-success-foreground;
}

这里的 .token-primary 是一个独立教学类。实际 shadcn Button 应将原 hover 类改为 hover:bg-primary-hover，再检查 className 合并规则；不要只增加变量就预期 Button 自动变化。

HeroUI：覆盖已有变量与派生结果

:root,
[data-theme="light"] {
  --accent: oklch(0.55 0.18 260);
  --accent-foreground: oklch(0.99 0 0);
  --accent-hover: oklch(0.48 0.17 260);
  --success: oklch(0.35 0.08 150);
  --success-foreground: oklch(0.99 0 0);
}

.dark,
[data-theme="dark"] {
  --accent: oklch(0.76 0.12 260);
  --accent-foreground: oklch(0.18 0.02 260);
  --accent-hover: oklch(0.82 0.10 260);
  --success: oklch(0.80 0.12 150);
  --success-foreground: oklch(0.18 0.02 150);
}

.token-primary {
  @apply bg-accent text-accent-foreground hover:bg-accent-hover;
}

.token-success {
  @apply bg-success text-success-foreground;
}

HeroUI 已经注册 accent-hover 与 success 系列的 Utility，不必再写一遍 @theme inline。已有 primary Button 也已消费 accent-hover；本例仍使用独立教学类，以便与 shadcn 检查相同的 HTML：

<button class="token-primary" type="button">保存更改</button>
<p class="token-success" role="status">已保存</p>

在独立页面中分别测试：light 下按钮背景为 oklch(0.55 0.18 260)，hover 为 oklch(0.48 0.17 260)；根元素增加 dark 后，分别变为 oklch(0.76 0.12 260) 与 oklch(0.82 0.10 260)。成功提示应切换为各自的 success/foreground 配对。此例只对照颜色与消费链，实际按钮仍须具备合适的尺寸与 focus indicator。

本轮以 Tailwind 4.3.3、HeroUI styles 3.2.6 编译上述两份扩展，并在 Chromium 中核对了两种模式的 normal、hover 与 success 配对，计算样式符合这些值。同时验证了局部 accent 覆盖的继承差异，以及全局 field 边框从 0px 改为 1px 的结果。

一般项目够不够用

以常规组件和深浅色主题为起点，两者通常都够。 这是一项工程判断，前提是允许团队添加少量项目角色与页面规则，而不是要求每项设计决定都必须在库的默认清单中找到同名 token。

如果已经采用 HeroUI，并且喜欢其组件视觉，不值得仅因 shadcn 有 chart 或 sidebar 命名就迁移。给项目补这两类角色通常更直接。反过来，已有 shadcn 项目只缺 success、warning，也通常可以扩展现有主题，不必更换组件库。

如果几乎每个组件都需要覆盖圆角、间距、状态和阴影，应重新评估默认 Recipe 是否符合项目。默认 token 少，不自动意味着工作多；默认变量多，也不能弥补视觉方向不匹配。

用三个真实页面验证“够用”

选一页信息展示、一页复杂表单、一页列表或数据页，使用真实中文、长标题、长数字与真实状态：

1. 定义页面所需的角色，记录默认已有、可复用和需要新增的项目项。
2. 同时检查深浅色；逐项看文字层级、表面、边框、焦点、hover、invalid、disabled、pending、成功与失败反馈。
3. 把重复覆盖写进项目 Recipe 或 Semantic Token。只出现一次的装饰不必立即提升为全局契约。
4. 改一次主强调色与基础圆角，确认预期组件响应；另改一次表单外观或图表色，确认没有误伤无关角色。
5. 检查完整任务路径：键盘可操作，错误可理解，浮层不遮挡关键操作，长内容仍可读。

通过标准是关键页面能复用同一组规则、缺口可解释且集中、主题修改能传播到预期位置。不要凭变量数量估算“覆盖 90%”；没有项目需求清单就不存在可核查的覆盖率。

附录：Tailwind 变量索引与补充示例

这里保留完整映射与基础主题清单，供查名和排错。理解两家机制时，可以先沿正文比较顺序阅读，需要查具体名称时再回到本节。

Tailwind 桥接变量对照

这些变量由两家主题注册进 Tailwind；它们不是 Tailwind 默认调色板自带的颜色。表内箭头表示“桥接名称 → 主表里的语义变量”，不是两个独立设计值。这张表仍列变量名称，bg-primary、bg-accent 等消费类见前文变量与 class 分层，不与变量混计。

其中 --color-field 指向 --field-background；--shadow-surface 指向 --surface-shadow，不是机械地在原名之前加 color 或 shadow。field 的部分映射还带有 default、foreground、muted、border 等 fallback，精确表达式以共享主题源码为准。

Tailwind 原生主题变量完整清单

本表固定为 Tailwind CSS 4.3.3 的 theme.css，共 413 个当前声明名 + 6 个 Deprecated 名称 = 419 个。其中 26 个色族各 11 档，再加黑白两项，共 288 个颜色；其余是字体、尺寸、阴影、动效等基础尺度。为便于查找，每个色族和相关尺度合并一行，但每一个实际声明名都明确写出。

下表是两家叠加主题之前的 Tailwind 基础清单。相同名称可以被库或项目覆写，因此不能把 419 直接加到 39 或 123 上，也不能据此认定两家的最终默认值都相同。

例如 Tailwind 的 Deprecated --radius 是 0.25rem，但两家都有同名的普通根圆角变量；应以项目实际层叠后的值为准，不能把兼容值当成两家组件的最终圆角。编译器生成的 --tw-shadow、--tw-ring-shadow 等组合样式变量也不属于 theme.css 的默认主题清单。

Theme variables define which design values are exposed to Tailwind utilities. They are distinct from the internal custom properties that utilities use to compose CSS. Tailwind Theme Variables、4.3.3 默认主题源码

一个最小扩展例子：库负责组件颜色，项目负责页面规则

下面可加入一个已经配置 HeroUI v3 与 Tailwind v4 的 React 项目。它演示主题 token 也能服务自建 HTML，以及项目如何补充内容宽度和 section 间距；不是完整的项目脚手架。

app.css：

@import "tailwindcss";
@import "@heroui/styles";

:root {
  --accent: oklch(0.55 0.18 260);
  --accent-foreground: oklch(0.99 0 0);
  --radius: 0.625rem;

  /* 项目自定义的页面角色，不属于 HeroUI 默认清单。 */
  --site-content-max: 72rem;
  --site-reading-max: 68ch;
  --site-section-gap: clamp(2rem, 5vw, 5rem);
}

.dark,
[data-theme="dark"] {
  --accent: oklch(0.76 0.12 260);
  --accent-foreground: oklch(0.18 0.02 260);
}

.site-shell {
  width: min(calc(100% - 2rem), var(--site-content-max));
  margin-inline: auto;
  padding-block: var(--site-section-gap);
}

.reading-copy {
  max-width: var(--site-reading-max);
}

App.tsx：

import "./app.css";

export default function App() {
  return (
    <main className="min-h-screen bg-background text-foreground">
      <section className="site-shell">
        <div className="rounded-xl bg-surface p-6 shadow-surface">
          <h1 className="text-2xl font-semibold">项目概览</h1>
          <p className="reading-copy mt-3 text-muted">
            组件颜色来自 HeroUI，正文宽度和页面节奏由项目定义。
          </p>
          <a
            href="#details"
            className="mt-5 inline-flex rounded-lg bg-accent px-4 py-2
              text-accent-foreground hover:bg-accent-hover
              focus-visible:outline-2 focus-visible:outline-offset-2
              focus-visible:outline-focus"
          >
            阅读详情
          </a>
        </div>
        <section id="details" className="reading-copy mt-8">
          <h2 className="text-xl font-semibold">设计范围</h2>
          <p className="mt-3">内容层级、布局和交互规则仍需项目决定。</p>
        </section>
      </section>
    </main>
  );
}

在文档核验时，上述 CSS 使用 @heroui/styles 3.2.6、Tailwind 4.3.3 编译，关键 Utility 与项目规则均生成；React 示例可渲染为 HTML。将根元素切到 class="dark" 可使用深色分支。这个例子检验主题接入与样式生成，实际产品仍应按自己的文字尺寸和承载背景检查对比度。

使用 shadcn 时也可以沿用这些项目页面角色；主行动换用 primary、正文弱化色换用 muted-foreground，卡片换用 card，再按项目 Recipe 处理阴影与状态。不要将两个库的整套全局 CSS 叠在一起解决映射问题：共享变量和 Utility 名称可能冲突，若确需共存，应明确主题归属、作用域和组件适配边界。

关联阅读

除了 token，一个网站还要设计什么

信息架构、字体、布局、内容、交互恢复与交付流程另见网站 UI 设计实践：从内容结构到交互验收。该文包含设计方法、案例、验收条件与资料选读路线；这里集中比较两家的 token 与组件样式机制。

• 网站 UI 实现：布局、层叠与交互状态：CSS 机制、完整实验与历史实测结果。
• Frontend 主题导航
• Base UI 与 React Aria：底层机制、现代 API 与 HeroUI 样式复用：进一步区分外观、组件组合和底层交互职责。

参考资料

• shadcn/ui Theming、Typeset
• shadcn/ui 固定版本主题文档、Nova 样式
• HeroUI Theming、Colors
• HeroUI 固定版本默认变量、共享映射
• HeroUI Button、Input、状态 Utilities：核对 token 的实际消费与例外。
• shadcn Chart、Sidebar：专用角色与局部配置。
• Tailwind 4.3.3 默认 theme.css：原生主题变量清单与 Deprecated 区域。
• Tailwind Utility classes、状态与条件、源码检测：核对 class 的生成、组合与任意值边界。
• Tailwind Theme Variables、CSS Variables、CSS Color 5 混色规则：区分映射、继承与派生公式。
• DTCG Format 2025.10、WCAG 2.2