# Design decisions

[How it compares](https://hraness.github.io/ra/docs/how-it-compares/) argues the three largest choices: measure instead of asking a model, close the world, and put measured findings beside the outline. These are the others, each with the standard, study, or fixture it rests on.

- **Contrast comes from painted pixels, not from CSS.** WCAG asks for 4.5:1, or 3:1 for large text ([SC 1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)). Text often sits on something CSS names no single colour for, such as a gradient, a photo, a blur, or a shadow. [`tricky.html`](https://github.com/hraness/ra/blob/main/test/fixtures/site/tricky.html) has white text on a dark gradient, which reads well, and ra must stay quiet about it. ra reads the background across each whole line, reports the line only when three quarters of that background falls short, and prints the median ratio.
- **Small tap targets are reported only when crowded.** WCAG's minimum is 24 by 24 CSS pixels, and its exceptions include a target with enough room around it and a link in a sentence ([SC 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)). ra leaves the same two alone, and `tricky.html` holds both. `broken.html` has two 18 by 18 buttons side by side, and ra reports them.
- **A 320px view is built in.** WCAG's reflow criterion asks that a page work at 320 CSS pixels wide without scrolling sideways ([SC 1.4.10](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html)). A page can fit the 390px `phone` view and still scroll sideways at 320px, which the `narrow` view shows.
- **ra does the waiting, and every wait has a limit.** In a study of 235 flaky UI tests from 62 web and Android projects, 45.1% came from a test that did not wait properly for something asynchronous ([Romano et al., ICSE 2021](https://arxiv.org/abs/2103.02669)). A state has no sleeps to write: ra waits for 200 ms of network quiet and then 120 ms of stillness. By default it reports what is still open after 5 seconds as `busy`, and each part of a look stops at 30 seconds.
- **Nothing runs inside your app.** ra's predecessor asked an app to route its outside calls through a port, write adapters, and ship a second build. It carried 18,445 lines of source and 15,786 of tests ([From Direct to ra](https://hraness.github.io/ra/docs/from-direct/)). ra is about 6,000 lines, and a first look needs no config.
- **No pixel baselines in CI.** [Playwright's guide](https://playwright.dev/docs/test-snapshots) warns that rendering varies with the host's operating system, version, settings, hardware, power source, and headless mode. `ra check` compares a page with rules, not with an earlier picture, so there is no baseline to store or approve. `ra snap` and `ra diff` keep their files in `.ra/`, which ignores itself in git, for the length of one change.
- **One browser, launched one way.** ra runs the Chromium that your project's pinned Playwright installed and refuses an installed, auto-updating Chrome, so the browser changes only when your pin does. Every run prints the browser and version it used.
