@gemboss/website-ui 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,191 @@
+# @gemboss/website-ui: read this before you build or change a page
+
+You are building a public website for a GemCommerce brand (GemBoss, GemPages, Gemians…) with this kit. The people
+asking you are often not designers. The kit is how their site ends up looking like it was made by a careful design
+team: **use the kit, follow the rules below, and when the kit is missing something, report it instead of inventing
+it.** Everything here applies to every page, in every language.
+
+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 |
+| `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 |
+| `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 |
+
+## 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.
+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`
+   (popovers: the mega menu, menus).
+5. **Only the scales.** Spacing: 0 2 4 6 8 12 16 20 24 32 40 48 64 80 96 120 (px). Type: 11 12 13 14 16 18 20 22 24 30,
+   plus the two display sizes for h1/h2. No half pixels, no "just 15px", no colour outside the tokens.
+6. **Sentence case everywhere.** Headings, buttons, labels, menu items. No uppercase with letter spacing.
+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). 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).
+
+## 2. Build a page
+
+1. Copy `templates/page.html` into the site. It links `website.css` and `website.js`, has the skip link, the
+   header, the `<main>` and the footer. Fill the header and footer once (they are the same on every page).
+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. 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.
+5. Run the check, open the page at 320px and 1366px, fix, then hand it over.
+
+## 3. The system in short (values: `system.json`)
+
+- **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.
+- **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
+  the label square, the focus ring, check marks and borders. Night bands switch to the dark palette by themselves.
+- **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>`).
+- **Layout**: content sits in `.gw-wrap` (1120px max, 22px gutters) or `.gw-wrap--narrow` (780px). Sections use
+  `.gw-section` and get their vertical rhythm from `--gw-space-section`. Grids: `.gw-grid--2|3|4` collapse to one
+  column on phones.
+- **Night bands** (`.gw-band--night`): at most three on a page plus the closing CTA, never two in a row; everything
+  else on white or `--gw-bg-soft`.
+- **Motion**: only `transform` and `opacity`, the kit's ease, nothing moves under `prefers-reduced-motion`. Scroll
+  reveal is `.gw-reveal` (the JS adds `.is-in`, and a failsafe shows it anyway).
+
+## 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 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 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 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,
+  that is a gap (section 9).
+
+## 5. Accessibility
+
+- Text contrast at least 4.5:1 (3:1 for 24px and above). The tokens pass; a custom colour may not.
+- Every interactive thing is a real `<a href>` or `<button>`. Never a clickable `<div>`.
+- Focus stays visible (the kit draws it with the accent). Do not remove outlines.
+- 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
+
+- Write for the reader of the page: what it does for them, in their words, short sentences. Lead with the outcome,
+  then how.
+- **Claims**: say only what the product does today. Every number needs a source the person can point to. If you do
+  not know a fact (a price, a count, a date, a customer), write a visible placeholder (`[PRICE]`) and ask.
+- 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
+  (prices, numbers, names, links, claims) stay identical. Labels inside buttons, chips and pills must not grow much
+  longer than the English, or they overflow on phones.
+
+## 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`.
+
+## 8. Where things go in a consuming site
+
+- Link the kit, then the site's own CSS after it: `website.css` → `site.css`.
+- The site's own CSS is for content the kit cannot know (an illustration, a product mock-up) and uses only the
+  tokens. Its classes start with the site's prefix (for example `gp-` on GemPages), never `gw-`.
+- Shared header and footer markup lives in one place in the site (a partial or component), not copied per page.
+
+## 9. When the kit is missing something
+
+The kit is young; it will not have everything. When a page needs something it does not have:
+
+1. **Is it really missing?** Look in `demo/index.html` and `docs/components.md`. Can two existing pieces together do
+   it (a grid of cards, a split with a list)? Can a variant do it? If yes, use that.
+2. **Is it a kit thing or a page thing?** A kit thing is reusable by other pages and other brands: a section shape,
+   a component, a token, a behaviour. A one-off illustration or a product mock-up is a page thing: build it in the
+   site's own CSS with the tokens, and stop here.
+3. **Build a stopgap in the site, not in the kit.** Put it in one file, `kit-gaps.css` (and `kit-gaps.js` if it needs
+   behaviour), with classes prefixed `kitgap-`, using only the kit's tokens and scales, and a comment naming the gap.
+   Never edit files inside `node_modules`, and never override `.gw-*` classes.
+4. **Report it.** Run `npx gemboss-website gap` and answer its questions (or pass `--title`, `--need`, `--page`,
+   `--kind`, `--stopgap kit-gaps.css`). It opens an issue in the kit's repository with everything the kit team needs,
+   or, when GitHub is not available, writes `kit-gaps/<name>.md` for the person to send. Tell the person you did it.
+5. **When the kit ships it**, `npx gemboss-website upgrade` lists the gaps that are now in the kit: replace your
+   stopgap with the kit's class and delete the `kitgap-` code.
+
+## 10. Check before you hand it over
+
+```sh
+npx gemboss-website check            # every .html and .css in the site against the rules above
+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.
+
+## 11. Upgrading the kit
+
+`npx gemboss-website upgrade` shows what changed since the version the site has (from `CHANGELOG.md`), the gaps that
+were closed, and the exact command to install the new version. Read it, upgrade, run the check, look at the pages.

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+Every release lists what changed for a site that uses the kit. A release that adds what a site reported as missing
+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.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.
+
+- `website.css`: tokens (light and dark, from `system.json`), base type, layout, buttons, links, labels, chips,
+  badges, cards, window frame, tables, FAQ, header with mega menu and mobile menu, footer, and the sections hero,
+  logos, stats, features, split, showcase, steps, quote, pricing and CTA.
+- Cards and plans carry the dashboard's resting shadow; the mega menu is a floating card under the bar (as on
+  gemboss.ai); night bands: at most three per page plus the closing CTA.
+- `website.js`: mega menu, mobile menu, theme toggle, scroll reveal, current-page marking.
+- `AGENTS.md`: the rules every page follows (what to use, what never to do, words, accessibility, theming, gaps).
+- `templates/`: the page skeleton and one snippet per section. `demo/`: every component on one page.
+- CLI `gemboss-website`: `init` (CLAUDE.md block + Claude Code skill), `check`, `gap`, `upgrade`.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @gemboss/website-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The website kit of GemCommerce.** Tokens, header with mega menu, footer, sections and the design rules that public
+websites built by GemCommerce teams share, plus a CLI that checks a site, reports what the kit is missing and upgrades
+it. Made so that a team working with Claude Code, even without a designer, ships pages that look like one family.
+
+> Bộ kit website của GemCommerce: token, header kèm mega menu, footer, các section và luật thiết kế mà mọi website
+> công khai của các team GemCommerce (GemBoss, GemPages, Gemians…) dùng chung, kèm một CLI kiểm site, báo chỗ kit còn
+> thiếu và nâng cấp. Viết để một team làm việc với Claude Code, kể cả không có designer, vẫn ra trang đúng một họ.
+
+## Có gì trong gói
+
+| | |
+|---|---|
+| `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 |
+| `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 |
+| `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` |
+
+Cần Node 18 trở lên cho CLI. CSS và JS chạy trên mọi trình duyệt hiện đại, không cần bước build.
+
+## Cài đặt
+
+```sh
+npm install @gemboss/website-ui        # hoặc: pnpm add @gemboss/website-ui / yarn add @gemboss/website-ui
+npx gemboss-website init               # nối luật của kit vào Claude Code của dự án (xem bên dưới)
+```
+
+`init` thêm một khối vào `CLAUDE.md` của dự án (giữa hai dấu `<!-- @gemboss/website-ui:start/end -->`, không đụng chữ
+khác) và cài skill `.claude/skills/gemboss-website-ui/SKILL.md`. Từ đó, mỗi lần bạn nhờ Claude Code làm một trang,
+nó đọc `AGENTS.md` của kit trước, dựng từ mẫu, và chạy `check` trước khi báo xong. Claude Code không tự đọc tệp trong
+`node_modules`, nên bước này là cần thiết.
+
+## Dùng trên trang
+
+**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="/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>
+```
+
+**Next.js (App Router):** nạp CSS trong layout gốc, nạp script bằng `next/script`.
+
+```js
+// app/layout.js
+import "@gemboss/website-ui/website.css";
+import "./site.css";
+import Script from "next/script";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="vi">
+      <body className="gw-page">
+        {children}
+        <Script src="/kit/website.js" strategy="afterInteractive" />
+      </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`.
+
+**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ở
+`demo/index.html` để xem kit có gì trước khi tự viết bất cứ thứ gì.
+
+## 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`.
+
+## 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 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 |
+
+`check` thoát mã 1 khi có lỗi, nên chạy được trong CI của site:
+`npx gemboss-website check --ignore vendor/`.
+
+## Khi kit thiếu thứ bạn cần
+
+Đừng đè class `gw-` hay sửa tệp trong `node_modules`. Làm tạm trong site (`kit-gaps.css`, class `kitgap-`, chỉ dùng
+token và thang), rồi `npx gemboss-website gap`. Khi một bản kit mới có thứ đó, CHANGELOG ghi `Closes gap #N` và
+`upgrade` nhắc bạn xoá phần làm tạm. Quy trình đầy đủ: `AGENTS.md` mục 9.
+
+## Phiên bản
+
+Semver. Ở 0.x, bản minor có thể đổi markup (đọc CHANGELOG trước khi nâng), bản patch thì an toàn. Ghim đúng phiên bản
+khi dùng CDN.
+
+## Dành cho team GemCommerce
+
+Tài liệu GemBoss Design System đầy đủ (triết lý, nền tảng, thành phần, mẫu trang, thương hiệu, quản trị) nằm ở cổng
+tài liệu nội bộ docs.gemboss.ai (đăng nhập bằng GemBoss). Mã nguồn của kit: `packages/website-ui` trong repo
+gemboss-www; mọi thay đổi đi qua PR, giá trị của hệ thống chỉ sửa ở `system.json`.
+
+```sh
+cd packages/website-ui
+node scripts/build.mjs        # sinh css/tokens.css từ system.json, ghép website.css và website.min.css
+node test/run.mjs             # tự kiểm CLI
+node scripts/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`. 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/gemboss-website.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// gemboss-website: the CLI of @gemboss/website-ui. How a site's Claude Code follows the kit's rules (init, check),
+// reports what the kit is missing (gap) and upgrades (upgrade). Node >= 18, no dependencies.
+import { PKG, UsageError } from "./lib/util.mjs";
+
+export const USAGE = `gemboss-website (${PKG.name} ${PKG.version})
+
+Usage: npx gemboss-website <command> [options]   (run it in the site's root folder)
+
+Commands
+  init [--force]
+      Add or refresh the kit's block in CLAUDE.md (between <!-- ${PKG.name}:start/end --> markers;
+      text outside them is never touched) and install the Claude Code skill
+      .claude/skills/gemboss-website-ui/SKILL.md (replaced only if init wrote it, or with --force).
+
+  check [paths...] [--json] [--fix-list] [--ignore <path>]... [--include-kit]
+      Check every .html/.htm/.css (and <style>, style="") under the paths (default: here) against
+      the kit's rules: colours, radii, type and spacing outside the scales, half pixels, shadows,
+      uppercase labels, accent-filled buttons, overrides of .gw-* classes, em dashes, images without
+      alt, vague links, h1 count, <html lang>, clickable divs. Notes list likely gaps (a site class on
+      3+ pages) and open kitgap-* stopgaps. Skips node_modules, dist, build, out, coverage, dot-folders
+      and the kit's own files. Exit 1 when there is an error, 0 otherwise.
+        --json        machine-readable findings
+        --fix-list    the findings as a markdown to-do list
+        --ignore      skip a file or folder (repeatable), e.g. third-party CSS
+        --include-kit also check the kit's own HTML (templates, demo): for the kit's own CI
+
+  gap [--title ...] [--need ...] [--kind token|component|section|behavior|doc|other]
+      [--page <url>] [--site ...] [--why ...] [--shape ...] [--stopgap <file>]
+      [--screenshot <path-or-url>] [--dry-run]
+      Report something the kit is missing. Asks for missing answers in a terminal; without one,
+      --title and --need are required. With gh signed in, opens an issue in ${(PKG.gemboss && PKG.gemboss.gapRepo) || "the kit's repo"};
+      otherwise (or with --dry-run, which never touches the network) writes kit-gaps/<slug>.md
+      and prints how to send it.
+
+  upgrade
+      Installed vs latest version, the CHANGELOG sections in between, the gaps they close, the
+      project's kitgap-* stopgaps that name those gaps, and the install command.
+
+  help
+      This text.
+
+Environment (tests and offline use)
+  GEMBOSS_WEBSITE_CHANGELOG=<file>   upgrade reads this changelog instead of the kit's CHANGELOG.md
+  GEMBOSS_WEBSITE_LATEST=<version>   upgrade uses this as the latest version instead of asking npm
+  GEMBOSS_WEBSITE_OFFLINE=1          upgrade does not ask npm
+  GEMBOSS_WEBSITE_GH=<path>          gap runs this instead of gh
+  NO_COLOR=1                         no colours in the output
+
+Rules: node_modules/${PKG.name}/AGENTS.md`;
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case undefined: case "help": case "--help": case "-h":
+      console.log(USAGE);
+      return 0;
+    case "--version": case "-v": case "version":
+      console.log(PKG.version);
+      return 0;
+    case "init": return (await import("./lib/init.mjs")).cmdInit(rest);
+    case "check": return (await import("./lib/check.mjs")).cmdCheck(rest);
+    case "gap": return (await import("./lib/gap.mjs")).cmdGap(rest);
+    case "upgrade": return (await import("./lib/upgrade.mjs")).cmdUpgrade(rest);
+    default:
+      throw new UsageError(`unknown command "${cmd}"`);
+  }
+}
+
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (err) => {
+  if (err instanceof UsageError) {
+    console.error(`gemboss-website: ${err.message}\nRun "npx gemboss-website help" for usage.`);
+    process.exitCode = 2;
+  } else {
+    console.error(err && err.stack ? err.stack : err);
+    process.exitCode = 3;
+  }
+});