@gemboss/website-ui 0.1.0 → 0.3.0

package/AGENTS.md

@@ -10,23 +10,30 @@ 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; no dependencies |
+| `js/website.js` | header, mega menu, mobile menu, theme toggle, scroll reveal, segmented control, busy buttons; no dependencies |
 | `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… |
+| `templates/sections/*.html` | ready sections: hero, features, split, showcase, logos, stats, steps, pricing, FAQ, CTA, prose… |
 | `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 |
 | `docs/components.md` | every class, what it is for, its variants |
-| `docs/theming.md` | how a brand other than GemBoss sets its accent and logo, and what it must not change |
+| `docs/theming.md` | what a brand other than GemBoss chooses (accent, wash, logo, three named profiles), and what it must not change |
 
 ## 1. The ten rules
 
 1. **Compose, do not invent.** A page is the page skeleton plus kit sections plus your words. Look in `demo/` and
    `docs/components.md` first. A new class is a last resort (section 9).
-2. **White canvas, ink actions, one accent.** The background is white (`--gw-bg`). The thing you click is near-black
-   (`.gw-btn`). The accent colour is for links, focus, the active item, the 8px label square and a chart line. **The
-   accent is never a button fill and never body text.**
-3. **Actions are rectangles, chips are pills.** Buttons: radius 8px, 40px tall, sentence case, 14px/600. Chips,
-   toggles, badges: fully rounded. Cards: radius 12px (16px for a large panel). No other radii.
+2. **White canvas, one action colour, one accent.** The background is white (`--gw-bg`). The thing you click
+   (`.gw-btn`) is near-black ink, or the brand's accent when the site chose the `accent` action profile
+   (`data-gw-action="accent"` on `<html>`, section 7): one colour for every primary button of the site, never chosen
+   per button. Why the choice (0.3.0): the site and the product speak one language, and GemPages' product clicks in
+   blue while GemBoss's clicks in ink. Otherwise the accent is for links, focus, the active item, the 8px label
+   square and a chart line. **The accent is never body text, never words in a heading, never a section band, and
+   never a fill you set yourself.**
+3. **Actions are rectangles, chips are pills.** Buttons: 40px tall, sentence case, 14px/600, the action radius of the
+   site's profile (8px; 12px in `soft`). Chips, toggles, badges: fully rounded. Cards: the card radius (12px; 20px in
+   `soft`), large panels the panel radius (16px; 24px). No other radii: the site picks its profile once
+   (`data-gw-radius`), components follow.
 4. **A card sits.** A card (`.gw-card`, a plan) is a white box with a 1px `--gw-line` border and the resting shadow
    `--gw-shadow`, the same as the GemBoss dashboard. It never lifts on hover. To separate anything else, use space or a
    hairline before a shadow. The only shadows are `--gw-shadow` (rest), `--gw-shadow-sm` and `--gw-shadow-raised`
@@ -37,7 +44,8 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 7. **One idea per section, one primary action per view.** A section has a short label, a headline, at most two
    lines under it, then the content. One `.gw-btn` per section; the second action is `.gw-btn--secondary` or a link.
 8. **Real words, real facts.** No lorem ipsum, no invented numbers, customers, logos, reviews or quotes. Missing
-   facts become a visible placeholder like `[PRICE]` and a question to the person (section 6).
+   facts become a visible placeholder like `[PRICE]` and a question to the person (section 6). A drawn mock-up may
+   show made-up numbers only with the caption `<p class="gw-window__caption">Illustrative data.</p>` in its window.
 9. **It must work at 320px.** Check every page at 320, 390, 768 and 1366px wide. Nothing scrolls sideways, no text
    is clipped, every tap target is at least 44px.
 10. **Run the check before you say "done".** `npx gemboss-website check` (section 10).
@@ -48,7 +56,8 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
    header, the `<main>` and the footer. Fill the header and footer once (they are the same on every page).
 2. Pick sections from `templates/sections/` in the order the page needs. A typical page: hero → proof (logos or
    stats) → 2 to 4 feature sections → one showcase or split → FAQ → final CTA. Not every page needs every section;
-   fewer, clearer sections beat more.
+   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.
 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.
@@ -64,7 +73,14 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
   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
   the label square, the focus ring, check marks and borders. Night bands switch to the dark palette by themselves.
+- **Brand profiles** (section 7): `data-gw-action` and `data-gw-radius` on `<html>`, `.gw-header--float` on the
+  header. Without them a page is GemBoss: ink buttons, tight corners, the flat header.
 - **Controls** are 40px tall on desktop and at least 44px on touch screens; `.gw-btn--sm` is 36px with a 46px hit area on desktop and 44px tall on touch screens.
+- **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.
+- **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,
   line height 1.6. The house headline shape: a muted first sentence, an ink second one
   (`<h2><span class="gw-dim">Two builders.</span> One engine underneath.</h2>`).
@@ -78,20 +94,27 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 
 ## 4. Don't (each of these has happened, and each one made a page look cheap or broke it)
 
-- Don't fill a button with the accent colour, a gradient or a wash hue.
+- Don't fill a button yourself: not with the accent (that is the site's action profile, set once on `<html>`), a
+  gradient or a wash hue. No raised or inset shadow on a button.
+- Don't colour the words of a heading with the accent or a gradient, and don't fill a section band with the accent.
 - Don't use uppercase labels with letter spacing ("FEATURES").
 - Don't add shadows beyond the three tokens, and don't lift cards on hover.
 - Don't round a button into a pill, and don't square a chip.
 - Don't use cream, beige or grey page backgrounds; white or `--gw-bg-soft` only.
-- Don't use colours, sizes, spacings or radii outside the tokens and scales.
-- Don't put a floating, blurred, rounded "pill" header on the page; the header is a flat bar with one hairline.
+- Don't use colours, sizes, spacings or radii outside the tokens and scales, and don't redefine a kit token to get
+  another look: choose a profile.
+- Don't build your own floating, blurred or "pill" header. The header is the kit's flat bar with one hairline, or
+  its inset card `.gw-header--float` when the brand chose it.
 - Don't tuck the hero under the header with a negative margin.
 - Don't use emoji as icons; use inline stroke SVG (1.7–2px stroke, `currentColor`, `aria-hidden="true"`).
-- Don't use gradient washes behind body text, glassmorphism on chrome, or neon glows.
+- Don't use gradient washes behind body text, glassmorphism on chrome, or neon glows (the floating header's blur is
+  the kit's, not a style to copy).
 - Don't put two primary buttons side by side.
 - 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 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 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,
@@ -105,6 +128,10 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 - Tap targets at least 44×44px, with at least 8px between neighbours.
 - One `<h1>` per page, headings in order, landmarks (`header`, `nav`, `main`, `footer`), and the skip link kept.
 - Icon-only buttons get `aria-label`. Decorative SVG gets `aria-hidden="true"`.
+- Loading is `aria-busy="true"` on the button, with its label kept; when the wait ends, say what happened in words
+  (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.
 
 ## 6. Words
 
@@ -115,6 +142,9 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 - Product names, plan names and prices are written exactly as the brand writes them.
 - Domains in the text are the brand's own; never a made-up example brand that looks real.
 - Do not name or quote internal tools or internal data on a public page.
+- 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.
 - 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
@@ -123,14 +153,24 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 
 ## 7. Theming for another brand
 
-A brand other than GemBoss changes **only**: the accent family, the wash hues, the logo in the header and footer, and
-the favicon. The accent family is eight variables set in one `:root {}` block after the kit:
-`--gw-accent-light`, `--gw-accent-strong-light`, `--gw-accent-soft-light`, `--gw-on-accent-light` and the same four
-ending in `-dark`. 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 (links, the active menu item) uses `--gw-accent-strong`, so a new
-accent-strong must reach 4.5:1 on both `--gw-bg` and `--gw-bg-soft`. A brand does not change the shapes, the scales,
-the ink action, the white canvas or the type. Recipe and checks: `docs/theming.md`; a working example:
-`demo/theme-example.html`.
+A brand other than GemBoss chooses **only** these, and nothing else:
+
+- **the accent family**: eight variables in one `:root {}` block after the kit, `--gw-accent-light`,
+  `--gw-accent-strong-light`, `--gw-accent-soft-light`, `--gw-on-accent-light` and the same four ending in `-dark`.
+  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**;
+- **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
+    `check` fails;
+  - radius: `data-gw-radius="soft"` on `<html>` (12 / 20 / 24) instead of `tight` (8 / 12 / 16, default);
+  - header: `<header class="gw-header gw-header--float">`, an inset card from 1080px, instead of the flat bar.
+
+A brand does not change the neutrals, the type, the spacing, the shadows or the widths, and the profiles do not open
+accent-coloured heading words, accent bands or uppercase labels. Recipe and checks: `docs/theming.md`; working
+examples: `demo/theme-example.html` (accent only) and `demo/brand-profiles.html` (all three profiles).
 
 ## 8. Where things go in a consuming site
 
@@ -164,9 +204,11 @@ npx gemboss-website check            # every .html and .css in the site against
 npx gemboss-website check --fix-list # the same, as a to-do list
 ```
 
-It reports colours, radii, spacing and type outside the system, shadows on chrome, accent-filled buttons, uppercase
-labels, em dashes in visible text, images without `alt`, overrides of `.gw-*` classes, and patterns that repeat
-across pages (likely gaps). It does not replace looking at the page at 320px and 1366px.
+It reports colours, radii, spacing and type outside the system, shadows on chrome, buttons filled from site CSS,
+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.
 
 ## 11. Upgrading the kit
 

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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.3.0 (2026-10-25)
+
+Brand profiles: three knobs so that another GemCommerce brand (GemPages first, Gemians later) can use the kit and
+still look like itself. Each one is a named profile chosen once for the site, never a free value. Markup that worked
+in 0.2.0 still works, and a page without the new attributes looks exactly as before (ink buttons, tight corners, the
+flat header: the demo is pixel-identical to 0.2.0 at 390 and 1366px, light and dark).
+
+Closes #61
+
+- Action colour: `data-gw-action="accent"` on `<html>` fills the primary `.gw-btn` with the brand's accent
+  (`--gw-on-accent` words, `--gw-accent-strong` on hover and press, the `-dark` family in dark mode and night bands).
+  The default is `ink`. No button shadow. The build fails when the kit's own colours put the button's words below
+  4.5:1, light or dark, and `check` does the same with a brand's colours (`action-contrast`).
+- Radius profiles: `data-gw-radius="soft"` on `<html>` gives 12 / 20 / 24 (action, card, panel) and 24 for the mega
+  menu; the default `tight` keeps 8 / 12 / 16 and 20. Every component reads `--gw-radius-action|card|panel|popover`;
+  no component keeps a radius of its own.
+- Floating header: `<header class="gw-header gw-header--float">` is, from 1080px, an inset card (the panel radius, the
+  surface at 85% over a 10px blur, one hairline, the raised shadow, 16px from the top). Same bar, mega menu and
+  script; the flat bar below 1080px, so the phone menu is unchanged; solid under `prefers-reduced-transparency` and
+  where the browser cannot blur.
+- Still forbidden with every profile: accent or gradient words in a heading, accent section bands, uppercase labels.
+  `AGENTS.md` (rules 2 and 3, section 7), `docs/theming.md` (a brand chooses six things, nothing else) and
+  `docs/philosophy.md` say what changed and why: the site speaks the language of the brand's own product.
+- `check`: `profile-unknown` (a name that does not exist, or a profile set off `<html>`), `header-float-markup` (the
+  float class off the header) and `action-contrast`, all errors; `token-redefined` and `radius-off-scale` point at
+  the profiles.
+- `system.json` version 2: `profiles` (action, radius, header). `radius.action`, `radius.card` and `radius.panel`
+  moved to `profiles.radius.options.tight`; `radius.scale` gains 24. New tokens: `--gw-radius-popover`,
+  `--gw-radius-24`, `--gw-header-gap`, `--gw-header-surface`, `--gw-header-blur`.
+- `demo/brand-profiles.html`: a GemPages-style brand with all three profiles and the accent `#3c67ff`; its
+  accent-strong `#2f52d6` is an example the GemPages team has still to confirm.
+
+## 0.2.0 (2026-10-25)
+
+Four gaps reported while the GemBoss Design System was written. Markup that worked in 0.1.0 still works.
+
+- Buttons: a pressed state (`:active`: the ink one step darker, nothing moves) and a loading state
+  (`aria-busy="true"` on the `<button>`: the label keeps the width and the accessible name, a 16px ring in the
+  button's own ink, a still ellipsis under reduced motion). `website.js` ignores presses on a busy button, so a form
+  is not sent twice. Replace a `kitgap-` spinner or loading class with `aria-busy`.
+  Closes gap #25 (button pressed and loading states)
+- Segmented control `.gw-segmented` (+ `--block`): one choice out of two to four, a radio group (one Tab stop, the
+  arrow keys move and choose) with the dashboard's look, the chosen option on the accent tint. Content for one
+  option carries `data-gw-show="group:value"`; `website.js` shows it and fires `gw:segmented`.
+  `templates/sections/pricing.html` now has the monthly / yearly control. A `kitgap-segmented` group of
+  `aria-pressed` buttons becomes `role="radiogroup"` with `role="radio"` options (docs/components.md).
+  Closes gap #27 (segmented control, pricing monthly / yearly)
+- `.gw-window__caption`: what the numbers in a window are, 12px muted at the end of the window. Under a drawn
+  mock-up it says "Illustrative data." (vi: "Dữ liệu minh hoạ.", zh: "示意数据。"); under real numbers, their source.
+  The hero, split and showcase templates carry it.
+  Closes gap #32 (illustrative data caption for mock-ups)
+- `.gw-prose` (+ `--sm` for docs and legal): long-form reading. The article's own HTML needs no classes: headings,
+  paragraphs, lists, quotes, inline and block code, tables that scroll inside their own box, images and captions,
+  all on the kit's scales. New `templates/sections/prose.html`.
+  Closes gap #46 (long-form prose styles)
+- `check`: `busy-button` and `segmented-markup` (errors), `illustrative-caption` (a warning: a drawn window with
+  numbers and no caption).
+- Tokens: `--gw-font-mono` and `--gw-spin-ms` (`type.mono` and `motion.spin_ms` in `system.json`).
+- `website.js` 0.2.0, about 9 KB. `AGENTS.md` and the skill say when to use the four new parts.
+
 ## 0.1.0 (2026-10-24)
 
 The foundation.

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 39 KB, 31 KB bản min): token sáng và tối, chữ, bố cục, nút, link, nhãn, chip, badge, card, khung cửa sổ, bảng, FAQ, header + mega menu + menu điện thoại, footer, 11 section |
-| `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; không phụ thuộc thư viện nào, khoảng 7 KB |
+| `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 |
 | `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à 11 section (hero, logos, stats, features, split, showcase, steps, quote, pricing, faq, cta) |
-| `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 |
+| `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ơ |
 | `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.1.0/website.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.3.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.1.0/js/website.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.3.0/js/website.js" defer></script>
 ```
 
 **Next.js (App Router):** nạp CSS trong layout gốc, nạp script bằng `next/script`.
@@ -74,16 +74,24 @@ section trong `templates/sections/` theo thứ tự trang cần, thay mọi ch
 
 ## Thương hiệu khác GemBoss
 
-Một thương hiệu chỉ đổi màu nhấn (8 biến cho sáng và tối), màu wash, logo và favicon, trong một khối `:root {}` đặt
-sau kit. Hình dạng, thang, nút màu mực, nền trắng và kiểu chữ giữ nguyên. Công thức và các phép kiểm tương phản:
-`docs/theming.md`; ví dụ chạy được: `demo/theme-example.html`.
+Một thương hiệu chỉ chọn sáu thứ: màu nhấn (8 biến cho sáng và tối, trong một khối `:root {}` đặt sau kit), màu
+wash, logo (kèm favicon), và ba hồ sơ có tên, chọn một lần cho cả site:
+
+- màu nút chính: `data-gw-action="accent"` trên `<html>` cho nút chính dùng màu nhấn (mặc định `ink`, nút màu mực);
+  chữ trên nút phải đạt 4,5:1 cả sáng lẫn tối, không thì `check` báo lỗi;
+- bo góc: `data-gw-radius="soft"` trên `<html>` (12 / 20 / 24) thay cho `tight` (8 / 12 / 16, mặc định);
+- header: `<header class="gw-header gw-header--float">`, một thẻ nổi từ 1080px; điện thoại giữ thanh phẳng.
+
+Nền trắng, màu trung tính, chữ, khoảng cách, bóng giữ nguyên; chữ màu nhấn trong tiêu đề, dải nền màu nhấn, nhãn
+viết hoa vẫn cấm. Công thức và các phép kiểm tương phản: `docs/theming.md`; ví dụ chạy được:
+`demo/theme-example.html` (chỉ màu nhấn) và `demo/brand-profiles.html` (cả ba hồ sơ).
 
 ## Lệnh
 
 | 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ô màu nhấn, nhãn viết hoa giãn chữ, đè class `gw-`, 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ồ… 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 |
 
@@ -114,5 +122,6 @@ node test/run.mjs             # tự kiểm CLI
 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)
 ```
 
-Phát hành: tăng `version`, thêm mục CHANGELOG (kèm `Closes gap #N`), rồi gắn tag `website-ui-vX.Y.Z` (Trusted
-Publishing), hoặc `npm publish` từ thư mục này.
+Phát hành: tăng `version`, thêm mục CHANGELOG (kèm `Closes gap #N`), rồi gắn tag `website-ui-vX.Y.Z`. GitHub Actions
+đưa bản đó lên npm ở dạng CHỜ DUYỆT (`npm stage publish`, Trusted Publishing, không có token nào); bản chỉ ra công
+khai khi một maintainer duyệt bằng passkey trên npmjs.com (hoặc `npm stage approve <id>`).

package/bin/lib/check.mjs

@@ -3,8 +3,19 @@
 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";
 
 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.
+const PROFILE = Object.fromEntries(["action", "radius"].map((k) => {
+  const p = SYSTEM.profiles[k];
+  return [p.attribute, { kind: k, names: Object.keys(p.options).filter((n) => !n.startsWith("$")) }];
+}));
+const FLOAT_CLASS = SYSTEM.profiles.header.options.float.class;
+const ACCENT_ACTION = SYSTEM.profiles.action.options.accent;
+const profileList = () => Object.entries(PROFILE).map(([attr, p]) => `${attr}="${p.names.join("|")}"`).join(" and ");
+const radiusText = () => Object.entries(SYSTEM.profiles.radius.options).filter(([n]) => !n.startsWith("$"))
+  .map(([n, o]) => `${n} ${o.action}/${o.card}/${o.panel}`).join(", ");
 const TYPE = new Set(SYSTEM.type.scale);
 // The page gutter (layout.gutter) is a system value too: horizontal padding and the negative bleed that undoes it.
 const SPACE = new Set([...SYSTEM.space.scale, SYSTEM.layout.gutter]);
@@ -20,13 +31,13 @@ export const RULES = {
   },
   "token-redefined": {
     level: "error", title: "Kit token redefined",
-    why: "Only the accent family and the wash hues are themable. Changing another --gw-* token changes every component on the site.",
-    fix: "Remove it. If the brand really needs a different value, report a gap: npx gemboss-website gap --kind token.",
+    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.",
+    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": {
     level: "error", title: "Radius not on the scale",
-    why: "Actions are 8px rectangles, cards 12px, panels 16px, chips 999px. Other radii make a page look improvised.",
-    fix: `Use one of ${list(RADII)} (px), or a kit class that already has the shape.`,
+    why: `Actions, cards and panels take the radius of the site's profile (${radiusText()}), chips 999px. Other radii make a page look improvised.`,
+    fix: `Use var(--gw-radius-action), var(--gw-radius-card) or var(--gw-radius-panel) (they follow the profile), one of ${list(RADII)} (px), or a kit class that already has the shape.`,
   },
   "type-off-scale": {
     level: "error", title: "Font size not on the type scale",
@@ -55,8 +66,8 @@ export const RULES = {
   },
   "accent-button": {
     level: "error", title: "Button filled with the accent, a wash or a gradient",
-    why: "The thing you click is ink. The accent marks links, focus and the active item; it is never a button fill.",
-    fix: "Use .gw-btn (ink) or .gw-btn--secondary as they are. Do not restyle buttons.",
+    why: "The thing you click has one colour on the whole site, the action profile: ink, or the brand's accent when <html> has data-gw-action=\"accent\". A fill set in site CSS breaks that, and a gradient or a wash hue is never one.",
+    fix: "Use .gw-btn and .gw-btn--secondary as they are. For an accent button, put data-gw-action=\"accent\" on <html> (docs/theming.md).",
   },
   "gw-override": {
     level: "error", title: "Site CSS overrides a kit class",
@@ -93,11 +104,41 @@ export const RULES = {
     why: "A div or span with onclick cannot be reached by keyboard and is not announced as a control.",
     fix: "Use <a href> to go somewhere and <button type=\"button\"> to do something.",
   },
+  "busy-button": {
+    level: "error", title: "Loading button not marked with aria-busy",
+    why: "The kit draws a waiting button from aria-busy=\"true\": the label keeps the width and the accessible name, the ring turns (still under reduced motion) and website.js ignores a second press. A loading class or a hand-made spinner does none of that, and disabled throws the keyboard focus back to the top of the page.",
+    fix: "While it waits, set aria-busy=\"true\" on the <button class=\"gw-btn\"> and remove it when the answer comes. No loading class, no spinner element, no disabled.",
+  },
+  "segmented-markup": {
+    level: "error", title: "Segmented control without its radio-group markup",
+    why: "website.js and screen readers find the choice through the markup: a radiogroup with a name and data-gw-segmented, two to four <button role=\"radio\"> options, exactly one aria-checked=\"true\". Without it the arrows do nothing and the choice is not announced.",
+    fix: "Copy the markup from docs/components.md (Segmented control) or templates/sections/pricing.html.",
+  },
+  "profile-unknown": {
+    level: "error", title: "Brand profile that does not exist, or not on <html>",
+    why: "A brand chooses its action colour and its corners once for the site, from a fixed list, with one attribute on <html>. An unknown name falls back to the default without a word, and on any other element the profile reaches only part of the page.",
+    fix: `Use ${profileList()} on <html>, and nowhere else (docs/theming.md).`,
+  },
+  "header-float-markup": {
+    level: "error", title: "Floating header class not on the header",
+    why: `.${FLOAT_CLASS} reshapes the <header class="gw-header"> itself (an inset card from 1080px). On another element it does nothing, or draws a card inside the bar.`,
+    fix: `Put both classes on the header: <header class="gw-header ${FLOAT_CLASS}" data-gw-header>.`,
+  },
+  "action-contrast": {
+    level: "error", title: "Words on the accent button below 4.5:1",
+    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.",
+  },
   "uppercase-text": {
     level: "warning", title: "Uppercase text",
     why: "Headings, buttons, labels and menu items are sentence case.",
     fix: "Write it in sentence case instead of capitals or text-transform: uppercase.",
   },
+  "illustrative-caption": {
+    level: "warning", title: "Numbers in a drawn mock-up with no caption",
+    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.",
+  },
   "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.",
@@ -367,6 +408,39 @@ function checkFontSize(d, value, where, add) {
   }
 }
 
+/**
+ * The brand's accent primitives (--gw-accent-light, --gw-on-accent-dark…) as one page sees them: the plain :root
+ * blocks of the site's CSS files, then the page's own <style> blocks, over the kit's values. { name: { value, at } }
+ */
+function brandAccent(cssRules, page) {
+  const vals = {};
+  const take = ({ file, rules }) => {
+    for (const r of rules) {
+      if (r.atBlock || r.at.length || !r.selector || !isRootish(r.selector) || /data-theme/i.test(r.selector)) continue;
+      for (const d of r.decls) {
+        if (/^--gw-(?:on-)?accent(?:-strong|-soft)?-(?:light|dark)$/.test(d.prop)) vals[d.prop] = { value: d.value.replace(/!important\s*$/i, "").trim(), at: `${file}:${d.line}` };
+      }
+    }
+  };
+  for (const c of cssRules.filter((x) => !x.inline)) take(c);
+  for (const c of cssRules.filter((x) => x.inline && x.file === page)) take(c);
+  return vals;
+}
+
+/** 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")) {
+    const brand = brandAccent(out.cssRules, pg.file);
+    const colours = (theme, role) => (brand[`--gw-${role}-${theme}`] || { value: SYSTEM.color[theme][role] }).value;
+    const src = (theme, role) => { const b = brand[`--gw-${role}-${theme}`]; return b ? ` (${b.at})` : " (kit default)"; };
+    for (const p of actionPairs(ACCENT_ACTION, colours)) {
+      if (p.ok) continue;
+      const pair = `--gw-${p.textRole}-${p.theme} ${p.text}${src(p.theme, p.textRole)} on --gw-${p.fillRole}-${p.theme} ${p.fill}${src(p.theme, p.fillRole)}`;
+      add("action-contrast", { file: pg.file, line: pg.line, excerpt: `${p.theme}, ${p.state === "rest" ? "at rest" : "hover"}: ${pair} ${p.ratio === null ? "cannot be read as a colour" : `is ${ratio(p.ratio)}, needs ${MIN_CONTRAST}:1`}` });
+    }
+  }
+}
+
 // --------------------------------------------------------------------------------------------- HTML scanning
 
 const TAG_RE = /<([a-zA-Z][\w:-]*)((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*\/?>/g;
@@ -382,6 +456,19 @@ const VAGUE = new Set(["click here", "here", "learn more", "read more", "more",
 const LABELISH = /label|eyebrow|kicker|overline|badge|chip|btn|button|pill/i;
 const SKIP_CLASS = /^(?:gw-|is-|has-|js-|kitgap-)/;
 
+/** The end offset of the element whose start tag is at `start`, counting nested tags of the same name; -1 if unclosed. */
+function elementEnd(text, start, tag) {
+  const re = new RegExp(`<(/?)${tag}\\b[^>]*>`, "gi");
+  re.lastIndex = start;
+  let depth = 0;
+  for (let m; (m = re.exec(text));) {
+    if (m[1]) { if (--depth <= 0) return m.index + m[0].length; } else if (!m[0].endsWith("/>")) depth++;
+  }
+  return -1;
+}
+const LOADING_CLASS = /^(?:is-)?(?:loading|busy)$|--(?:loading|busy)$/;
+const SPINNER_CLASS = /\bclass\s*=\s*["'][^"']*(?:spinner|loader|loading)/i;
+
 function parseAttrs(s) {
   const a = {};
   for (const m of s.matchAll(ATTR_RE)) a[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? "";
@@ -441,6 +528,13 @@ function analyzeHtml(file, text, out) {
     if (tag === "img" && !("alt" in a)) add("img-alt", where());
     if (tag === "h1" && ++h1 === 2) add("multiple-h1", where());
     if (tag === "html" && !(a.lang || "").trim()) add("missing-lang", where());
+    for (const [attr, p] of Object.entries(PROFILE)) {
+      if (!(attr in a)) continue;
+      const v = (a[attr] || "").trim();
+      if (tag !== "html") add("profile-unknown", where(`${attr}="${v}" on <${tag}>: only on <html>`));
+      else if (!p.names.includes(v)) add("profile-unknown", where(`${attr}="${v}": no such ${p.kind} profile (${p.names.join(", ")})`));
+      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());
     for (const k of ["alt", "title", "aria-label", "placeholder"]) {
       if (a[k] && hasEmDash(a[k])) add("em-dash", where(`${k}="${a[k]}"`));
@@ -453,6 +547,32 @@ function analyzeHtml(file, text, out) {
       classes.add(k);
       if (k.startsWith("kitgap-") && !out.kitgapUse.has(gapBlock(k))) out.kitgapUse.set(gapBlock(k), { file: relFile, line });
     }
+    if (cls.includes(FLOAT_CLASS) && !cls.includes("gw-header")) add("header-float-markup", where());
+    const inner = () => { const end = elementEnd(scanText, m.index, tag); return end < 0 ? "" : scanText.slice(m.index + m[0].length, end); };
+    if (cls.includes("gw-btn")) {
+      const busy = (a["aria-busy"] || "").trim() === "true";
+      if (busy ? "disabled" in a : cls.some((k) => LOADING_CLASS.test(k)) || SPINNER_CLASS.test(inner())) add("busy-button", where());
+    }
+    if (cls.includes("gw-segmented")) {
+      const opts = [...inner().matchAll(/<button\b([^>]*)>/gi)].map((x) => parseAttrs(x[1]));
+      const missing = [
+        a.role !== "radiogroup" && 'role="radiogroup"',
+        !(a["aria-label"] || a["aria-labelledby"]) && "aria-label",
+        !(a["data-gw-segmented"] || "").trim() && "data-gw-segmented=\"name\"",
+        (opts.length < 2 || opts.length > 4) && "two to four <button> options",
+        opts.some((o) => o.role !== "radio" || !("aria-checked" in o)) && 'role="radio" and aria-checked on each option',
+        opts.filter((o) => o["aria-checked"] === "true").length !== 1 && 'exactly one aria-checked="true"',
+      ].filter(Boolean);
+      if (missing.length) add("segmented-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 100)}  missing: ${missing.join(", ")}`));
+    }
+    if (cls.includes("gw-window")) {
+      const end = elementEnd(scanText, m.index, tag);
+      const body = end < 0 ? "" : scanText.slice(m.index, end);
+      const words = end < 0 ? "" : decode(visible.slice(m.index, end)).replace(/\s+/g, " ").trim();
+      if (/\d/.test(words) && !/<(?:img|picture|video|iframe|canvas)\b/i.test(body) && !/\bgw-window__caption\b/.test(body)) {
+        add("illustrative-caption", where(`${m[0].replace(/\s+/g, " ").slice(0, 60)} ${words.slice(0, 70)}`));
+      }
+    }
     if ("style" in a && a.style.trim()) {
       const selector = tag + (a.id ? `#${a.id}` : "") + cls.map((k) => "." + k).join("");
       checkRule({ selector, decls: parseInline(decode(a.style), line), line }, { file: relFile, svg: within(svg, m.index), inline: true }, add);
@@ -516,7 +636,7 @@ export function runCheck(paths, { ignore = [], includeKit = false } = {}) {
     const r = RULES[rule];
     findings.push({ rule, level: r.level, file: w.file, line: w.line, excerpt: w.excerpt, title: r.title, why: r.why, fix: r.fix });
   };
-  const out = { add, cssRules: [], pageClasses: [], kitgapUse: new Map() };
+  const out = { add, cssRules: [], pageClasses: [], kitgapUse: new Map(), pageProfiles: [] };
   const counts = { html: 0, css: 0, skipped: [] };
   for (const f of files) {
     let text;
@@ -534,6 +654,8 @@ export function runCheck(paths, { ignore = [], includeKit = false } = {}) {
     }
   }
 
+  checkActionContrast(out, add);
+
   // Classes styled in site CSS: first definition of each.
   const styled = new Map();
   for (const { file, rules, text } of [...out.cssRules].sort((a, b) => (a.inline ? 1 : 0) - (b.inline ? 1 : 0))) {

package/bin/lib/contrast.mjs

@@ -0,0 +1,67 @@
+// WCAG 2 contrast for the kit's action profiles (system.json `profiles.action`). One implementation for the build
+// (scripts/build.mjs checks the kit's own colours) and for `gemboss-website check` (a brand's accent family).
+// No dependencies, Node 18 or later.
+
+export const MIN_CONTRAST = 4.5;
+
+/** "#rgb", "#rrggbb" (alpha ignored only when fully opaque), "rgb(r g b)" / "rgb(r, g, b)" -> [r, g, b], else null. */
+export function parseColor(value) {
+  const v = String(value || "").trim().toLowerCase();
+  let m = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(v);
+  if (m) {
+    let h = m[1];
+    if (h.length <= 4) h = [...h].map((c) => c + c).join("");
+    if (h.length === 8 && h.slice(6) !== "ff") return null;
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+  }
+  m = /^rgba?\(\s*(\d{1,3})[\s,]+(\d{1,3})[\s,]+(\d{1,3})\s*(?:[,/]\s*(1|1\.0+|100%)\s*)?\)$/.exec(v);
+  if (m) {
+    const rgb = m.slice(1, 4).map(Number);
+    return rgb.every((n) => n <= 255) ? rgb : null;
+  }
+  return null;
+}
+
+const channel = (c) => { const s = c / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+const luminance = ([r, g, b]) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+
+/** Contrast ratio of two colours (any order), or null when one cannot be read. */
+export function contrast(a, b) {
+  const x = parseColor(a), y = parseColor(b);
+  if (!x || !y) return null;
+  const [hi, lo] = [luminance(x), luminance(y)].sort((p, q) => q - p);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export const ratio = (n) => `${(Math.floor(n * 100) / 100).toFixed(2)}:1`;
+
+/**
+ * Every pair a primary button paints in one action profile: its label (`on-action`) on the fill (`action`) and on the
+ * hover and pressed fill (`action-hover`), in light and in dark (a night band uses the dark palette).
+ * `colours(theme, role)` returns the colour of a role ("accent", "on-accent", "action"…) in "light" or "dark".
+ * Returns [{ theme, state, text, fill, textRole, fillRole, ratio, ok }]; `ratio` is null when a colour is unreadable.
+ */
+export function actionPairs(profile, colours) {
+  const out = [];
+  for (const theme of ["light", "dark"]) {
+    for (const [state, fillRole] of [["rest", profile.action], ["hover", profile["action-hover"]]]) {
+      const textRole = profile["on-action"];
+      const text = colours(theme, textRole), fill = colours(theme, fillRole);
+      const r = contrast(text, fill);
+      out.push({ theme, state, text, fill, textRole, fillRole, ratio: r, ok: r !== null && r >= MIN_CONTRAST });
+    }
+  }
+  return out;
+}
+
+/** The kit's own colours for a role, from system.json `color.light` / `color.dark`. */
+export const kitColours = (system) => (theme, role) => system.color[theme][role];
+
+/** Every action profile of system.json against the kit's own colours: [{ profile, ...pair }]. Used by the build. */
+export function kitActionContrast(system) {
+  const out = [];
+  for (const [name, profile] of Object.entries(system.profiles.action.options).filter(([k]) => !k.startsWith("$"))) {
+    for (const p of actionPairs(profile, kitColours(system))) out.push({ profile: name, ...p });
+  }
+  return out;
+}

package/css/base.css

@@ -61,8 +61,8 @@ h5, h6 { font-size: 16px; font-weight: 600; letter-spacing: 0; }
   background: var(--gw-accent);
 }
 
-/* links inside running text get a visible link style; everything else opts in with .gw-link */
-:where(p, dd, td, figcaption, .gw-list--check li) a:not([class]),
+/* links inside running text (and anywhere in .gw-prose) get a visible link style; everything else opts in with .gw-link */
+:where(p, dd, td, figcaption, .gw-list--check li, .gw-prose) a:not([class]),
 .gw-link {
   color: var(--gw-accent-strong);
   font-weight: 500;
@@ -71,7 +71,7 @@ h5, h6 { font-size: 16px; font-weight: 600; letter-spacing: 0; }
   text-underline-offset: 4px;
   text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);
 }
-:where(p, dd, td, figcaption, .gw-list--check li) a:not([class]):hover,
+:where(p, dd, td, figcaption, .gw-list--check li, .gw-prose) a:not([class]):hover,
 .gw-link:hover { text-decoration-color: currentColor; }
 
 :focus-visible { outline: 2px solid var(--gw-accent); outline-offset: 2px; }