design-sketch

name	design-sketch
description	ASCII art UI sketches + .monojson Monodraw stub. Use for any UI/layout decision or layout code changes (flexbox, grid, modals, dialogs).

design-sketch

The default medium for UI design discussions in this account. Use ASCII art in chat to communicate layout decisions; emit a sibling empty Monodraw stub on disk so the user can draw an alternative visually if the ASCII proposal isn't quite right.

When to fire

Fire when:

• The user describes a UI change, layout, modal, panel, dialog, form, or component
• A plan file is being written and design decisions came up in conversation
• The user explicitly says "sketch this", "design this", "lay this out", or invokes /design-sketch
• A code change is touching layout-relevant code (CSS grid, flexbox, modal markup, dialog components)

Do NOT fire when:

• The work is pure logic, backend, or data — no UI surface
• A bug fix that doesn't change layout
• Documentation of non-visual things (APIs, data models, etc.)

What to produce

Every invocation produces both:

1. ASCII sketch in chat

Render the proposed layout using box-drawing characters and a consistent vocabulary:

• Boxes: ┌─┐ │ └─┘ for borders, ┏━┓ ┃ ┗━┛ for emphasis, ╭─╮ │ ╰─╯ for rounded
• Dividers: ├─┤ for horizontal, ┬─┴ for T-junctions
• Form controls: ◯ empty radio, ⦿ selected radio, ☐ empty checkbox, ☑ checked
• Buttons: [ Label ] for buttons, [[ Primary ]] for primary action
• Region labels: caps inside the box (e.g. SOURCE, TARGET, ACTION)
• Annotations: lowercase descriptions outside the box, with arrows ← → ↑ ↓ if pointing at something

When mcp-monodraw is configured, you can use its mcp__monodraw__create_ascii_art tool for typed shapes (box, flowchart, sequence, architecture, table, tree). For freeform layouts, hand-author the ASCII — it's usually faster and more precise.

Render the part being decided, not the whole app. A modal redesign shows the modal, not the surrounding page. A sidebar tweak shows the sidebar with brief context, not the entire layout.

2. Sibling .monojson stub on disk

Write an empty Monodraw canvas to ~/.claude/design-sketches/<YYYY-MM-DD>-<HHMM>-<slug>.monojson and print the path in chat so the user can click it in Ghostty to open Monodraw.

Slug rules:

• kebab-case
• max 40 characters
• describes the design topic, not the file purpose (e.g. conflict-modal-action-column, not sketch-1)

Example path: /Users/pierce/.claude/design-sketches/2026-05-05-1430-conflict-modal.monojson

How to create the stub:

mkdir -p ~/.claude/design-sketches
cp ~/.claude/skills/design-sketch/seed.monojson \
   ~/.claude/design-sketches/$(date +%Y-%m-%d-%H%M)-<slug>.monojson

Use the actual slug, not the placeholder. The seed is a valid empty canvas; the user draws into it. The ~/.claude/design-sketches/ directory is gitignored at the top level — files inside are ephemeral working copies, not committed artifacts.

How to communicate the path to the user:

After writing the stub, print one line in chat with the full absolute path so it's clickable in Ghostty:

Stub: /Users/pierce/.claude/design-sketches/2026-05-05-1430-conflict-modal.monojson

Tell the user they can click that path in Ghostty to open it in Monodraw, draw an alternative, save, and let you know.

Reading the user's edits

When the user says "I edited it" / "take a look" / "I drew it":

1. Read the file via the mcp__monodraw__export_diagram tool (or fall back to /usr/local/bin/monodraw <path> via Bash)
2. Render the result inline in your reply so you can refer to it
3. Respond to what was actually drawn — what changed, what tradeoffs the user made, whether the layout has issues

Inline-in-plan rule

When writing or editing a plan file (under ~/.claude/plans/ or a project's docs/) and the conversation included design decisions, embed the ASCII sketch directly in the plan under a ## Design or ### Layout heading. Plan files for design work must visually communicate what was decided, not just describe it.

The .monojson stub does NOT go into the plan — only the ASCII rendering. Reference the stub path in a "Working files" or "Artifacts" section if relevant.

Cleanup

Before writing each new stub, prune the directory:

1. List ~/.claude/design-sketches/*.monojson
2. Delete any file whose <YYYY-MM-DD> prefix is more than 30 days before today
3. If the directory still has more than 50 .monojson files, delete oldest until 50 remain (sort by filename, which is chronologically ordered)

A single find invocation handles the date-based prune:

find ~/.claude/design-sketches -name "*.monojson" -mtime +30 -delete

For the count cap, list and trim:

ls -1t ~/.claude/design-sketches/*.monojson 2>/dev/null | tail -n +51 | xargs rm -f

Run both before writing the new stub. Don't announce the cleanup unless something unusual happened.

Notes

• The .monojson format is a UUID-referenced object graph. Do NOT attempt to author non-trivial .monojson files by hand — only the seed (empty canvas) is hand-authorable. The user is the only writer of meaningful .monojson content; you only read.
• The Monodraw CLI (/usr/local/bin/monodraw) is render-only: .monojson → ASCII. It cannot import ASCII back into a .monojson. Don't try.
• If mcp-monodraw is not configured in the current project, fall back to invoking the CLI via Bash — the workflow still works, just with one fewer convenience.
• If the user asks for ASCII without a Monodraw round-trip ("just sketch it"), skip the stub-file step. The ASCII alone is sometimes enough.