@gemboss/website-ui 0.11.0 → 0.13.0

package/js/website.mjs

@@ -6,7 +6,7 @@
 // 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.11.0';
+var version = '0.13.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, desk, mid, live = [], queued = false;
@@ -554,19 +554,46 @@ function theme(ctx) {
   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.
+// Reveal (0.12.0, as gemboss.ai; system.json motion.reveal): once, when 12% of it is in view with the bottom 6% of the
+// view taken off. Each .gw-reveal after the first among its .gw-reveal siblings waits 70ms more (at most 380ms), so a
+// grid cascades. A [data-gw-count] number inside counts up from 0 when its reveal shows. Failsafe: all shown 1.6s after
+// the init that found them, or at once without IntersectionObserver or under reduced motion (and then nothing counts).
+var REVEAL = { threshold: 0.12, margin: '0px 0px -6% 0px', stagger: 70, staggerMax: 380, failsafe: 1600, count: 1100 };
+// the number in the element's first words: "$1,200+" counts from 0 to 1,200 with its sign, grouping and decimals kept
+function countUp(el) {
+  var n = el.firstChild, m = n && n.nodeType === 3 && /^(\s*\D*?)(\d[\d,]*(?:\.\d+)?)(.*)$/.exec(n.nodeValue), t0;
+  if (!m) return;
+  var num = m[2].replace(/,/g, ''), dec = (num.split('.')[1] || '').length;
+  function fmt(v) { v = v.toFixed(dec); return m[1] + (num !== m[2] ? Number(v).toLocaleString('en-US') : v) + m[3]; }
+  n.nodeValue = fmt(0);
+  requestAnimationFrame(function step(ts) {
+    var p = Math.min((ts - (t0 = t0 || ts)) / REVEAL.count, 1);
+    n.nodeValue = fmt(p < 1 ? num * (1 - Math.pow(1 - p, 3)) : +num);
+    if (p < 1) requestAnimationFrame(step);
+  });
+}
 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(); }
+  var els = [], io, calm = still.matches;
+  each(ctx, '.gw-reveal', 'reveal', function (el) {
+    els.push(el);
+    return { stop: function () { if (io) io.unobserve(el); el.style.transitionDelay = ''; } };
+  });
+  function show(el) {
+    if (el.classList.contains('is-in')) return;
+    el.classList.add('is-in');
+    if (!calm) [].forEach.call(el.querySelectorAll('[data-gw-count]'), countUp);
+  }
   if (!els.length) return;
-  if (!window.IntersectionObserver || mq('(prefers-reduced-motion: reduce)').matches) return showAll();
+  if (!window.IntersectionObserver || calm) return els.forEach(show);
+  els.forEach(function (el) {
+    var i = [].filter.call(el.parentNode.children, function (c) { return c.classList.contains('gw-reveal'); }).indexOf(el);
+    if (i > 0) el.style.transitionDelay = Math.min(i * REVEAL.stagger, REVEAL.staggerMax) + 'ms';
+  });
   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 });
+    list.forEach(function (en) { if (en.isIntersecting) { show(en.target); io.unobserve(en.target); } });
+  }, { threshold: REVEAL.threshold, rootMargin: REVEAL.margin });
   els.forEach(function (el) { io.observe(el); });
-  setTimeout(showAll, 2500);
+  setTimeout(function () { els.forEach(show); io.disconnect(); }, REVEAL.failsafe);
 }
 
 // Header: .is-scrolled past 8px, read once per frame (one scroll listener for every header).

package/package.json

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

@@ -78,6 +78,16 @@
       "dot": "rgba(255, 255, 255, 0.1)",
       "ink": "#ffffff"
     },
+    "announce": {
+      "$comment": "The announcement bar (0.12.0): one sentence over the header, as gemboss.ai draws it, the same in light and dark. bg its ground, ink its words, line its hairline at the bottom; tag and tag-ink the small pill before the sentence; link the link's words and link-line their underline. A brand sets its own bar here.",
+      "bg": "#171a38",
+      "ink": "#b9beda",
+      "line": "rgba(255, 255, 255, 0.06)",
+      "tag": "rgba(122, 132, 255, 0.2)",
+      "tag-ink": "#a7aeff",
+      "link": "#ffffff",
+      "link-line": "rgba(255, 255, 255, 0.28)"
+    },
     "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.",
@@ -85,7 +95,8 @@
       "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.",
       "scrim": "The veil over the page while a mega menu is open (0.11.0): a dim and a 4px blur, as gemboss.ai.",
-      "stage": "The ground of a mega menu's pictures and nothing else (0.11.0)."
+      "stage": "The ground of a mega menu's pictures and nothing else (0.11.0).",
+      "announce": "The announcement bar over the header and nothing else (0.12.0)."
     }
   },
   "radius": {
@@ -113,13 +124,16 @@
       "wordmark": "clamp(40px, 9vw, 128px)",
       "$comment": "wordmark (0.7.0): the footer's last line on gemboss.ai, the brand's name, faint, at the end of the page. Decoration only, never a heading. Weight 800 (0.10.0, as gemboss.ai draws it): the one use of 800 in the kit.",
       "weight": 600,
-      "tracking": "-0.03em"
+      "tracking": "-0.03em",
+      "h1_leading": 1.1,
+      "$comment_leading": "1.1 and 1.06 (0.12.0, gemboss.ai's): at 1.02 the descenders of a first line touched the capitals of the second (Chris, 15/10/2026).",
+      "h2_leading": 1.06
     },
     "heading": { "weight": 650, "tracking": "-0.022em", "line_height": 1.08 },
     "subhead": { "weight": 600 },
     "body": { "size": 18, "line_height": 1.6 },
-    "label": { "size": 13, "weight": 500, "case": "sentence", "$comment": "muted, led by the 8px accent square; never uppercase tracking" },
-    "button": { "size": 14, "weight": 600, "case": "sentence" }
+    "label": { "size": 13, "weight": 500, "case": "sentence", "$comment": "muted, led by the 8px square in ink (0.12.0, as gemboss.ai; the input --gw-label-mark paints it another colour); never uppercase tracking" },
+    "button": { "size": 14, "weight": 600, "case": "sentence", "family": "Inter", "$comment": "family (0.12.0): a button names the brand face alone, as gemboss.ai does. A glyph the face does not carry (the arrow → is not in Inter's web subset) is then drawn by the system's own fallback, the width gemboss.ai's buttons have (with the full stack it is a different face, 1px narrower, and a pair of buttons fits where gemboss.ai wraps it)." }
   },
   "space": {
     "scale": [0, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 120],
@@ -168,6 +182,16 @@
     "properties": ["transform", "opacity"],
     "ease": "cubic-bezier(.22,1,.36,1)",
     "reveal_ms": 700,
+    "reveal": {
+      "$comment": "Scroll reveal (0.12.0, as gemboss.ai): a .gw-reveal rises distance px and fades in over reveal_ms when threshold of it is in view, the bottom margin of the view taken off; each one after the first among its .gw-reveal siblings waits stagger_ms more (at most stagger_max_ms); all are shown failsafe_ms after the script starts. A [data-gw-count] number inside counts up from 0 over count_ms when its reveal shows. The script's numbers are held equal to these by the tests.",
+      "distance": 20,
+      "threshold": 0.12,
+      "margin": "0px 0px -6% 0px",
+      "stagger_ms": 70,
+      "stagger_max_ms": 380,
+      "failsafe_ms": 1600,
+      "count_ms": 1100
+    },
     "spin_ms": 700,
     "$comment": "Animate transform and opacity only. Everything is still under prefers-reduced-motion (a busy button's ring turns once every spin_ms, as the dashboard's spinner, and stands still as an ellipsis). One exception, the spotlight (spot): its light is one painted layer of one element, so its radius may grow.",
     "spot": {

package/templates/header.html

@@ -11,7 +11,8 @@
   the panel's (--gw-mega-w, --gw-mega-pv; 1000 and 320 when it says nothing), its columns too (--gw-mega-cols, 3).
   Limits: at most five top-level items, one .gw-btn (the primary action), one second text action (.gw-header__link).
   Each panel: two or three columns of four or five rows, at most one card, three links in its strip. The announcement
-  bar is optional: one sentence.
+  bar is optional: one sentence, one link, a small pill before it if you like (.gw-announce__tag, one word); its
+  colours are the brand's (system.json color.announce), the same in light and dark.
   Two options (0.8.0):
   - The mobile menu drills down (data-gw-menu="drill" on #gw-mobile-menu, as gemboss.ai's phone menu): the top level
     lists the sections, a tap on one shows its level alone with Back and its title, and the actions stay in a bar at
@@ -25,7 +26,7 @@
     never be translated. Put the word for "Language" in the page's language in data-gw-label-language.
   Replace every [bracketed] placeholder; delete what you do not use.
 -->
-<div class="gw-announce" role="region" aria-label="Announcement">[One sentence of news.] <a href="[link]">[Where the link goes]</a></div>
+<div class="gw-announce" role="region" aria-label="Announcement"><span class="gw-announce__tag">[New]</span> [One sentence of news.] <a href="[link]">[Where the link goes]</a></div>
 <header class="gw-header" data-gw-header>
   <div class="gw-header__bar">
     <a class="gw-brand" href="/"><img class="gw-brand__mark" src="[/logo.svg]" alt="" width="34" height="34"><span class="gw-brand__name">[Brand]</span></a>

package/templates/page.html

@@ -26,7 +26,7 @@
 <body class="gw-page">
   <a class="gw-skip" href="#main">Skip to content</a>
 
-  <div class="gw-announce" role="region" aria-label="Announcement">[One sentence of news.] <a href="[link]">[Where the link goes]</a></div>
+  <div class="gw-announce" role="region" aria-label="Announcement"><span class="gw-announce__tag">[New]</span> [One sentence of news.] <a href="[link]">[Where the link goes]</a></div>
   <header class="gw-header" data-gw-header>
     <div class="gw-header__bar">
       <a class="gw-brand" href="/"><img class="gw-brand__mark" src="[/logo.svg]" alt="" width="34" height="34"><span class="gw-brand__name">[Brand]</span></a>
@@ -134,7 +134,7 @@
     <div class="gw-wrap">
       <div class="gw-footer__grid">
         <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>
+          <a class="gw-brand" href="/"><img class="gw-brand__mark" src="[/logo.svg]" alt="" width="34" height="34"><span class="gw-brand__name">[Brand]</span></a>
           <p>[One sentence on what the brand does for the reader.]</p>
         </div>
         <nav class="gw-footer__col" aria-label="[Column heading]">

package/templates/sections/form.html

@@ -11,6 +11,8 @@
     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.
+  As a page's first screen (a contact page, 0.13.0): the heading is the page's one <h1>, drawn at the section size
+  (<h1 class="gw-h2">), and the page needs no hero above it.
   Limits: three fields, one .gw-btn; no field that the team does not read.
 -->
 <section class="gw-section" aria-labelledby="[form-h]">

package/templates/sections/hero.html

@@ -3,7 +3,8 @@
   Variants: .gw-hero--center (centred, for short promises), .gw-hero--compact (subpages: less height, h2-sized h1).
   Add .gw-band--night for a dark hero (it counts as one of the page's three night bands).
   Limits: a short label, a two-part headline (muted first sentence, ink second), at most two lines under it,
-  one .gw-btn and one secondary action. The optional window holds a real product screen (img with alt, width, height)
+  one .gw-btn and one secondary action. Instead of the window, a photo: <figure class="gw-figure"> with its caption.
+  The optional window holds a real product screen (img with alt, width, height)
   or a drawn mock-up. Numbers in it that are not real get the caption "Illustrative data." (vi: "Dữ liệu minh hoạ.",
   zh: "示意数据。"); real ones get their source there. Never tuck the hero under the header.
 -->

package/templates/sections/split.html

@@ -2,7 +2,7 @@
   Split: one idea told in words beside a figure (a real screen, or a drawn mock-up of the product).
   .gw-split--reverse puts the figure on the left on wide screens; on phones the words always come first.
   Alternate --reverse between consecutive splits. Limits: label, h2, at most two lines, a check list of three to
-  five items, one action (a link or one button). The figure is a .gw-window or a <figure> with alt text; numbers in
+  five items, one action (a link or one button). The figure is a .gw-window (a screen) or a <figure class="gw-figure"> (a photo, with alt text and a caption); numbers in
   a window that are not real get the caption "Illustrative data.", real ones their source.
 -->
 <section class="gw-section">

package/templates/site/app/[[...path]]/route.js

@@ -0,0 +1,23 @@
+// Every static HTML page, served byte for byte from the built file and prerendered at build time, so each page is a
+// file on the CDN. A more specific route (app/blog/[slug]/page.js…) wins over this catch-all. Unknown URL: 404.html, 404.
+// Written by `gemboss-website init --site` (@gemboss/website-ui); the site owns it from here.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ROOT, pages } from "../../lib/pages.mjs";
+
+export const dynamic = "force-static";
+export const dynamicParams = true;
+
+export function generateStaticParams() {
+  return [...pages().keys()].map((route) => ({ path: route === "/" ? [] : route.slice(1).split("/") }));
+}
+
+const HTML = { "content-type": "text/html; charset=utf-8" };
+
+export async function GET(_req, { params }) {
+  const { path } = await params;
+  const route = "/" + (path || []).join("/");
+  const file = pages().get(route);
+  if (file) return new Response(await readFile(join(/*turbopackIgnore: true*/ ROOT, file)), { status: 200, headers: HTML });
+  return new Response(await readFile(join(/*turbopackIgnore: true*/ ROOT, "404.html")), { status: 404, headers: HTML });
+}

package/templates/site/assets/kit-gaps.css

@@ -0,0 +1,3 @@
+/* Stopgaps for what @gemboss/website-ui does not have yet (AGENTS.md section 9). Each: classes prefixed kitgap-, the
+   kit's tokens and scales only, never a .gw-* override, and a comment naming its gap (gap #N, from
+   npx gemboss-website gap). npx gemboss-website upgrade says when the kit ships it: then delete the stopgap. */

package/templates/site/assets/site.css

@@ -0,0 +1,16 @@
+/* The site's own CSS, linked after the kit (website.css). Two jobs only (AGENTS.md sections 7 and 8):
+   1. the brand's choices, in ONE :root block: its accent family and wash, and if it has its own, its announcement bar
+      and Stage colours (docs/theming.md). Delete the lines the brand keeps from the kit; GemBoss sets none.
+   2. what the kit cannot know: an illustration, a drawn mock-up of the product. Tokens and scales only, classes with
+      the site's own prefix, never .gw-*. Something reusable the kit lacks is a gap: kit-gaps.css. */
+:root {
+  /* --gw-accent-light: #5661f5;         the accent on light pages: links' marks, focus ring, label square, check marks */
+  /* --gw-accent-strong-light: #3a44de;  accent text: 4.5:1 on --gw-bg and --gw-bg-soft */
+  /* --gw-accent-soft-light: #eef0fe;    its tint */
+  /* --gw-on-accent-light: #ffffff;      words on it (the button, under data-gw-action="accent") */
+  /* --gw-accent-dark: #7c84ff;          the same four in dark mode and night bands */
+  /* --gw-accent-strong-dark: #a3a9ff; */
+  /* --gw-accent-soft-dark: #1f2140; */
+  /* --gw-on-accent-dark: #0d0d12; */
+  /* --gw-wash-pink: #ff6f5e; --gw-wash-violet: #7c8af7; --gw-wash-sky: #43b0ff; --gw-wash-mint: #1fcf9f; */
+}

package/templates/site/gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+/.next/
+/public/
+.DS_Store

package/templates/site/lib/pages.mjs

@@ -0,0 +1,41 @@
+// The static HTML pages this site serves, and at which URL: the Next route (app/[[...path]]/route.js) serves them, and
+// `npx gemboss-website build` writes the header and footer into them. An allow-list, not "every .html": partials/ and
+// node_modules/ are full of HTML that is not a page. A new folder of pages goes into DIRS on purpose, e.g. ["blog", true].
+// Written by `gemboss-website init --site` (@gemboss/website-ui); the site owns it from here.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+export const ROOT = process.cwd();
+// [folder, recursive?]
+const DIRS = [["", false]];
+
+// turbopackIgnore: these reads only run at BUILD (prerendering every page); without it Next traces the whole project
+// into the function. At runtime the function only needs 404.html (next.config.mjs).
+function htmlIn(dir, deep) {
+  const abs = join(/*turbopackIgnore: true*/ ROOT, dir);
+  if (!existsSync(/*turbopackIgnore: true*/ abs)) return [];
+  const out = [];
+  for (const name of readdirSync(/*turbopackIgnore: true*/ abs)) {
+    const full = join(/*turbopackIgnore: true*/ abs, name);
+    if (statSync(/*turbopackIgnore: true*/ full).isDirectory()) {
+      if (deep) out.push(...htmlIn(join(dir, name), true));
+    } else if (name.endsWith(".html")) {
+      out.push(relative(ROOT, full).split(sep).join("/"));
+    }
+  }
+  return out;
+}
+
+/** file → clean URL, like Vercel's cleanUrls: index.html → /, pricing.html → /pricing. */
+export function routeOf(file) {
+  const stem = file.slice(0, -".html".length);
+  if (stem === "index") return "/";
+  return "/" + stem.replace(/\/index$/, "");
+}
+
+/** URL → file for every served page (404.html is the error page, not a page). */
+export function pages() {
+  const map = new Map();
+  for (const [dir, deep] of DIRS) for (const f of htmlIn(dir, deep)) if (f !== "404.html") map.set(routeOf(f), f);
+  return map;
+}

package/templates/site/next.config.mjs

@@ -0,0 +1,15 @@
+// Clean URLs: /pricing.html and /index.html redirect to the clean URL, /pricing/ to /pricing.
+// Written by `gemboss-website init --site` (@gemboss/website-ui); the site owns it from here.
+/** @type {import('next').NextConfig} */
+export default {
+  trailingSlash: false,
+  poweredByHeader: false,
+  async redirects() {
+    return [
+      { source: "/index.html", destination: "/", permanent: true },
+      { source: "/:path(.*)\\.html", destination: "/:path", permanent: true },
+    ];
+  },
+  // an unknown URL runs the route at request time and reads 404.html: ship that file with the function
+  outputFileTracingIncludes: { "/*": ["./404.html"] },
+};

package/templates/site/stage-public.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Copy the site's static files (not its HTML pages) into public/ before `next build`: Next serves only public/ and the
+// routes in app/. An ALLOW-LIST: only what is listed here becomes a public URL. Written by
+// `gemboss-website init --site` (@gemboss/website-ui); the site owns it from here.
+//   node stage-public.mjs           # rebuild public/ (npm run build runs it)
+//   node stage-public.mjs --check   # CI: public/ has what it needs and nothing internal
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+const ROOT = process.cwd();
+const OUT = join(ROOT, "public");
+const ROOT_FILES = ["favicon.svg", "robots.txt", "sitemap.xml"];
+const DIRS = ["assets"];
+const SKIP = (name) => name.endsWith(".html") || name.endsWith(".md") || name === ".DS_Store";
+
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else out.push(relative(OUT, full).split(sep).join("/"));
+  }
+  return out;
+}
+
+function stage() {
+  rmSync(OUT, { recursive: true, force: true });
+  mkdirSync(OUT, { recursive: true });
+  for (const f of ROOT_FILES) if (existsSync(join(ROOT, f))) cpSync(join(ROOT, f), join(OUT, f));
+  for (const d of DIRS) if (existsSync(join(ROOT, d))) cpSync(join(ROOT, d), join(OUT, d), { recursive: true, filter: (src) => !SKIP(src.split(sep).pop()) });
+  const files = walk(OUT);
+  console.log(`public/: ${files.length} files`);
+  return files;
+}
+
+function check() {
+  const files = stage();
+  const bad = [];
+  for (const need of ["favicon.svg", "assets/kit/website.css", "assets/kit/website.js", "assets/site.css"]) {
+    if (!files.includes(need)) bad.push(`missing public file: ${need}`);
+  }
+  for (const f of files) if (/\.(html|md|py|mjs|sh)$/.test(f) || /(^|\/)(package(-lock)?\.json|vercel\.json)$/.test(f)) bad.push(`internal file in public/: ${f}`);
+  for (const b of bad) console.error("  " + b);
+  console.log(bad.length ? `stage-public: RED, ${bad.length}` : "stage-public: green");
+  return bad.length ? 1 : 0;
+}
+
+if (process.argv.includes("--check")) process.exit(check());
+stage();

package/templates/site/vercel.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs",
+  "buildCommand": "npm run build"
+}