Wireframe Design

How to Create a Wireframe

Tips for creating wireframes that drive accurate specs via /ml-spec

Purpose

Wireframes are the primary input to the Meta-Loop specification process. The AI reads your wireframe and generates a specification document from it. There are two types: screen wireframes (what the user sees) and logic wireframes (what happens behind the scenes). These tips help you create both types of wireframes that communicate your intent clearly — especially the parts the AI is likely to misunderstand.

For the full Meta-Loop process, see the meta-loop-methodology skill.

Wireframe Principles

1. Whiteboard quality is fine. Wireframes don't need to be pixel-perfect. Rough sketches with clear annotations work better than polished mockups with no annotations.

2. Annotations are the real content. The sketch shows layout; the annotations communicate intent. When in doubt, add an annotation.

3. Wireframes communicate intent, not pixels. The AI doesn't need exact dimensions or colors — it needs to understand what you want the user to experience.

Wireframe Types

Screen Wireframes

Screen wireframes show what the user sees — layout, UI elements, and visual states. These are the classic wireframes: boxes representing views, labels indicating content, and annotations explaining behavior.

• Show layout structure, spacing, and element arrangement
• Can show multiple states side-by-side on one image (e.g., populated list and empty state)
• Name with a descriptive suffix: main-view-wireframe.png, edit-wireframe.png

Logic Wireframes

Logic wireframes show what happens behind the scenes — data flow, processing steps, derived values, and decision points. These look like flowcharts or data-flow diagrams, not screen layouts.

• Show how data enters, transforms, and flows through the feature
• No UI chrome needed — boxes represent processes, not views
• Use for paste capture logic, validation pipelines, rating calculations, etc.
• Name with a descriptive suffix: paste-logic-wireframe.png, search-logic-wireframe.png

When to Use Each

Most features need at least one screen wireframe. Add logic wireframes when the feature involves non-trivial processing that the AI needs to understand to write a correct spec.

What to Annotate

The Difference Rule

When a component or layout behaves differently from how it appears on other screens, annotate the difference.

Why This Matters

The spec writer (AI) will look at your wireframe, identify familiar components, and assume they behave the same way they do everywhere else. Most of the time this assumption is correct. When it isn't, the spec will silently inherit the wrong behavior — and the bug won't surface until implementation.

The Rule

If you're reusing a component or layout pattern from another screen, and it behaves differently here, write an annotation that calls out the difference. The format is:

← [what happens here] (unlike [what happens elsewhere])

Real Example: Reused Container Bug

Imagine a PageBackground container appears on 6 views. On 5 of them, it wraps discrete lines of text (menu items, stat rows) where the content has a natural fixed width. The spec writer saw PageBackground on the Document Reader wireframe and assumed the same sizing pattern — "hugs content width." But the Document Reader wraps flowing text that needs to fill the available width.

Without annotation: The spec prescribed a sizing strategy that works for discrete lines but breaks flowing text. Implementation followed the spec. Text didn't wrap.

With annotation: A note saying ← content fills width (unlike views with discrete lines) would have told the spec writer that this container behaves differently, preventing the wrong assumption.

More Examples

What NOT to Annotate

These are implementation details that belong in code, not wireframes:

Rule of thumb: If it's about what the user sees, annotate it. If it's about how the developer builds it, skip it.

File Format and Location

• Format: PNG (exported from any drawing tool — iPad sketch apps, Figma, whiteboard photos)
• Location: specs/views/<feature-name>/
• Naming: Use descriptive names ending in -wireframe.png

specs/views/bookmarks/
├── bookmark-main-view-wireframe.png    ← screen wireframe (you create)
├── bookmark-edit-wireframe.png         ← screen wireframe (you create)
├── paste-logic-wireframe.png           ← logic wireframe (you create)
├── about-this-view.md                  ← optional context (you create)
├── spec.md                             ← generated by /ml-spec
└── notes.md                            ← generated by /ml-wireframe

Orientation and States

Orientation Variants

Create separate wireframes for each orientation only when the layouts differ meaningfully (e.g., single-column portrait vs. two-column landscape). Name them with orientation in the filename:

• main-view-portrait-wireframe.png
• main-view-landscape-wireframe.png

Portrait-only apps need no orientation annotation or separate wireframes — a single screen wireframe is sufficient.

If the layout is identical in both orientations (just wider), you can note that on a single wireframe: ← same layout in landscape, just wider.

State Variants

When a view has multiple visual states (populated, empty, error, loading):

• Show multiple states side-by-side on one image when practical — this gives the AI full context in a single wireframe
• Use separate images with descriptive names when states are complex enough to warrant their own wireframe (e.g., search-results-wireframe.png, search-empty-wireframe.png)

Quick Checklist

Scan this before running /ml-wireframe:

• Every visual element is labeled (what component it is)
• Data sources are annotated (where content comes from)
• Scrollable areas are marked
• Any behavior that differs from the same component on other screens is annotated (The Difference Rule)
• Interaction triggers are noted (what tapping does)
• Orientation is addressed (separate wireframes, annotation, or portrait-only)
• All wireframe files use descriptive -wireframe.png names
• Logic wireframes (if any) show processing steps, not UI layout
• No implementation details (no modifier names, no pixel values, no API calls)
• Error/empty states are shown or annotated

Converted and distributed by TomeVault — claim your Tome and manage your conversions.