@gemboss/website-ui 0.2.0 → 0.4.0

package/AGENTS.md

@@ -10,23 +10,31 @@ 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; 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… |
 | `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`
@@ -66,6 +74,8 @@ 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
@@ -85,16 +95,21 @@ 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.
@@ -105,6 +120,9 @@ Files you will use, all inside `node_modules/@gemboss/website-ui/`:
 - 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
 
@@ -139,14 +157,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
 
@@ -180,10 +208,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, 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, 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,69 @@ 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.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
+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.

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 49 KB, 38 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 |
-| `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 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") |
 | `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 |
+| `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,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.2.0/website.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.4.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.2.0/js/website.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.4.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ở
@@ -74,16 +96,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 |
 
@@ -109,7 +139,7 @@ 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 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 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

@@ -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",
@@ -103,6 +114,21 @@ export const RULES = {
     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.",
@@ -382,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;
@@ -469,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]}"`));
@@ -481,6 +547,7 @@ 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";
@@ -569,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;
@@ -587,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/components.css

@@ -1,6 +1,8 @@
 /* components: buttons, links, chips, badges, cards, windows, icons, lists, tables, FAQ. */
 
-/* actions are rectangles: 40px, radius 8, 14px/600, sentence case, ink fill (never the accent) */
+/* actions are rectangles: 40px, the action radius of the site's profile (8, 12 in soft), 14px/600, sentence case.
+   The fill is the action colour: ink, or the brand's accent under data-gw-action="accent" (tokens.css). Never a
+   gradient, a wash hue or a shadow. */
 .gw-btn {
   position: relative;
   display: inline-flex;
@@ -64,7 +66,7 @@
 @media (prefers-reduced-motion: reduce) {
   .gw-btn[aria-busy="true"]::before {
     border: 0;
-    border-radius: 0;
+    border-radius: var(--gw-radius-0);
     background:
       radial-gradient(circle at 3px 50%, currentColor 1.5px, transparent 2px),
       radial-gradient(circle at 8px 50%, currentColor 1.5px, transparent 2px),
@@ -110,8 +112,8 @@
 }
 
 /* segmented control: one choice out of two to four (Monthly / Yearly), a radio group of buttons. The dashboard's look
-   (@gemboss/ui .ui-seg): one hairline group, radius 8, a hairline between options, the chosen one on the accent tint,
-   so it follows a brand's accent. The weight never changes with the choice: the labels do not move. */
+   (@gemboss/ui .ui-seg): one hairline group, the action radius, a hairline between options, the chosen one on the
+   accent tint, so it follows a brand's accent. The weight never changes with the choice: the labels do not move. */
 .gw-segmented {
   display: inline-flex;
   max-width: 100%;
@@ -170,8 +172,8 @@
 .gw-badge--success::before, .gw-badge--warning::before { content: ""; flex: none; width: 6px; height: 6px; border-radius: var(--gw-radius-chip); background: var(--gw-success); }
 .gw-badge--warning::before { background: var(--gw-warning); }
 
-/* cards sit: white, 1px hairline, radius 12, the dashboard's resting shadow (Chris 24/10/2026: one language with the
-   app); no hover lift. A soft card is a tint and carries no shadow. */
+/* cards sit: white, 1px hairline, the card radius of the site's profile (12, 20 in soft), the dashboard's resting
+   shadow (Chris 24/10/2026: one language with the app); no hover lift. A soft card is a tint and carries no shadow. */
 .gw-card {
   padding: 24px;
   border: 1px solid var(--gw-line);