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.