From 67152a8477758c9f374d26653af08c72a64e0f76 Mon Sep 17 00:00:00 2001 From: Bryan Ward Date: Mon, 14 Sep 2026 10:25:39 -0700 Subject: [PATCH] fix: restore the breadcrumb chevron and light the mermaid participant labels Two visual defects found by walking the live docs site at 375, 768 and 1440 in both themes. The breadcrumb separator rendered as a solid square on every page, in both themes, at every width. Infima draws it as a chevron background-image; the theme recoloured it with the `background` shorthand, which also resets background-image, so only a 7.5px block of colour was left and the trail read as a row of tags rather than a hierarchy. The chevron now travels in a mask, so background-color still sets the colour and the Infima filter is dropped. Sequence diagrams rendered their participant names in near-black. Mermaid's dark theme applies `.actor { fill: #1f2020 }` to the label as well as the box, and the rule meant to correct that, `text.actor > tspan`, never matches, because these labels carry their text directly in the element with no tspan. The measured result was 1.50:1 against the box and 1.05:1 against the page, so participants read as empty rectangles. Setting the label to --ink-900 gives 10:1. The mermaid dark-mode rules move here from the docs site's own stylesheet, so that every site on the theme gets them and visual fixes live in one repo. Flowcharts, graphs and state diagrams were already correct at 10.71:1 and are unchanged. Co-Authored-By: Claude Opus 5 --- package.json | 2 +- src/css/custom.css | 53 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 5763396..5fe5e15 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@vantagecompute/docusaurus-theme", - "version": "0.5.1", + "version": "0.5.2", "description": "Shared Vantage Compute Docusaurus theme: design system, brand assets, and common theme overrides for all vantagecompute documentation sites.", "license": "MIT", "main": "lib/index.cjs", diff --git a/src/css/custom.css b/src/css/custom.css index 6e9af5a..09c4dfa 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1185,8 +1185,17 @@ html[data-theme='dark'] .provider-showcase-item { background: var(--iris-50); } +/* Infima draws the separator as a chevron background-image tinted by + --ifm-breadcrumb-separator-filter. Recolouring it through the `background` + shorthand also reset background-image, leaving a solid 7.5px square between + every crumb, so the trail read as a row of tags rather than a hierarchy. + Carry the chevron in a mask instead: background-color still sets the colour, + and the filter is no longer needed. */ .breadcrumbs__item:not(:last-child)::after { background: var(--ink-300); + -webkit-mask: var(--ifm-breadcrumb-separator) center / contain no-repeat; + mask: var(--ifm-breadcrumb-separator) center / contain no-repeat; + filter: none; opacity: 0.5; } @@ -2058,3 +2067,47 @@ article { margin-top: 1.5rem; } } + +/* ── Mermaid diagrams in dark mode ─────────────────────────────────── */ + +/* Mermaid's dark theme fills nodes with #1f2020, which sits within about 2% of + the Docusaurus dark page background (#1b1b1d): a contrast ratio of 1.05:1. + Node borders and label text stay legible, but the shapes lose their surfaces + and read as bare wireframe outlines. Lifting the fill to #3a3d44 gives + 1.58:1 against the page while keeping label contrast comfortably above + WCAG AA. + + !important is required throughout: mermaid injects a stylesheet inside each + SVG whose selectors are ID-scoped (#mermaid-nnn .label-container), so an + author stylesheet cannot win on specificity alone. */ +[data-theme='dark'] .docusaurus-mermaid-container rect.label-container, +[data-theme='dark'] .docusaurus-mermaid-container .node rect, +[data-theme='dark'] .docusaurus-mermaid-container .node polygon, +[data-theme='dark'] .docusaurus-mermaid-container .node circle, +[data-theme='dark'] .docusaurus-mermaid-container .node path { + fill: #3a3d44 !important; +} + +/* Sequence diagrams draw their participant boxes as .actor / .labelBox rather + than .node, so they need the same lift. State diagrams already use .node rect + and are covered above. Notes are left alone deliberately: their accent fill + is meaningful and does not collide with the page background. + + These selectors MUST stay qualified to `rect`. Mermaid puts class="actor" on + both the participant box and its label , so a bare `.actor` rule would + paint the label the same colour as the box. */ +[data-theme='dark'] .docusaurus-mermaid-container rect.actor, +[data-theme='dark'] .docusaurus-mermaid-container rect.labelBox { + fill: #3a3d44 !important; +} + +/* The participant label itself. Mermaid's own `.actor { fill: #1f2020 }` hits + the as well as the box, and the rule meant to correct it, + `text.actor > tspan`, never matches: these labels put their text directly in + the element with no tspan. So the name renders near-black, at 1.50:1 + on the lifted box and 1.05:1 on the page, which is why participants looked + like empty rectangles. --ink-900 resolves to #f4f5fb here, giving 10:1. */ +[data-theme='dark'] .docusaurus-mermaid-container text.actor, +[data-theme='dark'] .docusaurus-mermaid-container text.actor > tspan { + fill: var(--ink-900) !important; +}