Koala UI · 2026

Koala POC Canvas

Un canvas local per fer proves de concepte: un agent posa variants vives de les teves pròpies pantalles una al costat de l'altra, tu marques, comentes i tries, i les opcions descartades es congelen en imatges. Gratuït i de codi obert.

Rol

Product Design, Front-End

Stack

ReactTailwindCSSNode.js

Any

2026

Dona-li una estrella a GitHub

Project Details

Koala POC Canvas is a local canvas where AI agents lay out live design options side by side, and I choose between them. Every frame is a real route of the project, running, not a picture of it. It's free and open source, under the MIT licence, on GitHub.

I built it because an agent can write five directions for a screen in the time it takes me to sketch one, but reading them one tab at a time is slow and I forget what I saw. On a canvas I see all of them at once, mark them, leave comments or draw where they matter, ask for more, and record the choice. It replaced the part of my job I used to do in Figma.

It is the tool behind every proof of concept in Koala UI, which is where the POC in the name comes from. The canvases further down are real ones, open to explore.

Behind each round there is a small team of agents. A researcher reads the screen and writes the directions, builders make them at the same time, one each, and a reviewer checks every variant before it reaches the canvas. I only see frames that already render.

This page is the documentation. It covers installing, the loop, the agent team, every command and shortcut, and the questions people ask.

Getting started

You need Node 20 or later, and Chrome or Chromium for screenshots.

npm i -g https://github.com/jespinosa19/koala-poc-canvas/releases/latest/download/koala-poc-canvas.tgz
koala-poc-canvas skill

The first command installs the koala-poc-canvas command. The second installs the agent skill in ~/.claude/skills and its three agents (researcher, builder and reviewer) in ~/.claude/agents, so Claude Code knows the whole workflow in any project. Run it with --project to install them in the current project's .claude folder instead.

Start your dev server, then from the project root:

koala-poc-canvas serve --target http://localhost:3000

Open http://localhost:4848/__canvas/ and ask your agent for options:

Put three directions for the pricing section on the canvas, desktop and mobile.

The agent builds each direction as a route in a scratch area of the project, checks it, adds one frame per route and hands you the canvas. From there you look, comment, draw and choose, and it reads what you did. It won't always nail it in one round. That's what the next round is for.

Updating

Run the install command again, then koala-poc-canvas skill so the skill and agents match the new version. Every version is on the releases page.

Coming from Koala Canvas

The tool used to be called Koala Canvas. Installing the new version keeps koala-canvas as an alias of koala-poc-canvas, and your .koala-canvas/ folders keep loading as they are. koala-poc-canvas skill installs the renamed skill and agents and removes the old koala-canvas ones, so the agent doesn't see two copies.

From source

git clone https://github.com/jespinosa19/koala-poc-canvas.git
cd koala-poc-canvas
npm install
npm link
koala-poc-canvas skill

npm install builds the tool, and npm link points the command at your clone, so a rebuild with npm run build reaches every project.

What's in it

koala-poc-canvas, the command. Everything the agent does goes through it: create a canvas, check a route, add frames, read comments and drawings, answer requests, record a decision. Every command prints JSON, so the agent never parses a screen.

The canvas, a page served on port 4848. It proxies every other path to your dev server, so frames are same origin: they keep hot reload, and the canvas knows which element a comment points at.

The skill and its agents, the instructions the agent follows, split into a team: a researcher that writes three or four directions from the code, the design system and the canvas history; builders, one per direction, working in parallel; and a reviewer that renders every variant and sends back the ones that break, drift from their direction or ignore a comment. The rules stay the same: build directions, not versions; settle layout before visuals; read verdicts as signal for the next round.

The interface, built with Koala UI in its tactile style with the Lime accent, dark by default.

.koala-canvas/, a folder in your project with one JSON file per canvas. Nothing leaves your machine. Add it to .gitignore.

How it works

A canvas holds frames. A frame is a live iframe of a route at a real size: desktop 1440, laptop 1280, tablet 820, mobile 390, or any width you set. Frames can also point at another URL or at an image.

Frames sit in rows, and a row is a question. Round 1 · Layout compares structure with plain visuals; Round 2 · Visual styles the layout that won. Desktop and mobile can be rows of their own, so a direction that only works wide shows it straight away.

Each frame in a row is a direction, not a version. A direction is a different idea with a letter and a name, "A · Plan cards", "B · Seat slider", "C · Comparison table". Three takes on the same layout is not a choice.

I mark frames with a verdict: Pick, Maybe or Out. Out frames read dimmed and struck through. The agent reads verdicts before it builds the next round.

Comments pin to a point or to an area I drag. Each one carries the element under it, so the agent changes the right thing, then replies or resolves with a note on what changed.

Drawings are for what is faster to show than to write. The Draw tool (D) has a pen, a marker, an arrow, a box, a circle and an eraser, in five colours. Strokes sit on their frame and follow its scroll, and the agent reads them like comments: what was drawn, where, and over which element.

Requests are how I ask from the canvas. More like this on one frame, with an optional hint. Mix on two frames or more, saying what to take from each. Choose this on the winner, with the reason.

A decision closes a row. The winner keeps running; every other frame is captured and frozen into an image, so the record survives when the scratch routes are deleted. The row label shows what was chosen and why.

A decision, start to finish

This is the pricing section of the Koala UI site, decided on the canvas.

1. Directions. The agent built A, plan cards, then B, a seat slider, and C, a comparison table, each as its own route.
2. More like this. I asked for a variation of A and got A2.
3. Mix. I asked for "the headline of C, the cards of A2" and got D.
4. Verdicts. I marked A as Pick and the rest as Out.
5. Choose this. I chose A with the reason "plan cards read fastest; the slider hid the price".
6. Decision. The agent recorded it. A2, B, C and D froze into images; A stays live.

Click it to open the real canvas. Double-click a frame to focus it and step through the others with the arrows; the frame toolbar shows every action described above.

The agent team

A round is too much for one context to do well: reading the history, building three or four routes and judging them honestly. So it's split.

• Lead, your agent. Talks with you, owns the canvas, dispatches the others and hands over. It doesn't build the variants itself when there are three or more.
• Research, koala-poc-canvas-researcher. Reads the screen, the design system and the canvas history, and writes the brief: what to keep, what to avoid, your signals, and three or four directions with one file each. It never edits code or the canvas.
• Build, koala-poc-canvas-builder, one per direction, all at once. Builds its direction as a scratch route in its own file and checks it renders. It never touches another builder's file or the canvas.
• Review, koala-poc-canvas-reviewer. Renders every variant and judges it against the brief and your comments and drawings, and checks the set is genuinely different. It returns pass or fix; it never fixes code.

A round, step by step:

Small jobs skip the team: a single variation, a one-line fix after a comment, or a round of two. They're still checked with check before they reach the canvas.

On the canvas

The shortcuts work even while the keyboard is inside a frame, so a comment lands on the first click.

Commands

Every command prints JSON. Run them from the project root. --canvas <name> (or -c) targets a canvas other than the current one.

Canvas

Frames

Feedback

Decisions

Configuration

In Git Bash on Windows, prefix commands with MSYS_NO_PATHCONV=1, or routes like /pricing get rewritten into Windows paths.

Real canvases from Koala UI

Every canvas here decided part of Koala UI. They run in the real interface, with the real comments between me and the agent. Click one to explore it. Nothing you change leaves your browser.

Badges

Four rounds to settle the badge: the model, the light theme, the real component, then motion. Each direction sits next to the docs page and the blog posts that use it, so the choice is checked where it will live.

Agents

Status language first, then how a lead agent splits and folds the work, how agents answer in chat, and the key moments of a run. Sixteen comments, each with the change that answered it.

Weather card

Desktop and mobile as separate rows, at their real sizes, so a direction that only works wide shows it straight away.

FAQ

Tech Used

ReactTailwindCSSNode.js

The interface is built with Koala UI components, in the tactile style with the Lime accent. A small Node server serves it, keeps the state in JSON with atomic writes, streams changes to the page, and proxies every route to your dev server. Screenshots and frozen frames use your own Chrome. It has no runtime dependencies beyond Node.

Open source

The code is on GitHub under the MIT licence. If it saves you time, give it a star so more people find it. Issues and pull requests are welcome. The README has the project layout and how to cut a release.

Limitations

Frames need a route that renders in a plain browser. A screen that only runs inside a host needs a route with mock data first.

Screenshots and decisions need Chrome or Chromium on the machine.

The canvas is for comparing and deciding. It does not write the final code; the winner still gets folded into the real screen when I say so.

For now

I make most interface decisions here now. The agents explore, I choose, and the record of why stays next to the work.

npm i -g https://github.com/jespinosa19/koala-poc-canvas/releases/latest/download/koala-poc-canvas.tgz