# Naive UI 设计系统

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

搜索记录、展开审核详情、跨页选择行，并将本地批次标记为已审核。

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

从已安装的软件包中检查 Naive UI 2.45.3 的 common 浅色主题对象。这些 camelCase 属性是主题覆盖项，并非公开的 --token CSS 变量命名方案。预览使用的自定义 common 覆盖项另行列出。

### 默认 common 颜色

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| primaryColor | #18a058 | 默认主色绿色。 |
| primaryColorHover | #36ad6a | 悬停状态变体。 |
| primaryColorPressed | #0c7a43 | 按下状态变体。 |
| primaryColorSuppl | #36ad6a | 辅助主色。 |
| infoColor | #2080f0 | 信息角色。 |
| successColor | #18a058 | 成功角色。 |
| warningColor | #f0a020 | 警告角色。 |
| errorColor | #d03050 | 错误角色。 |
| textColor1 | rgb(31, 34, 37) | 强调文本。 |
| textColor2 | rgb(51, 54, 57) | 常规文本。 |
| textColor3 | rgb(118, 124, 130) | 次要文本。 |
| borderColor | rgb(224, 224, 230) | 默认边界。 |
| dividerColor | rgb(239, 239, 245) | 细微分隔线。 |
| tableHeaderColor | rgb(250, 250, 252) | 表头背景。 |
### 字体与控件尺寸

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| fontFamily | v-sans, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" | 首选 UI 字体栈；不会自动下载 v-sans。 |
| fontSize | 14px | 默认 14px 字号。 |
| fontSizeMini | 12px | 迷你字号。 |
| fontSizeSmall | 14px | 小型控件文字。 |
| fontSizeMedium | 14px | 中型控件文字。 |
| fontSizeLarge | 15px | 大型控件文字。 |
| fontSizeHuge | 16px | 超大型控件文字。 |
| lineHeight | 1.6 | 默认文本节奏。 |
| heightTiny | 22px | 微型控件高度。 |
| heightSmall | 28px | 小型控件高度。 |
| heightMedium | 34px | 中型控件高度。 |
| heightLarge | 40px | 大型控件高度。 |
| heightHuge | 46px | 超大型控件高度。 |
| borderRadius | 3px | 默认 3px 圆角。 |
| borderRadiusSmall | 2px | 默认 2px 小圆角。 |
### 预览实际使用的主题覆盖项

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| common.primaryColor | #176b57 | 原创的深绿色主操作色。 |
| common.primaryColorHover | #238a71 | 原创的配套悬停值。 |
| common.primaryColorPressed | #115340 | 原创的配套按下状态值。 |
| common.borderRadius | 6px | 原创圆角覆盖值；默认值为 3px。 |
| Layout spacing | 32px outer / 24px section gaps / 16px toolbar gap | 原创页面间距，并非声称属于 Naive 全局间距比例。 |
## Naive UI 设计系统完整指南

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

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

## Naive UI 设计系统：JavaScript 主题对象，而非 Sass 构建流水线

### JavaScript 主题对象，而非 Sass 构建流水线

> Naive UI 是一个 Vue 3 组件库，其主题自定义通过 JavaScript 对象实现。审核队列将 themeOverrides 传给 NConfigProvider。其 common 部分覆盖 primaryColor、primaryColorHover、primaryColorPressed 和 borderRadius，其余组件默认值仍可通过该 provider 使用。

参考表列出了已安装的 2.45.3 common 浅色主题中的实际值，不会根据这些 camelCase 键臆造 CSS 变量名称。默认主色为 #18a058，默认圆角为 3px；此示例中的深绿色和 6px 圆角明确属于原创覆盖项。

阅读配套规范

## Naive UI 设计系统：密集型界面的字号与控件高度

### 密集型界面的字号与控件高度

常用主题采用 14 像素字号和 1.6 的行高。小号和中号文本的字号都是 14 像素，但控件高度不同。heightSmall 为 28 像素，heightMedium 为 34 像素；因此，尺寸名称描述的是组件几何尺寸，而不只是字号的递进关系。

首选字体栈以 v-sans 开头，但该组件库并不要求下载此字体才能渲染此示例。外围页面使用 system-ui、34px 标题和 18px 辅助分区标题。这些页面样式均为原创。采用该组件库的设计师应区分主题的控件尺寸比例与落地页更大的编辑式层级。

阅读配套规范

## Naive UI 设计系统：列定义承载行为

### 列定义承载行为

NDataTable 接收 columns 数组和 records 数组。示例以选择列开头，接着是展开列，然后是具名数据列。Reference 列显示醒目的名称和较小的稳定 ID。Entries 列使用数值比较器，名称列则使用默认排序器。Review 列根据记录状态渲染原生 NTag。

这是实际生效的配置，而不是只有装饰性表头的截图。对 Entries 列排序时，比较的是数值计数，而非格式化后的字符串。展开内容会显示每条记录对应的审核问题。数据表负责控制行的显示，应用则负责定义这些记录的含义。

阅读配套规范

## Naive UI 设计系统：重新排序后仍须保留选择状态

### 重新排序后仍须保留选择状态

row-key 函数会返回每条记录的稳定 ID。checked-row-keys 和 update:checked-row-keys 会在 Vue 状态中维持受控选择。排序或翻页可能改变记录的显示位置，但批量操作使用的身份标识不会改变。如果改用数组索引，行顺序变化时这种对应关系就会变得脆弱。

选择列会禁用已归档记录。这些记录仍会显示，以供历史参考，但无法加入审核批次。执行操作时，应用还会检查记录状态，确保数据变更与界面上显示的限制一致。在实际系统中，服务器仍需负责执行授权检查；禁用复选框并不能构成权限边界。

1. 在第一页选择一条可审核的记录。

2. 前往下一页，查看保留的选中数量。

3. 执行批量操作，确认所选记录的状态已更改，且未触及任何已归档记录。

阅读配套规范

## Naive UI 设计系统：筛选和分页使用独立状态

### 筛选和分页拥有独立状态

搜索框会匹配参考项名称和负责人。修改搜索内容时，当前页会重置为第 1 页，以免筛选结果仍停留在已无结果的后续页面。分页每页显示四条记录，并使用 onChange 处理函数；六条记录足以直观呈现页面切换效果。

选中项有意与筛选后的数组分开管理，并且可以跨页保留。工具栏中的数量会显示选中项的范围。生产环境中的批量操作应明确规定如何处理被筛选隐藏的选中项：保留还是清除。此示例选择保留。它不会将筛选操作当作对底层审核记录的修改。

阅读配套规范

## Naive UI 设计系统：展开行，再做出批量决策

### 批量决策前先展开行

每行都包含一个具体任务，例如检查导航中的键盘移动，或比较不同空状态所表达的含义。这样，展开区域就能为审核决策提供有用依据，而不只是重复泛泛的描述。表格使用 renderExpand 展开列，在对应记录下方显示常规内容。

表格在窄屏上仍保留列结构，并设置 scroll-x=640。这样，原生表格区域可以水平滚动，同时页面仍处于视口范围内。工具栏在移动设备上会纵向排列，但不会为了让截图更简洁而悄悄删减数据。

阅读配套规范

## Naive UI 设计系统：批量审核是本地数据转换

### 批量审核是本地数据转换

受控的键数组为空时，“将所选项标记为已审核”按钮会被禁用。点击后，程序会遍历记录，只将已选中且未归档的项目状态改为“已审核”。随后会清空选中项，并通过原生成功提示准确说明本地执行的操作。卡片标题中的已审核数量由记录计算得出，而非单独累加。

不会修改任何代码仓库、审核服务或外部文档。实际的异步实现需要处理加载、拒绝和部分失败等情况；在确认哪些更新成功之前，不应清空选中项。此示例明确将操作限制为同步的本地处理，因此成功提示与代码行为相符。

- 批量操作按钮会根据是否有选中项调整状态。

- 已审核数量根据表格中显示的同一组记录计算得出。

- 结果提示明确说明未修改任何代码仓库。

阅读配套规范

## Naive UI 设计系统：无需导入必需的 CSS 即可使用 Vue 组件

### 无需导入必需的 CSS 的 Vue 组件

在 Vue 3 项目中安装 naive-ui@2.45.3，并导入 App.vue 使用的组件。Naive UI 会在运行时提供组件样式；与许多以 CSS 为首选的库不同，这些组件无需通过全局导入包样式表来使用。提供的 style.css 仅包含原有的工作台布局。

NConfigProvider 同时接收英文组件语言包、日期语言包和通用主题覆盖配置。完整的单文件组件可使用标准 Vite Vue 插件编译。独立示例会打包编译后的组件，无需网络请求即可使用原生组件和应用行为。

阅读配套规范

## Naive UI 设计系统：主题和数据边界清晰可查

### 主题与数据边界清晰可查

此工作台是一个小型参考库，并非凭空编造指标的通用管理仪表盘。每一行都是示例内容，每种状态都有明确含义，展开文本也说明了查看该项的具体原因。主题表和完整单文件组件让样式与行为都可复现。

将 Naive UI 用于更大型的系统时，应协调管理全局通用覆盖配置和组件级覆盖配置。主色的默认、悬停和按下状态应一并审核。如果配置提供器提供受支持的主题定制入口，就不应优先通过设置样式来修改生成的内部结构。

阅读配套规范

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

### 完整的 Vue 审核队列

DataTable 列配置、稳定行键、选择、展开和受控分页。

```
<script setup>
import {ref,computed,h} from 'vue';
import {NConfigProvider,NDataTable,NButton,NInput,NTag,NAlert,NCard,NSpace,enUS,dateEnUS} from 'naive-ui';
const themeOverrides={common:{primaryColor:'#176b57',primaryColorHover:'#238a71',primaryColorPressed:'#115340',borderRadius:'6px'}};
const rows=ref([{id:'DS-101',name:'Navigation patterns',owner:'Maya',items:18,status:'Needs review',note:'Check keyboard movement between primary and overflow navigation.'},{id:'DS-102',name:'Empty-state copy',owner:'Alex',items:9,status:'Needs review',note:'Compare first-use guidance with filtered-empty and permission-empty states.'},{id:'DS-103',name:'Color role mapping',owner:'Jules',items:24,status:'Reviewed',note:'Semantic aliases were compared in light and dark appearances.'},{id:'DS-104',name:'Form error summary',owner:'Sam',items:12,status:'Needs review',note:'Verify error links focus the corresponding input.'},{id:'DS-105',name:'Legacy icon export',owner:'Maya',items:36,status:'Archived',note:'Historical export retained for reference; batch review is disabled.'},{id:'DS-106',name:'Density variants',owner:'Alex',items:15,status:'Needs review',note:'Check compact controls with long translated labels.'}]);
const query=ref(''),checked=ref([]),page=ref(1),notice=ref('');const filtered=computed(()=>rows.value.filter(r=>(r.name+' '+r.owner).toLowerCase().includes(query.value.toLowerCase())));
const columns=[{type:'selection',disabled:r=>r.status==='Archived'},{type:'expand',renderExpand:r=>h('div',{class:'row-note'},r.note)},{title:'Reference',key:'name',sorter:'default',width:240,render:r=>h('div',[h('strong',r.name),h('div',{class:'row-id'},r.id)])},{title:'Owner',key:'owner',width:100},{title:'Entries',key:'items',sorter:(a,b)=>a.items-b.items,width:95},{title:'Review',key:'status',width:140,render:r=>h(NTag,{type:r.status==='Reviewed'?'success':r.status==='Archived'?'default':'warning',bordered:false},{default:()=>r.status})}];
const pagination=computed(()=>({page:page.value,pageSize:4,onChange:p=>page.value=p}));function apply(){rows.value=rows.value.map(r=>checked.value.includes(r.id)&&r.status!=='Archived'?{...r,status:'Reviewed'}:r);notice.value=`Marked ${checked.value.length} selected references reviewed in this preview. No repository was changed.`;checked.value=[];}
</script>
<template><NConfigProvider :locale="enUS" :date-locale="dateEnUS" :theme-overrides="themeOverrides"><main class="review-desk"><header><p class="eyebrow">NAIVE UI / REFERENCE REVIEW</p><h1>A review queue with context.</h1><p>Search, expand a row, compare entry counts, and apply a local batch action.</p></header><NCard title="Reference library"><template #header-extra><NTag :bordered="false" type="success">{{rows.filter(r=>r.status==='Reviewed').length}} reviewed</NTag></template><div class="toolbar"><NInput v-model:value="query" placeholder="Search reference or owner" clearable aria-label="Search reference or owner" @update:value="page=1"/><NButton type="primary" :disabled="!checked.length" @click="apply">Mark selected reviewed</NButton></div><p class="selection-note">{{checked.length}} selected · Selection uses stable IDs and can span pages.</p><NDataTable :columns="columns" :data="filtered" :row-key="r=>r.id" :checked-row-keys="checked" @update:checked-row-keys="keys=>checked=keys" :pagination="pagination" :scroll-x="640" :single-line="false"/><NAlert v-if="notice" type="success" class="notice">{{notice}}</NAlert></NCard><div class="notes"><section><h2>Expand before judging</h2><p>The expand control reveals a concrete review question for each reference. A title alone is not enough context for a meaningful batch decision.</p></section><section><h2>Archived is a separate state</h2><p>Archived records stay visible but cannot join the batch selection. Search and pagination never change the underlying review data.</p></section></div><footer>Native Naive UI 2.45.3 DataTable, Input, Button, Tag, Card and Alert. All records and mutations are local examples.</footer></main></NConfigProvider></template>
```

代码参考

- 选中状态通过稳定的参考 ID 关联。

- 选择列的判断函数会禁用已归档的行。

- 通过 NConfigProvider 提供通用主题覆盖配置。

### 原有工作台布局

围绕原生数据表格的页面排版和响应式间距。

```
*{box-sizing:border-box}body{margin:0;background:#f5f7f6;color:#1f2225;font-family:system-ui,sans-serif;font-size:14px;line-height:1.6}.review-desk{max-width:1120px;margin:auto;padding:32px}header{max-width:720px;margin-bottom:28px}h1{font-size:34px;line-height:1.2;letter-spacing:-.03em;margin:10px 0 16px}.eyebrow{font-size:11px;letter-spacing:.12em;font-weight:700;color:#426258}.toolbar{display:flex;align-items:center;gap:16px}.toolbar .n-input{max-width:360px}.selection-note,.row-id{font-size:12px;color:#767c82}.row-id{margin-top:4px}.row-note{padding:12px 16px;max-width:65ch;color:#335547}.notice{margin-top:20px}.notes{display:grid;grid-template-columns:1fr 1fr;gap:24px;margin-top:24px}.notes section{border-top:2px solid #c8d7cf;padding:18px 0}.notes h2{font-size:18px;margin:0 0 10px}.notes p{margin:0}footer{font-size:12px;color:#767c82;margin-top:20px}@media(max-width:700px){.review-desk{padding:20px 16px}h1{font-size:28px}.toolbar{align-items:stretch;flex-direction:column}.toolbar .n-input{max-width:none}.notes{grid-template-columns:1fr}.n-card>.n-card__content{padding:16px!important}}
```

代码参考

- Naive UI 会注入组件样式；此样式表仅包含应用布局。

## Naive UI 设计系统 Agent 设置

### 实现起点

已通过 Vue 3 和 Naive UI 2.45.3 验证。使用标准单文件组件编译。所有参考记录均为本地数据。

```
// Create the project first:
// npm create vite@latest naive-ui-specimen -- --template vue
// cd naive-ui-specimen && npm install
// In a Vite Vue 3 project:
// npm install naive-ui@2.45.3
// Save the complete component above as App.vue and layout as style.css.
import {createApp} from 'vue';
import App from './App.vue';
import './style.css';
createApp(App).mount('#app');
// index.html contains <div id="app"></div>.
// NConfigProvider, locales, themeOverrides and component imports are in App.vue.
// No Naive UI global CSS import is required for these components.
// Keep the template index.html and replace its entry with the code above.
// npm run dev
```

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

```
使用 Naive UI 2.45.3 参考审核队列，搭配 NConfigProvider 和原生 NDataTable 列、展开、排序、分页及选择功能。筛选或切换页面时，应保留稳定的参考键；批量操作应作用于选中记录，而非仅作用于当前可见行。空状态和禁用操作状态应与实际数据集一致。保留提供的 themeOverrides，将其作为区别于包默认值的应用级覆盖配置，并保持完整的原始布局。此队列用于本地参考审核，并非数据集导入服务。
```

## Naive UI 设计系统来源与范围

Naive UI 2.45.3。主题默认值与原有覆盖配置分别标明。审核记录和批量更改均保留在本地。

- 官方代码仓库 Vue 3、运行时样式和主题定制。

- DataTable 示例 原生数据表格模式和 API 示例。

- 通用浅色主题 实际默认调色板及其派生角色。

- 通用几何参数 字号、控件高度和圆角。

- 配置提供器 配置提供器主题配置。

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

### Nuxt UI

使用真实 Vue 组件、语义化主题引用、输入验证和明确的本地草稿行为，构建完整的 Nuxt UI 4.11.3 简报编辑器。

### Oruga UI

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

### Pico CSS

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


- [实现参考](https://github.com/tusen-ai/naive-ui/tree/main/src/data-table/demos/enUS)
- [来源](https://github.com/tusen-ai/naive-ui/blob/main/src/_styles/common/light.ts)
- [来源](https://github.com/tusen-ai/naive-ui/tree/main/src/config-provider)
- [阅读配套规范](https://github.com/tusen-ai/naive-ui/blob/main/src/_styles/common/light.ts)
- [阅读配套规范](https://github.com/tusen-ai/naive-ui/tree/main/src/data-table/demos/enUS)
- [阅读配套规范](https://github.com/tusen-ai/naive-ui)
- [阅读配套规范](https://github.com/tusen-ai/naive-ui/tree/main/src/config-provider)
- [代码参考](https://github.com/tusen-ai/naive-ui/tree/main/src/data-table/demos/enUS)
- [代码参考](https://github.com/tusen-ai/naive-ui)
- [官方代码仓库 Vue 3、运行时样式和主题定制。](https://github.com/tusen-ai/naive-ui)
- [DataTable 示例 原生数据表格模式和 API 示例。](https://github.com/tusen-ai/naive-ui/tree/main/src/data-table/demos/enUS)
- [通用浅色主题 实际默认调色板及其派生角色。](https://github.com/tusen-ai/naive-ui/blob/main/src/_styles/common/light.ts)
- [通用几何参数 字号、控件高度和圆角。](https://github.com/tusen-ai/naive-ui/blob/main/src/_styles/common/_common.ts)
- [配置提供器 配置提供器主题配置。](https://github.com/tusen-ai/naive-ui/tree/main/src/config-provider)