Guide

What it is

Sketchcoded is a bulletin board for the app you're about to build. You bring drawings of screens as image files. You pin them to a cork board, drop numbered pins on the parts that do something, and tie yarn from a pin to the screen it leads to. Every pin and every yarn carries plain-language notes: what happens, when, and what data is involved.

Before you draw, you can write down every idea in the plan, assign each to a screen, and let the app turn them into pins once the drawing exists. Screens can hold a web drawing and a mobile drawing of the same view. When the board is ready, you play it like a paper prototype, run the checks, and export a bundle an AI agent can build from.

The example: this website

The board on the landing page is this very website, planned in Sketchcoded: a Home frame with the landing page, the workstation, the screen editor, and planned frames waiting for drawings. A read-only version you can click through online is coming. Until then, the example ships inside the app: your first launch opens the Little chat board, and you can import the Sketchcoded board from the repository's examples once it is published.

Set up

Paste this into your AI assistant, or run the commands yourself.

Loading…

Copy prompt

By hand

git clone <the repository> sketchcoded
cd sketchcoded
npm install
npm run dev

Open http://127.0.0.1:5173. Stop the server with Ctrl+C when you're done.

Set up from the Markdown files

The repository is written to be read by an agent. AGENTS.md holds the working rules, README.md the user guide, and docs/ the original brief, the graph contract, the decisions made along the way and the functionality list. An agent that reads those files knows how to run, test and extend the app without asking.

The automatic checks

Review flow reads the board as a graph and reports three kinds of finding.

Repair needed

• Broken references: a yarn to a missing screen, a pin with no screen, a missing image.
• Yarn attached to a detail reference or a link pin, which never navigate.
• A Back or Dismiss action with a fixed destination.

Check this path

• No starting screen, an untitled screen, a pin without a name or intent.
• A pin with no yarn, a screen nobody can reach, a screen with no way onward.
• Two branches with the same label, or more than one fallback.
• A planned frame still waiting for its drawing; a pin missing from the mobile layout; a link pin without an address.

Use your judgment

• Branches described in words that may overlap or leave a case out.
• A one-way path with no structural way back, such as after logging in.
• A Back action on a screen you can arrive at without history.

You accept an intentional exception with a reason. The reason travels with the export and reopens if the relevant evidence changes. Nothing in words is executed or proved.

Build rules

These rules apply to Sketchcoded itself and to anything built from a Sketchcoded board. They live in the repository's AGENTS.md so an agent follows them without being told.

• Nothing grows or shrinks because of what was clicked. Dialogs and panels keep a fixed size; their content scrolls.
• Nothing overlaps. Labels, pins and frames keep clear of each other.
• Text stays readable and controls reachable at browser zoom from 125% to 250%. Click targets are at least 44px; fields at least 48px.
• Links out are pins with the address in their notes, never separate screens.
• The page never scrolls; panels do. The board never pans out of sight of its content. Every view works at every zoom.
• A frame wearing the “Leave it up to the AI” post-it needs no drawing: the builder makes a standard, conventional page from its title, purpose, ideas and yarn. Everything else is built as drawn.

What the AI gets

Export produces a ZIP with:

• project.json: the canonical graph, layout, library, planning backlog and review decisions.
• schema.json: the JSON Schema for that file.
• flow.md: the same specification organized by screen, pin, branch and finding, plus the planning outline. Frames left to the AI are marked there.
• BUILD-CHECKLIST.md: your general build rules, the ones that hold for every app you make; the agent reads them first.
• skills/: the agent's instructions, one file each: read a board, build rules, describe pins, connect screens, plan the backlog, resolve findings, walk the flow, talk to Sketchcoded.
• review.json: current findings and accepted exceptions with reasons.
• assets/: the drawings.

You rarely need the export while you work. Every view has a Tell the agent button: it copies a three-line prompt naming exactly what you are looking at and the address of a task brief the running app serves for it; the brief carries the task, the skills to read and your rules. Whatever you type under the prompt is part of the task. The agent reads the live board on your computer and writes back through the same local API. A new board is written at the level you choose: just the to-do list, frames with the strings already tied, or built out, where every frame is left to the AI and Test flow walks the whole site: real pages you scroll, buttons that follow your yarn, forms and dialogs, with nothing behind them. You take the post-it off the one or two pages you want to draw yourself.

FAQ