Dark mode compatibility

[chaban-mb]

While MusicBrainz itself has no dark mode yet @kellnerd made some excellent userstyles.

However most scripts in this repo have poor or no dark mode integration:

[majkinetor]

I use Dark Reader and scripts oblige.

[chaban-mb]

I suspected as much.

A native dark mode theme however has significant benefits over automated darkening. For example it doesn't require yet another browser extension, that can increase the attack surface and negatively impact performance.

Dark reader also cannot cover all parts of the design and loses nuances. For example the border of the Falcon icon is not visible anymore and the hover effect almost non-noticeable.

See also https://tickets.metabrainz.org/browse/MBS-14102

[majkinetor]

While not perfect, (there are settings to configure though to minimize said behavior) it works right now with 0 effort. Implementation and syncing across scripts is not exactly trivial too. I will move this to ideas for now.

[claude-ai-milic]

I measured what this would actually take across the repo. Posting the numbers so the decision is grounded — and because the answer turned out better than expected.

The expensive-sounding part is already free

Two facts:

• No script uses attachShadow. Every panel is in the light DOM, so a userstyle can reach all of it.
• kellnerd defines his tokens on :root (--background, --text, --border, --link, --negative, --positive, --invert-value, 34 in total). They already inherit into our injected DOM.

So color: var(--text, #222) themes itself when a userstyle is installed and falls back to exactly today's appearance when it isn't. No dependency on Stylus, no coupling to kellnerd's repo, no runtime cost, nothing to detect. Dark Reader keeps working for anyone who prefers it.

Worth knowing: musicbrainz-userscripts-dark.user.css currently patches jesus2099, loujine, ROpdebee and kellnerd's own scripts — none of the ones here. That file is per-script !important fixups written by hand. So there is nothing to "become compatible with" today; the choice is between waiting to be patched from outside, or being themeable from the inside. Nothing in this repo currently uses prefers-color-scheme either.

What the colour work costs

script	distinct colours	usages	share inside CSS blocks
apollo_editor	233	673	100%
group_therapy	104	250	99%
isrc_scout	98	281	94%
art_station	87	166	100%
credit_hoarder	76	135	52%
platform_check	59	100	56%
mammoth	45	136	98%
fusion	45	67	already tokenised
falcon	27	52	87%
scribe	23	34	100%
total (MB scripts)	~620 distinct	~1900	~90%

Two things follow.

~90% of all colour sits in each script's own CSS template literal — one or two contiguous blocks per script, not scattered through JS. Only credit_hoarder (48%) and platform_check (44%) carry significant inline/.style. colour, and those accept var() fine.

Most of those 620 colours are drift, not design. The top 10 colours cover only 30–46% of usages per script; 125 of Apollo's 233 are used exactly once. The repo contains seven near-identical pale lavenders — #e0d7f2 #e0d8f0 #e0d9f0 #e2dcef #e3d8f5 #e3dcf2 #e3def2 — and two different "primary purples", #5f3ec0 across 5 scripts and #6f42c1 across 7, both meaning the accent.

It is not only colour

Same measurement for the rest of the CSS surface, across the ten MB scripts:

• 105 distinct box-shadow values
• 46 distinct z-index values
• 8 competing border-radius values (5px ×77, 4px ×72, 3px ×68, 6px ×42, 8px ×27, 7px ×26, 9px ×20…)
• font stacks: 164 uses of bare Arial against 36 -apple-system system stacks and 54 inherit — Apollo alone has 40 distinct font declarations
• every script has rolled its own log window, config window, help link, popover and toast, with its own class prefix and its own markup

None of that is a dark-mode problem. It is the same underlying problem: no shared base, so each script re-invented the same six components slightly differently. Dark mode is just the first thing that makes the divergence expensive.

What this means for the work

The mechanical substitution is not the cost. Three things are:

1. Mapping ~620 colours onto ~25 semantic roles. A judgement call per colour; no tool can tell "this grey is a border" from "this grey is disabled text".
2. Colours that carry meaning rather than decoration — Apollo's confidence tiers, group_therapy's row shading, platform_check's ✓/~/× states, diff highlighting. A pale-red "low confidence" tint is invisible on #333; these need re-deriving for a dark background, not token-swapping. This is the only part that needs real design work.
3. Visual QA on every surface, twice. This dominates the calendar time, not the editing.

Two risks worth recording now: Dark Reader plus a native theme will double-invert (so anything shipped must be off unless asked for, or detect an already-dark palette), and brand colours must be explicitly exempt — platform icons and provider colours are correct as they are, and someone will eventually "fix" Spotify green if that carve-out isn't written down.

Recommendation

Do it as a shared base rather than as a dark theme. The token layer is theme-source-agnostic: Stylus, a built-in theme picker, or prefers-color-scheme all drive the same variables, so this stays useful whether or not anyone installs a userstyle — and future scripts start from the standard instead of re-deriving it.

Sequenced so every step ships on its own and stopping halfway still leaves the repo better off. Tracking issues to follow.

/cc @chaban-mb — the meaning-carrying colours in point 2 are where your eye would be most useful; that is the part I would not want to decide alone.

[claude-ai-milic]

Tracking issues created, sequenced so each one ships on its own and stopping part-way still leaves the repo better off:

• UI standardization: one shared base for all scripts #561 — umbrella: one shared base for all scripts, with the per-script tracker and the right to stop
• Standardization: shared design tokens (colour, type, spacing, elevation) #562 — shared design tokens (colour, type, spacing, elevation). No visible change; unblocks the rest
• Standardization: shared UI components (log, config, help, popover, toast, toolbar) #563 — shared UI components: log window, config window, help link, popover/entity picker, toast, toolbar
• Standardization: theme configurator #564 — theme configurator: built-in light/dark/auto plus Stylus override

Scope narrowed on majkinetor's call: discogs_credits is deprecated and bandcamp_player_enhanced isn't a MusicBrainz script, so both are out — ten scripts in.

@chaban-mb the part worth your attention is in #564: the colours that carry meaning rather than decoration — Apollo's confidence tiers, group_therapy's row shading, platform_check's ✓/~/× and the amber "found but wrong" ring, diff highlighting, Art Station's staged/removed/error cards. Those are pale tints picked against white; on #333 a pale-red "low confidence" tint is simply invisible, and they need dark counterparts that keep the same ordering and the same at-a-glance reading. That is judgement rather than substitution, and the screenshots in your original post are the best evidence of where it currently breaks.

[majkinetor]

Merged to main. #564