GitHub's Dark Mode Mermaid Glitch: A Small Hiccup for Big Engineering Goals

When System Sync Breaks the Flow: GitHub's Mermaid Dark Mode Challenge

In the world of software development, clear communication is paramount. Tools like Mermaid diagrams, used extensively on platforms like GitHub, help visualize complex processes and system architectures. However, a recent community discussion highlighted a persistent glitch: GitHub's Mermaid rendering still struggles in dark mode when the theme is synced with system settings, impacting developer experience and potentially hindering the clarity needed to achieve critical engineering goals.

The issue, brought to light by user echlebek, describes how Mermaid diagrams appear broken—often with illegible text or incorrect styling—when a user's GitHub theme is set to 'system' and their operating system is in dark mode. This contrasts with diagrams rendering correctly when dark mode is explicitly selected within GitHub's settings, suggesting a problem with how GitHub detects and applies system-wide theme preferences to Mermaid.

The Technical Hiccup: `prefers-color-scheme`

A GitHub staff member, jovbcorreia, confirmed this as a known issue. The root cause lies in Mermaid's inability to correctly detect the prefers-color-scheme: dark media query when GitHub's theme is set to sync with the system. Essentially, the Mermaid integration doesn't re-render diagrams when the system color scheme changes, leading to a mismatch in styling.

Community-Driven Workarounds for Better Developer Analytics

While GitHub works on a permanent fix, the community has stepped up with immediate workarounds. These solutions, though not perfect, offer a way to ensure diagrams remain readable, contributing to smoother workflows and better understanding of project structures—an indirect but important aspect of developer analytics and productivity.

1. Force Dark Theme (Trade-off)

You can force Mermaid to use a dark-compatible theme directly within your diagram's source code. This ensures readability for dark mode users but will render in dark theme even for those in light mode.

%%{init: {'theme': 'dark'}}%%
sequenceDiagram
    box transparent Reconciliation on Resource Event
    participant client as k8s-client
    participant api as api-server
    participant cr@{ "type": "control" } as controller-runtime
    end
    client->>api: spec subresource update
    api-->>client: ok
    api->>cr: resource event loop reconciler
    cr->>cr: compute status, can retry end
    cr->>api: status subresource apply
    api-->>cr: ok

2. Use Neutral Theme (Recommended Trade-off)

A more balanced approach is to use the 'neutral' theme. This theme is designed to render well on both light and dark backgrounds, offering a better compromise for all users.

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    box transparent Reconciliation on Resource Event
    participant client as k8s-client
    participant api as api-server
    participant cr@{ "type": "control" } as controller-runtime
    end
    client->>api: spec subresource update
    api-->>client: ok
    api->>cr: resource event loop reconciler
    cr->>cr: compute status, can retry end
    cr->>api: status subresource apply
    api-->>cr: ok

The Path Forward for Engineering Goals

This discussion underscores the importance of seemingly small UI/UX details for overall developer productivity. When tools don't function as expected, even minor glitches can disrupt focus and create friction, hindering the pursuit of larger engineering goals. The community's proactive engagement and the provision of workarounds highlight the collaborative spirit essential for platform improvement.

Users are encouraged to upvote the original discussion on GitHub to help prioritize a permanent fix. Such feedback is invaluable in shaping a more robust and user-friendly GitHub experience for everyone.