@gemboss/website-ui 0.11.0 → 0.13.0

package/AGENTS.md

@@ -17,6 +17,7 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 | `templates/header.html` | the header of every site, with its two options (the drill-down mobile menu, the language switcher): fill it once, in the site's shared partial |
 | `templates/footer.html` | the footer of every site (the footer of gemboss.ai): fill it once, in the site's shared partial |
 | `templates/sections/*.html` | ready sections: hero, features, split, showcase, logos, stats, steps, pricing, FAQ, CTA, prose, article, post list, a short form, testimonials… |
+| `templates/site/` | 0.13.0: what a new site owns from the start (the Next.js wrapper that serves its static pages, its page list, its public allow-list, `site.css`, `kit-gaps.css`): `npx gemboss-website init --site` writes it |
 | `demo/index.html` | every component on one page: open it to see what exists before you build anything |
 | `demo/brand-profiles.html` | a GemPages-style brand: its accent, the accent button, soft corners, the floating header |
 | `demo/article.html`, `demo/blog.html` | a whole blog post (breadcrumbs, meta, contents, prose, callouts, FAQ) and the blog index (post list, pagination) |
@@ -60,6 +61,13 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 
 ## 2. Build a page
 
+**A new site** (0.13.0, the way gemboss.ai and gemians.com are built): `npx gemboss-website init --site` in an empty
+folder writes the header and footer partials, `index.html` and `404.html`, `assets/site.css`, `assets/kit-gaps.css` and
+the Next.js wrapper that serves the static pages, and adds the scripts to `package.json`. Then each page is a file with
+`<!-- gw:header -->` and `<!-- gw:footer -->` markers, and `npx gemboss-website build` writes the partials into every
+page (with `aria-current="page"` on its own links) and copies the kit into `assets/kit/`. Never hand-copy a header into
+a page. A page of such a site starts from `index.html`, not from `templates/page.html`.
+
 1. Copy `templates/page.html` into the site. It links `website.css` and `website.js`, has the skip link, the
    header, the `<main>` and the footer. Fill the header and footer once (they are the same on every page).
    **The footer comes from `templates/footer.html`.** A brand fills its rows (the columns, the family rows, the
@@ -225,7 +233,9 @@ A brand other than GemBoss chooses **only** these, and nothing else:
   Do not set `--gw-accent` itself: the kit points it at those per theme, and a direct override loses as soon as the
   theme toggle is pressed. Accent text uses `--gw-accent-strong`, so it must reach 4.5:1 on `--gw-bg` and
   `--gw-bg-soft`;
-- **the wash hues**, **the logo** in the header and footer, and **the favicon**;
+- **the wash hues**, **the logo** in the header and footer (a mark beside the name, or one drawing of both:
+  `.gw-brand__logo`, with a second file for dark grounds when the brand has one), and **the favicon**;
+- **the announcement bar's and the Stage's colours** (`--gw-announce-*`, `--gw-stage-*`), only when it shows them;
 - **three named profiles**, once for the site, never free values:
   - action colour: `data-gw-action="accent"` on `<html>` fills the primary button with the accent (default `ink`).
     Its words (`--gw-on-accent`) must reach 4.5:1 on `--gw-accent` and `--gw-accent-strong`, light and dark, or
@@ -242,7 +252,9 @@ examples: `demo/theme-example.html` (accent only) and `demo/brand-profiles.html`
 - Link the kit, then the site's own CSS after it: `website.css` → `site.css`.
 - The site's own CSS is for content the kit cannot know (an illustration, a product mock-up) and uses only the
   tokens. Its classes start with the site's prefix (for example `gp-` on GemPages), never `gw-`.
-- Shared header and footer markup lives in one place in the site (a partial or component), not copied per page.
+- Shared header and footer markup lives in one place in the site (a partial or component), not copied per page:
+  `partials/header.html` and `partials/footer.html`, written into the pages by `npx gemboss-website build` (CI runs
+  `build --check`, which fails when a page is out of date).
 
 ## 9. When the kit is missing something
 

package/CHANGELOG.md

@@ -4,6 +4,83 @@ Every release lists what changed for a site that uses the kit. A release that ad
 says so with `Closes gap #N` (the GitHub issue number), so `npx gemboss-website upgrade` can tell that site which
 stopgap (`kitgap-*`) it can now delete.
 
+## 0.13.0 (2026-10-26)
+
+What building a second site on the kit taught it. gemians.com was rebuilt on 0.12.0 from npm, kit sections only (Chris,
+26/10/2026: inherit from the GemBoss website kit, fix the kit where it gets in the way, then update Gemians and
+GemBoss), and every place the kit fell short became one of these. A minor version: nothing a 0.12.0 site uses changes
+its look, except a list right under a section's head (below), which now gets the head's spacing it was always meant to.
+
+- **A new site in one command**: `npx gemboss-website init --site` writes what gemboss.ai and gemians.com both had to
+  write by hand: the header and footer partials (from the kit's templates), `index.html` and `404.html` with the
+  build's markers, `assets/site.css` (the brand's `:root` block, commented) and `assets/kit-gaps.css`, and the Next.js
+  wrapper that serves the static pages byte for byte (`app/[[...path]]/route.js`, `lib/pages.mjs`, `next.config.mjs`
+  with clean URLs, `stage-public.mjs` with its allow-list, `vercel.json`, `.gitignore`), from the new
+  `templates/site/`. It never overwrites a file and adds the scripts a site needs to `package.json`.
+- **`npx gemboss-website build`** (new): copies the kit into `assets/kit/` as published, writes `partials/header.html`
+  and `partials/footer.html` into every page between `<!-- gw:header -->` and `<!-- gw:footer -->` (their leading
+  comments, the templates' notes, stay out), puts `aria-current="page"` on the header's links to that page, and the
+  kit's version on its two links (`?v=0.13.0`). `--check` writes nothing and fails when a page is out of date (CI).
+  One build for every site, so a fix reaches all of them with the kit, instead of a script per site that drifts.
+- **A logo drawn as one file** (`.gw-brand__logo`, new): the mark and the wordmark together, 26px tall, in place of
+  `__mark` and `__name`, its `alt` the brand's name. A logo made for dark grounds (Gemians' white wordmark) comes with a
+  second file, `.gw-brand__logo--dark`, shown in dark only (the system's setting or the toggle). `check`:
+  `brand-markup`.
+- **A photo beside words** (`.gw-figure`, new): a `<figure>` with its picture at the card radius and a 14px muted
+  caption 12px under it, in a split or under a hero's actions (48px below, as a window). Until now only the prose had
+  one; a split could hold a product window but not a photo of the team.
+- **A list under a section's head gets the head's spacing**: `.gw-steps`, `.gw-stats`, `.gw-post-list` and
+  `.gw-testimonials` no longer reset their own margin, which beat 0.12.0's "what follows a head starts 40px below it
+  (48px from 768px)", so the steps sat right under the heading. The base still zeroes a list's margins, at no
+  specificity.
+- **A brand's announcement bar and Stage**: `--gw-announce-*` and `--gw-stage-*` may be set in the brand's `:root` block
+  (`system.json` always said "a brand sets its own bar here", and `check` called it `token-redefined`). `check` computes
+  the bar's words and link on its ground and the Stage's words on its gradient (`brand-contrast`, 4.5:1).
+- Docs: `docs/theming.md` asks 4.5:1 only of the accent's text form (`--gw-accent-strong-*`); the plain accent is never
+  text in the kit (icons, marks, the focus ring), so 3:1 is its bar (WCAG 1.4.11), and a gold brand keeps its gold. A
+  brand mark is 34×34 (the docs and `templates/page.html` still said 26). A contact page's form is its first screen
+  with the page's one `<h1>` (`templates/sections/form.html`). The demo's announcement pill says "New", in sentence case.
+
+## 0.12.0 (2026-10-26)
+
+The grammar of every page, 1:1 with gemboss.ai: the announcement bar, the skip link, the button, the type (headings,
+lead, label, the dim first sentence), a section, its head, the wrap, and the scroll reveal. After the footer (0.10.0)
+and the header (0.11.0), this is the first step of the pages' own bodies onto the kit (Chris, 26/10/2026: every value in
+the kit, so that GemPages, Gemians and GemX inherit them). gemboss.ai's 83 pages now draw these parts with the kit's
+classes, and were measured against the pages before, in Chromium: the computed style of every one of these parts (2,300
+of them) at 320, 390, 768, 1080, 1366 and 1920px, light and dark, and every page pixel by pixel at 390 and 1366px; the
+reveal's delays and counts, a hovered button, the focused skip link.
+
+A minor version: a site on 0.11.0 sees these values change (below), none of the markup.
+
+- The announcement bar (`.gw-announce`): gemboss.ai's, on its own ground in both themes, from the new tokens
+  `--gw-announce-*` (`system.json` `color.announce`: ground, words, hairline, the pill, the link and its underline). A
+  small pill may lead the sentence (`.gw-announce__tag`, new); the link's underline is a hairline that brightens on
+  hover. 12px words in a slimmer bar up to 520px.
+- The skip link (`.gw-skip`): an accent tab out of the top left corner (was an ink button 8px in).
+- The button (`.gw-btn`): on hover the filled one rises 1px onto the rest shadow (was a darker fill); a framed or
+  frameless one does not move. Its face is the new `--gw-font-action` (`type.button.family`, the brand face alone, as
+  gemboss.ai names it: a glyph Inter's web subset lacks, the arrow, is then the system's own, the width gemboss.ai's
+  buttons have). Its line height is its surroundings'. A label wider than needed stays at the start (centred only in
+  `--block`, a phone's row of actions in a hero or CTA, an inline form). An arrow after the label is
+  `.gw-btn__arrow` (new): 3px further on hover. Up to 768px every button is at least 44px tall, by the width only (it was
+  also by a coarse pointer); a label wraps only up to 480px and only in `<main>`, at 1.35 lines (was up to 768px,
+  balanced).
+- Type: h1 at line height 1.1 and h2 at 1.06 (new tokens `--gw-display-h1-leading`, `--gw-display-h2-leading`; at 1.02
+  the descenders of a first line touched the capitals of the second). h3 and `.gw-h3` 20px / 600, tracking −0.02em,
+  1.2 lines, as every h3 on gemboss.ai (was 24px / 650). The lead at most 58ch (was 60ch). The label's square is ink
+  with 2px corners (was the accent, square) and its line height its surroundings'; the input `--gw-label-mark` (new, on
+  the label or anything around it) paints the square another colour, a gradient too.
+- A section's head (`.gw-section__head`) up to 760px (was 660px). A lead under a heading 20px below it (in a head, a
+  split column, a CTA; 16px in the hero). What follows a head starts 40px below it, 48px from 768px, as a top margin
+  of the next thing at no specificity, so a block that brings its own keeps it (was the head's bottom margin).
+- The scroll reveal: 20px (new token `--gw-reveal-distance`, was 24px), once 12% of it is in view with the bottom 6% of
+  the view not counting (was 15%); each `.gw-reveal` after the first among its siblings waits 70ms more, at most 380ms;
+  a `[data-gw-count]` number inside counts up from 0 over 1.1s (new); the script's failsafe at 1.6s (was 2.5s). The
+  values are `system.json` `motion.reveal`.
+- `check`: `--gw-label-mark` is an input, like a mega panel's widths.
+- `website.js` is 10.4 KB gzipped (the budget is 10.5 KB, was 10 KB: the reveal's stagger and count-up).
+
 ## 0.11.0 (2026-10-26)
 
 The header, 1:1 with gemboss.ai. Since the footer (0.10.0), the header was the last part of gemboss.ai not drawn by

package/README.md

@@ -19,7 +19,8 @@ it. Made so that a team working with Claude Code, even without a designer, ships
 | `demo/` | mọi thành phần trên một trang; `theme-example.html` cho thấy một thương hiệu khác đổi màu nhấn; `brand-profiles.html` là một thương hiệu kiểu GemPages bật cả 3 hồ sơ; `article.html` là một bài blog trọn vẹn, `blog.html` là trang danh sách bài; `forms.html` là mọi trạng thái của ô nhập, newsletter ở footer, tường review và huy hiệu điểm (dữ liệu mẫu); `footer.html` là footer đầy đủ như gemboss.ai, kèm nút chuyển sang bản kiểu GemPages; `header.html` là header của gemboss.ai trên điện thoại (menu đi sâu từng mục, thanh nút dính đáy, nút đổi ngôn ngữ với ba ngôn ngữ), cũng có bản kiểu GemPages; `spotlight.html` là đốm sáng trên thẻ gói giá, thẻ link, thẻ nổi bật của mega menu và nút trong dải tối, cũng có bản kiểu GemPages |
 | `docs/` | danh mục class (`components.md`), đổi thương hiệu (`theming.md`), triết lý (`philosophy.md`), hợp đồng markup |
 | `system.json` | mọi giá trị của hệ thống (màu, khoảng cách, chữ, bo góc, bóng, khung): nguồn duy nhất |
-| CLI `gemboss-website` | `init`, `check`, `gap`, `upgrade` |
+| CLI `gemboss-website` | `init` (và `init --site`), `build`, `check`, `gap`, `upgrade` |
+| `templates/site/` | 0.13.0: bộ khung một site mới (Next.js phục vụ trang HTML tĩnh, danh sách trang, danh sách tệp công khai, `site.css`, `kit-gaps.css`), `init --site` chép ra |
 
 Cần Node 18 trở lên cho CLI. CSS và JS chạy trên mọi trình duyệt hiện đại, không cần bước build.
 
@@ -40,9 +41,9 @@ nó đọc `AGENTS.md` của kit trước, dựng từ mẫu, và chạy `check`
 **Site HTML tĩnh hoặc không có bước build:** dùng CDN của npm, ghim đúng phiên bản.
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.11.0/website.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.13.0/website.min.css">
 <link rel="stylesheet" href="/site.css">   <!-- CSS riêng của site, luôn SAU kit -->
-<script src="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.11.0/js/website.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.13.0/js/website.js" defer></script>
 ```
 
 Chèn markup của kit sau khi trang đã tải (block của builder, bản xem trước CMS): gọi `gwWebsite.init(phầnMới)` ngay
@@ -113,6 +114,8 @@ viết hoa vẫn cấm. Công thức và các phép kiểm tương phản: `docs
 | lệnh | làm gì |
 |---|---|
 | `npx gemboss-website init` | nối luật của kit vào Claude Code của dự án (CLAUDE.md + skill) |
+| `npx gemboss-website init --site` | 0.13.0: dựng một site mới như gemboss.ai và gemians.com: partial header và footer, `index.html` và `404.html` có dấu `<!-- gw:header -->` / `<!-- gw:footer -->`, `site.css`, `kit-gaps.css`, phần Next.js phục vụ trang tĩnh; không ghi đè tệp có sẵn, thêm script còn thiếu vào `package.json` |
+| `npx gemboss-website build` | 0.13.0: chép kit vào `assets/kit/`, ghi partial header và footer vào mọi trang (đánh dấu `aria-current="page"` cho link của chính trang đó); `--check` cho CI, báo đỏ khi trang chưa cập nhật |
 | `npx gemboss-website check` | kiểm mọi `.html` và `.css` của site: màu, khoảng cách, chữ, bo góc ngoài thang, bóng, nút tự tô màu, nhãn viết hoa giãn chữ, đè class `gw-`, đổi token của kit, hồ sơ thương hiệu sai tên hoặc sai chỗ, chữ trên nút màu nhấn dưới 4,5:1, dấu gạch dài, ảnh thiếu `alt`, link mơ hồ, sao thiếu giá trị bằng chữ, điểm hay review không có link nguồn, cột footer gập thiếu tiêu đề trong summary, wordmark không ẩn với trình đọc màn hình, mục của menu đi sâu thiếu nút Back hay tiêu đề, nút ngôn ngữ không ẩn sẵn hay bản dịch thiếu `hreflang`… và gợi ý chỗ kit có thể đang thiếu |
 | `npx gemboss-website gap` | báo một chỗ kit còn thiếu: mở GitHub Issue ở repo của kit (nếu `gh` đã đăng nhập và có quyền), không thì ghi `kit-gaps/<tên>.md` để gửi |
 | `npx gemboss-website upgrade` | so bản đang dùng với bản mới nhất, in thay đổi, gap đã có trong kit, và lệnh nâng cấp |

package/bin/gemboss-website.mjs

@@ -8,10 +8,21 @@ export const USAGE = `gemboss-website (${PKG.name} ${PKG.version})
 Usage: npx gemboss-website <command> [options]   (run it in the site's root folder)
 
 Commands
-  init [--force]
+  init [--force] [--site]
       Add or refresh the kit's block in CLAUDE.md (between <!-- ${PKG.name}:start/end --> markers;
       text outside them is never touched) and install the Claude Code skill
       .claude/skills/gemboss-website-ui/SKILL.md (replaced only if init wrote it, or with --force).
+        --site        also start a whole site, as gemboss.ai and gemians.com are built: the header and
+                      footer partials, index.html and 404.html with their markers, assets/site.css and
+                      kit-gaps.css, and the Next.js wrapper that serves the static pages (app/, lib/pages.mjs,
+                      next.config.mjs, stage-public.mjs, vercel.json, .gitignore). Never overwrites a file;
+                      adds the missing scripts to package.json.
+
+  build [--check]
+      Copy the kit into assets/kit/ and write partials/header.html and partials/footer.html into every
+      page between its <!-- gw:header --> / <!-- gw:footer --> markers, with aria-current="page" on
+      the header's links to that page. Pages: lib/pages.mjs pages() and 404.html (else every .html in
+      the root). --check writes nothing and exits 1 when a file is out of date (for CI).
 
   check [paths...] [--json] [--fix-list] [--ignore <path>]... [--include-kit]
       Check every .html/.htm/.css (and <style>, style="") under the paths (default: here) against
@@ -59,6 +70,7 @@ async function main(argv) {
       console.log(PKG.version);
       return 0;
     case "init": return (await import("./lib/init.mjs")).cmdInit(rest);
+    case "build": return (await import("./lib/build.mjs")).cmdBuild(rest);
     case "check": return (await import("./lib/check.mjs")).cmdCheck(rest);
     case "gap": return (await import("./lib/gap.mjs")).cmdGap(rest);
     case "upgrade": return (await import("./lib/upgrade.mjs")).cmdUpgrade(rest);

package/bin/lib/build.mjs

@@ -0,0 +1,101 @@
+// `gemboss-website build [--check]`: the parts every page of a static site shares, written into each page in place, so
+// the HTML on disk is the HTML served (0.13.0, from gemboss-www and gemians-www):
+//   1. the kit itself: website.min.css and js/website.js → assets/kit/website.css and assets/kit/website.js, as published;
+//   2. partials/header.html and partials/footer.html → between <!-- gw:header --> … <!-- /gw:header --> (and gw:footer)
+//      in every page, with aria-current="page" on the header's links to that page;
+//   3. the kit's version on its two links (?v=0.13.0), so a new kit is never served from an old cache.
+// The pages are the site's lib/pages.mjs (`pages()`: Map of URL → file, the same list its Next route serves) plus
+// 404.html; without that file, every .html in the site's root folder.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PKG, PKG_DIR, UsageError, c, parseArgs } from "./util.mjs";
+
+export const KIT_DIR = "assets/kit";
+const CURRENT = /\b(?:gw-nav__link|gw-nav__trigger|gw-mobile-menu__top|gw-mobile-menu__link|gw-mega__link)\b/;
+
+/** file → clean URL, as Vercel's cleanUrls and the site's Next route: index.html → /, a/index.html → /a, a.html → /a. */
+export function routeOf(file) {
+  const stem = file.replace(/\.html$/, "");
+  if (stem === "index") return "/";
+  return "/" + stem.replace(/\/index$/, "");
+}
+
+/** The header for one page: aria-current="page" on each of its links (nav, mobile menu, mega rows) to that URL. */
+export function markCurrent(html, route) {
+  return html.replace(/<a\b([^>]*)>/g, (tag, attrs) => {
+    const cls = (/\bclass\s*=\s*"([^"]*)"/.exec(attrs) || [])[1] || "";
+    const href = (/\bhref\s*=\s*"([^"]*)"/.exec(attrs) || [])[1];
+    if (!CURRENT.test(cls) || href !== route || /\baria-current\s*=/.test(attrs)) return tag;
+    return `<a${attrs} aria-current="page">`;
+  });
+}
+
+/** Put `body` between the page's <!-- gw:name --> markers; null when the page has none. */
+export function fillRegion(html, name, body) {
+  const re = new RegExp(`(<!-- gw:${name} -->)[\\s\\S]*?(<!-- /gw:${name} -->)`);
+  return re.test(html) ? html.replace(re, (_, a, b) => `${a}\n${body}\n${b}`) : null;
+}
+
+async function sitePages(root) {
+  const lib = join(root, "lib", "pages.mjs");
+  let files;
+  if (existsSync(lib)) {
+    const mod = await import(pathToFileURL(lib).href);
+    if (typeof mod.pages !== "function") throw new UsageError("lib/pages.mjs must export pages() (a Map of URL → file)");
+    files = [...mod.pages().entries()].map(([route, file]) => ({ route, file }));
+  } else {
+    files = readdirSync(root).filter((f) => f.endsWith(".html") && f !== "404.html").map((file) => ({ route: routeOf(file), file }));
+  }
+  if (existsSync(join(root, "404.html"))) files.push({ route: "/404", file: "404.html" });
+  return files;
+}
+
+export async function cmdBuild(argv) {
+  const opts = parseArgs(argv, { check: "bool" });
+  if (opts._.length) throw new UsageError(`build takes no arguments (got ${opts._.join(" ")}); run it in the site's root folder`);
+  const root = process.cwd();
+  const stale = [], wrote = [];
+  const put = (file, text) => {
+    const abs = resolve(root, file);
+    if (existsSync(abs) && readFileSync(abs, "utf8") === text) return;
+    if (opts.check) { stale.push(file); return; }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, text);
+    wrote.push(file);
+  };
+
+  put(`${KIT_DIR}/website.css`, `/* ${PKG.name} ${PKG.version}, copied by gemboss-website build: do not edit */\n` + readFileSync(join(PKG_DIR, "website.min.css"), "utf8"));
+  put(`${KIT_DIR}/website.js`, readFileSync(join(PKG_DIR, "js", "website.js"), "utf8"));
+
+  // a partial's leading comments are notes for its author (the kit templates' instructions), not for every page
+  const partial = (name) => { const p = join(root, "partials", `${name}.html`); return existsSync(p) ? readFileSync(p, "utf8").replace(/^(?:\s*<!--[\s\S]*?-->)+/, "").trim() : null; };
+  const header = partial("header"), footer = partial("footer");
+  const pages = await sitePages(root);
+  const problems = [];
+  for (const { route, file } of pages) {
+    const abs = join(root, file);
+    if (!existsSync(abs)) { problems.push(`${file}: listed by lib/pages.mjs, not found`); continue; }
+    let html = readFileSync(abs, "utf8");
+    for (const [name, body] of [["header", header && markCurrent(header, route)], ["footer", footer]]) {
+      if (!html.includes(`<!-- gw:${name} -->`)) continue;
+      if (body === null) { problems.push(`${file}: has <!-- gw:${name} --> but partials/${name}.html is missing`); continue; }
+      const next = fillRegion(html, name, body);
+      if (next === null) problems.push(`${file}: <!-- gw:${name} --> without its closing <!-- /gw:${name} -->`);
+      else html = next;
+    }
+    html = html.replace(/((?:href|src)\s*=\s*"\/assets\/kit\/website\.(?:css|js))(?:\?v=[^"]*)?"/g, `$1?v=${PKG.version}"`);
+    put(file, html);
+  }
+
+  for (const p of problems) console.error(`  ${c.red(p)}`);
+  if (opts.check) {
+    for (const f of stale) console.error(`  out of date: ${f}`);
+    const bad = stale.length + problems.length;
+    console.log(bad ? c.red(`build: RED, ${stale.length} file(s) out of date, ${problems.length} problem(s). Run: npx gemboss-website build`) : c.green(`build: green, ${pages.length} pages, kit ${PKG.version}`));
+    return bad ? 1 : 0;
+  }
+  for (const f of wrote) console.log(`  wrote ${f}`);
+  console.log(`build: ${pages.length} pages, kit ${PKG.version}${wrote.length ? "" : ", nothing to write"}`);
+  return problems.length ? 1 : 0;
+}

package/bin/lib/check.mjs

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { PKG, SYSTEM, UsageError, blank, c, isKitPath, lineIndex, parseArgs, rel, walkFiles } from "./util.mjs";
-import { MIN_CONTRAST, actionPairs, ratio } from "./contrast.mjs";
+import { MIN_CONTRAST, actionPairs, contrast, ratio } from "./contrast.mjs";
 
 const RADII = new Set(SYSTEM.radius.scale);
 // A brand's named profiles (system.json `profiles`): one attribute on <html> each, and the floating header's class.
@@ -31,7 +31,7 @@ export const RULES = {
   },
   "token-redefined": {
     level: "error", title: "Kit token redefined",
-    why: "A brand chooses its accent family and wash hues (variables), its logo, and three named profiles; nothing else. Changing another --gw-* token changes every component on the site.",
+    why: "A brand chooses its accent family and wash hues (variables), the colours of its announcement bar and of its Stage (--gw-announce-*, --gw-stage-*), its logo, and three named profiles; nothing else. Changing another --gw-* token changes every component on the site.",
     fix: `Remove it. The action colour and the corners are profiles, not tokens: ${profileList()} on <html>; the floating header is the class ${FLOAT_CLASS} (docs/theming.md). If the brand needs something else, report a gap: npx gemboss-website gap --kind token.`,
   },
   "radius-off-scale": {
@@ -129,6 +129,16 @@ export const RULES = {
     why: `With data-gw-action="accent" the primary button is filled with the brand's accent. Its words (--gw-on-accent) must reach ${MIN_CONTRAST}:1 on --gw-accent and on --gw-accent-strong (hover and pressed), in light and in dark, or the main action of every page is hard to read.`,
     fix: "Darken --gw-accent-light and --gw-accent-strong-light (or change --gw-on-accent-light), lighten the -dark ones (dark words on them), until every pair passes; write them as #rrggbb. Or keep the ink button: remove data-gw-action.",
   },
+  "brand-contrast": {
+    level: "error", title: "Words on the brand's announcement bar or Stage below 4.5:1",
+    why: `A brand that sets its own announcement bar (--gw-announce-*) or Stage (--gw-stage-*) picks colours the kit cannot check for it: the bar's words and its link on its ground, and the Stage's words on both ends of its gradient, must reach ${MIN_CONTRAST}:1, or the sentence over every page and the mega menu's pictures are hard to read.`,
+    fix: "Darken the ground (--gw-announce-bg, --gw-stage-top, --gw-stage-bottom) or lighten the words (--gw-announce-ink, --gw-announce-link, --gw-stage-ink) until every pair passes; write them as #rrggbb.",
+  },
+  "brand-markup": {
+    level: "error", title: "Brand logo without its markup",
+    why: "A logo drawn as one file (.gw-brand__logo, the mark and the wordmark together) stands in for the brand's name: its alt is that name, or the home link has no name for a screen reader. Its width and height keep the bar from jumping while it loads. A file for dark grounds (.gw-brand__logo--dark) is the same logo in another colour and needs the first one right before it.",
+    fix: "Write <a class=\"gw-brand\" href=\"/\"><img class=\"gw-brand__logo\" src=\"/logo.png\" alt=\"Brand\" width=\"150\" height=\"26\"><img class=\"gw-brand__logo gw-brand__logo--dark\" src=\"/logo-on-dark.png\" alt=\"Brand\" width=\"150\" height=\"26\"></a> (docs/theming.md, the logo).",
+  },
   "toc-target": {
     level: "error", title: "Contents link to a heading that is not on the page",
     why: "A .gw-toc link whose #id names no element on the page jumps nowhere, and website.js cannot mark its section. It happens when a heading is renamed or removed and the list is not.",
@@ -336,9 +346,12 @@ const ATTR_THEME = String.raw`\[\s*data-theme(?:\s*[~|^$*]?=\s*(?:"[^"]*"|'[^']*
 const ROOTISH = new RegExp(`^(?::root|html)?(?:${ATTR_THEME}|:not\\(\\s*${ATTR_THEME}\\s*\\))*$`, "i");
 const isRootish = (sel) => splitTop(sel).every((s) => s && ROOTISH.test(s));
 // set on one element in the markup, read by the kit's CSS: the stars' value (style="--gw-stars: 4.9"); a mega panel's width,
-// its pictures' width and its columns (0.11.0: style="--gw-mega-w: 1120px; --gw-mega-pv: 380px; --gw-mega-cols: 2")
-const INPUTS = new Set(["--gw-stars", "--gw-mega-w", "--gw-mega-pv", "--gw-mega-cols"]);
-const THEMABLE = /^--gw-(?:accent(?:-[\w-]+)?|on-accent(?:-(?:light|dark))?|wash(?:-[\w-]+)?)$/; // docs/theming.md: the eight accent variables (-light/-dark) + wash
+// its pictures' width and its columns (0.11.0: style="--gw-mega-w: 1120px; --gw-mega-pv: 380px; --gw-mega-cols: 2"); the colour of
+// a label's square (0.12.0: --gw-label-mark, on the label or around it)
+const INPUTS = new Set(["--gw-stars", "--gw-mega-w", "--gw-mega-pv", "--gw-mega-cols", "--gw-label-mark"]);
+// docs/theming.md: the eight accent variables (-light/-dark), the wash, and (0.13.0) the announcement bar's and the
+// Stage's colours, which system.json always said a brand sets
+const THEMABLE = /^--gw-(?:accent(?:-[\w-]+)?|on-accent(?:-(?:light|dark))?|wash(?:-[\w-]+)?|announce-[\w-]+|stage-[\w-]+)$/;
 
 const COLOR_PROPS = /^(?:color|background(?:-color|-image)?|border(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?(?:-color)?|outline(?:-color)?|fill|stroke|text-decoration(?:-color)?|caret-color|accent-color|column-rule(?:-color)?|text-emphasis(?:-color)?|-webkit-text-fill-color|-webkit-text-stroke(?:-color)?|scrollbar-color|stop-color|flood-color|lighting-color)$/;
 const NAMED = new Set(("white black red green blue yellow orange purple pink gray grey silver gold navy teal maroon olive lime aqua " +
@@ -479,6 +492,28 @@ function brandAccent(cssRules, page) {
   return vals;
 }
 
+/** The brand's announcement bar and Stage, when its CSS sets them: their words on their grounds (brand-contrast). */
+function checkBrandContrast(out, add) {
+  const vals = {};
+  for (const { file, rules } of out.cssRules.filter((x) => !x.inline)) {
+    for (const r of rules) {
+      if (r.atBlock || r.at.length || !r.selector || !isRootish(r.selector)) continue;
+      for (const d of r.decls) if (/^--gw-(?:announce|stage)-/.test(d.prop)) vals[d.prop] = { value: d.value.replace(/!important\s*$/i, "").trim(), at: `${file}:${d.line}` };
+    }
+  }
+  const pairs = [["announce", "ink", "bg"], ["announce", "link", "bg"], ["stage", "ink", "top"], ["stage", "ink", "bottom"]];
+  for (const [part, text, ground] of pairs) {
+    const t = vals[`--gw-${part}-${text}`], g = vals[`--gw-${part}-${ground}`];
+    if (!t && !g) continue; // the kit's own pair, checked by the kit
+    const kit = (k) => SYSTEM.color[part][k];
+    const tv = t ? t.value : kit(text), gv = g ? g.value : kit(ground);
+    const r = contrast(tv, gv);
+    if (r !== null && r >= MIN_CONTRAST) continue;
+    const at = (t || g).at, [file, line] = [at.slice(0, at.lastIndexOf(":")), Number(at.slice(at.lastIndexOf(":") + 1))];
+    add("brand-contrast", { file, line, excerpt: `--gw-${part}-${text} ${tv} on --gw-${part}-${ground} ${gv} ${r === null ? "cannot be read as a colour (write #rrggbb)" : `is ${ratio(r)}, needs ${MIN_CONTRAST}:1`}` });
+  }
+}
+
 /** Pages with data-gw-action="accent": the words of the primary button on its fills, light and dark (action-contrast). */
 function checkActionContrast(out, add) {
   for (const pg of out.pageProfiles.filter((p) => p.action === "accent")) {
@@ -658,6 +693,15 @@ function analyzeHtml(file, text, out) {
       ].filter(Boolean);
       if (missing.length) add("stars-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 100)}  missing: ${missing.join(", ")}`));
     }
+    if (tag === "img" && cls.includes("gw-brand__logo")) {
+      const before = scanText.slice(0, m.index).replace(/\s+$/, "");
+      const missing = [
+        !(a.alt || "").trim() && "alt with the brand's name (the logo stands in for it)",
+        !(a.width && a.height) && "width and height",
+        cls.includes("gw-brand__logo--dark") && !/<img\b[^>]*\bclass\s*=\s*["'][^"']*\bgw-brand__logo\b(?![\w-])[^"']*["'][^>]*>$/i.test(before) && "the light file right before it (<img class=\"gw-brand__logo\">)",
+      ].filter(Boolean);
+      if (missing.length) add("brand-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 80)}  missing: ${missing.join(", ")}`));
+    }
     if (cls.includes("gw-footer__wordmark") && (a["aria-hidden"] || "").trim() !== "true") {
       add("footer-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 80)}  missing: aria-hidden="true" (the wordmark is decoration)`));
     }
@@ -824,6 +868,7 @@ export function runCheck(paths, { ignore = [], includeKit = false } = {}) {
   }
 
   checkActionContrast(out, add);
+  checkBrandContrast(out, add);
 
   // Classes styled in site CSS: first definition of each.
   const styled = new Map();

package/bin/lib/init.mjs

@@ -1,5 +1,5 @@
 // `gemboss-website init`: connect the kit's rules to the project's Claude Code (CLAUDE.md block + skill).
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { PKG_DIR, PKG_NAME, UsageError, parseArgs, rel } from "./util.mjs";
 
@@ -59,8 +59,87 @@ export function upsertBlock(text, block) {
   return { text: text + sep + b + eol, action: "added" };
 }
 
+// ------------------------------------------------------------------------------------------- init --site
+
+/** The files a new site owns from the start, from templates/site/ (gitignore → .gitignore: npm drops dotfiles). */
+function siteTemplateFiles(dir = join(PKG_DIR, "templates", "site"), base = "") {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const abs = join(dir, name), r = base ? `${base}/${name}` : name;
+    if (statSync(abs).isDirectory()) out.push(...siteTemplateFiles(abs, r));
+    else out.push({ from: abs, to: r === "gitignore" ? ".gitignore" : r });
+  }
+  return out;
+}
+
+/**
+ * A page of the site from templates/page.html: the header and footer become the build's markers, the kit's paths the
+ * site's (assets/kit/), and kit-gaps.css follows site.css. `main` replaces the template's <main> when given.
+ */
+export function sitePage(main) {
+  let html = readFileSync(join(PKG_DIR, "templates", "page.html"), "utf8");
+  const cut = (re, what) => { if (!re.test(html)) throw new Error(`templates/page.html: no ${what} to replace`); html = html.replace(re, ""); };
+  html = html.replace(/<!--\s*\n\s*Page skeleton:[\s\S]*?-->\n/, `<!-- A page of this site. Its header and footer are partials/header.html and partials/footer.html, written between the
+     markers by \`npx gemboss-website build\`. Compose <main> from node_modules/${PKG_NAME}/templates/sections/. -->\n`);
+  cut(/\n\s*<div class="gw-announce"[\s\S]*?<\/header>\n/, "header");
+  html = html.replace(/(<a class="gw-skip"[^\n]*\n)/, "$1  <!-- gw:header -->\n  <!-- /gw:header -->\n\n");
+  cut(/\n\s*<!-- the short footer[^\n]*-->\s*<footer class="gw-footer">[\s\S]*?<\/footer>\n/, "footer");
+  html = html.replace(/(\s*<\/main>\n)/, "$1\n  <!-- gw:footer -->\n  <!-- /gw:footer -->\n");
+  html = html.split("[/kit]").join("/assets/kit").replace("[/assets]/site.css", "/assets/site.css")
+    .replace(/(<link rel="stylesheet" href="\/assets\/site\.css">)/, '$1\n  <link rel="stylesheet" href="/assets/kit-gaps.css">')
+    .replace("[/favicon.svg]", "/favicon.svg");
+  if (main) html = html.replace(/<main id="main">[\s\S]*?<\/main>/, `<main id="main">\n${main}\n  </main>`);
+  return html;
+}
+
+const NOT_FOUND_MAIN = `    <section class="gw-hero gw-hero--compact">
+      <div class="gw-wrap">
+        <p class="gw-label">404</p>
+        <h1><span class="gw-dim">This page is not here.</span> The rest of the site is.</h1>
+        <div class="gw-actions">
+          <a class="gw-btn" href="/">Go to the home page</a>
+        </div>
+      </div>
+    </section>`;
+
+export const SITE_SCRIPTS = {
+  "build:site": "gemboss-website build",
+  build: "gemboss-website build && node stage-public.mjs && next build",
+  start: "next start",
+  check: "gemboss-website build --check && node stage-public.mjs --check && gemboss-website check . --ignore node_modules --ignore public",
+};
+export const SITE_DEPS = "next@16.4.2 react@19.2.8 react-dom@19.2.8";
+
+function initSite(cwd, done) {
+  const write = (to, text) => {
+    const abs = resolve(cwd, to);
+    if (existsSync(abs)) { done.push([to, "kept (exists)"]); return; }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, text);
+    done.push([to, "created"]);
+  };
+  for (const { from, to } of siteTemplateFiles()) write(to, readFileSync(from, "utf8"));
+  write("partials/header.html", readFileSync(join(PKG_DIR, "templates", "header.html"), "utf8"));
+  write("partials/footer.html", readFileSync(join(PKG_DIR, "templates", "footer.html"), "utf8"));
+  write("index.html", sitePage());
+  write("404.html", sitePage(NOT_FOUND_MAIN).replace("<title>[Page title] · [Brand]</title>", "<title>Page not found · [Brand]</title>"));
+
+  const pkgPath = resolve(cwd, "package.json");
+  const pkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, "utf8")) : { name: "[site]-www", private: true, type: "module" };
+  pkg.scripts = pkg.scripts || {};
+  const added = Object.keys(SITE_SCRIPTS).filter((k) => !(k in pkg.scripts));
+  for (const k of added) pkg.scripts[k] = SITE_SCRIPTS[k];
+  const typed = pkg.type === "module";
+  if (!typed && !pkg.type) pkg.type = "module";
+  if (added.length || !existsSync(pkgPath) || !typed) {
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    done.push(["package.json", added.length ? `scripts added: ${added.join(", ")}` : "written"]);
+  } else done.push(["package.json", "scripts already there"]);
+  if (pkg.type !== "module") done.push(["package.json", `"type" is "${pkg.type}": the .mjs files work, next.config.mjs too`]);
+}
+
 export function cmdInit(argv) {
-  const opts = parseArgs(argv, { force: "bool" });
+  const opts = parseArgs(argv, { force: "bool", site: "bool" });
   if (opts._.length) throw new UsageError(`init takes no arguments (got ${opts._.join(" ")}); run it in the project's root folder`);
   const cwd = process.cwd();
   const done = [];
@@ -89,11 +168,22 @@ export function cmdInit(argv) {
     }
   }
 
+  if (opts.site) initSite(cwd, done);
+
   const w = Math.max(...done.map(([p]) => p.length));
   console.log(`gemboss-website init (${PKG_NAME})`);
   for (const [p, what] of done) console.log(`  ${p.padEnd(w)}  ${what}`);
   console.log("");
   console.log(`Claude Code now reads ${KIT}/AGENTS.md before website work in this project.`);
-  console.log("Next: start a page from the kit's templates/page.html, then run: npx gemboss-website check");
+  if (opts.site) {
+    console.log("Next:");
+    console.log(`  1. npm install ${SITE_DEPS}`);
+    console.log("  2. Fill partials/header.html and partials/footer.html once (delete what the site does not use),");
+    console.log("     the brand's :root block in assets/site.css, and add favicon.svg");
+    console.log("  3. npm run build:site, then compose index.html from the kit's templates/sections/");
+    console.log("  4. npm run check, and look at every page at 320px and 1366px");
+  } else {
+    console.log("Next: start a page from the kit's templates/page.html, then run: npx gemboss-website check");
+  }
   return 0;
 }

package/css/article.css

@@ -203,7 +203,7 @@
    .gw-card__media first, a .gw-label for the category, the title (its link covers the card, so the card is one target
    and the link's name is the title alone), one or two lines of excerpt and a .gw-article-meta row at the foot. One
    column on phones, two from 768px, three from 1080px. --compact: one column of rows, no card and no picture. */
-.gw-post-list { display: grid; grid-template-columns: minmax(0, 1fr); gap: 16px; margin: 0; padding: 0; list-style: none; }
+.gw-post-list { display: grid; grid-template-columns: minmax(0, 1fr); gap: 16px; padding: 0; list-style: none; }
 .gw-post-list > li { display: flex; min-width: 0; }
 .gw-post { position: relative; display: flex; flex: 1 1 auto; flex-direction: column; min-width: 0; }
 .gw-post:hover { border-color: var(--gw-line-strong); }

package/css/base.css

@@ -32,33 +32,34 @@ h1, h2, h3, h4, h5, h6, .gw-h1, .gw-h2, .gw-h3, .gw-h4 {
   text-wrap: balance;
 }
 h1, .gw-h1, h2, .gw-h2 { font-weight: var(--gw-display-weight); letter-spacing: var(--gw-display-tracking); }
-h1, .gw-h1 { font-size: var(--gw-display-h1); }
-h2, .gw-h2 { font-size: var(--gw-display-h2); }
-h3, .gw-h3 { font-size: 24px; }
+h1, .gw-h1 { font-size: var(--gw-display-h1); line-height: var(--gw-display-h1-leading); }
+h2, .gw-h2 { font-size: var(--gw-display-h2); line-height: var(--gw-display-h2-leading); }
+/* h3 (0.12.0): 20px/600, as every h3 on gemboss.ai */
+h3, .gw-h3 { font-size: 20px; font-weight: 600; letter-spacing: -0.02em; line-height: 1.2; }
 h4, .gw-h4 { font-size: 20px; font-weight: 600; letter-spacing: -0.01em; }
 h5, h6 { font-size: 16px; font-weight: 600; letter-spacing: 0; }
 
-.gw-lead { font-size: 18px; line-height: 1.55; color: var(--gw-muted); max-width: 60ch; }
+.gw-lead { font-size: 18px; line-height: 1.55; color: var(--gw-muted); max-width: 58ch; }
 .gw-note { font-size: 14px; color: var(--gw-muted); }
 .gw-dim { color: var(--gw-muted); }
 
-/* the label above a heading: sentence case, muted, led by the 8px accent square */
+/* the label above a heading: sentence case, muted, led by the 8px square, ink by default (0.12.0, as gemboss.ai). The
+   input --gw-label-mark paints the square another colour (a product's own, say): set it on the label or on anything
+   around it, e.g. style="--gw-label-mark: var(--gw-accent)". */
 .gw-label {
   display: inline-flex;
   align-items: center;
   gap: 8px;
   font-size: 13px;
   font-weight: 500;
-  line-height: 1.4;
   color: var(--gw-muted);
 }
 .gw-label::before {
   content: "";
-  flex: none;
   width: 8px;
   height: 8px;
-  border-radius: var(--gw-radius-0);
-  background: var(--gw-accent);
+  border-radius: var(--gw-radius-2);
+  background: var(--gw-label-mark, var(--gw-ink));
 }
 
 /* links inside running text (and anywhere in .gw-prose) get a visible link style; everything else opts in with .gw-link */
@@ -78,19 +79,22 @@ h5, h6 { font-size: 16px; font-weight: 600; letter-spacing: 0; }
 :focus-visible { border-radius: var(--gw-radius-4); outline: 2px solid var(--gw-accent); outline-offset: 3px; }
 [id] { scroll-margin-top: calc(var(--gw-header-height) + 16px); }
 
+/* the skip link (0.12.0, gemboss.ai's): the accent tab in the top left corner, shown while it has the focus */
 .gw-skip {
   position: absolute;
   left: -9999px;
-  top: 8px;
-  z-index: 100;
-  padding: 12px 16px;
-  border-radius: var(--gw-radius-action);
-  background: var(--gw-action);
-  color: var(--gw-on-action);
+  top: 0;
+  z-index: 200;
+  padding: 12px 20px;
+  border-radius: 0 0 var(--gw-radius-card) 0;
+  background: var(--gw-accent);
+  color: var(--gw-on-accent);
+  box-shadow: var(--gw-shadow);
   font-size: 14px;
   font-weight: 600;
 }
-.gw-skip:focus { left: 16px; }
+/* its corner again with the focus: a page's own :focus-visible corners, loaded after the kit, must not round the tab */
+.gw-skip:focus { left: 0; border-radius: 0 0 var(--gw-radius-card) 0; }
 
 /* words for a screen reader only (0.7.0): " (opens in a new tab)" in a link with target="_blank" */
 .gw-visually-hidden {
@@ -104,10 +108,11 @@ h5, h6 { font-size: 16px; font-weight: 600; letter-spacing: 0; }
   border: 0;
 }
 
-/* scroll reveal: the script adds .is-in; the animation is a failsafe that shows it anyway after 2.5s */
+/* scroll reveal: the script adds .is-in (system.json motion.reveal: when, the stagger, the failsafe); the animation is
+   a second failsafe, for a page whose script never ran, that shows it anyway after 2.5s */
 .gw-reveal {
   opacity: 0;
-  transform: translateY(24px);
+  transform: translateY(var(--gw-reveal-distance));
   transition: opacity var(--gw-reveal-ms) var(--gw-ease), transform var(--gw-reveal-ms) var(--gw-ease);
   animation: gw-reveal-failsafe 1ms linear 2.5s forwards;
 }