From 6e10721cf829a5aab36184837922c62226293473 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 25 Aug 2026 10:00:55 +0000 Subject: [PATCH] docs: document Valentus FOUC paint-hold (rebased onto main) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebase PR #3 onto main: the head-meta paint-hold fix (including document.fonts.ready release) already landed in 4104c22. This commit keeps only the documentation — branding guide section, activity-log entry, README, and dark-mode-analysis — aligned with the current fonts.ready + 3s fallback implementation. Co-authored-by: Ryan Johnson --- README.adoc | 2 +- dark-mode-analysis.md | 2 +- docs/modules/ROOT/pages/activity-log.adoc | 1 + .../pages/publishing/antora-ui-branding.adoc | 16 ++++++++++++++++ 4 files changed, 19 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index d915d6d..d708407 100644 --- a/README.adoc +++ b/README.adoc @@ -50,7 +50,7 @@ This repository contains the Antora playbook and configuration for the **Dev Cen | `antora-playbook.yml` | Production Antora playbook. Uses remote GitHub URLs for all content sources and the published UI bundle. Used by CI/CD. | `antora-playbook-local.yml` | Local sibling-repo playbook (committed). Expects content repos as siblings (see the playbook `sources` list: `../devcentr`, `../switchyard`, `../msi-generator`, …). | `antora-playbook.testing.yml` | Same local content sources, but points `ui.bundle` at `../valentus-theme/build/ui-bundle.zip` for theme work. -| `supplemental-ui/` | Site overlay on the valentus-theme 2.x UI bundle: custom domain `CNAME`, accent-token brand CSS, header logo under `img/`, and a thin `head-meta.hbs` fork that loads the brand stylesheet. Header logo / navbar text use playbook `site.keys`. +| `supplemental-ui/` | Site overlay on the valentus-theme 2.x UI bundle: custom domain `CNAME`, accent-token brand CSS, header logo under `img/`, and a thin `head-meta.hbs` fork (FOUC paint-hold + preference boot scripts vendored from Valentus, plus the brand stylesheet link). Header logo / navbar text use playbook `site.keys`. | `.vscode/` | VS Code folder settings and extension recommendations for this playbook repo. | `package.json` | Defines dependencies and build scripts. |=== diff --git a/dark-mode-analysis.md b/dark-mode-analysis.md index 137bfd4..155e329 100644 --- a/dark-mode-analysis.md +++ b/dark-mode-analysis.md @@ -10,6 +10,6 @@ Migrated from the retired `antora-dark-theme` package (2026-06). As of valentus-theme 2.x, header logo and navbar branding use playbook `site.keys` (for example `header_logo`) plus optional SVGs in `supplemental-ui/img/`. Search lives in the tool band (not the header). Consumers should not override `partials/header-content.hbs` for logo wiring alone; keep `head-meta.hbs` in sync with upstream when upgrading. -Color theming uses `supplemental-ui/css/devcentr-brand.css` (accent-token overrides), loaded from a thin `head-meta.hbs` fork (vendored from valentus so FOUC / dark-mode / read-width boot stay intact). Playbook `site.keys` stay snake_case; Antora camelCases them for the UI model. +Color theming uses `supplemental-ui/css/devcentr-brand.css` (accent-token overrides), loaded from a thin `head-meta.hbs` fork (vendored from valentus so FOUC paint-hold, dark-mode, read-width, and font-size boot stay intact). The interim `adt-fouc-pending` class hides the page until layered CSS, preference attrs, and web fonts apply; keep brand CSS in the stylesheet stack before the `document.fonts.ready` release script. Playbook `site.keys` stay snake_case; Antora camelCases them for the UI model. See `docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc`. diff --git a/docs/modules/ROOT/pages/activity-log.adoc b/docs/modules/ROOT/pages/activity-log.adoc index 6427386..5cab9dc 100644 --- a/docs/modules/ROOT/pages/activity-log.adoc +++ b/docs/modules/ROOT/pages/activity-log.adoc @@ -8,6 +8,7 @@ This page records significant documentation and project activity at an org level === August +* **valentus-theme FOUC paint-hold** — Synced supplemental `head-meta.hbs` with Valentus interim paint-hold (`adt-fouc-pending`): hide until layered CSS, preference attrs, and web fonts apply; release via `document.fonts.ready` (3s fallback). Brand CSS stays in the stylesheet stack before the release script. xref:publishing/antora-ui-branding.adoc#fouc-paint-hold-interim[Antora UI branding]. * **Internet Architecture / Internet Reliability** — Peer home-nav group (body in general-knowledge): systems altitude for reference durability and usability of the internet; deep-links HCI *Labels versus wires* + connectome-fs. Build-time Mermaid + PlantUML via Kroki (`asciidoctor-kroki`); how-to xref:publishing/antora-diagram-formats.adoc[Antora diagram formats]. Compose pack scaffold `antora-supplemental/antora-facto` (Valentus stays lean). xref:general-knowledge::explanation/internet-architecture/reliability/index.adoc[Internet Reliability]. * **Graphics rendering engines** — general-knowledge explanation for desktop UI stacks, large-document patterns, and post-Skia pipelines (Graphite, Impeller, Vello). Essay: link:https://devcentr.org/news/2026-08-19-after-skia-where-rendering-is-headed[After Skia: where rendering is headed]. Wired into DevCentr toolchain advisor and docs nav. xref:general-knowledge::explanation/architecture/graphics-rendering-engines.adoc[Explanation]. diff --git a/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc b/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc index a6a6a7f..418eb0c 100644 --- a/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc +++ b/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc @@ -37,6 +37,22 @@ Do **not** override `partials/header-content.hbs` unless you need markup the the When upgrading valentus-theme, re-diff `head-meta.hbs` against upstream and keep the brand CSS link after `site-visual.css` / `site-read-width.css` / `site-font-size.css`. The font-size FOUC script and stylesheet are required for the condensed A/A/A control (desktop hide + doc zoom). +[#fouc-paint-hold-interim] +== FOUC paint-hold (interim) + +Valentus 2.x ships an interim *paint-hold* in `head-meta.hbs` while Default UI single-pass CSS lands (see link:https://gitlab.com/antora/antora-ui-default/-/merge_requests/207[antora-ui-default!207] and upstream FOUC/stylesheets guidance). The supplemental overlay must stay in sync with that block. + +Load order in `supplemental-ui/partials/head-meta.hbs`: + +. Inline `html.adt-fouc-pending { visibility: hidden !important; }` plus a script that adds `adt-fouc-pending` on `` *before* stylesheets. +. All layered CSS links (fonts, `site-doc-layout.css`, `site-visual.css`, read-width, font-size, `devcentr-brand.css`, mermaid, math). +. Preference boot scripts (dark mode, read-width, font-size) that set `data-*` attrs / `dark-theme` from `localStorage`. +. A final script that removes `adt-fouc-pending` *after* those scripts run — on this site, via `document.fonts.load` / `document.fonts.ready` with a 3s fallback if the CDN stalls. + +Do **not** place the paint-hold release script before the brand or module stylesheets — users would see a flash of unstyled or wrong-accent chrome. Do **not** drop the read-width or font-size FOUC blocks; they are separate from the global paint-hold but must run before the release script. + +When valentus-theme updates this partial, copy the upstream paint-hold comment block and release timing, then re-insert the `devcentr-brand.css` link in the stylesheet stack. + == Header logo and navbar text [source,yaml]