# Wireframe tool - agent guide

Free online wireframe tool: https://john-richardson.net/tools/wireframing
This file: https://john-richardson.net/tools/wireframing/agents.txt  (HTML version: https://john-richardson.net/tools/wireframing/agents)

Everything runs in the user's browser. There is no API, account or server. Return the layout as plain text in a single fenced code block. The user copies the text, opens the tool, clicks "Import", and pastes it into the import dialog.
Do not encode the layout into a URL or generate a #layout= link unless the user explicitly asks for one. Layout URLs get too long for larger designs.

## Layout format (text)

One element per line:

    type [x y w h] ["text"]

- type: one of the element types below.
- x y w h: pixels, origin top-left. Give all four, or give none (see auto-layout).
- "text": optional, always in double quotes. Leave out to use the element's default text.
- "frame browser" or "frame phone" on its own line starts a section for that frame. Without it the layout goes into the frame the user currently has open.
- Lines starting with # or // are ignored.
- Line order is stacking order: later lines draw on top.

Frames:
- browser: 1200 px wide.
- phone: 390 px wide.
- The page grows downwards automatically, so any height works. x + w should not exceed the frame width.

Auto-layout: lines with no numbers are stacked top to bottom, 20 px apart. Full-width elements (navbar, hero, footer) span the frame; others are centred at their default size. Use explicit coordinates for columns (e.g. three cards side by side).

Tips for a good wireframe:
- Work top to bottom: navbar, hero, content sections, call to action, footer.
- Align to a 20 px grid (multiples of 20 for x, y, w, h).
- Browser: keep content in a column from x=100 to x=1100. Three cards: x=100, 450, 800 at w=300.
- Phone: keep a 20 px margin (x>=20, x+w<=370), stack vertically, prefer navbar (shows a burger menu), hero, then single-column content.
- Keep text short. Wireframes show structure, not copy.
- Aim for 8 to 30 elements.

## Notes (feedback from the user)

A line starting with note directly after an element attaches a note to that element:

    hero 0 90 1200 400 "Plan trips together"
    note "Headline too long; make the call to action more prominent"

(In JSON use a "note" field.) When the user pastes a layout that contains notes, treat each note as a change request for the element above it. Apply the changes and return the full updated layout in one code block, leaving the note lines out unless you are asking a question.

## JSON format (also accepted)

    { "frame": "browser", "elements": [ { "type": "hero", "x": 0, "y": 90, "w": 1200, "h": 400, "text": "Headline" } ] }

or { "browser": [ ... ], "phone": [ ... ] }, or just an array of elements.

## Element types

- rect  (Basic; default 200 x 120; text = optional label centred in the box)
- circle  (Basic; default 120 x 120; no text)
- heading  (Basic; default 360 x 40; default text "Heading"; text = the heading text)
- paragraph  (Basic; default 360 x 80; no text)
- button  (Basic; default 140 x 44; default text "Button"; text = button label)
- divider  (Basic; default 360 x 20; no text)
- image  (Media; default 280 x 180; default text "Image"; text = caption under the placeholder icon)
- video  (Media; default 400 x 225; no text)
- avatar  (Media; default 64 x 64; no text)
- logo  (Media; default 150 x 44; default text "Logo"; text = wordmark next to the logo mark)
- input  (Forms; default 280 x 44; default text "Placeholder"; text = placeholder text)
- checkbox  (Forms; default 200 x 28; default text "Checkbox label"; text = label)
- list  (Forms; default 280 x 140; no text)
- form  (Forms; default 360 x 340; default text "Contact us"; text = form title (Name, Email, Message and Submit are drawn automatically))
- navbar  (Navigation; default full width x 70; default text "Logo"; text = logo text)
- floatnav  (Navigation; default 480 x 56; default text "Home, Range, Research, How to use"; text = comma-separated menu items (first is highlighted))
- menu  (Navigation; default 360 x 32; default text "Home, About, Pricing, Contact"; text = comma-separated menu items (first is underlined))
- burger  (Navigation; default 44 x 44; no text)
- dropdown  (Navigation; default 180 x 40; default text "Select option"; text = placeholder text)
- menulist  (Navigation; default 190 x 170; default text "Profile, Settings, Billing, Sign out"; text = comma-separated menu items)
- usermenu  (Navigation; default 84 x 40; text = optional user name)
- hero  (Blocks; default full width x 360; default text "Hero headline"; text = headline)
- features  (Blocks; default 800 x 200; no text)
- cta  (Blocks; default 800 x 160; default text "Ready to get started?"; text = banner heading)
- card  (Blocks; default 280 x 320; default text "Card title"; text = card title)
- pricing  (Blocks; default 260 x 360; default text "Pro plan"; text = plan name)
- testimonial  (Blocks; default 400 x 200; default text "Customer name"; text = person name)
- accordion  (Blocks; default 360 x 220; default text "Question one, Question two, Question three"; text = comma-separated row titles (first row is open))
- tabs  (Blocks; default 420 x 160; default text "Overview, Details, Reviews"; text = comma-separated tab names (first is active))
- slider  (Blocks; default 600 x 300; no text)
- table  (Blocks; default 560 x 220; no text)
- modal  (Blocks; default 420 x 260; default text "Modal title"; text = modal title)
- footer  (Blocks; default full width x 140; no text)

Aliases accepted for convenience: box, square, img, photo, header, nav, title, text, btn, field, select, carousel, faq, quote, banner.

## Example

frame browser
navbar 0 0 1200 70 "Acme"
hero 0 90 1200 400 "Plan trips together"
card 100 520 300 320 "Flights"
card 450 520 300 320 "Hotels"
card 800 520 300 320 "Cars"
cta 100 880 1000 160 "Join the beta"
footer 0 1080 1200 140

frame phone
navbar 0 0 390 70 "Acme"
hero 0 90 390 360 "Plan trips together"
card 50 480 290 320 "Flights"
footer 0 840 390 140

Auto-layout example (no coordinates):

navbar "Acme"
hero "Plan trips together"
features
cta "Join the beta"
footer

## Giving the user a layout

Return one fenced code block containing the complete layout text, with both "frame browser" and "frame phone" sections when requested. Keep explanations outside the code block so the contents can be copied directly into the tool.

Tell the user to:
1. Open https://john-richardson.net/tools/wireframing.
2. Click "Import" in the toolbar (or "Import layout..." in the project menu).
3. Paste the layout text and click "Replace canvas". Use "Add to canvas" to keep existing elements.

A normal link to the tool is fine; do not put the layout text in the link.

## For agents that control a browser

On the tool page, window.wireframe is available:
- window.wireframe.load(text, { add: false })  - import layout text or JSON; returns { added, warnings }. add: true appends instead of replacing.
- window.wireframe.export()  - current layout as text.

## Notes

- Exports: the tool exports PNG. Projects are saved in the user's browser only.
- Questions or feature requests: https://john-richardson.net/contact