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 服务器。如果尚未配置，请添加：

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 — 按名称或描述查找 composables（无参数则列出所有）
• search_icons — 搜索 Iconify 图标（默认为 lucide），返回 i-{prefix}-{name} 名称
• get_component — 完整的组件文档及使用示例
• get_component_metadata — props、slots、events（轻量，不含文档内容）
• get_example — 真实代码示例

当您需要了解组件接受什么或其 API 如何工作时，请使用 MCP。本技能教您何时使用哪个组件以及如何构建良好。

核心规则（始终适用）

1. 始终将应用包裹在 UApp 中 — 这是 toasts、tooltips 和程序化覆盖层所必需的。接受 locale 属性用于国际化。
2. 始终使用语义颜色 — text-default、bg-elevated、border-muted 等。切勿使用原始 Tailwind 调色板颜色如 text-gray-500。
3. 读取生成的主题文件以获取插槽名称 — Nuxt：.nuxt/ui/<component>.ts，Vue：node_modules/.nuxt-ui/ui/<component>.ts。这些文件显示任何组件的每个插槽、变体和默认类。
4. 覆盖优先级（最高优先）：ui 属性 / class 属性 → 全局配置 → 主题默认值。
5. 图标使用 i-{collection}-{name} 格式 — lucide 是默认集合。使用 MCP 的 search_icons 工具查找图标，或在 icones.js.org 浏览。

如何使用本技能

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

参考文件

指南 — 设计决策和约定：

• design-system — 语义颜色、主题、品牌定制、变体、ui 属性
• component-selection — 决策矩阵：何时使用 Modal 与 Slideover、Select 与 SelectMenu、Toast 与 Alert 等。
• conventions — 编码模式、插槽命名、items 数组、composables、键盘快捷键
• forms — 表单验证、字段布局、错误处理、Standard Schema

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

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

食谱 — 常见任务的完整模式：

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

快速参考：

• components — 分类的组件索引，用于查找正确的组件名称

路由表

任务	加载这些参考
构建着陆页	design-system, conventions, landing
构建仪表盘/管理 UI	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";

<!-- app.vue -->
<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";

<!-- src/App.vue -->
<template>
  <UApp>
    <RouterView />
  </UApp>
</template>

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