idiom · field guide
Your coding agent builds fast. Nobody looks at every screen in every condition. Idiom opens your real, running app, walks every state you declare — the expired link, the error message, mobile, dark mode — judges what rendered against your own design rules, and turns problems into small, provable fixes. Then it remembers what you decided, so the same argument never happens twice.
Crawlers and your own eyes see the happy path. Idiom drives fixture-fed states no crawler can reach — expired, taken, invalid, empty — at every viewport, in light and dark, on web pages and desktop (Electron) apps.
Screenshots tied to a commit. Findings that cite the rule they break. Before/after proof a fix landed. Reports that say what was not checked. Never a 0–100 score.
Reject a finding once — "that's intentional" — and it never comes back. Accepted taste becomes rules fed to your agent before it writes code. Review tools nag; Idiom learns.
idiom init mines your repo, interviews you for what code can't answer, and writes PRODUCT.md and DESIGN.md — your product's design law.
idiom capture starts your app for real and photographs every declared state × viewport × color scheme, keyed to the exact commit.
idiom review runs ten measurable checks (overflow, contrast, tap targets, console errors, breaks in your product's own spacing rhythm…) plus a model judge armed with your law. Five findings max.
You accept or reject each finding. Accepted ones become bounded tickets — or paste-ready instructions for Claude Code, Lovable, Cursor, whatever builds your code.
idiom verify re-renders the same states after the fix and proves the finding is gone. No model — the exit code is the verdict. Wire it into CI.
Every decision is logged forever. idiom context hands the accumulated judgment to the next agent before it writes a line of UI.
| Command | What it does |
|---|---|
| The doorway — zero setup | |
| idiom quick <url…> | Review any running page (localhost works): desktop + mobile, light + dark, all measurable checks, an HTML report — and an honest list of what it couldn't reach without setup. Two minutes, no config. |
| Setting up | |
| idiom init | Scaffold PRODUCT.md, DESIGN.md, and .idiom/. Interactive form interviews you; can also wire itself into an autobuild pipeline. --yes for scripts. |
| idiom validate [flow] | Check the config and flow files are well-formed before anything runs. |
| idiom reference add | Pin images or URLs of designs you're aiming for — or, with --anti, ones to avoid. The review holds your app against them. |
| The loop | |
| idiom capture <flow> | Drive the real app — a web page or an Electron desktop window — through every declared state and store screenshots, DOM, console, and accessibility data, tied to the commit. |
| idiom review <flow> | Judge a capture: deterministic checks + model critique against your design law, references, and past decisions. |
| idiom report [run] | Open the self-contained HTML report — printable, sendable, states its own coverage and limits. |
| idiom decide | Accept or reject findings, with reasons. Recorded permanently; rule-scope rejections suppress the pattern forever. |
| idiom ruling | Answer the design questions a review raised ("you style inputs three ways — which is law?"). Your answer is appended to DESIGN.md. |
| idiom instruction | Render one accepted finding as plain paste-ready text for any coding tool or chat. |
| idiom tickets | Emit accepted findings as bounded repair tickets into your tracker's triage. |
| idiom verify <flow> | After the fix merges: re-render, compare before/after, exit 0 only if the finding is provably gone. Model-free, CI-safe. |
| Improving — when the law doesn't exist yet | |
| idiom explore <flow> | Give one state and one sentence of dissatisfaction; get three real rendered directions of your own app to choose between. Choosing writes a rule into your design law — the rule, not a patch, is the product. Repair tickets offered, declinable. |
| idiom explore resolve | Record your choice (or an explicit no-choice) against a completed exploration run later — the run survives even if the process, terminal, or session didn't. |
| Memory, made visible | |
| idiom system | Open your design system as a visual page: token palette as swatches, the colors and type that actually shipped, your rules, your rulings, your standing rejections with evidence, and what's covered. |
| idiom context [flow] | Print the accumulated design brief — law, rulings, prohibitions, tokens, open work — sized to paste into any agent before it writes UI. |