Tutorial: PhiaUI Design — Visual Editor + Claude Code

Build Phoenix LiveView pages visually or by describing them to Claude Code. Export production-ready HEEx/LiveView code from your designs.

What you'll learn

• How to start the visual editor with mix phia.design
• How to configure Claude Code with the MCP server
• How to build complete UIs using natural language
• How to export designs to production code
• How to analyze designs for hooks and dependencies

Prerequisites

• Elixir 1.17+ and Phoenix 1.7+ with LiveView 1.0+
• TailwindCSS v4 configured in your project
• PhiaUI installed: {:phia_ui, "~> 0.1.17"} in mix.exs
• Bandit in your deps: {:bandit, "~> 1.6"} (for the visual editor)
• Claude Code installed (for the AI workflow)

Part 1 — Visual Editor

Start the editor

mix phia.design              # Start on port 4200
mix phia.design --port 4201  # Custom port
mix phia.design --no-open    # Don't auto-open browser

The editor runs alongside your existing Phoenix app on a separate port.

Editor layout

The editor has three panels:

1. Left — Component Browser: Search and browse all 829 components by tier (primitive, interactive, widget, composite, surface, animation). Click to insert.

2. Center — Canvas: Live rendering of your design. Components render with real PhiaUI output (not placeholders). Click nodes to select. Toolbar provides:

   • Save/load designs as .phia.json files
   • Page templates (dashboard, settings, auth, landing, etc.)
   • Responsive preview (desktop / tablet / mobile)

3. Right — Properties + Code:

   • Properties tab: Edit selected node's attributes and slots
   • Code tab: Live HEEx preview of the current design

Page templates

Click "Templates" in the toolbar to start from a pre-built page:

Save and load

Designs are saved as .phia.json files in priv/phiaui_design/projects/. The format stores all nodes, their hierarchy, attributes, slots, and theme.

Part 2 — Claude Code + MCP

Configure MCP

Add the PhiaUI Design MCP server to your project's .mcp.json:

{
  "mcpServers": {
    "phiaui-design": {
      "command": "mix",
      "args": ["phia.design.mcp"],
      "env": {"MIX_ENV": "dev"}
    }
  }
}

Or add it globally to ~/.claude/.mcp.json.

How it works

The MCP server exposes 15 tools that Claude Code can call:

User describes UI → Claude browses catalog → inserts components →
configures attrs/slots → exports code → user gets a working LiveView

Available tools

Example prompts

Dashboard:

Design a SaaS analytics dashboard with a sidebar, 3 KPI stat cards,
a monthly revenue bar chart, and a data grid of recent orders.
Export as MyAppWeb.DashboardLive.

Login page:

Create a centered login page with email and password inputs,
a "Sign in" button, and a "Forgot password?" link.
Use the card component for the form container.

Landing page:

Build a landing page with an animated gradient background,
a glass card hero section, feature cards in a 3-column grid,
a pricing section, and a CTA at the bottom.

Settings page:

Design a settings page with tabs for Profile, Account, and
Notifications. Each tab has form sections with appropriate inputs.
Use the settings page template as a starting point.

Part 3 — Export & Analyze

Export to code

# Export as LiveView module
mix phia.design.export my_design.phia.json \
  --format liveview \
  --output lib/my_app_web/live/dashboard_live.ex \
  --module MyAppWeb.DashboardLive \
  --web-module MyAppWeb

# Export as HEEx template only
mix phia.design.export my_design.phia.json \
  --format heex \
  --output lib/my_app_web/templates/page.html.heex

# Print to stdout (for piping)
mix phia.design.export my_design.phia.json

Analyze a design

# Human-readable analysis
mix phia.design.analyze my_design.phia.json

# JSON output (for CI/scripts)
mix phia.design.analyze my_design.phia.json --json

Output includes:

• Total node count
• Unique components used
• Required JS hooks
• Install commands needed

Round-trip workflow

1. Design — use the visual editor or Claude Code MCP
2. Save — design is persisted as .phia.json
3. Export — generate LiveView module with mix phia.design.export
4. Compile — mix compile succeeds, page renders correctly
5. Iterate — re-open design, modify, re-export

Part 4 — Tips

Combining visual editor + Claude Code

You can use both tools together:

1. Start with a page template in the visual editor
2. Ask Claude Code to add specific components via MCP
3. Fine-tune attrs in the properties panel
4. Export the final result

Component families

Many components belong to families that work together:

• Card family: card, card_header, card_title, card_description, card_content, card_footer
• Form family: form_section, form_fieldset, form_grid, form_row, form_actions
• Data grid family: data_grid, data_grid_head, data_grid_cell, data_grid_row

When using Claude Code, mention the family name and it will compose components correctly.

Theme switching

Set the theme to rose

Claude will call set_phia_theme with rose. Available themes: zinc, slate, stone, gray, red, rose, orange, blue, green, violet.