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。此技能教你何時使用哪個元件以及如何建構良好的 UI。

核心規則（始終適用）

1. 務必將應用程式包裹在 UApp 中 — 這是 toast、tooltip 及程式化覆蓋層的必要條件。接受 locale prop 以支援 i18n。
2. 務必使用語意化顏色 — 例如 text-default、bg-elevated、border-muted。絕不要使用原始 Tailwind 色板顏色如 text-gray-500。
3. 讀取產生的主題檔案以取得 slot 名稱 — Nuxt：.nuxt/ui/<component>.ts，Vue：node_modules/.nuxt-ui/ui/<component>.ts。這些檔案顯示每個元件的所有 slot、variant 及預設 class。
4. 覆蓋優先順序（最高優先）：ui prop / class prop → 全域設定 → 主題預設值。
5. 圖示使用 i-{collection}-{name} 格式 — lucide 是預設集合。使用 MCP 的 search_icons 工具尋找圖示，或至 icones.js.org 瀏覽。

如何使用此技能

根據任務，在撰寫任何程式碼之前載入相關的參考檔案。不要全部載入，只載入需要的部分。

參考檔案

指南 — 設計決策與慣例：

• design-system — 語意化顏色、主題設定、品牌自訂、variants、ui prop
• component-selection — 決策矩陣：何時使用 Modal 與 Slideover、Select 與 SelectMenu、Toast 與 Alert 等
• conventions — 編碼模式、slot 命名、items 陣列、composables、鍵盤快捷鍵
• 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";

<!-- 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' })。