@gemboss/website-ui 0.2.0 → 0.4.0

package/docs/markup-contract.md

@@ -3,8 +3,8 @@
 The full class list, including the CSS-only helpers added while building 0.1.0 (`.gw-h1`–`.gw-h4`, `.gw-lead`,
 `.gw-note`, `.gw-actions`, `.gw-stats__source`, `.gw-plan__price`, the mobile menu parts…), is `docs/components.md`.
 
-The CSS (`css/*.css`), the script (`js/website.js`) and the templates (`templates/`) agree on exactly this. Change it
-here first, then in all three.
+The CSS (`css/*.css`), the script (`js/website.mjs`, and `js/website.js` built from it) and the templates
+(`templates/`) agree on exactly this. Change it here first, then in all three.
 
 Prefixes: kit classes `gw-`, kit CSS variables `--gw-`, state classes `is-` (set by the script), hooks `data-gw-*`.
 BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
@@ -12,20 +12,96 @@ BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
 ## Page
 
 ```html
-<html lang="en" data-theme?="light|dark">     <!-- absent = follow the system; the toggle sets it -->
+<html lang="en" data-theme?="light|dark" data-gw-action?="accent" data-gw-radius?="soft">
+<!-- data-theme absent = follow the system; the toggle sets it. data-gw-action, data-gw-radius: brand profiles (0.3.0),
+     absent = ink, tight -->
 <body class="gw-page">
   <a class="gw-skip" href="#main">Skip to content</a>
   <div class="gw-announce" role="region" aria-label="Announcement">…<a href="…">…</a></div>   <!-- optional -->
   <header class="gw-header" data-gw-header> … </header>
   <main id="main"> sections </main>
   <footer class="gw-footer"> … </footer>
-  <script src="…/website.js" defer></script>
+  <script src="…/website.js" defer></script>   <!-- or the ESM entry, see "Script" below -->
+```
+
+## Script (0.4.0)
+
+One script wires every part below: the mega menu, the mobile menu, the theme toggle, reveal, the header's scroll
+state, the current page, the segmented control and the busy button. It comes in two entries built from one source
+(`js/website.mjs`; `scripts/build.mjs` writes `js/website.js` from it and `--check` fails when they differ):
+
+| entry | file | how it starts |
+|---|---|---|
+| classic | `js/website.js` (`@gemboss/website-ui/website.js`) | `<script src="…/website.js" defer>`: wires the page on `DOMContentLoaded` by itself, then `window.gwWebsite` |
+| ESM | `js/website.mjs` (`@gemboss/website-ui/website.mjs`) | `import { init, destroy, version } from '@gemboss/website-ui/website.mjs'`: importing does nothing (safe on a server); the app calls `init()` |
+
+- **`init(root = document)`** wires the kit markup under `root`, `root` included. It is idempotent: an element is
+  wired once, so call it again after every client-side navigation or insert, and only the new elements are wired.
+  Called on a fragment, it wires that fragment and nothing else. It also lets go of elements removed from the page
+  since the last call, and moves the script's own `aria-current` mark to the new path. The listeners that belong
+  to the page (Escape, the outside click, the busy-button guard, the system theme, the scroll) are installed once.
+- **`destroy(root = document)`** takes back what `init` wired under `root`: its listeners and its marks. An open
+  mega menu or mobile menu is closed first, so an unmounted menu cannot leave the page locked.
+- **`version`**: `'0.4.0'`. The classic script exposes the three as `window.gwWebsite`.
+- **`data-gw-ready`**: on each wired element, the parts wired on it (`mega`, `menu`, `theme`, `reveal`, `header`,
+  `segmented`). It is a mark for people and tests, not a switch: markup copied from a live page, attribute and all,
+  is still wired.
+- **One copy per page.** The first copy that runs owns the page (`window.gwWebsite`); another one (the classic
+  script next to a bundle, two bundles) hands its calls to it, so nothing is wired twice.
+- Never wire a kit part with the site's own script (a click handler on `.gw-nav__trigger`, a class toggled by hand):
+  insert the kit's markup, then call `init` on it.
+
+### After inserting markup
+
+A Next.js app (App Router): one client component in the root layout, an effect on each route change. Effects run
+after hydration, so the server's markup is never changed before React reads it.
+
+```jsx
+// app/kit-script.jsx
+'use client';
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { init } from '@gemboss/website-ui/website.mjs';
+
+export default function KitScript() {
+  const pathname = usePathname();
+  useEffect(() => { init(); }, [pathname]);
+  return null;
+}
+// app/layout.js: <body className="gw-page">{children}<KitScript /></body>
+```
+
+A component that mounts and unmounts kit markup on its own (a dialog, a part that streams in later):
+`useEffect(() => { const el = ref.current; init(el); return () => destroy(el); }, [])`, on a wrapper with
+`style={{ display: 'contents' }}` so it does not change the layout.
+
+A page that inserts HTML (a GemPages block rendered after load, a CMS preview), with the classic script:
+
+```js
+var slot = document.getElementById('pricing-slot');
+slot.innerHTML = html;           // kit markup: a header, a segmented control, sections
+window.gwWebsite.init(slot);     // wires what is new in it; the rest of the page is left alone
+```
+
+### Events
+
+The script tells the page's own code what changed. Every event is a `CustomEvent` that bubbles, so one listener on
+`document` hears them all; none is fired by `init`.
+
+| event | target | `detail` | fires when |
+|---|---|---|---|
+| `gw:mega` | the trigger (`[data-gw-mega]`) | `{ id, open }`: the panel's `id`, `true` when it opened | a panel opens or closes: click, hover, Escape, a click outside, focus leaving, a link inside, `destroy` of an open one. Moving to another menu fires a close, then an open |
+| `gw:theme` | `<html>` | `{ theme: 'light' \| 'dark' }`: the theme the page now shows | a press on a theme toggle; also a change of the system's scheme while the page follows it (no `data-theme`) |
+| `gw:segmented` | the group (`[data-gw-segmented]`) | `{ name, value }`: the group's name, the chosen option's `value` | the reader chooses an option (click, arrows, Home, End) |
+
+```js
+document.addEventListener('gw:theme', function (e) { chart.setTheme(e.detail.theme); });
 ```
 
 ## Header
 
 ```html
-<header class="gw-header" data-gw-header>
+<header class="gw-header gw-header--float?" data-gw-header>   <!-- --float: a brand's header profile (0.3.0) -->
   <div class="gw-wrap gw-header__bar">
     <a class="gw-brand" href="/"><img class="gw-brand__mark" src="…" alt="" width="26" height="26"><span class="gw-brand__name">GemBoss</span></a>
     <nav class="gw-nav" aria-label="Main">
@@ -59,23 +135,35 @@ BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
 Script behaviour:
 - **Mega menu**: click on a trigger toggles its panel (`hidden` removed, `aria-expanded="true"`, `.is-open` on the
   `.gw-nav__item`). Hover opens on fine pointers after 80ms and closes 160ms after leaving item and panel. Only one
-  open at a time. `Escape` closes and returns focus to the trigger. A click outside closes. Arrow keys are not required.
+  open at a time on the page, across every header `init` wired. `Escape` closes and returns focus to the trigger. A
+  click outside closes. Arrow keys are not required. Each change fires `gw:mega`.
 - **Mobile menu** (below 1080px the `.gw-nav` and sign-in hide, `.gw-menu-toggle` shows): the toggle flips `hidden`
-  on `#gw-mobile-menu`, `aria-expanded`, `.is-menu-open` on `<html>` (the CSS locks scroll), and its `aria-label`
-  (Open menu / Close menu). `Escape` closes. Resizing above 1080px closes it.
+  on the menu its `aria-controls` names (`#gw-mobile-menu`), `aria-expanded`, `.is-menu-open` on `<html>` (the CSS
+  locks scroll), and its `aria-label` (Open menu / Close menu). `Escape` closes. Resizing above 1080px closes it.
 - **Labels in other languages**: the script never writes English over a translated page. Give the toggles their
   words with `data-gw-label-open` / `data-gw-label-close` (menu toggle) and `data-gw-label-dark` /
   `data-gw-label-light` (theme toggle); without them it keeps the markup's own `aria-label`, then falls back to English.
 - **Theme toggle**: cycles light ↔ dark by setting `data-theme` on `<html>`, stores the choice in `localStorage`
-  (`gw-theme`, every access in try/catch), updates `aria-label`. On load, a stored choice is applied before paint by a
-  one-line inline script in `<head>` that the template carries (`templates/page.html`).
-- **Reveal**: elements with `.gw-reveal` get `.is-in` when 15% visible (IntersectionObserver, once). Failsafe: after
-  2.5s, or if IntersectionObserver is missing, all get `.is-in`. Under `prefers-reduced-motion` the CSS shows them
-  without motion.
+  (`gw-theme`, every access in try/catch), updates `aria-label` on every toggle, fires `gw:theme`. On load, a stored
+  choice is applied before paint by a one-line inline script in `<head>` that the template carries
+  (`templates/page.html`).
+- **Reveal**: elements with `.gw-reveal` get `.is-in` when 15% visible (IntersectionObserver, once). Failsafe: 2.5s
+  after the `init` that found them, or at once if IntersectionObserver is missing, they get `.is-in`. Under
+  `prefers-reduced-motion` the CSS shows them without motion.
 - **Header**: `.is-scrolled` on `[data-gw-header]` once the page scrolled more than 8px (the CSS may use it for the
-  hairline only; the bar does not change height or colour).
-- **Current page**: the script marks `aria-current="page"` on `.gw-nav__link` / `.gw-mega__link` whose `href`
-  pathname equals `location.pathname` (when the markup did not already).
+  hairline only; the bar does not change height or colour). The floating header needs nothing more from the script:
+  it is the same element with one more class.
+- **Current page**: the script marks `aria-current="page"` on `.gw-nav__link` / `.gw-mega__link` and the mobile
+  menu's links whose `href` pathname equals `location.pathname` (when the markup did not already). Each `init` takes
+  its own marks back first, so after a client-side navigation they follow the new path; a mark in the markup stays.
+
+## Brand profiles (0.3.0)
+
+- `data-gw-action` and `data-gw-radius` sit on `<html>` only, with a name from `system.json` `profiles` (`ink` or
+  `accent`, `tight` or `soft`); absent means the first. The CSS reads them (`css/tokens.css`), the script does not.
+- `.gw-header--float` sits on the `<header class="gw-header">` itself, next to `gw-header`.
+- `check` reports any other name or place (`profile-unknown`, `header-float-markup`) and, with `accent`, words on the
+  button below 4.5:1 (`action-contrast`).
 
 ## Segmented control (0.2.0)
 
@@ -112,14 +200,14 @@ Script behaviour:
 
 | class | what |
 |---|---|
-| `.gw-btn` (+ `--secondary`, `--ghost`, `--on-night`, `--sm`, `--lg`, `--block`) | actions; rectangle 8px, ink fill by default; `:active` pressed, `[aria-busy="true"]` loading (script above) |
+| `.gw-btn` (+ `--secondary`, `--ghost`, `--on-night`, `--sm`, `--lg`, `--block`) | actions; a rectangle with the action radius, the action colour as fill (ink, or the accent under `data-gw-action="accent"`); `:active` pressed, `[aria-busy="true"]` loading (script above) |
 | `.gw-link` (+ `--arrow`) | inline text link in the accent; `--arrow` adds → that moves 2px on hover |
 | `.gw-label` | the label above a heading: 13px muted, 8px accent square before it |
 | `.gw-dim` | the muted first sentence inside a headline |
 | `.gw-chip` (+ `.is-active`) | selectable token, pill |
 | `.gw-segmented` (+ `--block`) | one choice out of two to four (script above) |
 | `.gw-badge` (+ `--accent`, `--success`, `--warning`) | small status, pill |
-| `.gw-card` (+ `--soft`, `--link`) | white box, 1px hairline, radius 12; `--link` makes the whole card an `<a>` |
+| `.gw-card` (+ `--soft`, `--link`) | white box, 1px hairline, the card radius; `--link` makes the whole card an `<a>` |
 | `.gw-window` (+ `__bar`, `__body`, `__caption`) | a framed screenshot/mock-up, like a browser or app window; `__caption` (last child) says what its numbers are: "Illustrative data." or their source |
 | `.gw-icon` | 20px inline stroke SVG wrapper |
 | `.gw-list--check` | list with check marks |

package/docs/philosophy.md

@@ -7,26 +7,31 @@ spirit. Each rule came from measuring real pages, not from taste alone.
 
 A visitor crosses from the website into the product in one click. If the two disagree (a cream site and a white app,
 a purple button outside and a black one inside), the seam is exactly where trust is decided. So the website uses the
-product's language: white canvas, ink actions, one accent, hairlines, almost no shadow.
+product's language: white canvas, the product's action colour, one accent, hairlines, almost no shadow.
 
-## The thing you click is ink
+## The thing you click is one colour: the product's
 
-A page has one thing it wants you to do. Near-black is the strongest mark on white and stays readable in every
-light; the accent colour is louder but weaker as an instruction, and a page full of accent-coloured buttons has no
-hierarchy left. The accent marks where you are and what is interactive in text: links, focus, the active item, the
-small square before a label.
+A page has one thing it wants you to do, and the button that does it looks the same on every page. For GemBoss that
+is near-black ink, as in its dashboard: the strongest mark on white, readable in every light. Since 0.3.0 a brand
+whose product clicks in its accent (GemPages' product uses blue primary buttons) may do the same on its site, with
+the `accent` action profile: the site and the product still speak one language. It is a mode, not a colour picked
+per button; its words must reach 4.5:1 on it, and it never gains a shadow or a gradient. Everywhere else the accent
+marks where you are and what is interactive in text: links, focus, the active item, the small square before a
+label. It never colours the words of a heading or a whole section band: that makes a page louder, not clearer.
 
 ## Shapes carry meaning
 
 Rectangles act, pills choose. When every button is a rectangle and every chip is a pill, people stop reading the
-shape and read the words. A radius scale with seven steps means two cards side by side never differ by 2px, which is
-the kind of drift that makes a page feel assembled rather than designed.
+shape and read the words. A site has one set of corners, a named profile (`tight` for GemBoss, `soft` for GemPages,
+as in each product), so two cards side by side never differ by 2px, which is the kind of drift that makes a page feel
+assembled rather than designed. Profiles, not free values: a brand can look like itself without inventing a radius.
 
 ## Separation by line and space, light only at rest
 
 A shadow says "this floats above". Cards on a page do not float; they sit on it. A 1px hairline and the dashboard's
 resting shadow (two faint pixels) separate a card and keep the page calm; nothing lifts on hover. Larger light is
-spent where it means something: a popover such as the mega menu, an illustration that lights itself.
+spent where it means something: a popover such as the mega menu, the floating header a brand may choose (it does
+float), an illustration that lights itself.
 
 ## Scales instead of eyeballing
 

package/docs/theming.md

@@ -1,27 +1,37 @@
 # Theming for a brand other than GemBoss
 
-A GemCommerce brand (GemPages, Gemians…) uses the kit as it is and changes four things: **its accent colour**, **the
-wash hues**, **its logo** and **its favicon**. Everything else stays the kit's: the shapes, the scales, the ink
-buttons, the white canvas, the type. That is what makes the sites look like one family, and it is why a site built
-by someone with no design training still looks careful.
+A GemCommerce brand (GemPages, Gemians…) uses the kit as it is and chooses six things, **and nothing else**:
 
-Working example: `demo/theme-example.html` (the demo's hero, buttons and cards with a GemPages-style blue).
+1. **the accent variables** (eight, light and dark),
+2. **the wash hues** (only if the brand has its own),
+3. **the logo** (and the favicon),
+4. **the action colour mode**: `data-gw-action="ink|accent"` on `<html>`,
+5. **the radius profile**: `data-gw-radius="tight|soft"` on `<html>`,
+6. **the header style**: the flat bar, or `.gw-header--float`.
 
-## What you may override
+The last three are **named profiles**, not values: a brand picks one of a short list, once for the whole site, and
+every component follows. Everything else stays the kit's: the neutrals, the type, the spacing, the shadows, the
+widths. That is what makes the sites look like one family, and why a site built by someone with no design training
+still looks careful. `npx gemboss-website check` reports anything outside this set.
+
+Working examples: `demo/theme-example.html` (the accent only) and `demo/brand-profiles.html` (a GemPages-style brand:
+the accent, all three profiles and the floating header).
+
+## 1 to 3. Accent, wash, logo
 
 Put these in the site's own CSS (`site.css`, linked **after** `website.css`), in **one `:root {}` block**, and nowhere
 else.
 
 | variable | what it is | GemBoss value |
 |---|---|---|
-| `--gw-accent-light` | the accent on light pages: links, focus ring, active item, label square, chart line | `#5661f5` |
-| `--gw-accent-strong-light` | the accent on hover and as text on `--gw-accent-soft` | `#3a44de` |
+| `--gw-accent-light` | the accent on light pages: links, focus ring, active item, label square, chart line; the primary button's fill under `data-gw-action="accent"` | `#5661f5` |
+| `--gw-accent-strong-light` | accent text (links, the active item), and the accent button's hover and pressed fill | `#3a44de` |
 | `--gw-accent-soft-light` | the accent's tint: active chip, chosen segmented option, accent badge, icon hover | `#eef0fe` |
-| `--gw-on-accent-light` | text on a solid accent (rare; the kit never fills a button with it) | `#ffffff` |
+| `--gw-on-accent-light` | words on a solid accent: the accent button's label | `#ffffff` |
 | `--gw-accent-dark` | the accent in dark mode **and inside night bands** | `#7c84ff` |
-| `--gw-accent-strong-dark` | its hover / strong form | `#a3a9ff` |
+| `--gw-accent-strong-dark` | its text and hover form | `#a3a9ff` |
 | `--gw-accent-soft-dark` | its tint | `#1f2140` |
-| `--gw-on-accent-dark` | text on it | `#0d0d12` |
+| `--gw-on-accent-dark` | words on it | `#0d0d12` |
 | `--gw-wash-pink`, `--gw-wash-violet`, `--gw-wash-sky`, `--gw-wash-mint` | the secondary hues of the hero wash and illustrations | `#ff6f5e`, `#7c8af7`, `#43b0ff`, `#1fcf9f` |
 
 Why the `-light` / `-dark` names and not `--gw-accent` itself: the kit sets `--gw-accent` from these in four places
@@ -33,45 +43,86 @@ The logo and the favicon are files, not variables: the `<img class="gw-brand__ma
 `alt=""` because the name is written next to it) and the `<span class="gw-brand__name">` in the header and footer
 partials, and `<link rel="icon">` in the page head.
 
+## 4 to 6. The three profiles
+
+Chosen once, in the page skeleton (the layout or partial every page shares). The first of each is the default and
+needs no markup, so a GemBoss page, and every page written for 0.2.0, stays exactly as it was.
+
+```html
+<html lang="en" data-gw-action="accent" data-gw-radius="soft">
+…
+<header class="gw-header gw-header--float" data-gw-header> …the same header markup… </header>
+```
+
+| knob | profiles | what changes |
+|---|---|---|
+| action colour, `data-gw-action` on `<html>` | `ink` (GemBoss, default), `accent` | `accent`: the primary `.gw-btn` is filled with `--gw-accent`, its words are `--gw-on-accent`, hover and pressed are `--gw-accent-strong`. In dark mode and night bands it takes the `-dark` family. Secondary, ghost and on-night buttons do not change. |
+| radius, `data-gw-radius` on `<html>` | `tight` (GemBoss, default): 8 action, 12 card, 16 panel, 20 mega menu; `soft` (GemPages): 12, 20, 24, 24 | every button, control, card, window, table, FAQ, plan, quote and the mega menu. Chips and badges stay pills. |
+| header, a class on the `<header>` | flat (default), `.gw-header--float` | from 1080px the bar becomes an inset card: the panel radius of the profile (16 tight, 24 soft), the surface at 85% over a 10px blur, one hairline, the raised shadow, 16px from the top. Same bar, same mega menu, same script; below 1080px it is the flat bar, so the phone menu is unchanged. Solid for a visitor who asks for less transparency, and in a browser that cannot blur. |
+
+Why the action colour is a mode and not a colour of its own: the button stays one colour on the whole site, and that
+colour is a family the brand already checked for contrast. "Site and product speak one language": GemBoss's dashboard
+clicks in ink, so gemboss.ai does; GemPages' product uses blue primary buttons, so a GemPages site may too. Still no
+raised or inset shadow on a button, no gradient, no wash.
+
+Why the header uses the panel radius: it is the largest piece of chrome on the page, so it follows the profile with
+the panels; in `tight` that is the 16px the header was designed with.
+
 ## What you may not change
 
 - **Neutrals**: `--gw-bg`, `--gw-bg-soft`, `--gw-surface`, `--gw-ink`, `--gw-ink-2`, `--gw-muted`, `--gw-line`,
   `--gw-line-strong`, and the night colours. No cream or grey page, no brand-coloured ink.
-- **The action**: `--gw-action`, `--gw-action-hover`, `--gw-on-action`. Buttons stay ink. Your accent never fills a
-  button, a section or a header.
+- **The action tokens**: `--gw-action`, `--gw-action-hover`, `--gw-on-action`. Choose the `accent` profile instead;
+  a colour set here is not checked and does not follow dark mode or night bands.
 - **State**: `--gw-success`, `--gw-warning` and their tints. Green and amber mean state on every GemCommerce site.
-- **Scales and shapes**: type sizes and weights, spacing, radii, shadows, widths, the header height, the
-  font family. No rounder buttons, no bigger shadows, no other font.
+- **Scales and shapes**: type sizes and weights, spacing, the radius tokens (`--gw-radius-*`: choose a profile), shadows,
+  widths, the header height, the font family. No pill buttons, no bigger shadows, no other font.
 - **Kit classes**: never restyle a `.gw-*` class. If the kit cannot do what your brand needs, that is a gap
   (`AGENTS.md` section 9), not a theme.
 
-`npx gemboss-website check` reports colours outside the tokens, overrides of `.gw-*` classes and accent-filled
-buttons.
+### Still forbidden with every profile
+
+- **Gradient or accent-coloured words in a heading.** A heading is ink, with a muted first sentence (`.gw-dim`).
+- **Accent-coloured section bands.** A section is white, `--gw-bg-soft` or a night band; the accent only lights a
+  night band's top edge.
+- **All-caps labels.** Labels are sentence case, muted, led by the 8px accent square.
+
+These make a page louder without making it clearer, and `check` reports the last one (`uppercase-label`) and any
+button filled from site CSS (`accent-button`).
+
+`check` also reports: colours outside the tokens, a redefined kit token (`token-redefined`, including the radius and
+action tokens), overrides of `.gw-*` classes, an unknown profile or one set on another element than `<html>`
+(`profile-unknown`), `.gw-header--float` anywhere but the header itself (`header-float-markup`), and, on a page with
+`data-gw-action="accent"`, accent button words below 4.5:1 (`action-contrast`).
 
 ## A full example
 
 ```css
-/* site.css, linked after website.css. The whole theme of a GemPages-style site. */
+/* site.css, linked after website.css. The whole CSS of a GemPages-style brand. */
 :root {
-  /* accent, light pages: #1e5eff on #ffffff is 5.1:1 */
-  --gw-accent-light: #1e5eff;
-  --gw-accent-strong-light: #1547d1;
-  --gw-accent-soft-light: #eaf0ff;
+  /* light pages. #3c67ff fills the accent button: white words on it are 4.58:1 */
+  --gw-accent-light: #3c67ff;
+  /* EXAMPLE, not confirmed by the GemPages team: accent text needs a darker step, because #3c67ff is 4.13:1 on
+     --gw-bg-soft. #2f52d6 is 6.36:1 on white and 5.73:1 on --gw-bg-soft, and the button's hover. */
+  --gw-accent-strong-light: #2f52d6;
+  --gw-accent-soft-light: #eaefff;
   --gw-on-accent-light: #ffffff;
-  /* accent, dark mode and night bands: #6b98ff on #0d0d12 is 7.0:1 */
-  --gw-accent-dark: #6b98ff;
-  --gw-accent-strong-dark: #a8c0ff;
+  /* dark mode and night bands: #7c9bff is 7.37:1 on #0d0d12, and #0d0d12 words on it are 7.37:1 */
+  --gw-accent-dark: #7c9bff;
+  --gw-accent-strong-dark: #a9beff;
   --gw-accent-soft-dark: #16213d;
   --gw-on-accent-dark: #0d0d12;
   /* wash: only if the brand has its own secondary hues; otherwise leave the kit's */
-  --gw-wash-violet: #7b9cff;
 }
 ```
 
 ```html
+<html lang="en" data-gw-action="accent" data-gw-radius="soft">
 <link rel="icon" href="/favicon.svg" type="image/svg+xml">
 …
-<a class="gw-brand" href="/"><img class="gw-brand__mark" src="/logo-mark.svg" alt="" width="26" height="26"><span class="gw-brand__name">GemPages</span></a>
+<header class="gw-header gw-header--float" data-gw-header>
+  <div class="gw-wrap gw-header__bar">
+    <a class="gw-brand" href="/"><img class="gw-brand__mark" src="/logo-mark.svg" alt="" width="26" height="26"><span class="gw-brand__name">GemPages</span></a>
 ```
 
 ## Check the contrast before you ship
@@ -87,10 +138,15 @@ So:
 3. `--gw-accent-dark` and `--gw-accent-strong-dark` on `#0d0d12` (dark page) and on `#0c0e14` (night band): at
    least 4.5:1.
 4. `--gw-accent-strong-dark` on `--gw-accent-soft-dark`: at least 4.5:1.
+5. **With `data-gw-action="accent"`**: `--gw-on-accent-light` on `--gw-accent-light` and on
+   `--gw-accent-strong-light`, and `--gw-on-accent-dark` on `--gw-accent-dark` and on `--gw-accent-strong-dark`: at
+   least 4.5:1. `check` computes these four and fails the site below it (write the colours as `#rrggbb`); the kit's
+   build does the same for its own colours.
 
 Any WCAG contrast checker works (paste the two hex values). A bright brand colour (yellow, light green, cyan) almost
 never passes on white: darken it for `-light` and keep the bright one for `-dark`. If you cannot get 4.5:1 without
 changing the brand colour beyond recognition, keep the kit's accent and use the brand colour only in the logo and
-illustrations.
+illustrations, and keep the ink button.
 
-Then open the site in light and dark (the toggle in the header), at 320px and at 1366px, and look at a night band.
+Then open the site in light and dark (the toggle in the header), at 320px and at 1366px, and look at a night band and
+at the header while the page scrolls under it.