/documd-visuals

Palette contract

The rules every colour in this skill obeys. A theme assigns values to the tokens below; this file defines what those tokens are, which uses they may have, and what has to hold for a use to be allowed.

documd-visuals does not follow the host document's theme. A theme is chosen for the figure, and the figure then looks the same wherever it is pasted — in the viewer, in an export, in a slide, on paper. That is the point: a diagram is an artefact with its own design, not a chameleon.

Values are literal in every theme and every block. No alias or indirection layer, in any engine, including CSS. Token names exist so we can talk about the roles; what ships is values.

Themes

Pick the one that matches where the figure will be read. Nine exist, and they are deliberately different — that is what makes the set useful.

Every theme is designed for a light ground. The set ships no dark page, by decision: a figure is an artefact with its own background, and these are the backgrounds it can carry. A dark page is the host document's business, not something a figure follows.

Each theme is grounded in a named system or a published methodology for its hues and its structure, but the values are this package's own and every one of them is measured against the thresholds below:

Across the set the ramp is held inside a narrow CIELAB lightness band — Solarized's rule — so no category shouts louder than another. The cost is greyscale separation: two categories can sit close in luminance, reported per theme as ramp gap by the contrast gate. A figure that has to survive a photocopier should use Print, whose ramp is a lightness ladder first and a hue set second.

Each theme file carries its own token values, its derived tints and shades, a complete rendered figure showing the theme in use, and a paste-ready block for every engine. Read one file, paste one block.

Two things a theme cannot do, and one it must:

• Cannot widen a token's uses beyond the contract below — only narrow them.
• Cannot invent a token, or put a colour in a block that is not in its own table.
• Must declare, for every fill that may carry a label, the colour allowed to sit on it — and that declaration is measured, not trusted.

Token contract

may be used as is the widest set of uses a theme may grant a token; a theme narrows it, never widens. The cap is structural, not aesthetic: an amber light enough to be a pleasant band is too light to be text or a line, on any ground. sits on is the fill a text token may be placed on.

The ramp is positional: a chart with four categories uses cat-1 … cat-4, in order. Two themes place different colours in those slots; nothing else about the diagram changes.

positive / negative are conveniences for the two semantic families — a theme may point them at the category that already carries that meaning (cat-2 and cat-4 in most themes). -ink variants exist because a mid-lightness family can be a fine fill and a poor text colour; instead of darkening the family (which wrecks the fill), each semantic family gets one readable ink variant — positive-ink, negative-ink, warning-ink. A status chip is the standard use: the family's tint as the fill, its shade as the border, its -ink as the words.

Derived colours

Two derivations cover everything else. Both are computed by the theme generator, never hand-picked, and the table shipped in each theme file is generated from them:

Three things about this are deliberate:

• The mix base is the ground, not a surface. Mixing into a tinted near-white drags every hue towards the same grey and the tints stop being tellable apart — measured: three families' tints became indistinguishable. Mixing into the ground also makes the formula work unchanged on a cream or a dark ground.
• A family gets a shade only when the theme lets it be a line. A family too light to be a line is too light to border its own fill; those take the neutral line border.
• shade flips direction with the theme's polarity. On a light ground the fill is light and the border must be darker; on a dark ground the fill is dark and the border must be lighter.

Modes

Charts pass the ramp to the engine (the top-level color array, config.range.category, the infographic theme.palette, the ordinal scale's range) in token order — never a hand-written list. Cards pick a single accent; a second categorical colour means the layout is really a chart.

Contrast thresholds

WCAG 2.1 relative luminance. Measured per theme, against that theme's own ground and against every fill a token may sit on:

A theme is not graded against the host document's background — that is what the contract's "filled shapes carry their own background" rule is for. It is graded against its own ground, which is the background it was designed to sit on.

Rules for writers

• Pick a theme first, then take every colour from that theme's table. Never mix two themes.
• A raw hex that is not in the theme you chose is a bug — the usage gate fails on it.
• Never put muted inside a tinted fill (it only clears 4.5 on the theme's ground).
• Never use a fill-only token as text or as a line, and never a text token as a fill.
• Charts: list up to 8 categories, in ramp order. More categories → group the tail.
• Cards: one accent plus neutrals. Semantic colour earns its place only if the card is about that state.
• A figure that must survive both a light and a dark page should use a theme whose ground matches neither — the Print ladder reads on either. Otherwise pick the theme for where it will be read.

Verification

Every claim above is machine-checked, per theme:

node skills/scripts/check-all.mjs runs all of them.