@gemboss/website-ui 0.4.0 → 0.6.0

package/js/website.js

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

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

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

@@ -17,6 +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`.
+   - A form asks as little as it can: one field beats a form, a form keeps two or three fields
+     (`KIT/templates/sections/form.html`; one field and its button: `.gw-form-inline`). Label above, the error in
+     words under it with `aria-invalid="true"`; the page decides when, the kit draws it.
+   - Ratings and testimonials (`KIT/templates/sections/testimonials.html`): only real ones, each linked to the page it
+     comes from, the reviewer's words exactly; stars carry their value in words (`aria-label="4.9 out of 5"`).
    - 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

@@ -11,6 +11,7 @@
       "muted": "#686b71",
       "line": "#e5e7ea",
       "line-strong": "#d5d8dd",
+      "line-control": "#85888e",
       "action": "#1b1c1e",
       "action-hover": "#000000",
       "on-action": "#ffffff",
@@ -21,6 +22,10 @@
       "success": "#007f5f",
       "success-soft": "#e3f1df",
       "warning": "#9a6700",
+      "warning-soft": "#fbf1dc",
+      "danger": "#b42318",
+      "danger-soft": "#fff0e9",
+      "on-danger": "#ffffff",
       "night": "#0c0e14",
       "night-2": "#141722",
       "on-night": "#e3e4e8",
@@ -35,6 +40,7 @@
       "muted": "#9a9ca6",
       "line": "#2a2b33",
       "line-strong": "#383944",
+      "line-control": "#6a6d78",
       "action": "#f2f3f5",
       "action-hover": "#ffffff",
       "on-action": "#0d0d12",
@@ -45,6 +51,10 @@
       "success": "#34c38f",
       "success-soft": "#132a22",
       "warning": "#e0b341",
+      "warning-soft": "#2b2410",
+      "danger": "#ff6b5a",
+      "danger-soft": "#2e1714",
+      "on-danger": "#0d0d12",
       "night": "#0a0b10",
       "night-2": "#12141c",
       "on-night": "#e3e4e8",
@@ -60,7 +70,8 @@
     "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/danger": "State only. Their -soft tints are grounds: a tip or a warning callout, a success or an error badge, a field marked invalid. danger (0.6.0, gap #28) is the dashboard's --gemboss-danger family: the words of a field's error and the fill of a destructive button (on-danger on it).",
+      "line-control": "The border of a form control (a field, a checkbox, a radio), 0.6.0: it must reach 3:1 on bg, bg-soft and surface, light and dark, where line and line-strong are hairlines that do not. Like the dashboard's --gemboss-field-line.",
       "wash": "The hero wash and illustrations only."
     }
   },

package/templates/footer.html

@@ -2,6 +2,10 @@
   Footer: one per site, the same on every page. A brand block, three to five link columns, a bottom row.
   Limits: column headings are one or two words in sentence case; four to seven links per column; the bottom row
   holds the copyright, the legal links and the social links, nothing else. Replace every [bracketed] placeholder.
+  The newsletter form in the brand block is optional (0.6.0): keep it only when it is wired to a list that keeps the
+  address and sends what the note promises; otherwise delete the <form>. The note says how often and how to stop, and
+  links to the privacy policy. No box ticked for the reader, no "No thanks, I hate saving money". On send: the page
+  sets aria-invalid="true" and the error's words, or aria-busy on the button and then a role="status" line.
 -->
 <footer class="gw-footer">
   <div class="gw-wrap">
@@ -9,6 +13,17 @@
       <div class="gw-footer__brand">
         <a class="gw-brand" href="/"><img class="gw-brand__mark" src="[/logo.svg]" alt="" width="26" height="26"><span class="gw-brand__name">[Brand]</span></a>
         <p>[One sentence on what the brand does for the reader.]</p>
+        <form class="gw-footer__newsletter" action="[/newsletter endpoint]" method="post" novalidate>
+          <div class="gw-field">
+            <label class="gw-field__label" for="footer-email">[Product news by email]</label>
+            <div class="gw-form-inline">
+              <input class="gw-input" id="footer-email" name="email" type="email" autocomplete="email" required aria-describedby="footer-email-error footer-email-note">
+              <button class="gw-btn gw-btn--secondary" type="submit">[Subscribe]</button>
+            </div>
+            <p class="gw-field__error" id="footer-email-error"></p>
+            <p class="gw-field__hint" id="footer-email-note">[How often you write.] Unsubscribe in one click. <a href="[/privacy]">Privacy policy</a></p>
+          </div>
+        </form>
       </div>
       <nav class="gw-footer__col" aria-label="[Column heading]">
         <h2 class="gw-footer__heading">[Column heading]</h2>

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/form.html

@@ -0,0 +1,42 @@
+<!--
+  Form: a short form beside the reason to send it (a contact form, "get the guide", a demo request). Ask as little as
+  you can: one field beats a form, and a form keeps two or three fields. A question with a good guess is a choice the
+  reader confirms (a radio group with the guess checked), not a box to fill.
+  - Every field: its <label for> above the control, the error right under it, then the hint; aria-describedby names
+    the error first, then the hint. Mark the optional fields "(optional)" in the label; the placeholder is never the label.
+  - Validation is the page's: on send, set aria-invalid="true" on each wrong field and write in its .gw-field__error
+    what to do ("Enter your work email, like name@example.com"), then move the focus to the first one. The kit adds the
+    icon and the colour; the words say it, never the colour alone. Keep the empty error element in the markup.
+  - While it is sent: aria-busy="true" on the button. When the answer comes: say what happened in words in the
+    role="status" line ("Sent. We'll reply to name@example.com.").
+  - Consent boxes start unchecked, say exactly what the reader gets, and are never required to get something else.
+  - One field and its button (a newsletter, "email me the guide"): the .gw-form-inline row, see templates/footer.html.
+  Limits: three fields, one .gw-btn; no field that the team does not read.
+-->
+<section class="gw-section" aria-labelledby="[form-h]">
+  <div class="gw-wrap gw-split">
+    <div>
+      <p class="gw-label">[Contact]</p>
+      <h2 id="[form-h]"><span class="gw-dim">[The reader's question.]</span> [What sending this gets them.]</h2>
+      <p class="gw-lead">[One line: who answers and how.]</p>
+    </div>
+    <form class="gw-card gw-form" action="[/endpoint]" method="post" novalidate>
+      <div class="gw-field">
+        <label class="gw-field__label" for="[form-email]">[Work email]</label>
+        <input class="gw-input" id="[form-email]" name="email" type="email" autocomplete="email" required aria-describedby="[form-email]-error">
+        <p class="gw-field__error" id="[form-email]-error"></p>
+      </div>
+      <div class="gw-field">
+        <label class="gw-field__label" for="[form-message]">[What are you building?]</label>
+        <textarea class="gw-textarea" id="[form-message]" name="message" rows="3" required aria-describedby="[form-message]-error [form-message]-hint"></textarea>
+        <p class="gw-field__error" id="[form-message]-error"></p>
+        <p class="gw-field__hint" id="[form-message]-hint">[A sentence or two is enough.]</p>
+      </div>
+      <label class="gw-check"><input type="checkbox" name="[news]" value="yes"><span>[Also send me product news, once a month]</span></label>
+      <div class="gw-actions">
+        <button class="gw-btn" type="submit">[Send the request]</button>
+        <p class="gw-note" role="status"></p>
+      </div>
+    </form>
+  </div>
+</section>

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>

package/templates/sections/testimonials.html

@@ -0,0 +1,58 @@
+<!--
+  Testimonials: a rating badge and a wall of short reviews. Every one comes from a page anyone can open, and links to
+  it: the badge to the store's review page, each card to its review. Copy only what that page shows: the score and
+  the count on the day you copy them (update them when they change), the reviewer's words exactly (cut a long one
+  with an ellipsis, never reword it), their name and store as they wrote them. No review you wrote, no score you
+  averaged yourself, no source you cannot link: leave the card out. `check` warns about a badge or a card without
+  its link (rating-source).
+  - Stars: style="--gw-stars: N" and aria-label="N out of 5", the same number (0 to 5, one decimal). A number you also
+    show beside them is aria-hidden="true", so it is not read twice.
+  - The badge's icon: the generic bag below, or the store's own mark only where its brand rules allow it.
+  - Avatars are optional: a photo the reviewer made public with the review, alt="" (the name is beside it).
+  Limits: three or six cards; one to three sentences each; one badge.
+-->
+<section class="gw-section gw-section--soft" aria-labelledby="[reviews-h]">
+  <div class="gw-wrap">
+    <div class="gw-section__head">
+      <p class="gw-label">[Reviews]</p>
+      <h2 id="[reviews-h]"><span class="gw-dim">[What merchants say.]</span> [In their own words.]</h2>
+      <a class="gw-rating-badge" href="[https://apps.shopify.com/your-app/reviews]">
+        <span class="gw-rating-badge__icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><path d="M5 8h14l-1 12H6z"/><path d="M9 8V6a3 3 0 0 1 6 0v2"/></svg></span>
+        <span class="gw-rating-badge__body">
+          <span class="gw-rating-badge__score"><span aria-hidden="true">[4.9]</span><span class="gw-stars" role="img" aria-label="[4.9] out of 5" style="--gw-stars: 4.9"></span></span>
+          <span class="gw-rating-badge__count">[1,234] reviews on the [Shopify App Store]</span>
+        </span>
+      </a>
+    </div>
+    <ul class="gw-testimonials" role="list">
+      <li>
+        <figure class="gw-card gw-testimonial">
+          <span class="gw-stars" role="img" aria-label="[5] out of 5" style="--gw-stars: 5"></span>
+          <blockquote class="gw-testimonial__quote"><p>[The reviewer's exact words.]</p></blockquote>
+          <figcaption class="gw-testimonial__by">
+            <img class="gw-testimonial__avatar" src="[/img/reviewer.webp]" alt="" width="40" height="40" loading="lazy">
+            <span><b>[Name]</b>[Store] · <a href="[https://link to the review]">[Shopify App Store]</a></span>
+          </figcaption>
+        </figure>
+      </li>
+      <li>
+        <figure class="gw-card gw-testimonial">
+          <span class="gw-stars" role="img" aria-label="[5] out of 5" style="--gw-stars: 5"></span>
+          <blockquote class="gw-testimonial__quote"><p>[The reviewer's exact words.]</p></blockquote>
+          <figcaption class="gw-testimonial__by">
+            <span><b>[Name]</b>[Store] · <a href="[https://link to the review]">[Shopify App Store]</a></span>
+          </figcaption>
+        </figure>
+      </li>
+      <li>
+        <figure class="gw-card gw-testimonial">
+          <span class="gw-stars" role="img" aria-label="[5] out of 5" style="--gw-stars: 5"></span>
+          <blockquote class="gw-testimonial__quote"><p>[The reviewer's exact words.]</p></blockquote>
+          <figcaption class="gw-testimonial__by">
+            <span><b>[Name]</b>[Store] · <a href="[https://link to the review]">[Shopify App Store]</a></span>
+          </figcaption>
+        </figure>
+      </li>
+    </ul>
+  </div>
+</section>