Skip to content

fix(docs): force ER attribute text color via themeCSS in dark mode#132

Merged
pratyush618 merged 1 commit intomasterfrom
fix/mermaid-er-text-color
May 3, 2026
Merged

fix(docs): force ER attribute text color via themeCSS in dark mode#132
pratyush618 merged 1 commit intomasterfrom
fix/mermaid-er-text-color

Conversation

@pratyush618
Copy link
Copy Markdown
Collaborator

Follow-up to #131. The 7-slide schema carousel showed alternating dim text in dark mode — odd rows ended up with washed-out characters that were nearly unreadable.

Root cause

Two compounding issues:

  1. Mermaid's auto-contrast for ER rows. With odd-vs-even row backgrounds set to two slightly different shades (#1f2024 / #272a30), Mermaid's internal heuristics chose different text colors for each — and in dark mode the choice for one of them landed on a low-contrast grey instead of the configured textColor.

  2. themeVariables.textColor doesn't propagate to ER .attribute-text reliably. The ER renderer uses its own internal class hierarchy (.er.attributeBoxOdd, .er.attributeBoxEven, .er .attribute-text) and doesn't always read from textColor. Some Mermaid versions ship hardcoded fills.

Fix

Three layers of defense in docs/src/components/mermaid.tsx:

  1. Drop the zebra stripe — set both attributeBackgroundColorOdd and attributeBackgroundColorEven to the same value (#1f2024 dark / #ffffff light). Removes the auto-contrast asymmetry entirely.
  2. darkMode: true flag in dark theme variables. Tells Mermaid which way internal heuristics should lean for any color it auto-picks.
  3. themeCSS override with !important — explicit CSS injected into every Mermaid SVG forcing .er.entityBox, .er.entityLabel, .er.attributeBoxOdd/Even, .er .attribute-text, and .er text to the right fill colors. Belt-and-suspenders against any Mermaid-version-specific hardcoded values.

Light theme keeps a subtle alternation (#ffffff / #f4f4f5) since the contrast is fine on a light bg.

Test plan

  • pnpm --dir docs types:check clean
  • pnpm --dir docs lint clean
  • pnpm --dir docs build clean
  • CI: Deploy Docs job
  • Visual: open /docs/architecture/storage in dark mode, flip through all 7 carousel slides — every column (TYPE / NAME / KEY) should be uniformly readable on every row.
  • Light mode same page — subtle row striping, all text readable.
  • Other Mermaid diagrams still render correctly (/docs/architecture/job-lifecycle, /docs/architecture/scheduler).

@github-actions github-actions Bot added the docs label May 3, 2026
@pratyush618 pratyush618 merged commit 744693f into master May 3, 2026
14 checks passed
@pratyush618 pratyush618 deleted the fix/mermaid-er-text-color branch May 3, 2026 12:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant