nuxt-ui

Nuxt UI

基于 Reka UI + Tailwind CSS + Tailwind Variants 构建的 Vue 组件库。可与 Nuxt、Vue (Vite)、Laravel (Vite + Inertia) 和 AdonisJS (Vite + Inertia) 搭配使用。

MCP 服务

如需了解组件 API 详情（props、slots、events、完整文档和示例），请使用 Nuxt UI MCP server。如果尚未配置，请添加：

Cursor — .cursor/mcp.json：

{ "mcpServers": { "nuxt-ui": { "type": "http", "url": "https://ui.nuxt.com/mcp" } } }

Claude Code：

claude mcp add --transport http nuxt-ui https://ui.nuxt.com/mcp

主要 MCP 工具：

• search-components — 按名称、类别或意图查找组件（不带参数时列出全部组件）
• search-composables — 按名称或描述查找组合式函数（不带参数时列出全部组合式函数）
• search-icons — 搜索 Iconify 图标（默认为 lucide），返回 i-{prefix}-{name} 格式的名称
• get-component — 提供完整的组件文档和用法示例
• get-component-metadata — 提供 props、slots、events（轻量级，不含文档内容）
• get-example — 获取真实场景中的代码示例

需要了解组件接受哪些内容或其 API 的工作方式时，请使用 MCP。本技能会教你何时使用哪种组件以及如何构建优质界面。

核心规则（始终适用）

1. 始终使用 UApp 包裹应用 — toast、tooltip 和程序化 overlay 都需要它。支持用于 i18n 的 locale prop。
2. 始终使用语义化颜色 — 例如 text-default、bg-elevated、border-muted。切勿使用 text-gray-500 这类原始 Tailwind 调色板颜色。
3. 读取生成的主题文件以查看 slot 名称 — Nuxt：.nuxt/ui/<component>.ts，Vue：node_modules/.nuxt-ui/ui/<component>.ts。这些文件会展示任意组件的所有 slot、variant 和默认类名。
4. 覆盖优先级（优先级从高到低）：ui prop / class prop → 全局配置 → 主题默认值。
5. 图标使用 i-{collection}-{name} 格式 — 默认图标集为 lucide。使用 MCP search-icons 工具查找图标，或访问 icones.js.org 浏览。

如何使用此技能

根据任务，在编写代码之前加载相关参考文件。不要全部加载，只加载所需内容。

参考文件

指南 — 设计决策和约定：

• design-system — 语义化颜色、主题设置、品牌自定义、variant、ui prop
• component-selection — 决策矩阵：何时使用 Modal 而非 Slideover、Select 而非 SelectMenu、Toast 而非 Alert 等
• conventions — 编码模式、slot 命名、items 数组、组合式函数、键盘快捷键
• forms — 表单验证、字段布局、错误处理、Standard Schema

布局 — 完整的页面结构模式：

• landing — 落地页、博客、更新日志、定价页面
• dashboard — 带侧边栏和面板的管理界面
• docs — 带导航和目录的文档站点
• chat — 使用 Vercel AI SDK 构建的 AI 聊天
• editor — 带工具栏的富文本编辑器

方案 — 常见任务的完整模式：

• data-tables — 带筛选、分页、排序和选择功能的表格
• auth — 登录、注册、忘记密码表单
• overlays — 模态框、侧滑面板、抽屉、命令面板
• navigation — 页眉、侧边栏、面包屑、标签页

快速参考：

• components — 按类别整理的组件索引，便于查找合适的组件名称

路由表

任务	加载这些参考资料
构建落地页	design-system、conventions、landing
构建仪表盘 / 管理界面	conventions、component-selection、dashboard
添加设置页面	conventions、forms
创建登录 / 注册表单	conventions、forms、auth
在表格中显示数据	conventions、component-selection、data-tables
自定义主题 / 品牌颜色	design-system
添加聊天界面	conventions、chat
添加模态框、侧滑面板或抽屉	conventions、component-selection、overlays
构建网站导航	conventions、component-selection、navigation
构建文档网站	conventions、docs
渲染 markdown	component-selection、components、docs
添加富文本编辑器	conventions、editor
通用 UI 工作	conventions、component-selection

安装

Nuxt

pnpm add @nuxt/ui tailwindcss

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css']
})

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

<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

Vue (Vite)

pnpm add @nuxt/ui tailwindcss

// 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()
  ]
})

// src/main.ts
import './assets/css/main.css'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)
const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)
app.mount('#app')

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

<template>
  <UApp>
    <RouterView />
  </UApp>
</template>

当本地安装图标集（@iconify-json/lucide）时，图标（v4.10+）会打包到构建产物中，以便用于 SSR / 离线场景。在 Vue 中，使用 ui({ icon: { clientBundle: { scan: true } } })。 在 nuxt.config.ts 中设置 ui: { theme: { unstyled: true } }（v4.9+），以移除默认主题类并使用你自己的设计系统。

在 index.html 中的根 <div id="app"> 添加 class="isolate"。 对于 Inertia：在 vite.config.ts 中使用 ui({ router: 'inertia' })。