Spell UI 是一个高质量的开源 React 组件库，目前已收录 33+ 个基于 React 和 Tailwind CSS 的动画、按钮、输入框等组件，覆盖动画、交互、展示三大场景。本文是一份面向新手贡献者的完整指南：你不需要搭建复杂的工程，只需修改 4 个文件，就能把自己的组件提交进这个组件库，并获得一个专属的文档页 🚀

一、环境准备：5 分钟克隆仓库并跑通本地项目

在动手写组件前，先把仓库跑起来，方便随时本地预览效果。

1. Fork 仓库：点击仓库页面的 Fork 按钮，复制一份到你自己的账号下。
2. 克隆到本地（本镜像地址可直接使用）：

git clone https://gitcode.com/gh_mirrors/sp/spell-ui cd spell-ui

3. 安装依赖并启动：项目使用 pnpm 管理依赖（版本要求见 package.json）。

pnpm i pnpm dev

启动后打开http://localhost:3000，就能看到组件库的文档站。

💡 建议：写新组件前先浏览几个现有组件的文档页（如 Shimmer Text、Marquee），感受一下文档和演示的呈现风格。

二、核心流程：只改 4 个文件，你的组件就"上架"了

Spell UI 采用registry 注册表机制：侧边栏导航和文档目录都会根据注册表自动生成，所以你不需要手动改导航，只需改下面 4 个文件（以example-component为例）：

文件 1：创建组件本体

在registry/spell-ui/目录下新建一个.tsx文件。这是唯一"真正写代码"的文件——用 TypeScript + Tailwind CSS 实现你的组件即可。

参考优秀范例 registry/spell-ui/shimmer-text.tsx：注意它顶部用"use client"标记客户端组件，并用cn()做样式合并。

文件 2：在 registry.json 中注册

打开 registry.json，在items数组里追加一段配置，关键字段包括：

• name：组件唯一标识（小写中划线，如example-component）
• type：固定为registry:component
• title/description：展示在文档站的名称与简介
• files：指向组件源码的路径
• category：所属分类，可选animation、button、input、feedback、background、interactive、display等（见 lib/doc.ts）

如果组件依赖第三方包（如动画库），把包名填进dependencies字段即可。

文件 3：编写演示 demo.tsx

在docs/example-component/目录下新建demo.tsx，导入刚写的组件并渲染出来。文档站的"实时预览区"就来自这个文件。

范例可参考 docs/shimmer-text/demo.tsx——只需要几行代码。

如果想展示多种变体（不同尺寸、颜色、速度等），可以额外创建demo-sizes.tsx、demo-colors.tsx等文件，文档站已有大量这样的多示例组件（如docs/spinner/、docs/badge/），直接照着抄结构即可。

文件 4：撰写文档 doc.mdx

新建docs/example-component/doc.mdx，推荐四段式结构（完整模板见 docs/shimmer-text/doc.mdx）：

1. <DemoCanvas>：实时演示 + 可展开源码
2. ## Installation：安装命令，用<InstallationTabs>包裹
3. ## Usage：两三行使用示例
4. ## Props：用<PropsTable>列出参数名、类型、说明

三、构建注册表并本地验收

4 个文件改完后，执行一条命令生成 CLI 安装所需的注册表文件：

pnpm registry:build

它会在public/r/下生成example-component.json（可对照 public/r/registry.json 查看产物结构）。此时刷新本地文档站，你的组件应已自动出现在侧边栏和文档目录中——这一切由 lib/doc.ts 的getDocSchema从注册表自动生成，零手动配置。

四、提交 PR 与社区约定

📦提交你的组件：从你 Fork 仓库的新分支（如my-new-component）向主仓库发起 Pull Request，附上组件的预览动图，会大大提高合并效率。

组件写作规范速查（来自 CONTRIBUTING.md）：

遇到问题？直接在仓库里开一个 Issue 提问即可。

写在最后

回顾一下全流程：Fork → 克隆 → 改 4 个文件 →pnpm registry:build→ 提交 PR。整套流程对新手非常友好，你的第一个组件也许一晚上就能合入。现在就挑一个你最想实现的 UI 效果，动手把它变成 Spell UI 的第 34 个组件吧 ✨