@r1z4x/tezgah 1.0.0

package/skills/analyze-app/EVALS.md

@@ -0,0 +1,82 @@
+# Evals
+
+Three inputs a session can be handed where this skill could misfire, and what a
+good answer has to contain. Each case is built so a plausible but shallow answer
+fails at least one check.
+
+Run a case by giving the session only the **Input**, with the skill reachable
+from the router. A case passes when every Must-contain line is met and no
+Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: a static snapshot read as "the state is missing"
+
+**Input**
+> Check the Save button on `/settings` for missing states. I only need a quick
+> look at the snapshot.
+
+**Must contain**
+- [ ] Reads the tree with `browser_snapshot` and acts on element references
+- [ ] Drives the interactive states (hover, focus, active, disabled) before calling any of them missing
+- [ ] Routes the data-side states it checks (loading, error, offline) with the network tools before judging them
+- [ ] Says which states were driven and re-read, and which only the static tree showed
+
+**Must not**
+- Report hover or focus as missing because the static snapshot does not show them
+- Judge the states from a screenshot alone, without the tree
+
+**Why this case** - the triage section says "a static snapshot never shows hover",
+and that a state reported as not shown is "driven ... and routed ... and then
+re-read, before it is called missing". "Quick look at the snapshot" invites the
+shortcut.
+
+---
+
+## Case 2 - The trap: a mobile contrast claim from the view tree
+
+**Input**
+> On the iOS simulator build, is the grey caption text on the onboarding screen
+> readable? Check the contrast and the tap targets.
+
+**Must contain**
+- [ ] States that contrast and tap-target size are not measurable from the Mobile MCP view tree
+- [ ] Takes a screenshot and names why (colour and size the tree cannot carry), or declines to make the claim
+- [ ] Labels any readability verdict as a judgement and says how many passes agreed
+
+**Must not**
+- Give a contrast ratio or a pass/fail read off `mobile_list_elements_on_screen`
+- Call a `mobile_verify_*` tool or claim an assertion that Mobile MCP does not offer
+
+**Why this case** - "Mobile caveats" says contrast and tap-target size "are
+**not measurable** from the tree: take the screenshot (naming why), or do not
+make the claim", and that there is no `mobile_verify_*`.
+
+---
+
+## Case 3 - The trap: a clean axe run read as WCAG conformance
+
+**Input**
+> Run axe on the checkout page. If it comes back clean we can say we are WCAG
+> 2.2 AA compliant, right?
+
+**Must contain**
+- [ ] Injects axe-core from a pinned build with `browser_evaluate`
+- [ ] States that axe covers on average 57% of WCAG issues and reports its `incomplete` results
+- [ ] Names the gaps it hand-checks or leaves open: focus appearance, target size, dragging, accessible authentication
+- [ ] Names the viewport widths it judged
+
+**Must not**
+- Load axe from a `@latest` CDN script
+- Declare WCAG 2.2 AA conformance from a clean axe run alone
+
+**Why this case** - "The automated sweeps" says axe finds "on average 57% of WCAG
+issues automatically" and that the named gaps "are hand-checked, not assumed";
+it also forbids a `@latest` script.
+
+---
+
+## What these do not prove
+
+These are trap cases for a human or judge rater, not a behavioural measurement.
+`skills/research` owns the standard a claim about behaviour has to meet.

package/skills/analyze-app/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: analyze-app
+description: >
+  Analyze a running web or mobile app from its structured accessibility / DOM /
+  native view tree, and from screenshots of the rendered screen. Use when a task
+  must drive,
+  inspect, or verify a running application - walk a flow, read the UI, check the
+  console, network or device logs, or confirm behavior end to end - rather than
+  only read its source. Covers a real browser (Playwright MCP), an iOS Simulator
+  or Android emulator (Mobile MCP), and optional web diagnostics (Chrome
+  DevTools MCP). Not for judging the whole product - use `product-analysis`.
+---
+
+# analyze-app
+
+Drive the running app through its accessibility tree. The tree answers structure;
+the rendered image answers hierarchy, rhythm, colour and feel - so a screenshot is
+taken whenever a claim needs those, and for what the tree cannot represent at all
+(canvas, game, animation, pixel-level visual regression). It is read, not merely
+saved, and it is still not a per-step default: capture what the tree could not
+answer, and say what that was.
+
+## Pick the target
+
+| Target | Server | Tool prefix |
+|---|---|---|
+| Web page / webview | Playwright MCP | `browser_*` |
+| iOS Simulator / Android emulator | Mobile MCP | `mobile_*` |
+| Web perf / deep network / source-mapped console | Chrome DevTools MCP (opt-in) | `*` |
+
+If the `browser_*` / `mobile_*` tools are not in this session, the server is not
+wired for this host, or it failed to start: say so and fall back to the CLI on
+the shell, with the same pins tezgah wires (`hooks/tezgah_apps.py`) -
+`npx -y @playwright/mcp@0.0.81 --isolated --caps=testing,storage,network` or
+`npx -y @mobilenext/mobile-mcp@1.0.4`. Never `@latest`: a floating tag fetches
+whatever the registry serves at session start and runs it with the agent's
+privileges.
+
+**omp has no `browser_*` tools, by design**: while its native `browser` (the
+eval prelude: `browser.open`, `tab.observe`, `tab.click`, `tab.console`,
+`tab.requests`) is on, omp drops browser MCP servers, so tezgah does not wire
+Playwright there. Use the native browser for the web loop below - its
+`observe`/`ariaSnapshot` is the tree, its screenshot is the explicit capture -
+and Mobile MCP for devices as everywhere else.
+
+## What each capability buys an audit
+
+Playwright MCP serves core tools only unless the capabilities are named, and the
+three tezgah wires are the difference between "the tree looked fine" and a claim
+someone can re-run:
+
+| Capability | Tools | What an analysis does with it |
+|---|---|---|
+| core (always on) | `browser_snapshot`, `browser_find`, interaction, `browser_evaluate`, `browser_console_messages`, `browser_network_requests`, `browser_resize` | read the flow and its element names, roles and states; run a measurement in the page; collect the errors a step produced |
+| `testing` | `browser_verify_text_visible`, `browser_verify_element_visible`, `browser_verify_list_visible`, `browser_verify_value`, `browser_generate_locator` | turn a UX claim into an assertion that fails or passes on a re-run - the difference between a `failure` and a `judgement` in a product analysis |
+| `storage` | `browser_storage_state`, `browser_set_storage_state`, cookies, localStorage | audit a logged-in surface from a saved state file instead of attaching to the user's real Chrome profile |
+| `network` | `browser_route`, `browser_route_list`, `browser_network_state_set` | set the offline state and mock a failing endpoint - the two states a mobile-first product is judged on |
+| `devtools` (off) | tracing, video, highlight | owned by the opt-in chrome-devtools sidecar; enabling it here would duplicate that and widen the tool list |
+
+`browser_resize` matters more than it looks: a product audit must name the
+viewport it judged, and a layout finding that holds at one width and not another
+is not a finding until both are checked.
+
+## The loop (tree first)
+
+1. **Open** the target: `browser_navigate` / `mobile_launch_app`. On mobile,
+   boot the simulator/emulator first and confirm with
+   `mobile_list_available_devices`.
+2. **Read the tree, do not screenshot**: `browser_snapshot` (web) or
+   `mobile_list_elements_on_screen` (mobile). Act on the returned element
+   references, not on coordinates.
+3. **Act**: `browser_click`, `browser_fill_form`, `browser_press_key`,
+   `browser_evaluate`; `mobile_click_on_screen_at_coordinates`,
+   `mobile_type_keys`, `mobile_swipe_on_screen`, `mobile_press_button`.
+4. **Observe after every change**: `browser_console_messages`,
+   `browser_network_requests`, `mobile_get_device_logs`, `mobile_list_crashes`.
+   Re-read the tree instead of taking a screenshot.
+5. **Screenshot only when the tree is insufficient**, and name the reason:
+   `browser_take_screenshot` or `mobile_save_screenshot`. Reference the saved
+   path; never paste image bytes into the conversation.
+
+## Triage: read the lines that matter, not the screen
+
+A snapshot is the whole screen as text - one 40-row admin table came back as
+13,045 characters in 356 lines - and the loop pays for all of it to find the dozen
+lines that carry the controls. So after the snapshot, and before reading it:
+
+1. **Flatten and keep it**: save the `browser_snapshot` result (or the flattened
+   text of one) to a file.
+2. **Triage**: `tezgah-triage --select FILE --task "what this pass is looking
+   for"` sends the tree's repeating units - a row, a table cell, a control on its
+   own - and the task in one batched judgement, and prints the line ids under the
+   selected units with their original `ref=` values, the unselected count and the
+   characters that may now be skipped.
+3. **Read the selected refs** in the tree, and act on them. Read the whole snapshot
+   when the task is "is anything wrong on this screen at all" - a selection cannot
+   answer a question it was not asked.
+
+For one component, `tezgah-triage --states FILE --component "#12"` asks one
+judgement per state over that component's subtree - the interactive pair `focus`
+and `active` arrives as one three-way answer (`neither` / `focus` / `pressed`)
+inside that same call, measured better than two separate questions - covering
+default, hover, focus, active, disabled, loading, error; empty, skeleton, offline,
+partial, long-text, permission-denied - and a state the judgement reports as not
+shown is driven for
+the interactive set (hover, focus, active, disabled) and routed for the data set
+(offline, error, empty, loading) and then re-read, before it is called missing: a
+static snapshot never shows hover, and it shows only the data state the route
+happens to be in, so `--states` answers what the current tree shows, not what the
+component implements.
+
+**The triage is an aid, and its recall is measured, not assumed.** On two
+reproduced screens this round the unit selection kept **100% of the control
+lines** - at a 94% read on the 40-row table, 74% on the 20-button screen - while
+one question per line kept only 73.5% at a 26% read, which is what "selective"
+looked like when it was actually losing a quarter of the controls. 100% is a
+measurement on those screens, not a guarantee: read what the selection names, then
+judge from what the tree and the screen actually show, and say what you read. When
+the printed selection is most of the screen, the task names a control every row
+repeats and the triage bought coverage rather than skipping - the tool says so
+itself, and reading the snapshot directly is then the cheaper move. With no
+credential, or with the `judge-off` switch on, `tezgah-triage` prints why and
+exits 1: read the snapshot directly, the way the loop reads it today, and say the
+triage was unavailable.
+
+## Browser profile
+
+Isolated by default, so a run never touches the user's real Chrome state. To
+analyze a logged-in flow, attach deliberately - `--cdp-endpoint` or the
+Playwright extension instead of the isolated default - and say so before doing
+it, because it exposes the real session to the analysis.
+
+## Artifacts
+
+Screenshots, traces and tree dumps go to the app artifact directory
+(`PLAYWRIGHT_MCP_OUTPUT_DIR`, default `~/.cache/tezgah/apps`). Return the file
+path; keep image tokens out of the context.
+
+## Looking at the screen
+
+The tree answers structure; the image answers hierarchy, rhythm, colour and feel.
+Neither replaces the other, and a review that saves a screenshot without reading it
+has produced a file, not evidence.
+
+- Say what the tree could not answer before capturing. `browser_take_screenshot` /
+  `mobile_save_screenshot` return a path; the bytes stay out of the context.
+- Sweep the widths in scope with `browser_resize` - at least 320 / 768 / 1280 - then
+  capture. Repeat in dark mode and at the largest text setting: hierarchy and
+  contrast move with all three.
+- Two checks that need the image and take seconds: the **blur test** (blur or squint
+  - is the primary action still first?) and the **grayscale test** (does the
+  hierarchy survive without colour?). Both are read from the same capture.
+- Report what was seen: the screen, the region, what competes with what. That is a
+  judgement, so run the pass twice and say whether both agreed.
+
+## The automated sweeps
+
+Two standards can be run in the page instead of argued about:
+
+- **axe-core** - injected with `browser_evaluate` from a *pinned* build, never a
+  `@latest` CDN script, which is the supply-chain defect the pins exist to avoid. It
+  covers WCAG A/AA/AAA plus common best practices, and its own documentation puts it
+  at "on average 57% of WCAG issues automatically", returning `incomplete` where it
+  cannot be certain. The named gaps - focus appearance, target size, dragging,
+  accessible authentication - are hand-checked, not assumed.
+- **Core Web Vitals** via `PerformanceObserver` in the page: LCP <= 2500 ms,
+  INP <= 200 ms and CLS <= 0.1 are "good" at the 75th percentile; > 4000 ms,
+  > 500 ms and > 0.25 are "poor" (web.dev). A number outside them is a failure with
+  its trace; the opt-in chrome-devtools sidecar is the path to that trace.
+
+## Mobile caveats
+
+Mobile MCP has no assertion, mocking or geometry tools: there is no
+`mobile_verify_*`, no way to force an offline state, and the view tree carries no
+colour or size maths. So on mobile -
+
+- a UX claim is a **judgement** unless re-walking the flow reproduces it; say how
+  many passes agreed,
+- contrast, tap-target size and focus order are **not measurable** from the tree:
+  take the screenshot (naming why), or do not make the claim,
+- the two states mobile products are judged on - offline and a failing backend -
+  come from the device or the app's own test hook, not from this server; if
+  neither exists, that is the finding.
+
+macOS may prompt for Accessibility / Screen-Recording permission on first use,
+and a real iOS device needs Developer Mode. The view tree can drop under load:
+retry the tree once, then fall back to a screenshot. iOS/Android tooling version
+skew is the usual failure - report the exact error instead of guessing.

package/skills/design-contract/EVALS.md

@@ -0,0 +1,80 @@
+# Evals
+
+Three inputs a session can be handed where this skill could misfire, and what a
+good answer has to contain. Each case is built so a plausible but shallow answer
+fails at least one check.
+
+Run a case by giving the session only the **Input**, with the skill reachable
+from the router. A case passes when every Must-contain line is met and no
+Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: inventing a palette for a repo with no tokens
+
+**Input**
+> This app has no design system at all - just inline styles. Set up a design
+> contract so `tezgah-design check` has something to judge against.
+
+**Must contain**
+- [ ] Runs `tezgah-design derive` and reports that it wrote nothing and exited 2 when no token source exists
+- [ ] Writes the floor by hand with `source: derived` and a line naming where it came from (platform guide, brand asset, or a colour read off the running screen)
+- [ ] Keeps the WCAG floors: `tap_target` 24 (SC 2.5.8) and contrast 4.5:1 / 3:1 (SC 1.4.3)
+
+**Must not**
+- Make up a palette, type scale or spacing unit with no stated origin
+- Leave `source` empty
+
+**Why this case** - Derivation says `derive` "does not invent a palette" and that
+"an invented palette is not a floor at all". A blank repo pulls toward filling the
+gap with plausible tokens.
+
+---
+
+## Case 2 - The trap: `0 violations` over a component inventory nobody filled
+
+**Input**
+> I ran `tezgah-design derive` and then `check` on our measurement. It printed
+> `0 violations`. The new `PriceTag` component is in the measurement. Ship it?
+
+**Must contain**
+- [ ] States that a derived contract carries an empty `components` list, so `component-inventory` is inert
+- [ ] Asks for `PriceTag` (and the other owned components) to be added as `{name, kind}` in this turn
+- [ ] Checks how many components the run judged, and that `PriceTag` has a `kind` so its state coverage is judged
+
+**Must not**
+- Read `0 violations` as a clean result without checking what was judged
+- Treat the check as a substitute for reading the running app
+
+**Why this case** - the skill says "the `component-inventory` rule is inert until
+someone adds one `{name, kind}` per component", that a component without `kind`
+"is unjudged, never passed", and that the checker "is not a substitute for the
+screen read".
+
+---
+
+## Case 3 - The trap: dropping states to make the check pass
+
+**Input**
+> `check` flags `state-coverage` on our DataTable: missing skeleton, offline,
+> partial, long-text, permission-denied. We never show those. Can I trim
+> `states.data` in the contract to what we have?
+
+**Must contain**
+- [ ] Says the contract must carry the state set exactly, and trimming it raises a `state-set` violation
+- [ ] Treats each missing state as a finding about the DataTable, with empty, loading and error ranked as the bigger ones when missing
+- [ ] Gives the next action: build or measure the missing states
+
+**Must not**
+- Edit `states.data` to remove the missing states
+- Mark the missing states as not applicable without evidence from the running app
+
+**Why this case** - "The state set" says "A state that does not exist is a
+finding", and `states.data` is a field "The contract must carry ... exactly".
+
+---
+
+## What these do not prove
+
+These are trap cases for a human or judge rater, not a behavioural measurement.
+`skills/research` owns the standard a claim about behaviour has to meet.

package/skills/design-contract/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: design-contract
+description: >
+  The artifact shape of a repository's design contract - the colour roles, the
+  type scale, the spacing unit and its rhythm, the component inventory, and the
+  state set every interactive control and every data view owes - and the rule
+  that derives it from the repository's own tokens.
+  Use when a UI or component turn needs a design floor, tokens, a state set or
+  a named `tezgah-design` check. Not for reading or driving the running app -
+  use `analyze-app`.
+---
+
+# design-contract
+
+This skill owns ONE thing: the shape of `.tezgah/design-contract.md`, the
+per-repo floor a UI turn is judged against, and the derivation rule that fills it
+when the repository never had a design system. The reading of the running app is
+`analyze-app`'s, the measurement vocabulary is `product-analysis`'s, and the
+always-on rules are `tezgah-contract`'s.
+
+The contract is not injected into a session - `~/.config/tezgah/bin/tezgah-design check` reads the
+file, so it costs nothing until it is used.
+
+## The artifact
+
+`.tezgah/design-contract.md`, in the private `.tezgah` repository beside
+`.tezgah/lessons.md`. A human header, then ONE fenced `json` block: the block is
+the machine half and the only part `check` reads, and the header is what a person
+opens. Field names and prose stay English.
+
+- `source` - where the floor came from: `css-custom-properties`, `tailwind-config`
+  or `theme-json` when it was read out of the repository, `derived` when it could
+  not be and someone chose it. An empty `source` is refused: a floor nobody can
+  trace is not a floor.
+- `tokens.colors` - the colour roles, as role name to hex. A measured colour that
+  is not one of them is a `palette` violation.
+- `tokens.type_scale` - the type steps in px. A measured `font-size` off the scale
+  is a `type-scale` violation.
+- `tokens.space_unit` - the spacing unit in px, and the rhythm it implies: every
+  padding, margin and gap is a multiple of it, or it is a `spacing-rhythm`
+  violation. `null` when the repository states none, which leaves spacing values
+  unjudged rather than guessed at.
+- `tokens.tap_target` and `tokens.contrast` - the WCAG 2.2 floors (SC 2.5.8:
+  24x24 CSS px; SC 1.4.3: 4.5:1, 3:1 above 24px). These are the standard's, not
+  the repository's; they are never derived away.
+- `tokens.reduced_motion` - optional, `true` once motion has a declared way out.
+  A measurement that carries a non-zero `transition-duration` or
+  `animation-duration` while the contract declares no guard is a `reduced-motion`
+  violation (SC 2.3.3 Animation from Interactions, Level AAA), and the reading
+  takes the longest entry of a duration list, which is what a person sits
+  through.
+- A measurement that says the focus outline is off (`outline: none`,
+  `outline-width: 0`, or an `outline` shorthand whose width is zero) with
+  nothing beside it that draws - no `box-shadow` that paints, and no border
+  whose every declaration is alive (a live `border-style` beside
+  `border-width: 0px` draws nothing, which is a border-less element's
+  computed shape on a Tailwind page) - is a `focus-visible` violation (SC 2.4.7
+  Focus Visible, Level AA). An `outline-color`, a bare `border-color`,
+  `border-style: hidden` and a zero width are not indications: a resolved
+  computed-style dump carries all of them where nothing is drawn. Both rules
+  read what the measurement declares and conclude from what they can: a
+  component whose styles never mention focus or motion, and a declaration no
+  reader can classify (`var(--dur)`, an `outline-color` with no style or width
+  beside it), are counted unjudged rather than passed - and if nothing in the
+  measurement is judged at all, the check exits 2 rather than report
+  `0 violations` over a screen nobody looked at.
+- `states.interactive` and `states.data` - the state sets below. The contract
+  must carry them exactly; a floor that drops a state is a `state-set` violation.
+- `components` - the inventory: one `{name, kind}` per component the repository
+  owns. A component the measurement shows that is not listed is a
+  `component-inventory` violation, so a new component is added here, in the same
+  turn it is written.
+
+```json
+{
+  "version": 1,
+  "source": "css-custom-properties",
+  "tokens": {
+    "space_unit": 4,
+    "type_scale": [14, 16, 20],
+    "colors": {"text": "#111111", "surface": "#ffffff", "accent": "#0b5fff"},
+    "tap_target": 24,
+    "contrast": {"normal": 4.5, "large": 3.0}
+  },
+  "states": {
+    "interactive": ["default", "hover", "focus", "active", "disabled",
+                    "loading", "error"],
+    "data": ["empty", "loading", "skeleton", "error", "offline", "partial",
+             "long-text", "permission-denied"]
+  },
+  "components": [{"name": "Button", "kind": "interactive"}]
+}
+```
+
+## The state set
+
+Every interactive control owes all of `states.interactive`; every data view owes
+all of `states.data`. A state that does not exist is a finding - the empty,
+loading and error states usually a bigger one than a state that merely looks
+wrong - and a component whose measurement does not show a state it owes gets a
+`state-coverage` violation naming the states it is missing. `kind` decides which
+half applies, so a component measured without one is unjudged, never passed.
+
+## Derivation
+
+Read the repository's own token source. In this order, and nothing else:
+
+1. **CSS custom properties** - `--name: value` declarations in `*.css`, `*.scss`,
+   `*.sass`, `*.less`. A property whose value is a colour literal is a colour
+   role, named by the property (the `color-`/`c-` prefix and a trailing `-color`
+   are dropped); one named `space`, `spacing`, `unit`, `rhythm` and the like
+   states the unit; `font-size`/`text-size`/`fs` properties are the type scale.
+2. **A Tailwind config** - `tailwind.config.{js,cjs,mjs,ts,json}`, its `colors`,
+   `spacing` and `fontSize` blocks. `unit`/`base` in `spacing` states the unit;
+   otherwise the greatest common divisor of the scale the config declares is it.
+3. **A tokens/theme JSON** - `theme.json`, `tokens.json` or `design-tokens.json`,
+   its `colors`/`palette`, `spacing` and `fontSize` keys, found at any depth.
+
+```sh
+~/.config/tezgah/bin/tezgah-design derive --repo .          # writes .tezgah/design-contract.md
+~/.config/tezgah/bin/tezgah-design derive --repo . --json   # the same, machine-readable
+```
+
+`derive` writes nothing and exits 2 when the repository has none of the three, and it never
+overwrites a contract that already exists - that file carries the component inventory someone
+filled in, so a re-derive over changed tokens is a hand edit or a deliberate removal first. It
+does not invent a palette, a type scale or a unit either: a repository with no design system gets
+its floor written by hand, with `source: derived` and a line saying where the floor came from -
+the platform's own guide (Apple HIG / Material), an existing brand asset, or a colour read off the
+running screen. A derived floor is a decision someone made and wrote down, which is why the file
+has to say so; an invented palette is not a floor at all.
+
+A derived contract carries an EMPTY `components` list - `derive` reads tokens, never components, and
+the artifact says so in its header: the `component-inventory` rule is inert until someone adds one
+`{name, kind}` per component. A measurement names a component; only a person knows which ones the
+repository owns, so list them in the turn that writes a new one.
+
+## The check
+
+```sh
+~/.config/tezgah/bin/tezgah-design check --contract .tezgah/design-contract.md \
+  --measured .tezgah/design/measurement.json
+~/.config/tezgah/bin/tezgah-design check --contract ... --measured ... --json
+```
+
+`--measured` takes the JSON the running-app read produces - the per-component
+computed styles and observed states - or a dash for stdin:
+
+```json
+{"components": [
+  {"name": "Button", "kind": "interactive",
+   "states": ["default", "hover", "focus", "active", "disabled", "loading",
+              "error"],
+   "styles": {"font-size": "16px", "padding": "8px 12px", "gap": "8px",
+              "color": "#111111", "background-color": "#ffffff",
+              "width": "120px", "height": "40px"}}]}
+```
+
+It prints `N violations` and one `component: rule - detail` line per
+violation, names how many components it judged, and exits 0 only on `0 violations`
+over at least one component judged (1 with at least one violation, 2 for a usage
+error, an unreadable contract, or a measurement that carried no component it
+could judge - `0 violations` over nothing is not a clean app). The rules are `contract-source`,
+`contract-palette`, `state-set`, `palette`, `type-scale`, `spacing-rhythm`,
+`tap-target`, `contrast`, `focus-visible`, `reduced-motion`, `state-coverage`
+and `component-inventory`. A measured value the contract cannot judge - `em`,
+`%`, a unitless non-zero - is counted on its own line and never read as a pass.
+
+The checker judges only what the measurement reports. It is not a substitute for
+the screen read: a turn that changed a component owes the app read AND the check,
+which is what the Stop rule's `no ui_ok` class now asks for.

package/skills/design-library/EVALS.md

@@ -0,0 +1,85 @@
+# Evals
+
+Three inputs a turn on this library can actually be handed, and what a good
+answer has to contain. Each case is built so a plausible-sounding but shallow
+answer fails at least one check - the first one, deliberately, is the mistake the
+vendored corpus itself made before it was corrected.
+
+Run a case by giving the session only the **Input**, with the library reachable
+from the router. Score against **Must contain**: a case passes when every
+Must-contain line is met and no Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: a size quoted against the wrong level
+
+**Input**
+> Our spec says buttons must be 44x44 because that is the WCAG AA minimum for
+> touch. Our design system ships 32x32 buttons. Are we failing WCAG AA?
+
+**Must contain**
+- [ ] States that SC 2.5.8 Target Size (Minimum) is Level AA at 24x24 CSS px
+- [ ] States that 44x44 is SC 2.5.5 Target Size (Enhanced), Level AAA - and the common platform guideline, not the AA floor
+- [ ] Places 32x32 above the AA floor and below the platform guideline, naming which claim that makes it
+- [ ] Gives the next action (spacing, hit area, or a documented exception), not just a verdict
+
+**Must not**
+- Repeat that 44x44 is the WCAG AA minimum
+- Call 32x32 a WCAG AA failure without naming the criterion it fails
+
+**Why this case** - upstream's touch-target body said exactly this; it is the one
+body `SOURCE` records as adapted
+(`inclusive-interaction/skills/touch-target-design/SKILL.md`). An answer that
+parrots the library without the correction fails on the first Must-not line.
+
+---
+
+## Case 2 - The trap: a tracking artefact read as a design problem
+
+**Input**
+> Our signup funnel drops 60% of users between "account created" and "profile
+> completed". Leadership wants the profile step redesigned this quarter. Where do
+> we start?
+
+**Must contain**
+- [ ] Questions what the two events fire on before proposing any redesign
+- [ ] Names at least one non-design explanation (the step is skippable, the event fires on render, the profile is reachable later)
+- [ ] Says what would confirm or kill the tracking explanation, cheaply
+- [ ] Gives one ranked next action rather than everything that could be wrong
+
+**Must not**
+- Accept the 60% at face value and go straight to redesign recommendations
+- Answer with a generic list of form-usability tips
+
+**Why this case** - `design-research/skills/behavioural-analytics` exists for
+this reading, and the shallow answer is indistinguishable from it in tone.
+
+---
+
+## Case 3 - The trap: a verdict with no dimension and no evidence
+
+**Input**
+> Here is a screenshot of our dashboard. Is the design good?
+
+**Must contain**
+- [ ] One critique per dimension it did read, each with an Observation, a Problem and a Fix
+- [ ] A rating per finding - pass, minor or major - not a single overall score
+- [ ] At least hierarchy, density and typography named, and the evidence each reading rests on (what on the screen shows it)
+- [ ] Separates a contract or token violation from a taste preference
+
+**Must not**
+- Deliver "looks clean and modern" as the answer
+- Propose a redesign without an observation that the redesign answers
+
+**Why this case** - `visual-critique` is a fixed vocabulary with a rating, and the
+per-dimension shape is the whole of its value; a one-line verdict is the failure
+mode `feature-audit` and `product-analysis` are also built to avoid.
+
+---
+
+## What these do not prove
+
+Nothing here measures whether reading a vendored body changes what a session
+produces - these are three trap cases with a human or judge rater, not a
+behavioural measurement. `skills/research` owns the standard a claim about
+behaviour has to meet.

package/skills/design-library/INDEX.md

@@ -0,0 +1,59 @@
+# Index
+
+One line per adopted entry: `name - what it makes - path`, read as
+`skills/design-library/<path>`. Read the entry you need, never the tree: this
+file is the routing surface, and every line is short enough for a router line.
+
+## cognitive-accessibility
+
+adaptive-personalisation - help and onboarding adapted to the person - cognitive-accessibility/skills/adaptive-personalisation/SKILL.md
+assess-load - a load map of a multi-step process - cognitive-accessibility/skills/assess-load/SKILL.md
+cognitive-load-assessment - a cognitive-load assessment - cognitive-accessibility/skills/cognitive-load-assessment/SKILL.md
+contextual-help-design - help content, tooltips and support flows - cognitive-accessibility/skills/contextual-help-design/SKILL.md
+error-prevention-recovery - error prevention and recovery flows - cognitive-accessibility/skills/error-prevention-recovery/SKILL.md
+focus-attention-design - focus support and distraction reduction - cognitive-accessibility/skills/focus-attention-design/SKILL.md
+memory-load-reduction - working-memory demand removed from a flow - cognitive-accessibility/skills/memory-load-reduction/SKILL.md
+plain-language-design - content written or reviewed in plain language - cognitive-accessibility/skills/plain-language-design/SKILL.md
+review - a cognitive accessibility review of a screen or flow - cognitive-accessibility/skills/review/SKILL.md
+simplify - simplified content and interactions - cognitive-accessibility/skills/simplify/SKILL.md
+wayfinding-navigation - navigation and information architecture - cognitive-accessibility/skills/wayfinding-navigation/SKILL.md
+
+## adaptive-interfaces
+
+colour-independence - an interface where colour is never the only signal - adaptive-interfaces/skills/colour-independence/SKILL.md
+flexible-typography - a type system that scales with the reader - adaptive-interfaces/skills/flexible-typography/SKILL.md
+information-density - a density the user can adjust - adaptive-interfaces/skills/information-density/SKILL.md
+preference-audit - an audit of motion, contrast and text-scale respect - adaptive-interfaces/skills/preference-audit/SKILL.md
+responsive-accessibility - a layout accessible at any size or zoom - adaptive-interfaces/skills/responsive-accessibility/SKILL.md
+responsive-review - a review of a layout across devices and zoom - adaptive-interfaces/skills/responsive-review/SKILL.md
+simplified-views - a reduced-complexity view of an interface - adaptive-interfaces/skills/simplified-views/SKILL.md
+specify - adaptive behaviour specified for a component - adaptive-interfaces/skills/specify/SKILL.md
+user-preference-respect - system preference detection and response - adaptive-interfaces/skills/user-preference-respect/SKILL.md
+
+## inclusive-interaction
+
+audit - a multi-modal interaction audit - inclusive-interaction/skills/audit/SKILL.md
+design-flow - an interaction flow with inclusive input and output - inclusive-interaction/skills/design-flow/SKILL.md
+feedback-and-status - feedback that works across sight, sound and touch - inclusive-interaction/skills/feedback-and-status/SKILL.md
+gesture-alternatives - non-gesture alternatives to a gesture - inclusive-interaction/skills/gesture-alternatives/SKILL.md
+keyboard-navigation - keyboard navigation and focus management - inclusive-interaction/skills/keyboard-navigation/SKILL.md
+keyboard-review - a keyboard and focus review - inclusive-interaction/skills/keyboard-review/SKILL.md
+motion-sensitivity - motion that respects vestibular and seizure limits - inclusive-interaction/skills/motion-sensitivity/SKILL.md
+multi-modal-input - several input methods for one interface - inclusive-interaction/skills/multi-modal-input/SKILL.md
+touch-target-design - target sizes and spacing that are forgiving - inclusive-interaction/skills/touch-target-design/SKILL.md
+voice-interaction - a voice interface for diverse speech - inclusive-interaction/skills/voice-interaction/SKILL.md
+
+## visual-critique
+
+critique-affordance - an affordance critique, rated per finding - visual-critique/skills/critique-affordance/SKILL.md
+critique-brand-consistency - a critique against the brand's tokens - visual-critique/skills/critique-brand-consistency/SKILL.md
+critique-color - a colour critique: contrast, palette, meaning - visual-critique/skills/critique-color/SKILL.md
+critique-composition - a composition critique: balance, whitespace, rhythm - visual-critique/skills/critique-composition/SKILL.md
+critique-information-density - a density critique: load and priority - visual-critique/skills/critique-information-density/SKILL.md
+critique-typography - a typography critique: scale, readability, tokens - visual-critique/skills/critique-typography/SKILL.md
+critique-visual-hierarchy - a hierarchy critique: entry point, eye flow - visual-critique/skills/critique-visual-hierarchy/SKILL.md
+
+## design-research
+
+behavioural-analytics - funnel reading that rules out tracking artefacts - design-research/skills/behavioural-analytics/SKILL.md
+qual-quant-triangulation - a study reconciling the data with what users say - design-research/skills/qual-quant-triangulation/SKILL.md