[Design] Style Mermaid diagrams

[MaggieAppleton]

Base branch: main
Branch: maggie/style-mermaid-diagrams
Depends on: None

Goal

Research and implement a distinctive, readable Mermaid visual system for Chopin diagrams instead of the current generic neutral rendering.

Context From Planning

• Mermaid diagrams in /design-audit#authored-content look poor and need a dedicated design pass.
• Investigate existing styled Mermaid approaches rather than inventing every diagram treatment from scratch.
• Candidate: beautiful-mermaid offers token-like two-color theming and React integration: https://github.com/lukilabs/beautiful-mermaid. Mermaid itself supports base theme variables and themeCSS. Treat these as candidates, not selected dependencies.

Current Behavior

Chopin lazily renders Mermaid with strict security, HTML labels disabled, suppressed Mermaid error SVGs, and the built-in neutral theme. The editor owns source and preview; wide diagrams use authored drawing size inside an overflowable preview so labels remain readable.

Desired Behavior

Define a Chopin diagram theme and presentation shell with clean typography, hierarchy, spacing, connectors, nodes, groups, state colors, overflow, source controls, and parse-error treatment across common software-planning diagrams.

Acceptance Criteria

• A research note compares native Mermaid base theme variables/themeCSS, beautiful-mermaid, and at least one other maintained styling approach for quality, diagram coverage, security, bundle cost, and React/editor fit.
• The design audit includes representative flowchart, sequence, state, class/entity, and dense/wide diagrams plus invalid and empty source states.
• Diagram colors, type, radii, strokes, and spacing derive from Chopin design tokens where Mermaid permits.
• Labels remain readable, diagrams can be keyboard-scrolled, and narrow layouts preserve the current overflow behavior.
• Strict security, disabled HTML labels/click handlers, lazy loading, parse-error containment, and source ownership remain intact.
• The chosen approach avoids a second editor or writing generated SVG into Lexical's canonical source.
• Maggie approves the audit specimens before production migration.

Verification Commands

• bun run types
• bun run ci
• bun test packages/editor
• bun run e2e

Primary Surfaces

• /design-audit#authored-content
• Mermaid rendering and preview in packages/editor
• Shared Chopin color, typography, radius, and spacing tokens

Expected PR Checks

• Repo required checks

Report Requirements

• Library/theme comparison and dependency decision
• Before/after screenshots for every representative diagram
• Security, accessibility, bundle, and performance evidence
• Unsupported diagram-specific styling limitations

Implementation Notes

• Prefer native theming when it can reach the desired quality; add a dependency only when it materially improves output and remains maintainable.
• Keep arithmetic/layout owned by Mermaid or application code, not model-generated pixel coordinates.
• Preserve generated SVG sanitization/security boundaries and the derived-preview ownership model.

Stop Conditions

• A candidate requires enabling HTML labels, scripts, click handlers, or unsafe rendering.
• The visual direction cannot cover common diagram types consistently without a design decision.