tailwind-semantic-theme

用途

Tailwind Semantic Theme 用于在 Tailwind v4 项目中搭建或重构主题体系，采用 shadcn 的语义化主题契约，但不把 shadcn 作为依赖引入。它保留 shadcn 的令牌名称与 CSS 结构，同时根据当前项目的实际情况调整文件布局。

该技能仅在明确点名调用，或用户明确要求采用此方法论时使用。目标项目为 Tailwind v4。它优先提供方法论；如果用户要求实现，则把方法论转化为对现有项目的具体修改。不要为了获得这套模式而额外添加 shadcn。

主要能力

将主题值一次性定义为语义 CSS 变量。
通过 :root 与 .dark 让浅色和深色模式共用同一套令牌名。
通过 @theme inline 把这些令牌暴露给 Tailwind。
保留 shadcn 兼容的令牌名称，便于未来接入组件。
优先使用 OKLCH 颜色值。

使用方式

工作流程

检查当前样式边界：找到全局样式表、Tailwind 入口和暗色模式切换逻辑；检查项目是否已使用 CSS 变量、@theme 或不同的暗色模式选择器。尽可能复用现有的全局 CSS 文件，不要创建与之竞争的主题层。
判断用户需要的是指导还是修改：对于仅需方法论的情况，说明结构、提供脚手架并给出迁移指导；对于实现请求，更新现有全局 CSS，并接通 .dark 类契约所需的暗色模式接线。
建立令牌契约，使用完整令牌集：background、foreground；card、card-foreground；popover、popover-foreground；primary、primary-foreground；secondary、secondary-foreground；muted、muted-foreground；accent、accent-foreground；destructive、destructive-foreground；border、input、ring；chart-1 至 chart-5；sidebar、sidebar-foreground；sidebar-primary、sidebar-primary-foreground；sidebar-accent、sidebar-accent-foreground；sidebar-border、sidebar-ring；radius。保持 name / name-foreground 成对，以兼容表面与文本；原始颜色值保留在 CSS 变量中，而不是写在组件类名里。
按以下顺序组织 CSS：@import "tailwindcss"；@custom-variant dark (&:is(.dark *))；@theme inline { ... } 将语义变量映射到 Tailwind 令牌；:root { ... } 浅色值；.dark { ... } 深色值；@layer base { ... } 仅用于少量重置，例如 body/背景/文本以及共享的 border/ring 默认值。
保持暗色模式简单：遵循 shadcn 默认做法，通过 .dark 实现基于类的暗色模式；当令牌覆盖已足够时，不要在组件类中重复暗色样式；除非用户要求，不要自行发明自动生成暗色值的机制，浅色与深色值应显式编写。
保持组件语义化：优先使用 bg-background text-foreground、bg-card text-card-foreground、bg-primary text-primary-foreground 等语义工具类；如果 bg-zinc-900 或 text-slate-500 这类原始调色板类在应用中反复出现，应将其提升为语义令牌；当真实角色是语义时，避免用 slate、blue、gray 等调色板族来命名令牌。
增量迁移：从全局令牌脚手架开始；先映射复用最多的表面与操作；在改动的文件中用语义类替换重复的原始颜色工具类；除非一次性装饰色正在成为可复用的设计原语，否则不要把它们搅进令牌系统。

输出

对于仅需方法论的情况，提供：要修改的目标文件；推荐的 Tailwind v4 脚手架；令牌契约及其存在原因；现有类的迁移顺序；.dark 所需的暗色模式接线。

对于实现请求，还需：编辑现有样式表，而不是引入并行主题文件；保留项目特有的导入与布局；总结在标准契约之外新增的令牌。

参考脚手架

需要具体起点时，可阅读 references/tailwind-v4-theme-scaffold.css，并将其适配到项目现有 CSS 文件，而不是盲目复制。

适用场景

在 Tailwind v4 应用中搭建 shadcn 风格主题变量，但不安装 shadcn。
把原始 Tailwind 颜色重构为带 .dark 模式的语义令牌。
查看 OKLCH 令牌、@theme inline 与 shadcn 兼容命名的正确 globals.css 结构。

限制

仅在明确点名该技能或用户明确要求此方法论时使用。
目标为 Tailwind v4 项目。
除非用户明确要求，不要添加 shadcn 作为依赖。
当全局 CSS 中的 @theme inline 更合适时，不要使用 Tailwind 配置主题颜色。
除非用户明确想要迁移，不要在现有主题系统旁再建第二套主题系统。
当语义令牌能表达相同意图时，不要把浅色和深色调色板类硬编码进组件。
如果未来 shadcn 风格兼容性重要，不要仅为匹配本地偏好而重命名标准令牌。