主题与样式
自定义 TanStack 模板的 Tailwind CSS v4 token、深色模式与 shadcn/ui。
模板使用 Tailwind CSS v4、语义 CSS 变量、next-themes 与 shadcn/ui。虽然包名
带有 next，next-themes 在这里作为通用 React 主题控制器使用；应用本身仍是
TanStack Start。
样式栈
| 文件 | 作用 |
|---|---|
vite.config.ts | 注册 @tailwindcss/vite |
src/styles.css | Tailwind import、深色 variant、设计 token、Fumadocs 映射、排版、动画与布局工具 |
src/components/theme-provider.tsx | 配置 next-themes class 模式、系统默认值与 theme storage key |
src/routes/__root.tsx | 执行 hydration 前主题脚本并挂载 ThemeProvider |
src/components/common/ThemeToggle.tsx | 营销 UI 中的主题控制 |
components.json | shadcn 风格、alias、图标库与 CSS 入口 |
src/lib/utils.ts | cn() class 合并函数 |
Tailwind 以 Vite 插件运行，默认设置没有 Tailwind 配置文件。src/styles.css 导入
Tailwind，并通过 @theme inline 暴露语义 token。
语义颜色
组件使用 bg-background、text-foreground、bg-card、
text-muted-foreground、border-border 与 ring-ring 等角色，对应变量位于
:root 和 .dark。
:root {
--background: #f8fafc;
--foreground: #0f172a;
--primary: #3b76f6;
--border: #e2e8f0;
}
.dark {
--background: #090807;
--foreground: #f8fafc;
--primary: #3b76f6;
}优先修改 token，不要逐个替换组件中的语义 utility。src/styles.css 还把
Fumadocs 的 --color-fd-* 映射到同一套系统，使文档与应用界面保持一致。
components.json 选择 shadcn new-york 风格、Zinc 基础色和 CSS 变量。当前
stylesheet 又进一步定制为 slate 表面、品牌蓝与偏暖的深色背景，因此可见主题应
以语义变量为准。
无闪烁深色模式
ThemeProvider 把 light、dark 或 system 存在 theme key 下，并将解析后的
light/dark class 应用到 <html>。__root.tsx 的 inline 脚本会在 React
hydration 之前读取该值、解析系统偏好、设置 colorScheme，并把原始偏好写入
data-theme。
根 <html> 使用 suppressHydrationWarning，因为脚本可能在 React 接管前改变
class。Fumadocs 自身的主题控制已关闭，因此全站只有一个主题 owner。
Inline 脚本与 ThemeProvider 的 storage key、可接受值、默认主题、class 属性和
系统行为必须保持一致，否则会出现闪烁或 hydration warning。
添加 shadcn 组件
项目不是 RSC 应用（"rsc": false）。shadcn alias 指向 #/components、
#/components/ui、#/lib 与 #/hooks。
pnpm dlx shadcn@latest add alert-dialog检查生成的 import，把复用 primitive 放在 src/components/ui。功能 UI 放进
auth、home、dashboard、layout、ai 等领域目录，动画放进 motion。
条件 utility 与冲突合并使用 cn()：
import { cn } from "#/lib/utils"
<div className={cn("rounded-lg border", active && "border-primary")} />代码风格
Biome 用 tab 与双引号格式化 TypeScript/TSX；生成的
src/routeTree.gen.ts 与手工维护的 stylesheet 不在常规格式化范围。新代码和
配置示例应沿用 tab 缩进与 #/* alias。
验证主题修改
- 明暗模式的文字、表面、边框、输入框、焦点环、图表和危险状态均满足对比要求。
- 刷新后
light、dark、system都能恢复，且没有明显闪烁。 - 控制台没有主题 class 导致的 hydration warning。
- Fumadocs 页面与营销、dashboard 页面使用同一品牌 token。
- 新 shadcn 组件使用语义颜色，键盘与焦点状态正常。
- 生成组件后
pnpm check与pnpm build通过。