@pixerate/editor 0.223.7 → 0.223.9

package/dist/tools/skill-evals.d.cts

@@ -20,7 +20,7 @@ export interface SkillEvalCheck extends SkillEvalToolCall {
 }
 export interface SkillEval {
     prompt: string;
-    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture;
     checks: SkillEvalCheck[];
     solution: SkillEvalToolCall[];
 }
@@ -54,6 +54,8 @@ export interface VectorEvalFixture {
         id: string;
         params?: Record<string, unknown>;
     }>;
+    /** Also register the colour tools (`check_color_contrast`, `check_color_palette`, ...). */
+    colorTools?: boolean;
 }
 export interface PaintEvalFixture {
     editor: 'paint';
@@ -107,6 +109,13 @@ export interface EffectEvalFixture {
     /** Tool calls that prepare the session, run in order. */
     setup?: SkillEvalToolCall[];
 }
+export interface CanvasEvalFixture {
+    editor: 'canvas';
+    /** The starting nodes (React Flow style: `id`, `type`, `position`, `width`, `height`, `data`, `parentId`). */
+    nodes: Array<Record<string, unknown>>;
+    /** Tool calls that prepare the canvas (components, instances), run in order. */
+    setup?: SkillEvalToolCall[];
+}
 /** One eval file of a skill. */
 export interface SkillEvalFile {
     skill: string;

package/dist/tools/skill-evals.d.ts

@@ -20,7 +20,7 @@ export interface SkillEvalCheck extends SkillEvalToolCall {
 }
 export interface SkillEval {
     prompt: string;
-    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture;
     checks: SkillEvalCheck[];
     solution: SkillEvalToolCall[];
 }
@@ -54,6 +54,8 @@ export interface VectorEvalFixture {
         id: string;
         params?: Record<string, unknown>;
     }>;
+    /** Also register the colour tools (`check_color_contrast`, `check_color_palette`, ...). */
+    colorTools?: boolean;
 }
 export interface PaintEvalFixture {
     editor: 'paint';
@@ -107,6 +109,13 @@ export interface EffectEvalFixture {
     /** Tool calls that prepare the session, run in order. */
     setup?: SkillEvalToolCall[];
 }
+export interface CanvasEvalFixture {
+    editor: 'canvas';
+    /** The starting nodes (React Flow style: `id`, `type`, `position`, `width`, `height`, `data`, `parentId`). */
+    nodes: Array<Record<string, unknown>>;
+    /** Tool calls that prepare the canvas (components, instances), run in order. */
+    setup?: SkillEvalToolCall[];
+}
 /** One eval file of a skill. */
 export interface SkillEvalFile {
     skill: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.223.7",
+  "version": "0.223.9",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -65,6 +65,10 @@ request like "clean up this export" finds it.
 | [`pixerate-animation-logo-reveal`](pixerate-animation-logo-reveal/SKILL.md) | Animation (`pixerate-animation-editor`) | A short reveal built from the logo's parts, landing on the beat and ending on the held, finished logo. |
 | [`pixerate-generation-budgeted-batch`](pixerate-generation-budgeted-batch/SKILL.md) | Generation (`pixerate-generation`) | The right model for the format, plan and estimate before spending, drafts cheap and finals once, safe retries, variations from the history. |
 | [`pixerate-effect-look-development`](pixerate-effect-look-development/SKILL.md) | Effects (`pixerate-effect-authoring`) | Tune a look in a few moves, save it as a preset, animate with eased keyframes, seamless loops. |
+| [`pixerate-accessibility-audit`](pixerate-accessibility-audit/SKILL.md) | Cross-domain (`pixerate-color`) | Text and non-text contrast, colour-blind-safe meaning, both modes, smallest fixes and a report, in any editor. |
+| [`pixerate-brand-application`](pixerate-brand-application/SKILL.md) | Cross-domain (`pixerate-color`) | Brand roles mapped to exact palette values, near-misses snapped, readable text on brand colours, derivatives and house-style checks. |
+| [`pixerate-canvas-design-system-components`](pixerate-canvas-design-system-components/SKILL.md) | Canvas (`pixerate-canvas`) | Main components and linked instances, component sets with named variant properties, overrides kept linked. |
+| [`pixerate-canvas-layout`](pixerate-canvas-layout/SKILL.md) | Canvas (`pixerate-canvas`) | Align, distribute, order and lock with the arrange commands, changing only the intended axis. |
 | [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Video (`pixerate-video-editor`) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. Owns the dialogue tools. |
 | [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Video (`pixerate-video-editor`) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. Owns the music tools. |
 
@@ -128,12 +132,13 @@ same change.
   `packages/core/tests/agent-skill-evals.test.ts`. An eval has a `prompt` (the task, in the
   user's words), a `fixture` (the starting document: `{ "editor": "spreadsheet", "rows" }`,
   `{ "editor": "image", "width", "height", "background", "shapes" }` or `{ "editor":
-  "vector", "width", "height", "setup" }` with commands that draw the starting art, 
+  "vector", "width", "height", "setup", "colorTools" }` with commands that draw the starting art, 
   `{ "editor": "paint", "width", "height", "setup" }` `{ "editor": "video", "setup" }` or `{ "editor":
   "chart", "setup" }` `{ "editor": "diagram", "setup" }` with tool calls,
   `{ "editor": "rich-text", "html" }`, 
   `{ "editor": "animation", "setup" }`, `{ "editor": "generation", "models", "prices", "history" }`
-  (a fake host that records each generation) or `{ "editor": "effect", "effectId", "setup" }`), `checks` (a read-only
+  (a fake host that records each generation) `{ "editor": "effect", "effectId", "setup" }` or `{ "editor": "canvas",
+  "nodes", "setup" }` (a headless canvas with the component, arrange and document tools)), `checks` (a read-only
   tool, or `run_command` with a read-only command such as `vector.list`, its `args`, what its result must match in `expect`, and `why`) and a `solution` (the
   tool calls an expert would make). The test proves each eval: some check fails on the fixture,
   and all pass after the solution. A model harness runs the same file with the model in place

package/skills/pixerate-accessibility-audit/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: pixerate-accessibility-audit
+description: The accessibility audit workflow across Pixerate editors - checking text contrast (WCAG AA 4.5:1, large text 3:1), non-text contrast for icons, borders and controls (3:1), colour-only meaning and palettes under colour-vision deficiencies, light and dark modes, type readability, and fixing what fails with the smallest change, then reporting what was checked and changed. Use when asked to audit, check or fix accessibility, contrast, legibility, readability or colour-blind safety of a design, chart, icon, document, UI or brand palette, or to meet WCAG, or when check_color_contrast, check_color_palette or check_dual_color_contrast are available. Load with pixerate-color, which lists the colour tools, and the skill for the editor that holds the design.
+metadata:
+  kind: workflow
+  reference: pixerate-color
+---
+
+# Auditing accessibility
+
+An accessibility audit finds what some readers cannot see or tell apart, fixes it with the
+smallest change that keeps the design's intent, and reports both. Measure, never eyeball:
+every text and background pair gets a contrast ratio, every set of colours that carries meaning
+gets a colour-vision check, and every fix is measured again.
+
+This skill is the method. `pixerate-color` has the colour tools; read colours from the design
+with its editor's tools (`vector.list` in the vector editor, `get_chart` and
+`check_chart_colors` for charts, `measure_region` for an image).
+
+## Goal and quality bar
+
+- Normal text at least 4.5:1 against its background, large text (24 px, or 18.5 px bold) at
+  least 3:1 (`check_color_contrast`, with `large: true` for large text).
+- Icons, borders, focus rings, chart lines and control outlines at least 3:1 against what they
+  sit on.
+- Colours that carry meaning (status, series, categories) distinct under protanopia,
+  deuteranopia and tritanopia (`check_color_palette` `ok: true`), and not the only cue (add a
+  label, shape or pattern where meaning matters).
+- Both light and dark modes pass when the design has them (`check_dual_color_contrast`).
+- Fixes change as little as possible: the text colour rather than the brand background, a
+  darker shade of the same hue rather than a new hue.
+- A report lists each pair checked, its ratio before and after, and what changed.
+
+## Inputs to confirm
+
+- **The standard:** WCAG 2 AA (the default) or AAA.
+- **What may change:** usually text and icon colours; brand backgrounds and logos only with
+  approval.
+- **Modes:** light, dark or both.
+
+## Working method
+
+1. **Inventory.** Read every foreground and background pair from the design's editor: text on
+   surfaces, icons on cards, lines on plots, status colours.
+   **Check:** each pair has a role (normal text, large text, graphic, decorative).
+2. **Measure.** `check_color_contrast` for each pair (`large: true` for large text);
+   `check_color_palette` for sets of meaningful colours; `check_dual_color_contrast` for dual
+   colours.
+   **Check:** a list of failures with their ratios.
+3. **Fix the smallest thing.** Use the `suggestion` the contrast check returns (a lightness that
+   passes), or a darker or lighter shade of the same hue; for palettes, replace the clashing
+   colours with ones that differ in lightness as well as hue (blue and orange rather than red and
+   green). Apply with the editor's own tools (`vector.setStyle`, `update_chart_series`).
+   **Check:** measure the pair again; it passes.
+4. **Meaning without colour.** Where a palette carries meaning, make sure a label, icon or shape
+   carries it too.
+5. **Report** pairs, ratios before and after, and anything left that needs a decision (a brand
+   colour that cannot pass with any text colour).
+
+## Decision table
+
+| Element | Requirement | Tool |
+| --- | --- | --- |
+| Body text, labels | 4.5:1 | `check_color_contrast` |
+| Large or bold headings | 3:1 | `check_color_contrast` with `large: true` |
+| Icons, borders, focus rings, chart lines | 3:1 | `check_color_contrast` |
+| Status or series colours | Distinct under CVD | `check_color_palette` |
+| Light and dark themes | Both pass | `check_dual_color_contrast` |
+| Decorative graphics, disabled controls, logos | No requirement | Note them as exempt |
+
+## Recipes
+
+**Fix a button label.** `check_color_contrast` `{ foreground: label, background: button }` →
+use its suggested lightness or a dark shade of the button's hue → apply → check again.
+
+**Colour-blind-safe status colours.** `check_color_palette` with the three colours → replace with
+a set that varies in lightness (`#0072b2`, `#e69f00`, `#000000`) → check again; keep the labels.
+
+**A faint icon.** `check_color_contrast` icon stroke against the card; darken the stroke until it
+reaches 3:1.
+
+## Pitfalls
+
+- **Eyeballing contrast.** Screens and eyes vary; measure every pair.
+- **Changing the brand colour** to fix text; change the text first.
+- **Large-text allowance on small text.** 3:1 applies only to large or bold-large text.
+- **Translucent colours** are measured composited over their real backdrop; pass the opaque
+  backdrop.
+- **Red and green only** for meaning fails the most common colour-vision deficiency.
+- **Fixing one mode** and breaking the other in a dual theme.
+
+## Tools used
+
+- `check_color_contrast`: text and graphic contrast, with a suggested passing lightness
+- `check_color_palette`: distinctness under colour-vision deficiencies
+- `check_dual_color_contrast`, `derive_dual_color`: light and dark modes
+- `inspect_color`: parse and convert a colour
+- `blend_colors`: shades and tints of a hue

package/skills/pixerate-accessibility-audit/evals/button-label-contrast.json

@@ -0,0 +1,97 @@
+{
+	"prompt": "Our 'Buy now' button fails accessibility review: the label is hard to read on the button. Fix the label colour so it meets WCAG AA for normal text, keeping the button's brand blue.",
+	"fixture": {
+		"editor": "vector",
+		"width": 200,
+		"height": 80,
+		"colorTools": true,
+		"setup": [
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 20,
+					"y": 20,
+					"width": 160,
+					"height": 40,
+					"name": "Button",
+					"fill": "#4da3ff",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 60,
+					"y": 32,
+					"width": 80,
+					"height": 16,
+					"name": "Label",
+					"fill": "#ffffff",
+					"stroke": null
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "label on button at least 4.5:1",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$expr": "(() => { const L = (h) => { const c = [1, 3, 5].map((i) => parseInt(h.replace('#', '').padEnd(6, '0').slice(i - 1, i + 1), 16) / 255).map((x) => (x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4)); return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]; }; const cr = (a, b) => { const [x, y] = [L(a), L(b)].sort((p, q) => q - p); return (x + 0.05) / (y + 0.05); }; return cr(v.find((n) => n.name === 'Label').fill, v.find((n) => n.name === 'Button').fill) >= 4.5; })()"
+					}
+				}
+			}
+		},
+		{
+			"why": "the button keeps its blue",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$some": {
+							"name": "Button",
+							"fill": "#4da3ff"
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "check_color_contrast",
+			"args": {
+				"foreground": "#ffffff",
+				"background": "#4da3ff"
+			}
+		},
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "vector.setStyle",
+				"params": {
+					"ids": [
+						{
+							"$read": "run_command",
+							"args": {
+								"id": "vector.list"
+							},
+							"path": "result.nodes.1.id"
+						}
+					],
+					"fill": "#0b1f33"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-accessibility-audit/evals/distinct-for-cvd.json

@@ -0,0 +1,160 @@
+{
+	"prompt": "These three status dots (OK, warning, error) must be told apart by colour-blind users too. Fix their colours.",
+	"fixture": {
+		"editor": "vector",
+		"width": 120,
+		"height": 40,
+		"colorTools": true,
+		"setup": [
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "ellipse",
+					"x": 10,
+					"y": 10,
+					"width": 20,
+					"height": 20,
+					"name": "OK",
+					"fill": "#2ca02c",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "ellipse",
+					"x": 50,
+					"y": 10,
+					"width": 20,
+					"height": 20,
+					"name": "Warning",
+					"fill": "#bcbd22",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "ellipse",
+					"x": 90,
+					"y": 10,
+					"width": 20,
+					"height": 20,
+					"name": "Error",
+					"fill": "#d62728",
+					"stroke": null
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the three colours pass the colour-vision check",
+			"tool": "check_color_palette",
+			"args": {
+				"colors": {
+					"$read": "run_command",
+					"args": {
+						"id": "vector.list"
+					},
+					"path": "result.nodes.*.fill"
+				}
+			},
+			"expect": {
+				"ok": true
+			}
+		},
+		{
+			"why": "still three dots",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$length": 3
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "check_color_palette",
+			"args": {
+				"colors": [
+					"#2ca02c",
+					"#bcbd22",
+					"#d62728"
+				]
+			}
+		},
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "vector.setStyle",
+				"params": {
+					"ids": [
+						{
+							"$read": "run_command",
+							"args": {
+								"id": "vector.list"
+							},
+							"path": "result.nodes.0.id"
+						}
+					],
+					"fill": "#0072b2"
+				}
+			}
+		},
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "vector.setStyle",
+				"params": {
+					"ids": [
+						{
+							"$read": "run_command",
+							"args": {
+								"id": "vector.list"
+							},
+							"path": "result.nodes.1.id"
+						}
+					],
+					"fill": "#e69f00"
+				}
+			}
+		},
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "vector.setStyle",
+				"params": {
+					"ids": [
+						{
+							"$read": "run_command",
+							"args": {
+								"id": "vector.list"
+							},
+							"path": "result.nodes.2.id"
+						}
+					],
+					"fill": "#000000"
+				}
+			}
+		},
+		{
+			"tool": "check_color_palette",
+			"args": {
+				"colors": {
+					"$read": "run_command",
+					"args": {
+						"id": "vector.list"
+					},
+					"path": "result.nodes.*.fill"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-accessibility-audit/evals/icon-non-text-contrast.json

@@ -0,0 +1,109 @@
+{
+	"prompt": "The outline icon on this card is too faint. Make sure it meets the WCAG contrast for non-text graphics (3:1) against the card.",
+	"fixture": {
+		"editor": "vector",
+		"width": 120,
+		"height": 120,
+		"colorTools": true,
+		"setup": [
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 0,
+					"y": 0,
+					"width": 120,
+					"height": 120,
+					"name": "Card",
+					"fill": "#ffffff",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "ellipse",
+					"x": 40,
+					"y": 40,
+					"width": 40,
+					"height": 40,
+					"name": "Icon",
+					"fill": null,
+					"stroke": "#c8c8c8",
+					"strokeWidth": 2
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the icon stroke against the card is at least 3:1",
+			"tool": "check_color_contrast",
+			"args": {
+				"foreground": {
+					"$read": "run_command",
+					"args": {
+						"id": "vector.list"
+					},
+					"path": "result.nodes.1.stroke"
+				},
+				"background": {
+					"$read": "run_command",
+					"args": {
+						"id": "vector.list"
+					},
+					"path": "result.nodes.0.fill"
+				}
+			},
+			"expect": {
+				"ratio": {
+					"$min": 3
+				}
+			}
+		},
+		{
+			"why": "the card is unchanged",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$some": {
+							"name": "Card",
+							"fill": "#ffffff"
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "check_color_contrast",
+			"args": {
+				"foreground": "#c8c8c8",
+				"background": "#ffffff"
+			}
+		},
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "vector.setStyle",
+				"params": {
+					"ids": [
+						{
+							"$read": "run_command",
+							"args": {
+								"id": "vector.list"
+							},
+							"path": "result.nodes.1.id"
+						}
+					],
+					"stroke": "#767676"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-brand-application/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: pixerate-brand-application
+description: The brand application workflow across Pixerate editors - applying a brand palette, type and tokens to a design, chart or document, mapping each element to its brand role (background, primary, accent, text), snapping near-miss colours to the palette, keeping text readable on brand colours, deriving tints and dark-mode variants without leaving the brand, and running the house-style checks. Use when asked to brand, rebrand, apply a brand, style guide, palette, theme or design tokens, make something on-brand, snap colours to a palette, or check brand consistency, or when check_color_contrast, check_color_palette, blend_colors or a check_*_style tool is available. Load with pixerate-color, which lists the colour tools, and the skill for the editor that holds the design.
+metadata:
+  kind: workflow
+  reference: pixerate-color
+---
+
+# Applying a brand
+
+A brand is a small set of decisions: a palette with roles (background, primary, accent, text),
+type, and rules for using them. Applying it means mapping every element of a design to a role
+and giving it that role's value exactly, not something close. Colours outside the palette are
+either snapped to the nearest brand colour or derived from one deliberately (a tint, a dark-mode
+variant), and every text pairing still meets contrast.
+
+This skill is the method. `pixerate-color` has the colour tools; the design's editor applies the
+values (`vector.setStyle`, `update_chart_series`), design tokens live in `pixerate-tokens`, type
+in `pixerate-typography`, and a host's house style in `check_*_style` tools.
+
+## Goal and quality bar
+
+- Every colour in the design is a brand colour, or a documented derivative of one (a tint, a
+  shade, a dark-mode pair).
+- Each element has the colour of its role: backgrounds, primary surfaces, accents, text.
+- Text on every brand surface meets WCAG AA (see `pixerate-accessibility-audit`).
+- Values are exact (`#1d3557`, not `#1f3759`), referenced from tokens where the editor supports
+  them.
+- Layout, geometry and content are unchanged by the rebrand.
+- House-style checks pass where the host provides them.
+
+## Inputs to confirm
+
+- **The palette with roles**, or a tokens set (`pixerate-tokens`), and the type.
+- **Which elements take which role** when it is not obvious.
+- **What to do when a pairing cannot meet contrast** (another palette colour, larger text, or an
+  approved derivative).
+
+## Working method
+
+1. **Read the design** with its editor: every element's fills, strokes and text colours.
+   **Check:** each element has a role.
+2. **Map roles to brand values.** Write the mapping (background → `#f1faee`, panel → primary,
+   badge → accent) before changing anything.
+3. **Apply exactly**, in one batch where the editor allows it (`run_commands` of
+   `vector.setStyle`, one `update_chart` call).
+   **Check:** reading the design again shows only brand values, and geometry unchanged.
+4. **Snap near-misses.** For colours close to the palette, pick the nearest brand colour by
+   perceptual distance (OKLab): `inspect_color` gives each colour's OKLCH for comparison.
+5. **Readable text.** `check_color_contrast` for each text-on-surface pair; when white fails on a
+   light brand colour, use the darkest brand colour for the text.
+   **Check:** every text pair passes AA.
+6. **Derivatives.** Tints and shades with `blend_colors` in OKLab from a brand colour; dark-mode
+   pairs with `derive_dual_color`. Name and report them.
+7. **House style.** Run the host's `check_*_style` tools (for example `check_chart_style`) and fix
+   what they report.
+
+## Decision table
+
+| Situation | Approach |
+| --- | --- |
+| A colour close to a brand colour | Snap to the nearest by OKLab distance |
+| A needed colour not in the palette | Tint or shade a brand colour (`blend_colors`), and say so |
+| White text fails on a light brand colour | The darkest brand colour for text |
+| No palette colour passes on a surface | Report it; propose larger text or another surface colour |
+| A dark mode is needed | `derive_dual_color` from each brand colour |
+| Charts | Series colours from the palette in its order, checked with `check_chart_colors` |
+| Tokens available | Apply token references, not raw values |
+
+## Recipes
+
+**Apply a palette.** Read element ids → one `run_commands` with a `vector.setStyle` per element
+and its brand `fill` → read again to confirm values and bounds.
+
+**Snap to the palette.** `inspect_color` each off-brand colour and each brand colour; pick the
+smallest OKLab distance; apply.
+
+**Readable badge text.** `check_color_contrast` white and the darkest brand colour on the badge;
+apply the one that passes.
+
+## Pitfalls
+
+- **Close is not on-brand.** `#1f3759` beside `#1d3557` looks the same and fails every audit.
+- **Inventing colours** to fix contrast leaves the brand; use a palette colour or an approved
+  derivative.
+- **Some pairings can never pass**: no text colour reaches 4.5:1 on a mid-tone red or blue.
+  Report it instead of breaking the brand silently.
+- **Rebranding moves things**: change only colours and type, not geometry or content.
+- **Accent overuse**: accents mark what matters; most of a design is background and primary.
+- **Hue-only palettes** for charts fail colour-blind readers; check them.
+
+## Tools used
+
+- `inspect_color`: parse colours and compare them in OKLCH
+- `check_color_contrast`: text on brand surfaces
+- `check_color_palette`: brand colours used for meaning, under colour-vision deficiencies
+- `blend_colors`: tints and shades of brand colours
+- `derive_dual_color`, `check_dual_color_contrast`: dark-mode variants
+- `suggest_color_harmony`: supporting colours when the palette has gaps