贡献指南
向组件注册表贡献组件的完整指南
组件库结构
SSP UI Registry 基于 shadcn/ui Registry 进行能力管理，所有模块都存放在 registry/ssp 目录下：
registry/ssp/
├── theme/ # Tailwind 主题与设计令牌
├── ui/ # 基础组件（shadcn/ui 适配版）
├── block/ # 复合/场景化组件
├── hook/ # React Hooks
└── item/ # 工程模板与工具能力每个模块都包含 index.json 元数据、示例代码和 README，提交前请确保内容完整。
脚本工具
项目使用 Bun 作为包管理器，可通过 bun run 调用脚本：
创建组件/能力
bun run registry:create <name>
# 指定类型模板
bun run registry:create <name> --type theme
bun run registry:create <name> --type ui
bun run registry:create <name> --type block
bun run registry:create <name> --type hook
bun run registry:create <name> --type item生成文档
bun run registry:gen-doc <name> --type theme
bun run registry:gen-doc <name> --type ui
bun run registry:gen-doc <name> --type block
bun run registry:gen-doc <name> --type hook
bun run registry:gen-doc <name> --type item同步注册表
bun run registry:sync同步脚本会刷新 registry.json 与 public/r/ 下的公共索引，请在提交前执行。
组件类型
Theme
- 位置：
registry/ssp/theme/ - 用途：Tailwind v4 主题配置、Design Token、样式输出
- 文档：
content/docs/ssp/theme/
UI 基础组件
- 位置：
registry/ssp/ui/ - 用途：基础 UI 组件，主要基于 shadcn/ui 调整
- 文档：
content/docs/ssp/ui/
Blocks 高阶组件
- 位置：
registry/ssp/block/ - 用途：复合组件、特效组件、业务组件
- 文档：
content/docs/ssp/block/
Hooks
- 位置：
registry/ssp/hook/ - 用途：React 自定义 Hooks
- 文档：
content/docs/ssp/hook/
Items 工程能力
- 位置：
registry/ssp/item/ - 用途：工程模版、网络请求封装、配置生成器等
- 文档：
content/docs/ssp/item/
贡献流程
- 选择类型：根据要贡献的内容确定所属目录（theme/ui/block/hook/item）
- 创建模板：运行
bun run registry:create生成基础文件 - 开发实现：补充组件/能力逻辑、类型定义与示例代码
- 编写文档：使用
bun run registry:gen-doc生成文档骨架并完善内容 - 更新元信息：补充
index.json、README 等元数据 - 同步注册表：执行
bun run registry:sync更新registry.json - 本地验证：可选运行
bun run registry:build与bun run lint确认构建与格式正确 - 提交 PR：附带变更说明与测试结果
代码规范
- 语言：使用 TypeScript，导出严格类型
- 风格与格式化：通过
bun run lint调用 Biome 进行代码检查与格式化（无需 ESLint/Prettier） - 样式：优先使用 Tailwind CSS 原子类，复用 Theme 定义的 Design Token
- 命名：遵循 kebab-case 文件命名、PascalCase 组件命名、camelCase 函数命名
- 文档：示例代码需可直接运行，README 描述使用场景与配置方式
下一步
根据要贡献的能力类型，继续阅读对应的详细指南：