feat(style): add selectable style palettes via new <stylePalette> component

[dqnykamp]

Add selectable style palettes: named, coordinated sets of style definitions that an author swaps in with a single tag.

What changed

• New <stylePalette palette="..."/> component, placed in a document/section directly or in <setup>, scoping exactly like <styleDefinition>. (The attribute is palette rather than name because name is the reserved component-naming attribute.)
• Semantics:
  • A palette selection resets the base styles for its subtree — ancestor <styleDefinition> overrides are discarded (they were tuned against a different palette's colors and could silently break contrast); <styleDefinition>s in the same section or below apply on top.
  • Style numbers beyond the palette's size cycle through the palette (((n−1) mod N)+1), so every number stays on-palette and keeps its accessibility guarantees. Documents with no palette tag keep today's fall-back-to-default behavior, unchanged.
  • Style number 1 always renders text in the ordinary document text color (black, or white in dark mode). Text and math outside a graph take their color from selectedStyle.textColor, and content with no styleNumber lands on style 1 — so without this rule, choosing a palette would recolor every unstyled <text> and <m> in the document. Palette expansion forces it, including for style numbers that wrap onto style 1. Style 1 keeps its own color everywhere else (lines, markers, fills, highContrastColor), styles 2 and up still color their text, and a <styleDefinition styleNumber="1" textColor="..."> still overrides it.
  • Several <stylePalette>s in one section: last wins, earlier ones get a warning diagnostic. Palette names match case-insensitively; unknown names fall back to the default palette with a diagnostic (via validValues).
• Eight new built-in palettes, all meeting the WCAG thresholds in both light and dark mode; marker shapes and line widths (and, in several palettes, line styles) vary across styles so distinctions don't rest on color alone. The registry-wide accessibility guard test enforces this for any future palette.
  • okabeito — colorblind-friendly, adapted from the Okabe–Ito palette: light mode darkens each hue only as far as the contrast thresholds require (with separate darker text variants where a graphic anchor sits below 4.5:1); dark mode pins the canonical Okabe–Ito colors, which all clear the thresholds on a dark canvas.
  • tolbright (7 styles), tolmuted (9), and tolhighcontrast (4) — adapted from Paul Tol's colorblind-safe qualitative palettes, and ibm (5) from the IBM Design Library palette, using the same adaptation recipe; tolhighcontrast keeps every pair above dE 14 under every simulated deficiency, and rebuilds its lightness ladder in dark mode so it stays legible in grayscale there too. (Tol's vibrant palette was evaluated and rejected: post-adaptation it degrades to dE 4 and duplicates tolbright.) The reference page leads with a short recommended list (default, okabeito, tolhighcontrast) so the larger registry stays navigable.
  • grayscale — four hueless grays at even CIELAB-lightness steps across the full contrast-allowed range in each mode; the best option for achromatopsia, and the motivation for a new guarantee: every palette has at least four styles (guard-tested), and docs now advise authors to reserve style numbers 1–4 for their most important distinctions since higher numbers wrap on a four-style palette. Its dark-mode text and high-contrast grays are pinned rather than derived, for two different reasons: textColorDarkMode derives by inverting the light-mode lightness, which keeps the four grays distinct but re-steps them ~15 then ~8 L* instead of the even ~20 the palette is built on; highContrastColorDarkMode derives by lightening the light-mode color only as far as 4.5:1 on the dark canvas requires, and every one of these grays starts below that, so with nothing pinned all four collapse onto the same minimum gray while their *Word descriptors still claim four different grays.
  • categorical — ten maximally varied hues adapted from the Category10 sequence (D3 / matplotlib tab10), with conventional color names. No pair falls below CIEDE2000 dE 12 for typical vision in either mode — the widest spread of any built-in palette — for documents needing many obviously distinct styles. Explicitly not CVD-engineered (green/olive and blue/purple converge under red-green deficiency); documented as such, with all ten styles varying marker shape and line style. Earlier ocean/sunset palettes were dropped: staying within one hue family made adjacent style numbers read as shades of each other. A registry-wide distinctness guard test (paletteColorDistinctness.test.ts) enforces the dE floor on every palette in both modes.
  • grumpynarwhal (6 styles) — saturated burnt orange, forest green, deep pink, arctic teal, gold, and purple that swap for neon counterparts in dark mode; contributed as a CSS custom-property set. Its own background and body-text colors were dropped (Doenet owns the canvas), and dark-mode purple's text variant was lightened to clear 4.5:1 on Doenet's dark canvas. Like categorical, not CVD-engineered, and documented as such.
  • Color words (used in the core-computed style descriptions) are pinned wherever the nearest-anchor hex-to-word derivation misnames a color — it called okabeito's blue "cyan" and its reddish purple "red"; derivation remains the default where it is accurate. Fixing the matcher itself is tracked in Improve the hex-to-color-word algorithm used for style descriptions #1527. Words are guard-tested to be unique per style within a palette, and to agree across the keys of a style that share a color, so style descriptions can always tell two styles apart and never describe one style's lines and markers by different names — this surfaced and fixed a historical flaw where the default palette's style 4 dark-mode purple derived the word "blue".
  • Palette lines and markers render fully opaque unless a palette states lineOpacity/markerOpacity (fills are unaffected — fillOpacity does not feed the contrast diagnostic). Palette colors are chosen against the 3:1 graphic threshold at full strength, but an unstated opacity inherits the built-in 0.7 and blends the color 70% into the canvas, landing most styles of every new palette around 2.1-2.9:1. The accessibility guard now composites at the renderer's own opacity fallback instead of assuming 1, so the gap can't reopen silently. (default states 0.7 on every style, so its softer look is unchanged.)
  • A style that gives textColor and highContrastColor one light-mode value keeps them paired in dark mode: an unstated highContrastColorDarkMode takes the palette's authored textColorDarkMode rather than deriving from the light-mode color alone. Deriving independently ignored the brighter dark anchor the palette pinned, so okabeito's and tolhighcontrast's black styles reported a mid-gray high-contrast color while the rest of the style was white, and okabeito's and tolbright's yellow styles reported a dark olive. A guard now requires a style's high-contrast color to answer to the same word as its lines, in both modes.
  • Palette expansion lowercases the enum-valued keys (markerStyle, lineStyle, fillStyle). Authored attribute values are lowercased on their way to a renderer, but palette data doesn't travel that path, so a palette written with the schema's documented camelCase spelling (markerStyle: "triangleDown") reached JSXGraph as an unknown face name and its points rendered invisible. Guard-tested for every palette.
• New activeStylePaletteName/localStylePaletteName state variables on document and sectioning components drive the reset and cycling.
• The LSP static style resolver mirrors the palette walk (reset, registry lookup, cycling, case-insensitive name matching), so editor context help matches the runtime; palette names autocomplete with per-palette descriptions (schema regenerated).
• Docs: new reference/stylePalette page, a palette section in the styling guide, an updated concepts page, and a note on the styleDefinition page that the styles a <styleDefinition> starts from are the active palette's.

Tests

• Worker: stylePalette.test.ts — selection (document, section, <setup>), scoping, ancestor-override reset, layering, subsection re-selection, cycling (including inherited-palette cycling inside a section), cycled seeding of out-of-range <styleDefinition>s, unknown-name fallback and its diagnostic, case-insensitive names, explicit default-palette selection via a bare <stylePalette/> (still a reset, still cycles), palette-aware style descriptions, camelCase marker styles reaching the renderer in JSXGraph's spelling, neutral style-1 text for unstyled prose (and a <styleDefinition> still overriding it), palette lines/markers reaching selectedStyle at full opacity while the default palette stays at 0.7, last-wins with warning.
• LSP: palette-aware resolution cases in resolve-active-style.test.ts.
• utils: registry/expansion/cycling units — including that a palette painting style 1's text has it overwritten, not merely defaulted — plus registry-wide guards that every palette is WCAG-accessible in both modes, keeps its colors pairwise distinct, never collapses two styles onto one high-contrast color, has at least four styles, describes its colors consistently and uniquely, normalizes its enum values, leaves style 1's text neutral, and describes its high-contrast color the way it describes its lines; plus units for the full-opacity and dark high-contrast pairing rules (each verified to fill in only what a palette leaves unstated).

🤖 Generated with Claude Code