The Visual System

What Verbatim looks like and the rules that hold it together: the palette and where its values live, the type, the shape and layout rules, the motion rules, and the accessibility floor. Everything here is true of the stylesheets as they stand. Where a figure is not known, it says so.

The reasoning behind each choice lives in docs/.ai/decisions.html — the web font in ADR-92, the palette in ADR-93, where a gradient may go in ADR-94. Deployment moved to the TDD, which owns the container shape and the nginx path list.

The one rule

Where the values live

Colour

One hue for anything a person can act on, one for escalation and refusal, and no third — --accent and --alarm. The greys are --accent desaturated, so the page reads as one family rather than a neutral with a colour dropped on it. Meaning never rests on colour alone: draft, final, material and withheld are carried by label, weight and shape first, so they survive colour blindness and a monochrome screenshot.

The schemes

Light is the base :root. It is overridden by @media (prefers-color-scheme: dark), and by prefers-contrast: more paired with each of light and dark. The high-contrast pair moves the inks and the rules and nothing else.

--paper is the record: the diff, the claim cards, the source extract and every table of record sit on it. --surface-sunk is the withheld ground, and it is deliberately not paper, because a withheld claim is not a record of anything.

The ground under the shell

A frosted pane over one flat colour is a flat pane. Blur only reads as glass when there is something varied behind it, and probing /proceedings in Chromium at dpr 2 returned the same value at every point probed across the frame — both gutters, mid-column, and 1200px down. Probed, not exhaustively sampled. The claim is that no probe found any variation, which is weaker than saying there was none, and it is what was actually done; verbatim.css hedges its own comment the same way and this page keeps the hedge. The filter was running correctly on a page that gave it no work. So the page floor takes structure from the subject rather than from a hero gradient: a sheet of ruled filing paper on a desk. --ground is layered — the desk stepping down outside the 76rem shell, a writing rule every 32px, a docket column every 96px — and only its colours flip between schemes; the geometry is written once. It is switched off entirely under @media print, under prefers-contrast: more and under prefers-reduced-transparency: reduce, and a test asserts each.

The glass ladder

Solid first, unconditionally. Every pane declares background: var(--glass-solid) outside its @supports block and the translucent value only inside it. Written the other way round — declare the alpha and hope — a browser without the filter renders the raw translucent value over whatever is behind it, which is the grey-text-on-a-grey-rectangle failure this design may not have.

/* Solid for everyone, first and unconditionally. */
.masthead { background: var(--glass-solid); box-shadow: var(--edge), var(--glass-lift); }

/* Glass only where the filter exists. A browser that ignores this block
   never sees the translucent value at all. */
@supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
  .masthead {
    background: var(--glass-1);
    -webkit-backdrop-filter: var(--blur-1);
    backdrop-filter: var(--blur-1);
  }
}

--glass-solid is not decoration: it is what a reader without backdrop-filter, and every reader who asked for reduced transparency, actually sees. It must stay --glass-1 composited over --bg, and tests/test_glass_contrast.py::test_the_flat_pane_token_matches_the_translucent_one_it_stands_in_for holds it there to one value per channel. That literal has gone stale against its source before. prefers-contrast: more takes a different route again: it drops the filter and paints the panes on opaque --surface instead.

Type

Each face stands for a different kind of truth. A reader must never mistake a quotation for the product's own words, so the registers never share a face.

Display only is the point of the font decision. Interface text keeps the system stack, because the dense screens were measured against those metrics and because swapping body text is what makes a page lurch on load. ADR-12 said no web font, as part of no build step and no CDN; the build step and the CDN still hold and only the font moved.

Twelve pixels is the floor, not a preference. --t-micro is the most-used size in the application, it is nearly always uppercase and tracked, and tracked uppercase at eleven pixels is where a reader stops reading and starts guessing. The analyst this is built for is often past forty and often on a laptop in somebody else's meeting room.

Tracking and leading, and the rules behind them. Tracking slackens as the type grows: --track-display −0.02em at 48px, --track-title −0.014em at 32px, --track-h1 −0.009em at 24px. One value across them would either loosen the hero or close up the page title. Uppercase labels take --track-label 0.09em, and --track-label-tight 0.04em where the same label sits in a narrow grid track. Leading runs the other way: --lh-micro is 1.55, more than --lh-ui's 1.5, because letter-spacing pushes glyphs apart across the line and tight leading then crowds the lines into each other until the label reads as a grey block. --lh-doc is 1.72 and --measure is 66ch, because document prose gets read closely rather than scanned.

A weight floor on glass, and a size floor with it. A blurred backdrop lowers apparent contrast even where the measured figure holds, because the eye reads edges and a blur softens them. Nothing on a pane goes below weight 500, and no text on glass goes below --t-small — which is the rule that rules out the thing that would actually break it, body prose on a pane. Do not reach for -webkit-font-smoothing: antialiased to compensate: on a Mac it thins the strokes, which is the opposite of what is wanted.

Shape and layout

Chrome is soft, evidence is square. The radii split in two, and the split is the design rather than a preference: a filing with rounded corners is a card about a filing.

The shell and the grid. --shell is 76rem, the width everything lines up inside. Space is a 4px grid, --s1 through --s8. Document prose is bounded by --measure, 66ch, wherever it appears.

Sticky chrome, and the heights it is measured against

The masthead sticks from 48rem up. Below that it does not, and that is deliberate: the nav wraps to two rows at 640px and three below 480px, so a sticky bar would take a quarter of a phone screen permanently. The tab rail sticks at every width, including phones, because it is 46px and it is the only thing telling a reader where they are on a page thousands of pixels long.

--stuck is the masthead's own height and it is not one number. Nothing here runs on scroll, so the bar does not collapse; what changes with width is how many rows the nav wraps to. Measured in Chromium stepping 4px from 760 to 1460, across the screens and every demonstration account, taking the worst case — the administrator gets an extra nav item, so the nav wraps at a different width for each account and a table measured on one is short for another:

  768 to 855     233px   nav on three rows   --stuck: 14.5625rem  (@media min-width: 48rem)
  856 to 1171    164px   nav on two rows     --stuck: 10.25rem    (@media min-width: 53.5rem)
  1172 and up    110px   nav on one row      --stuck: 7rem        (@media min-width: 73.25rem)

  --rail-h: 2.875rem                         the tab rail, measured at 46px
  --anchor: calc(var(--stuck) + var(--rail-h) + var(--s4))
  --focus-anchor: var(--anchor)

--anchor is what every scroll target uses, and it clears the rail as well as the masthead, because the rail sticks underneath it. --focus-anchor is the same clearance for focus rather than for anchors — WCAG 2.2 added 2.4.11, Focus Not Obscured, and this layout was failing it: every rule that carried --anchor was on something a fragment link points at, none on the controls a person tabs through. It is a separate token because a scroll container must lower it for its own descendants; ten rem of clearance inside a panel twenty rem tall would solve 2.4.11 on the page and break it in the panel.

Tables scroll themselves. Below 62rem a table becomes its own scrolling box — display: block, width: max-content, min-width: 100% — so a table wider than the viewport does not push the whole page sideways. Fixed in the stylesheet rather than by wrapping every table in every template, so a table added tomorrow is covered without anybody remembering. The 62rem bound is a known hole and the stylesheet says so: a table is too wide when it is wider than the space it has, which is a fact about the table and not about the screen. The registers on /admin/sources and /admin/invites push a 1280px laptop sideways — measured in a browser, scrollWidth 1368 and 1377 against a clientWidth of 1280 — while sitting perfectly inside a 390px handset, where the rule fires. Until that is settled, a table known to be wide wears .table-scroll by hand.

Motion

The settle: one orchestrated moment, and the record is not in it

Bands on page load, 420ms end to end, and it never repeats. Nothing else in the product is choreographed.

Every band takes --ease-settle. Claims, quotes, source extracts, tables and the diff are in band nothing. They paint at full opacity in the first frame. The frame assembles around a document that was already there, which is the sequence saying what the product says: the filing is not something this software produced and it should not appear to arrive.

Band 3 selects the frame and not the containers, and that is load-bearing rather than tidy. Selecting a parent would composite its opacity onto every claim inside it, including a withheld one, and the signature would be gone with no line in the diff mentioning it.

The rest of it

Arrivals animate. Departures do not. The dock and the source panel are toggled with the hidden attribute, which the stylesheet forces to display: none !important. A transition cannot run out of display: none, but an animation restarts every time an element becomes displayed — so both reveals are animations and neither needs a line of JavaScript. Closing is instant: a person closing a panel has already decided.

What has no motion

• The withheld surface. Specified below.
• Every number. No count-up, ever. These counts are findings withheld and items waiting on a person; a number that animates from zero displays a false value for the length of the animation, which in a compliance tool is a wrong reading on screen rather than a flourish.
• Anything triggered by scroll. No reveal-on-scroll, no parallax. A reader scrolling back up a diff must find it exactly as they left it.
• The type scale. Nothing resizes at any time. Type that shrinks as you scroll reflows text while a person is reading it.
• The ground and the panes. Nothing in either drifts, breathes or parallaxes, and a test asserts that no movement is declared in a backdrop token.

Reduced motion removes motion. It does not shorten it.

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation: none !important;
    transition: none !important;
    scroll-behavior: auto !important;
  }
}

Shortening every duration to a hundredth of a millisecond leaves every animation and transition running: the events still fire, the compositor still works, and an element mid-animation at a repaint can still flash. With animation: none the fill mode goes too, so every band renders at its natural state, which is exactly the intended end state.

The withheld surface

The refusal takes more than one form and they are one thing, so the block names each: .claim--withheld on a change page and on a shared claim, .queue__row in the escalation queue, and .withheld — the hatched slot — wherever it appears, including inside an assistant reply and inside a blocked plan step. .withheld__label and .withheld__reason are named separately because admin templates use the reason with no .withheld parent, and a refusal has to look the same on an admin screen as on a change page. The block sits after every rule in verbatim.css that adds an effect, so at equal specificity it wins against all of them on order.

The differences that carry the refusal, and none of them is colour. A broken left rule where a verified claim has a solid one; inset from the column so it does not sit on the assertion axis; sunk instead of raised; the statement position occupied by a 135° hatched slot naming the reason; no citation chip; and a quoted-against-source pair a verified claim never carries. It survives a monochrome screenshot and needs no legend.

On paper, all but one of them are read rather than measured. The print block sets print-color-adjust: exact on .claim--withheld, .queue__row and .withheld, so a printer is not free to drop the hatch or the rule, and every one of those differences is structural rather than colour. Nothing in the suite renders a printed page — the only print assertions are token-level, that --ground is none under @media print. The one with a test behind it is the missing statement: it is not in the markup at all, and tests/test_change_view.py::test_a_withheld_claims_statement_never_appears_in_the_response_body holds the response body to that. Print renders the same markup, so that one carries over. The rest are styled and have been read, not measured.

The rule that keeps it the signature, and nothing enforces it. The withheld surface must be the stillest thing on any screen it appears on. If a second element ever competes, the second element gets motion, or it is cut.

The accessibility floor

The ratios, pinned

Every ratio verbatim.css states in prose is pinned to two decimals in tests/test_glass_contrast.py, so moving a colour without revisiting the comment that describes it fails there rather than in front of a reviewer. scripts/contrast_report.py regenerates the literal from the stylesheet. Every ratio cell below carries the scheme, the ink and the ground it came from, and tests/test_design_guards.py recomputes it out of verbatim.css to 0.01. A second guard fails if the table stops covering the whole PINNED list, so a row cannot go missing quietly either.

The two concessions, and why they are kept. Light --ink-3 is under 4.5:1 on --bg and on --surface-sunk. It is the second level of a deliberate two-level ink hierarchy, and the worst case for it is .nav__link--off: a nav item that leads nowhere is a <span aria-disabled>, not a link, and being drawn in --ink-3 while its neighbours are --ink-2 is the only thing on screen saying so. Raising it would make an unreachable screen look exactly like a reachable one, and a nav item that leads nowhere while looking live is a small lie this product's argument says it does not tell.

Tests hold the shape of that trade rather than leaving it to a comment. All but one are here; the weak one is below. --ink-3 may never equal --ink-2, in every scheme, with at least 1.3:1 between them — it shipped equal once, in the prefers-contrast block, which flattened a two-level hierarchy across the stylesheets for the one reader who asked to see more. And asking for more contrast must actually get more: high-contrast --ink-3 beats base --ink-3 on every ground, and in high-contrast light it clears 4.5:1 on every opaque ground. That is what the query is for; a reader who asks for more contrast and is handed something still under the floor has been gestured at, not answered.

Focus

The focus ring is an outline, in every scheme, on every surface, glass included, and it is declared once. The halo beside it is a box-shadow, which makes it an enhancement: the withheld surface drops it and keeps the ring.

• Never write outline: none outside :focus:not(:focus-visible), which is the browser's own judgement that a pointer put the focus there. tests/test_a11y_guards.py walks every stylesheet under app/web/static/ and fails on anything else.
• A sheet that carries its own controls draws its own ring, and a sheet that animates answers prefers-reduced-motion itself rather than leaning on the global sweep. Both are asserted per sheet. The tour is the first thing a new reader meets and it had no ring.
• Keep the ink-coloured ring on filled controls. An accent ring on an accent fill disappears, so the primary button, the citation chip and the skip link switch outline-color. Any new filled control joins that list.
• Anything rendering outside .shell, out on the darkened desk, needs an opaque fill or it belongs inside the shell. The skip link is the one element that does, and a test holds its background opaque.

What is not known, and what ships broken

1. The refusal animation is dead. Two rules in verbatim.css contradict each other on .claim--withheld and the !important one wins. Detailed above. It is not the only defect here that changes what a reader sees — the wordmark below is another.
2. Nothing here has been opened on a handset. Every 390px figure comes from a headless Chromium at a fixed viewport. A phone has a real backdrop-filter cost, a real address bar that resizes the viewport, and a real thumb. verbatim.css says the same at the foot of its table rules, and tests/test_responsive.py says plainly in its docstring that it cannot lay out a page.
3. The rendered contrast on a translucent pane over the indigo page is unknown. The pinned figures are token arithmetic and the pane figures that existed were measured against the palette this product no longer uses.
4. Nobody has tabbed the whole product with the current palette. The source guards above stop a ring being deleted; nothing asserts a ring is visible on G1, G2 or G3, in either scheme.
5. The 62rem bound on the table scroll rule is a hole, not a decision, and is named as one in the stylesheet rather than left looking deliberate.
6. Whether dark glass earns its compositor pass is unknown. --glass-solid at #161d31 over a #0b1020 page is a real step, but a 20px blur of a dark, mostly empty page returns something close to a flat tint. If it reads as a plain panel on a real dark screen, the honest move is to drop backdrop-filter in dark, keep the tint, the edge and the shadow, and save the pass. Nobody has looked at it on an actual display in dark.
7. The brand ships in more than one form, and a reader sees it. The lockup nearly everywhere, the old text-and-bars form in login.html, and a micro-label in invite_accept.html, which is the first Verbatim screen an invited colleague meets. Detailed under Type.
8. The withheld block is not last in verbatim.css and its comment says it is. Nothing asserts the position.
9. --r-glass is declared and read by nothing. One line, no consumer.
10. workflow.css obeys the no-colour rule and no test enforces it, unlike clerk.css and tour.css.
11. Most of this document is still unguarded. Tests read the mirror numbers and every ratio it prints, and re-derive both from the tree. Nothing else here is checked: the alphas, the blurs, the type scale, the sticky heights and the browser figures were read back by hand, and a stylesheet edit tomorrow can make any of them false with the suite green. This round dropped every count whose sentence survived without it, so less is left to rot. Not nothing.
12. No user has seen this palette, or the one before it. The argument for indigo is reasoned from the category rather than from evidence, and docs/user-research.html still records zero interviews. That is the weakest claim on this page and it is not a small one: every rule above is a designer's judgement that nobody in the intended job has been asked about.