Hand your app to Claude with a Markdown spec

If you only tell Claude "build me a shopping app", it has to guess how many screens there are, where each button leads, and what changes when the user picks a delivery method. The more it guesses, the more you end up fixing. This post shows how to design the screens and the paths between them in ScreenPath first, then hand that design to Claude as one Markdown spec file.

Why the spec comes first

When an app is turned into code, the thing that goes wrong most often is not the look but the flow.

• Where does the sign-in button go on success, and on failure?
• Does choosing "Delivery" or "Pickup" in a selector lead to different screens?
• Does back go to the previous screen or to home?
• What does a list look like when it is empty, loading, or failed?

In ScreenPath you draw all of this directly, as paths on a map and as screen states. So the exported spec contains decided facts, not impressions.

Designing in ScreenPath

1. Place screens on the map — arrange screen cards in menu groups (for example Common, Shop, Order). You can start from a sample project.
2. Build screens from parts — place 15 kinds of parts such as buttons, selectors, inputs, lists, tabs, and modals. Your project's design rules (color, type, corners, spacing) apply automatically.
3. Connect paths — draw a path from a button to the next screen. A selector can lead somewhere different for each value, and the map shows those condition paths as dashed lines.
4. States and motion — give each screen default, empty, loading, and error states, and pick motion presets for transitions and in-screen reactions.
5. Check in the player — tap through it in the player to find broken paths.

What goes into the Markdown spec

Export follows a fixed format called screenpath.export/1. Section headings and table headers never change, and exporting the same project again produces byte-identical output. Claude reads it the same way every time, and diffs between versions are easy to read.

Section	Contents
Design rules	Color, type, radius, shadow, spacing, and motion tokens; web CSS variables; Tailwind theme; native JSON tokens
IA and flow	Groups and screens, a Mermaid flow diagram
Actions	Which part leads where, under which condition, with which transition
Selectors and variables	Options and defaults, variables and conditions
Per-screen spec	Part layout, states, actions, computed pixel boxes
Appendix	Open comments

You can export the whole project, a single group, or a single screen.

Handing it to Claude

Drop the Markdown file into a Claude conversation or a Claude Code working folder and ask, for example:

Implement the screens and the actions table in this spec exactly. Use the tokens from the design rules section as the theme, and do not add navigation that is not in the actions table.

Because the spec has already decided the paths, Claude follows the table instead of guessing where things go. When you change the design, export again and compare with the previous file to see exactly what changed.

If you'd rather connect than pass files

Instead of passing files around, you can connect Claude to ScreenPath over MCP. Claude then reads the project directly and can edit the design with you. That is the topic of the next post, Designing screens with Claude over MCP.