@gemboss/website-ui 0.4.0 → 0.6.0

package/AGENTS.md

@@ -10,13 +10,15 @@ 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; `window.gwWebsite.init(root)` |
+| `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, a short form, testimonials… |
 | `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) |
+| `demo/forms.html` | fields in every state, choices, the footer newsletter, a short form, stars, the testimonial wall and the rating badge |
 | `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 |
 
@@ -59,6 +61,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.
@@ -68,8 +74,9 @@ 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-danger` (an error, a destructive button; `--gw-danger-soft`,
+  `--gw-on-danger`), `--gw-line-control` (a form control's border, 3:1), `--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
@@ -80,6 +87,13 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 - **A button that waits** (a form sent, an audit started) gets `aria-busy="true"` from the page's script until the
   answer comes: the kit keeps its label and width, draws the ring and ignores a second press. Nothing else: no
   `disabled`, no loading class, no spinner of your own, no "Loading…" label.
+- **Forms** (0.6.0): a field is `.gw-field` (its `<label>` above, the control, the error, the hint), the controls
+  `.gw-input`, `.gw-select`, `.gw-textarea`, `.gw-check`, `.gw-radio` (a group in `.gw-choices`), one field and its
+  button in a row `.gw-form-inline`, a short form `.gw-form`. Ask as little as you can: one field beats a form, and a
+  form keeps two or three fields (`templates/sections/form.html`). A field in error is `aria-invalid="true"` plus its
+  `.gw-field__error` in words; the page decides when, the kit draws it.
+- **Ratings** (0.6.0): stars `.gw-stars` (`role="img"`, `aria-label="4.9 out of 5"`, `style="--gw-stars: 4.9"`), the
+  wall `.gw-testimonials` of `.gw-card.gw-testimonial`, the badge `.gw-rating-badge` (`templates/sections/testimonials.html`).
 - **One choice out of two to four** (Monthly / Yearly) is `.gw-segmented`, a radio group; what each option shows
   carries `data-gw-show="group:value"`. Markup: `docs/components.md`, `templates/sections/pricing.html`.
 - **Type**: Inter. Headings weight 650, tracking −0.022em; display h1/h2 weight 600, tracking −0.03em. Body 18px,
@@ -114,8 +128,16 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 - Don't write "Click here", "Learn more" as the only words of a link; say where it goes.
 - Don't use the em dash (—) in visible text. Use a comma, a colon or a full stop.
 - Don't invent numbers, customer names, logos, testimonials, ratings, awards or certifications.
+- Don't show a rating or a testimonial without a link to the page it comes from, and don't reword a review, round a
+  score up or average one yourself (section 6).
+- Don't build a form of many fields where one question does; don't use the placeholder as the label; don't tick a
+  consent box for the reader or word a refusal to shame them ("No thanks, I like losing sales").
+- Don't tell an error by its colour alone: `aria-invalid="true"` and words in `.gw-field__error` that say how to fix it.
 - 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,
@@ -136,6 +158,15 @@ 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 form field has a visible `<label for>` above it; its error and hint sit under it and are named by
+  `aria-describedby` (the error first). An error is `aria-invalid="true"` on the control plus words that say how to
+  fix it ("Enter your work email, like name@example.com"); after a failed send, move the focus to the first field in
+  error. Mark the optional fields "(optional)". A group of checkboxes or radios is a `<fieldset class="gw-choices">`
+  with its question in the `<legend>`.
+- Stars are `role="img"` with the value in words (`aria-label="4.9 out of 5"`); a number shown beside them is
+  `aria-hidden="true"`.
+- 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
 
@@ -149,6 +180,11 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 - Made-up numbers in a drawn mock-up: `.gw-window__caption` says exactly "Illustrative data." (vi: "Dữ liệu minh
   hoạ.", zh: "示意数据。"), plus one sentence only when a demo brand needs naming ("Vital Glow is a GemBoss demo
   brand."). Real numbers in a window: the caption names their source.
+- **Ratings and testimonials**: every one links to the page it comes from (the store's review page, the review
+  itself), and says only what that page says: the score and the count as shown there on the day you copy them, the
+  reviewer's own words (cut with an ellipsis, never reworded), their name and store as they wrote them. No made-up
+  review, no quote you wrote for a customer, no score you averaged yourself, no rating without its link (`check`
+  warns: `rating-source`). Do not name internal tools as the source.
 - Image sources: record where each image comes from (the brand's own screen, a licensed photo). No photos of real
   people or other brands' logos without permission.
 - Other languages: rewrite each page for its reader (transcreation), do not translate sentence by sentence. Facts
@@ -212,7 +248,9 @@ 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, stars without their value in words, a rating or a testimonial without a link to
+its source, 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,123 @@ 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.6.0 (2026-10-25)
+
+Forms and ratings: the fields a contact page, a sign-up or a footer newsletter needs, with their error state, and the
+proof a product site on the Shopify App Store shows (stars, a wall of short reviews, the store's rating badge). Markup
+that worked in 0.5.0 still works, and a page without the new parts looks exactly as before: the demo index (without its
+new link), `brand-profiles.html`, `article.html`, `blog.html` and `theme-example.html` are pixel-identical to 0.5.0 at
+390 and 1366px, light and dark, with and without reduced motion.
+
+- Fields `.gw-field` (`__label`, `__error`, `__hint`): the label above, the control, the error in words after an icon,
+  then the hint, 8px apart, tied with `for`/`id` and `aria-describedby` (the error first). Controls `.gw-input`,
+  `.gw-select` (a drawn caret that follows dark mode) and `.gw-textarea`: the dashboard's field family at the
+  website's sizes, as tall as a button (40px, 44px on touch), 16px words so a phone does not zoom, the action radius of
+  the site's profile, a 1px border that reaches 3:1. States by attribute: hover, focus (the accent ring and an ink
+  border), `readonly` (the soft ground), `disabled` (faded, its reason in the hint), `aria-invalid="true"` (the danger
+  border and tint, and the message in the danger colour with its icon: never the colour alone).
+  Closes gap #28 (form fields and the error state)
+- Choices `.gw-choices` (a `<fieldset>` and its `<legend>`), `.gw-check` and `.gw-radio` (the `<label>` is the row and
+  the target: 32px, 44px on touch; chosen, the box takes the accent and the mark `--gw-on-accent`), and a filter's
+  count `.gw-check__count`, for the template gallery filters the gempages.net research found.
+- One field and its button `.gw-form-inline` (one line from 480px, each a full line below it or in a narrow box), and
+  a short form's stack `.gw-form` (fields 24px apart, actions 32px below, 560px at most; on a card too).
+- Footer newsletter: `templates/footer.html` has an optional `<form class="gw-footer__newsletter">` in the brand block
+  (label, the inline row with a secondary button, a note that says how often and how to stop and links to the privacy
+  policy). Delete it unless it is wired to a list. Existing footers are unchanged.
+- `.gw-btn--danger` (the danger fill, `--gw-on-danger` words, hover and pressed one step towards the ink) for the action
+  of a page that destroys something, and `.gw-badge--danger` (a danger dot, ink words on the danger tint), as the gap
+  asked.
+- Tokens: `--gw-danger` (`#b42318`, dark `#ff6b5a`: the dashboard's `--gemboss-danger` family; 5.92:1 or more on every
+  ground, light, dark and in night bands), `--gw-danger-soft` (`#fff0e9`, dark `#2e1714`), `--gw-on-danger` (`#ffffff`,
+  dark `#0d0d12`; 6.57:1 and 6.92:1 on the fill) and `--gw-line-control` (`#85888e`, dark `#6a6d78`): a form control's
+  border, 3.20:1 or more on `bg`, `bg-soft` and `surface` and in night bands, where `--gw-line-strong` (1.28:1) is a
+  hairline. A brand does not change them.
+- Stars `.gw-stars`: a value from 0 to 5 in `style="--gw-stars: 4.9"`, drawn as five 16px ink stars with a partial
+  last one (a mask over a hard-stop gradient; system colours on a forced-colours screen), and heard as its name:
+  `role="img"`, `aria-label="4.9 out of 5"`.
+- Testimonial wall `.gw-testimonials` (one, two from 768px, three from 1080px; no masonry, a row's cards share its
+  height) of `.gw-card.gw-testimonial` (`__quote`, `__by` with the name, the store and the link to the review,
+  `__avatar` optional), and the rating badge `.gw-rating-badge` (an `<a>` to the store's review page: `__icon`,
+  `__score` with the stars, `__count`).
+  Closes gap #56 (testimonial wall with star rating, App Store rating badge)
+- Content rule (`AGENTS.md` sections 4 to 6, `docs/components.md`): every rating and testimonial links to the page it
+  comes from and copies only what it shows; no made-up review, no reworded quote, no score averaged by hand.
+- `check`: `stars-markup` (an error: `.gw-stars` without `role="img"` or its name, a value outside 0 to 5, a name that
+  does not carry the drawn number) and `rating-source` (a warning: a `.gw-rating-badge` or a `.gw-testimonial` without
+  a link). `--gw-stars` set on the element is an input, not a redefined token.
+- No script: the page owns validation (the kit ships no validator), so `website.js` only carries the new version.
+- Templates: `templates/sections/form.html` (a short form beside its reason: two fields and a choice) and
+  `templates/sections/testimonials.html` (the badge and the wall). Demo: `demo/forms.html` (every field state, the
+  choices, the inline row, the danger button, stars from 0 to 5, a short form, the badge and the wall with sample data,
+  the footer newsletter), linked from `demo/index.html`.
+- Budget: `website.min.css` is 59.3 KB, 10.5 KB gzipped (0.5.0: 50.5 KB, 9.1 KB). `js/website.js` is unchanged in size.
+- Tests: `test/run.mjs` covers the tokens and their contrast, the new CSS and the two `check` rules; `test/browser.mjs`
+  drives `demo/forms.html` in Chromium (Tab through a form, a label click, the error in the accessibility tree,
+  44px targets and the newsletter row at 390px, the stars' names, the soft and accent profiles).
+
+## 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

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`, `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ờ; không phụ thuộc thư viện nào, khoảng 4 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") |
+| `website.css`, `website.min.css` | toàn bộ kit trong một tệp (khoảng 82 KB, 59 KB bản min, 10,5 KB khi nén gzip): token sáng và tối, chữ, bố cục, nút (cả trạng thái nhấn, đang chờ và nút xoá), 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), ô nhập và trạng thái lỗi (ô chữ, danh sách chọn, ô nhiều dòng, checkbox, radio, hàng một ô một nút cho newsletter), sao đánh giá, tường review, huy hiệu điểm App Store, header + mega menu + menu điện thoại, footer (kèm ô newsletter tuỳ chọn), 16 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à 16 section (hero, logos, stats, features, split, showcase, steps, quote, pricing, faq, cta, prose, article, post-list, form, testimonials) |
+| `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) |
 | `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,9 +40,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.4.0/website.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.6.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.4.0/js/website.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.6.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,7 +113,7 @@ 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 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ồ… và gợi ý chỗ kit có thể đang thiếu |
+| `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… 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 |
 
@@ -140,7 +140,8 @@ 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, sinh js/website.js từ js/website.mjs
-node test/run.mjs             # tự kiểm CLI
+node test/run.mjs             # tự kiểm CLI, CSS và website.js (DOM giả)
+node test/browser.mjs         # demo trong Chromium thật: bài viết (cuộn, Tab, mục lục, bảng) và form, sao, review (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,21 @@ 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>.",
+  },
+  "stars-markup": {
+    level: "error", title: "Stars without their value in words",
+    why: "The kit draws .gw-stars from style=\"--gw-stars: N\" (a number from 0 to 5), and a screen reader hears only its name: role=\"img\" and aria-label=\"N out of 5\". Without them the stars are empty or silent, and a label that names another number than the drawing says two things at once.",
+    fix: "Write <span class=\"gw-stars\" role=\"img\" aria-label=\"4.9 out of 5\" style=\"--gw-stars: 4.9\"></span>: the same number in the style and in the label, from 0 to 5 (docs/components.md, Ratings).",
+  },
   "uppercase-text": {
     level: "warning", title: "Uppercase text",
     why: "Headings, buttons, labels and menu items are sentence case.",
@@ -139,6 +154,16 @@ 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).",
+  },
+  "rating-source": {
+    level: "warning", title: "Rating or testimonial without a link to its source",
+    why: "A score, a review count or a quote is a claim. Linked to the page it comes from (the store's review page, the review itself), a reader can check it; without the link it reads as made up, and a made-up review makes every other claim on the page doubtful.",
+    fix: "Make the .gw-rating-badge itself the <a href> to the review page, and give every .gw-testimonial a link to its review (in the byline: <a href=\"…\">Shopify App Store</a>). If there is no source to link, do not show the rating or the quote.",
+  },
   "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.",
@@ -290,6 +315,7 @@ export function subjectOf(sel) {
 const ATTR_THEME = String.raw`\[\s*data-theme(?:\s*[~|^$*]?=\s*(?:"[^"]*"|'[^']*'|[\w-]+))?\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));
+const INPUTS = new Set(["--gw-stars"]); // set on one element in the markup (style="--gw-stars: 4.9"), read by the kit's CSS
 const THEMABLE = /^--gw-(?:accent(?:-[\w-]+)?|on-accent(?:-(?:light|dark))?|wash(?:-[\w-]+)?)$/; // docs/theming.md: the eight accent variables (-light/-dark) + wash
 
 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)$/;
@@ -346,6 +372,8 @@ function checkRule(rule, ctx, add) {
     const where = { file: ctx.file, line: d.line, excerpt: excerptOf(sel, d) };
     if (d.prop.startsWith("--")) {
       if (d.prop.startsWith("--gw-")) {
+        // an input a component reads from its own markup (the stars' value), not a token: stars-markup checks it
+        if (INPUTS.has(d.prop)) continue;
         if (!(THEMABLE.test(d.prop) && rootish)) add("token-redefined", where);
       } else if (!ctx.svg && colorLiterals(value).length) add("color-literal", where);
       continue;
@@ -519,6 +547,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 +565,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 +595,45 @@ 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-stars")) {
+      const v = (/(?:^|;)\s*--gw-stars\s*:\s*([^;]*)/.exec(decode(a.style || "")) || [])[1];
+      const n = v !== undefined && /^\s*\d+(?:\.\d+)?\s*$/.test(v) ? Number(v) : null;
+      const label = a["aria-label"] || "";
+      const said = [...label.replace(/(\d),(\d)/g, "$1.$2").matchAll(/\d+(?:\.\d+)?/g)].map((x) => Number(x[0]));
+      const missing = [
+        a.role !== "img" && 'role="img"',
+        !(label.trim() || a["aria-labelledby"]) && 'aria-label with the value in words ("4.9 out of 5")',
+        v === undefined ? 'style="--gw-stars: N"' : (n === null || n > 5) && `a value from 0 to 5 (--gw-stars: ${v.trim()})`,
+        n !== null && n <= 5 && label.trim() && !said.includes(n) && `the same number in aria-label as in --gw-stars (${n})`,
+      ].filter(Boolean);
+      if (missing.length) add("stars-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 100)}  missing: ${missing.join(", ")}`));
+    }
+    if (cls.includes("gw-rating-badge") || cls.includes("gw-testimonial")) {
+      const linked = (tag === "a" && "href" in a) || /<a\b[^>]*\bhref\s*=/i.test(inner());
+      if (!linked) add("rating-source", 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 +663,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 });
 }