Skip to main content

MasterStyles: Documents That Finally Look Right

· 3 min read
Masterminds Team
Masterminds Team
Product Team

Your documents just got a visual upgrade. Code blocks render with syntax highlighting, Mermaid diagrams are readable by everyone, and hero images change based on your content.

What Was Wrong​

MasterStyles had a rendering gap. Fenced code blocks in HTML, JavaScript, or Python rendered as plain text -- no syntax highlighting, no visual structure. Mermaid diagrams used color themes that failed accessibility standards. Documents flickered during load. Hero images were static placeholders regardless of content.

These problems compounded. A well-structured document looked amateur when rendered.

What Changed​

Syntax-Highlighted Code Blocks​

Fenced code blocks now render with proper syntax highlighting across HTML, JavaScript, and Python. The convert-md-to-html edge function handles language detection and applies theme-aware highlighting before the content reaches your browser.

No configuration needed. Write your code blocks as usual -- the rendering pipeline handles the rest.

Accessible Mermaid Diagrams​

Every Mermaid diagram -- flowcharts, sequence diagrams, ERDs, C4 -- now renders with high-contrast, accessible color themes. This applies across both Markdown and HTML variable types.

We tested against WCAG contrast ratios. Dark elements on light backgrounds, clear label text, and distinguishable color coding. No more squinting at low-contrast node labels.

Dynamic Hero Images​

Hero images now change based on your variable's theme. The system pulls from a catalog stored in mvpl_parameters, matching the variable's topic to relevant imagery. A strategy document gets a different hero than a technical spec.

No More Flicker​

The HtmlSandbox component now debounces contrast passes during load. Previously, the rendering pipeline would flash between states as CSS loaded asynchronously. Now, CSS loads in parallel via the useAllCss() hook with HTTP caching enabled. The result: smooth rendering from the first frame.

Why This Matters​

Documents are the primary output of AI-assisted work in Masterminds. If the rendered output looks unprofessional, the entire platform feels unprofessional -- regardless of how good the AI's content is.

This release closes that gap:

  • Code-heavy documents are now scannable and professional
  • Diagram-heavy documents work for everyone, including users with visual impairments
  • First impressions are smooth -- no loading artifacts or flicker

Technical Notes (for SWEs)​

  • Rendering pipeline: convert-md-to-html edge function handles fenced block detection and highlighting
  • CSS source of truth: src/index.css with 3 variants (non-scoped, .mm-doc-root-scoped, responsive breakpoints)
  • CSS build pipeline: scripts/build-mm-html-style.mjs generates 4 output files -- NEVER edit public/mm_html_style*.css directly
  • Mermaid themes: Accessible defaults applied in both edge function pre-rendering and browser rendering
  • Hero image catalog: Stored in mvpl_parameters via migration 20260211190000_add_masterstyles_hero_images_parameter.sql
  • Contrast debounce: HtmlSandbox.tsx debounces the contrast pass to prevent flicker during parallel CSS load

What's Next​

  • Custom themes per workspace (planned)
  • PDF export with MasterStyles rendering (in design)
  • Collaborative annotations on rendered documents (concept stage)