clide/.claude/skills/frame0-wireframe/SKILL.md

name, description

name

description

frame0-wireframe

Create and export UI wireframes using Frame0 (local desktop wireframing app with HTTP API). Use when the user says "create wireframe", "wireframe this", "mock up the UI", "draw a screen", "UI layout", "wireframe the HUD", "Frame0", "frame0", "export wireframe", or invokes /frame0-wireframe. Wireframes are authored as local JSON files (source of truth) and synced to Frame0 for rendering and export. Requires Frame0 to be running locally.

Frame0 Wireframe Generation

Create UI wireframes as JSON files, sync them to Frame0 for rendering, and export as PNG. Local JSON is the source of truth — Frame0 is the renderer.

Frame0 is a renderer, not a workspace. Treat it as disposable output. Push freely, delete test pages, keep it clean. Never pull from Frame0 unless the user explicitly says they have made edits in Frame0 and want to import them. The pull workflow exists for that case only — do not use it proactively.

Prerequisite: Frame0 desktop app must be running. If not available, stop and inform the user. Point to references/setup-guide.md.

Health Check

Always check first:

.claude/skills/frame0-wireframe/scripts/frame0-cmd.sh health

Core Workflow

Wireframing is a design conversation, not a batch job. Produce one screen at a time, show it, and stop for the user's reaction before authoring the next. Each shown screen is a checkpoint — never fan out a whole set of wireframes unprompted, even if the user described several screens up front.

1. Health check — verify Frame0 is running
2. Write wireframe JSON — to docs/design/wireframes/{category}/{name}.json. Author one screen.
3. Push to Frame0 — frame0-sync.py push <file.json>
4. Export PNG — frame0-sync.py export <file.json> <output.png>
5. Show it inline — surface the exported PNG in the conversation so the user sees the result without opening Frame0. Always do this after an export, and again whenever you re-export or the user asks to see it.
   • Inside clide (the IDE hosting this session — CLIDE_SOCK is set): render it as a native image card in the live Claude pane with clide image show <path> [--caption "…"] (T-249). This is the proper way to put an image in the clide conversation — a bare Read only shows it in the transcript, not in the UI the user is looking at.
   • Otherwise: Read the PNG so it renders inline in the transcript.
6. STOP and wait for approval — after showing a screen, pause and ask the user for feedback. Do not author, push, or export the next screen until they give an explicit go-ahead. Iterate on the current screen until they're happy, then proceed to the next one — looping back to step 2 for each.
7. Clean up — delete test/scratch pages from Frame0 when done

Multi-screen requests are still one-at-a-time. If the user asks for several screens, treat it as a queue: build the first, show it, get approval, then move on. The only exception is an explicit, unambiguous instruction to generate a batch without stopping (and even then prefer the batch-export dry-run + approval flow below).

Scripts

Script	Purpose
scripts/frame0-sync.py	Primary. Push/pull/export wireframes between JSON and Frame0
scripts/frame0-cmd.sh	Low-level API wrapper for ad-hoc commands

Wireframe JSON Format

{
  "name": "Dialogue Box",
  "shapes": {
    "panel": {
      "type": "Rectangle",
      "left": 170, "top": 500, "width": 800, "height": 260,
      "fillColor": "#1a1e24",
      "strokeColor": "#333340",
      "corners": [8, 8, 8, 8]
    },
    "speaker": {
      "type": "Text",
      "parent": "panel",
      "left": 190, "top": 520,
      "text": "LERA KONSTANTIN",
      "fontColor": "#c8d0e0",
      "fontSize": 16
    },
    "btn-ask": {
      "type": "Rectangle",
      "parent": "panel",
      "left": 190, "top": 670, "width": 370, "height": 30,
      "fillColor": "#2a3040",
      "strokeColor": "#c8d8f0",
      "corners": [4, 4, 4, 4]
    }
  },
  "connectors": {
    "flow-1": {
      "tailId": "panel",
      "headId": "btn-ask",
      "strokeColor": "#c8d8f0"
    }
  }
}

Key rules

• Shape IDs are stable local IDs you control (e.g. "panel", "btn-ask")
• parent references another local shape ID for nesting
• type uses create-API names: Rectangle, Ellipse, Text, Line
• Colors can be hex (#2a3040) or Frame0 theme tokens ($slate6)
• After a pull, Frame0 returns its native vocabulary (Box for Rectangle, theme tokens for colors). The sync script handles the mapping transparently.
• The .idmap.json mapping file (gitignored) tracks local ID ↔ Frame0 ID

Sync commands

SYNC=".claude/skills/frame0-wireframe/scripts/frame0-sync.py"

# Push local JSON to Frame0 (clears page, recreates all shapes)
$SYNC push docs/design/wireframes/dialogue/dialogue-box.json

# Pull Frame0 page back to local JSON (preserves local IDs via mapping)
$SYNC pull "Dialogue Box" docs/design/wireframes/dialogue/dialogue-box.json

# Push + export as PNG in one step
$SYNC export docs/design/wireframes/dialogue/dialogue-box.json \
  docs/design/wireframes/dialogue/dialogue-box.png

Batch export

Use this when exporting multiple wireframes. It runs as a single Bash call, avoiding repeated permission prompts.

BATCH=".claude/skills/frame0-wireframe/scripts/frame0-export-batch.sh"

# Dry run first — shows full manifest, no Frame0 calls
$BATCH --dry-run

# Export everything (skips PNGs already newer than their JSON)
$BATCH

# Export one category only
$BATCH --category dialogue

# Force re-export of everything
$BATCH --force

Always dry-run first, then get approval before running the live export.

Low-Level Commands

For ad-hoc operations or exec calls not covered by sync:

CMD=".claude/skills/frame0-wireframe/scripts/frame0-cmd.sh"
$CMD health
$CMD list-pages
$CMD current-page
$CMD get-page <page-id>
$CMD create-shape Rectangle '{"name":"btn","left":100,"top":100,"width":120,"height":36}'
$CMD create-connector <tail-id> <head-id>
$CMD move <shape-id> <dx> <dy>
$CMD export --format image/png
$CMD exec "view:fit-to-screen" '{}'

If you find yourself using exec for the same command repeatedly, flag it as a candidate for a proper wrapper in frame0-cmd.sh.

Project Styling Defaults

Colors from docs/design/visual-grammar-v01.md:

Role	Hex	Frame0 token
Background	#1a1e24	$sage3
Stroke	#333340	$slate6
Fill	#2a3040	$slate5
Text	#c8d0e0	$mint12
Accent	#c8d8f0	$blue12

Use hex when authoring new wireframes. Frame0 maps them to theme tokens on push.

Output Convention

docs/design/wireframes/
  hud/              # HUD layout wireframes
  menus/            # Menu screen wireframes
  dialogue/         # Dialogue box wireframes
  insert/           # Neural insert wireframes

Both .json source and .png exports are tracked in git. .idmap.json mapping files are gitignored.

Agent Guidance

• Araminta — Primary user. Full wireframe creation, layout iteration, visual consistency. Uses all component library patterns.
• Tyre — Interface architecture wireframes. System boundary diagrams.
• Qatux — Export wireframes for UI decision records and documentation.

References

• references/component-library.md — Pre-built JSON wireframe templates (HUD, dialogue, menus, modals, lists, inventory). Copy and adapt.
• references/api-reference.md — Frame0 HTTP API command reference and type mappings. Read for low-level control.
• references/setup-guide.md — Frame0 installation and startup for Fedora.