@gemboss/website-ui 0.3.0 → 0.5.0

package/AGENTS.md

@@ -10,12 +10,14 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 | file | what it is |
 |---|---|
 | `website.css` | the whole kit, one file (tokens, base, layout, components, sections) |
-| `js/website.js` | header, mega menu, mobile menu, theme toggle, scroll reveal, segmented control, busy buttons; no dependencies |
+| `js/website.js` | header, mega menu, mobile menu, theme toggle, scroll reveal, segmented control, busy buttons, an article's contents and its tables' scroll box; no dependencies; `window.gwWebsite.init(root)` |
+| `js/website.mjs` | the same script as an ES module for apps: `import { init, destroy } from '@gemboss/website-ui/website.mjs'` |
 | `system.json` | every value of the system: colours, spacing, type, radii, shadows, widths |
 | `templates/page.html` | the page skeleton: start every new page from it |
-| `templates/sections/*.html` | ready sections: hero, features, split, showcase, logos, stats, steps, pricing, FAQ, CTA, prose… |
+| `templates/sections/*.html` | ready sections: hero, features, split, showcase, logos, stats, steps, pricing, FAQ, CTA, prose, article, post list… |
 | `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) |
 | `docs/components.md` | every class, what it is for, its variants |
 | `docs/theming.md` | what a brand other than GemBoss chooses (accent, wash, logo, three named profiles), and what it must not change |
 
@@ -58,6 +60,10 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
    stats) → 2 to 4 feature sections → one showcase or split → FAQ → final CTA. Not every page needs every section;
    fewer, clearer sections beat more. A page that is read rather than scanned (a blog post, docs, terms, privacy) is
    the prose section: the article's own HTML inside `.gw-prose`, no classes and no site CSS for its type.
+   **An article page (a blog post, a guide) is `templates/sections/article.html`**: breadcrumbs, the meta row
+   (author, category, date, read time), a contents list (`.gw-toc`) built from the article's h2s, the prose, callouts
+   where they help, the FAQ last. Never a callout told by its colour alone: it always carries its label in words
+   (Note, Tip, Warning). The blog index and "more from the blog" are `templates/sections/post-list.html`.
 3. Write the copy (section 6), then delete what you did not use. Do not leave empty slots or sample text.
 4. Images: real product screens or photos the brand owns. Give every `<img>` a real `alt` (or `alt=""` when it is
    decoration), `width`, `height`, and `loading="lazy"` below the first screen.
@@ -67,8 +73,8 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 
 - **Colour roles** (CSS variables, light and dark): `--gw-bg`, `--gw-bg-soft` (the neutral raised fill),
   `--gw-surface`, `--gw-ink`, `--gw-ink-2`, `--gw-muted`, `--gw-line`, `--gw-line-strong`, `--gw-action`,
-  `--gw-on-action`, `--gw-accent`, `--gw-accent-strong`, `--gw-accent-soft`, `--gw-success`, `--gw-warning`,
-  `--gw-night` (the dark band). Wash hues `--gw-wash-pink|violet|sky|mint` exist for the hero wash and illustrations only.
+  `--gw-on-action`, `--gw-accent`, `--gw-accent-strong`, `--gw-accent-soft`, `--gw-success`, `--gw-warning` (and
+  their tints `--gw-success-soft`, `--gw-warning-soft`), `--gw-night` (the dark band). Wash hues `--gw-wash-pink|violet|sky|mint` exist for the hero wash and illustrations only.
 - **Dark mode** follows the visitor's system and the theme toggle (`data-theme` on `<html>`). Use the variables and
   it works; a hard-coded colour breaks it.
 - **Accent as text** (links, the active menu item, step numbers) is `--gw-accent-strong`; the plain accent is for
@@ -115,10 +121,16 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 - Don't invent numbers, customer names, logos, testimonials, ratings, awards or certifications.
 - Don't write fake numbers on a mock-up without the caption "Illustrative data." under it, and don't reword it.
 - Don't style an article's headings, lists or code in site CSS; wrap the article in `.gw-prose`.
+- Don't make a callout whose kind only its colour tells: `.gw-callout` starts with its `.gw-callout__label` in words.
+- Don't type separators (›, /, >) between breadcrumbs, and don't build a contents list whose links point at ids the
+  page does not have: build it from the article's own h2s.
 - Don't animate layout properties (width, height, top, margin), and don't autoplay motion that cannot be stopped.
 - Don't ship a page you have not seen at 320px.
 - Don't write CSS that overrides a `.gw-*` class to change how it looks. If the kit's version is wrong for you,
   that is a gap (section 9).
+- Don't wire kit components with your own JS (no click handler on a trigger, no class toggled by hand). After you
+  insert kit markup (a route change, a block rendered later), call `gwWebsite.init(root)` on it, or `init(root)` from
+  `website.mjs`.
 
 ## 5. Accessibility
 
@@ -132,6 +144,8 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
   (a `.gw-note` or a `role="status"` line). Under `prefers-reduced-motion` the kit's ring stands still.
 - A single choice is a radio group (`.gw-segmented`): one Tab stop, the arrows move and choose. Never a row of
   `aria-pressed` buttons for it.
+- A wide table gets a scroll box a keyboard can reach: the `.gw-table` wrapper, or, for a bare table in `.gw-prose`,
+  the box `website.js` adds. Give the table a `<caption>`: it names the box.
 
 ## 6. Words
 
@@ -208,7 +222,8 @@ It reports colours, radii, spacing and type outside the system, shadows on chrom
 uppercase labels, em dashes in visible text, images without `alt`, overrides of `.gw-*` classes, redefined kit tokens,
 a waiting button not marked with `aria-busy`, a segmented control without its radio-group markup, a drawn mock-up
 with numbers and no caption, an unknown brand profile or one set off `<html>`, `.gw-header--float` off the header,
-words on the accent button below 4.5:1, and patterns that repeat across pages (likely gaps). It does not replace looking at the page at 320px and 1366px.
+words on the accent button below 4.5:1, breadcrumbs without their markup, a contents link to an id that is not on
+the page, a callout without its label, and patterns that repeat across pages (likely gaps). It does not replace looking at the page at 320px and 1366px.
 
 ## 11. Upgrading the kit
 

package/CHANGELOG.md

@@ -4,6 +4,99 @@ 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.5.0 (2026-10-25)
+
+The blog release: the parts around a long article and the blog index, so a blog (gempages.net's 1,290 posts first,
+its Shopify article template the proposed pilot) is built from the kit instead of site code. Markup that worked in
+0.4.0 still works, and a page without the new parts looks exactly as before: the demo index (without its new link),
+`brand-profiles.html` and `theme-example.html` are pixel-identical to 0.4.0 at 390 and 1366px, light and dark, with
+and without reduced motion, the index's bare prose table now in its script-made scroll box included.
+
+- Breadcrumbs `.gw-breadcrumbs`: a `<nav>` with a name around an `<ol>`, the last item `aria-current="page"`. The
+  separators are a chevron the CSS draws, never a character in the text; the current item stays on one line and is
+  cut with an ellipsis on a phone. A BreadcrumbList JSON-LD example is in `docs/components.md` (the kit writes none).
+- Article meta row `.gw-article-meta` (+ `__avatar`): author, category, `<time datetime>`, read time; 14px muted on
+  24px lines, a dot between items that never starts a wrapped line.
+- Article layout `.gw-article` (+ `__head`, `__hero`) and contents `.gw-toc` (`data-gw-toc`): one column on phones
+  with the contents folded above the prose (a `<details>`); from 1080px (the kit's desktop width) the reading column (68ch) and the contents
+  beside it, sticky under the header (the floating header included). The links work without the script.
+  `website.js` marks the section in view with `aria-current="true"` (an accent bar; the weight never changes) using
+  an IntersectionObserver that sees a heading cross the line 30% down the window, so a jump across sections counts
+  too; it opens the list from 1080px, folds it again below, and a link folds it on a phone before the page moves.
+  Each change of section fires `gw:toc` on the nav (`{ id }`, `''` above the first heading). A contents link glides
+  to its section, except under `prefers-reduced-motion`.
+  Closes gap #54 (blog article chrome: breadcrumbs, meta row, sticky contents, callout, post list)
+- Callout `.gw-callout` (+ `--note`, `--tip`, `--warning`, `__label`), `role="note"`: the kind in words (the label),
+  a 16px icon before it, on the kit's tints: the accent's, success's and the new `--gw-warning-soft`. Inside
+  `.gw-prose` it takes 32px of air like a figure.
+- Card picture `.gw-card__media` (+ `--wide` 1.91:1 for 1200 x 630 share images, `--square`; 16:9 by default): the
+  card's first child, edge to edge across its top, its corners the card's radius inside the hairline, the soft
+  ground while it loads.
+  Closes gap #33 (card with a thumbnail)
+- Post list `.gw-post-list` (+ `--compact`) of `.gw-card.gw-post` (`__title`): a picture, the category as a
+  `.gw-label`, the title whose link covers the card (one target, named by the title alone), an excerpt and a meta
+  row; one, two (768px) and three (1080px) columns. Pagination `.gw-pagination` (+ `__status`): previous and next as
+  links, markup only.
+- Prose tables: `website.js` puts each `<table>` straight inside a `.gw-prose` in a scroll box of its own,
+  `div.gw-prose__table`, a region named after the table's caption (else its first header cell, else its first
+  cell) with `tabindex="0"`, and marks the table `.is-wrapped`. The table keeps `display: table`, so its rows and
+  cells stay a table to assistive tech. Without the script, or before it runs, the table scrolls by itself as in
+  0.2.0 (`:not(.is-wrapped)`); the box looks the same. `destroy` takes the box away again. A site's own wrapper for
+  bare tables can go. Issue #63 itself stays open until the box is heard with VoiceOver on Safari, as it asks (the
+  table semantics are checked in Chromium's accessibility tree only).
+  Closes gap #63 (prose tables that scroll without losing table semantics)
+- `init(root)` and `destroy(root)` cover the two new parts like the others: wired once (`data-gw-ready="toc"` and
+  `"table"`), taken back by `destroy` (observer disconnected, mark removed, box removed), wired again by a later
+  `init`.
+- Templates: `templates/sections/article.html` (breadcrumbs, title, meta, hero, contents, prose with callouts and a
+  table, FAQ last) and `templates/sections/post-list.html` (cards, pagination, the compact list). Demo:
+  `demo/article.html` (a whole post, then a post list) and `demo/blog.html` (the blog index), linked from
+  `demo/index.html`, with their drawn pictures in `demo/assets/`.
+- `check`: `toc-target` (a contents link to an id that is not on the page) and `breadcrumbs-markup` (no `<nav>`,
+  no name, no `<ol>`, `aria-current="page"` missing from the last item or set on another, a typed separator) are
+  errors; `callout-label` (a callout without its label, told by colour alone) is a warning.
+- Token: `--gw-warning-soft` (`#fbf1dc`, dark `#2b2410`), the warning's tint, next to `--gw-success-soft`.
+- Budget: `js/website.js` is 13.8 KB unminified, 4.5 KB gzipped (0.4.0: 11.3 KB, 3.8 KB); the test now holds it
+  under 15 KB and 5 KB. `website.min.css` is 50.5 KB, 9.1 KB gzipped (0.4.0: 40.6 KB, 7.7 KB), most of it the
+  icons' masks, which gzip well.
+- Tests: `test/run.mjs` covers the new script parts, rules and CSS in its fake DOM; `test/browser.mjs` drives the
+  demo in Chromium (wheel and jump scrolling, Tab and Enter through the contents, the fold below 1080px, the table's
+  box and accessibility tree at 390px, init twice, destroy then init, the soft and accent profiles). CI runs it in
+  the kit's job.
+- `AGENTS.md`, the skill and the docs: an article page is `templates/sections/article.html` (breadcrumbs, meta,
+  contents from the h2s, prose, callouts); never a callout told by its colour alone.
+
+## 0.4.0 (2026-10-25)
+
+The website script, standardised like the CSS: it now wires markup that arrives after the page loaded (a Next.js
+route change, a GemPages block rendered later, a CMS preview), and comes as an ES module too. A page that loads
+`js/website.js` with `defer` and changes nothing works exactly as in 0.3.0 (the demo is pixel-identical at 390 and
+1366px, light and dark).
+
+Closes #64
+
+- `gwWebsite.init(root = document)`: wires the kit's markup under `root`, `root` included. Idempotent: each element
+  is wired once (and marked `data-gw-ready`), so call it after every navigation or insert and only the new elements
+  are wired; on a fragment it wires that fragment only. The page's own listeners (Escape, the outside click, the
+  busy-button guard, the system theme, the scroll) are installed once. Each call lets go of elements removed from
+  the page meanwhile and moves the script's `aria-current` mark to the new path (a mark in the markup stays).
+- `gwWebsite.destroy(root = document)`: removes what `init` wired under `root`, its listeners and its marks, for
+  frameworks that unmount. An open mega or mobile menu closes first, so the page is never left locked.
+- ESM entry `@gemboss/website-ui/website.mjs` (`js/website.mjs`): `export { init, destroy, version }`, no side
+  effects on import (safe to import on a server), no auto-init. `js/website.js` keeps its path, its export
+  `./website.js` and its behaviour: it starts by itself on `DOMContentLoaded` and exposes `window.gwWebsite`.
+- One source: `scripts/build.mjs` writes `js/website.js` from `js/website.mjs` (the code in an IIFE, without the
+  comments), and `--check` fails when they differ or when the version is not `package.json`'s.
+- One copy per page: the first copy that runs owns `window.gwWebsite`; another one (the classic script next to a
+  bundle) hands its calls to it, so nothing is wired twice.
+- Events, all bubbling, listed in `docs/markup-contract.md`: `gw:mega` on the trigger (`{ id, open }`) and
+  `gw:theme` on `<html>` (`{ theme: 'light' | 'dark' }`), next to `gw:segmented`.
+- Budget: `js/website.js` is 11.3 KB unminified, 3.8 KB gzipped (0.3.0: 9.2 KB, 3.3 KB). The test now holds it under
+  12 KB unminified and 4.5 KB gzipped (was 10 KB unminified): the comments live in `website.mjs`, the classic file
+  carries none.
+- `AGENTS.md`, the skill and `docs/components.md`: never wire a kit part with your own JS; call `init(root)` after
+  inserting kit markup. README: the ESM import and the Next.js recipe (a client effect on each route change).
+
 ## 0.3.0 (2026-10-25)
 
 Brand profiles: three knobs so that another GemCommerce brand (GemPages first, Gemians later) can use the kit and

package/README.md

@@ -12,11 +12,11 @@ it. Made so that a team working with Claude Code, even without a designer, ships
 
 | | |
 |---|---|
-| `website.css`, `website.min.css` | toàn bộ kit trong một tệp (khoảng 52 KB, 40 KB bản min): token sáng và tối, chữ, bố cục, nút (cả trạng thái nhấn và đang chờ), link, nhãn, chip, segmented control, badge, card, khung cửa sổ kèm chú thích "Illustrative data.", bảng, FAQ, chữ bài dài (`.gw-prose`), header + mega menu + menu điện thoại, footer, 12 section, 3 hồ sơ thương hiệu |
-| `js/website.js` | mega menu, menu điện thoại, đổi giao diện sáng/tối, hiện dần khi cuộn, đánh dấu trang hiện tại, segmented control, chặn bấm lần hai khi nút đang chờ; không phụ thuộc thư viện nào, khoảng 9 KB |
+| `website.css`, `website.min.css` | toàn bộ kit trong một tệp (khoảng 68 KB, 51 KB bản min, 9 KB khi nén gzip): token sáng và tối, chữ, bố cục, nút (cả trạng thái nhấn và đang chờ), link, nhãn, chip, segmented control, badge, card (kèm ảnh trên đầu thẻ), khung cửa sổ kèm chú thích "Illustrative data.", bảng, FAQ, chữ bài dài (`.gw-prose`), bộ khung bài blog (breadcrumb, dòng tác giả và ngày, mục lục dính, hộp lưu ý, danh sách bài, phân trang), header + mega menu + menu điện thoại, footer, 14 section, 3 hồ sơ thương hiệu |
+| `js/website.js`, `js/website.mjs` | mega menu, menu điện thoại, đổi giao diện sáng/tối, hiện dần khi cuộn, đánh dấu trang hiện tại, segmented control, chặn bấm lần hai khi nút đang chờ, đánh dấu mục đang đọc trong mục lục bài viết, khung cuộn cho bảng trong bài; không phụ thuộc thư viện nào, khoảng 4,5 KB khi nén gzip. `website.js` là script thường (tự chạy khi trang tải xong), `website.mjs` là bản ES module cho app; cả hai có `init(root)` để gắn lại phần markup chèn sau (`docs/markup-contract.md`, mục "Script") |
 | `AGENTS.md` | luật mà Claude Code (và người) phải theo: 10 luật, cách dựng trang, điều cấm, chữ, khả năng truy cập, đổi thương hiệu, khi kit thiếu |
-| `templates/` | khung một trang và 12 section (hero, logos, stats, features, split, showcase, steps, quote, pricing, faq, cta, prose) |
-| `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ơ |
+| `templates/` | khung một trang và 14 section (hero, logos, stats, features, split, showcase, steps, quote, pricing, faq, cta, prose, article, post-list) |
+| `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 |
 | `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` |
@@ -40,33 +40,55 @@ 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.3.0/website.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.5.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.3.0/js/website.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.5.0/js/website.js" defer></script>
 ```
 
-**Next.js (App Router):** nạp CSS trong layout gốc, nạp script bằng `next/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
+sau đó. Đừng tự viết JS cho mega menu, nút đổi giao diện hay segmented control.
+
+**Next.js (App Router):** nạp CSS trong layout gốc; script là bản ES module, gọi `init()` trong một effect mỗi lần
+đổi trang (chuyển trang phía client không tải lại trang, nên phần markup mới phải được gắn lại).
+
+```js
+import { init, destroy } from "@gemboss/website-ui/website.mjs";
+```
+
+```js
+// app/kit-script.jsx
+"use client";
+import { useEffect } from "react";
+import { usePathname } from "next/navigation";
+import { init } from "@gemboss/website-ui/website.mjs";
+
+export default function KitScript() {
+  const pathname = usePathname();
+  useEffect(() => { init(); }, [pathname]);
+  return null;
+}
+```
 
 ```js
 // app/layout.js
 import "@gemboss/website-ui/website.css";
 import "./site.css";
-import Script from "next/script";
+import KitScript from "./kit-script";
 
 export default function RootLayout({ children }) {
   return (
     <html lang="vi">
       <body className="gw-page">
         {children}
-        <Script src="/kit/website.js" strategy="afterInteractive" />
+        <KitScript />
       </body>
     </html>
   );
 }
 ```
 
-Chép `node_modules/@gemboss/website-ui/js/website.js` vào `public/kit/` (hoặc phục vụ nó bằng một route). Font Inter
-nạp từ Google Fonts như trong `templates/page.html`.
+`init()` gọi lại bao nhiêu lần cũng được: phần đã gắn thì bỏ qua, chỉ gắn phần mới. Font Inter nạp từ Google Fonts
+như trong `templates/page.html`.
 
 **Bắt đầu một trang:** chép `templates/page.html`, điền header và footer một lần (chung cho mọi trang), ghép các
 section trong `templates/sections/` theo thứ tự trang cần, thay mọi chỗ `[trong ngoặc]`, xoá phần không dùng. Mở
@@ -117,8 +139,9 @@ gemboss-www; mọi thay đổi đi qua PR, giá trị của hệ thống chỉ s
 
 ```sh
 cd packages/website-ui
-node scripts/build.mjs        # sinh css/tokens.css từ system.json, ghép website.css và website.min.css
-node test/run.mjs             # tự kiểm CLI
+node scripts/build.mjs        # sinh css/tokens.css từ system.json, ghép website.css và website.min.css, sinh js/website.js từ js/website.mjs
+node test/run.mjs             # tự kiểm CLI, CSS và website.js (DOM giả)
+node test/browser.mjs         # bài viết demo trong Chromium thật: cuộn, Tab, mục lục gập, bảng (cần .ci của repo)
 node scripts/gate-demo.mjs    # cổng thị giác và khoảng thở của gemboss.ai trên demo (cần .ci của repo)
 ```
 

package/bin/lib/check.mjs

@@ -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.",
   },
+  "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.",
+    fix: "Give the heading the id the link names (<h2 id=\"…\">), or point the link at the heading's id. Build the list from the article's own h2s (docs/components.md, Contents).",
+  },
+  "breadcrumbs-markup": {
+    level: "error", title: "Breadcrumbs without their markup",
+    why: "A screen reader announces the trail from its markup: a <nav> with a name around an <ol>, the last item marked aria-current=\"page\". The kit draws the separators; a › or / typed between the links is read out as a word.",
+    fix: "Copy the markup from docs/components.md (Breadcrumbs) or templates/sections/article.html: <nav class=\"gw-breadcrumbs\" aria-label=\"Breadcrumb\"><ol><li><a href=\"/blog\">Blog</a></li><li><a href=\"…\" aria-current=\"page\">This page</a></li></ol></nav>.",
+  },
   "uppercase-text": {
     level: "warning", title: "Uppercase text",
     why: "Headings, buttons, labels and menu items are sentence case.",
@@ -139,6 +149,11 @@ export const RULES = {
     why: "A drawn mock-up's numbers are made up. Without a caption a visitor reads them as a claim, and a claim found to be made up makes every other number on the page doubtful.",
     fix: "Add <p class=\"gw-window__caption\">Illustrative data.</p> as the last child of the .gw-window (vi: Dữ liệu minh hoạ. zh: 示意数据。), or the source when the numbers are real.",
   },
+  "callout-label": {
+    level: "warning", title: "Callout that tells its kind by colour only",
+    why: "A note, a tip and a warning differ by their tint, which a colour-blind reader, a screen reader and a printed page do not get. The kind has to be in words.",
+    fix: "Start the callout with <p class=\"gw-callout__label\">Note</p> (Tip, Warning, or the same word in the page's language).",
+  },
   "possible-gap": {
     level: "note", title: "Possible kit gap: a site class used on several pages",
     why: "A site class styled in site CSS and used on 3 or more pages is often a reusable part the kit does not have yet.",
@@ -519,6 +534,7 @@ function analyzeHtml(file, text, out) {
   }
 
   const classes = new Set();
+  const ids = new Set(), tocs = [];
   let h1 = 0;
   for (const m of scanText.matchAll(TAG_RE)) {
     const tag = m[1].toLowerCase();
@@ -536,6 +552,7 @@ function analyzeHtml(file, text, out) {
       else if (p.kind === "action") out.pageProfiles.push({ file: relFile, line, action: v });
     }
     if ((tag === "div" || tag === "span") && "onclick" in a) add("clickable-div", where());
+    if (a.id) ids.add(a.id);
     for (const k of ["alt", "title", "aria-label", "placeholder"]) {
       if (a[k] && hasEmDash(a[k])) add("em-dash", where(`${k}="${a[k]}"`));
     }
@@ -565,6 +582,28 @@ function analyzeHtml(file, text, out) {
       ].filter(Boolean);
       if (missing.length) add("segmented-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 100)}  missing: ${missing.join(", ")}`));
     }
+    if (cls.includes("gw-toc")) {
+      const end = elementEnd(scanText, m.index, tag);
+      if (end > 0) tocs.push({ start: m.index, end });
+    }
+    if (cls.includes("gw-breadcrumbs")) {
+      const body = inner();
+      const items = [...body.matchAll(/<li\b[^>]*>[\s\S]*?<\/li\s*>/gi)].map((x) => x[0]);
+      const current = (li) => /\baria-current\s*=\s*["']?page\b/i.test(li);
+      const words = decode(body.replace(/<[^>]*>/g, " "));
+      const missing = [
+        tag !== "nav" && "a <nav> (the class is on <" + tag + ">)",
+        tag === "nav" && !(a["aria-label"] || a["aria-labelledby"]) && "aria-label on the <nav>",
+        !/<ol\b/i.test(body) && "an <ol> of <li> items",
+        items.length && !current(items[items.length - 1]) && 'aria-current="page" on the last item',
+        items.slice(0, -1).some(current) && 'aria-current="page" on the last item only',
+        /(?:^|\s)(?:›|»|>|\/|\||·|•|→)(?=\s|$)/.test(words) && "no separator characters in the text (the kit draws them)",
+      ].filter(Boolean);
+      if (missing.length) add("breadcrumbs-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 80)}  missing: ${missing.join(", ")}`));
+    }
+    if (cls.includes("gw-callout") && !/\bclass\s*=\s*["'][^"']*\bgw-callout__label\b/i.test(inner())) {
+      add("callout-label", where(`${m[0].replace(/\s+/g, " ").slice(0, 80)} ${decode(visible.slice(m.index, elementEnd(scanText, m.index, tag))).replace(/\s+/g, " ").trim().slice(0, 60)}`));
+    }
     if (cls.includes("gw-window")) {
       const end = elementEnd(scanText, m.index, tag);
       const body = end < 0 ? "" : scanText.slice(m.index, end);
@@ -594,6 +633,14 @@ function analyzeHtml(file, text, out) {
       if (shouty(txt)) add("uppercase-text", where(`${m[0].slice(0, 60)}${txt.trim()}`));
     }
   }
+  // Contents links point at ids of this page (an id may come after the list: checked once the page is read).
+  for (const t of tocs) {
+    for (const x of scanText.slice(t.start, t.end).matchAll(/<a\b[^>]*?\bhref\s*=\s*["']#([^"']*)["']/gi)) {
+      let id = x[1];
+      try { id = decodeURIComponent(id); } catch { /* as written */ }
+      if (!ids.has(id)) add("toc-target", { file: relFile, line: lineAt(t.start + x.index), excerpt: `href="#${x[1]}": no element on the page has id="${id}"` });
+    }
+  }
   out.pageClasses.push({ file: relFile, classes });
 }
 

package/css/article.css

@@ -0,0 +1,237 @@
+/* article (0.5.0): the parts around a long read and the blog index. Breadcrumbs, the meta row, the article layout with
+   its contents list (.gw-toc), callouts, the post list and prev / next pagination. The article's own HTML stays in
+   .gw-prose (prose.css); .gw-card__media is in components.css. */
+
+/* breadcrumbs: a nav with an <ol>, the last item aria-current="page". The separator is drawn here (a chevron mask,
+   no character), so screen readers read the trail and not the punctuation. The current item stays on one line and
+   is cut with an ellipsis on a phone: the h1 right under it says it in full. */
+.gw-breadcrumbs { color: var(--gw-muted); font-size: 13px; line-height: 1.5; }
+.gw-breadcrumbs > ol { display: flex; flex-wrap: wrap; align-items: center; gap: 0 8px; margin: 0; padding: 0; list-style: none; }
+.gw-breadcrumbs li { display: flex; align-items: center; gap: 8px; min-width: 0; max-width: 100%; }
+.gw-breadcrumbs li + li::before {
+  content: "";
+  flex: none;
+  width: 12px;
+  height: 12px;
+  background: currentColor;
+  opacity: 0.6;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M9 6l6 6-6 6' fill='none' stroke='%23000' stroke-width='2.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 12px no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M9 6l6 6-6 6' fill='none' stroke='%23000' stroke-width='2.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 12px no-repeat;
+}
+.gw-breadcrumbs a { display: inline-flex; align-items: center; min-height: 24px; color: var(--gw-muted); }
+.gw-breadcrumbs a:hover { color: var(--gw-ink); text-decoration: underline; text-underline-offset: 4px; }
+.gw-breadcrumbs [aria-current="page"] {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--gw-ink);
+  font-weight: 500;
+  line-height: 24px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* meta row: author (an optional 24px avatar), category, published or updated <time datetime>, read time, each item a
+   <span> (or a <time>, an <a>) straight in the row. Small muted text on 24px lines that wraps. A dot sits before every
+   item; the row is pulled 16px to the left and clipped there, so the dot before the first item of each line is hidden
+   and a wrapped line never starts with a separator. */
+.gw-article-meta {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  row-gap: 4px;
+  margin-inline-start: -16px;
+  clip-path: inset(-8px -8px -8px 12px);
+  color: var(--gw-muted);
+  font-size: 14px;
+  line-height: 24px;
+}
+.gw-article-meta > *::before {
+  content: "";
+  display: inline-block;
+  width: 4px;
+  height: 4px;
+  margin-inline: 6px;
+  border-radius: var(--gw-radius-chip);
+  background: var(--gw-line-strong);
+  vertical-align: middle;
+}
+.gw-article-meta a {
+  display: inline-block;
+  color: var(--gw-accent-strong);
+  font-weight: 500;
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 4px;
+  text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);
+}
+.gw-article-meta a:hover { text-decoration-color: currentColor; }
+.gw-article-meta__avatar { display: inline-block; width: 24px; height: 24px; margin-inline-end: 8px; border-radius: var(--gw-radius-chip); object-fit: cover; vertical-align: top; }
+
+/* the article page (templates/sections/article.html): <article class="gw-wrap gw-article"> holding __head
+   (breadcrumbs, h1, meta), an optional __hero image, the .gw-toc and the .gw-prose, in that order. On phones one
+   column, the contents folded above the prose. From 1080px (the kit's desktop width, where the header shows its nav)
+   two columns: the reading column (68ch, the prose measure) and the contents beside it, sticky under the header. */
+.gw-article { padding-block: 32px 64px; }
+.gw-article__head > * + * { margin-top: 16px; }
+.gw-article__head h1 { font-size: var(--gw-display-h2); }
+.gw-article__hero { margin-top: 32px; }
+.gw-article__hero img { width: 100%; border-radius: var(--gw-radius-card); background: var(--gw-bg-soft); }
+.gw-article__hero figcaption { margin-top: 12px; color: var(--gw-muted); font-size: 14px; line-height: 1.5; }
+.gw-article > .gw-toc { margin-top: 32px; }
+.gw-article > .gw-prose { margin-top: 40px; }
+@media (min-width: 768px) {
+  .gw-article { padding-block: 48px 96px; }
+  .gw-article__hero { margin-top: 40px; }
+}
+@media (min-width: 1080px) {
+  .gw-article {
+    display: grid;
+    grid-template-columns: minmax(0, 68ch) minmax(200px, 240px);
+    grid-template-rows: auto auto 1fr;
+    justify-content: space-between;
+    column-gap: 64px;
+  }
+  .gw-article > * { grid-column: 1; }
+  .gw-article > .gw-article__head { grid-row: 1; }
+  .gw-article > .gw-article__hero { grid-row: 2; }
+  .gw-article > .gw-prose { grid-row: 3; }
+  .gw-article > .gw-toc { grid-column: 2; grid-row: 2 / 4; margin-top: 40px; }
+}
+
+/* contents: <nav class="gw-toc" aria-label="On this page" data-gw-toc> holding a <details>, its <summary> and an <ol>
+   of links to the article's h2s (a nested <ol> for h3s). Plain links: they work without the script. website.js marks
+   the section in view (aria-current="true", the accent bar) and opens the <details> from 1080px, where the list sits
+   beside the article and sticks under the header; below 1080px it is folded above the article and a link closes it.
+   The weight never changes with the mark, so the list does not move. */
+.gw-toc { font-size: 14px; line-height: 1.45; }
+.gw-toc > details { border: 1px solid var(--gw-line); border-radius: var(--gw-radius-card); background: var(--gw-surface); }
+.gw-toc summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  min-height: var(--gw-tap-min);
+  padding: 8px 16px;
+  color: var(--gw-ink);
+  font-weight: 600;
+  list-style: none;
+  cursor: pointer;
+}
+.gw-toc summary::-webkit-details-marker { display: none; }
+.gw-toc summary::after {
+  content: "";
+  flex: none;
+  width: 12px;
+  height: 12px;
+  background: currentColor;
+  opacity: 0.6;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M6 9l6 6 6-6' fill='none' stroke='%23000' stroke-width='2.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 12px no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M6 9l6 6 6-6' fill='none' stroke='%23000' stroke-width='2.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 12px no-repeat;
+  transition: transform 0.18s var(--gw-ease);
+}
+.gw-toc details[open] > summary::after { transform: rotate(180deg); }
+.gw-toc ol { margin: 0; padding: 0; list-style: none; }
+/* the rail is a background, so the list can scroll inside itself without clipping the bar of the marked link */
+.gw-toc details > ol { margin: 0 16px 16px; background: linear-gradient(var(--gw-line), var(--gw-line)) 0 0 / 1px 100% no-repeat; }
+.gw-toc a {
+  display: block;
+  padding: 6px 8px 6px 16px;
+  border-left: 2px solid transparent;
+  color: var(--gw-muted);
+}
+.gw-toc ol ol a { padding-left: 32px; }
+.gw-toc a:hover { color: var(--gw-ink); }
+.gw-toc a:focus-visible { outline-offset: -2px; }
+.gw-toc a[aria-current="true"] { border-left-color: var(--gw-accent); color: var(--gw-ink); }
+/* from 1080px: sticky beside the article; a long list scrolls inside itself, under the summary. Under the floating
+   header it sticks below the card. */
+@media (min-width: 1080px) {
+  .gw-toc { position: sticky; top: calc(var(--gw-header-height) + 32px); align-self: start; }
+  .gw-toc > details { border: 0; border-radius: var(--gw-radius-0); background: transparent; }
+  .gw-toc summary { min-height: 32px; padding: 0; color: var(--gw-muted); font-size: 13px; }
+  .gw-toc details > ol {
+    max-height: calc(100vh - var(--gw-header-height) - 120px);
+    margin: 8px 0 0;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+  }
+  :root:has(.gw-header--float) .gw-toc { top: calc(var(--gw-header-height) + var(--gw-header-gap) + 32px); }
+  :root:has(.gw-header--float) .gw-toc details > ol { max-height: calc(100vh - var(--gw-header-height) - var(--gw-header-gap) - 120px); }
+}
+/* a contents link glides to its section, except for a visitor who asked for less motion (base.css stops it too) */
+@media (prefers-reduced-motion: no-preference) {
+  :root:has(.gw-toc) { scroll-behavior: smooth; }
+}
+
+/* callout: a note, a tip or a warning inside an article. The kind is said in words by __label (Note, Tip, Warning,
+   or the reader's language), with a 16px icon before it; the tint only repeats it. Tints are the kit's: the accent's,
+   success's and warning's -soft grounds; the icon takes the solid hue. role="note" on the box. */
+.gw-callout {
+  padding: 16px 20px;
+  border-radius: var(--gw-radius-card);
+  background: var(--gw-accent-soft);
+  color: var(--gw-ink);
+  font-size: 16px;
+  line-height: 1.6;
+}
+.gw-callout > * + * { margin-top: 8px; }
+.gw-callout--tip { background: var(--gw-success-soft); }
+.gw-callout--warning { background: var(--gw-warning-soft); }
+.gw-callout__label { display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 600; line-height: 1.5; }
+.gw-callout__label::before {
+  content: "";
+  flex: none;
+  width: 16px;
+  height: 16px;
+  background: var(--gw-accent);
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round'%3E%3Ccircle cx='12' cy='12' r='9'/%3E%3Cpath d='M12 11v5M12 7.5v.5'/%3E%3C/svg%3E") center / 16px no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round'%3E%3Ccircle cx='12' cy='12' r='9'/%3E%3Cpath d='M12 11v5M12 7.5v.5'/%3E%3C/svg%3E") center / 16px no-repeat;
+}
+.gw-callout--tip > .gw-callout__label::before {
+  background: var(--gw-success);
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M9 18h6M10 21h4M12 3a6 6 0 0 0-3.6 10.8c.7.5 1.1 1.3 1.1 2.2h5c0-.9.4-1.7 1.1-2.2A6 6 0 0 0 12 3z'/%3E%3C/svg%3E");
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M9 18h6M10 21h4M12 3a6 6 0 0 0-3.6 10.8c.7.5 1.1 1.3 1.1 2.2h5c0-.9.4-1.7 1.1-2.2A6 6 0 0 0 12 3z'/%3E%3C/svg%3E");
+}
+.gw-callout--warning > .gw-callout__label::before {
+  background: var(--gw-warning);
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 3.5 2.8 19.5h18.4z'/%3E%3Cpath d='M12 10v4M12 16.8v.2'/%3E%3C/svg%3E");
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 3.5 2.8 19.5h18.4z'/%3E%3Cpath d='M12 10v4M12 16.8v.2'/%3E%3C/svg%3E");
+}
+
+/* post list: the blog index and "more from the blog". A <ul role="list"> of post cards: .gw-card with a
+   .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 > 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); }
+.gw-post > .gw-card__media + * { margin-top: 20px; }
+.gw-post > .gw-label + .gw-post__title { margin-top: 8px; }
+.gw-post__title { font-size: 20px; line-height: 1.3; }
+.gw-post__title a { color: var(--gw-ink); }
+.gw-post__title a::after { content: ""; position: absolute; inset: 0; z-index: 1; border-radius: var(--gw-radius-card); }
+.gw-post:hover .gw-post__title a { text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: 4px; }
+.gw-post__title a:focus-visible { outline: 0; }
+.gw-post__title a:focus-visible::after { outline: 2px solid var(--gw-accent); outline-offset: 2px; }
+.gw-post__title + p { margin-top: 8px; }
+.gw-post > .gw-article-meta { margin-top: auto; padding-top: 16px; }
+@media (min-width: 768px) {
+  .gw-post-list { gap: 24px; }
+  .gw-post-list:not(.gw-post-list--compact) { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+@media (min-width: 1080px) {
+  .gw-post-list:not(.gw-post-list--compact) { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+}
+.gw-post-list--compact { gap: 0; border-top: 1px solid var(--gw-line); }
+.gw-post-list--compact .gw-post { padding: 20px 0; border: 0; border-bottom: 1px solid var(--gw-line); border-radius: var(--gw-radius-0); background: transparent; box-shadow: none; }
+.gw-post-list--compact .gw-post__title a::after { border-radius: var(--gw-radius-0); }
+.gw-post-list--compact .gw-card__media { display: none; }
+.gw-post-list--compact .gw-post > .gw-article-meta { padding-top: 8px; }
+
+/* pagination: previous and next as links, a muted "Page 2 of 12" between them. Markup only, no script. */
+.gw-pagination { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 12px 16px; }
+* + .gw-pagination { margin-top: 40px; }
+.gw-pagination__status { color: var(--gw-muted); font-size: 14px; }
+.gw-pagination > [rel="next"] { margin-inline-start: auto; }

package/css/components.css

@@ -185,6 +185,21 @@
 .gw-card--soft { background: var(--gw-bg-soft); box-shadow: none; }
 .gw-card--link { display: block; color: inherit; }
 .gw-card--link:hover { border-color: var(--gw-line-strong); }
+/* a card's picture (0.5.0, gap #33): the first child of the card, edge to edge across its top, its corners the card's
+   radius inside the hairline. An aspect-ratio box (16:9; --wide 1.91:1, the share-image shape, so a post's own
+   1200 x 630 image fits uncut; --square 1:1) that the image covers, on the soft ground while it loads. */
+.gw-card__media {
+  overflow: hidden;
+  aspect-ratio: 16 / 9;
+  margin: -24px -24px 0;
+  border-top-left-radius: calc(var(--gw-radius-card) - 1px);
+  border-top-right-radius: calc(var(--gw-radius-card) - 1px);
+  background: var(--gw-bg-soft);
+}
+.gw-card__media--wide { aspect-ratio: 1200 / 630; }
+.gw-card__media--square { aspect-ratio: 1 / 1; }
+.gw-card__media :is(img, video) { width: 100%; height: 100%; object-fit: cover; }
+@media (min-width: 768px) { .gw-card__media { margin: -32px -32px 0; } }
 :where(.gw-card, .gw-feature, .gw-plan) > :is(h3, h4) + p { margin-top: 8px; }
 :where(.gw-card, .gw-feature) h3 { font-size: 20px; }
 :where(.gw-card, .gw-feature) p { font-size: 16px; color: var(--gw-muted); }