Petal Components：让 AI 助手按真实 schema 写 Phoenix HEEx 组件

它解决的是 AI 写错组件属性这个问题

Phoenix 开发者用 LiveView 写界面时，最常见的痛点不是不会写 HEEx，而是记不住每个组件的属性名。shadcn 在 React 世界解决了样式复用，但它的组件是复制进项目的文件，AI 工具在生成 JSX 时仍可能凭空捏造类名。Petal Components 换了一条路：它把组件做成 Hex 包，同时提供一个托管在 mcp.petal.build 的 MCP 服务器。这个服务器暴露每个组件的真实 schema，AI 编码工具在生成代码前可以调用 list_components 和 get_component，拿到准确的属性列表，而不是从训练数据里猜。文档里那句「AI assistants can actually use」不是营销话术，它指的就是这个机制。

从安装到调用的机制拆解

安装分两条路径。推荐路径是先用 claude mcp add petal --transport http https://mcp.petal.build/mcp 注册 MCP 服务器，然后在项目里告诉 AI「install petal_components」。AI 代理会调用 get_install_instructions，自动修改 mix.exs、运行 mix deps.get、修补 assets/css/app.css，并在 web 模块里加上 use PetalComponents。这个设计把项目结构的差异交给 AI 处理，而不是让安装脚本去特判每个项目。手动路径则清晰得多：在 mix.exs 添加 {:petal_components, "~> 4.0"}，在 app.css 里加 @source "../deps/petal_components/**/*.*ex" 和 @import "../deps/petal_components/assets/default.css"，最后在 MyAppWeb 的 html 块里 use PetalComponents。注意文档提到，只有密码输入、可复制输入和聊天组件需要注册 JS hooks，其余组件纯靠 CSS 和 LiveView.JS。这意味着大部分场景下你不需要碰 JavaScript。

组件目录：30 多个标签覆盖常见模式

组件按功能分成五类。布局类有 container、card、accordion、tabs、stepper，表单类有 field、text_input、select、checkbox、switch、date_input，操作类有 button、dropdown、menu，反馈类有 modal、slide_over、popover、tooltip，数据展示类有 table、pagination、badge、avatar。文档强调 MCP 服务器是权威清单，调用 list_components 能拿到完整列表，这暗示 README 里列出的只是精选。从示例看，组件的 API 设计贴近 Phoenix 习惯，比如 <.field field={@form[:name]} label="Name" /> 直接接受 Ecto 变更集字段，而不需要手动处理错误信息。表格组件用 <:col> 插槽定义列，配合 :let={user} 解构每一行，这个模式对熟悉 Phoenix 插槽的开发者来说很自然。

与 shadcn 的差异：不是复制，是换运行时

项目主页专门有一页对比 shadcn，说明作者清楚这两者的相似性会引发误解。相同点是哲学：可组合的原子组件、不搞 monolithic 主题系统、AI 工具读取 schema。不同点在于运行时和分发方式。shadcn 是 CLI 工具，把组件文件复制进你的仓库，样式基于 Tailwind 3 加 CSS 变量；Petal Components 是 Hex 包，用 Tailwind v4 的 @source 指令扫描依赖目录，更新走 mix deps.update。这个差异有实际后果：shadcn 的组件复制进来后你可以随意改，但升级时要手动合并；Petal Components 升级是自动的，但如果你想深度定制某个组件，得用覆盖机制或 fork，文档没有详细说明覆盖方式。另外，Petal Components 同时支持 LiveView 和 dead view，这是 JSX 组件做不到的。

局限：MCP 依赖与版本前提

最明显的限制是 MCP 服务器是托管的，不是自托管的。如果你的团队在隔离网络环境工作，或者 AI 工具不支持 MCP 协议，那么核心卖点就失效了，剩下的只是一个普通的组件库。文档没有提供自托管 MCP 服务器的方案，这是一个值得在采用前确认的点。另一个限制是 Tailwind v4 是硬性要求。示例里的 @source 指令和 default.css 导入都基于 v4 的语法，如果你的项目还在用 Tailwind 3，直接引入会报错。还有，chat markdown 组件需要额外依赖 mdex，这是可选的，但如果你用到了 Chat.markdown 而忘记加这个依赖，编译期才会暴露问题。

替代方案：LiveView 原生组件与 shadcn 风格移植

不引入 Petal Components 的话，你有两个现实选择。第一个是直接用 Phoenix 自带的 core_components，它随新项目生成，提供 button、modal、table 等基础组件，但样式朴素，需要自己用 Tailwind 打磨，也没有 MCP 集成。第二个是像 shadcn 那样自己维护一组 HEEx 组件文件，用 Tailwind v4 的 @source 指向自己的组件目录。这个方案的好处是完全可控，坏处是 AI 工具没有 schema 可读，生成代码时依然会乱猜属性。Petal Components 的差异化在于它把 schema 作为一等公民，这是前两者都没有的。如果你的团队 AI 使用频率低，或者你更信任手写代码，那么 core_components 加少量自定义组件可能更轻量。

维护与升级成本

仓库的发布记录显示 v3.2.2 在 2026 年 5 月发布，距离 v3.2.0 只有六周，说明迭代速度不慢。作为 Hex 包，升级路径是标准的 mix deps.update petal_components，但你需要留意 changelog 中的破坏性变更，尤其是表单和模态框的 API。文档提到 petal_pro 是基于这个库的商业 SaaS 样板，这意味着组件库的维护动力来自上游商业项目，短期内不太可能停止维护。许可证是 MIT，可以自由使用和修改，但如果你修改了组件，需要自己维护 fork 的同步。JS hooks 的注册方式在安装文档里有明确说明，不注册的话密码输入和聊天组件会失效，这是升级后最容易踩的坑。

编辑结论

Petal Components 适合正在用 Phoenix LiveView 开发、并且依赖 Claude Code、Cursor 等 AI 辅助编码的团队。它把组件发现成本从人工查文档转移到 MCP 调用，对频繁使用表单、模态框、表格的 CRUD 应用能明显减少手写 HEEx 的重复劳动。不适合以下场景：你的项目仍停留在 Tailwind v3 且短期内不打算迁移到 v4，或者你对引入一个需要维护 JS hooks 的依赖持保守态度。采用前先验证三件事：确认你的 Phoenix 项目能接受 Tailwind v4 的 @source 配置；在 mix deps.get 后检查 assets/css/app.css 的导入顺序是否正确；如果用到密码输入或聊天组件，确认 JS hooks 已合并进 LiveSocket。组件库的更新节奏很快，v3.2.0 到 v3.2.2 间隔不到两个月，升级前应查看 changelog，尤其是表单和模态框的 API 是否变动。MIT 许可证允许商业使用，但 petal_pro 作为独立产品不在本仓库范围内。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes