主题与样式
Nuxt 模板中的 Tailwind、配色模式与 shadcn-vue 样式。
模板的视觉系统由 Tailwind CSS v4、CSS 变量设计令牌、shadcn-vue、Nuxt Color Mode、Nuxt Icon 与 Nuxt Image 组成。
重要文件
| 文件 | 作用 |
|---|---|
app/assets/css/tailwind.css | Tailwind 导入、设计令牌、明暗变量与字体 |
nuxt.config.ts | 全局 CSS、Tailwind Vite 插件、配色、图标、图片与 shadcn |
components.json | shadcn-vue 风格、别名、基础色与 CSS 路径 |
app/lib/utils.ts | cn() class 合并函数 |
app/components/common/ThemeToggle.vue | 基于 useColorMode() 的明暗切换 |
app/assets/icons/ | 自定义 my-icons 图标集合 |
Tailwind CSS v4 与设计令牌
@tailwindcss/vite 作为 Vite 插件注册，app/assets/css/tailwind.css 则通过
Nuxt 的 css 选项加载。该文件导入 Tailwind 与 tw-animate-css，定义基于
class 的暗色变体，并把 background、primary、muted、border 等语义
令牌映射到 CSS 变量。
换品牌时优先修改 :root 与 .dark 变量，不要在组件中散落固定颜色。两种
模式需一起更新，并检查文字、焦点环、图表和侧栏的对比度。
配色模式
@nuxtjs/color-mode 默认与回退均为 light，classPrefix/classSuffix 为空，
并以 theme 为存储键。因此暗色模式添加的就是 .dark class，与 Tailwind
自定义变体一致。
const colorMode = useColorMode()
colorMode.preference = colorMode.preference === "light" ? "dark" : "light"对于必须等客户端读取偏好后再渲染的内容，使用 <ColorScheme>。模板还包含一
个客户端插件，在切换主题时临时关闭 CSS 过渡，避免闪烁。
shadcn-vue
components.json 选择 new-york 风格、neutral 基础色、CSS 变量与 Lucide
图标。Nuxt 模块将基础组件放在 app/components/ui，AI 元素放在
app/components/ai-elements，均不加组件名前缀。
新增基础组件时使用 shadcn-vue CLI，然后检查生成代码与导入。条件 class 使用：
import { cn } from "@/lib/utils"
const classes = cn("rounded-lg border", active && "border-primary")cn() 结合 clsx 与 tailwind-merge，后出现的工具类会正确解决冲突。
字体、图标与图片
Geist 与 Geist Mono 通过 app.head 中的 Google Fonts <link> 加载，并在
CSS 中映射到 --font-sans/--font-mono；这里不是 next/font。若需减少外部
请求或满足隐私要求，可自托管字体并同时更新 head 链接和字体变量。
@nuxt/icon 提供 Iconify 图标，包括已安装的 Lucide 集合。app/assets/icons
中的文件以 my-icons 前缀使用，例如 <Icon name="my-icons:resend" />。
响应式产品图片使用 @nuxt/image/<NuxtImg>。
验证主题修改
- 明暗模式的表面、边框、文字、焦点环与图表均清晰可读。
- 刷新后仍从
theme存储键恢复偏好。 - 控制台没有 color-mode hydration 警告。
- 新生成的 shadcn 组件使用语义令牌而非固定颜色。
- 字体回退与加载行为可接受。
- 自定义图标和优化图片在生产构建中正常显示。