The design/ folder

What lives where

frames/<name>/frame.tsx

The frame: a file that default-exports one React component.

frames/<name>/frame.json

Its size and place on the canvas.

frames/<page>/<name>/

A frame on a page. Pages hold pages, to any depth.

../../..

Components more than one frame uses.

../../../../tokens.css

The project's tokens, for every frame without a theme of its own.

../../../../transitions.css

How the player moves between frames, in plain CSS.

../../../../scenarios/*.json

Named seeds for the state a session starts from.

../../../../assets

Images and fonts more than one frame uses.

../../../../thumbnail.*

The project's picture on Home.

Names

A frame is named by its path under frames/: checkout on the root page, shop/checkout on the page shop. That full name is how links, commands and addresses reach it. A variant is a sibling with a -- suffix, such as checkout--empty: a complete frame of its own, filed beside the one it varies. Deleting a frame is deleting its folder.

Pages

A folder under frames/ without a frame.tsx is a page, and each page is its own canvas. Rename or move frames and pages on the canvas, and spool rewrites every link that named them. A move made outside spool leaves those links for you: spool flows marks them missing.

frame.json

The one file both hands write. The agent writes the size, { "w": 1440, "h": 900 }, and spool adds x and y beside the page's other frames. A frame with no size is 1440 by 900. Your drags and resizes rewrite it after that.

spool's own files

canvas.json and .spool/ belong to spool, and nothing else writes them. spool init also leaves AGENTS.md and CLAUDE.md in design/, pointing your agent at spool skill.