@gemboss/website-ui 0.1.0 → 0.3.0

package/demo/index.html

@@ -22,7 +22,6 @@
     @media (min-width: 480px) { .demo-metrics b { font-size: 18px; } }
     .demo-head { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; }
     .demo-ask { margin-left: auto; max-width: 320px; padding: 8px 12px; border-radius: var(--gw-radius-card); background: var(--gw-bg-soft); color: var(--gw-ink); }
-    .demo-illus { margin-top: 12px; color: var(--gw-muted); font-size: 12px; }
     .demo-mt { margin-top: 16px; }
     .demo-specimen + .demo-specimen { margin-top: 48px; }
     .demo-specimen > h3 { margin-bottom: 16px; font-size: 20px; }
@@ -170,8 +169,8 @@
               <div class="demo-row"><span><small>Product page</small><b>The Radiance Serum</b></span><span class="gw-badge gw-badge--success">Live</span></div>
               <div class="demo-row"><span><small>Offer</small><b>Build a box, save 25%</b></span><span class="gw-badge">Draft</span></div>
             </div>
-            <p class="demo-illus">GemBoss-built demo pages for Vital Glow. Illustrative.</p>
           </div>
+          <p class="gw-window__caption">Illustrative data. Vital Glow is a GemBoss demo brand.</p>
         </div>
       </div>
     </section>
@@ -287,8 +286,8 @@
               <p><b>0.004</b>CLS</p>
               <p><b>0.05 s</b>TTFB</p>
             </div>
-            <p class="demo-illus">Measured on a live GemBoss store: mobile, simulated 4G, median of 8 Lighthouse runs, 10 Oct 2026.</p>
           </div>
+          <p class="gw-window__caption">Measured on a live GemBoss store: mobile, simulated 4G, median of 8 Lighthouse runs, 10 Oct 2026.</p>
         </div>
       </div>
     </section>
@@ -315,8 +314,8 @@
               <div class="demo-row"><span><b>What dermatologists check first</b><small>Solution aware · ingredient readers</small></span><span class="gw-badge">Drafted</span></div>
               <div class="demo-row"><span><b>A gift that looks after her</b><small>Product aware · gift buyers</small></span><span class="gw-badge">Drafted</span></div>
             </div>
-            <p class="demo-illus">GemBoss-built demo pages for Vital Glow. Illustrative.</p>
           </div>
+          <p class="gw-window__caption">Illustrative data. Vital Glow is a GemBoss demo brand.</p>
         </div>
       </div>
     </section>
@@ -339,8 +338,8 @@
               <li>Checked the render on desktop and phone</li>
             </ul>
             <div class="demo-head demo-mt"><span>The change waits on the canvas until you publish it.</span><span class="gw-badge gw-badge--accent">Draft</span></div>
-            <p class="demo-illus">Vital Glow is a GemBoss demo store. Illustrative.</p>
           </div>
+          <p class="gw-window__caption">Illustrative data. Vital Glow is a GemBoss demo store.</p>
         </div>
         <div class="gw-features gw-grid--3">
           <div class="gw-feature"><h3>Ask in plain words</h3><p>"Add a trust row under the buy box" is enough.</p></div>
@@ -383,12 +382,17 @@
           <p class="gw-label">Pricing</p>
           <h2 id="pricing-h"><span class="gw-dim">Every angle gets its own funnel.</span> Pay for the traffic you send it.</h2>
           <p class="gw-lead">Build as many funnels as you like on every plan, and try it free for 14 days.</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 –20%</button>
+          </div>
         </div>
         <div class="gw-pricing">
           <div class="gw-plan">
             <h3>Starter</h3>
             <p>Find your first winning angle.</p>
-            <p class="gw-plan__price">$49 <small>/ month</small></p>
+            <p class="gw-plan__price"><span data-gw-show="billing:monthly">$49</span><span data-gw-show="billing:yearly" hidden>$39</span> <small>/ month</small></p>
+            <p><span data-gw-show="billing:monthly">Billed monthly through Shopify</span><span data-gw-show="billing:yearly" hidden>Billed $470.40 a year through Shopify</span></p>
             <a class="gw-btn gw-btn--secondary gw-btn--block" href="https://admin.gemboss.ai/signup">Start 14-day free trial</a>
             <ul class="gw-list--check">
               <li>10,000 funnel sessions a month</li>
@@ -401,7 +405,8 @@
             <span class="gw-badge gw-badge--accent">Recommended for $10k–50k</span>
             <h3>Growth</h3>
             <p>Test new angles every week.</p>
-            <p class="gw-plan__price">$149 <small>/ month</small></p>
+            <p class="gw-plan__price"><span data-gw-show="billing:monthly">$149</span><span data-gw-show="billing:yearly" hidden>$119</span> <small>/ month</small></p>
+            <p><span data-gw-show="billing:monthly">Billed monthly through Shopify</span><span data-gw-show="billing:yearly" hidden>Billed $1,430.40 a year through Shopify</span></p>
             <a class="gw-btn gw-btn--block" href="https://admin.gemboss.ai/signup">Start 14-day free trial</a>
             <ul class="gw-list--check">
               <li>50,000 funnel sessions a month</li>
@@ -413,7 +418,8 @@
           <div class="gw-plan">
             <h3>Scale</h3>
             <p>Run many angles at once.</p>
-            <p class="gw-plan__price">$399 <small>/ month</small></p>
+            <p class="gw-plan__price"><span data-gw-show="billing:monthly">$399</span><span data-gw-show="billing:yearly" hidden>$319</span> <small>/ month</small></p>
+            <p><span data-gw-show="billing:monthly">Billed monthly through Shopify</span><span data-gw-show="billing:yearly" hidden>Billed $3,830.40 a year through Shopify</span></p>
             <a class="gw-btn gw-btn--secondary gw-btn--block" href="https://admin.gemboss.ai/signup">Start 14-day free trial</a>
             <ul class="gw-list--check">
               <li>200,000 funnel sessions a month</li>
@@ -450,7 +456,7 @@
               <tr><th scope="col">Plan</th><th scope="col">Starter</th><th scope="col">Growth</th><th scope="col">Scale</th><th scope="col">Enterprise</th></tr>
             </thead>
             <tbody>
-              <tr><th scope="row">Price a month</th><td>$49</td><td>$149</td><td>$399</td><td>from $999</td></tr>
+              <tr><th scope="row">Price a month</th><td><span data-gw-show="billing:monthly">$49</span><span data-gw-show="billing:yearly" hidden>$39</span></td><td><span data-gw-show="billing:monthly">$149</span><span data-gw-show="billing:yearly" hidden>$119</span></td><td><span data-gw-show="billing:monthly">$399</span><span data-gw-show="billing:yearly" hidden>$319</span></td><td>from $999</td></tr>
               <tr><th scope="row">Funnel sessions a month</th><td>10,000</td><td>50,000</td><td>200,000</td><td>Custom</td></tr>
               <tr><th scope="row">Funnels live at once</th><td>3</td><td>15</td><td>Unlimited</td><td>Unlimited</td></tr>
               <tr><th scope="row">A/B tests at once</th><td>2</td><td>5</td><td>20</td><td>Unlimited</td></tr>
@@ -480,6 +486,20 @@
             <a class="gw-btn gw-btn--sm" href="https://admin.gemboss.ai/signup">Start free</a>
             <a class="gw-btn gw-btn--lg" href="https://admin.gemboss.ai/signup">Start 14-day free trial</a>
           </div>
+          <div class="gw-actions demo-mt">
+            <button class="gw-btn" type="button" data-demo-busy>Send the request</button>
+            <button class="gw-btn gw-btn--secondary" type="button" data-demo-busy>Run the audit</button>
+          </div>
+          <p class="gw-note demo-mt">Press one: it waits two seconds, keeps its width and ignores a second press.</p>
+        </div>
+        <div class="demo-specimen">
+          <h3>Segmented control</h3>
+          <div class="gw-segmented" role="radiogroup" aria-label="How you want to work" data-gw-segmented="work">
+            <button type="button" role="radio" aria-checked="true" value="self">Run it yourself</button>
+            <button type="button" role="radio" aria-checked="false" value="managed">We run it for you</button>
+          </div>
+          <p class="demo-mt" data-gw-show="work:self">Self-serve plans from $49 a month. You build, test and promote the funnels.</p>
+          <p class="demo-mt" data-gw-show="work:managed" hidden>Managed from $690 a month. A dedicated operator builds and tests the funnels you approve.</p>
         </div>
         <div class="demo-specimen">
           <h3>Links</h3>
@@ -521,6 +541,51 @@
       </div>
     </section>
 
+    <!-- prose -->
+    <section class="gw-section" aria-labelledby="prose-h">
+      <div class="gw-wrap gw-wrap--narrow">
+        <div class="gw-section__head">
+          <p class="gw-label">Prose</p>
+          <h2 id="prose-h"><span class="gw-dim">Blog, docs and legal.</span> Plain HTML, easy to read.</h2>
+          <p class="gw-lead">A bare article inside .gw-prose: no class on its headings, lists, quote, code or table.</p>
+        </div>
+        <article class="gw-prose" aria-label="Why the kit looks the way it does">
+          <h2>One language for the site and the product</h2>
+          <p>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: <a href="https://gemboss.ai/">white canvas, ink actions, one accent</a>, hairlines, almost no shadow.</p>
+          <h3>Scales instead of eyeballing</h3>
+          <p>On gemboss.ai, before the scales, the four most common paddings were 9, 5, 12 and 15 pixels, and 1,291 of 2,076 spacing values belonged to no scale. The scales make "a bit more space" a choice between two real values:</p>
+          <ul>
+            <li>Spacing: 0 2 4 6 8 12 16 20 24 32 40 48 64 80 96 120 (px)</li>
+            <li>Type: 11 12 13 14 16 18 20 22 24 30, plus the two display sizes</li>
+            <li>Radii: 8 for actions, 12 for cards, 16 for panels, fully round for chips</li>
+          </ul>
+          <blockquote><p>A made-up number or a fake testimonial is found out, and then every other claim on the page is doubted.</p></blockquote>
+          <h3>Check before you hand it over</h3>
+          <p>Run <code>npx gemboss-website check</code> in the site; <code>--fix-list</code> prints the same findings as a to-do list. Then look at the page at 320px and 1366px.</p>
+          <figure>
+            <pre><code>npx gemboss-website check
+npx gemboss-website check --fix-list</code></pre>
+            <figcaption>The check exits 1 on an error, so it can run in the site's CI too.</figcaption>
+          </figure>
+          <h3>What a brand changes</h3>
+          <table>
+            <thead><tr><th scope="col">Variable</th><th scope="col">What it is</th><th scope="col">GemBoss</th></tr></thead>
+            <tbody>
+              <tr><th scope="row"><code>--gw-accent-light</code></th><td>Links, focus ring, active item, label square</td><td><code>#5661f5</code></td></tr>
+              <tr><th scope="row"><code>--gw-accent-strong-light</code></th><td>Accent as text, and on its own tint</td><td><code>#3a44de</code></td></tr>
+              <tr><th scope="row"><code>--gw-accent-soft-light</code></th><td>The tint: active chip, chosen option</td><td><code>#eef0fe</code></td></tr>
+              <tr><th scope="row"><code>--gw-on-accent-light</code></th><td>Text on a solid accent</td><td><code>#ffffff</code></td></tr>
+            </tbody>
+          </table>
+          <ol>
+            <li>Set the eight accent variables once, in a <code>:root</code> block after the kit.</li>
+            <li>Check the contrast of the accent as text on white and on the soft ground.</li>
+            <li>Look at the site in light and dark, at 320px and 1366px.</li>
+          </ol>
+        </article>
+      </div>
+    </section>
+
     <!-- faq -->
     <section class="gw-section" aria-labelledby="faq-h">
       <div class="gw-wrap gw-wrap--narrow">
@@ -625,5 +690,14 @@
   </footer>
 
   <script src="../js/website.js" defer></script>
+  <script>
+    // demo only: what a site's own code does while a request is on its way
+    document.addEventListener('click', function (e) {
+      var b = e.target.closest('[data-demo-busy]');
+      if (!b || b.getAttribute('aria-busy') === 'true') return;
+      b.setAttribute('aria-busy', 'true');
+      setTimeout(function () { b.removeAttribute('aria-busy'); }, 2000);
+    });
+  </script>
 </body>
 </html>

package/docs/components.md

@@ -8,6 +8,10 @@ Conventions: kit classes start with `gw-`, variants are `--name`, parts are `__n
 `is-*`. Never style a `.gw-*` class in your site's CSS: if the kit's version is wrong for you, that is a gap
 (`AGENTS.md` section 9).
 
+Radii and the button fill follow the site's brand profiles (`docs/theming.md`): below, "radius 8 / 12 / 16" is the
+default `tight` profile, and `soft` makes them 12 / 20 / 24; "ink fill" is the default `ink` action profile, and
+`data-gw-action="accent"` makes it the accent.
+
 Spacing between the children of text blocks is automatic: inside `.gw-section__head`, the hero, a split column,
 `.gw-cta`, `.gw-card`, `.gw-feature` and `.gw-plan`, each child is 16px below the previous one, a `.gw-actions` row
 32px, a `.gw-list--check` 24px. Do not add margins to fix rhythm; reorder or remove content instead.
@@ -86,7 +90,8 @@ Don't: more than three night bands on a page (the closing CTA does not count), o
 
 ### Buttons `.gw-btn`
 
-40px tall, radius 8, 14px/600, sentence case, ink fill. Variants: `--secondary` (hairline, transparent), `--ghost`
+40px tall, the action radius (8, 12 in `soft`), 14px/600, sentence case, the action colour as fill: ink, or the
+brand's accent with `--gw-on-accent` words under `data-gw-action="accent"` (one colour on the whole site). Variants: `--secondary` (hairline, transparent), `--ghost`
 (no frame), `--on-night` (light fill for a dark surface that is not a `.gw-band--night`), `--sm` (36px, with a 44px
 hit area), `--lg` (48px, 16px type), `--block` (full width). On touch screens every button is at least 44px tall and
 its label may wrap. Inside a night band the default button turns light by itself.
@@ -98,8 +103,30 @@ its label may wrap. Inside a night band the default button turns light by itself
 </div>
 ```
 
-Don't: an accent, gradient or wash fill; pill-shaped buttons; uppercase; two filled buttons side by side (one
-`.gw-btn` per view, the second is `--secondary` or a link); a `<div>` with a click handler instead of `<a>`/`<button>`.
+Pressed (`:active`): the fill one step stronger (the hover fill: the darker ink, or `--gw-accent-strong`), and
+nothing moves; `--secondary` takes the soft tint and
+`--ghost` the hairline tint.
+
+**Loading.** While a `<button>` waits on the network (a form sent, an audit started), set `aria-busy="true"` on it and
+remove it when the answer comes. The label stays in the markup, so the button keeps its width and its accessible name,
+but it is not painted: a 16px ring in the button's own ink turns in its place, and under `prefers-reduced-motion` it is
+a still ellipsis. `website.js` ignores presses on a busy button, by mouse or keyboard, so nothing is sent twice. When
+the wait ends, say what happened in words (a `.gw-note` or a `role="status"` line next to it).
+
+```html
+<button class="gw-btn" type="submit" aria-busy="true">Send the request</button>
+```
+
+```js
+button.setAttribute('aria-busy', 'true');   // the request leaves
+button.removeAttribute('aria-busy');        // the answer came
+```
+
+Don't: a fill of your own (the accent comes only from the action profile, set on `<html>`), a gradient or a wash; a
+raised or inset shadow; pill-shaped buttons; uppercase; two filled buttons side by side (one
+`.gw-btn` per view, the second is `--secondary` or a link); a `<div>` with a click handler instead of `<a>`/`<button>`;
+a loading class, your own spinner or `disabled` on a waiting button (`check` reports `busy-button`: `disabled` throws
+the keyboard focus to the top of the page); a "Loading…" label in place of the real one.
 
 ### Chips `.gw-chip`
 
@@ -112,6 +139,37 @@ hairline on accent-soft). As a `<button>`, `<a>` or `<label>` it is 44px tall on
 
 Don't: use a chip as the page's action; square it; more than about six in a row.
 
+### Segmented control `.gw-segmented`
+
+One choice out of two to four, shown as one group: Monthly / Yearly on a pricing page, Run it yourself / We run it for
+you. It is a radio group: one Tab stop, the arrow keys (and Home, End) move and choose, a click or Space chooses. The
+look is the dashboard's (`@gemboss/ui` `.ui-seg`): one hairline group, the action radius, a hairline between options, the chosen
+option on the accent tint, so it follows a brand's accent. 40px tall; on touch screens every option is at least 44px
+and its label may wrap. `--block` stretches it to the row and shares the width equally.
+
+What an option shows: any element with `data-gw-show="group:value"` (the group's `data-gw-segmented` name, the option's
+`value`) is hidden unless that option is chosen. Put every version in the markup and `hidden` on all but the chosen
+one's: without the script the page reads with the default choice, with it `website.js` swaps them. An element may
+belong to several options (`data-gw-show="billing:monthly billing:quarterly"`). A choice also fires `gw:segmented` on
+the group (it bubbles; `detail` is `{ name, value }`) for the page's own script, for example to move a "Recommended"
+badge.
+
+```html
+<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 –20%</button>
+</div>
+<p class="gw-plan__price"><span data-gw-show="billing:monthly">$49</span><span data-gw-show="billing:yearly" hidden>$39</span> <small>/ month</small></p>
+```
+
+Labels: one to three words, as short in every language as in English (gemboss.ai: "Tháng / Năm –20%", "按月 / 按年
+–20%"). The chosen label does not change weight, so nothing moves. A discount in a label is the one billing gives.
+
+Don't: links dressed as a segmented control (to go to another page, use links); panels of one page that the reader
+should be able to see side by side; more than four options (use chips); a choice that changes nothing visible; two
+groups with the same name on one page; the old `role="group"` with `aria-pressed` buttons (`check` reports
+`segmented-markup`).
+
 ### Badges `.gw-badge`
 
 Small status, a pill, 12px. Variants: `--accent` (a test, the recommended plan), `--success` and `--warning` (state:
@@ -125,7 +183,7 @@ Don't: make a badge clickable; write a sentence in it; use success or warning fo
 
 ### Cards `.gw-card`
 
-A white box with a 1px hairline, radius 12, the resting shadow `--gw-shadow` (as the dashboard's cards), 24px padding
+A white box with a 1px hairline, the card radius (12, 20 in `soft`), the resting shadow `--gw-shadow` (as the dashboard's cards), 24px padding
 (32px from 768px). It sits: no hover lift. `--soft` is a tint and has no shadow.
 Variants: `--soft` (on `--gw-bg-soft`), `--link` (the whole card is one `<a>`; the border darkens on hover).
 
@@ -137,22 +195,32 @@ Variants: `--soft` (on `--gw-bg-soft`), `--link` (the whole card is one `<a>`; t
 </a>
 ```
 
-Don't: put links or buttons inside a `--link` card (one card, one destination); a bigger shadow or a hover lift; radius
-other than 12 (16 is for large panels: plans, quote).
+Don't: put links or buttons inside a `--link` card (one card, one destination); a bigger shadow or a hover lift; a
+radius of your own (cards take the card radius, plans and the quote the panel radius, both from the profile).
 
 ### Window `.gw-window`
 
-A framed screen: `__bar` (three dots and where the screen lives) and `__body` (16px padding, none around a single
-`<img>`). Use it around real product screenshots, or around a drawn mock-up built in the site's CSS with the tokens.
+A framed screen: `__bar` (three dots and where the screen lives), `__body` (16px padding, none around a single
+`<img>`) and `__caption`. Use it around real product screenshots, or around a drawn mock-up built in the site's CSS with
+the tokens.
+
+`__caption` says what the numbers in the window are: 12px, muted, at the end of the window, the last child after
+`__body` (a `<figcaption>` when the window is a `<figure>`). Under a drawn mock-up whose numbers are made up it says
+**"Illustrative data."**, in exactly these words: vi "Dữ liệu minh hoạ.", zh "示意数据。". Add a second sentence only when
+the mock-up shows a demo brand ("Vital Glow is a GemBoss demo brand."). Under real numbers it names their source
+("Measured on a live GemBoss store, 10 Oct 2026."). `check` warns about a drawn window with numbers and no caption
+(`illustrative-caption`).
 
 ```html
 <div class="gw-window">
   <div class="gw-window__bar">Funnels / Radiance Serum</div>
   <div class="gw-window__body"><img src="/img/funnels.webp" alt="The funnel list with four steps" width="1200" height="750"></div>
+  <p class="gw-window__caption">Illustrative data. Vital Glow is a GemBoss demo brand.</p>
 </div>
 ```
 
-Don't: put interactive controls inside a mock-up; show made-up numbers without "Illustrative" under them.
+Don't: put interactive controls inside a mock-up; show made-up numbers without the caption; write the caption in
+other words ("Sample", "Demo numbers") or leave it in English on a translated page.
 
 ### Icon `.gw-icon`
 
@@ -177,7 +245,7 @@ Don't: more than five or six items; full paragraphs as items.
 
 ### Table `.gw-table`
 
-A wrapper around a plain `<table>`: hairline, radius 12, and it scrolls inside its own box when the table is wider
+A wrapper around a plain `<table>`: hairline, the card radius, and it scrolls inside its own box when the table is wider
 than the screen. `--compare`: centred values, a 640px minimum width and a sticky first column, for plan comparisons.
 Give the wrapper `role="region"`, an accessible name and `tabindex="0"` so keyboard users can scroll it.
 
@@ -204,7 +272,7 @@ Native `<details class="gw-faq__item">` with a `<summary>`, no script. The + tur
 
 Don't: hide content a reader needs to decide (prices, terms) only inside a closed answer; more than eight questions.
 
-### Not in 0.1.0
+### Not in the kit yet
 
 `.gw-tabs` does not exist yet. If a page needs tabs, build a stopgap (`kitgap-tabs`) and report the gap.
 
@@ -214,10 +282,11 @@ Don't: hide content a reader needs to decide (prices, terms) only inside a close
 |---|---|
 | `.gw-announce` | optional one-sentence bar above the header, with one link |
 | `.gw-header` (`data-gw-header`) | the sticky, flat 64px bar with one hairline; `.is-scrolled` darkens the hairline |
+| `.gw-header--float` | with `.gw-header`, a brand's header profile: from 1080px the same bar as an inset card (panel radius, the surface at 85% over a blur, one hairline, the raised shadow, 16px from the top); the flat bar below 1080px; solid under `prefers-reduced-transparency` |
 | `.gw-header__bar` | the row inside (`.gw-wrap gw-header__bar`) |
 | `.gw-brand`, `__mark`, `__name` | logo (26px) and name, linking home |
 | `.gw-nav`, `__list`, `__item`, `__trigger`, `__link` | the desktop nav (from 1080px); `__trigger` opens a mega panel, `__link` is a plain link; `aria-current="page"` underlines it in the accent |
-| `.gw-mega`, `__grid`, `__col`, `__heading`, `__link`, `__icon`, `__feature` | a floating card centred under the bar (radius 20, raised shadow, as on gemboss.ai): columns of links with an icon and one line each, and at most one feature card |
+| `.gw-mega`, `__grid`, `__col`, `__heading`, `__link`, `__icon`, `__feature` | a floating card centred under the bar (the popover radius: 20, 24 in `soft`; raised shadow, as on gemboss.ai): columns of links with an icon and one line each, and at most one feature card |
 | `.gw-header__actions` | theme toggle, Sign in, Book a demo, Start free, menu button |
 | `.gw-header__signin` | with `.gw-nav__link`: hidden below 1080px (it moves into the mobile menu) |
 | `.gw-theme-toggle` | icon button (`data-gw-theme-toggle`), 40px, 44px on touch |
@@ -231,7 +300,8 @@ Don't: hide content a reader needs to decide (prices, terms) only inside a close
 Header buttons: the secondary one shows from 768px, the primary one from 480px; below that they live in the mobile
 menu. Full markup: `templates/header.html`.
 
-Don't: a floating, rounded or blurred header; more than five top-level items; a second filled button in the bar; a
+Don't: a floating, rounded or blurred header of your own (the one floating header is `.gw-header--float`, chosen
+for the whole site); more than five top-level items; a second filled button in the bar; a
 hero pulled up under the header.
 
 ## Footer
@@ -282,6 +352,48 @@ One snippet per section, with its limits in a comment, is in `templates/sections
 Don't: a number without a source; logos or quotes you do not have permission for; a filled button on every plan
 (only the featured one); a hero without a real first line of content above the fold on a 390px phone.
 
+## Prose
+
+| class | for |
+|---|---|
+| `.gw-prose` | a page that is read rather than scanned (a blog post, a docs page, terms, privacy): the article's own HTML inside it, 18px body, 68ch measure |
+| `.gw-prose--sm` | the same at a 16px body, for docs and legal pages |
+
+The HTML a CMS or a markdown renderer writes needs no classes. Inside `.gw-prose`:
+
+| element | look |
+|---|---|
+| `h1` | the article title, at the section-headline size (`--gw-display-h2`) |
+| `h2`, `h3`, `h4` | 30, 24, 20px (24, 20, 18px in `--sm`), weight 650; 48, 40, 32px of air above, 12px below |
+| `p`, `ul`, `ol` | 20px between blocks (16px in `--sm`); bullets and numbers with muted markers, 8px between items |
+| `blockquote` | a 3px rule on its left, muted words (the dashboard's reader quote) |
+| `code` | a tint chip in `--gw-font-mono` (16px, 14px in `--sm`) that wraps on a phone; in a table it stays whole |
+| `pre` | a soft box, 14px mono, that scrolls sideways inside itself |
+| `table` | as a direct child: the `.gw-table` look, and it scrolls inside its own box when it is wider than the column |
+| `img`, `figure`, `figcaption` | images take the card radius; a caption 14px muted, 12px under its figure |
+| `hr`, `a` | a hairline with 32px of air; links in the accent, underlined |
+
+Kit components inside the prose keep their own look (`.gw-table`, `.gw-window`, `.gw-list--check`, `.gw-quote`,
+`.gw-btn`). Prefer the `.gw-table` wrapper (`role="region"`, a name, `tabindex="0"`) when you write the markup: a
+keyboard can scroll it.
+
+```html
+<section class="gw-section">
+  <div class="gw-wrap gw-wrap--narrow">
+    <article class="gw-prose">
+      <h1>Why the kit looks the way it does</h1>
+      <p>Each rule came from measuring real pages, not from taste alone.</p>
+      <h2>One language for the site and the product</h2>
+      <p>A visitor crosses from the website into the product in one click. …</p>
+      <ul><li>…</li></ul>
+    </article>
+  </div>
+</section>
+```
+
+Don't: marketing sections inside the prose (end the article, then the section); headings chosen for their size (keep
+them in order); a page without `.gw-prose` that styles its articles in site CSS (that was the stopgap of gap #46).
+
 ## Motion
 
 | class | for |
@@ -291,6 +403,17 @@ Don't: a number without a source; logos or quotes you do not have permission for
 Put it on a block (a grid, a list, a window), not on each card in a grid. Don't use it on the hero or anything in
 the first screen, and don't animate anything but `transform` and `opacity`.
 
+## Additions to the markup contract in 0.3.0
+
+The brand profiles: `data-gw-action="ink|accent"` and `data-gw-radius="tight|soft"` on `<html>`, and
+`.gw-header--float` on the header (`docs/theming.md`). Tokens: `--gw-radius-popover` (the mega menu), `--gw-radius-24`,
+`--gw-header-gap`, `--gw-header-surface`, `--gw-header-blur`. No markup of 0.2.0 changes.
+
+## Additions to the markup contract in 0.2.0
+
+The button states (`:active`, `[aria-busy="true"]`), `.gw-segmented` (+ `--block`) with its `data-gw-segmented` /
+`data-gw-show` hooks, `.gw-window__caption` and `.gw-prose` (+ `--sm`). Two tokens: `--gw-font-mono` and `--gw-spin-ms`.
+
 ## Additions to the markup contract in 0.1.0
 
 The contract names the classes the script relies on; these CSS-only helpers were added with it: `.gw-page`

package/docs/markup-contract.md

@@ -12,7 +12,9 @@ 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 -->
@@ -25,7 +27,7 @@ BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
 ## 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">
@@ -73,27 +75,69 @@ Script behaviour:
   2.5s, or if IntersectionObserver is missing, all 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).
+  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` whose `href`
   pathname equals `location.pathname` (when the markup did not already).
 
+## 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)
+
+```html
+<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 –20%</button>
+</div>
+…
+<span data-gw-show="billing:monthly">$49</span><span data-gw-show="billing:yearly" hidden>$39</span>
+```
+
+- The group: `.gw-segmented` (+ `--block`), `role="radiogroup"`, a name (`aria-label` or `aria-labelledby`) and
+  `data-gw-segmented="<name>"`, unique on the page. Two to four `<button type="button" role="radio">` children, each
+  with a `value` and `aria-checked`, exactly one `"true"`: the choice the page shows without the script.
+- Content: any element with `data-gw-show="<name>:<value>"` (several tokens, space-separated, for several options) is
+  shown only while that option is chosen. The markup sets `hidden` on every version but the default's.
+- Script behaviour: on load the checked option (or the first) is chosen again, which corrects `hidden` on the content
+  and sets the roving `tabindex` (`0` on the chosen option, `-1` on the others: one Tab stop). A click chooses;
+  ArrowRight / ArrowDown and ArrowLeft / ArrowUp move to the next and previous option, wrapping, Home and End to the
+  first and last, and the moved-to option is chosen and focused (the radio-group pattern). Each choice made by the
+  reader fires `gw:segmented` on the group (`bubbles: true`, `detail: { name, value }`); loading does not.
+
+## Busy button (0.2.0)
+
+- Markup: `aria-busy="true"` on a `<button class="gw-btn">` while it waits; the page's own script sets and removes it.
+  No `disabled` at the same time, no loading class, no spinner element: the CSS draws the ring (`::before`; `--sm`
+  keeps `::after` for its hit area).
+- Script behaviour: one click listener on the document, in the capture phase, cancels a click on a
+  `.gw-btn[aria-busy="true"]` (or inside one) before the page's handlers see it: `preventDefault` and
+  `stopPropagation`. A form is not submitted twice, by mouse, Enter or Space, and the button keeps the focus.
+
 ## Components (CSS only)
 
 | class | what |
 |---|---|
-| `.gw-btn` (+ `--secondary`, `--ghost`, `--on-night`, `--sm`, `--lg`, `--block`) | actions; rectangle 8px, ink fill by default |
+| `.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-window` (+ `__bar`, `__body`) | a framed screenshot/mock-up, like a browser or app window |
+| `.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 |
 | `.gw-table` (+ `--compare`) | data / comparison table; scrolls inside its box on phones |
 | `.gw-faq` (`<details class="gw-faq__item"><summary>`) | FAQ accordion with no script |
-| `.gw-tabs` (`role="tablist"`) | NOT in 0.1.0 (a reported gap would add it) |
+| `.gw-prose` (+ `--sm`) | long-form reading: an article's own HTML, no classes inside |
+| `.gw-tabs` (`role="tablist"`) | NOT in the kit yet (a reported gap would add it) |
 
 ## Sections
 

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