@gemboss/website-ui

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 107 KB, 74 KB bản min, 12,7 KB khi nén gzip): token sáng và tối, chữ, bố cục, nút (cả trạng thái nhấn, đang chờ và nút xoá), link, nhãn, chip, segmented control, badge, card (kèm ảnh trên đầu thẻ), khung cửa sổ kèm chú thích "Illustrative data.", bảng, FAQ, chữ bài dài (.gw-prose), bộ khung bài blog (breadcrumb, dòng tác giả và ngày, mục lục dính, hộp lưu ý, danh sách bài, phân trang), ô nhập và trạng thái lỗi (ô chữ, danh sách chọn, ô nhiều dòng, checkbox, radio, hàng một ô một nút cho newsletter), sao đánh giá, tường review, huy hiệu điểm App Store, header + mega menu + menu điện thoại (tuỳ chọn đi sâu từng mục kèm thanh nút dính đáy, như gemboss.ai) + nút đổi ngôn ngữ, footer như gemboss.ai (cột gập lại trên điện thoại, hàng Ask AI, hàng sản phẩm cùng nhà, nút sáng/tối, wordmark; ô newsletter tuỳ chọn), đốm sáng theo con trỏ trên thứ bấm được (data-gw-spot, bật từng chỗ), 16 section, 3 hồ sơ thương hiệu | | js/website.js, js/website.mjs | mega menu, menu điện thoại (kể cả bản đi sâu từng mục: Back, giữ focus trong menu, sự kiện gw:menu), nút đổi ngôn ngữ (đọc <link rel="alternate" hreflang> của trang, ẩn khi trang chỉ có một ngôn ngữ), đổi giao diện sáng/tối, hiện dần khi cuộn, đánh dấu trang hiện tại, segmented control, chặn bấm lần hai khi nút đang chờ, đánh dấu mục đang đọc trong mục lục bài viết, khung cuộn cho bảng trong bài, cột footer gập/mở theo khổ màn, đốm sáng theo con trỏ; không phụ thuộc thư viện nào, khoảng 7,1 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, header (header.html: hai tuỳ chọn, menu điện thoại đi sâu và nút ngôn ngữ), footer (footer.html: footer của gemboss.ai, mọi phần tuỳ chọn đều ghi rõ) và 16 section (hero, logos, stats, features, split, showcase, steps, quote, pricing, faq, cta, prose, article, post-list, form, testimonials) | | demo/ | mọi thành phần trên một trang; theme-example.html cho thấy một thương hiệu khác đổi màu nhấn; brand-profiles.html là một thương hiệu kiểu GemPages bật cả 3 hồ sơ; article.html là một bài blog trọn vẹn, blog.html là trang danh sách bài; forms.html là mọi trạng thái của ô nhập, newsletter ở footer, tường review và huy hiệu điểm (dữ liệu mẫu); footer.html là footer đầy đủ như gemboss.ai, kèm nút chuyển sang bản kiểu GemPages; header.html là header của gemboss.ai trên điện thoại (menu đi sâu từng mục, thanh nút dính đáy, nút đổi ngôn ngữ với ba ngôn ngữ), cũng có bản kiểu GemPages; spotlight.html là đốm sáng trên thẻ gói giá, thẻ link, thẻ nổi bật của mega menu và nút trong dải tối, cũng có bản kiểu GemPages | | 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 (và init --site), build, check, gap, upgrade | | templates/site/ | 0.13.0: bộ khung một site mới (Next.js phục vụ trang HTML tĩnh, danh sách trang, danh sách tệp công khai, site.css, kit-gaps.css), init --site chép ra |

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

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.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/[email protected]/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/[email protected]/js/website.js" defer></script>

Chèn markup của kit sau khi trang đã tải (block của builder, bản xem trước CMS): gọi gwWebsite.init(phầnMới) ngay 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).

import { init, destroy } from "@gemboss/website-ui/website.mjs";

// 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;
}

// app/layout.js
import "@gemboss/website-ui/website.css";
import "./site.css";
import KitScript from "./kit-script";

export default function RootLayout({ children }) {
  return (
    <html lang="vi">
      <body className="gw-page">
        {children}
        <KitScript />
      </body>
    </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ở 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ỉ 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: mặc định iris (từ 0.19.0, Chris 04/11/2026: nút iris #5661f5, chữ trắng); data-gw-action="ink" trên <html> cho nút màu mực như trước 0.19.0, data-gw-action="accent" cho nút dùng màu nhấn của brand; 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 init --site | 0.13.0: dựng một site mới như gemboss.ai và gemians.com: partial header và footer, index.html và 404.html có dấu <!-- gw:header --> / <!-- gw:footer -->, site.css, kit-gaps.css, phần Next.js phục vụ trang tĩnh; không ghi đè tệp có sẵn, thêm script còn thiếu vào package.json | | npx gemboss-website build | 0.13.0: chép kit vào assets/kit/, ghi partial header và footer vào mọi trang (đánh dấu aria-current="page" cho link của chính trang đó); --check cho CI, báo đỏ khi trang chưa cập nhật | | npx gemboss-website check | kiểm mọi .html và .css của site: màu, khoảng cách, chữ, bo góc ngoài thang, bóng, nút tự tô màu, nhãn viết hoa giãn chữ, đè class gw-, đổi token của kit, hồ sơ thương hiệu sai tên hoặc sai chỗ, chữ trên nút màu nhấn dưới 4,5:1, dấu gạch dài, ảnh thiếu alt, link mơ hồ, sao thiếu giá trị bằng chữ, điểm hay review không có link nguồn, cột footer gập thiếu tiêu đề trong summary, wordmark không ẩn với trình đọc màn hình, mục của menu đi sâu thiếu nút Back hay tiêu đề, nút ngôn ngữ không ẩn sẵn hay bản dịch thiếu hreflang… 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.

cd packages/website-ui
node scripts/build.mjs        # sinh css/tokens.css từ system.json, ghép website.css và website.min.css, sinh js/website.js từ js/website.mjs
node test/run.mjs             # tự kiểm CLI, CSS và website.js (DOM giả)
node test/browser.mjs         # demo trong Chromium thật: bài viết (cuộn, Tab, mục lục, bảng), form, sao, review, footer (gập, Tab, nút sáng/tối) và header (menu đi sâu bằng chạm và bàn phím, giữ focus, nút ngôn ngữ) (cần .ci của repo)
node scripts/gate-demo.mjs    # cổng thị giác và khoảng thở của gemboss.ai trên demo (cần .ci của repo)

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>).