npm - @gemboss/website-ui - Versions diffs - 0.4.0 → 0.5.0 - Mend

@gemboss/website-ui 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/AGENTS.md +16 -5
package/CHANGELOG.md +62 -0
package/README.md +8 -7
package/bin/lib/check.mjs +47 -0
package/css/article.css +237 -0
package/css/components.css +15 -0
package/css/prose.css +29 -16
package/css/tokens.css +5 -0
package/demo/article.html +359 -0
package/demo/assets/article-hero.svg +1 -0
package/demo/assets/avatar-gemboss.svg +1 -0
package/demo/assets/post-headless.svg +1 -0
package/demo/assets/post-motion.svg +1 -0
package/demo/assets/post-output.svg +1 -0
package/demo/assets/post-speed.svg +1 -0
package/demo/assets/post-theme.svg +1 -0
package/demo/assets/post-voice.svg +1 -0
package/demo/blog.html +314 -0
package/demo/index.html +1 -0
package/docs/components.md +191 -7
package/docs/markup-contract.md +58 -4
package/js/website.js +68 -8
package/js/website.mjs +80 -7
package/package.json +1 -1
package/skill/SKILL.md +3 -0
package/system.json +3 -1
package/templates/sections/article.html +93 -0
package/templates/sections/post-list.html +65 -0
package/website.css +288 -17
package/website.min.css +1 -1

package/docs/markup-contract.md CHANGED Viewed

@@ -27,7 +27,8 @@ BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
 ## Script (0.4.0)
 One script wires every part below: the mega menu, the mobile menu, the theme toggle, reveal, the header's scroll
-state, the current page, the segmented control and the busy button. It comes in two entries built from one source
+state, the current page, the segmented control, the busy button, an article's contents list and the scroll box of its
+prose tables (0.5.0). It comes in two entries built from one source
 (`js/website.mjs`; `scripts/build.mjs` writes `js/website.js` from it and `--check` fails when they differ):
 | entry | file | how it starts |
@@ -42,9 +43,9 @@ state, the current page, the segmented control and the busy button. It comes in
   to the page (Escape, the outside click, the busy-button guard, the system theme, the scroll) are installed once.
 - **`destroy(root = document)`** takes back what `init` wired under `root`: its listeners and its marks. An open
   mega menu or mobile menu is closed first, so an unmounted menu cannot leave the page locked.
-- **`version`**: `'0.4.0'`. The classic script exposes the three as `window.gwWebsite`.
+- **`version`**: `'0.5.0'`. The classic script exposes the three as `window.gwWebsite`.
 - **`data-gw-ready`**: on each wired element, the parts wired on it (`mega`, `menu`, `theme`, `reveal`, `header`,
-  `segmented`). It is a mark for people and tests, not a switch: markup copied from a live page, attribute and all,
+  `segmented`, `toc`, `table`). It is a mark for people and tests, not a switch: markup copied from a live page, attribute and all,
   is still wired.
 - **One copy per page.** The first copy that runs owns the page (`window.gwWebsite`); another one (the classic
   script next to a bundle, two bundles) hands its calls to it, so nothing is wired twice.
@@ -93,9 +94,11 @@ The script tells the page's own code what changed. Every event is a `CustomEvent
 | `gw:mega` | the trigger (`[data-gw-mega]`) | `{ id, open }`: the panel's `id`, `true` when it opened | a panel opens or closes: click, hover, Escape, a click outside, focus leaving, a link inside, `destroy` of an open one. Moving to another menu fires a close, then an open |
 | `gw:theme` | `<html>` | `{ theme: 'light' \| 'dark' }`: the theme the page now shows | a press on a theme toggle; also a change of the system's scheme while the page follows it (no `data-theme`) |
 | `gw:segmented` | the group (`[data-gw-segmented]`) | `{ name, value }`: the group's name, the chosen option's `value` | the reader chooses an option (click, arrows, Home, End) |
+| `gw:toc` | the contents (`[data-gw-toc]`) | `{ id }`: the id of the heading whose section is now marked, `''` above the first one | the section in view changes: scrolling, a contents link, a jump. Also once after load when the page opens inside a section (a link to `#id`): the observer reports after `init`, never during it |
 ```js
 document.addEventListener('gw:theme', function (e) { chart.setTheme(e.detail.theme); });
+document.addEventListener('gw:toc', function (e) { analytics.track('section', e.detail.id); });
 ```
 ## Header
@@ -157,6 +160,50 @@ Script behaviour:
   menu's links whose `href` pathname equals `location.pathname` (when the markup did not already). Each `init` takes
   its own marks back first, so after a client-side navigation they follow the new path; a mark in the markup stays.
+## Article: contents and prose tables (0.5.0)
+```html
+<article class="gw-wrap gw-article">
+  <header class="gw-article__head"> .gw-breadcrumbs, <h1>, .gw-article-meta </header>
+  <figure class="gw-article__hero"><img …></figure>                 <!-- optional -->
+  <nav class="gw-toc" aria-label="On this page" data-gw-toc>
+    <details>                                                       <!-- no open: the script opens it from 1080px -->
+      <summary>On this page</summary>
+      <ol><li><a href="#section-id">The section's heading</a><ol>…h3s…</ol></li> …</ol>
+    </details>
+  </nav>
+  <div class="gw-prose"> <h2 id="section-id">…</h2> … <table><caption>…</caption>…</table> … </div>
+</article>
+```
+- **Contents** (`[data-gw-toc]`, a `.gw-toc`): the script reads its links whose `href` is `#id` of an element on the
+  page (percent-encoded ids are decoded; links to other pages and to no id are ignored). With none, the list is not
+  wired yet and a later `init` tries again.
+  - The section in view is the one whose heading is the last above the line 30% down the window. Its link gets
+    `aria-current="true"`; the previous link loses it. Above the first heading no link is marked. Each change fires
+    `gw:toc` on the nav.
+  - One `IntersectionObserver` per list, observing the linked headings, with
+    `rootMargin: '100000px 0px -70% 0px'`: its root runs from far above the window down to the line, so a heading
+    is "intersecting" exactly while it is above the line, and a jump across many sections is seen as well as a
+    scroll. Each report measures every heading again. Without `IntersectionObserver` nothing is marked; the links
+    still work.
+  - The `<details>` inside: from 1080px (`matchMedia('(min-width: 1080px)')`, the kit's desktop width, where the CSS makes it sticky) the
+    script sets `open`; below it, the markup's own state (folded unless the markup says `open`), again on every
+    change of width. Below 1080px a click on a link folds it, in the click, before the browser moves to the section.
+  - `destroy`: the observer disconnects, the mark goes, the `<details>` takes the markup's state back.
+- **Prose tables**: every `<table>` that is a child of a `.gw-prose` (not one inside the author's own `.gw-table`, a
+  figure or another element) is moved into `<div class="gw-prose__table" role="region" tabindex="0" aria-label="…">`
+  at its place, and gets `.is-wrapped`.
+  - The name is the text of the table's `<caption>`, else of its first `<th>`, else of its first `<td>`, spaces
+    collapsed. A table with no text there is left as it is.
+  - The CSS keeps a wrapped table `display: table` (some Safari versions stop announcing a table whose display
+    changed) and gives the box the scroll, the hairline and the radius. A table without `.is-wrapped` (no script,
+    or before it runs) scrolls by itself with `display: block`, as in 0.2.0. Both look the same.
+  - Once per table: a second `init` finds it inside its box and leaves it. `destroy` puts the table back in the
+    prose, removes the box, and removes `.is-wrapped` unless the markup had it.
+  - A framework that renders the prose's table itself (JSX, not HTML from the CMS) should call `destroy(prose)`
+    before it re-renders that part, as for every element the script changed.
 ## 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
@@ -208,12 +255,19 @@ Script behaviour:
 | `.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, the card radius; `--link` makes the whole card an `<a>` |
+| `.gw-card__media` (+ `--wide`, `--square`) | the card's picture, first child, edge to edge on top; 16:9, 1.91:1 or 1:1 (0.5.0) |
+| `.gw-callout` (+ `--note`, `--tip`, `--warning`, `__label`) | a note, a tip or a warning in an article, `role="note"`, its kind in words (0.5.0) |
+| `.gw-breadcrumbs` | `<nav aria-label>` + `<ol>`, the last item `aria-current="page"`; separators drawn by the CSS (0.5.0) |
+| `.gw-article-meta` (+ `__avatar`) | author, category, `<time datetime>`, read time (0.5.0) |
+| `.gw-article` (`__head`, `__hero`), `.gw-toc` | the article page and its contents (script above, 0.5.0) |
+| `.gw-post-list` (+ `--compact`), `.gw-post` (`__title`) | post cards; the title's link covers the card (0.5.0) |
+| `.gw-pagination` (`__status`) | previous / next links, `rel="prev"` / `rel="next"`, markup only (0.5.0) |
 | `.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-prose` (+ `--sm`) | long-form reading: an article's own HTML, no classes inside; its bare tables get a `.gw-prose__table` box from the script (0.5.0) |
 | `.gw-tabs` (`role="tablist"`) | NOT in the kit yet (a reported gap would add it) |
 ## Sections

package/js/website.js CHANGED Viewed

@@ -1,11 +1,11 @@
-/*! @gemboss/website-ui 0.4.0 website.js | GENERATED by scripts/build.mjs from js/website.mjs (the source, with its comments): edit that file | spec: docs/markup-contract.md | load with defer */
+/*! @gemboss/website-ui 0.5.0 website.js | GENERATED by scripts/build.mjs from js/website.mjs (the source, with its comments): edit that file | spec: docs/markup-contract.md | load with defer */
 (function () {
 'use strict';
 if (window.gwWebsite) return;
-var version = '0.4.0';
+var version = '0.5.0';
 var api = { version: version, init: init, destroy: destroy };
-var doc, root, mine, fine, sys, live = [], megaOpen = null, megaTimer = 0, queued = false;
+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 }; }
@@ -18,8 +18,9 @@ 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 })); }
-function each(ctx, sel, kind, fn) {
-  within(sel, ctx).forEach(function (el) {
+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);
@@ -191,14 +192,73 @@ function segmented(ctx) {
   });
 }
+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;
+  });
+}
+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');
+    } };
+  });
+}
 function install() {
   doc = document; root = doc.documentElement; mine = new WeakSet();
   fine = mq('(hover: hover) and (pointer: fine)'); sys = mq('(prefers-color-scheme: dark)');
-  var wide = mq('(min-width: 1080px)'), stored = null;
+  var stored = null;
+  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(); });
+  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);
@@ -223,7 +283,7 @@ function init(ctx) {
   window.gwWebsite = api;
   if (!doc) run([install]);
   live.slice().forEach(function (r) { if (r.el.isConnected === false) drop(r); });
-  run([mega, mobile, theme, reveal, header, current, segmented], ctx && ctx.querySelectorAll ? ctx : doc);
+  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. */

package/js/website.mjs CHANGED Viewed

@@ -6,10 +6,10 @@
 // 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.4.0';
+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, live = [], megaOpen = null, megaTimer = 0, queued = false;
+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 }; }
@@ -27,8 +27,10 @@ function emit(el, type, detail) { if (window.CustomEvent) el.dispatchEvent(new C
 // 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.
-function each(ctx, sel, kind, fn) {
-  within(sel, ctx).forEach(function (el) {
+// 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);
@@ -215,15 +217,86 @@ function segmented(ctx) {
   });
 }
+// 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 wide = mq('(min-width: 1080px)'), stored = null;
+  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(); });
+  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);
@@ -254,7 +327,7 @@ function init(ctx) {
   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], ctx && ctx.querySelectorAll ? ctx : doc);
+  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. */

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@gemboss/website-ui",
-  "version": "0.4.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",

package/skill/SKILL.md CHANGED Viewed

@@ -17,6 +17,9 @@ 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`.

package/system.json CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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>