plannotator-visual-explainer emits unsupported OKLCH Mermaid themeVariables

[FNDEVVE]

Summary

The plannotator-visual-explainer skill explicitly tells agents to pass oklch(...) color strings into mermaid.initialize({ themeVariables }).

Mermaid 11's theme processing does not accept those values. As a result, otherwise-valid Mermaid diagrams render as the generic error SVG:

Syntax error in text

This is not a Mermaid diagram-syntax problem, and OKLCH is not generally invalid in the generated HTML. Modern browsers accept the existing OKLCH values in page CSS. The failure is specifically caused by passing OKLCH into Mermaid's own theme/color processing.

Faulty instruction

The current upstream reference contains this exact example:

https://github.com/backnotprop/plannotator/blob/main/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md#L82-L100

mermaid.initialize({
  theme: "base",
  themeVariables: {
    primaryColor: "oklch(0.50 0.25 280)",
    primaryTextColor: "oklch(1 0 0)",
    primaryBorderColor: "oklch(0.88 0.01 260)",
    lineColor: "oklch(0.40 0.02 260)",
    secondaryColor: "oklch(0.92 0.01 260)",
    tertiaryColor: "oklch(0.92 0.01 260)"
  }
});

The wrapper skill requires agents to read that reference and says the Plannotator color layer overrides the delegated nicobailon/visual-explainer palette. The delegated visual-explainer's Mermaid template already uses compatible hex values, but this Plannotator override replaces them with the failing OKLCH values.

Reproduction

1. Install or update plannotator-visual-explainer from backnotprop/plannotator.
2. Ask it to generate any architecture explainer containing Mermaid.
3. Use the instructed themeVariables above with Mermaid 11.
4. Render even a trivial diagram:

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

Loading

Actual

Mermaid returns an error SVG with aria-roledescription="error" and Syntax error in text.

Control

Replace only the OKLCH themeVariables with hex colors. The same Mermaid source renders successfully.

Expected

The skill should preserve OKLCH for normal page CSS, but supply Mermaid-compatible literal colors (for example hex) to themeVariables.

Mermaid's own theming documentation demonstrates literal hex colors for these fields:
https://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables

Why this keeps recurring

This is in the upstream skill source, not merely in one generated artifact. Every agent following the skill is explicitly instructed to reproduce the invalid configuration, and refreshing the installed skill from backnotprop/plannotator restores the same reference. The example was introduced with the standalone skill/HTML annotation work in commit 1eb561551ca1 and remains present on main.

Both repo-local and global installations therefore reproduce the same behavior.

Suggested acceptance criteria

• Keep Plannotator's OKLCH semantic tokens for page CSS.
• Use a separate light/dark hex (or otherwise Mermaid-compatible) palette inside themeVariables.
• State explicitly that oklch(...), var(...), and color-mix(...) must not be passed to Mermaid theme variables unless Mermaid adds support.
• Add a render check that rejects Mermaid error SVGs (aria-roledescription="error" / Syntax error in text) before an explainer is delivered.