@gemboss/website-ui 0.0.0-stage → 0.2.0

package/docs/markup-contract.md

@@ -0,0 +1,148 @@
+# Markup contract (CSS ↔ JS ↔ templates)
+
+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.
+
+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`.
+
+## Page
+
+```html
+<html lang="en" data-theme?="light|dark">     <!-- absent = follow the system; the toggle sets it -->
+<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>
+```
+
+## Header
+
+```html
+<header class="gw-header" data-gw-header>
+  <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">
+      <ul class="gw-nav__list">
+        <li class="gw-nav__item">
+          <button class="gw-nav__trigger" type="button" aria-expanded="false" aria-controls="gw-mega-product" data-gw-mega="gw-mega-product">Product</button>
+          <div class="gw-mega" id="gw-mega-product" hidden>
+            <div class="gw-wrap gw-mega__grid">
+              <div class="gw-mega__col"><p class="gw-mega__heading">Build</p>
+                <a class="gw-mega__link" href="…"><span class="gw-mega__icon" aria-hidden="true">svg</span><span><b>Title</b><i>One line</i></span></a>
+              </div>
+              <a class="gw-mega__feature" href="…">…</a>   <!-- optional card on the right -->
+            </div>
+          </div>
+        </li>
+        <li class="gw-nav__item"><a class="gw-nav__link" href="/pricing" aria-current?="page">Pricing</a></li>
+      </ul>
+    </nav>
+    <div class="gw-header__actions">
+      <button class="gw-theme-toggle" type="button" data-gw-theme-toggle aria-label="Switch to dark theme">svg</button>
+      <a class="gw-nav__link gw-header__signin" href="…">Sign in</a>
+      <a class="gw-btn gw-btn--secondary gw-btn--sm" href="…">Book a demo</a>
+      <a class="gw-btn gw-btn--sm" href="…">Start free</a>
+      <button class="gw-menu-toggle" type="button" aria-expanded="false" aria-controls="gw-mobile-menu" data-gw-menu-toggle aria-label="Open menu">svg</button>
+    </div>
+  </div>
+  <div class="gw-mobile-menu" id="gw-mobile-menu" hidden> …the same links as lists, and the actions… </div>
+</header>
+```
+
+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.
+- **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.
+- **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.
+- **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).
+
+## 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; `: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`, `__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-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
+
+| class | what |
+|---|---|
+| `.gw-section` (+ `--soft`, `--tight`) | vertical rhythm; `--soft` on `--gw-bg-soft` |
+| `.gw-band--night` | a dark band (max three per page plus the closing CTA, never adjacent) |
+| `.gw-section__head` (+ `--center`) | label + h2 + one or two lines, max 660px |
+| `.gw-hero` (+ `__wash`, `--center`, `--compact`) | first screen; `__wash` is the soft colour wash behind it |
+| `.gw-logos` | proof strip of customer or partner logos (real ones only) |
+| `.gw-stats` (`__item`, `__value`, `__label`) | 3–4 facts in a row, each with its source |
+| `.gw-features` (`.gw-grid--3` of `.gw-feature`) | icon, title, one or two lines |
+| `.gw-split` (+ `--reverse`) | text beside a figure; stacks on phones |
+| `.gw-showcase` | night band with a large screen and two or three points |
+| `.gw-steps` (`<ol>`) | numbered steps, how it works |
+| `.gw-quote` | one real testimonial with name, role, company |
+| `.gw-pricing` (`.gw-plan`, `--featured`) | plan cards; the featured one has a hairline in the accent, not a fill |
+| `.gw-cta` | closing call to action band |
+| `.gw-footer` (`__grid`, `__col`, `__heading`, `__bottom`) | footer columns + bottom row |

package/docs/philosophy.md

@@ -0,0 +1,69 @@
+# Why the kit looks the way it does
+
+`AGENTS.md` says what to do. This page says why, so that when a case is not covered you can decide in the same
+spirit. Each rule came from measuring real pages, not from taste alone.
+
+## One language for the site and the product
+
+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.
+
+## The thing you click is ink
+
+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.
+
+## 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.
+
+## 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.
+
+## Scales instead of eyeballing
+
+On gemboss.ai, before the scales, the four most common paddings were 9, 5, 12 and 15 pixels: spacing tuned by eye,
+one element at a time. 1,291 of 2,076 spacing values belonged to no scale. Nobody sees one 15px; everybody feels a
+page made of hundreds of them. The scales (4px base, the type steps) make "a bit more space" a choice between two
+real values.
+
+## Sentence case and a quiet label
+
+Uppercase tracked labels ("FEATURES") shout and say nothing. A label in sentence case, muted, led by a small accent
+square, tells the reader where they are and lets the headline do the talking. The house headline shape, a muted
+first sentence and an ink second one, gives every section the same rhythm: context, then the point.
+
+## One idea per section
+
+Visitors scan. A section that makes one point, with one action, survives scanning; a section with three ideas loses
+all three. Fewer, clearer sections beat a long page of everything.
+
+## Real words, or a visible gap
+
+A made-up number or a fake testimonial is found out, and then every other claim on the page is doubted. A visible
+`[PRICE]` is honest and gets filled; an invented one ships.
+
+## Motion that does not cost
+
+Only `transform` and `opacity` move, because they do not re-layout the page and stay at 60 fps on a cheap phone.
+Everything stops for people who ask the system for reduced motion. Motion explains (a panel opens from its
+trigger, a section arrives as you reach it); it never decorates.
+
+## Phones first in the checking, not just in the CSS
+
+Most visitors from ads arrive on a phone. A label that fits at 1366px and overflows at 320px is a broken page for
+most of them. That is why the kit is checked at 320, 390, 768 and 1366px, and why translated labels must not grow.
+
+## When the kit is not enough
+
+A kit that people work around stops being a kit. The workaround is allowed, in the site, with the tokens, under a
+`kitgap-` name, and it is reported. The next version of the kit gets the real thing, every site gets it, and the
+workaround is deleted. That loop, not the first release, is what keeps all GemCommerce websites one family.

package/docs/theming.md

@@ -0,0 +1,96 @@
+# 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.
+
+Working example: `demo/theme-example.html` (the demo's hero, buttons and cards with a GemPages-style blue).
+
+## What you may override
+
+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, 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-accent-dark` | the accent in dark mode **and inside night bands** | `#7c84ff` |
+| `--gw-accent-strong-dark` | its hover / strong form | `#a3a9ff` |
+| `--gw-accent-soft-dark` | its tint | `#1f2140` |
+| `--gw-on-accent-dark` | text 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
+(the light default, dark from the system setting, dark from the toggle, light from the toggle) and in every night
+band. Override the eight primitives once and all of them follow. Overriding `--gw-accent` directly works only until
+someone presses the theme toggle.
+
+The logo and the favicon are files, not variables: the `<img class="gw-brand__mark">` (26×26, SVG preferred, with
+`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.
+
+## 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.
+- **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.
+- **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.
+
+## A full example
+
+```css
+/* site.css, linked after website.css. The whole theme of a GemPages-style site. */
+: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;
+  --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;
+  --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
+<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>
+```
+
+## Check the contrast before you ship
+
+The accent family is read as text: the kit draws links, step numbers, active menu items and badge words in
+`--gw-accent-strong`, and the label square, focus ring, check marks and the featured plan's hairline in `--gw-accent`.
+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, 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.
+
+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.
+
+Then open the site in light and dark (the toggle in the header), at 320px and at 1366px, and look at a night band.

package/js/website.js

@@ -0,0 +1,186 @@
+/*! @gemboss/website-ui website.js | spec: docs/markup-contract.md | load with defer */
+(function () {
+  'use strict';
+  if (window.gwWebsite) return;
+  window.gwWebsite = { version: '0.2.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); }
+  function all(sel, ctx) { return [].slice.call((ctx || doc).querySelectorAll(sel)); }
+  function on(el, type, fn, opt) { el.addEventListener(type, fn, opt || false); }
+  function attr(el, name, dflt) { return el.getAttribute(name) || dflt; }
+  function esc(e) { return e.key === 'Escape'; }
+  function link(e) { return e.target.closest('a[href]'); }
+
+  // Mega menu. Opened by hover then clicked, a panel stays open: the click meant "open".
+  function mega() {
+    var fine = mq('(hover: hover) and (pointer: fine)'), open = null, timer = 0;
+    var menus = all('[data-gw-mega]').map(function (t) {
+      var p = doc.getElementById(attr(t, 'data-gw-mega', attr(t, 'aria-controls', '')));
+      return p && { t: t, p: p, item: t.closest('.gw-nav__item') || t.parentNode };
+    }).filter(Boolean);
+    if (!menus.length) return;
+    function set(m, show, mode) {
+      m.p.hidden = !show;
+      m.t.setAttribute('aria-expanded', String(show));
+      m.item.classList.toggle('is-open', show);
+      m.mode = mode;
+      open = show ? m : open === m ? null : open;
+    }
+    function show(m, mode) {
+      clearTimeout(timer);
+      if (open === m) { if (mode === 'click') m.mode = mode; return; }
+      if (open) set(open, false);
+      set(m, true, mode);
+    }
+    function hide(focus) {
+      var m = open;
+      clearTimeout(timer);
+      if (!m) return;
+      set(m, false);
+      if (focus === true) m.t.focus();
+    }
+    function inside(m, el) { return !!el && (m.item.contains(el) || m.p.contains(el)); }
+    menus.forEach(function (m) {
+      on(m.t, 'click', function () { if (open === m && m.mode !== 'hover') hide(); else show(m, 'click'); });
+      (m.item.contains(m.p) ? [m.item] : [m.item, m.p]).forEach(function (el) {
+        on(el, 'mouseenter', function () {
+          if (fine.matches) { clearTimeout(timer); if (open !== m) timer = setTimeout(function () { show(m, 'hover'); }, 80); }
+        });
+        on(el, 'mouseleave', function () {
+          if (fine.matches) { clearTimeout(timer); if (open === m && m.mode === 'hover') timer = setTimeout(hide, 160); }
+        });
+      });
+      on(m.item, 'focusout', function (e) { if (open === m && e.relatedTarget && !inside(m, e.relatedTarget)) hide(); });
+      on(m.p, 'click', function (e) { if (link(e)) hide(); });
+    });
+    on(doc, 'click', function (e) { if (open && !inside(open, e.target)) hide(); });
+    on(doc, 'keydown', function (e) { if (open && esc(e)) hide(inside(open, doc.activeElement) || open.mode === 'click'); });
+  }
+
+  // Mobile menu. Labels: data-gw-label-open/-close, else the markup's aria-label, else English.
+  function mobile() {
+    var btn = doc.querySelector('[data-gw-menu-toggle]');
+    var menu = btn && doc.getElementById(attr(btn, 'aria-controls', 'gw-mobile-menu'));
+    if (!menu) return;
+    var label = [attr(btn, 'data-gw-label-open', attr(btn, 'aria-label', 'Open menu')), attr(btn, 'data-gw-label-close', 'Close menu')];
+    var wide = mq('(min-width: 1080px)');
+    function isOpen() { return !menu.hidden; }
+    function set(o, focus) {
+      menu.hidden = !o;
+      btn.setAttribute('aria-expanded', String(o));
+      btn.setAttribute('aria-label', label[+o]);
+      root.classList.toggle('is-menu-open', o);
+      if (focus) btn.focus();
+    }
+    on(btn, 'click', function () { set(!isOpen()); });
+    on(doc, 'keydown', function (e) { if (esc(e) && isOpen()) set(false, true); });
+    on(menu, 'click', function (e) { if (link(e)) set(false); }); // same-page anchors do not reload
+    watch(wide, function () { if (wide.matches && isOpen()) set(false); });
+    on(window, 'pageshow', function (e) { if (e.persisted && isOpen()) set(false); });
+  }
+
+  // Theme toggle. Labels: data-gw-label-dark/-light, else the markup's aria-label, else English.
+  function theme() {
+    var sys = mq('(prefers-color-scheme: dark)'), stored = null;
+    try { stored = localStorage.getItem('gw-theme'); } catch (e) { /* blocked */ }
+    if (!root.hasAttribute('data-theme') && /^(light|dark)$/.test(stored)) root.setAttribute('data-theme', stored);
+    var btns = all('[data-gw-theme-toggle]'), labels = btns.map(function (b) {
+      return [attr(b, 'data-gw-label-dark', attr(b, 'aria-label', 'Switch to dark theme')), attr(b, 'data-gw-label-light', 'Switch to light theme')];
+    });
+    function dark() { var t = root.getAttribute('data-theme'); return t ? t === 'dark' : sys.matches; }
+    function relabel() { btns.forEach(function (b, i) { b.setAttribute('aria-label', labels[i][+dark()]); }); }
+    btns.forEach(function (b) {
+      on(b, 'click', function () {
+        var next = dark() ? 'light' : 'dark';
+        root.setAttribute('data-theme', next);
+        try { localStorage.setItem('gw-theme', next); } catch (e) { /* blocked */ }
+        relabel();
+      });
+    });
+    watch(sys, relabel);
+    relabel();
+  }
+
+  // Reveal at 15% visible, once. Failsafe: all shown after 2.5s, or at once without IntersectionObserver.
+  function reveal() {
+    var els = all('.gw-reveal'), io = null;
+    function showAll() { els.forEach(function (el) { el.classList.add('is-in'); }); if (io) io.disconnect(); }
+    if (!els.length) return;
+    if (!window.IntersectionObserver || mq('(prefers-reduced-motion: reduce)').matches) return showAll();
+    io = new IntersectionObserver(function (list) {
+      list.forEach(function (en) { if (en.isIntersecting) { en.target.classList.add('is-in'); io.unobserve(en.target); } });
+    }, { threshold: 0.15 });
+    els.forEach(function (el) { io.observe(el); });
+    setTimeout(showAll, 2500);
+  }
+
+  // Header: .is-scrolled past 8px, read once per frame.
+  function header() {
+    var h = doc.querySelector('[data-gw-header]'), state = false, queued = false;
+    if (!h) return;
+    function update() {
+      var s = window.scrollY > 8;
+      queued = false;
+      if (s !== state) h.classList.toggle('is-scrolled', (state = s));
+    }
+    on(window, 'scroll', function () { if (!queued) { queued = true; requestAnimationFrame(update); } }, { passive: true });
+    update();
+  }
+
+  // aria-current="page" on nav links to this path, unless the markup marked one.
+  function current() {
+    var menu = doc.getElementById('gw-mobile-menu');
+    var links = all('.gw-nav__link[href], .gw-mega__link[href]').concat(menu ? all('a[href]', menu) : []);
+    function norm(p) { return p.replace(/\/index\.html?$/, '/').replace(/\.html?$/, '').replace(/\/+$/, '') || '/'; }
+    if (links.some(function (a) { return a.hasAttribute('aria-current'); })) return;
+    links.forEach(function (a) {
+      if (a.classList.contains('gw-btn') || a.hash || a.host !== location.host) return;
+      if (norm(a.pathname) === norm(location.pathname)) a.setAttribute('aria-current', 'page');
+    });
+  }
+
+  // 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, segmented, busy].forEach(function (f) {
+      try { f(); } catch (e) { console.error('[gw-website]', e); }
+    });
+  }
+  if (doc.readyState === 'loading') on(doc, 'DOMContentLoaded', init); else init();
+})();

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@gemboss/website-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+  "files": [
+    "website.css",
+    "website.min.css",
+    "css/",
+    "js/",
+    "system.json",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "README.md",
+    "templates/",
+    "demo/",
+    "docs/",
+    "bin/",
+    "skill/"
+  ],
+  "exports": {
+    "./website.css": "./website.css",
+    "./website.min.css": "./website.min.css",
+    "./website.js": "./js/website.js",
+    "./system.json": "./system.json",
+    "./css/*": "./css/*",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "gemboss-website": "bin/gemboss-website.mjs"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node test/run.mjs",
+    "prepack": "node scripts/build.mjs --check && node test/run.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chriskoh26/gemboss-www.git",
+    "directory": "packages/website-ui"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gemboss": {
+    "gapRepo": "chriskoh26/gemboss-www"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: gemboss-website-ui
+description: Use when building or changing pages of a website that uses @gemboss/website-ui (the GemCommerce website kit) - a new page, adding or changing a section, header, footer or copy, theming the kit for a brand, or reviewing a page before hand-over. Covers the kit's rules, its templates, the check, reporting a missing kit part (gap) and upgrading the kit.
+---
+<!-- managed by @gemboss/website-ui init -->
+
+# Website pages with @gemboss/website-ui
+
+The kit lives in `node_modules/@gemboss/website-ui/` (below: `KIT/`). The person asking is often not a designer;
+the kit and its rules are how the page ends up looking designed. Compose from the kit, do not invent.
+
+## Every time
+
+1. **Read `KIT/AGENTS.md`** completely before the first page change of the session. It wins over habit and over
+   generic design advice.
+2. **See what exists**: `KIT/demo/index.html` (every component) and `KIT/docs/components.md` (every class).
+3. **Build**:
+   - New page: copy `KIT/templates/page.html`, then add sections from `KIT/templates/sections/` in the order the page
+     needs. Fill the words, delete what you did not use.
+   - 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`).
+4. **Words**: real facts only. A missing price, number, name or date becomes a visible `[PLACEHOLDER]` and a
+   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.
+
+## When the kit is missing something
+
+1. Make sure it is really missing (demo, components doc, two existing parts together, a variant).
+2. A one-off illustration is a page thing: site CSS with tokens, stop.
+3. A reusable thing is a gap: build a stopgap in `kit-gaps.css` (classes `kitgap-…`, tokens only, a comment naming
+   the gap), then report it:
+
+   ```sh
+   npx gemboss-website gap --title "…" --kind component --need "…" --why "…" \
+     --page https://… --stopgap kit-gaps.css
+   ```
+
+   It files a GitHub issue (gh) or writes `kit-gaps/<slug>.md` to send. Put the printed `/* gap #N */` comment
+   above the stopgap. Tell the person what you reported.
+
+## Upgrading the kit
+
+`npx gemboss-website upgrade` shows what changed, the gaps the new version closes and the install command. Upgrade,
+replace the listed `kitgap-` stopgaps with the kit's classes, run `npx gemboss-website init` (refreshes this skill)
+and the check, and look at the pages again.