Usage Guide

🚀 Launching the App

Just run the following command in your terminal. No additional installation is needed as long as you have Node.js.

npx poseidon-flow@latest

If your browser doesn't open automatically, navigate to http://localhost:7437.

🖥 Interface Overview

📄 Adding, Editing & Deleting Pages

Adding a Page

Editing a Page

Click any page node on the canvas to open the edit form in the right panel. You can freely modify the page name, path, prompt (AI generation hint), and components. Enter prompts in bullet-point format — one item per line.

Duplicating a Page

Cmd + D (Windows: Ctrl + D) is not yet implemented. To duplicate a page, add a new one via the "+ Add Page" button and copy the details manually in the right panel.

Deleting a Page

Select the page you want to remove and press Delete or Backspace. You can also select multiple pages and delete them all at once.

🔗 Connecting Pages (Creating Transitions)

To create a transition (arrow) between pages, drag from a handle on the edge of a node.

To delete a transition, click the arrow to select it and press Delete.

🖱 Canvas Navigation

☑️ Multi-Selection

Use multi-selection when you want to move or delete several pages at once.

🧩 Components

Record which UI elements are included in each page. Think of it as a living spec sheet for your page design.

Page Type & Auth Flag

In addition to components, you can also set the page type and authentication requirement in the right panel.

🔒 Lock Feature

Both components and pages can be locked individually.

📁 Project Management

Save and switch between multiple named site designs. Click the project button in the toolbar (◫ Untitled ▼) to manage projects.

Saving a Project

Switching Projects

Click a project name in the project list to switch to that design. The current project is indicated with a ●.

Directory Association

You can associate a local directory path with each project — useful for keeping track of which codebase a design corresponds to.

📋 Sample Templates

Click "◈ Samples ▾" in the toolbar to open a dropdown of industry-specific templates. Choose from 7 samples to load instantly.

E-Commerce Sample Page Structure

The e-commerce sample includes the complete purchase flow (26 pages, 37 transitions):

Use this as a starting point to get a feel for how Poseidon Flow works.

📤 Export

Click the "⇣ Export / Import" button in the toolbar to open the modal, where you can preview Mermaid diagrams, generate an AI brief, export files, and import — all in one place.

Mermaid Tab (sitemap / pages / flows)

Export Buttons

Using Mermaid Output

Paste the contents of an exported .mmd file into GitHub Markdown and it will render as a diagram:

```mermaid
graph TD
  Home --> ProductList
  ProductList --> ProductDetail
  ProductDetail --> Cart
  Cart --> OrderComplete
```

📥 Import

Load a previously exported JSON or Mermaid file to resume work from where you left off.

⌨️ Keyboard Shortcuts

🤖 AI Wireframe / Design Generation

There are two ways to generate wireframes and designs automatically.

Method 1 — Generate from the Right Panel

Method 2 — Ask Claude Code (MCP)

With MCP configured, you can chat with Claude Code to generate everything in bulk.

Check the site structure with get_project_summary, then
generate HTML wireframes for each page in order and
save them with set_wireframe_html.

Design Generation (DESIGN.md)

Write a design system definition (DESIGN.md) in the "AI" tab of the "⇣ Export / Import" modal. Claude Code will then generate realistic HTML designs that reflect your brand colors, fonts, and component styles.

AI Brief Panel (🤖 Brief)

Click the "🤖 Brief" button in the toolbar to generate and copy a Markdown summary of your entire project structure. Paste it directly into Claude or any other AI chat for context.

🎨 Figma Export

Send your generated wireframes or designs directly to a Figma file.

Using Claude Code (Recommended)

The "Send to Figma" button in the UI uses Claude Code's Figma MCP credentials (~/.claude/.credentials.json).

Using Other AI Agents (Cursor / Copilot, etc.)

The "Send to Figma" button is exclusive to Claude Code, but by combining the poseidon-flow MCP + your AI's Figma MCP, you can achieve the same result.

Preview URL format:

http://localhost:7437/preview/wireframe/{pageId}/content
http://localhost:7437/preview/design/{pageId}/content

Example instruction to your AI:

Send the poseidon-flow brd-home page (URL: http://localhost:7437/preview/wireframe/brd-home/content)
to Figma using the generate_figma_design tool with fileKey=AbCdEfG123.

🔌 MCP Integration (Claude Code / AI Agents)

Poseidon Flow includes a built-in MCP (Model Context Protocol) server. Connect it to an AI agent to read and write project page data, and have the AI automatically generate and save wireframes.

Setup — Global Configuration

Add the following to ~/.claude/settings.json:

{
  "mcpServers": {
    "poseidon-flow": {
      "command": "npx",
      "args": ["poseidon-flow", "--mcp"]
    }
  }
}

Setup — Project-Local Configuration

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "poseidon-flow": {
      "command": "npx",
      "args": ["poseidon-flow", "--mcp"]
    }
  }
}

Available Tools

Example Instructions to AI