设计系统

Nuxt UI 的设计系统使用 Tailwind CSS 来实现简单的皮肤设置和轻松的自定义。

Tailwind CSS

Tailwind CSS 采用 CSS 优先的配置方式，让你能够直接在 CSS 中使用 @theme 指令定义设计令牌（Design Tokens）。这使得你的主题更具可移植性、可维护性且易于自定义。

app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  /* Your custom design tokens go here */
}
请查看 Tailwind CSS 文档以了解所有可用的主题变量自定义选项。
Tailwind CSS v4 修改了其 Preflight，使按钮使用 cursor: default 而不是 cursor: pointer，以匹配浏览器默认行为。如果你想全局恢复指针光标，请将这些基础样式添加到你的 CSS 中。
app/assets/css/main.css
@layer base {
  button:not(:disabled),
  [role="button"]:not(:disabled) {
    cursor: pointer;
  }
}

字体

使用 --font-* 主题变量来自定义项目中字体系列工具类。

app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  --font-sans: 'Public Sans', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}
在此定义的字体将由 @nuxt/fonts 模块自动加载和优化。

颜色

使用 --color-* 主题变量来自定义你的颜色或覆盖默认颜色。

app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

@theme static {
  /* Override default green color */
  --color-green-50: #EFFDF5;
  --color-green-100: #D9FBE8;
  --color-green-200: #B3F5D1;
  --color-green-300: #75EDAE;
  --color-green-400: #00DC82;
  --color-green-500: #00C16A;
  --color-green-600: #00A155;
  --color-green-700: #007F45;
  --color-green-800: #016538;
  --color-green-900: #0A5331;
  --color-green-950: #052E16;

  /* Define new custom color */
  --color-brand-50: #fef2f2;
  --color-brand-100: #fee2e2;
  --color-brand-200: #fecaca;
  --color-brand-300: #fca5a5;
  --color-brand-400: #f87171;
  --color-brand-500: #ef4444;
  --color-brand-600: #dc2626;
  --color-brand-700: #b91c1c;
  --color-brand-800: #991b1b;
  --color-brand-900: #7f1d1d;
  --color-brand-950: #450a0a;
}
添加自定义颜色时，请务必为每种颜色定义从 50 到 950 的所有色阶。

断点（Breakpoints）

使用 --breakpoint-* 主题变量来自定义断点。

app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  --breakpoint-3xl: 1920px;
  --breakpoint-4xl: 2560px;
  --breakpoint-5xl: 3840px;
}

颜色

Nuxt UI 的色彩系统围绕语义化命名而非具体的颜色值设计。这种方法使你的 UI 更易于维护，并允许轻松切换主题。

语义化颜色

Nuxt UI 提供了描述颜色用途的语义化颜色别名。每个别名都根据你的 @theme 配置中的一种颜色进行定义，除了 Tailwind CSS 默认调色板外，还可以是你定义的任何颜色。

颜色默认值描述
primarygreen主要操作按钮 (CTA)、激活的导航、品牌元素、重要链接
secondaryblue次要按钮、替代操作、补充性 UI 元素
successgreen成功消息、已完成状态、正面确认
infoblue信息提示、工具提示、帮助文本、中性通知
warningyellow警告消息、待处理状态、需要注意的事项
errorred错误消息、验证错误、破坏性操作
neutralslate文本、边框、背景、禁用状态

这些语义化颜色可用于 Nuxt UI 组件的 color 属性中。

<template>
  <UButton color="primary">Save Changes</UButton>
</template>
尝试标题栏中的 主题选择器，即可立即查看不同配色方案如何影响整个 UI！

运行时配置

你可以在 app.config.ts 文件中的 ui.colors 键下于运行时配置这些颜色，从而实现无需重启服务器的动态主题自定义。

app/app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      neutral: 'zinc'
    }
  }
})

你可以在 vite.config.ts 文件中的 ui.colors 键下于运行时配置这些颜色，从而实现动态主题自定义。

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        colors: {
          primary: 'blue',
          secondary: 'purple',
          neutral: 'zinc'
        }
      }
    })
  ]
})
你只能使用主题中存在的颜色。要么：
  • 使用 Tailwind 默认颜色（如 blue, green, zinc）
  • 首先使用 @theme 指令定义自定义颜色（如上述示例中的 brand）

扩展颜色

你可能希望定义除默认值之外的额外语义化颜色，例如添加一个 tertiary（第三）颜色。

首先，在 nuxt.config.ts 的 ui.theme.colors 键下注册新颜色。

nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    theme: {
      colors: [
        'primary',
        'secondary',
        'tertiary',
        'info',
        'success',
        'warning',
        'error'
      ]
    }
  }
})

然后，在 app.config.ts 的 ui.colors 键下进行分配。

app/app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      tertiary: 'indigo'
    }
  }
})

在你的 vite.config.ts 文件中注册并分配新颜色。

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        colors: [
          'primary',
          'secondary',
          'tertiary',
          'info',
          'success',
          'warning',
          'error'
        ]
      },
      ui: {
        colors: {
          primary: 'blue',
          secondary: 'purple',
          tertiary: 'indigo'
        }
      }
    })
  ]
})

最后，在支持 color 属性的组件中使用此新颜色，或将其作为类名使用。

<UButton color="tertiary">
  Special Action
</UButton>

贡献

CSS 变量