Parent: structure
Twelve gates, one doctrine: every visual primitive has exactly one definition, and a build-time guard makes the second one impossible. This is where the product's visual coherence actually comes from — not from a style guide, and not from review.
Each gate was written after the same discovery, and the discovery is always the same shape: this was not a few places that missed the change — this layer did not exist, so every surface decided for itself.
| Gate | The rule | What was found |
|---|---|---|
check-one-select | one dropdown, in SelectField | 19 <select> in five mutually-unaware styles — boxed, small-boxed, underlined, sm-field-input, and the gate's near-black solid (the heaviest colour block on its page) |
check-one-text-input | one look, sourced from .sm-field-input | the same control wore two faces: connector credentials / op args / SEO were full-framed; the code-create modal, résumé composer, gate and AI-provider panel were underlined. The owner changed standard every other screen |
check-one-time-format | three formats, all in lib/ui/format-time.ts | three formats in one session — 8/8/2026, 10:16:07 AM (US locale, seconds, AM/PM), 2026-08-07T01:09:14Z (ISO+Z, written for machines), and last refresh · now on the same page |
check-one-scrim | one modal scrim | four *-overlay rules each carrying a literal color-mix(…). Four literals that do not know about each other: tune one, the other three silently fork — and a forked scrim does not error, it just makes some modals hold the layer below and others not |
check-one-layer-scale | z-order declared in one place | who is above whom was unreadable: 19 layer values across two languages — nine CSS magic numbers, ten Tailwind utilities — none declaring the order they meant. "Modal scrim" alone had three different z values |
check-one-empty-state | admin list empty states come from ListPane | every section wrote list.length === 0 ? <Empty/> : <List/> — a sentence with two outcomes, in a world with three: a failed fetch also yields an empty array, so failure wore the empty state's clothes |
check-one-section-heading | one section heading, from AdminSectionHead | — |
check-one-corpus-href | a corpus entry's public address has one source | 15 sites disagreeing; the genre name was used as the route name, and a writing entry's citation 404'd in production (corpus) |
check-sm-class-defined | every sm-* written in TSX must exist in CSS | a class name that is merely plausible renders nothing and reports nothing |
check-no-computed-class | no interpolation inside a Tailwind arbitrary value | w-[${n}px] generates zero CSS and nobody errors. Four places had names claiming to express a quantity while being constants |
check-no-native-file-input | the file-picker button is drawn by this product | <input type="file"> draws its own Choose File / No file chosen, styled by the operating system — nothing to do with cream paper, vermillion and mono. In the connector modal it was the one undesigned control, sitting next to designed ones |
check-peek-signals-more | a preview card that will be clipped must signal continuation at the cut | the summarize report card is a deliberate sneak-peek (inner iframe pinned at 280px), but the cut carried no signal: prose stopped mid-sentence against the card border and read as broken rather than more |
Why gates and not a style guide
A style guide is advice; it is consulted by whoever remembers it exists. Every entry above was written after the divergence had already shipped, and in most cases the divergence was invisible in review — five dropdown styles look fine one file at a time. The property that matters is not "we agreed on a look" but there is nowhere for a second look to live.
Note also what these gates are not: they do not judge whether a design is good. They enforce that a decision, once made, has a single home (mechanical-guardrails, and the same move as the backend's convergence-inbound-and-outbound). Taste stays a human question; multiplicity stops being one.
The cost, stated honestly
A gate at the wrong granularity removes working behaviour: fixing "an action is offered that cannot happen" with a rule coarser than the action produced "the action that could happen was removed too" — and CI stayed green throughout, because the gate was satisfied. So the question to ask of each new gate is not only what does this forbid but what does this forbid that I still want.