appCN

---

快速开始

CLI 会帮你配置 NativeWind + Reanimated，并注册 @app-cn shadcn 命名空间。一个命令完成设置，再用一个命令添加组件。

# 1. (Recommended) One-shot project setup
npx @app-cn/cli@latest init

# 2. Add any component by slug
npx @app-cn/cli@latest add voice-sphere

想使用自己的工作流？appcn add 是 shadcn 的轻量封装——你可以 完全跳过 CLI：

# Copy a single component via shadcn (no setup, one-off)
npx shadcn@latest add https://appcn.vercel.app/r/voice-sphere.json

# Or pull the whole library as a managed dep
npm install @app-cn/ui

正在使用 AI Agent 构建应用？添加 appCN MCP 服务，让 Claude Code、Cursor 或 Windsurf 帮你发现并安装组件，还能按照 appCN 的动画/触觉风格编写新代码：

# Claude Code
claude mcp add appcn -- npx -y @app-cn/mcp

Cursor / Windsurf / VS Code 配置请参阅 MCP 文档。

状态：v0.1.0 已在 npm 发布。 已推出五个组件——AI 组件集合是主打特色， 也是新功能开发的首要方向。

---

包含内容

新功能： appCN 已可在真实手机上运行——使用 Expo Go 扫描二维码， 几秒钟内即可在 Android 或 iPhone 上加载完整的组件库。 无需模拟器，也无需开发者账号。独立的 Play Store APK 正在审核中—— 即将发布。

基础组件

组件	亮点
Button	按下时以弹簧动画缩放至 0.96，并在 140 ms 内稳定下来——手感厚实，绝不飘忽

原生 AI

组件	亮点
StreamBubble	三阶段：思考 → 令牌流 → 完成
PromptInput	发送按钮变为带旋转环的停止按钮
ReasoningTrace	答案一出现，便自动折叠
VoiceSphere	会随语音音量起伏呼吸的响应式 3D 球体

每个组件都有交互式网页预览、可用 Expo Go 扫描运行的二维码，以及一段视频——所有平台使用相同的代码路径。→ appcn.vercel.app/components

---

为什么选择 appCN

• 真机预览。 用 Expo Go 扫描二维码，组件即可在设备上实时运行，并支持原生手势。无需折腾模拟器。
• 旗舰级原生 AI 体验。 AI 组件集是我们的差异化优势——专为 AI 应用打造的组件，其他产品都做不好。
• 四种分发方式。 使用 appcn CLI、shadcn registry、npm 上的 @app-cn/ui，或通过 MCP 服务让 AI 编码 Agent 为你安装组件。同一套基础组件，任你选择。
• 默认优先考虑动效。 使用 Reanimated + gesture-handler、共享动效令牌（duration / easing / spring），并为每个组件加入一处令人惊喜的细节。
• 优先支持深色模式。 先按深色模式设计，再适配浅色模式。高级感来自层次，而非彩虹色。
• 源代码由你掌控。 复制粘贴的理念意味着没有锁定——组件加入你的代码库后，你可以自由编辑。

---

文档

平台	内容
appcn.vercel.app	在线文档网站——首页、所有组件和实时预览
CLI 文档	init、add、环境变量和幂等性约定
移动应用	Play Store + Expo Go 安装方式、深度链接约定
CLAUDE.md	架构、单体仓库概览、命令、Metro/Reanimated 注意事项
DESIGN.md	品味准则——动效规则、“一处令人惊喜的细节”规则、8 步 SOP
CONTRIBUTING.md	开发环境设置、Changesets 发布流程、PR 规范
AGENTS.md	面向 AI 编码 Agent 的跨工具指南（Claude / Cursor / Windsurf / Codex / Aider）

---

参与贡献

每个新组件都必须遵循 DESIGN.md → 组件检查清单中的 8 步 SOP。请勿跳过步骤——PR 模板会强制检查，缺少 changeset 则会阻止发布流程。

使用 AI Agent 进行开发？调用 /new-component Claude 技能——它会引导你完成检查清单，生成可填写的类型化 <slug>.meta.ts 模板，接入 registry 和展示页面条目，并通过类型检查和 registry 构建进行验证。

完整指南：CONTRIBUTING.md。

---

发布

发布由 Changesets 驱动，并通过 OIDC Trusted Publishing 发布到 npm——无需长期有效的密钥。

pnpm changeset           # describe what changed + pick a bump
git commit -am "..."     # commit the changeset alongside your code
# Open a PR. After merge to main, a "Version Packages" PR opens automatically.
# Merge that PR → CI publishes via OIDC.

每个已发布版本都会在 npm 上获得经过验证的来源徽章。

---

部署

此网站由同一个单体仓库中的两个 Vercel 项目构成 — 点击查看设置。

项目	Vercel 根目录	提供的内容
文档	apps/web	首页、/components/*、/docs/*、位于 /r/*.json 的 shadcn 注册表
展示站	apps/showcase	Expo Web 导出 — 交互式预览的 iframe 目标

部署顺序（很重要）：

1. 先部署展示站（apps/showcase），获取其 URL。
2. 部署文档站，将 NEXT_PUBLIC_SHOWCASE_WEB_URL 设置为该 URL。
3. 可选：配置自定义域名（appcn.vercel.app → 文档站，appcn-showcase.vercel.app → 展示站）。

必需的环境变量（文档项目）：

变量	值
NEXT_PUBLIC_SHOWCASE_WEB_URL	https://<showcase-project>.vercel.app
NEXT_PUBLIC_EXPO_URL	（v1 设为空 — QR 标签页需要 EAS Update）
NEXT_PUBLIC_REGISTRY_URL	https://<docs-domain>/r

展示站项目无需环境变量。默认值位于 apps/web/.env.example。

---

致谢

灵感来自 shadcn/ui 的复制粘贴理念，以及 react-native-reusables 精致的 文档站点。构建于 NativeWind、 Reanimated 和 Expo 之上。

---

许可证

MIT — 代码归你所有。