UI refresh follow-ups + review fixes

docs/antora-playbook.yml

@@ -40,13 +40,20 @@ antora:
         # ref globs support *, braces and ! exclusions, but not [] classes.
         tagsarray: [ v*, '!v0.0.*', '2*.*.*' ]
     - require: '@sntke/antora-mermaid-extension' # <1>
+      # Also imported by ui/src/partials/footer-scripts.hbs; keep in sync.
       mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs # <2>
       script_stem: header-scripts
       mermaid_initialize_options:
-        start_on_load: true
+        # startOnLoad waits for window load, which the search index holds back
+        # by seconds. footer-scripts.hbs runs Mermaid as soon as it is ready.
+        start_on_load: false
         theme: base
         theme_variables:
-          font_family: '"Roboto", sans-serif'
+          # The body stack, so diagram labels match the prose around them.
+          # footer-scripts.hbs waits for the webfont before rendering.
+          # Kept in sync by hand with --ds-font-body: this is YAML and cannot
+          # read the token.
+          font_family: '"Special Elite", "Special Elite Fallback", Roboto, sans-serif'
           quadrant1_fill: 'transparent'
           quadrant2_fill: 'transparent'
           quadrant3_fill: 'transparent'

docs/extensions/config-options-reference.js

@@ -126,14 +126,18 @@ function renderFixtureHtml(optionName) {
     }
     if (f.adoc) {
         try {
-            // `leveloffset=2` so the embedded symbol page's `==` headings
-            // render as `<h4>` instead of `<h2>`. That stops the embedded
-            // title from colliding with the absolute-positioned preview
-            // label and matches the `.adoc-preview h4/h5/h6` rules in
-            // `adoc-preview.css`.
+            // `leveloffset=3` so the embedded symbol page's `==` headings
+            // render as `<h5>` and its `===` subsections as `<h6>`, matching
+            // `adoc-preview-extension.js` and the `.adoc-preview h5/h6` rules.
+            // Keeps the embedded title clear of the absolute-positioned
+            // preview label.
             let html = asciidoctorCore().convert(f.adoc, {
                 standalone: false,
-                attributes: { leveloffset: '+2' },
+                // `source-highlighter` makes Asciidoctor emit the
+                // `highlightjs`/`hljs` classes the theme's highlight bundle
+                // selects on. Standalone converter, so it inherits nothing
+                // from the playbook and has to be set here.
+                attributes: { leveloffset: '+3', 'source-highlighter': 'highlightjs' },
             })
             // Tag every section heading inside the preview with
             // `class="discrete"`. The convert() output emits plain

docs/modules/ROOT/pages/commands/index.adoc

@@ -81,14 +81,10 @@ Other ecosystems have adopted similar approaches and comment styles, sometimes w
 MrDocs uses the same two-phase parsing model as the https://spec.commonmark.org/0.31.2/#appendix-a-parsing-strategy[CommonMark specification^]. It adds a pre-step to extract the text from the comment markers, and recognizes some MrDocs-specific commands alongside the standard CommonMark syntax.
 
 .Doc-comment parsing pipeline
-[mermaid]
+// Reserves the rendered size (viewBox 1087.7x298) so the page does not jump.
+[mermaid, height="calc(min(100cqi, 1087.7px) * 298 / 1087.7)"]
 ....
 graph LR
-  classDef input fill:#D1E8FF,stroke:#005CFF,stroke-width:2;
-  classDef common fill:#FFF5D1,stroke:#FFA500,stroke-width:2;
-  classDef mrdocs fill:#F3D1FF,stroke:#8000C0,stroke-width:2;
-  classDef output fill:#D1FFD1,stroke:#008000,stroke-width:2;
-
   PRE["Pre-step<br/>strip markers,<br/>fix indentation"]
   B1["Phase 1<br/>group lines<br/>into blocks"]
   B2["Metadata blocks<br/>@param, @returns…"]

docs/modules/ROOT/pages/generators/index.adoc

@@ -47,7 +47,8 @@ mrdocs --config=path/to/mrdocs.yml --generator=html
 
 Each format trades *redundancy* (how much duplicated or unstructured information lives in the output) against *convenience* (how readily the output is usable without further tooling). The built-in generators are the starting point. When none of them is the right fit, you customize only as far as you need: each step below reaches deeper than the previous one, and each is covered in the xref:extensions/index.adoc[Extensions] section.
 
-[mermaid]
+// Reserves the rendered size (viewBox 500x500) so the page does not jump.
+[mermaid, height="calc(min(100cqi, 500px) * 500 / 500)"]
 ....
 quadrantChart
     title Output format trade-off

docs/modules/ROOT/pages/index.adoc

@@ -9,14 +9,10 @@ Alan Freitas <alandefreitas@gmail.com>
 
 Mr.Docs is a C++ reference documentation generator built on Clang/LLVM. It reads your project's source through a compilation database, builds a complete symbol corpus from the real Clang AST, and emits documentation in several formats. The same corpus feeds rendered documents intended for human readers and structured data intended for downstream tools.
 
-[mermaid]
+// Reserves the rendered size (viewBox 862.71x302) so the page does not jump.
+[mermaid, height="calc(min(100cqi, 862.71px) * 302 / 862.71)"]
 ....
 graph LR
-  classDef input fill:#D1E8FF,stroke:#005CFF,stroke-width:2;
-  classDef stage fill:#FFF5D1,stroke:#C97A00,stroke-width:2;
-  classDef output fill:#D1FFD1,stroke:#1C7C1C,stroke-width:2;
-  classDef ext fill:#F0E2F0,stroke:#7A4A8E,stroke-width:2,stroke-dasharray:4 2;
-
   CPP["C++ source<br/>doc comments"]:::input
   CFG[Configuration]:::input
   CORPUS([Symbol corpus]):::stage

docs/modules/ROOT/partials/workflow.adoc

@@ -1,4 +1,5 @@
-[mermaid]
+// Reserves the rendered size (viewBox 615.89x860) so the page does not jump.
+[mermaid, height="calc(min(100cqi, 615.89px) * 860 / 615.89)"]
 ....
 graph TD
   %% Define styles for visual clarity

docs/shared/design-system.css

@@ -75,6 +75,20 @@
   --ds-blue-300: #93c5fd; /* Figma exact: hero title, primary button fill */
   --ds-code-800: #272e3e; /* Figma exact: code panel body               */
 
+  /* --- Palette: syntax (code panels, both surfaces) ---------------- *
+   * GitHub Primer dark dimmed, named by its scale index, plus the
+   * brand's green pair for doc comments and the Figma comment grey.
+   * See docs/ui/src/css/highlight.css for the role mapping. */
+  --ds-syntax-gray-400: #6e727b; /* Figma exact: comments        */
+  --ds-syntax-red-300: #f47067; /* keywords                      */
+  --ds-syntax-blue-100: #96d0ff; /* strings                      */
+  --ds-syntax-blue-200: #6cb6ff; /* constants, attributes, meta  */
+  --ds-syntax-orange-200: #f69d50; /* types, class names         */
+  --ds-syntax-purple-200: #dcbdfb; /* function names             */
+  --ds-syntax-green-100: #8ddb8c; /* tags                        */
+  --ds-syntax-green-600: #5e874f; /* doc-comment prose           */
+  --ds-syntax-lime-500: #a4b543; /* doc-comment @tags and names  */
+
   /* --- Palette: brand gold (comic CTA ramp) ------------------------- */
   --ds-gold-400: #ffd700; /* peak / hover              */
   --ds-gold-500: #e5be33; /* rest / function-name / check accent */
@@ -144,6 +158,7 @@
   --ds-leading-tight: 1.125; /* h1                     */
   --ds-leading-snug: 1.25; /* h2                     */
   --ds-leading-normal: 1.5; /* body                   */
+  --ds-leading-code: 1.55; /* code blocks            */
 
   /* --- Spacing scale (base unit = 1rem) ---------------------------- */
   --ds-space: 1rem;
@@ -156,6 +171,7 @@
   --ds-space-2xl: 3rem;
   --ds-space-3xl: 4rem;
   --ds-section-gap: 3rem; /* → 4rem on ≥576px         */
+  --ds-gutter: 16px; /* page side gutter → 24/28/78px, see breakpoints */
 
   /* --- Radii & borders --------------------------------------------- */
   --ds-radius: 0.5rem;
@@ -212,16 +228,19 @@
   :root {
     --ds-font-size: 17px;
     --ds-section-gap: 4rem;
+    --ds-gutter: 24px;
   }
 }
 @media (min-width: 768px) {
   :root {
     --ds-font-size: 18px;
+    --ds-gutter: 28px;
   }
 }
 @media (min-width: 992px) {
   :root {
     --ds-font-size: 19px;
+    --ds-gutter: 78px;
   }
 }
 @media (min-width: 1200px) {
@@ -460,11 +479,21 @@
   --ds-code-panel-chrome: var(--ds-color-code-chrome);
   --ds-code-panel-border: var(--ds-color-outline);
   --ds-code-panel-fg: var(--ds-paper-50); /* plain code text; comments use --ds-code-panel-comment */
-  --ds-code-panel-comment: #6e727b;
+  --ds-code-panel-comment: var(--ds-syntax-gray-400);
   --ds-code-panel-linenum: rgba(255, 255, 255, 0.4);
   --ds-code-panel-keyword: var(--ds-color-label);
-  --ds-code-panel-fn: var(--ds-blue-300);
   --ds-code-panel-tab: var(--ds-white);
+  /* Syntax roles, shared by the docs code blocks and the landing panels.
+     Doc comments take the green pair so the parts that feed the rendered
+     documentation stand out. */
+  --ds-code-panel-hl-keyword: var(--ds-syntax-red-300);
+  --ds-code-panel-hl-string: var(--ds-syntax-blue-100);
+  --ds-code-panel-hl-const: var(--ds-syntax-blue-200);
+  --ds-code-panel-hl-entity: var(--ds-syntax-orange-200);
+  --ds-code-panel-hl-title: var(--ds-syntax-purple-200);
+  --ds-code-panel-hl-tag: var(--ds-syntax-green-100);
+  --ds-code-panel-hl-doc: var(--ds-syntax-green-600);
+  --ds-code-panel-hl-doc-strong: var(--ds-syntax-lime-500);
 
   /* ---- Hero cityscape ---------------------------------------------- *
    * Skyline band anchored to the bottom of the hero. Height is width-

docs/ui/gulp.d/tasks/build.js

@@ -125,8 +125,9 @@ function getPostCssPlugins (dest, preview) {
         //
         // Deliberately not octicons-16.svg: it is referenced with #view-*
         // fragments, which cannot survive inlining. home*.svg is below the
-        // fold on mobile only.
-        filter: /^src[/\\]img[/\\](?:caret|chevron|github|search)\.svg$/,
+        // fold on mobile only. toc-backdrop.svg is not an icon but is a mask
+        // too, so it has the same paint-nothing-until-loaded problem.
+        filter: /^src[/\\]img[/\\](?:caret|chevron|github|search|toc-backdrop)\.svg$/,
         url: 'inline',
         encodeType: 'encodeURIComponent',
         optimizeSvgEncode: true,

docs/ui/src/css/adoc-preview.css

@@ -88,33 +88,50 @@
 }
 
 /*
- * The card is a self-contained visual context, so its headings are
- * sized to read on their own rather than relative to the host page's
- * section depth. The symbol name (h5) is the dominant element and
- * its subsections (h6) are clearly subordinate.
+ * The card renders the same symbol panels as the landing page, so it follows
+ * that spec: symbol title gold at 36px, section titles blue at 24px, both with
+ * the 1.5px-OUTSIDE ink edge. See `docs/website/styles.css`
+ * `.side-by-side > .documentation-panel h2/h3`.
+ *
+ * The sizes are load-bearing: the ink edge is a centred `-webkit-text-stroke`
+ * of fixed width, so at small sizes it closes Bangers' counters and the label
+ * renders as a blob.
+ *
+ * h5 is the symbol name, h6 its sections -- matching
+ * `adoc-preview-extension.js` and the `leveloffset=3` in
+ * `config-options-reference.js`.
  */
 
 .doc .adoc-preview h4,
 .doc .adoc-preview h5,
 .doc .adoc-preview h6 {
   margin: 1.1rem 0 0.5rem;
-  font-weight: 600;
   border: none;
-  color: inherit;
+  /* Landing runs these at 120%; `.doc h1-h6` sets 0.9, which clips the
+     descenders on a stroked face. */
+  line-height: 1.2;
 }
 
+/* Symbol name -- landing `.documentation-panel h2`: gold, 36px. */
 .doc .adoc-preview h4,
 .doc .adoc-preview h5 {
-  font-size: 1.35rem;
-  color: var(--heading-font-color);
+  --doc-heading-fill: var(--gold-surface);
+  --doc-heading-stroke: 3px; /* Figma 1.5px OUTSIDE */
+  --doc-heading-drop: drop-shadow(1.5px 1.5px 0 var(--outline));
+
+  font-size: calc(36 / var(--rem-base) * 1rem);
 }
 
+/* Section titles -- landing `.documentation-panel h3`: blue, 24px, uppercased.
+   Same ink edge as the symbol name, not the thinner one `.doc h6` applies. */
 .doc .adoc-preview h6 {
-  font-size: 0.8rem;
-  color: var(--text-muted);
-  font-weight: 700;
+  --doc-heading-fill: var(--blue-surface);
+  --doc-heading-stroke: 3px; /* Figma 1.5px OUTSIDE */
+  --doc-heading-drop: drop-shadow(1.5px 1.5px 0 var(--outline));
+
+  font-size: calc(24 / var(--rem-base) * 1rem);
   text-transform: uppercase;
-  letter-spacing: 0.06em;
+  letter-spacing: 0.4px;
   margin-top: 1.25rem;
 }
 

docs/ui/src/css/custom.css

@@ -211,6 +211,116 @@ body {
   color: var(--logo-fill);
 }
 
+/* Mermaid renders client-side from the raw source text. Hide the block until
+   the finished SVG lands, then fade it in. Not `[data-processed]`: Mermaid
+   sets that when it starts, before its diagram code has even loaded. The
+   final SVG is the only direct child; the one it measures in is nested. */
+.doc .mermaid:not(:has(> svg)) {
+  visibility: hidden;
+}
+
+/* Each [mermaid] block reserves its rendered height in `cqi` (see the sources),
+   so the page does not jump when the SVG lands. Once it has, the SVG sizes the
+   box: a drifted reservation then shifts slightly rather than overlapping. */
+.doc .imageblock:has(> .mermaid) {
+  container-type: inline-size; /* stylelint-disable-line property-no-unknown */
+}
+
+/* Labels wrap at Mermaid's 200px; `.doc`'s auto hyphens split words there. */
+.doc .mermaid {
+  hyphens: manual;
+}
+
+.doc .mermaid:has(> svg) {
+  animation: mermaid-in var(--ds-transition);
+  height: auto !important;
+}
+
+@keyframes mermaid-in {
+  from {
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .doc .mermaid:has(> svg) {
+    animation: none;
+  }
+}
+
+/* Flowcharts are themed here rather than in the page sources. Mermaid emits
+   `classDef` colours as inline `!important`, which no stylesheet can reach, so
+   the sources bind semantic classes only (input, stage, output...) and leave
+   the colour to these rules. Mermaid's own styles are ID-scoped inside the
+   SVG, hence `!important` throughout.
+
+   Scoped to flowcharts: the quadrant charts below theme their own text, and
+   these node rules would fight them. */
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node polygon,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node path {
+  fill: var(--diagram-surface) !important;
+  stroke: var(--outline) !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.input rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.input polygon,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.input path {
+  fill: var(--diagram-input) !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.stage rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.common rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.stage path,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.common path {
+  fill: var(--diagram-stage) !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.output rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.output path {
+  fill: var(--diagram-output) !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.ext rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.mrdocs rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.concepts rect,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.ext path,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.mrdocs path,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .node.concepts path {
+  fill: var(--diagram-accent) !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) .nodeLabel,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .cluster-label,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .edgeLabel {
+  color: var(--diagram-ink) !important;
+  fill: var(--diagram-ink) !important;
+  background: transparent !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) .cluster rect {
+  fill: var(--diagram-cluster-bg) !important;
+  stroke: var(--border-strong) !important;
+}
+
+/* The label sits on a painted chip; without this it keeps a light one and the
+   ink above turns invisible on dark. */
+.doc .mermaid :is(.flowchart, .flowchart-v2) .edgeLabel .labelBkg,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .edgeLabel rect {
+  fill: var(--bg) !important;
+  background: var(--bg) !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) .flowchart-link {
+  stroke: var(--diagram-line) !important;
+}
+
+.doc .mermaid :is(.flowchart, .flowchart-v2) marker path,
+.doc .mermaid :is(.flowchart, .flowchart-v2) .arrowMarkerPath {
+  fill: var(--diagram-line) !important;
+  stroke: var(--diagram-line) !important;
+}
+
 /* Mermaid quadrant charts (e.g. the "Output format trade-off" scatter) draw
    their title, axis labels and point labels with a fill baked in at init time.
    That single colour can't suit both themes, so recolour the text and the