Documentation

Start here#

DesignLoop is a Chrome extension and a companion Figma plugin. It closes one loop: the live page comes into Figma as real layers, the fix happens in the browser on the real thing, and the fix goes back to code as an issue a developer — or a coding agent — can implement without a meeting.

There is no server, no account and no telemetry. On default settings nothing leaves your machine: the default model is Chrome's on-device Gemini Nano and the default transcription mode is none. Everything that does leave — GitHub, OpenRouter, OpenAI — leaves on a key you supply, to a service you configured, and only when you take an action that says so.

The four things it does

Install & set up#

Two installs — the extension and the Figma plugin — then as much or as little configuration as the features you actually want.

1 · The extension

From the Chrome Web Store, or unpacked from source. Unpacked is the development path and needs bun:

bun run install:all
bun run build
# chrome://extensions → Developer mode → Load unpacked → extension/dist

Load extension/dist, not extension/. Pin the icon to the toolbar — activation is a click on it, and there is no content script running before that click.

2 · The Figma plugin

Published as DesignLoop Import in the Figma Community, or loaded locally from source, which needs the Figma desktop app: Plugins → Development → Import plugin from manifest… and pick figma-plugin/manifest.json.

You only need the plugin for full-fidelity imports. The SVG and PNG copy formats paste into Figma — or anywhere else — with no plugin at all.

3 · Configure only what you need

Nothing below is required to export a page or to edit one with the on-device model. Each row is a feature you switch on by supplying its key.

The GitHub token

Scope a fine-grained PAT to the single repo you want issues in, with two permissions: Issues: read & write (to create the issue) and Contents: read & write (to upload screenshots — GitHub's REST API cannot attach files to an issue, so assets are committed to a designloop-assets branch and linked). Paste it with the repo in Settings and hit Test connection.

The microphone

Granted once, on the extension's own origin, from a page the extension opens for exactly that purpose — a background worker cannot raise that prompt itself. After that, voice works on every site with no further prompts.

How it fits together#

Five runtime surfaces, one session, and a hard rule about where secrets are allowed to live. Worth five minutes: most confusing behaviour in the product is a consequence of one of these.

The surfaces

The session

Everything you change on a page belongs to an iterate session: an ordered list of steps, each with the element it touched, the declarations it wrote, a before/after screenshot and a computed-style diff. Chat turns, dock edits, voice utterances and sweeps all land in the same list, which is why ⌘Z walks back a manual padding edit and an AI restyle identically, and why Create issue can describe a change in executable detail rather than in adjectives.

Sessions are keyed by page — origin plus pathname, so a query string or a hash is still the same view — and survive navigation, the worker dying, and the panel being closed. They do not survive a reload of the page itself: the edits are live DOM changes, so a refresh restores the site exactly as its server sent it.

Where things are stored

The page toolbar#

Clicking the extension icon injects one floating glass bar into the page. It is the only thing DesignLoop puts on a site by default, it is draggable by its mark, and every control on it is a mode you can leave with Esc.

Two other ways in

⌥⇧E arms the export picker and ⌥⇧I arms the issue picker without touching the toolbar; ⌥ double-click on any element starts an issue on it directly. Both shortcuts are rebindable at chrome://extensions/shortcuts.

The inspector dock#

A Figma-style properties panel, drawn on the page itself. It reads the pinned element's computed styles and hands every commit to the session — so a manual edit is a first-class step: live, diffed, undoable, and mirrored into the side panel's ledger alongside the AI's.

What's in it

The field grammar

Fields are invisible at rest — no ground, no border — so the dock reads as a list of values rather than a wall of inputs. Focus takes a violet border and halo. A value commits on Enter or on blur, and that commit is the undoable session step: the field flashes violet, the ledger in the side panel grows a line, and ⌘Z takes it back.

Structural edits

The dock does more than restyle. With an element selected:

Chat#

The Chat tab is where a change gets described rather than drawn. Type what you want — “tighter padding, darker text” — and the model turns it into concrete declarations that are applied to the real page, screenshotted, and diffed.

Three ways to start

Past sessions are listed under the launcher, grouped by page, freshest first, with a search box over their names and pages. Resuming one restores its thread; it does not re-apply its changes to a page that has since reloaded.

Ask, Auto, Plan

The mode decides how a change is allowed to land, and ⇧⇥ cycles it. It is a single shared setting, so the on-page toolbar and the side panel never disagree about which one is active.

Ask leaps and then lets you look. Plan lets you look before it leaps. Apply on a plan keeps the change outright — the plan review was the review.

Slash commands

A / at the head of an empty draft opens the command menu: every session action that otherwise lives on a button, reachable from the keyboard. The query matches names and aliases, so /clear and /start both find /new. The moment you type a space it's prose again — /clear the deck is a sentence.

The composer

A box that grows with the draft rather than scrolling inside two rows, plus the model picker, an attach clip and a mic. Images can be pasted straight in with ⌘V or attached — they ride along as reference (“make it look like this”), which is the reason the cloud rungs can be pointed at a screenshot of somebody else's page. A very long paste becomes a reference chip instead of flooding the box, and oversized text attachments are skipped rather than blowing the prompt budget.

Raw property: value lines skip the model entirely. That is also the fallback when Gemini Nano isn't available on this machine.

Dictation

The mic in the composer dictates into the box. Chrome's recognizer supplies the live interim ticker either way; when a transcription key is set, a real STT model gets the last word, because the live recognizer's failure mode is a confident wrong sentence rather than an error — and acting on one costs an inference and an undo.

Live mode

Live keeps the mic hot. Each pause is an utterance; utterances land faster than a model answers, so they queue and drain in order, with the queue depth shown in the bar. You point at elements on the page and talk — the session is doing the typing.

Sweeps: the change with no element

Some instructions are about the page, not a node. Those run as a sweep: a scope pass that says out loud how many elements it reaches and names the first few, then clustered batches that land in order, with a progress rail so a long pass is never a frozen panel.

A sweep needs a rung that can hold the whole page at once, which is exactly the line the model ladder draws. On Nano the same instruction is refused with the reason rather than half-applied to one div.

The model ladder#

Three rungs. One runs on your machine and is free; two run in the cloud on your own key. Choosing a rung is the single decision in this product that changes where your page goes, so the picker says so on every row.

Nano is free, private and small: its context holds exactly one element at a time. That is a hard limit, not a soft one, and the picker says so rather than letting you discover it by asking for a whole-page restyle and getting one div back. It needs Chrome 138+ and a one-time model download of a few gigabytes.

Plus and Pro hold the whole page at once, which is what makes cross-cutting work possible: collapse eleven greys into three, snap every margin to an 8px grid, audit a page against its own design system. Both slugs are overridable in Settings — the whole point of bring-your-own-key is that you choose what you're paying for.

Notes & annotation#

Not every piece of feedback is a change. + Note arms a gesture: click an element and a pin threads itself onto it. The thread is a conversation about that one element — every note on it, oldest first, each stamped — and it rides into the issue you file.

Pins stay on the page whatever mode it's in — a note written while annotating has to still be there when you go back to editing, or the review it was written for never happens.

The annotator

Inside a draft in the Issues tab, Annotate opens the screenshot with a box and arrow tool. Drawings are baked into the image that is uploaded, so the annotation survives the trip to GitHub — where nobody has your extension.

The Design System tab#

Most pages already have a design system. They just don't know it: eleven greys that wanted to be three, a type scale with two accidents in it, five radii where the CSS says two. This tab reads that system out of the live page, lets you correct it, and then hands it back — to the page, to Figma, or to code.

Scanning

A scan walks the rendered page — computed styles, not the stylesheet — so it sees what actually shipped, including whatever a component library injected at runtime. It groups near-identical values into single tokens and counts how many elements use each one, because usage count is what separates a token from an accident. Every scan saves itself into a library keyed by page, so you can come back to a system without re-running it.

The board

Editing the system

Apply to page

Snap this page to tokens rewrites every element's colours and corner radius to the nearest token, in place. It is a deterministic pass, not a model call, and it reverts cleanly. Its real use is as a preparation step: snap first, then export, and Figma receives a page that is already token-aligned instead of one carrying eleven greys into your file.

Export

Only tokens are exported. Detected components are code, not tokens, so the writers ignore them — they appear in the header comment for provenance. Naming is role-first: a token's semantic role wins, otherwise its deterministic name is kebab-cased, and collisions are numbered so the map is always one-to-one.

Export to Figma#

The serializer walks the live DOM and emits an intermediate design JSON: real frames, text, vectors, images, auto-layout, gradients, strokes, effects. Not a screenshot, and not a re-implementation of the HTML — a translation of what the browser actually rendered.

Three scopes

Four ways out

The plugin formats are copied to the clipboard gzipped and base64'd, prefixed DLOOP1:. Larger captures — and every crawl — download as a .designloop file that the plugin accepts by drag-and-drop.

The skeleton pass

A skeleton is a page's loading state, and designers usually draw them by hand, guessing at line counts and bar heights. DesignLoop already holds the real tree, so it derives one: content becomes bones (text, images, SVG, form controls), containers are left exactly as they are. The card keeps its fill, its border, its 12px radius and its padding — only the words and the picture turn grey. The skeleton is pixel-aligned to the component by construction.

Multi-viewport capture

Ticking more than one viewport preset captures the page at each width, so a responsive layout arrives in Figma as the set of layouts it actually has. This is the one feature that attaches Chrome's debugger to your own tab — to call setDeviceMetricsOverride so the page reflows, and nothing else. It detaches immediately afterwards, including on error. Single-viewport export never attaches it.

Naming

Layer names come from the DOM: tag, classes, and the component name when a React or Vue dev build exposes one. On-device naming can be run over the tree to turn div.flex.items-center into something a designer can find in the layers panel.

Crawling a whole app

A crawl drives a same-origin app in its own background window — navigating page by page, injecting the content script, waiting for each page to settle, capturing it, and optionally probing it for modal and drawer states. It ends as one .designloop file: every page a board, every captured state its own frame.

The review step in the middle is the point: pass one only collects routes, and nothing is captured until you have seen what the crawler thinks the app is. Anything whose label reads like a destructive action — /account/delete, remove, revoke — is unticked for you before you get there.

A crawl survives the service worker being evicted: the frontier, the visited set and the capture list live in storage, rewritten after every step, and an alarm heartbeat resumes the loop from the cursor. A page the worker died inside is retried once, then recorded as a failure rather than retried forever.

The Figma plugin#

The consumer half of the contract. It takes the payload, rebuilds it as Figma nodes, and tells you the truth about everything it could not do.

1. Plugins → DesignLoop Import.
2. Paste the DLOOP1: payload with ⌘V, or drop a .designloop file onto the panel.
3. Set the three options, then Import.
4. Read the report — then fix any font substitution and re-import without re-exporting.

Fonts

Figma cannot embed webfonts. Families that aren't available fall back to Inter, and every substitution is listed in the report with a dropdown to pick a different one — including the licence-gated families Figma will never load. Change them, hit re-import, and the file is rebuilt with your choices.

What can't survive the trip

• Reversed auto-layout and real 2D grids. Figma has neither, so flex-direction: *-reverse and grid layouts fall back to absolute positioning — which is pixel-exact anyway.
• Closed shadow roots, cross-origin iframes, matrix3d transforms. These can't be read, so they become placeholder rectangles, each one listed in the report.
• Cross-origin images without CORS headers. They can't be inlined unless you grant the optional all-sites permission; otherwise they are skipped and reported.

Issues & handoff#

The other half of the loop. A report is worth filing only if the person receiving it can act on it without asking a question, so DesignLoop files the write-up for you: the words, the picture, the selector, the environment — and, when the report came out of an editing session, the exact change you already made.

Starting one

Transcription

Structure with AI turns the raw transcript into a title, steps, expected and actual. Attach the audio file controls only whether the .webm is uploaded to GitHub — the recording is kept locally either way.

What lands in the issue

HTML is sanitised in the page, before it is sent anywhere: input values redacted, emails masked, token-shaped strings stripped. The draft preview shows the exact payload before you push.

Drafts

Drafts accumulate — file ten while browsing, then Push all. The panel shows the current page's drafts by default; the toggle widens it to every page. Screenshots and audio are committed to the assets branch (a separate assets repo if you set one) and linked from the issue body, because GitHub's REST API cannot attach a file to an issue.

Handing it to a coding agent

DesignLoop cannot bring your personal Claude or ChatGPT subscription to a repository. Agents run as a GitHub App or workflow installed on the repo, billed to whoever installed it. All the extension does is emit the trigger that installed agent listens for.

Handle, delivery mode and labels are all editable — verify the mention syntax against each agent's own docs, since these change.

Hand every new draft to the agent automatically is off by default — it would spend the repo owner's agent credits on every half-formed voice note. Left off, each draft carries a checkbox and an editable instruction box instead, and already-pushed issues grow a Hand to… button so you can decide after the fact, or retry a handoff that failed. If the issue files but the mention fails, the draft is marked pushed with a warning: the issue is never lost to a failed poke.

# .github/workflows/designloop.yml — the label-only path
on:
  issues:
    types: [labeled]
jobs:
  fix:
    if: github.event.label.name == 'agent-fix'
    runs-on: ubuntu-latest
    permissions: { contents: write, pull-requests: write, issues: write }
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Settings reference#

Everything on the options page, with the value it ships with. Right-click the extension icon → Options, or the gear in the side panel.

GitHub

Capture

Voice & transcription

Models

Coding agent

Keyboard reference#

Everything below works on the page, while a session is live, and never while the caret is in a field — the page's or the dock's.

Getting in and out

Editing

Reviewing

View

The composer

The two ⌥⇧ chords are Chrome commands and can be rebound at chrome://extensions/shortcuts.

Privacy & permissions#

There is no DesignLoop server. No analytics, no tracking, no account. Every request goes straight from your browser to a service you set up, with your key. The full policy is at /privacy; this is the engineering view of it.

What leaves the browser, and when

Permissions, and why each exists

Deleting things

Drafts and exports are deletable individually in the panel. Blobs are garbage-collected once the draft that owns them is pushed or discarded. Uninstalling the extension removes the lot. Anything already pushed to GitHub, OpenAI or OpenRouter is governed by those services and must be deleted there.

Limits & troubleshooting#

The honest list. Most of these are properties of the browser or of Figma rather than bugs, which is why they are documented rather than fixed.

Known limits

• captureVisibleTab only sees the viewport and is rate-limited to roughly two per second, so captures are queued and off-screen elements are scrolled into view first.
• Cross-origin images without CORS headers can't be inlined without the optional all-sites permission. They're skipped, and reported as warnings.
• Closed shadow roots, cross-origin iframes and matrix3d transforms can't be serialised; they become placeholder rectangles, each one listed in the import report.
• Figma has no reversed auto-layout and no true 2D grid, so those fall back to absolute positioning.
• On private repos, embedded screenshots render for collaborators inside GitHub's UI, but raw links won't work for logged-out viewers. Use a separate public assets repo if that matters.
• Page edits are live DOM changes. A reload discards them — file the issue first.

When something doesn't work

Glossary#