validating-visual-design

Validating Visual Design with anoa

Frontend code that typechecks and passes unit tests can still render broken. This skill uses anoa — the browser CLI preinstalled in the Jonggrang sandbox — to open the running app in a real headless browser and verify the design actually works.

anoa is available to every agent backend (claude, opencode, codex, jonggrang). Call it via Bash. In the sandbox it is already there — start with the session step below.

On a bare host, install the binary once:

curl -fsSL https://raw.githubusercontent.com/porcupine-md/anoa-browser/master/scripts/install-linux.sh | bash

That is one binary carrying its own browser, so there is no second download for a browser — but the binary itself does have to exist. If anoa is not on PATH, install it rather than reaching for another tool.

The browser is a session

This is the one thing to get right. Start the browser once; every command after that attaches to the running browser and leaves it running, so the page, cookies and scroll position survive between commands.

anoa --headless --port 9222 &     # start once, in the background
anoa status                       # exit code 3 = nothing listening

A command that seems to do nothing almost always means no browser is running — check anoa status before assuming the command is wrong.

When to use

• After implementing or changing any UI (component, page, layout, styling).
• Before signalling completion on a task that touches the frontend.
• During Phase 10 design verification / interface-quality audits.

Core commands

anoa open http://localhost:3000    # go to a url (scheme optional)
anoa wait --load                   # or --text/--url/<css>: name what you expect
anoa screenshot design.png         # PNG of the viewport
anoa snapshot -i                   # interactive elements, each with an @ref
anoa get text                      # all visible text (cheaper than get html)
anoa click @e2                     # act by ref — or by any CSS selector
anoa fill @e3 "value"              # fires input/change, so React sees it
anoa set viewport 375 812          # resize the page
anoa set media dark                # emulate prefers-color-scheme
anoa console                       # what the page logged
anoa errors                        # uncaught exceptions