主题与暗色模式

Nuxt UI 自带一套设计体系，改主题不用重写每个组件。最常用的两件事是「换主色」和「切换暗色模式」，本篇都讲清楚。

本篇基于 /453.html 接好的环境。

换主色 primary

所有 color="primary" 的组件（按钮、标签、链接高亮）都会跟随 primary 的值。在 app.config.ts 里统一设置。

// app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'green'
    }
  }
})

Nuxt UI 内置了一组色名（red、orange、amber、yellow、lime、green、emerald、teal、cyan、sky、blue、indigo、violet、purple、fuchsia、pink、rose）。挑一个填进去，全站主色立即改变，改完保存会热更新。

其他语义色

除了 primary，ui.colors 还能覆盖 secondary、success、info、warning、error、neutral 等，按需调整。

// app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'violet',
      error: 'rose'
    }
  }
})

暗色模式

Nuxt UI 内置了暗色模式支持，靠根元素上的 dark class 切换。最简单的方式是用官方封装的 ColorMode 组件，它自带一个切换按钮。

<template>
  <ColorMode />
</template>

想自己控制，用 useColorMode composable 读取和设置。

<template>
  <UButton :icon="icon" @click="toggle">切换主题</UButton>
</template>

<script setup>
const colorMode = useColorMode()
const icon = computed(() => colorMode.value === 'dark' ? 'i-lucide-moon' : 'i-lucide-sun')

function toggle() {
  colorMode.value = colorMode.value === 'dark' ? 'light' : 'dark'
}
</script>

useColorMode() 返回的 value 是 'light' 或 'dark'，赋新值即可切换，Nuxt UI 会自动在 <html> 上加/去 dark class，所有组件样式跟着变。

用 CSS 变量深度定制

想改更细的视觉（某类圆角、某色阶），Nuxt UI 暴露了 --ui-* 一组 CSS 变量，在全局样式里覆盖即可。

/* app/assets/css/main.css */
:root {
  --ui-radius: 0.5rem;
}

初学阶段先用 primary 换色 + 暗色切换就够用，深度定制等熟悉后再碰。

常见问题

问题	解决方法
改了 primary 没效果	确认写在 `app.config.ts` 的 `ui.colors.primary`，且重启过 dev 服务器
暗色切换不生效	确认 `useColorMode` 来自 Nuxt UI（已装 `@nuxt/ui`），且根组件包了 `<UApp>`

参考资料

下拉菜单与命令面板

图标 Icon