idiom

readiness for AI-built software · every state, not every page

Capture → review → decide → repair → verify → remember

Your agent built it. Is it ready?

Idiom runs the product, opens the states that matter, judges the evidence against your design law, and remembers every human decision.

It is a generator-agnostic acceptance layer for the running product—not a component library, canvas, crawler, or autonomous redesign tool. Keep whatever writes your software. Add the proof that what it wrote is ready to ship.

The product, made visible

A design system derived from what you actually ship.

idiom system turns project law and rendered evidence into a page a human can inspect, print, and trust.

It brings authored tokens, observed palette and type, human design law, recorded rulings, standing prohibitions, and coverage into one read-only view. Every observed value points back to a flow, state, viewport, and colour scheme. Standing prohibitions carry the screenshot evidence that remains reachable; when an image or its report run is unavailable, the gap is stated plainly beside what was judged.

The result is self-contained, printable, offline, and model-free. It is a projection of evidence—not a second source of truth and not a promise that an older release contains a newer command.

The real Say When Idiom system page, showing its header, authored design-token swatches, evidence navigation, and the beginning of observed palette and typography coordinates
Real output from Say When. The crop shows the generated header, authored token swatches, and the evidence-derived observed section; the page continues through law, rulings, prohibitions, and disclosed coverage. source · Say When run 2026-08-20T13-43-38-374Z · captured commit 372a55c0a3c6224e4217e02d142a2e63c18c65fd · Idiom PR #30
60 / 60 declared booking tuples selected successfully source · Say When run 2026-08-20T13-43-38-374Z · commit 372a55c0a3c6224e4217e02d142a2e63c18c65fd
15 × 2 × 2 declared states × viewports × colour schemes source · Say When run 2026-08-20T13-43-38-374Z
PR #30 visual system shipped in the pinned release source · merged Idiom PR #30

Install · two-minute first result

From install to evidence in four commands.

You need Node >=20, Bun, Git, and working SSH access to GitHub. Run these in an unconfigured directory while your app is already available at a public or localhost URL.

install v0.2.0 · first quick review
$ bun add -g "git+ssh://git@github.com/mattskilly/idiom.git#v0.2.0"
$ idiom --version
0.2.0
$ bunx playwright@1.62.1 install chromium
$ idiom quick http://localhost:3000
source · release tag v0.2.0 · Playwright dependency 1.62.1 · quick shipped in PR #27

Access is currently by invitation while the repository is private.

Quick review prints the exact Markdown and HTML report paths. Open either report and read its “Quick-review limits” section before acting on a finding. The pinned release contains quick review, the visual-system page shown above, design exploration, desktop (Electron) capture targets, and the spacing-rhythm check derived from your product's own spacing.

Coverage is part of the result

It tells you what it judged—and what it could not.

Judged

Only the explicit same-origin public URLs you supply, at desktop 1440×900 and mobile 390×844, in light and dark. Deterministic checks run over four captures per supplied URL.

source · quick configuration · PR #27 · tag v0.2.0

Not judged

Fixture-dependent error and empty states, authenticated surfaces, destinations behind forms or interactions, product intent, design law, references, and design-token alignment.

source · quick report limits · PR #27 · tag v0.2.0
4 captures for each supplied URL; no crawling implied source · PR #27 · tag v0.2.0

A real judgment, carried to proof

Evidence becomes a bounded repair.

Idiom found this in Say When, a shipping product—not a fixture created for the landing page. A human accepted it, the build pipeline repaired it, and a recapture confirmed the change.

finding-11 major · confidence 0.8
Flow
booking · valid-known · desktop
Captured
e1eb68983e95b105ca8bf1b33c80666669ca9217
Layer
model · generic-pattern

The “Find more times” link rendered with a visible underline. The product's design law says hierarchy comes from weight and ink, and explicitly forbids underlined links in anything a recipient reads. The same choice recurred across bookable, taken, race, and error states, making it systemic.

“Underline links or bullet time lists in anything a recipient reads.” — Say When's DESIGN.md, quoted back with the finding

repair: remove the text-decoration underline; preserve affordance through ink, weight, hover, and focus.

✓ verified fixed source · legacy review run 2026-08-16T21-22-53-441Z · merged Say When PR #127

Capture → review → decide → repair → verify → remember

The acceptance loop has real files at every handoff.

  1. 01

    Capture

    idiom capture booking drives every declared tuple and creates an immutable run with screenshots, DOM, console and accessibility evidence, plus baseline.md.

  2. 02

    Review

    idiom review booking runs deterministic and judgment layers and writes findings.json, unruled-decisions.json, report.md, and report.html.

  3. 03

    Decide

    idiom decide --finding finding-11 --accept or --reject appends the human judgment to .idiom/decisions.jsonl.

  4. 04

    Repair

    idiom instruction --finding finding-11 emits a paste-ready brief, while idiom tickets --finding finding-11 hands bounded work to any generator.

  5. 05

    Verify

    idiom verify booking --spec path/to/spec.md performs an offline, model-free recapture and writes before-after.md, report.html, attachments.json, and comparison images.

  6. 06

    Remember

    idiom context [flow] carries decisions, rulings, prohibitions, and outstanding accepted work into the next repair instead of reopening settled judgment.

source · released command surface · capture, review, decision, ticket, verify, and context implementations

When the law does not exist yet

Nobody can write their design principles cold. Everyone can say “A, not B.”

idiom explore takes one state and one sentence of dissatisfaction, and renders three real directions of your own running product—no mockups, no canvas.

Each candidate is an isolated change to real components, captured through the same pipeline a review uses, compared as screenshots of your actual app. Choosing one records a rule in your design law, with your reason; that rule then governs every future review of every surface. Repair tickets are offered and declinable—the rule is the product. Exploration never enters the acceptance loop: review and verify stay deterministic.

ruling-1 explore · candidate A · recorded
Question
“the standing-link form feels off”
Rendered
3 directions · booking · standing-confirm
Recorded
2026-08-29 · Say When DESIGN.md

The winning direction found the cause a human could only feel: the standing-confirm inputs carried a bespoke, undocumented variant of the product's shared input tokens—same field, same product, two renderings.

“The same control type renders with one consistent set of shared tokens everywhere it appears in the product; a control does not get a bespoke, undocumented variant on a single screen.” — the rule the choice wrote into Say When's design law
rule recorded source · Say When exploration run 2026-08-29T20-07-58-571Z · DESIGN.md ruling-1

Keep your builder

Creation and acceptance are different jobs.

Whatever generates

Your agent, editor, framework, component system, and design tools keep writing the product. Idiom does not replace them or prescribe their stack.

Idiom accepts

It operates on rendered states, preserves the evidence and human ruling, emits bounded repair context, and proves the relevant surface again after the change.

Fast generation is abundant. Trustworthy readiness is the missing layer.