The visual grammar: what each mark rests on

A chart and a table both assert things, and neither usually says which of its marks the data forced and which the renderer, the solver or the tolerance chose. A fitted curve drawn solid looks exactly like a proved bound drawn solid. This grammar gives every mark one of four standings, and each standing one stroke:

• DECIDED — solid; in text, plain. An exact decision backs it: an interval enclosure, an exact rational comparison, a proof.
• COMPUTED — dashed, 5 4; in text, a dashed underline. Floating-point arithmetic, a solver stopped at a tolerance, a fit, a forecast, or a number someone printed: it may well be right, and nothing decided it.
• CHOSEN — dotted, 1 5 with round caps; in text, a dotted underline. One member of a set the data admit, picked by something that is not the data: a tie-break, a default, a seed, a prior, an interpolation.
• REFUSED — no mark at all. The instrument declined, or the input is missing; the void is drawn, hatched, and in text it reads refused. It is never interpolated across, never averaged, never a zero.

A mark takes the weakest standing on its path to the pixel: a knot computed exactly is solid, and the line drawn between two such knots is dotted, because a straight line is one curve of many through them. Standing is not a verdict. CERTIFIED, REFUTED and REFUSED are what an instrument concluded about a claim; they are said in words and chips, never in a stroke, and a refutation proved here is drawn solid. Nor is standing a confidence: a value known to many decimals can still be undecided, and a decided value can have a wide bracket, which is drawn as its own extent.

Every mark below is drawn by playground/warrant.js as this page is built, on one curve: y = √x for x from −1 to 4. The exact parts are decided by this page’s builder in integer arithmetic; the float parts are Math.sqrt. If the module changes, these drawings change with it.

A premise chain, with its ladder

A number that rests on a model names what it rests on, in the order the number travelled, each premise with its grade: validated · compared · verified · assumed (the ladder is explained below). This is the chain behind a wave limit at a beach on Swell, built here from the records Swell reads:

The rulebook is design/WARRANT.md (v2, frozen 28 October 2026, with dated rulings since). Each rule below was found on a page here that broke it. Each names the page, what was wrong, and the change that fixed it; the fix is checked by that page’s own build, which refuses when its record stops supporting its sentence.

Marks

• 1. Standing is not a verdict. What an instrument concluded about a claim — CERTIFIED, REFUTED, REFUSED — is said in words and chips; what a mark rests on is said by its stroke or its underline. The two never share a channel, so a refutation proved here is drawn solid.Found on neural-geometry: a frame verdict that failed was shown by striking its fitted number through, a line through a computed value carrying a verdict. The verdict is a word now, and the number keeps its dashed underline. fixed 28 October · 17eb3d7c
• 2. A pick must be a member of the set it was picked from, and the build checks that it is. When a figure draws one member of a set the data admit, it must really be a member, and the page’s build verifies the membership exactly.Found on census: the totals it drew (Table I’s least-squares repair) moved two edges outside the ±½ a rounded integer allows, while the page said they were inside. The repair is now a fit held inside the box, with its optimality (KKT) conditions checked exactly. fixed 28 October · 824b1261Found on occultation: the curve joining the measured chords is not concave, so no convex body has it: it was never a member of the set of silhouettes the chords admit. It is drawn dotted, as a chosen picture, and says so. fixed 28 October · 824b1261Found on navier-stokes: the drawn core was not incompressible: the field it replaced read |div u| about 1.2 times its larger term. The field is now solved from continuity in closed form, and the build refuses the page unless |div u| stays below 10⁻⁶ of it over the drawn range. fixed 28 October · 3a072548
• 3. A tie is chosen. When the optimum is not unique, the one drawn was picked by a tie-break: it is drawn dotted and said to be one of several.Found on neural-geometry: nine of the fifteen minimum spanning trees it draws tie (two edges of one length), so a tie-break picked them; they are dotted and named one of several. Recounted here from its record, by the same exact test. fixed 28 October · 17eb3d7c
• 4. Dash is for standing only. Which series or which model a line belongs to is carried by weight and opacity, never by a dash, in every figure on the site: a licence that held in one figure and not the next could not be read off the mark.Found on answer-shape: its three models were told apart by dash patterns (6 4 and 1.6 3.4 among them); the first dash census found them, and the page already carried the weight-and-opacity ladder underneath. fixed 5 September · 36b10f33Found on answer-shape: its closing edge and the model chips still used a dash for a role; they use opacity now. fixed 28 October · 17eb3d7c
• 5. The one accent. The witness red marks an exhibited counterexample, a specific object that broke a claim someone made about that object’s own record, always as a × beside words (the one in the meet specimen above). It never marks a verdict word or a region, a scalar comparison (a box that clears a box has no witness point), a refutation reached by deduction, or an object taken from another record. When in doubt, ink.Found on the return-level check: its list of × marks became one module, and “not the certified fit” came off it, because a box clearing a box has no witness point; on the atlas, the design table’s rows stay ink, because their objects belong to another record than the claim’s. fixed 28 October · 824b1261
• 6. Mood. A verdict that holds given a chosen input names that input in italic — given h = 3/50 — and a hypothesis that was read but not machine-checked is named the same way.Found on navier-stokes: its verdicts now name, in italic, the drawn stress and the theorems they cite. fixed 28 October · 3a072548Found on stereo-reach: the verdict now names its chosen inputs in italic. fixed 28 October · 824b1261Found on the return-level atlas: each claim’s box is a reading of the paper’s words, so it is drawn dotted, with the readings one 4° cell in or out beside it, and every claim is decided again on each. Of its ten claims, one turns on the reading: the claim for south of South America (40–58° S, 80–56° W) does not hold for the box as drawn, and holds with the north edge moved 4° south, or the east edge moved 4° west. The page says that verdict is a reading. fixed 27 October · 16a2f42e
• 7. An empty set is ∅. It gets ∅ and a word, never a zero-height bar or a zero.Found on occultation: at face value (no error at all) the set of convex silhouettes the chords admit is empty; its row now prints ∅ and the words instead of a bar. fixed 28 October · 824b1261
• 8. Read the site’s own prose against the record. Every number typed on a page comes from a record and is checked by that page’s build, so the build refuses when the record no longer supports the sentence. A headline with no record behind it is the failure this rule exists for. A printed bound is rounded outward, never truncated.Found on blind-spot: the headline read “Fourteen million certified verdicts could not see this mutant.” No record runs that corpus against the mutants; what the page rests on is a 4,000-pair sample of it, and the headline now counts the sample, read from the file. fixed 28 October · 4ad79bd3Found on contours: two expected counts were printed by cutting digits: 18262/36525 as 0.4999, where rounding gives 0.5000 (both computed here, exactly). They are rounded from the exact values now. fixed 28 October · 3a072548
• 9. A legend wherever a mark is. Every page that uses a stroke or an underline of the grammar prints its legend, compact beside a figure; tools/check-wiring.js refuses a page that has the marks without it.Found on shape-hunt: its marks were committed without a legend, and the build refused at that check until the legend was added. fixed 28 October · 824b1261
• 10. A page copied in is never edited. A page copied byte for byte from another source changes only through its wrapper, by anchored replacements that each refuse unless their anchor occurs exactly once, or through a patch declared beside the copy.Found on affect: its page script is a copy and stays untouched; every change on the page is a named passage the wrapper replaces, each refusing unless its anchor occurs exactly once. fixed 28 October · 4fbb5ad3

Two rulings of 28 October

• A layout placed by a float solver is a chosen picture. An embedding or an eigenvector map says so once, in its caption; each mark on it keeps the standing of what it asserts, so an edge that exists is solid.Found on neural-geometry: its map’s coordinates come from an eigendecomposition; the ring around the controls is dotted as a chosen picture, and the map’s sentence was corrected (one structured set sits inside the ring the page said the controls held alone). fixed 28 October · 17eb3d7c
• A model’s answer is a claim someone made. It is computed, dashed, like a number someone printed. The typed graph behind the wiring instruments already drew it so: the node holding a model’s answer emits a float, and its wire is dashed.

Numbers that rest on a model

• 11. A number that rests on a model names its premises. In the order the number travelled through them, each with its grade and the record behind it, ending with a line that names the weakest — beside the certificate, and on the method page.Found on Swell: every wave limit is decided exactly over a measured band, and the band reaches each beach through an island model whose own error at the shore has never been measured: true, and misleading read alone. Every beach card now says what its number rests on (the chain above). fixed 28 October · 4a1d50b8
• 12. A grade comes from a record, and a comparison is calibrated first. The build re-derives the comparison; before it is trusted, it must reproduce the published comparison it stands in for.Found on Swell: its island model against a Boussinesq model first reproduced the published comparison, with the same probes and tables. On the current tables its record reads N 556, r 0.44, bias +0.27 m, re-derived by the app’s battery. fixed 28 October · 4a1d50b8
• 13. The halo. An extent carried to a place by a model that is not validated there keeps its crisp edges, because the decision is made on them given the model, and gains a halo outside them. A validated extent has no halo (the key above).Found on Janela: a band borrowed from the nearest measured site, and the wind band, validated nowhere, gained the halo. fixed 28 October · bea04b72
• 14. A forecast line is computed and dashed, on canvas too. A canvas takes the same patterns: setLineDash is given G.claim(width) from design/grammar.js.Found on Swell: its forecast lines were drawn solid until 28 October; every one (waves, wind, gusts, tide, the open sea) is dashed now. fixed 28 October · 4a1d50b8
• 15. A field drawn from a model is a picture of the model. For crests or streamlines, the legend says so once.Found on Swell: its legend says the crests are a picture of the island model, not a measurement. fixed 28 October · 4a1d50b8
• 16. Where the model reads low, “under the limit” is flagged. Where a comparison says the model reads low at a place, any “under the limit” there is flagged as calling for more caution than the arithmetic shows: a flag, not a refusal, because a refusal would remove an exact statement.Found on Swell: Pântano do Sul (0.39×), Ingleses (0.43×) and Galheta (0.99×) read below the Boussinesq model on swells of 11 s and longer (the median ratio), and their cards say so. fixed 28 October · 4a1d50b8

Ink comes first: a figure must read completely in greyscale, and a colour always arrives with a shape and a word. The law came from a measurement: run through the validator, the palette of Machinidae, a sibling project built on this grammar, showed its two main series colours ΔE 0.4 apart to a deuteranope. To that reader they were one colour.

• 1. Ink first. Every figure reads completely in greyscale; a colour always comes with a shape and a word.
• 2. One colour, one meaning, in every project built on the grammar. Each colour is registered, below, with its meaning and the date it was approved.
• 3. Colour never carries standing (the stroke does), and it never stands in for a verdict word.
• 4. Four kinds of colour only: the witness, one red, for a shown counterexample; identity, at most three hues for the series compared in one figure, each with its own shape; order, one hue in lightness steps, for an ordered scale; status, an app’s decided states, always with an icon and a word.
• 5. Every pair passes the validator. Every set of colours that shares a figure is compared pair by pair, on the figure’s own ground, in OKLab (ΔE × 100) under the colour-vision model of Machado, Oliveira and Fernandes (2009): ΔE ≥ 8 for each simulated colour-vision deficiency and ≥ 15 for normal vision, every pair and not only neighbours in a list.
• 6. No yellow and no orange.
• 7. A new colour enters only with the validator’s report and an approval, recorded in the rulebook.

The registered colours

Read from the rulebook when this page is built. No swatches: the only colour this page draws is the witness ×.

• --witness #e0574e · witness — a shown counterexample; the only red on the site and in Machinidae (rose retired). Where: every project. Approved: 2026-10-27, as the only red 2026-10-28.
• #79b9d6 · identity — lineage (the arm, and the accent: not in the founder; filled = new, ringed = changed). Where: Machinidae. Approved: 2026-10-28.
• #6744c5 · identity — the rules arm (re-stepped from #9070c8; ΔE 28 against the blue for a deuteranope). Where: Machinidae. Approved: 2026-10-28.
• #9fd0bb · #5f9a83 · #335e4e · order — how far a birth got: lived · died · stillborn. Where: Machinidae. Approved: 2026-10-28.
• --v-cert · --v-refu · --v-refd · status — an app's decided state: allowed · refused by the rule · undetermined; --v-refu IS --witness since 2026-10-29. Where: the apps (design/app-shell.js). Approved: 2026-10-28; the red folded 2026-10-29.
• #3368c1 (print) · identity — the second series compared in a print figure, always with ■. Where: print only (design/print/tokens.js, kits/warrant-mpl). Approved: 2026-10-29.

One red

The witness red, #e0574e (the × in the meet specimen above), marks an exhibited counterexample and nothing else. Until 29 October the apps carried a second red for a refused state, ΔE about 4 from the witness: one red to the eye with two meanings, against law 2. It is folded now. The apps’ refused state reads the witness token, with the witness’s meaning: a decided state shown together with the datum that breaks the rule, always with its icon and its word.

Standing says how a number was computed. A number that rests on a physical model needs a second answer that standing cannot give: the arithmetic can be exact while the equations it was exact about have never met the thing they describe. So each premise carries a grade, which says where the checking of it stopped. Strongest first:

• validated — checked against observations of the thing itself, held out, with the number. In the literature: validation. On Swell: the open sea’s band, against satellite passes it had not seen.
• compared — checked against a model that keeps more of the physics, with the number; not against the thing itself. In the literature: code-to-code comparison. On Swell: the island model, against a Boussinesq model at twelve beaches.
• verified — the code reproduces an exact solution of its own equations; not measured against the thing itself. In the literature: code verification. On Swell: none yet.
• assumed — adopted from a source, chosen, or read; no machine here checked it. In the literature: an adopted assumption. On Swell: breaking at 0.55 times the depth (Thornton & Guza, 1982), and no sandbars.

The ladder is the verification-and-validation ladder of the modelling literature — Roache (1998), Oberkampf and Roy (2010), the ASME V&V 20 standard (2009) — cut to four grades a reader can tell apart. A conclusion is as checked as its weakest premise (W.weakest), and the page that states it names that premise. A grade is never a probability and never a confidence. It is carried by a word first and a three-step glyph second, never by colour.

A read step (ruled 29 October). A proof step that was read and not run by a machine gets no grade of its own: it is assumed, and the gloss says so. It does not cap a verdict. CERTIFIED, PARTIAL, REFUTED and REFUSED keep the meaning their certificate gives them; every read step is listed, graded assumed, in the page’s “what it rests on”, and the chain’s last line names it. A reader always sees where the machine stopped; the verdict word never hides a reading, and a reading never demotes a decision it does not touch. δ₃ = 117/2192 is an example: a decided finite core, and three steps proved on paper and read, listed as assumed.

Where a model carries an extent, the same idea is drawn as the halo (rule 13, the key above): blur is the sign of uncertainty readers understand most readily (MacEachren et al. 2012).

A grammar that no build checks is a suggestion. Four programs read every built page and refuse the site when a page breaks the grammar or its layout gets worse. Each carries red controls, planted violations it must catch, so a check that cannot fail is caught too. The numbers below are read from their output and their records as this page is built.

• tools/check-grammar.js — the dash census. Only the five patterns of design/grammar.js may appear in a built page; three uses of a dash array that are not lines (an arc length, a moving dot, a draw-on animation) are declared by name, each with its reason. The first census, on 5 September, counted twenty-five patterns: the dash had been derived from the stroke width, so every width minted a pattern of its own, one of them carrying a float artefact (1.04 5.460000000000001) into published HTML. At the last sync, 639 conforming uses and 0 outside the five:
  • 5 4 computed, the line pattern — 249 uses
  • 1.5 2 computed, under 1.5 px of stroke — 51 uses
  • 1 5 chosen, round caps — 91 uses
  • 1 3 chosen, under 1.5 px — 53 uses
  • 2 3 a guide: an axis, a ruler, a ghost; it says nothing — 84 uses
• tools/check-wiring.js — a legend wherever a mark is. A page with a mark of the grammar and no legend is refused. At the last check, 52 of the 127 pages it walks draw the grammar, and every one prints its legend. Its red control plants a computed line with no legend, and must catch it.
• tools/check-render.js — what a page shows. No text a builder leaked (a template that never filled, a cell reading undefined or NaN, a stray backtick); no mark whose paint does not resolve; no figure thinner in ink than its record (100 figures recorded); no new mark too faint to see; no script error while the page loads. Its paint check was made strict when the legend’s void swatch fell through to SVG’s default fill, black on a near-black ground, and had passed every run, because black is a paint.
• tools/check-measure.js — the layout ruler. Every built page driven in Chrome at 1440, 768, 390 px; the number of left edges, sideways overflow, blocks escaping the screen and clipped elements may only go down (137 pages recorded).

This page is held to the same standard by its own builder, tools/build-grammar.js, which reads every number above from its record and refuses to build when one stops saying what the page says.

The module is one file, playground/warrant.js, MIT-licensed, with the five patterns in design/grammar.js beside it; it needs no library. In Node, with what each call returns as this page was built:

const W = require('./playground/warrant.js');

// a line: its standing picks the stroke
W.attrs(W.COMPUTED)
  → class="w-computed" fill="none" stroke-width="2" stroke-dasharray="5 4"
W.attrs(W.meet(W.DECIDED, W.CHOSEN), { width: 1 })
  → class="w-chosen" fill="none" stroke-width="1" stroke-dasharray="1 3" stroke-linecap="round"

// a number in text
W.value('3.1416', W.COMPUTED)
  → <span class="w-val w-computed" title="computed — float, or a number someone printed; nothing decided it">3.1416</span>

// the legend, compact beside a figure, and the stylesheet, once per page
W.legendHtml({ compact: true })
W.css()

// a chain of premises, in the order the number travelled through them
W.premisesHtml([
  { grade: W.VALIDATED, label: 'The open sea and its band', evidence: '...' },
  { grade: W.ASSUMED, label: 'Breaking', evidence: '...' },
], { meetLine: 'The weakest premise is assumed.' })

On a canvas, setLineDash takes the same patterns from grammar.js: G.dash.claim is [5, 4] and G.dash.pick is [1, 5]. The legend and the ladder in Portuguese — suposto, verificado, comparado, validado — are in playground/warrant-pt.js. The rules are in design/WARRANT.md.

A print version and a Python kit for matplotlib are in preparation.