Quickstart
git clone to canvas in 30 seconds.Frameground is a local web app. Clone it, install dependencies, run the dev server. That's the whole setup. No accounts, no API keys, no cloud.
You need git and Node 20+. Everything else is local.
$ git clone https://github.com/basta/frameground.git $ cd frameground $ npm install $ npm run dev
Open http://localhost:5173 in your browser.
The home screen is a project picker. Click New project, give it a name, and you'll land on an empty canvas. A project is just a directory on disk under ./projects/ — you can ls it, git init it, edit files in it.
Open Claude Code (or Cursor, Windsurf, aider, opencode, Gemini CLI — anything that can write a file) inside the project directory and run:
> /frame my-app a dashboard with revenue charts
The syntax is /frame [project] [description]. The agent takes a moment to think through the design, then writes an HTML file to disk — the canvas picks it up the instant the file lands. Drag it, resize it, rename it from the canvas, or open the HTML file in your editor. Changes go both ways.
The skill ships preconfigured for Claude Code, opencode, Codex, and Gemini CLI — pick whichever matches your agent.
Each one is a slash command your agent can run. They're plain Markdown files; read them, fork them, replace them.
Reads the project's design tokens, picks a non-overlapping spot on the canvas, writes a self-contained HTML file, updates the manifest. Your default move.
The aesthetic advisor. Picks typography, color, motion, composition, and writes them into DESIGN.md and FEEL.md so every later frame is consistent.
Crawls another codebase, identifies its screens, extracts its aesthetic, and dispatches parallel subagents to port each screen as a redesignable frame. --redesign commits a fresh direction.
Generates parallel design variants of a frame so you can shop for one. Auto-picks execution-shopping (layout variants) or direction-shopping (aesthetic variants) based on whether DESIGN.md is filled.
Drops three named palette or typography variants into the Tokens panel. Preview each one live, apply with one click.
None of this is required to get started, but it's where the workflow gets fast.
The right edge of the canvas opens a panel showing every token in DESIGN.md — colors, typography, spacing, rounded, components. Edit them in place, preview instantly across all frames, commit back to DESIGN.md when you're happy.
The dev server watches your project with chokidar and streams changes over SSE. Anything an agent (or you, in vim) writes to disk reflects on the canvas the moment the file is saved; anything you do on the canvas (drag, resize, rename, delete) writes back to disk.
Skills are mirrored for Claude Code (.claude/skills/), opencode (.opencode/commands/), Codex (via AGENTS.md), and Gemini CLI (.gemini/commands/). Or write your own — anything that can POST to /api/projects/:id/frames can put a frame on the canvas.
By default projects go in ./projects/ (gitignored). Point that elsewhere with PROJECTS_ROOT=/your/path npm run dev — useful for keeping designs in their own repo, separate from Frameground itself.
Every frame is an HTML file. The manifest is JSON. The layout is JSON. Branch a redesign, open a PR with the rendered frames, review changes line by line. Merge conflicts on a button color resolve with git merge.
Create / rename / move / delete frames with plain HTTP at /api/projects/:id/.... Subscribe to filesystem changes via SSE at /api/projects/:id/events. The full table is in the README.