@gemboss/website-ui 0.12.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,43 @@ 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,

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.12.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.12.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.",
@@ -339,7 +349,9 @@ const isRootish = (sel) => splitTop(sel).every((s) => s && ROOTISH.test(s));
 // 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"]);
-const THEMABLE = /^--gw-(?:accent(?:-[\w-]+)?|on-accent(?:-(?:light|dark))?|wash(?:-[\w-]+)?)$/; // docs/theming.md: the eight accent variables (-light/-dark) + wash
+// 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 " +
@@ -480,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")) {
@@ -659,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)`));
     }
@@ -825,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/components.css

@@ -266,6 +266,13 @@
 }
 .gw-window__body:has(> img:only-child) + .gw-window__caption { padding-top: 12px; }
 
+/* figure (0.13.0, Gemians): a photo and its caption where a section shows one outside the prose (beside words in a
+   split, under a hero's actions): the picture at the card radius, the caption 14px, muted, 12px under it, as a figure
+   in .gw-prose. A screen of the product goes in .gw-window instead. */
+.gw-figure > :is(img, video, picture) { display: block; width: 100%; height: auto; border-radius: var(--gw-radius-card); }
+.gw-figure > picture > img { display: block; width: 100%; height: auto; border-radius: inherit; }
+.gw-figure > figcaption { margin-top: 12px; color: var(--gw-muted); font-size: 14px; line-height: 1.5; }
+
 /* icon: 20px inline stroke SVG (1.7 to 2px stroke, currentColor) */
 .gw-icon { display: inline-flex; align-items: center; justify-content: center; flex: none; width: 20px; height: 20px; }
 .gw-icon svg { width: 20px; height: 20px; }

package/css/header.css

@@ -703,3 +703,16 @@ html.is-menu-open .gw-header:has(> .gw-mobile-menu.is-drill) { position: sticky;
   :root:not([data-theme="light"]) .gw-theme-toggle__sun { display: block; }
   :root:not([data-theme="light"]) .gw-theme-toggle__moon { display: none; }
 }
+
+/* ---- 0.13.0: the brand's logo as one drawing (Gemians): the mark and the wordmark in one file, in place of the mark and
+   the name, 26px tall, its width the file's. Its alt is the brand's name. A logo drawn for dark grounds only (a white
+   wordmark) comes as a second file, .gw-brand__logo--dark, right after the first: it shows in dark (the system's or the
+   toggle's) and the first one hides, the toggle icons' rule. One file that reads on both: no --dark. */
+.gw-brand__logo { display: block; flex: none; width: auto; height: 26px; }
+.gw-brand__logo--dark { display: none; }
+:root[data-theme="dark"] .gw-brand__logo--dark { display: block; }
+:root[data-theme="dark"] .gw-brand__logo:has(+ .gw-brand__logo--dark) { display: none; }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) .gw-brand__logo--dark { display: block; }
+  :root:not([data-theme="light"]) .gw-brand__logo:has(+ .gw-brand__logo--dark) { display: none; }
+}

package/css/ratings.css

@@ -26,7 +26,6 @@
   display: grid;
   grid-template-columns: minmax(0, 1fr);
   gap: 16px;
-  margin: 0;
   padding: 0;
   list-style: none;
 }

package/css/sections.css

@@ -13,7 +13,7 @@
     radial-gradient(420px 320px at 52% 118%, color-mix(in srgb, var(--gw-wash-mint) 10%, transparent), transparent 62%);
 }
 .gw-hero h1 .gw-dim { display: block; }
-.gw-hero > .gw-wrap > .gw-window { margin-top: 48px; }
+.gw-hero > .gw-wrap > :is(.gw-window, .gw-figure) { margin-top: 48px; }
 .gw-hero--center { text-align: center; }
 .gw-hero--center > .gw-wrap > * { margin-inline: auto; }
 .gw-hero--center .gw-actions { justify-content: center; }
@@ -46,7 +46,7 @@
 .gw-logos img { width: auto; height: 28px; }
 
 /* stats: three or four facts, each with its source */
-.gw-stats { display: grid; grid-template-columns: minmax(0, 1fr); gap: 24px; margin: 0; padding: 0; list-style: none; }
+.gw-stats { display: grid; grid-template-columns: minmax(0, 1fr); gap: 24px; padding: 0; list-style: none; }
 .gw-stats__value { font-size: var(--gw-display-h2); font-weight: 600; letter-spacing: -0.03em; line-height: 1.1; font-variant-numeric: tabular-nums; }
 .gw-stats__label { margin-top: 8px; max-width: 28ch; color: var(--gw-muted); font-size: 14px; }
 .gw-stats__source { margin-top: 8px; color: var(--gw-muted); font-size: 12px; }
@@ -79,7 +79,6 @@
   display: grid;
   grid-template-columns: minmax(0, 1fr);
   gap: 32px 24px;
-  margin: 0;
   padding: 0;
   list-style: none;
   counter-reset: gw-step;

package/demo/header.html

@@ -44,7 +44,7 @@
 <body class="gw-page">
   <a class="gw-skip" href="#main">Skip to content</a>
 
-  <div class="gw-announce" role="region" aria-label="Announcement"><span class="gw-announce__tag">NEW</span> The GemBoss community is live. <a href="https://community.gemboss.ai">Join founders building brand-true stores &rarr;</a></div>
+  <div class="gw-announce" role="region" aria-label="Announcement"><span class="gw-announce__tag">New</span> The GemBoss community is live. <a href="https://community.gemboss.ai">Join founders building brand-true stores &rarr;</a></div>
   <header class="gw-header" data-gw-header>
     <div class="gw-header__bar">
       <a class="gw-brand" href="https://gemboss.ai/" data-gw-show="brand:gemboss"><svg class="gw-brand__mark" viewBox="0 0 100 116" aria-hidden="true"><polygon points="26,14 74,14 66,50 34,50" style="fill:var(--gw-accent)"/><path d="M26,14 74,14 96,50 50,110 4,50Z" fill="none" stroke="currentColor" stroke-width="9" stroke-linejoin="round"/><path d="M4,50H96M26,14 34,50M74,14 66,50M34,50 50,110M66,50 50,110" fill="none" stroke="currentColor" stroke-width="5.6" stroke-linejoin="round"/></svg><span class="gw-brand__name">GemBoss</span></a><a class="gw-brand" href="header.html#gempages" data-gw-show="brand:gempages" hidden><svg class="gw-brand__mark" viewBox="0 0 26 26" aria-hidden="true"><rect width="26" height="26" rx="7" style="fill:var(--gw-accent)"/><path d="M8 9h10M8 13h10M8 17h6" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round"/></svg><span class="gw-brand__name">Example brand</span></a>

package/docs/components.md

@@ -274,6 +274,24 @@ the mock-up shows a demo brand ("Vital Glow is a GemBoss demo brand."). Under re
 Don't: put interactive controls inside a mock-up; show made-up numbers without the caption; write the caption in
 other words ("Sample", "Demo numbers") or leave it in English on a translated page.
 
+### Figure `.gw-figure`
+
+0.13.0 (Gemians): a photo and its caption outside the prose, where a section shows one: beside the words of a split,
+under a hero's actions (48px below, as a window). The picture takes the card radius; the `<figcaption>` is 14px,
+muted, 12px under it, the look of a figure inside `.gw-prose`. A screen of the product goes in `.gw-window`; a photo
+of people, a place or a product goes here.
+
+```html
+<figure class="gw-figure">
+  <img src="/img/team-2025.webp" alt="The team together in the office, 2025" width="1000" height="471" loading="lazy">
+  <figcaption>The GemCommerce team, 2025.</figcaption>
+</figure>
+```
+
+Don't: a photo of people without their permission, or of another brand without its; a caption that repeats the alt
+word for word (the alt says what is in the picture, the caption says what it is); a frame, a shadow or a radius of
+your own.
+
 ### Icon `.gw-icon`
 
 A 20px box for an inline stroke SVG (1.7–2px stroke, `currentColor`, `aria-hidden="true"`). Inside `.gw-feature` it
@@ -341,6 +359,7 @@ level. A brand changes what it fills in and the tokens (colours, the Stage, the
 | `.gw-header--float` | with `.gw-header`, a brand's header profile: from 1081px the same bar as an inset card (panel radius, the surface at 85% over a blur, one hairline, the raised shadow, 16px from the top); the flat bar up to 1080px; solid under `prefers-reduced-transparency` |
 | `.gw-header__bar` | the row inside: the page's wrap + 12px (1132px on GemBoss), 24px inside (6px up to 640px), 32px between its parts |
 | `.gw-brand`, `__mark`, `__name` | logo (34px, its corners clipped at 8px) and name, linking home; a 44px row up to 768px |
+| `.gw-brand__logo`, `--dark` | 0.13.0: a brand's logo drawn as one file (mark and wordmark), 26px tall, in place of `__mark` and `__name`, `alt` the brand's name; `--dark` a second file shown in dark only, right after the first (docs/theming.md) |
 | `.gw-nav`, `__list`, `__item`, `__trigger`, `__chev`, `__link` | the desktop nav (from 1081px), 14px weight 500, 0.005em tighter; `__trigger` is a section's link that opens its mega panel (its 12px `__chev` turns while open), `__link` a plain link; the current page (`aria-current="page"`) or section (`aria-current` on a trigger) in the accent's strong ink, weight 600 |
 | `.gw-mega` (`--gw-mega-w`, `--gw-mega-pv`, `--gw-mega-cols`), `__body`, `__grid`, `__col`, `__heading`, `__link`, `__aside`, `__card`, `__art`, `__card-text`, `__go`, `__foot`, `__foot-start`, `__foot-end`, `__cta`, `__new` | 0.11.0, gemboss.ai's mega menu: a panel on one surface that morphs between panels (the popover radius, raised shadow), a caret at the open name, a pill under the hovered name, a highlight under the hovered row; columns of rows (a name and one line), the pictures beside them (`__aside`: the panel's own `__card`, a row's preview from its `<template>`), each picture on the Stage (`__art`: the deep iris ground, `--gw-stage-*`); an optional strip under it. The page behind dims and blurs (`.gw-scrim`). Script: `docs/markup-contract.md` |
 | `.gw-header__actions` | Sign in, a second text action, Start free, the menu button (4px apart; the button 8px further) |