Design canvas for Claude Code and Codex

The agent skill catalogs the canvas, commands, components, and project contracts. An optional evidence record shows product facts, design decisions, screenshots, and reviews in the canvas's Design evidence panel.

Remote machines and VMs

framio start listens on all IPv4 interfaces by default and prints local and network URLs. If Tailscale is running, it also prints the Tailscale IP and, when MagicDNS is enabled, its hostname. SSH into your VM, start Framio, and open its Tailscale URL in the browser on your main computer. Tailscale discovery is optional and never blocks startup for more than a brief timeout.

SSH and headless Linux sessions skip opening a browser on the server. A missing browser launcher does not stop the canvas. No desktop browser or display is required on the VM. Framio downloads its own headless Chromium for screenshots, thumbnails, and geometry inspection. Those features need Chromium's system libraries and sandbox support. If Chromium is unavailable, live previews remain usable and failed thumbnails show a message. Clipboard actions also support remote HTTP sessions.

Use framio start --host 127.0.0.1 for local-only access, or --host <address> to bind a specific interface. Anyone who can reach the port can edit the canvas, so keep access limited to your trusted network with your firewall and Tailscale access rules. Tailscale encrypts HTTP traffic through its tunnel. HTTPS needs a separate setup, such as Tailscale Serve.

What goes where

Everything lives in .framio/:

Drop images into a page folder to use them as a moodboard.

Theming

Edit the front matter in DESIGN.md and the canvas updates on save:

---
colors:
  primary: "#B8422E"
  primary-dark: "#E0694F" # used in dark mode
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 15px
rounded:
  lg: 14px
---

Colors use shadcn names (primary, background, muted, ...), so the bundled components pick them up. Fonts load from Google Fonts. The file follows Google's DESIGN.md format.

Commands

framio add preserves existing component files by default and reports installed, skipped, and failed destinations. Use --overwrite only when you intend to replace existing files. The installer verifies its completion receipt rather than treating a zero exit as proof.

Design evidence

Open Design evidence in the canvas sidebar to see the product brief, confirmed facts, assumptions, and selected composition. Direction links jump to their actual canvas frames. Technical inspection and composition review remain separate, and each review links to the exact screenshot and viewport it examined.

Screenshot receipts print the viewport, build generation, revision, capture ID, and actual image paths. Framio also archives each image so a later capture cannot change an earlier review's evidence. Reviews become outdated after frame, theme, asset, metadata, or design decision changes. A recorded pass covers its screenshot and scope, not every viewport.

.framio/evidence.json is optional. framio evidence returns the record and its revision. framio evidence --write <file> --expect <revision> validates and replaces the whole document; replacement documents retain existing entries and unknown fields. --expect new applies only to a missing file. Framio refuses malformed records and conflicting writes. It keeps recent captures and any capture referenced by a review across server restarts.

Layers

Name meaningful parts of a design with plain JSX:

<div className="min-h-screen">
  <header data-layer="Header">…</header>
  <main data-layer="Content">
    <section data-layer="Balance Card">…</section>
  </main>
</div>

The Layers panel sits below Pages. Select a frame to see its tree, hover to outline a layer, and click to select it. Clicking inside a frame reveals the nearest named layer. Repeated siblings group into one row; paths such as Content/Transaction Row[2] select an instance. An omitted index means the first match. Avoid /, [ and ] in names.

Double-click a name to rename its JSX string literal, including in shared components. A mapped list shares one source name, so renaming updates every instance. Expression names and stale or ambiguous source locations are refused.

Name every direct child of the frame root. Missing names produce non-blocking warnings on the canvas, in the panel, in .framio/.state/errors.json's additive warnings array, and in screenshot output. Selection keeps its existing fields and adds layer: { path, name }.

Full-frame screenshots also save top-level crops under <slug>.layers/, or <slug>@<width>.layers/ for responsive frames, and print the layer tree with sizes. Layer crops include 8px of surrounding context and use 1–2× scale to approach 1,500px on the longest side. For very tall layers, screenshot a child layer.

framio inspect checks text and child overflow, stack gaps, near alignment, the 4px spacing grid, text contrast, and interactive target sizes. These geometry checks guide review; text contrast assumes the measured flat background and cannot judge images, gradients, or overlays. Use --width with screenshot or inspect to review one responsive viewport. Layer crops require frame arguments; they cannot be combined with URL, page, or all-frame captures. Review the opening composition before extending a page, then use focused layer crops and full primary and mobile screenshots. Bound aesthetic revisions; fix functional defects and reconsider a weak composition instead of repeatedly polishing it.

Responsive frames

Use one component at several sizes:

export const meta = {
  name: "Invoices",
  widths: [1440, 768, 390],
  height: 900,
  // heights: [900, 1024, 844], // optional overrides in widths order
};

The first width is primary. Viewports appear side by side, largest first, and move as a group. Select any viewport individually; the agent's selection includes its width. Desktop heights use meta.height, tablet widths 600–1023 use 1024, and widths below 600 use 844. Frames still grow to fit content. Existing frames with width and height behave as before.

framio screenshot <page>/<frame> captures all widths as <slug>@<width>.png. Use --width <n> for one viewport; page screenshots include all viewports.

Comments

Press C or choose Comment, then click a frame to pin feedback. Enter saves; Escape cancels. Pins follow the clicked element and stay the same size when you zoom. The right comments panel lists the page's open feedback. Click a pin or list entry to reply, resolve, reopen, or delete. Open pins stay visible in Select and Hand; enable "Show resolved" to see resolved pins.

Comments live in .framio/comments.json, alongside the designs. Tell your agent to "address the comments": it reads the file, fixes the frames, replies as agent, and resolves verified fixes. File edits appear live. Invalid comments are reported in the canvas and .state/errors.json; the server preserves the broken file and refuses UI writes until it is fixed.

Quick edits

Double-click text to edit it on the canvas. Drag resize handles for 4px snapping, or hold Shift for free sizing. Drag an element to reorder it among its static siblings. Use Delete to remove, ⌘D to duplicate, and ⌘Z / ⇧⌘Z to undo or redo.

Edits are written to the TSX source as minimal changes. Values computed in code are locked, with a reason shown in the inspect panel.

Building your app

Ask your agent to build the chosen design in your real app. The Framio skill guides it to port DESIGN.md tokens and shared components into your app's conventions, replace mock data, and compare every screen, including its smallest width:

framio screenshot --url http://localhost:3000/invoices --compare 11-invoices/list --width 390

URL captures use managed Chromium, capture the full page, and save to .framio/.state/screenshots/urls/. To capture a redesign's current app on the moodboard, add --into 01-moodboard. It creates an image frame with an editable { name, source, note } sidecar.

Development

This Bun and Turborepo workspace contains the CLI in apps/framio and the Astro landing app in apps/landing. Use Bun 1.4.2 and Node.js 24 or newer.

bun install
bun run build:ui          # build the canvas UI
bun apps/framio/src/cli.ts <command>  # run from source
bun run test
bun run build:binary      # build a binary for this platform

Run bun run dev:landing to start Astro, bun run build:landing to build it, and bun run deploy:landing to deploy it with Wrangler. See apps/landing/README.md for the Cloudflare account and domain configuration.

To release, push a tag. GitHub Actions builds the binaries that install.sh and install.ps1 download.

git tag v0.1.0 && git push origin v0.1.0

Contributing

See CONTRIBUTING.md. Report security issues privately, as described in SECURITY.md.

Update Framio

The sidebar footer shows Update available when a newer stable release is found. Hover or focus the control for a short description, or open About this update on any device. Complete release notes opens the GitHub release.

Use Check for updates in the footer to refresh release information. If an older Studio has no update control, run framio upgrade --check in your terminal, then return to Studio to download and install the update. Versions before v0.0.12 can reach the new CLI with framio upgrade --download followed by framio upgrade --install.

Click Update available to download and verify the release. Framio keeps running. A verified download survives closing Framio. Click Install update whenever you are ready. This installs the executable and restarts only the current project at the same URL. Other projects continue running and offer Restart to update individually.

framio update
framio update --status
framio update --check
framio update --download
framio update --install
framio update --rollback

Run framio update to check, download, verify, and install the latest release in one command, in terminals and scripts. framio upgrade is an alias. --status only shows shared update state. A verified download can be installed offline. --download only downloads and verifies. --install requires an existing verified download and does not download one first. CLI installation lists running projects for you to restart after saving work. --rollback restores the retained previous executable. It does not reverse changes to project files.

Update discovery uses GitHub directly, with a shared 30-minute cache, conditional requests and bounded retries. An explicit check refreshes the cache unless GitHub's rate limit is still active. Studio displays discovery failures so you can retry. Network failures do not block startup. Updates are stored under ~/.framio/updates, keyed by the canonical installation path. Custom installation directories are supported. Framio never requests elevation. If your installation is not writable, ask its owner to update it or install Framio in a directory you own.

Source checkouts update through Git. The updater cannot replace Bun or the checkout. Releases without checksums cannot be downloaded through the updater.

Before a canvas restart, pending and active canvas saves must succeed. Close other canvas tabs for the same project after saving their work. Framio refuses a restart while another live canvas tab is connected. Unsubmitted comment and reply drafts stay local to their browser tab across reloads. The page, viewport, selection and panel context are retained. Drafts are never posted automatically.

If the updated server fails to start, the supervisor attempts to start the retained previous executable on the same port. The canvas reports recovery and offers a retry. If neither executable starts, run framio update --rollback, then framio start in your project. Installation recovery inspects the executable's actual version after an interrupted operation. A dead download owner leaves a retryable failure, never an installable partial archive.

Project setup and skill migrations are separate. If a release requires one, the canvas links to the instructions in its release notes.

Telemetry

Packaged Framio binaries send anonymous CLI, local server and Studio usage and application errors to PostHog. Events include command names from a fixed list, outcomes and durations, first-use installation counts, server starts and heartbeats, tool and panel changes, comment and update actions, and your Framio version, operating system and architecture. Studio events also include browser, device and session metadata. One random installation ID in ~/.framio/telemetry.json connects these surfaces without creating person profiles.

Framio does not send designs, page or frame names, comment text, raw command arguments, project paths or element text. Error messages and product stack locations are scrubbed. Design failures send a category and count only. Session recording, surveys and generic DOM autocapture are disabled. Delivery is best effort, so offline or opted-out installations are not fully counted. Install counts represent first enabled use, not downloads.

Run framio telemetry status to see the setting, framio telemetry off to persistently disable collection, or framio telemetry on to enable it again. FRAMIO_TELEMETRY=0 also disables collection, and truthy DO_NOT_TRACK always disables it. Environment variables override the saved preference. Restart running servers and reload Studio after changing the setting. Source checkouts send nothing unless you set FRAMIO_TELEMETRY=1.

The first enabled run prints a one-time notice. Telemetry internals describe the event catalog, collection limits, PostHog insights and release source map secrets.

License

MIT