All pages
The skill
For agents
This page is also Markdown. llms.txt lists every page, and llms-full.txt holds them all in one file. The skill teaches a coding agent to run ra by itself.
ra runs the app in Chromium and answers everything outside the app from a world you describe: API replies, blocked hosts and stand-in servers. It then prints what a person would meet on the page: what is wrong, what a screen reader would hear and how the page is laid out. Pictures are written to disk, and you open one only when the words leave a doubt.
When to reach for it
- You changed something visual: CSS, a layout, a component, or text that might not fit.
- A state is hard to reach by hand: empty, failed, overflowing, signed out, or a date at midnight.
- A change could reach further than the place you edited, such as a shared component, a design token or a global style.
- Someone asks whether it works on a phone, or whether it can be read in dark mode.
Do not use ra to test logic, to restate the implementation, or to check that live services work.
The loop
ra stateslists the states the project names. Without a config,ra look http://127.0.0.1:3000/pathworks on any running app.ra look <state> --at phoneshows one state. Read the findings, fix them, and look again. Use--at phone,desktopor--at allwhen more views matter.- Before a change whose reach you cannot see, run
ra snap. After it, runra diff. It says which elements moved, resized, appeared or vanished, which outline lines changed, and which findings are new. - Before handing off, run
ra check. Exit 0 means nothing is wrong in any state at any view.
Run ra through the project's package runner (bunx --no-install ra, npx ra). It brings and verifies its own browser, so do not start Chrome yourself.
Reading a look
broken at phone (390×844)
http://127.0.0.1:64156/broken — 200 — "Fixture — Broken on purpose"
page 921×1991, 7 requests, 2 stopped, 2.0s
16 findings
cut-off "Subscribe to updates" is cut off on the right by its own box (84px hidden).
at button.button.cut "Subscribe to updates"
covered button "Pay now" is covered by span.veil; a click or tap on it would land on that instead.
at button.button "Pay now"
outside The page asked api.example.com for data (GET https://api.example.com/v1/me); nothing in its world answers. …
outline
main: …
heading "Everything here is wrong" [level=1]
button "Subscribe to updates"
layout
main "Everything here is wrong" 390×857 at 0,65 10 items stacked
section#cut 350×48 at 20,220
pictures: .ra/look/broken.phone.png (first screen), .ra/look/broken.phone.full.png (whole page)
browser: Chromium 158.0.8127.18, playwright-core 1.65.0, …- The header gives the address, status, title and page size. A page wider than the view means it scrolls sideways.
- The findings are the point. Each one names the element (
at …) and says by how much it is wrong.docs/findings.mdsays how each kind is decided. When one faint colour is used in many places, ra names the first ten texts and counts the rest: fix the colour where it is defined, then look again. - Notes say what a look had to leave out, such as the part of a very long page below its first 40 screens.
ra checkprints them under their state, passing or not, and counts them in its last line. - The outline is what a screen reader would hear. Each line maps onto
getByRole(role, { name }). Check copy, headings, labels and order here rather than in a picture. - The layout lists boxes with their sizes and positions in CSS pixels, with how the children of each are arranged. Check alignment, wrapping and stacking here.
- The pictures are for what words cannot carry, such as a gradient, an illustration or whether something looks right at all.
- Exit codes: 0 fine; 1
ra checkfound something; 2 the command or config is wrong; 3 the app or the browser could not run. The message says what to do.
--json gives the same thing as data. --in "<selector>" narrows a look to part of the page, and --full prints a long outline in full.
Getting to a state
Prefer a named state in ra.config.ts, so the next look is one command:
"projects-empty": {
url: "/projects",
world: { replies: { "GET /api/projects": { json: [] } } },
see: ["No projects yet"],
},- Name states after visual risks: typical, empty, overflowing, failed. Do not name one for every route.
- Every request the page makes needs a reply, an
allowor ablock. Anoutsidefinding names the host that is missing one. - A reply cannot answer where a redirect leads, because the browser follows redirects without asking. When an
outsidefinding says a redirect was stopped, give the address that redirected a reply. - An error status that the world is told to give is the state itself. ra reports how the page handles it, not the error.
- For calls made by the app's server, use
upstreamsand pass{upstream.NAME}to the app inapp.env. storage,cookiesandclockset up the rest.steps(page)clicks through to a state after the page loads.javascript: falselooks at the page with its scripts off, as a reader without JavaScript or a crawler sees it. Every check still runs. It is still a read-only page load, so a run against a deployment may use it withoutlive.seecannot match text inside<noscript>; check that text inexpectwith a CSS locator.- A look never hangs the run. Steps, an
expector ra's own checks that take longer than the project'stimeout(30 seconds by default) end the look with asteps,expectorbusyfinding, and the next look runs. A state's steps are timed as a whole, so a long flow may need a largertimeout; ra's waits for the page to settle and for its images come on top of it.
For a one-off interaction, use --then. It runs Playwright code with page in scope before the look and prints what the code returns:
ra look checkout --at phone --then "await page.getByRole('button', { name: 'Pay' }).click()"Do not
- Do not accept a finding to make
ra checkpass. Fix it.acceptis for findings that are true and fine, and it needs awhy. - Do not
allowan API to silence anoutsidefinding. Give it a reply instead.allowis for fonts and CDNs that the page really needs. - Do not commit
.ra/. It holds pictures and snapshots for this machine, and it ignores itself in git. - Do not compare pictures in CI.
ra checkis the CI step, and it needs no baselines. - Do not read every picture. Read the findings and the outline first, and open a picture only for what they cannot say.
When ra doctor says the browser is missing, install it with the project's own Playwright: bunx --no-install playwright-core install chromium or npx playwright-core install chromium.