@gemboss/website-ui 0.1.0 → 0.3.0

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-soft-light` | the accent's tint: active chip, 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-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` | 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
@@ -82,14 +133,20 @@ So:
 
 1. **Accent text on white at least 4.5:1**: `--gw-accent-light` and `--gw-accent-strong-light` on `#ffffff`.
    Check `--gw-accent-strong-light` on `--gw-bg-soft` (`#f2f3f5`) too, where links sit in soft sections.
-2. `--gw-accent-strong-light` on `--gw-accent-soft-light`: at least 4.5:1 (the accent badge and the active chip).
+2. `--gw-accent-strong-light` on `--gw-accent-soft-light`: at least 4.5:1 (the accent badge, the active chip and the
+   chosen option of a segmented control).
 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.

package/js/website.js

@@ -2,7 +2,7 @@
 (function () {
   'use strict';
   if (window.gwWebsite) return;
-  window.gwWebsite = { version: '0.1.0' };
+  window.gwWebsite = { version: '0.3.0' };
   var doc = document, root = doc.documentElement;
   function mq(q) { return window.matchMedia ? matchMedia(q) : { matches: false }; }
   function watch(m, fn) { if (m.addEventListener) m.addEventListener('change', fn); }
@@ -140,8 +140,45 @@
     });
   }
 
+  // Segmented control: a radio group, one Tab stop; arrows (Home, End) move and choose. What one option shows carries
+  // data-gw-show="group:value" and is hidden unless that option is chosen; without the script the markup's own choice shows.
+  function segmented() {
+    all('[data-gw-segmented]').forEach(function (g) {
+      var name = attr(g, 'data-gw-segmented', ''), opts = all('[role="radio"]', g);
+      if (!opts.length) return;
+      function pick(o, focus, said) {
+        var v = attr(o, 'value', '');
+        opts.forEach(function (x) { x.setAttribute('aria-checked', String(x === o)); x.setAttribute('tabindex', x === o ? '0' : '-1'); });
+        if (focus) o.focus();
+        all('[data-gw-show]').forEach(function (el) {
+          var mine = attr(el, 'data-gw-show', '').split(/\s+/).filter(function (t) { return t.split(':')[0] === name; });
+          if (mine.length) el.hidden = mine.indexOf(name + ':' + v) < 0;
+        });
+        if (said && window.CustomEvent) g.dispatchEvent(new CustomEvent('gw:segmented', { bubbles: true, detail: { name: name, value: v } }));
+      }
+      opts.forEach(function (o, i) {
+        on(o, 'click', function () { pick(o, false, true); });
+        on(o, 'keydown', function (e) {
+          var n = opts.length, k = { ArrowRight: i + 1, ArrowDown: i + 1, ArrowLeft: i - 1 + n, ArrowUp: i - 1 + n, Home: 0, End: n - 1 }[e.key];
+          if (k === undefined || e.altKey || e.ctrlKey || e.metaKey) return;
+          e.preventDefault();
+          pick(opts[k % n], true, true);
+        });
+      });
+      pick(opts.filter(function (o) { return attr(o, 'aria-checked', '') === 'true'; })[0] || opts[0]);
+    });
+  }
+
+  // A busy button (aria-busy="true") ignores presses, by mouse or keyboard: no double submit. It keeps its focus and name.
+  function busy() {
+    on(doc, 'click', function (e) {
+      var b = e.target.closest && e.target.closest('.gw-btn[aria-busy="true"]');
+      if (b) { e.preventDefault(); e.stopPropagation(); }
+    }, true);
+  }
+
   function init() {
-    [mega, mobile, theme, reveal, header, current].forEach(function (f) {
+    [mega, mobile, theme, reveal, header, current, segmented, busy].forEach(function (f) {
       try { f(); } catch (e) { console.error('[gw-website]', e); }
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemboss/website-ui",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The GemBoss website kit: tokens, header, footer, sections and the rules (AGENTS.md) that GemCommerce public websites share, plus a CLI that checks a site, reports kit gaps and upgrades.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/SKILL.md

@@ -20,9 +20,12 @@ the kit and its rules are how the page ends up looking designed. Compose from th
    - Changed page: keep its kit classes; change words, order and choice of sections.
    - Site CSS only for what the kit cannot know (an illustration, a product mock-up), with the kit's tokens and
      scales, classes in the site's own prefix. Never style a `.gw-*` class, never edit `node_modules`.
-   - Another brand: change only the accent family, wash hues, logo and favicon (`KIT/docs/theming.md`).
+   - Another brand: choose only the accent family, wash hues, logo and favicon, and the three named profiles
+     (`data-gw-action` and `data-gw-radius` on `<html>`, `.gw-header--float`), never free values
+     (`KIT/docs/theming.md`).
 4. **Words**: real facts only. A missing price, number, name or date becomes a visible `[PLACEHOLDER]` and a
-   question to the person. No em dash in visible text, no "Learn more" as a whole link.
+   question to the person. Made-up numbers in a drawn mock-up get `<p class="gw-window__caption">Illustrative
+   data.</p>` in its window. No em dash in visible text, no "Learn more" as a whole link.
 5. **Check**: `npx gemboss-website check` and fix every error (`--fix-list` gives a to-do list). Then look at the
    page at 320px and 1366px. Only then say it is done.
 

package/system.json

@@ -1,6 +1,6 @@
 {
   "$comment": "The GemBoss website system in one file. css/tokens.css, the docs and `gemboss-website check` all read these values: change a value here, never in one of them alone. Values measured on gemboss.ai and the GemBoss dashboard (DESIGN-LANGUAGE.md of gemboss-www, 15/10/2026).",
-  "version": 1,
+  "version": 2,
   "color": {
     "light": {
       "bg": "#ffffff",
@@ -58,18 +58,16 @@
       "mint": "#1fcf9f"
     },
     "roles": {
-      "action": "The thing you click. Ink, not the accent.",
-      "accent": "Links, focus rings, active state, a chart line, the 8px label square. Never a button fill, never body text.",
+      "action": "The thing you click: ink, or the brand's accent when the site chose the accent action profile (profiles.action).",
+      "accent": "Links, focus rings, active state, a chart line, the 8px label square; the primary button only through the accent action profile. Never body text, never words in a heading, never a section band.",
       "success/warning": "State only.",
       "wash": "The hero wash and illustrations only."
     }
   },
   "radius": {
-    "scale": [0, 4, 6, 8, 12, 16, 20, 999],
-    "action": 8,
+    "scale": [0, 4, 6, 8, 12, 16, 20, 24, 999],
     "chip": 999,
-    "card": 12,
-    "panel": 16
+    "$comment": "Chips stay pills in every profile. The radii of actions, cards, panels and popovers come from the site's radius profile (profiles.radius): components read --gw-radius-action|card|panel|popover, never a number."
   },
   "shadow": {
     "rest": "0 1px 2px rgba(31,30,29,.04), 0 2px 6px rgba(31,30,29,.06)",
@@ -79,6 +77,7 @@
   },
   "type": {
     "family": "Inter, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
+    "mono": "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
     "weights": [400, 500, 600, 650, 700],
     "scale": [11, 12, 13, 14, 16, 18, 20, 22, 24, 30],
     "display_above": 30,
@@ -111,10 +110,37 @@
     "button_height": 40,
     "tap_target_min": 44
   },
+  "profiles": {
+    "$comment": "A brand's three knobs (Chris 25/10/2026, issue #61): each one a named profile, chosen once per site, never free values. The first option is the default and needs no markup. A brand chooses these, its accent family, its wash hues and its logo, and nothing else (docs/theming.md); check reports an unknown name.",
+    "action": {
+      "$comment": "What fills the primary .gw-btn: data-gw-action on <html>. A mapping of roles, not a colour: accent fills the button with the brand's own accent family. The build (with the kit's colours) and check (with the brand's) require on-action to reach 4.5:1 on action and on action-hover, in light and in dark.",
+      "attribute": "data-gw-action",
+      "options": {
+        "ink": { "$comment": "GemBoss, as its dashboard: the thing you click is ink", "action": "action", "action-hover": "action-hover", "on-action": "on-action" },
+        "accent": { "$comment": "a brand whose product's primary buttons are its accent (GemPages)", "action": "accent", "action-hover": "accent-strong", "on-action": "on-accent" }
+      }
+    },
+    "radius": {
+      "$comment": "The shapes: data-gw-radius on <html>. popover is the mega menu, the one floating card under the bar.",
+      "attribute": "data-gw-radius",
+      "options": {
+        "tight": { "$comment": "GemBoss, as its dashboard", "action": 8, "card": 12, "panel": 16, "popover": 20 },
+        "soft": { "$comment": "GemPages (gempages.net measured 25/10/2026: buttons 12, cards 16 to 24, panels 24)", "action": 12, "card": 20, "panel": 24, "popover": 24 }
+      }
+    },
+    "header": {
+      "$comment": "The header's shape: a class next to gw-header on the <header>. float is an inset card from 1080px (the panel radius of the site's profile, the surface at `surface` percent over a `blur` px blur, one hairline, the raised shadow, `gap` px from the top); below 1080px, and so for the phone menu, it is the flat bar. Solid under prefers-reduced-transparency and where the browser cannot blur.",
+      "options": {
+        "flat": { "$comment": "a flat 64px bar with one hairline", "class": "gw-header" },
+        "float": { "class": "gw-header--float", "gap": 16, "surface": 85, "blur": 10 }
+      }
+    }
+  },
   "motion": {
     "properties": ["transform", "opacity"],
     "ease": "cubic-bezier(.22,1,.36,1)",
     "reveal_ms": 700,
-    "$comment": "Animate transform and opacity only. Everything is still under prefers-reduced-motion."
+    "spin_ms": 700,
+    "$comment": "Animate transform and opacity only. Everything is still under prefers-reduced-motion (a busy button's ring turns once every spin_ms, as the dashboard's spinner, and stands still as an ellipsis)."
   }
 }

package/templates/header.html

@@ -1,6 +1,8 @@
 <!--
   Header: one per site, the same on every page. Keep it in one partial or component, never copied per page.
-  A flat 64px bar with one hairline. Below 1080px the nav and Sign in hide and the menu button opens #gw-mobile-menu,
+  A flat 64px bar with one hairline. A brand that chose the floating header adds one class to the <header>:
+  class="gw-header gw-header--float" (an inset card from 1080px, docs/theming.md); nothing else changes.
+  Below 1080px the nav and Sign in hide and the menu button opens #gw-mobile-menu,
   which repeats the same links. website.js runs the mega menus, the mobile menu and the theme toggle.
   Limits: at most five top-level items, one .gw-btn (the primary action), one .gw-btn--secondary. Each mega panel:
   two or three columns of four or five links, at most one feature card. The announcement bar is optional: one sentence.

package/templates/page.html

@@ -5,6 +5,8 @@
   then link the site's own CSS after the kit. Fill the header and footer once, in a shared partial.
   One <h1> per page (in the hero), sections in the order the page needs, then delete every unused part.
   Replace every [bracketed] placeholder. No lorem ipsum, no invented facts.
+  A brand other than GemBoss may add its profiles to <html>, once, here: data-gw-action="accent" (the primary button
+  takes the accent) and data-gw-radius="soft" (rounder corners). See docs/theming.md.
 -->
 <html lang="en">
 <head>

package/templates/sections/hero.html

@@ -4,7 +4,8 @@
   Add .gw-band--night for a dark hero (it counts as one of the page's three night bands).
   Limits: a short label, a two-part headline (muted first sentence, ink second), at most two lines under it,
   one .gw-btn and one secondary action. The optional window holds a real product screen (img with alt, width, height)
-  or a mock-up that says "Illustrative" when its numbers are not real. Never tuck the hero under the header.
+  or a drawn mock-up. Numbers in it that are not real get the caption "Illustrative data." (vi: "Dữ liệu minh hoạ.",
+  zh: "示意数据。"); real ones get their source there. Never tuck the hero under the header.
 -->
 <section class="gw-hero">
   <div class="gw-hero__wash" aria-hidden="true"></div>
@@ -20,6 +21,7 @@
     <div class="gw-window">
       <div class="gw-window__bar">[Where this screen lives, e.g. the app section]</div>
       <div class="gw-window__body"><img src="[/img/screen.webp]" alt="[What the screen shows]" width="[1200]" height="[750]"></div>
+      <p class="gw-window__caption">[Illustrative data. Or the source of the numbers. Delete when the screen shows no numbers.]</p>
     </div>
   </div>
 </section>

package/templates/sections/pricing.html

@@ -2,6 +2,11 @@
   Pricing: plan cards with the brand's real plan names and prices, exactly as billed. A missing price is [PRICE]
   and a question to the person, never a guess. One plan may be .gw-plan--featured (an accent hairline, never a fill)
   and only that one gets the filled .gw-btn; the others get .gw-btn--secondary.
+  Monthly / yearly: the .gw-segmented radio group, only when the brand really bills yearly for less, with the real
+  discount in its label. Every price is in the markup twice, data-gw-show="billing:monthly" and
+  data-gw-show="billing:yearly" (hidden): the page reads the monthly prices without the script, and website.js
+  swaps them on a choice. Under the price, say what is billed ("Billed $470.40 a year"). No yearly billing: delete
+  the control and every data-gw-show="billing:yearly" element.
   Limits: two to four plans, four to six lines per plan, the same lines in the same order on every plan.
 -->
 <section class="gw-section">
@@ -10,12 +15,17 @@
       <p class="gw-label">Pricing</p>
       <h2>[Headline about how pricing works]</h2>
       <p class="gw-lead">[One line: trial, billing, what every plan includes.]</p>
+      <div class="gw-segmented" role="radiogroup" aria-label="[Billing period]" data-gw-segmented="billing">
+        <button type="button" role="radio" aria-checked="true" value="monthly">[Monthly]</button>
+        <button type="button" role="radio" aria-checked="false" value="yearly">[Yearly –DISCOUNT%]</button>
+      </div>
     </div>
     <div class="gw-pricing">
       <div class="gw-plan">
         <h3>[Plan]</h3>
         <p>[Who it is for, in one line]</p>
-        <p class="gw-plan__price">[PRICE] <small>/ month</small></p>
+        <p class="gw-plan__price"><span data-gw-show="billing:monthly">[PRICE]</span><span data-gw-show="billing:yearly" hidden>[PRICE A MONTH, BILLED YEARLY]</span> <small>/ month</small></p>
+        <p><span data-gw-show="billing:monthly">[Billed monthly]</span><span data-gw-show="billing:yearly" hidden>[Billed $X a year]</span></p>
         <a class="gw-btn gw-btn--secondary gw-btn--block" href="[link]">[Action]</a>
         <ul class="gw-list--check"><li>[What is included]</li><li>[What is included]</li></ul>
       </div>
@@ -23,14 +33,16 @@
         <span class="gw-badge gw-badge--accent">[Why this one, e.g. Recommended for …]</span>
         <h3>[Plan]</h3>
         <p>[Who it is for]</p>
-        <p class="gw-plan__price">[PRICE] <small>/ month</small></p>
+        <p class="gw-plan__price"><span data-gw-show="billing:monthly">[PRICE]</span><span data-gw-show="billing:yearly" hidden>[PRICE A MONTH, BILLED YEARLY]</span> <small>/ month</small></p>
+        <p><span data-gw-show="billing:monthly">[Billed monthly]</span><span data-gw-show="billing:yearly" hidden>[Billed $X a year]</span></p>
         <a class="gw-btn gw-btn--block" href="[link]">[Action]</a>
         <ul class="gw-list--check"><li>[What is included]</li><li>[What is included]</li></ul>
       </div>
       <div class="gw-plan">
         <h3>[Plan]</h3>
         <p>[Who it is for]</p>
-        <p class="gw-plan__price">[PRICE] <small>/ month</small></p>
+        <p class="gw-plan__price"><span data-gw-show="billing:monthly">[PRICE]</span><span data-gw-show="billing:yearly" hidden>[PRICE A MONTH, BILLED YEARLY]</span> <small>/ month</small></p>
+        <p><span data-gw-show="billing:monthly">[Billed monthly]</span><span data-gw-show="billing:yearly" hidden>[Billed $X a year]</span></p>
         <a class="gw-btn gw-btn--secondary gw-btn--block" href="[link]">[Action]</a>
         <ul class="gw-list--check"><li>[What is included]</li><li>[What is included]</li></ul>
       </div>

package/templates/sections/prose.html

@@ -0,0 +1,36 @@
+<!--
+  Prose: a page that is read rather than scanned (a blog post, a docs page, terms, privacy). Put the article's own
+  HTML inside .gw-prose as it comes from the CMS or the markdown renderer: no classes needed on its headings,
+  paragraphs, lists, quotes, code, tables or images. Add .gw-prose--sm (16px) for docs and legal pages.
+  The page's <h1> is the article title: in a .gw-hero--compact above, or as the first child of .gw-prose.
+  Limits: one article per page; headings in order (h2, then h3) and never used for size alone; every image with
+  alt, width and height; a wide table in the .gw-table wrapper (a bare table scrolls inside its own box too).
+-->
+<section class="gw-section">
+  <div class="gw-wrap gw-wrap--narrow">
+    <article class="gw-prose">
+      <h1>[Article title]</h1>
+      <p>[The first paragraph: what the reader will know or be able to do by the end.]</p>
+      <h2>[A section of the article]</h2>
+      <p>[Paragraphs of two to five sentences. Links go where they say: <a href="[link]">[the setup guide]</a>.]</p>
+      <ul>
+        <li>[A point, in one or two lines]</li>
+        <li>[A point]</li>
+      </ul>
+      <h3>[A step or a sub-topic]</h3>
+      <p>[Inline code for a command or a name the reader types: <code>[npx gemboss-website check]</code>.]</p>
+      <pre><code>[a block of code or a config the reader copies]</code></pre>
+      <blockquote><p>[A quotation, with its source in the text around it.]</p></blockquote>
+      <figure>
+        <img src="[/img/article-screen.webp]" alt="[What the picture shows]" width="[1200]" height="[750]" loading="lazy">
+        <figcaption>[What to notice in the picture, or where it comes from.]</figcaption>
+      </figure>
+      <div class="gw-table" role="region" aria-label="[What the table compares]" tabindex="0">
+        <table>
+          <thead><tr><th scope="col">[Column]</th><th scope="col">[Column]</th></tr></thead>
+          <tbody><tr><th scope="row">[Row]</th><td>[Value]</td></tr></tbody>
+        </table>
+      </div>
+    </article>
+  </div>
+</section>

package/templates/sections/showcase.html

@@ -1,8 +1,8 @@
 <!--
   Showcase: a night band with one large product screen and two or three points under it. Use for the one feature
   the page is about. It counts as a night band: at most three per page, never two in a row.
-  Limits: centred head (label, h2, two lines), one window (a real screen or an "Illustrative" mock-up),
-  two or three points (.gw-features in .gw-grid--3 or --2), at most one action pair.
+  Limits: centred head (label, h2, two lines), one window (a real screen, or a mock-up whose made-up numbers carry
+  the caption "Illustrative data."), two or three points (.gw-features in .gw-grid--3 or --2), at most one action pair.
 -->
 <section class="gw-section gw-band--night gw-showcase">
   <div class="gw-wrap">
@@ -14,6 +14,7 @@
     <div class="gw-window">
       <div class="gw-window__bar">[Where this screen lives]</div>
       <div class="gw-window__body"><img src="[/img/screen.webp]" alt="[What the screen shows]" width="[1600]" height="[1000]" loading="lazy"></div>
+      <p class="gw-window__caption">[Illustrative data. Or the source of the numbers. Delete when the screen shows no numbers.]</p>
     </div>
     <div class="gw-features gw-grid--3">
       <div class="gw-feature"><h3>[Point]</h3><p>[One line.]</p></div>

package/templates/sections/split.html

@@ -2,7 +2,8 @@
   Split: one idea told in words beside a figure (a real screen, or a drawn mock-up of the product).
   .gw-split--reverse puts the figure on the left on wide screens; on phones the words always come first.
   Alternate --reverse between consecutive splits. Limits: label, h2, at most two lines, a check list of three to
-  five items, one action (a link or one button). The figure is a .gw-window or a <figure> with alt text.
+  five items, one action (a link or one button). The figure is a .gw-window or a <figure> with alt text; numbers in
+  a window that are not real get the caption "Illustrative data.", real ones their source.
 -->
 <section class="gw-section">
   <div class="gw-wrap gw-split">
@@ -20,6 +21,7 @@
     <div class="gw-window">
       <div class="gw-window__bar">[Where this screen lives]</div>
       <div class="gw-window__body"><img src="[/img/screen.webp]" alt="[What the screen shows]" width="[1200]" height="[900]" loading="lazy"></div>
+      <p class="gw-window__caption">[Illustrative data. Or the source of the numbers. Delete when the screen shows no numbers.]</p>
     </div>
   </div>
 </section>