Skip to content

fix: sync Valentus FOUC paint-hold in head-meta override #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AMDphreak wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: sync Valentus FOUC paint-hold in head-meta override #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
|===
Expand Down
2 changes: 1 addition & 1 deletion dark-mode-analysis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
1 change: 1 addition & 0 deletions docs/modules/ROOT/pages/activity-log.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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].
Expand Down
16 changes: 16 additions & 0 deletions docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<html>` *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]
Expand Down