contributing

用途

本指南用于指导开发者参与 Nuxt UI 组件库的贡献开发，涵盖项目结构、组件脚手架、主题编写、测试与文档约定。

项目结构

src/
├── runtime/
│   ├── components/     # Vue components (PascalCase.vue)
│   ├── composables/    # Composables (use*.ts)
│   ├── types/          # TypeScript types
│   └── utils/          # Utility functions
├── theme/              # Tailwind Variants themes (kebab-case.ts)
└── module.ts
test/
├── components/         # Component tests (*.spec.ts)
│   └── __snapshots__/  # Auto-generated snapshots
└── component-render.ts
docs/
└── content/docs/2.components/  # Documentation (*.md)
playgrounds/
└── nuxt/app/pages/components/  # Playground pages

脚手架 CLI

首次需先链接 CLI（一次性设置）：

npm link

随后可用它创建新组件：

nuxt-ui make component <name> [options]

选项：

• --primitive — Primitive 组件（使用 Reka UI Primitive）
• --prose — 散文/排版组件
• --content — 内容组件
• --template — 仅生成指定模板（playground、docs、test、theme、component）

可用参考文档

文件	主题
references/component-structure.md	Vue 组件文件模式、props/slots/emits 接口、script setup
references/theme-structure.md	Tailwind Variants 主题文件、slots、variants、compoundVariants
references/testing.md	Vitest 模式、快照测试、可访问性测试
references/documentation.md	组件文档结构、MDC 语法、示例

加载文件时应按任务选择，不要一次性全部加载：

• 创建/修改 Vue 组件时加载 references/component-structure.md
• 处理组件主题时加载 references/theme-structure.md
• 编写或审查测试时加载 references/testing.md
• 编写组件文档时加载 references/documentation.md

组件创建流程

创建新组件时可参照以下清单：

• [ ] 1. 使用 CLI 脚手架：nuxt-ui make component <name>
• [ ] 2. 在 src/runtime/components/ 中实现组件
• [ ] 3. 在 src/theme/ 中创建主题
• [ ] 4. 从 src/runtime/types/index.ts 导出类型
• [ ] 5. 在 test/components/ 中编写测试
• [ ] 6. 在 docs/content/docs/2.components/ 中创建文档
• [ ] 7. 添加 playground 页面
• [ ] 8. 运行 pnpm run lint
• [ ] 9. 运行 pnpm run typecheck
• [ ] 10. 运行 pnpm run test

PR 审查清单

审查组件 PR 时核查：

• [ ] 组件遵循现有模式（见 references/）
• [ ] 主题使用语义色，而非 Tailwind 调色板
• [ ] 测试覆盖 props、slots 与可访问性
• [ ] 文档包含 Usage、Examples 和 API 部分
• [ ] 采用 Conventional commit 提交信息格式
• [ ] 所有检查通过（lint、typecheck、test）

代码约定

约定	说明
类型导入	始终单独一行：import type { X }
Props 默认值	运行时用 withDefaults()，文档用 JSDoc @defaultValue
模板插槽	所有元素添加 data-slot="name" 属性
计算 ui	始终用 computed(() => tv(...)) 实现响应式主题
主题支持	用 useComponentUI(name, props) 合并 Theme 上下文与组件的 ui prop
语义色	使用 text-default、bg-elevated 等，绝不用 Tailwind 调色板
Reka UI props	用 reactivePick + useForwardPropsEmits 转发 props
表单组件	使用 useFormField 与 useFieldGroup composables

常用命令

pnpm run dev:prepare  # Generate type stubs (run after install)
pnpm run dev          # Nuxt playground
pnpm run dev:vue      # Vue playground
pnpm run docs         # Documentation site
pnpm run lint         # Check linting
pnpm run lint:fix     # Fix linting
pnpm run typecheck    # Type checking
pnpm run test         # Run tests

资源

• Contribution Guide
• Nuxt UI GitHub

限制

资料未提供具体的收费、价格、平台支持范围或效果数据。