antora-supplemental · cursor · Aug 12, 2026 · Aug 12, 2026
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -1,6 +1,11 @@
 = Changelog
 :toc:
 
+== 2026-08-12 — Valentus FOUC paint-hold sync
+
+* Sync `supplemental-ui/partials/head-meta.hbs` with Valentus interim paint-hold: open `adt-fouc-pending` before layered CSS links, run preference scripts, then release before deferred `site-math.js`.
+* Document load order and maintenance rules in `docs/modules/ROOT/pages/portal-supplemental-ui.adoc` (published as *Supplemental UI* on the hub).
+
 == 2026-07-31 — antora-supplemental.org domain map
 
 * `site.url` → `https://docs.antora-supplemental.org`; `site_home_url` → apex `https://antora-supplemental.org/`.

diff --git a/README.adoc b/README.adoc
@@ -12,6 +12,8 @@ ifdef::env-github[]
 <a href="https://github.com/antora-supplemental/docs/network/members"><img src="https://img.shields.io/github/forks/antora-supplemental/docs.svg?style=for-the-badge" alt="Forks"></a>
 <a href="https://github.com/antora-supplemental/docs/stargazers"><img src="https://img.shields.io/github/stars/antora-supplemental/docs.svg?style=for-the-badge" alt="Stars"></a>
 <a href="https://github.com/antora-supplemental/docs/issues"><img src="https://img.shields.io/github/issues/antora-supplemental/docs.svg?style=for-the-badge" alt="Issues"></a>
+<a href="https://docs.antora-supplemental.org/"><img src="https://img.shields.io/badge/docs-Antora%20Supplemental-22c55e?style=for-the-badge" alt="Docs"></a>
+<a href="https://github.com/antora-supplemental/docs/actions/workflows/deploy.yml"><img src="https://img.shields.io/github/actions/workflow/status/antora-supplemental/docs/deploy.yml?branch=main&style=for-the-badge&label=deploy" alt="Deploy"></a>
 <br />
 <h3 align="center">Antora Supplemental Docs</h3>
 <p align="center">
@@ -36,6 +38,8 @@ ifdef::env-github[]
 <a href="https://github.com/antora-supplemental/docs/network/members"><img src="https://img.shields.io/github/forks/antora-supplemental/docs.svg?style=for-the-badge" alt="Forks"></a>
 <a href="https://github.com/antora-supplemental/docs/stargazers"><img src="https://img.shields.io/github/stars/antora-supplemental/docs.svg?style=for-the-badge" alt="Stars"></a>
 <a href="https://github.com/antora-supplemental/docs/issues"><img src="https://img.shields.io/github/issues/antora-supplemental/docs.svg?style=for-the-badge" alt="Issues"></a>
+<a href="https://docs.antora-supplemental.org/"><img src="https://img.shields.io/badge/docs-Antora%20Supplemental-22c55e?style=for-the-badge" alt="Docs"></a>
+<a href="https://github.com/antora-supplemental/docs/actions/workflows/deploy.yml"><img src="https://img.shields.io/github/actions/workflow/status/antora-supplemental/docs/deploy.yml?branch=main&style=for-the-badge&label=deploy" alt="Deploy"></a>
 <br />
 <h3 align="center">Antora Supplemental Docs</h3>
 <p align="center">
@@ -55,6 +59,8 @@ image:https://img.shields.io/github/contributors/antora-supplemental/docs.svg?st
 image:https://img.shields.io/github/forks/antora-supplemental/docs.svg?style=for-the-badge[Forks,link=https://github.com/antora-supplemental/docs/network/members]
 image:https://img.shields.io/github/stars/antora-supplemental/docs.svg?style=for-the-badge[Stars,link=https://github.com/antora-supplemental/docs/stargazers]
 image:https://img.shields.io/github/issues/antora-supplemental/docs.svg?style=for-the-badge[Issues,link=https://github.com/antora-supplemental/docs/issues]
+image:https://img.shields.io/badge/docs-Antora%20Supplemental-22c55e?style=for-the-badge[Docs,link=https://docs.antora-supplemental.org/]
+image:https://img.shields.io/github/actions/workflow/status/antora-supplemental/docs/deploy.yml?branch=main&style=for-the-badge&label=deploy[Deploy,link=https://github.com/antora-supplemental/docs/actions/workflows/deploy.yml]
 
 = Antora Supplemental Docs
 
@@ -69,6 +75,7 @@ endif::[]
 
 Documentation hub for the antora-supplemental organization, built with Antora.
 The UI uses the link:https://github.com/antora-supplemental/valentus-theme[valentus-theme] rolling `v2` release bundle (`ui-bundle.zip`, refreshed each build via `snapshot: true`) plus a local green brand overlay (`supplemental-ui/`: `site-org-brand.css` and `img/logo.svg`) so this portal matches the org welcome-site vibe while staying on Valentus 2.x chrome.
+Head overrides and FOUC paint-hold are documented on the hub: link:https://docs.antora-supplemental.org/docs/ROOT/portal-supplemental-ui.html[Supplemental UI].
 
 ++++
 <p align="right">(<a href="#readme-top">back to top</a>)</p>

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -1,6 +1,7 @@
 * xref:index.adoc[Portal]
 * xref:site-rebuild.adoc[Site rebuild (v1/v2)]
 * xref:theme-products.adoc[Theme products]
+* xref:portal-supplemental-ui.adoc[Supplemental UI]
 * xref:antora-dark-mode.adoc[Antora Dark Mode]
 * xref:antora-deployment.adoc[Antora Deployment]
 * xref:antora-github-actions.adoc[Antora on GitHub]

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -10,6 +10,7 @@ Canonical dark-mode overlay docs (install, demo): link:https://antora-supplement
 == Components
 
 * xref:theme-products.adoc[Theme products] — Roles of Valentus, antora-dark-mode, and the retired `antora-dark-theme` name
+* xref:portal-supplemental-ui.adoc[Supplemental UI] — `head-meta.hbs` override, brand overlay, FOUC paint-hold contract
 * xref:antora-dark-mode.adoc[Antora Dark Mode] — Links to the canonical dark-mode extension docs (install, demo, troubleshooting); not duplicated here
 * xref:antora-deployment.adoc[Antora Deployment] — Root vs. subfolder strategy, CI, GitHub Pages, multi-repo playbooks
 * xref:antora-github-actions.adoc[Antora on GitHub] — Actions, workflow templates, template repos, Pages

diff --git a/docs/modules/ROOT/pages/portal-supplemental-ui.adoc b/docs/modules/ROOT/pages/portal-supplemental-ui.adoc
@@ -0,0 +1,86 @@
+= Portal supplemental UI
+:navtitle: Supplemental UI
+:description: How this hub overrides Valentus head-meta, brand CSS, and FOUC paint-hold.
+
+This site layers a local `supplemental-ui/` directory on top of the Valentus rolling `v2` UI bundle (`antora-playbook.yml` → `ui.supplemental_files`).
+The overlay supplies org branding and keeps head scripts in sync with Valentus so preference attributes apply before first paint.
+
+== Layout
+
+[source,text]
+----
+supplemental-ui/
+├── css/
+│   ├── site-math.css          # KaTeX / stem math (required on every org site)
+│   └── site-org-brand.css     # Green brand tokens over Valentus --adt-* variables
+├── img/
+│   ├── logo.svg               # Header mark (playbook site.keys.header_logo)
+│   └── logo-avatar.svg
+├── js/
+│   └── site-math.js           # KaTeX loader (defer in head-meta)
+└── partials/
+    └── head-meta.hbs          # Overrides Valentus head-meta (see below)
+----
+
+Brand CSS must load **after** Valentus `site-visual.css` and `site-read-width.css` so token overrides win over `!important` rules in the bundle (see xref:theme-products.adoc[Theme products] and `AGENTS.md`).
+
+== `head-meta.hbs` load order
+
+The partial replaces the bundle's `head-meta.hbs`.
+Order matters: interim paint-hold, early extras, fonts and layered CSS, preference scripts, then paint-hold release.
+
+[cols="1,3", options="header"]
+|===
+| Step | What runs
+
+| 1. Paint-hold (open)
+| Inline `html.adt-fouc-pending { visibility: hidden }` plus a script that adds `adt-fouc-pending` on `<html>`.
+
+| 2. Early head
+| `site-extra.css`, `dm-navbar` meta, Google Fonts preconnect + stylesheet.
+
+| 3. Layered Valentus CSS
+| `site-doc-layout.css`, `site-visual.css`, `site-read-width.css`, `site-font-size.css`, `site-math.css`, `site-org-brand.css`.
+
+| 4. Preference scripts
+| Dark-mode class (`org-portal`, `dark-theme`), read-width `data-adt-read-width`, font-size `data-adt-font-size` (read from `localStorage`).
+
+| 5. Paint-hold (close)
+| Script removes `adt-fouc-pending` so the page becomes visible with attributes and CSS already applied.
+
+| 6. Tail
+| Optional `antora-repo-url` meta, deferred `site-math.js`.
+|===
+
+=== Interim FOUC paint-hold
+
+Valentus 2.x ships the same interim hack until Antora Default UI can deliver layered stylesheets in a single pass (upstream: `antora-ui-default!207` and master FOUC/stylesheets guidance).
+This hub copies that contract so the portal does not flash unstyled or wrong-theme chrome while supplemental CSS loads.
+
+* **Do not** move brand CSS links above the paint-hold open block — the page stays hidden until layered CSS is linked.
+* **Do not** remove the closing `classList.remove('adt-fouc-pending')` — without it the site stays invisible.
+* When Valentus drops the hack upstream, remove the matching blocks here in the same PR that bumps the UI bundle pin.
+
+The read-width and font-size inline scripts are separate, smaller FOUC guards (same as Valentus `ui-modules`); they set `data-adt-*` attributes before body render.
+
+=== Dark mode and navbar
+
+`meta name="dm-navbar"` defaults to `light` via playbook `site.keys.dark_mode_navbar`.
+The head script copies that into `document.documentElement.dataset.dmNavbar` and applies `dark-theme` when stored preference or system scheme is dark.
+
+== Local preview
+
+[source,shell]
+----
+pnpm install
+pnpm run build        # production content sources
+pnpm run build:local  # sibling repos via local-antora-playbook.yml
+----
+
+After changing `head-meta.hbs` or brand CSS, rebuild and hard-refresh to verify no flash of wrong theme, read width, or font size.
+
+== See also
+
+* xref:theme-products.adoc[Theme products] — Valentus vs `antora-dark-mode`
+* xref:antora-dark-mode.adoc[Antora Dark Mode] — overlay-only dark mode (canonical docs off-site)
+* https://github.com/antora-supplemental/valentus-theme[valentus-theme] — upstream head-meta source of truth
diff --git a/supplemental-ui/partials/head-meta.hbs b/supplemental-ui/partials/head-meta.hbs
@@ -1,5 +1,26 @@
+{{!--
+  HACK (interim paint-hold): hide until layered CSS + preference attrs apply.
+  Copied from Valentus head-meta — pending upstream Default UI single-pass CSS
+  (antora-ui-default!207 + master FOUC/stylesheets guidance). Keep brand CSS
+  links with the other stylesheets, before the paint-hold release script.
+--}}
+<style>
+html.adt-fouc-pending { visibility: hidden !important; }
+</style>
+<script>
+document.documentElement.classList.add('adt-fouc-pending')
+</script>
 <link rel="stylesheet" href="{{{uiRootPath}}}/css/site-extra.css">
 <meta name="dm-navbar" content="{{or site.keys.darkModeNavbar 'light'}}">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=Plus+Jakarta+Sans:ital,wght@0,500;0,600;0,700;1,500&family=Source+Sans+3:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-doc-layout.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-visual.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-read-width.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-font-size.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-math.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-org-brand.css">
 <script>
 (function () {
   document.documentElement.classList.add('org-portal')
@@ -53,15 +74,9 @@
   }
 })()
 </script>
-<link rel="preconnect" href="https://fonts.googleapis.com">
-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=Plus+Jakarta+Sans:ital,wght@0,500;0,600;0,700;1,500&family=Source+Sans+3:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-doc-layout.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-visual.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-read-width.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-font-size.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-math.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-org-brand.css">
+<script>
+document.documentElement.classList.remove('adt-fouc-pending')
+</script>
 {{#if page.origin.webUrl}}
 <meta name="antora-repo-url" content="{{page.origin.webUrl}}">
 {{/if}}