# Nuxt UI 设计系统

## Nuxt UI 设计系统界面预览

编辑完整的示例输入，选择清单，并检查验证和重置效果。

## Nuxt UI 设计系统设计参考

Nuxt UI 4.11.3 默认值、实际编译后的语义 CSS，以及原生 Vue 组件契约。布局和验证方案均为原创，并已单独标明。

### 默认语义颜色别名

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| primary | green | Nuxt UI 4.11.3 的实际默认别名。组件颜色属性引用语义名称，配置的调色板则提供对应值。 |
| secondary | blue | Nuxt UI 4.11.3 的实际默认别名。组件颜色属性引用语义名称，配置的调色板则提供对应值。 |
| success | green | Nuxt UI 4.11.3 的实际默认别名。组件颜色属性引用语义名称，配置的调色板则提供对应值。 |
| info | blue | Nuxt UI 4.11.3 的实际默认别名。组件颜色属性引用语义名称，配置的调色板则提供对应值。 |
| warning | yellow | Nuxt UI 4.11.3 的实际默认别名。组件颜色属性引用语义名称，配置的调色板则提供对应值。 |
| error | red | Nuxt UI 4.11.3 的实际默认别名。组件颜色属性引用语义名称，配置的调色板则提供对应值。 |
| neutral | slate | Nuxt UI 4.11.3 的实际默认别名。组件颜色属性引用语义名称，配置的调色板则提供对应值。 |
### 浅色文本角色

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --ui-text-dimmed | var(--ui-color-neutral-400) | 强调程度最低的辅助文本。不要将此角色用于必填字段标签或验证消息。 |
| --ui-text-muted | var(--ui-color-neutral-500) | 用于字段提示等辅助说明，以及原始预览中的介绍段落。 |
| --ui-text-toned | var(--ui-color-neutral-600) | 次级阅读层级；进一步降低对比度前，请先与常规文本角色进行比较。 |
| --ui-text | var(--ui-color-neutral-700) | 用于主要阅读内容和用户输入内容的默认文本角色。 |
| --ui-text-highlighted | var(--ui-color-neutral-900) | 用于高强调标题和前景细节，包括预览中的主标题。 |
| --ui-text-inverted | #fff | 用于反转深色表面的前景色；不要将其作为适用于所有强调色的通用白色文本覆盖。 |
### 浅色表面与边框

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --ui-bg | #fff | 基础画布，以及完整编辑器使用的浅色卡片表面。 |
| --ui-bg-muted | var(--ui-color-neutral-50) | 用于浅色外观中次要区域的克制辅助表面。 |
| --ui-bg-elevated | var(--ui-color-neutral-100) | 与白色画布形成更明显的区分，适用于凸起或强调的次要表面。 |
| --ui-bg-accented | var(--ui-color-neutral-200) | 更醒目的中性背景；确保字段值在其上清晰易读。 |
| --ui-bg-inverted | var(--ui-color-neutral-900) | 用于搭配反转前景色的深色中性表面。 |
| --ui-border | var(--ui-color-neutral-200) | 用于字段和卡片轮廓的默认中性分隔线。 |
| --ui-border-muted | var(--ui-color-neutral-200) | 用于相关内容块之间的弱强调分隔，不作为明显的章节分界线。 |
| --ui-border-accented | var(--ui-color-neutral-300) | 当默认边框无法提供足够区分度时，使用更醒目的中性轮廓。 |
| --ui-border-inverted | var(--ui-color-neutral-900) | 用于反转表面的边框角色；需与其预期背景配合使用。 |
### 共享几何尺寸与 Tailwind 类型

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --ui-radius | .25rem | 实际编译输出中发布的 Nuxt UI 或 Tailwind 默认值。原始布局自行设置了 1100px 最大宽度和 24px 间距。 |
| --ui-container | 80rem | 实际编译输出中发布的 Nuxt UI 或 Tailwind 默认值。原始布局自行设置了 1100px 最大宽度和 24px 间距。 |
| --spacing | .25rem | 实际编译输出中发布的 Nuxt UI 或 Tailwind 默认值。原始布局自行设置了 1100px 最大宽度和 24px 间距。 |
| --text-sm | .875rem | 实际编译输出中发布的 Nuxt UI 或 Tailwind 默认值。原始布局自行设置了 1100px 最大宽度和 24px 间距。 |
| --text-xl | 1.25rem | 实际编译输出中发布的 Nuxt UI 或 Tailwind 默认值。原始布局自行设置了 1100px 最大宽度和 24px 间距。 |
| --text-4xl | 2.25rem | 实际编译输出中发布的 Nuxt UI 或 Tailwind 默认值。原始布局自行设置了 1100px 最大宽度和 24px 间距。 |
### Vue 组件契约

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| Vite plugin | ui({ colorMode: false }) | 生成组件和主题导入，并提供必要的浏览器集成。 |
| Vue plugin | createApp(App).use(ui) | 导入 ui from @nuxt/ui/vue-plugin；仅直接导入原始组件并不能构成完整的独立运行配置。 |
| UApp | Application wrapper | 为组件树提供原生应用上下文。 |
| UFormField | label, description, name | 将字段上下文和易读的辅助文本关联到控件。 |
| UInput / UTextarea | v-model | 两个输入框都由 Vue ref 控制；文本区域还启用了 autoresize 和 rows。 |
| USwitch | v-model + label | 可选清单项采用真正的布尔状态。 |
| UButton | @click / color / variant | 主要操作和中性描边的恢复操作使用原生变体。 |
| UCard | header slot + default body | 让字段内容与易读的结果处于相匹配的原生表面上。 |
| UBadge | color + variant="subtle" | 通过文本和外观区分等待状态与本地生成的结果。 |
## Nuxt UI 设计系统完整指南

实用指南，介绍如何为真实界面选择、应用和评审此系统。

完整指导、实现起点和源代码链接。

## Nuxt UI 设计系统独立 Vue 运行时

### 使用官方 Vue 集成方式

> 本示例在 Vue 3 和 Vite 中运行 @nuxt/ui 4.11.3，并非 Nuxt 服务端渲染应用。Vite 插件负责解析生成的 UI 模板、自动组件导入和框架别名；Vue 插件则注册所需的运行时集成。完整示例同时包含两者，避免出现只安装了软件包、却无法解析 #build 或 #imports 的误导性配置。

- @nuxt/ui/vite 提供构建时集成。

- @nuxt/ui/vue-plugin 提供运行时注册。

- UApp 包裹原生组件树。

### 保留应用包装组件和样式表

UApp 包裹整个组合界面。样式表导入 Tailwind CSS 和 @nuxt/ui，主入口则在挂载应用之前导入该样式表。构建产物包含真正的组件 CSS 和交互行为，而非卡片与开关的静态仿制品。这是一个用于检查该库的具体浏览器配置；Nuxt 应用应使用其自身文档说明的模块配置。

## Nuxt UI 设计系统语义颜色与组件变体

### 使用语义颜色，而非照搬绿色

默认配置将 primary 和 success 映射为绿色，将 secondary 和 info 映射为蓝色，将 warning 映射为黄色，将 error 映射为红色，并将 neutral 映射为 slate。原生组件通过 color 属性使用这些别名。因此，主要的生成按钮和中性描边的重置按钮分别代表不同的操作角色，无需引入一个被错误宣称为 Nuxt UI 默认值的自定义配色方案。

### 明确外观的适用范围

本示例仅支持浅色模式，因此 Vite 插件配置为 colorMode:false。参考表列出了对应的浅色文本、表面和边框声明，但并未声称这些固定值也适用于深色主题。若产品要添加颜色模式，应启用所选集成，并一并验证控件、表面和已保存的偏好设置。

## Nuxt UI 设计系统文本角色、表面与几何尺寸

### 理解语义 CSS 之间的关系

辅助文案使用 --ui-text-muted，该变量指向 neutral-500；主标题使用 --ui-text-highlighted，指向 neutral-900。表面和边框变量同样引用已配置的中性色阶。本指南保留了这些关联，而不是将所有内容简化为几个互不相关的十六进制值，因此即使更改中性色板，组件主题仍能保持协调一致。

### 区分共享默认值与页面级选择

此版本中的共享 --ui-radius 为 .25rem，--ui-container 为 80rem。原始简报布局则自行选择了 1100px 的外部最大宽度、两列布局与 24px 间距，并在宽度低于 700px 时改为单列。标题和辅助文本的字号使用 Tailwind 的实际文本角色。这些页面级选择写在随附的 CSS 中，并非凭空设定的全库要求。

## Nuxt UI 设计系统字段组合与本地验证

### 为每个输入框提供真实的字段上下文

UFormField 在 UInput 或 UTextarea 周围提供可见标签和名称。上下文输入框还会显示根据修剪后内容计算的字数。两个控件都使用 v-model，因此显示的值与组合处理程序读取的是同一组 refs。文本区域设置了合适的初始行数并启用 autoresize，让较长的用户输入能够随内容增长，而不会被裁切在固定高度的框内。

### 组合内容前先进行验证

原始组合操作要求标题和上下文经过修剪后均不为空。若缺少任一项，界面会显示清晰易读的提示，同时保留用户当前输入。这是应用层验证，并不意味着调用了服务器，也不代表包含了未提供的验证架构。随附代码在同一处清楚展示了验证规则和错误处理流程。

## Nuxt UI 设计系统派生草稿与过期状态防护

### 仅组合已有的文本

输出将提供的标题和上下文与可选的静态分享清单组合起来。结果明确表明这是一份本地草稿，而非 AI 回复。过程中不会调用模型、等待加载，也不会编造生成内容。可通过原生 USwitch 布尔开关控制是否加入清单，组合后的文本会直接反映开关状态。

### 输入变更时清除旧结果

Vue 会监听标题、上下文和清单开关；任一项修改后，都会移除之前组合的结果。状态徽标随后会恢复为“等待输入”。这样可避免用户编辑新内容时，旧草稿仍显示为最新结果。字数始终由计算属性得出，因此会与当前上下文保持一致。

## Nuxt UI 设计系统：完整的空状态与重置状态

### 让等待面板发挥作用

组合内容之前，右侧卡片会完整说明将显示哪些内容，以及编辑、隐私和重置的工作方式。它并非空白的内容模块。组合完成后，该区域会显示完整且易读的草稿，并保留换行和自动换行。徽标也会以文字显示当前状态，因此颜色并非唯一的提示方式。

### 重置为完整示例输入

重置示例会恢复原始标题、完整上下文并启用清单，同时清除结果和任何错误。它不会留下空白示例，让读者猜测应填入哪些内容。浏览器测试会先组合一份已修改的简报，再验证重置后完整示例标题已恢复。

## Nuxt UI 设计系统：响应式卡片与文本流

### 在窄屏上保持结果易读

视口宽度低于 700px 时，两张卡片会改为单列布局，所有输入项都会占满可用宽度。草稿采用 pre-wrap，而非无法换行的预格式化单行文本，因此较长的标题或句子都能自然换行。按钮会在操作组内自动换行。完成实际编辑与内容组合后，会在 280px 宽度，以及手机、平板和桌面尺寸下检查页面。

### 检查原生状态变化后的界面

开关样式包含原生状态过渡。视觉检查会等待过渡完成后再截取结果，避免将滑块或轨道的中间颜色误认为最终状态。功能检查则会确认布尔值确实生效：关闭开关后，组合出的文本中会移除清单。

## Nuxt UI 设计系统：完整的 Vue 与 Vite 项目

### 使用提供的全部五个文件

示例包含 App.vue、main.js、style.css、vite.config.mjs 和 index.html。配置中包含 @vitejs/plugin-vue 和 @nuxt/ui/vite；主入口则会安装 @nuxt/ui/vue-plugin。只安装 @nuxt/ui 并粘贴 App.vue，并不能构成完整的可运行项目。按指定版本配置后，可通过实际的原生组件和语义样式复现本地预览。

1. 将提供的全部五个文件放在同一目录中。

2. 安装指定版本的依赖。

3. 在该目录中运行 Vite。

4. 测试输入缺失、编辑后的输出、移除清单和重置。

### 将此浏览器端示例与部署分开

本地构建不包含服务器端点、身份验证、持久化存储或外部模型连接。不能根据组件名称或“组合”操作推断这些功能存在。真实产品可以复用字段和状态模式，并添加经过验证的持久化与服务行为；但即使不添加这些功能，此完整示例本身也具有实用价值。

## Nuxt UI 设计系统组件示例

### App.vue

完整组合原生组件与响应式状态。

```
<script setup>
import{ref,computed,watch}from'vue';
const title=ref('A calmer project handoff'),context=ref('Help a small team understand what is ready, what needs a decision, and who owns the next step.'),checklist=ref(true),error=ref(''),brief=ref('');const words=computed(()=>context.value.trim()?context.value.trim().split(/\s+/).length:0);watch([title,context,checklist],()=>{brief.value='';error.value=''});function compose(){if(!title.value.trim()||!context.value.trim()){error.value='Add both a title and context before composing.';return}brief.value=title.value.trim()+'\n\nPurpose\n'+context.value.trim()+(checklist.value?'\n\nBefore sharing\n• Name the next decision.\n• Identify an owner.\n• Include the source materials.':'')+'\n\nThis is a local draft, not a generated AI response.';}function reset(){title.value='A calmer project handoff';context.value='Help a small team understand what is ready, what needs a decision, and who owns the next step.';checklist.value=true;brief.value='';error.value=''}
</script>
<template><UApp><main><p class="text-primary font-semibold text-sm">NUXT UI / ORIGINAL BRIEF COMPOSER</p><h1 class="text-4xl font-bold tracking-tight mt-4 text-highlighted">Put the next step into words.</h1><p class="text-muted mt-5 max-w-2xl leading-7">A local composition tool using Nuxt UI 4.11.3 in a standalone Vue application. The preview assembles your text; it does not call an AI model.</p><div class="layout"><UCard><template #header><h2 class="font-semibold text-xl">Write the essentials</h2></template><div class="stack"><UFormField label="Brief title" name="title"><UInput v-model="title" class="w-full" placeholder="Name the work" aria-label="Brief title"/></UFormField><UFormField label="Context" name="context" :description="words+' words in your context'"><UTextarea v-model="context" class="w-full" autoresize :rows="5" placeholder="What should the next person understand?" aria-label="Context"/></UFormField><USwitch v-model="checklist" label="Include the sharing checklist"/><p v-if="error" role="alert" class="text-error text-sm">{{error}}</p><div class="flex flex-wrap gap-3"><UButton @click="compose">Compose local brief</UButton><UButton color="neutral" variant="outline" @click="reset">Reset sample</UButton></div></div></UCard><UCard><template #header><div class="flex justify-between gap-3 flex-wrap"><h2 class="font-semibold text-xl">Readable draft</h2><UBadge :color="brief?'success':'neutral'" variant="subtle">{{brief?'Composed locally':'Waiting for your text'}}</UBadge></div></template><div v-if="brief" class="brief" role="status">{{brief}}</div><div v-else class="space-y-4 text-muted leading-7"><p>Your draft will keep the title and context you provide, with an optional sharing checklist.</p><ul class="list-disc pl-5 space-y-2"><li>Editing any input clears an older composed result.</li><li>No content leaves the browser.</li><li>Reset returns to the complete sample inputs.</li></ul></div></UCard></div><p class="notes text-muted">Actual UCard, UFormField, UInput, UTextarea, USwitch, UButton and UBadge components with Nuxt UI’s default semantic theme. Original application content and state; this example uses Vue/Vite, not a Nuxt server.</p></main></UApp></template>
```

代码参考

- 将全部五个源文件放在一起。

### main.js

Vue 挂载与 Nuxt UI 运行时插件。

```
import{createApp}from'vue';import ui from'@nuxt/ui/vue-plugin';import App from'./App.vue';import './style.css';createApp(App).use(ui).mount('#app');
```

代码参考

- 将全部五个源文件放在一起。

### style.css

原生主题导入与原始响应式布局。

```
@import 'tailwindcss';
@import '@nuxt/ui';
body{margin:0}*{box-sizing:border-box}main{max-width:1100px;margin:auto;padding:32px}.layout{display:grid;grid-template-columns:1fr 1fr;gap:24px;margin-top:32px}.stack{display:grid;gap:24px}.brief{white-space:pre-wrap;line-height:1.7;overflow-wrap:anywhere}.notes{font-size:13px;line-height:1.6;margin-top:24px}@media(max-width:700px){main{padding:16px}.layout{grid-template-columns:1fr}}textarea{min-height:150px}button{max-width:100%}
```

代码参考

- 将全部五个源文件放在一起。

### vite.config.mjs

Vue 编译器与 Nuxt UI 构建插件。

```
import{defineConfig}from'vite';import vue from'@vitejs/plugin-vue';import ui from'@nuxt/ui/vite';export default defineConfig({plugins:[vue(),ui({colorMode:false})],base:'./',build:{cssCodeSplit:false}});
```

代码参考

- 将全部五个源文件放在一起。

### index.html

完整的浏览器根文档。

```
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Project brief composer</title></head><body><div id="app"></div><script type="module" src="./main.js"></script></body></html>
```

代码参考

- 将全部五个源文件放在一起。

## Nuxt UI 设计系统 AI Agent 配置

### 实现起点

先保存提供的全部五个文件。请使用与指定版本的 Vite 和 Nuxt UI 兼容的 Node 版本（本地构建使用的是 Node 22.17）。

```
npm init -y
npm install vue@3.5.43 vue-router@5.3.1 @nuxt/ui@4.11.3 tailwindcss@4.3.3 vite@8.3.2 @vitejs/plugin-vue@6.0.9
npx vite --host 127.0.0.1
```

### 适用于你项目的提示词

```
使用官方 Vite 和 Vue 插件，实现完整的 Nuxt UI 4.11.3 独立 Vue 简报编辑器。保留语义颜色、UFormField 上下文、受控输入与开关引用、trim 校验、计算字数、过期结果清除、完整的等待状态内容和重置功能。不要暗示会调用 AI 或保存到后端。
```

## Nuxt UI 设计系统：来源与范围

在独立的 Vue/Vite 浏览器应用中使用实际的 Nuxt UI 组件。简报编辑器是原创的 OpenDesign 代码，不会调用 AI 模型、Nuxt 服务器或持久化服务。

- Vue 安装 独立的 Vue 与 Vite 集成。

- 设计系统 语义化 CSS 与共享主题结构。

- 颜色 可配置的语义别名。

- 表单字段 标签、说明和字段上下文。

- 多行文本框 受控文本与调整大小行为。

## Nuxt UI 设计系统相关资源

### Oruga UI

原生 Oruga 目录编辑器，支持搜索和移除主题标签、强制执行词汇限制、使用可选主题的真实令牌，并通过实时卡片呈现所选标签。

### Pico CSS

Pico CSS 样式采用语义化 HTML，支持基于 rem 的响应式字号阶梯和主题变量。标准版、无类版和条件版的集成范围各不相同；本指南使用标准构建版本，展示带有原生展开面板和对话框行为的阅读偏好表单。

### Preline UI

使用原生 Preline 设计的行程规划工具，包含关联选项卡、受约束的数字输入插件、已安装的主题别名、实际的 Tailwind 尺度，以及随所选行程更新的本地材料估算。


- [实现参考](https://ui.nuxt.com/docs/getting-started/installation/vue)
- [来源](https://ui.nuxt.com/docs/getting-started/theme/colors)
- [来源](https://ui.nuxt.com/docs/getting-started/theme/design-system)
- [来源](https://ui.nuxt.com/docs/getting-started/installation/vue)
- [代码参考](https://ui.nuxt.com/docs/getting-started/installation/vue)
- [Vue 安装 独立的 Vue 与 Vite 集成。](https://ui.nuxt.com/docs/getting-started/installation/vue)
- [设计系统 语义化 CSS 与共享主题结构。](https://ui.nuxt.com/docs/getting-started/theme/design-system)
- [颜色 可配置的语义别名。](https://ui.nuxt.com/docs/getting-started/theme/colors)
- [表单字段 标签、说明和字段上下文。](https://ui.nuxt.com/docs/components/form-field)
- [多行文本框 受控文本与调整大小行为。](https://ui.nuxt.com/docs/components/textarea)