Design boards

The Design surface is a canvas for visual work. Ask for a mockup and the agent builds it as frames — real React components you can open and interact with, not a picture of an interface.

It’s for the stage before implementation: exploring what a screen should look like, putting variants side by side, and agreeing on a direction. Building a design changes no application code, so you can throw away five explorations without touching the app.

Start with a sketch or a board

Use /sketch <request> for a small visual question, such as comparing button styles or layouts for one card. Raven shows a few options as a card in the conversation, labeled A, B, C; click one to see it up close, or right-click to copy it as an image or as source. Sketches create no files and work in every mode.

Use /design <request> for work you want to keep: a screen, a flow across several screens, or a design you’ll revisit. The agent creates or updates a board and shows you a card pointing at the frame or section it built; click the card and the board opens on it. Boards are written in Build mode. Neither command is required — asking for “a mockup of the settings page” does the same.

If a sketch settles the direction, ask the agent to build that option into a board. Implementation remains a separate request.

A new board starts as a draft: it belongs to the workspace that made it and stays out of the repository until you press Save board, which asks for a name and a folder. Drafts are listed under their own heading on the Design surface, where a draft’s menu offers Save board… or Discard. Make as many drafts and saved boards as you like; deleting the workspace discards its unsaved drafts.

Boards, sections, and frames

Designs live in the repository:

• A board is a directory under .raven/designs/.
• A section is a directory inside a board, grouping related frames.
• A frame is a .tsx file directly inside a board or section.

Adding a file adds a frame; deleting one removes it. Boards are committed with everything else, so a branch carries its own designs, and the Design surface shows the boards on this checkout.

Every frame is a self-contained React component that default-exports itself and declares its own size:

export const frame = { width: 1440, height: 900 };

export default function Home() {
  return <div style={{ /* ... */ }}>…</div>;
}

Frames use inline styles and may only import react; they can’t pull in helpers from other frames or application components. Omit height to let the content decide it. Raven stamps a couple of measured fields (measuredHeight, contentHash) into the frame export after each turn; leave those alone. Position belongs to the board: Raven keeps board.json beside the frames when you arrange them (it also holds the board’s stable id), and a board’s decisions live in a paired context doc at .raven/context/designs/<board>.md, opened from Context doc in the board’s title row. The title row also has Copy board and, for a draft, Save board; click the board’s name to rename it.

Working on a board

⌘⇧D shows the Design surface; it’s pinned by default and opens wide, at 60% of the app’s width, with a button to widen it further. Whatever chat tab you’re in drives it — there’s no separate design conversation and no design mode. The board re-scans at the end of each turn, so you watch the design land as the agent finishes rather than flickering through half-written states.

Frames on the board are drawn as pictures, so a big board pans and zooms without stalling. Click a frame to select it, ⇧-click to add more, Esc to clear; the selection is for arranging and doesn’t reach the agent. To point the agent at a frame, right-click it for Mention in chat or Copy frame reference, or @-mention it in the composer. The same menu has Copy path, Copy image, Rename…, Move to section, and Delete…; a section’s adds New frame here; right-click the desk for a new frame or section, or a reference to the whole board.

Clicking through a prototype

Hover a frame and a ▶ Preview pill appears at its corner. It opens the frame live in an overlay where you can actually use it: click, type, navigate. Media queries and text still evaluate at the frame’s declared viewport, so a 390px frame behaves like a phone regardless of how big the overlay is. A reload button resets the prototype’s state.

The loop this is built around is short: click around, find what’s wrong, tell the agent, watch it change.

When a frame breaks

Each frame is compiled on its own. A frame with a syntax error, a missing size export, or a disallowed import renders that error in place — the other frames keep working. Content wider than the declared width is flagged rather than clipped. You never lose the whole board to one bad file, and you never get a silent blank where a frame should be. The one file that isn’t isolated is board.json: if it doesn’t parse — merge markers, say — the board says This board can’t be shown until it’s fixed.

The designs hub

Designs in the sidebar, or ⌘⇧B, browses a project’s boards from its committed home branch without opening a workspace — a board shows up there once it’s committed (and pushed, for a remote home branch). Preview one, then Open in a new workspace — local or worktree, your pick — to work on it. Designs on a branch surface inside the workspace that owns that branch, not in the hub.

Boards can be grouped into folders, one level above boards: All boards, Published, No folder, or a folder you’ve made, in a grid or a list, sorted by last update or name. Folder edits — new, rename, remove, Move to — happen inside a workspace and don’t change a board’s path, mentions, or context doc.

Publishing a board

Publish in the board’s title row puts the board on the web at a share.getraven.build link. The popover has one choice — Include this chat, which adds your messages and the agent’s replies beside the board, nothing it read or ran — then Publish hands you the link with Copy and Open. Anyone with the link can open it. The verb’s seat becomes a Published chip whose menu has Copy link, Open, Republish… (the page doesn’t update on its own after you change the board), and Unpublish…, which takes the page offline; publishing again brings it back at the same link. Drafts can be published too. Archiving or deleting the workspace takes its published pages offline, and the confirmation says so.

Turning a design into code

That’s a separate job, and an explicit one. A design is a mockup; asking for the real implementation is a different request, usually in a different workspace. @-mention the frame there, or paste a copied reference, so the agent knows exactly which design it’s building. Keeping the two apart is what makes it cheap to explore.