petal_components

<p align="center">
  <img src="https://res.cloudinary.com/wickedsites/image/upload/v1635752721/petal/logo_rh2ras.png" height="96">
</p>

<h1 align="center">Petal Components</h1>

<p align="center">
  <strong>Shadcn-style Phoenix components that AI assistants can actually use.</strong>
</p>

<p align="center">
  <a href="https://hex.pm/packages/petal_components"><img alt="Hex Version" src="https://img.shields.io/hexpm/v/petal_components.svg"></a>
  <a href="https://hexdocs.pm/petal_components"><img alt="Hex Docs" src="https://img.shields.io/hexpm/dt/petal_components.svg?style=flat"></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
</p>

<p align="center">
  <a href="https://petal.build/components">Live docs</a> ·
  <a href="https://mcp.petal.build">MCP server</a> ·
  <a href="./usage-rules.md">Rules for AI tools</a> ·
  <a href="https://petal.build/petal-components/vs-shadcn">vs shadcn</a>
</p>

---

## The 30-second pitch

Petal Components gives Phoenix LiveView apps a shadcn-style set of HEEx components: buttons, forms, modals, tables, cards, and more. They are built with Tailwind v4 and work in live or dead views.

The companion piece is a hosted MCP server at `mcp.petal.build` that exposes every component's real schema to AI coding tools. Install it once and Claude Code, Cursor, Codex, and Windsurf reach for the existing components instead of inventing raw Tailwind markup from training data.

If you have used shadcn in React, you already know the shape. Same idea, composable primitives, you own the patterns, AI tools read the schema and call it correctly. We just write HEEx, not JSX.

## Install

### The two-step way (recommended)

```sh
# 1. Install the MCP server once
claude mcp add petal --transport http https://mcp.petal.build/mcp
```

Then in any Phoenix project:

```
2. Tell your AI: "install petal_components"
```

The agent calls `get_install_instructions` on the MCP, applies the changes to your `mix.exs`, runs `mix deps.get`, patches `assets/css/app.css`, and adds `use PetalComponents` to your web module. Works in umbrella apps and standard Phoenix projects. The AI handles project shape variance the install would otherwise have to special-case.

Cursor, Windsurf, Continue, Codex, and Cline have their own MCP install commands - see https://petal.build/petal-components for snippets per tool.

### The manual way

If you'd rather install yourself, in `mix.exs`:

```elixir
def deps do
  [
    {:petal_components, "~> 4.0"},
    # optional — only needed for the chat markdown components (<Chat.markdown>, <Chat.rich_text>)
    {:mdex, "~> 0.12"}
  ]
end
```

In `assets/css/app.css`:

```css
@import "tailwindcss";
@source "../../deps/petal_components/**/*.*ex";
@source not "../../deps/petal_components/lib/petal_components/showcase";
@import "../../deps/petal_components/assets/default.css";
@plugin "@tailwindcss/forms";
```

In your `MyAppWeb` module:

```elixir
def html