fix visual-explainer Mermaid theme colors

[FNDEVVE]

Fixes #1043

Root cause

The delegated nicobailon/visual-explainer Mermaid template uses compatible literal hex colors, but Plannotator's authoritative theme override replaced those values with oklch(...) strings.

OKLCH remains valid for normal page CSS in modern browsers. Mermaid is a separate color-processing boundary: with theme: "base", it parses the supplied themeVariables and derives additional colors itself. Mermaid 11 rejects the OKLCH strings during that calculation.

Minimal reproduction

The diagram source was unchanged between both runs:

flowchart TD
  A["Provider"] --> B["Database"]

Loading

With the six OKLCH values from theme-override.md, I ran:

bunx --bun @mermaid-js/mermaid-cli@11.16.0 \
  -i .tmp-mermaid-repro/diagram.mmd \
  -o .tmp-mermaid-repro/oklch.svg \
  -c .tmp-mermaid-repro/oklch.json

Observed result:

Generating single mermaid chart
Error: Unsupported color format: "oklch(0.92 0.01 260)"

A direct Playwright browser probe against Mermaid 11.16.0 produced the same exception from mermaid.initialize(). This is the theme-processing failure behind the generic Mermaid error surface reported in #1043 (aria-roledescription="error" / Syntax error in text); in the current direct API and CLI it fails earlier, during initialization, before an SVG is returned.

Replacing only the theme colors with the new literal hex palette and running the same command produced:

Generating single mermaid chart

The output was a normal aria-roledescription="flowchart-v2" SVG containing Provider and Database.

What changed

• Replaced only the Mermaid-specific palette guidance with literal light and dark hex palettes that preserve Plannotator's purple/neutral identity.
• Added explicit guidance not to pass OKLCH functions, CSS custom-property references such as var(), or color-mix() values into Mermaid themeVariables.
• Clarified that the restriction applies only at Mermaid's color-processing boundary, not to ordinary page CSS.
• Added a directly reusable light/dark example that follows Plannotator's synchronized color-scheme and keeps Mermaid values literal.
• Added a colocated Bun regression test against the authoritative reference.

The light and dark foreground/background pairs were browser-checked at contrast ratios from 6.70:1 to 12.09:1.

Why the regression test is sufficient

This bug is an instruction-source regression, not a Plannotator runtime integration. The focused test reads the authoritative theme-override.md, isolates the Mermaid section and JavaScript example, and verifies that:

• the section and example still exist;
• the example contains Mermaid-compatible literal hex colors;
• the Mermaid section contains no parameterized OKLCH, var, or color-mix values;
• the surrounding light and dark page CSS still uses OKLCH.

That deterministic static contract catches the source mistake without adding a heavyweight Mermaid/browser dependency to the repository test suite. Real Mermaid 11 headless-browser rendering was still performed manually before and after the change.

Verification

• bun install --frozen-lockfile - passed; no lockfile change.
• bun test apps/skills/extra/plannotator-visual-explainer/SKILL.test.ts - 4 passed, 0 failed.
• bun test apps/skills - 7 passed, 0 failed.
• bun test scripts/install.test.ts - 85 passed, 0 failed; includes repository skill/frontmatter validation.
• bun test - 1,947 passed, 85 existing skips, 0 failed.
• bun run typecheck - passed.
• bun run /Users/fnd/.cache/opencode/packages/oh-my-openagent@latest/node_modules/oh-my-openagent/dist/skills/programming/scripts/typescript/check-no-excuse-rules.ts apps/skills/extra/plannotator-visual-explainer/SKILL.test.ts - no violations.
• git diff --check - passed.
• Light headless render: bunx --bun @mermaid-js/mermaid-cli@11.16.0 -i .tmp-mermaid-repro/diagram.mmd -o .tmp-mermaid-repro/light.svg -c .tmp-mermaid-repro/hex.json - passed.
• Dark headless render: bunx --bun @mermaid-js/mermaid-cli@11.16.0 -i .tmp-mermaid-repro/diagram.mmd -o .tmp-mermaid-repro/dark.svg -c .tmp-mermaid-repro/dark.json -b '#070b14' - passed.
• rg -q 'aria-roledescription="flowchart-v2"' plus negative checks for aria-roledescription="error"|Syntax error in text on both rendered SVGs - passed.

Ordinary Plannotator CSS custom properties, including all existing OKLCH light and dark tokens, remain unchanged.

[backnotprop]

thanks, in review