# Guardrails The guardrail kits hold an app to Ouro UI: the aim is that every control a person can reach is an Ouro control, and the number that are not can only fall.[^ratchets] The **census** (`ouro-census`) measures the running app, page by page and state by state. The **source rule** (`ouro-source-rules`) reads the app's source and finds the controls still built by hand. Each keeps a committed baseline, so every change is a reviewed diff, and each refuses a rise unless you record why.[^baselines] Add them from the same place and release tag as your components: ```sh npx shadcn@latest add ourostack/ouro-ui/ouro-census#v1.2.13 ourostack/ouro-ui/ouro-source-rules#v1.2.13 ``` `ouro-census` installs `e2e/ouro-census/` and names `@playwright/test` and `axe-core` as devDependencies. `ouro-source-rules` installs `scripts/ouro-source-rules.mjs` and names `typescript` and `postcss`. Like the test kit, they carry no version, so the CLI installs a package only when your app lacks it.[^kit-versions] The census reads names with axe-core and needs 4.13.0 or later: on an older one it throws before it loads axe into the page, naming the version it found.[^census-axe] ## The census A control's identity is one line: its role, its accessible name, its Ouro marker and part (`data-ouro-control` / `data-ouro-part`, `-` when there is none) and its context, the nearest landmark, dialog or named group, else the nearest `data-testid`.[^identity] Never its position: ```text button "Save" [button/root] in main option "Weekly" [select/item] in dialog "Repeat" link "Notes" [-/-] in testid "note-actions" ``` A state's census is the exact multiset of its visible controls. Whitespace in names collapses, and a relative time ("2 minutes ago") or a calendar date ("Jun 1, 2026") becomes `` or ``, so a name never depends on when the run happened.[^names] ### List the journeys A journey is a page your app renders, as the visitor who sees it, and the states a person can open on it: dialogs, menus, sheets, popovers, disclosures. Each state starts from a fresh load of the journey's `path`.[^fresh-load] Write its `action` to only open things, never to submit, so the census leaves your test data alone. ```ts // e2e/census.spec.ts import { test } from "@playwright/test"; import { censusTests, type Journey } from "./ouro-census/census-page.mjs"; const journeys: Journey[] = [ { id: "home", enrolled: false, path: "/", states: [{ id: "default" }] }, { id: "note", enrolled: true, path: "/notes/1", storageState: "e2e/.auth/writer.json", states: [ { id: "default" }, { id: "delete-dialog", action: async (page) => { await page.getByRole("button", { name: "Delete" }).click(); await page.getByRole("alertdialog").waitFor(); }, }, ], }, { id: "not-found", enrolled: false, path: "/no-such-page", status: 404, states: [{ id: "default" }] }, ]; censusTests({ test, journeys, projects: ["chromium", "webkit"], componentsDir: "src/components/ouro" }); ``` `projects` lists every Playwright project the spec runs in; a run that leaves one out fails the merge.[^merge-projects] `componentsDir` is where your app installs Ouro components: a marker naming no file there fails an enrolled journey.[^known-items] Pass `prepare` to wait for hydration after each load, and your own `test` to use your fixtures. Each test fails when the page answers another status (`status`, 200 by default) or redirects, since it would measure some other page.[^status] ### Run it and accept changes Each worker writes its census to `ouro-census/` (or `OURO_CENSUS_DIR`).[^worker-files] After the run, merge them and keep the result as the run's artifact, pass or fail: ```yaml - run: npx playwright test e2e/census.spec.ts - if: ${{ !cancelled() }} run: node e2e/ouro-census/census-merge.mjs ouro-census census-actual.json - if: ${{ !cancelled() }} uses: actions/upload-artifact@v4 with: name: ouro-census-actual path: census-actual.json ``` The merge fails, writing nothing, when any project skipped a state, recorded one twice, or recorded one the list lacks. Each state must equal `e2e/ouro-census/census.baseline.json` exactly: an added, removed, renamed, re-marked or duplicated control fails with a diff, and a state the baseline lacks fails with "no baseline".[^exact] To accept a change, rewrite the baseline from the run and commit it: ```sh node e2e/ouro-census/census-update.mjs # downloads the artifact with gh node e2e/ouro-census/census-update.mjs census-actual.json # or reads a local file ``` The census must be deterministic. Before baselining new journeys, run the same commit twice and compare: `node e2e/ouro-census/census-compare.mjs ` fails, naming every difference, unless both runs recorded the same multisets. Measure lists of run-specific data (this run's users, anything another test creates) in a state that cannot show it, such as a search that matches nothing. ### Enrol and ratchet An enrolled journey fails on any control without an Ouro marker. An unenrolled one is measured, and its unmarked count may only fall, state by state on each project: a fall in one state never pays for a rise in another.[^per-state] The update refuses a rise unless `--allow-regression ""` says why, and records it under `$allowedRegressions` until the next update. It also refuses to drop a journey or state the baseline has unless `--remove ` (or ``) names it and `--remove-reason ""` says why; a renamed journey is a drop plus a new one, and may not start with more unmarked controls than the one it replaces. Set `enrolled: true` on a journey once its controls are all Ouro's. ## The source rule The source rule reads every `.ts` and `.tsx` file under your source folder with the TypeScript compiler, and every `.css` file with PostCSS, skipping the Ouro installs (`components/ouro/`, `lib/ouro/`), tests, stories and declarations.[^scan] It finds: - a raw `