@gemboss/website-ui 0.3.0 → 0.5.0

package/js/website.mjs

@@ -0,0 +1,342 @@
+/*! @gemboss/website-ui website.mjs | spec: docs/markup-contract.md */
+// The ESM entry: import { init, destroy, version } from '@gemboss/website-ui/website.mjs'. Importing it does nothing;
+// call init() once the markup is in the page, and again after every route change or insert. No dependencies.
+//
+// js/website.js, the classic script, is GENERATED from this file by scripts/build.mjs (this code in an IIFE, without
+// the export line and the // comments, plus auto-init): edit this file, then run the build. Keep comments on lines of
+// their own, so the build can leave them out.
+
+var version = '0.5.0';
+var api = { version: version, init: init, destroy: destroy };
+// Page state. Set up by the first init(), never at import: a server can import this file.
+var doc, root, mine, fine, sys, wide, live = [], megaOpen = null, megaTimer = 0, queued = false;
+var READY = 'data-gw-ready';
+
+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)); }
+// Like all(), and ctx itself when it matches: init(header) wires the header it is given.
+function within(sel, ctx) { var l = all(sel, ctx); if (ctx.matches && ctx.matches(sel)) l.unshift(ctx); return l; }
+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]'); }
+function emit(el, type, detail) { if (window.CustomEvent) el.dispatchEvent(new CustomEvent(type, { bubbles: true, detail: detail })); }
+
+// Wiring. Each element under ctx that matches sel is wired once as `kind`: fn(el, on) adds the element's listeners
+// with the `on` it is given (so destroy can remove them) and returns a record, or nothing when the element cannot be
+// wired yet (the next init tries again). Records live in `live`. data-gw-ready lists the kinds wired on an element;
+// the record, not the attribute, decides, so markup copied from a live page, attribute and all, is still wired.
+// wire() does the same for a list of elements a selector cannot name (the tables straight inside a .gw-prose).
+function each(ctx, sel, kind, fn) { wire(within(sel, ctx), kind, fn); }
+function wire(els, kind, fn) {
+  els.forEach(function (el) {
+    if (live.some(function (r) { return r.el === el && r.kind === kind; })) return;
+    var offs = [], r = fn(el, function (t, type, f, opt) {
+      on(t, type, f, opt);
+      offs.push(function () { t.removeEventListener(type, f, opt || false); });
+    });
+    if (!r) return offs.forEach(function (f) { f(); });
+    r.el = el; r.kind = kind; r.offs = offs;
+    mark(el, kind, true);
+    live.push(r);
+  });
+}
+function mark(el, kind, add) {
+  var l = attr(el, READY, '').split(' ').filter(function (k) { return k && k !== kind; });
+  if (add) l.push(kind);
+  if (l.length) el.setAttribute(READY, l.join(' ')); else el.removeAttribute(READY);
+}
+function drop(r) {
+  if (r.stop) r.stop();
+  r.offs.forEach(function (f) { f(); });
+  mark(r.el, r.kind);
+  live.splice(live.indexOf(r), 1);
+}
+function records(kind, fn) { live.slice().forEach(function (r) { if (r.kind === kind) fn(r); }); }
+
+// Mega menu. Opened by hover then clicked, a panel stays open: the click meant "open". One open on the page, across
+// every header init() wired. Each change fires gw:mega on the trigger.
+function setMega(m, show, mode) {
+  m.p.hidden = !show;
+  m.t.setAttribute('aria-expanded', String(show));
+  m.item.classList.toggle('is-open', show);
+  m.mode = mode;
+  megaOpen = show ? m : megaOpen === m ? null : megaOpen;
+  emit(m.t, 'gw:mega', { id: m.p.id, open: show });
+}
+function showMega(m, mode) {
+  clearTimeout(megaTimer);
+  if (megaOpen === m) { if (mode === 'click') m.mode = mode; return; }
+  if (megaOpen) setMega(megaOpen, false);
+  setMega(m, true, mode);
+}
+function hideMega(focus) {
+  var m = megaOpen;
+  clearTimeout(megaTimer);
+  if (!m) return;
+  setMega(m, false);
+  if (focus === true) m.t.focus();
+}
+function inside(m, el) { return !!el && (m.item.contains(el) || m.p.contains(el)); }
+function mega(ctx) {
+  each(ctx, '[data-gw-mega]', 'mega', function (t, on) {
+    var p = doc.getElementById(attr(t, 'data-gw-mega', attr(t, 'aria-controls', '')));
+    if (!p) return;
+    var m = { t: t, p: p, item: t.closest('.gw-nav__item') || t.parentNode };
+    on(t, 'click', function () { if (megaOpen === m && m.mode !== 'hover') hideMega(); else showMega(m, 'click'); });
+    (m.item.contains(p) ? [m.item] : [m.item, p]).forEach(function (el) {
+      on(el, 'mouseenter', function () {
+        if (fine.matches) { clearTimeout(megaTimer); if (megaOpen !== m) megaTimer = setTimeout(function () { showMega(m, 'hover'); }, 80); }
+      });
+      on(el, 'mouseleave', function () {
+        if (fine.matches) { clearTimeout(megaTimer); if (megaOpen === m && m.mode === 'hover') megaTimer = setTimeout(hideMega, 160); }
+      });
+    });
+    on(m.item, 'focusout', function (e) { if (megaOpen === m && e.relatedTarget && !inside(m, e.relatedTarget)) hideMega(); });
+    on(p, 'click', function (e) { if (link(e)) hideMega(); });
+    m.stop = function () { if (megaOpen === m) hideMega(); };
+    return m;
+  });
+}
+
+// Mobile menu. Labels: data-gw-label-open/-close, else the markup's aria-label, else English. A link inside closes it
+// (same-page anchors do not reload). Taken back while open, it closes first: it must not keep the page locked.
+function mobile(ctx) {
+  each(ctx, '[data-gw-menu-toggle]', 'menu', function (btn, on) {
+    var menu = 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 r = {
+      open: function () { return !menu.hidden; },
+      set: function (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();
+      },
+      stop: function () { if (r.open()) r.set(false); }
+    };
+    on(btn, 'click', function () { r.set(!r.open()); });
+    on(menu, 'click', function (e) { if (link(e)) r.set(false); });
+    return r;
+  });
+}
+function closeMenus(focus) { records('menu', function (r) { if (r.open()) r.set(false, focus); }); }
+
+// Theme toggle. Labels: data-gw-label-dark/-light, else the markup's aria-label, else English. A press fires gw:theme
+// on <html>; so does a change of the system's scheme while the page follows it.
+function dark() { var t = root.getAttribute('data-theme'); return t ? t === 'dark' : sys.matches; }
+function relabel() { records('theme', function (r) { r.el.setAttribute('aria-label', r.labels[+dark()]); }); }
+function theme(ctx) {
+  each(ctx, '[data-gw-theme-toggle]', 'theme', function (b, on) {
+    var r = { labels: [attr(b, 'data-gw-label-dark', attr(b, 'aria-label', 'Switch to dark theme')), attr(b, 'data-gw-label-light', 'Switch to light theme')] };
+    on(b, 'click', function () {
+      var next = dark() ? 'light' : 'dark';
+      root.setAttribute('data-theme', next);
+      try { localStorage.setItem('gw-theme', next); } catch (e) { /* blocked */ }
+      relabel();
+      emit(root, 'gw:theme', { theme: next });
+    });
+    // taken back: the markup's own label again, so a later init reads the same words
+    r.stop = function () { b.setAttribute('aria-label', r.labels[0]); };
+    return r;
+  });
+  relabel();
+}
+
+// Reveal at 15% visible, once. Failsafe: shown 2.5s after the init that found them, or at once without
+// IntersectionObserver or under reduced motion.
+function reveal(ctx) {
+  var els = [], io = null;
+  each(ctx, '.gw-reveal', 'reveal', function (el) { els.push(el); return { stop: function () { if (io) io.unobserve(el); } }; });
+  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 (one scroll listener for every header).
+function scrolled() {
+  var s = window.scrollY > 8;
+  queued = false;
+  records('header', function (r) { if (r.s !== s) r.el.classList.toggle('is-scrolled', (r.s = s)); });
+}
+function header(ctx) {
+  each(ctx, '[data-gw-header]', 'header', function (h) { return { s: false, stop: function () { h.classList.remove('is-scrolled'); } }; });
+  scrolled();
+}
+
+// aria-current="page" on nav links to this path, unless the markup marked one. The script's own marks are taken
+// back first, so an init() after a client-side navigation moves them.
+function current(ctx) {
+  var links = within('.gw-nav__link[href], .gw-mega__link[href]', ctx);
+  within('#gw-mobile-menu, .gw-mobile-menu', ctx).forEach(function (m) { links = links.concat(all('a[href]', m)); });
+  function norm(p) { return p.replace(/\/index\.html?$/, '/').replace(/\.html?$/, '').replace(/\/+$/, '') || '/'; }
+  links.forEach(function (a) { if (mine.has(a)) { mine.delete(a); a.removeAttribute('aria-current'); } });
+  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'); mine.add(a); }
+  });
+}
+
+// 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. A choice made by the reader fires gw:segmented on the group; wiring it does not.
+function segmented(ctx) {
+  each(ctx, '[data-gw-segmented]', 'segmented', function (g, on) {
+    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 own = attr(el, 'data-gw-show', '').split(/\s+/).filter(function (t) { return t.split(':')[0] === name; });
+        if (own.length) el.hidden = own.indexOf(name + ':' + v) < 0;
+      });
+      if (said) emit(g, 'gw:segmented', { 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]);
+    return {};
+  });
+}
+
+// Contents (.gw-toc, data-gw-toc): links to the #ids of the article's headings, plain links that work without the
+// script. The section in view is the one whose heading last went above the line 30% down the window: its link gets
+// aria-current="true" and the nav fires gw:toc ({ id }, '' above the first heading). One IntersectionObserver per
+// list sees a heading cross that line, both ways; its root runs from far above the window down to the line, so a jump
+// across many sections (a link, End, a dragged scrollbar) still counts. Without IntersectionObserver nothing is
+// marked. The <details> is open from 1080px (the list sits beside the article), below that it keeps the markup's own
+// state (folded) and a link inside folds it before the page moves.
+function toc(ctx) {
+  each(ctx, '[data-gw-toc]', 'toc', function (nav, on) {
+    var box = nav.querySelector('details'), own = !!(box && box.open), cur = null, io = null;
+    var items = all('a[href]', nav).map(function (a) {
+      var id = attr(a, 'href', '');
+      if (id.charAt(0) !== '#') return null;
+      try { id = decodeURIComponent(id.slice(1)); } catch (e) { id = id.slice(1); }
+      return { a: a, h: doc.getElementById(id) };
+    }).filter(function (x) { return x && x.h; });
+    if (!items.length) return;
+    function update() {
+      var line = window.innerHeight * 0.3, top = -Infinity, next = null;
+      items.forEach(function (x) { var t = x.h.getBoundingClientRect().top; if (t <= line && t > top) { top = t; next = x; } });
+      if (next === cur) return;
+      if (cur) cur.a.removeAttribute('aria-current');
+      if (next) next.a.setAttribute('aria-current', 'true');
+      cur = next;
+      emit(nav, 'gw:toc', { id: next ? next.h.id : '' });
+    }
+    var r = {
+      fit: function () { if (box) box.open = wide.matches || own; },
+      stop: function () { if (io) io.disconnect(); if (cur) cur.a.removeAttribute('aria-current'); if (box) box.open = own; }
+    };
+    on(nav, 'click', function (e) { if (box && !wide.matches && link(e)) box.open = false; });
+    if (window.IntersectionObserver) {
+      io = new IntersectionObserver(update, { rootMargin: '100000px 0px -70% 0px' });
+      items.forEach(function (x) { io.observe(x.h); });
+    }
+    r.fit();
+    return r;
+  });
+}
+
+// Prose tables (gap #63): each <table> straight inside a .gw-prose goes into a scroll box of its own,
+// div.gw-prose__table, a region named after its caption, else its first header cell, else its first cell, with
+// tabindex="0" so a keyboard can scroll it. The table is marked .is-wrapped and keeps display: table. A table with no
+// words to name it is left as it is (it scrolls by itself, as in 0.2.0). destroy() takes the box away again.
+function words(el) { return el ? el.textContent.replace(/\s+/g, ' ').trim() : ''; }
+function tables(ctx) {
+  var list = [];
+  within('.gw-prose', ctx).forEach(function (p) {
+    list = list.concat([].filter.call(p.children, function (t) { return t.tagName === 'TABLE'; }));
+  });
+  wire(list, 'table', function (t) {
+    var name = words(t.querySelector('caption')) || words(t.querySelector('th')) || words(t.querySelector('td'));
+    if (!name) return;
+    var box = doc.createElement('div'), had = t.classList.contains('is-wrapped');
+    box.className = 'gw-prose__table';
+    box.setAttribute('role', 'region');
+    box.setAttribute('tabindex', '0');
+    box.setAttribute('aria-label', name);
+    t.parentNode.insertBefore(box, t);
+    box.appendChild(t);
+    t.classList.add('is-wrapped');
+    return { stop: function () {
+      var p = box.parentNode;
+      if (p) { p.insertBefore(t, box); p.removeChild(box); }
+      if (!had) t.classList.remove('is-wrapped');
+    } };
+  });
+}
+
+// Once per page: what belongs to the document, the window or a media query rather than to one element.
+function install() {
+  doc = document; root = doc.documentElement; mine = new WeakSet();
+  fine = mq('(hover: hover) and (pointer: fine)'); sys = mq('(prefers-color-scheme: dark)');
+  var stored = null;
+  // 1080px, the kit's desktop width: the header shows its nav, the contents sit beside the article
+  wide = mq('(min-width: 1080px)');
+  on(doc, 'click', function (e) { if (megaOpen && !inside(megaOpen, e.target)) hideMega(); });
+  on(doc, 'keydown', function (e) { if (megaOpen && esc(e)) hideMega(inside(megaOpen, doc.activeElement) || megaOpen.mode === 'click'); });
+  on(doc, 'keydown', function (e) { if (esc(e)) closeMenus(true); });
+  watch(wide, function () { if (wide.matches) closeMenus(); records('toc', function (r) { r.fit(); }); });
+  on(window, 'pageshow', function (e) { if (e.persisted) closeMenus(); });
+  try { stored = localStorage.getItem('gw-theme'); } catch (e) { /* blocked */ }
+  if (!root.hasAttribute('data-theme') && /^(light|dark)$/.test(stored)) root.setAttribute('data-theme', stored);
+  watch(sys, function () { relabel(); if (!root.hasAttribute('data-theme')) emit(root, 'gw:theme', { theme: dark() ? 'dark' : 'light' }); });
+  on(window, 'scroll', function () { if (!queued) { queued = true; requestAnimationFrame(scrolled); } }, { passive: true });
+  // A busy button (aria-busy="true") ignores presses, by mouse or keyboard: no double submit. It keeps its focus and
+  // name. One listener on the document, in the capture phase, so it covers buttons inserted later too.
+  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 run(fns, ctx) {
+  fns.forEach(function (f) { try { f(ctx); } catch (e) { console.error('[gw-website]', e); } });
+}
+// One copy of the kit owns a page (window.gwWebsite). When another one got there first (the classic script, a second
+// bundle), it does the work, so nothing is wired twice.
+function other() { var g = typeof window != 'undefined' && window.gwWebsite; return g && g !== api && g; }
+
+/** Wires the kit's markup under root (default: the whole document). Safe to call again: wires only what is new. */
+function init(ctx) {
+  // server rendering: nothing to wire
+  if (typeof document == 'undefined') return;
+  var g = other();
+  if (g) return g.init && g.init(ctx);
+  window.gwWebsite = api;
+  if (!doc) run([install]);
+  // an element removed from the page since the last init is let go
+  live.slice().forEach(function (r) { if (r.el.isConnected === false) drop(r); });
+  run([mega, mobile, theme, reveal, header, current, segmented, toc, tables], ctx && ctx.querySelectorAll ? ctx : doc);
+}
+
+/** Takes back what init() wired under root (default: the whole document): listeners and data-gw-ready marks. */
+function destroy(ctx) {
+  var g = other();
+  if (g) return g.destroy && g.destroy(ctx);
+  if (!doc) return;
+  ctx = ctx && ctx.querySelectorAll ? ctx : doc;
+  live.slice().forEach(function (r) { if (ctx === doc || ctx.contains(r.el)) drop(r); });
+}
+
+export { version, init, destroy };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemboss/website-ui",
-  "version": "0.3.0",
+  "version": "0.5.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",
@@ -23,6 +23,7 @@
     "./website.css": "./website.css",
     "./website.min.css": "./website.min.css",
     "./website.js": "./js/website.js",
+    "./website.mjs": "./js/website.mjs",
     "./system.json": "./system.json",
     "./css/*": "./css/*",
     "./package.json": "./package.json"

package/skill/SKILL.md

@@ -17,9 +17,14 @@ the kit and its rules are how the page ends up looking designed. Compose from th
 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.
+   - An article page (a blog post, a guide) is `KIT/templates/sections/article.html`: breadcrumbs, the meta row, a
+     contents list from the article's h2s, the prose, callouts, the FAQ last. Never a callout told by its colour
+     alone (it keeps its label: Note, Tip, Warning). The blog index is `KIT/templates/sections/post-list.html`.
    - 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`.
+   - No JS of your own for kit parts: markup inserted after load (a route change, a block) gets
+     `gwWebsite.init(root)`, or `init(root)` from `website.mjs` (`KIT/docs/markup-contract.md`, "Script").
    - 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`).

package/system.json

@@ -21,6 +21,7 @@
       "success": "#007f5f",
       "success-soft": "#e3f1df",
       "warning": "#9a6700",
+      "warning-soft": "#fbf1dc",
       "night": "#0c0e14",
       "night-2": "#141722",
       "on-night": "#e3e4e8",
@@ -45,6 +46,7 @@
       "success": "#34c38f",
       "success-soft": "#132a22",
       "warning": "#e0b341",
+      "warning-soft": "#2b2410",
       "night": "#0a0b10",
       "night-2": "#12141c",
       "on-night": "#e3e4e8",
@@ -60,7 +62,7 @@
     "roles": {
       "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.",
+      "success/warning": "State only. Their -soft tints are grounds: a tip or a warning callout, a success badge.",
       "wash": "The hero wash and illustrations only."
     }
   },

package/templates/sections/article.html

@@ -0,0 +1,93 @@
+<!--
+  Article: a blog post or a guide, the whole <main> of the page. In this order: breadcrumbs, the title (the page's one
+  <h1>), the meta row, a hero image, the contents list, the article's own HTML in .gw-prose, the FAQ last.
+  - Breadcrumbs: every level above the page, then the page itself with aria-current="page". No separator characters:
+    the kit draws them. A BreadcrumbList JSON-LD is up to the site (example: docs/components.md, Breadcrumbs).
+  - Meta row: each item a <span>; the date as <time datetime="YYYY-MM-DD">, "Updated" when it changed after it was
+    published; the read time at about 200 words a minute. The avatar is optional (alt="": the name is written next
+    to it).
+  - Hero: the post's own image, with width and height, not lazy (it is the first screen). Leave the figure out when
+    the post has none.
+  - Contents: one link per <h2> of the article (a nested <ol> for its <h3>s, if any), each to the heading's id, in the
+    article's order, with the heading's words. data-gw-toc lets website.js mark the section in view and fold the list
+    on phones; the links work without it. check reports a link to an id that is not on the page.
+  - Callouts: a note, a tip or a warning, one idea each, at most one every few sections. Always the label in words
+    (Note, Tip, Warning, or the page's language): never a callout told by its colour alone.
+  - FAQ: the last <h2> of the article, real questions with short answers. FAQPage JSON-LD only if every answer is
+    visible on the page (example: docs/components.md, Article).
+  Limits: one article per page; headings in order (h2, then h3), each <h2> with an id; tables straight in the prose
+  are boxed by website.js (gap #63), give them a <caption>.
+  Then a post list (templates/sections/post-list.html, "More from the blog") and the closing CTA, if the page needs one.
+-->
+<article class="gw-wrap gw-article">
+  <header class="gw-article__head">
+    <nav class="gw-breadcrumbs" aria-label="Breadcrumb">
+      <ol>
+        <li><a href="[/blog]">[Blog]</a></li>
+        <li><a href="[/blog/category]">[Category]</a></li>
+        <li><a href="[/blog/this-post]" aria-current="page">[The post's title]</a></li>
+      </ol>
+    </nav>
+    <h1>[The post's title]</h1>
+    <p class="gw-article-meta">
+      <span><img class="gw-article-meta__avatar" src="[/img/author.webp]" alt="" width="24" height="24">[Author or team]</span>
+      <span><a href="[/blog/category]">[Category]</a></span>
+      <span>[Updated] <time datetime="[2026-10-25]">[October 25, 2026]</time></span>
+      <span>[5] min read</span>
+    </p>
+  </header>
+  <figure class="gw-article__hero">
+    <img src="[/img/post-hero.webp]" alt="[What the picture shows]" width="[1200]" height="[675]" fetchpriority="high">
+  </figure>
+  <nav class="gw-toc" aria-label="[On this page]" data-gw-toc>
+    <details>
+      <summary>[On this page]</summary>
+      <ol>
+        <li><a href="#[first-section]">[The first section's heading]</a></li>
+        <li><a href="#[second-section]">[The second section's heading]</a>
+          <ol>
+            <li><a href="#[a-step]">[A step inside it]</a></li>
+          </ol>
+        </li>
+        <li><a href="#faq">[Frequently asked questions]</a></li>
+      </ol>
+    </details>
+  </nav>
+  <div class="gw-prose">
+    <p>[The first paragraph: what the reader will know or be able to do by the end.]</p>
+    <h2 id="[first-section]">[The first section's heading]</h2>
+    <p>[Paragraphs of two to five sentences. Links go where they say: <a href="[link]">[the setup guide]</a>.]</p>
+    <div class="gw-callout gw-callout--note" role="note">
+      <p class="gw-callout__label">[Note]</p>
+      <p>[Something the reader should keep in mind, in one or two sentences.]</p>
+    </div>
+    <h2 id="[second-section]">[The second section's heading]</h2>
+    <p>[A paragraph.]</p>
+    <h3 id="[a-step]">[A step inside it]</h3>
+    <p>[A paragraph.]</p>
+    <table>
+      <caption>[What the table compares]</caption>
+      <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 class="gw-callout gw-callout--tip" role="note">
+      <p class="gw-callout__label">[Tip]</p>
+      <p>[A shortcut or a better way, in one or two sentences.]</p>
+    </div>
+    <div class="gw-callout gw-callout--warning" role="note">
+      <p class="gw-callout__label">[Warning]</p>
+      <p>[What goes wrong if the reader skips this, in one or two sentences.]</p>
+    </div>
+    <h2 id="faq">[Frequently asked questions]</h2>
+    <div class="gw-faq">
+      <details class="gw-faq__item">
+        <summary>[A question the reader asks?]</summary>
+        <p>[The answer in two to four sentences.]</p>
+      </details>
+      <details class="gw-faq__item">
+        <summary>[A question the reader asks?]</summary>
+        <p>[The answer.]</p>
+      </details>
+    </div>
+  </div>
+</article>

package/templates/sections/post-list.html

@@ -0,0 +1,65 @@
+<!--
+  Post list: the blog index, a category page, or "More from the blog" under an article. Cards with a picture
+  (.gw-card__media, gap #33), the category as a .gw-label, the title, one or two lines of excerpt and the meta row.
+  - The title's link covers the whole card, so the card is one target and its name is the title alone: no other link
+    or button inside a card. The picture is alt="" here (the title says what the post is) and loading="lazy".
+  - The title is one level below the section's heading (h3 under an h2; h2 on the index, under its h1).
+  - --wide on the picture for 1200 x 630 share images (1.91:1), --square for 1:1; the default is 16:9.
+  - .gw-post-list--compact: rows without cards or pictures, for a long list or a sidebar.
+  - Pagination: previous and next as links (rel="prev" / rel="next"), the page number between them as words. Leave
+    out the link that does not exist (no "Newer posts" on page 1).
+  Limits: three, six or nine cards in the grid; the same picture shape for every card of a list; real posts, real
+  dates.
+-->
+<section class="gw-section" aria-labelledby="[posts-h]">
+  <div class="gw-wrap">
+    <div class="gw-section__head">
+      <p class="gw-label">[Blog]</p>
+      <h2 id="[posts-h]">[More from the blog]</h2>
+    </div>
+    <ul class="gw-post-list" role="list">
+      <li>
+        <article class="gw-card gw-post">
+          <div class="gw-card__media"><img src="[/img/post.webp]" alt="" width="[640]" height="[360]" loading="lazy"></div>
+          <p class="gw-label">[Category]</p>
+          <h3 class="gw-post__title"><a href="[/blog/post]">[The post's title]</a></h3>
+          <p>[One or two lines on what the reader gets from it.]</p>
+          <p class="gw-article-meta"><span><time datetime="[2026-10-25]">[Oct 25, 2026]</time></span><span>[5] min read</span></p>
+        </article>
+      </li>
+      <li>
+        <article class="gw-card gw-post">
+          <div class="gw-card__media"><img src="[/img/post.webp]" alt="" width="[640]" height="[360]" loading="lazy"></div>
+          <p class="gw-label">[Category]</p>
+          <h3 class="gw-post__title"><a href="[/blog/post]">[The post's title]</a></h3>
+          <p>[One or two lines on what the reader gets from it.]</p>
+          <p class="gw-article-meta"><span><time datetime="[2026-10-25]">[Oct 25, 2026]</time></span><span>[5] min read</span></p>
+        </article>
+      </li>
+      <li>
+        <article class="gw-card gw-post">
+          <div class="gw-card__media"><img src="[/img/post.webp]" alt="" width="[640]" height="[360]" loading="lazy"></div>
+          <p class="gw-label">[Category]</p>
+          <h3 class="gw-post__title"><a href="[/blog/post]">[The post's title]</a></h3>
+          <p>[One or two lines on what the reader gets from it.]</p>
+          <p class="gw-article-meta"><span><time datetime="[2026-10-25]">[Oct 25, 2026]</time></span><span>[5] min read</span></p>
+        </article>
+      </li>
+    </ul>
+    <nav class="gw-pagination" aria-label="[Blog pages]">
+      <a class="gw-btn gw-btn--secondary" href="[/blog?page=1]" rel="prev">[Newer posts]</a>
+      <p class="gw-pagination__status">[Page 2 of 12]</p>
+      <a class="gw-btn gw-btn--secondary" href="[/blog?page=3]" rel="next">[Older posts]</a>
+    </nav>
+  </div>
+</section>
+
+<!-- the compact list: rows, no picture -->
+<ul class="gw-post-list gw-post-list--compact" role="list">
+  <li>
+    <article class="gw-card gw-post">
+      <h3 class="gw-post__title"><a href="[/blog/post]">[The post's title]</a></h3>
+      <p class="gw-article-meta"><span>[Category]</span><span><time datetime="[2026-10-25]">[Oct 25, 2026]</time></span><span>[5] min read</span></p>
+    </article>
+  </li>
+</ul>