Foundations

The rule sets every language, chart, and page builds on. Numbered, permanent, cited where perception research backs a law.

FN-01 . Token contract

The rule that makes the whole catalogue themeable and deterministic:

Chart and component specs reference color ROLES, never hex values. Design languages (DL files) bind roles to hex. Rebranding = swapping the DL token file. No spec changes, no re-authoring.

Required roles (every DL must bind all of these)

Optional roles a DL may add: panel, benchmark, warning, primaryDark, and others. Specs that want an optional role declare a fallback chain, for example "context": ["benchmark", "muted"]: first role present in the palette wins. The renderer resolves the chain, so a spec never breaks on a DL that lacks an optional role.

Rules

1. Hex values live in tokens/DL-xx.json only. A hex value inside a chart spec or component spec fails validation on sight.
2. All hex is #RRGGBB uppercase. Enforced by schema/dl.schema.json and tools/validate.py.
3. ink and body must reach 4.5:1 contrast on background (WCAG AA). Enforced by tools/validate.py.
4. Fonts follow the same contract: specs reference display or body, the DL binds each to a family stack whose last entries are installed-everywhere fallbacks.

FN-02 . Canvas and spacing grid

Canvases

All positions and sizes in specs are exact pixels on these canvases. Adjectives ("comfortable margin", "medium bar") are banned in specs; a value the renderer cannot consume is not a spec.

The 8px grid

Every structural distance is a multiple of 8: margins, offsets, bar heights, gaps, plot bounds.

Text sizes are exempt from the 8-multiple (they follow FN-03) but their anchor positions are not.

Fixed furniture on every chart canvas

• Title: x=32, baseline y=56 (y=88 when the DL chrome adds an eyebrow).
• Source line: x=32, baseline y=516, always present, always bottom-left.
• Kicker + eyebrow: only when the DL's chrome block asks for them; kicker 24x4 px at (32, 28), eyebrow 11 px caps at (32, 52).

FN-03 . Type scale

Sizes are fixed per text role on the 960x540 chart canvas. A DL changes the family and weight, never the size or position (those belong to the chart spec).

Rules

1. Two font slots only: display (titles) and body (everything else). A third slot (mono for IDs and timestamps) is reserved for DLs that declare it; no spec may require it.
2. Every DL family stack ends in an installed-everywhere fallback (Segoe UI, Arial, Georgia, Consolas). Silent substitution with a different metric font is the failure mode this prevents.
3. Nothing below 11 px on the 960x540 canvas. On the 1280x720 slide canvas the floor is 12 px.
4. Emphasis is weight (400 to 600), never a size bump, never underline.

FN-04 . Contrast and color use

Hard limits (validated, not advisory)

1. ink and body reach 4.5:1 on background (WCAG AA body text). tools/validate.py computes this from the DL token file and blocks on failure.
2. Meaning is never carried by color alone. Status, deltas, and exceptions always pair color with a word or a number.
3. One saturated highlight per chart. The primary role appears on the one mark the title talks about; everything else uses muted or benchmark.

Discipline

• Series count before color count: if a chart needs more than 4 colors, the chart is wrong (split into small multiples), not the palette.
• positive and negative mark deltas and status, never decorate.
• Charts must survive grayscale: the highlighted mark must still read as the highlight through weight, position, or label emphasis.

The banned list (applies to every DL, every chart)

• Purple/blue gradient backgrounds, "hero" gradient bands
• Rainbow categorical palettes (one hue per bar)
• Color-only status dots
• Anything below AA contrast, including gray-on-gray captions
• 3D depth, glassmorphism, heavy drop shadows

FN-05 . Numbers, units, and scales

Numbers

1. Tabular (monospaced-figure) rendering wherever numbers stack in columns; right-aligned in tables.
2. Units appear ONCE per chart, not per value: - bar charts: on the first (largest) value label ("34 items", then "28", "21", ...) - line charts: on the top y tick label ("80%", then "60", "40", ...)
3. Missing value = "-" (hyphen nil marker), never zero, never a guess.
4. Titles state the finding with a number. "Backlog overview" fails QA; "Electrical holds 34 of 109 open items" passes.

Scales (deterministic by construction)

Bars start at zero, always, no exceptions. Line charts start at zero by default; a non-zero baseline requires a written justification in the entry that uses it.

Tick generation is an algorithm, not taste, so two renders can never disagree:

raw  = max_value / target_ticks        (target_ticks = 5)
mag  = 10 ^ floor(log10(raw))
step = first of {1, 2, 5, 10} * mag that is >= raw
top  = ceil(max_value / step) * step
ticks = 0, step, 2*step, ... top

Direct-label bar charts skip the axis entirely and scale bars to the max value; the labels carry the numbers.

Float formatting in renders

All coordinates format as max-2-decimal, trailing zeros stripped, "-0" normalized to "0". This is what makes byte-identical re-renders possible across machines.

FN-06 . Perceptual foundations

Every OVP rule traces to a named finding in visual perception research, not to taste. This entry is the trace, one line per rule family. It is deliberately one page: OVP cites the science, it does not rewrite it.

Canon referenced: Bertin (Semiologie graphique), Cleveland & McGill (graphical perception experiments), Ware (Information Visualization), Munzner (Visualization Analysis and Design), Tufte (VDQI), Few (Show Me the Numbers), Treisman (preattentive processing), Cowan/Miller (working memory), Kahneman (attention and effort).

Rule for extending OVP: a new rule that cannot cite a row here, or add one, is a preference, and preferences do not enter the protocol.

<!-- Generated by tools/build_blocks.py from decision/voice.json. Do not hand-edit. -->

FN-07 . Voice and prose

Design languages control how a page looks. This contract controls how it reads. It bans the patterns that make machine-written prose identical everywhere, and each design language layers its own register on top.

A design language that controls the palette but leaves the words to chance ships half an identity. Every generated word now resolves the same way a color does: the universal laws below first, then the voice block of the design language in use.

The universal laws

Exemptions

• Material inside straight double quotes: a rule may name the phrase it bans, and legal or press registers may quote a source verbatim.
• The generic side of a contrast example: it exists to show the failure and MUST trip at least one law.

The closed lists

Machine-checkable, case-insensitive, substring match. Canonical source: decision/voice.json.

Banned phrases (33): it's worth noting, it is worth noting, worth noting that, delve, dive into, in today's, fast-paced, seamless, holistic, cutting-edge, game-changer, unlock the, elevate your, streamline, navigate the complexities, at the end of the day, when it comes to, plays a crucial role, not just, but rather, the landscape of, leveraging, leverage the, testament to, a myriad of, in conclusion, furthermore, moreover, interesting, notably, importantly, clearly, obviously.

Words that need a number in the same sentence (23): significant, major, substantial, considerable, dramatic, notable, remarkable, robust, various, several, properly, appropriately, as needed, efficiently, effectively, potential, potentially, carefully, stunning, exceptional, finest, world-class, passion.

Hollow constructions (14): is being made, are being made, progress is being, it was decided, there are several, there is a need, we believe, we would like to, we are pleased to, it might be, may need to, going forward, a good idea, in order to.

Per-language voice

Each design language carries a voice block in its token file: stance, register, mood, hedging policy, a sentence cap, a title cap, the title grammar, three precepts to follow, three to avoid, and one contrast pair. The validator checks that the block's own prose obeys the laws above, that the examples fit the declared caps, and that the generic counter-example trips at least one law.

Runtime cost

The prose above is the handbook surface and never enters an agent context. The runtime payload is the voice block inside the one design language a request resolves to, plus the laws above in compact form. Section 2.1 of PROTOCOL.md governs: an agent loads one language, not the catalogue.