npm - @gemboss/website-ui - Versions diffs - 0.0.0-stage → 0.1.0 - Mend

@gemboss/website-ui 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/AGENTS.md +174 -0
package/CHANGELOG.md +19 -0
package/README.md +117 -2
package/bin/gemboss-website.mjs +78 -0
package/bin/lib/check.mjs +642 -0
package/bin/lib/gap.mjs +189 -0
package/bin/lib/init.mjs +99 -0
package/bin/lib/upgrade.mjs +155 -0
package/bin/lib/util.mjs +147 -0
package/css/base.css +107 -0
package/css/components.css +236 -0
package/css/footer.css +53 -0
package/css/header.css +231 -0
package/css/layout.css +59 -0
package/css/sections.css +173 -0
package/css/tokens.css +198 -0
package/demo/index.html +629 -0
package/demo/theme-example.html +133 -0
package/docs/components.md +299 -0
package/docs/markup-contract.md +115 -0
package/docs/philosophy.md +69 -0
package/docs/theming.md +95 -0
package/js/website.js +149 -0
package/package.json +50 -4
package/skill/SKILL.md +48 -0
package/system.json +120 -0
package/templates/footer.html +40 -0
package/templates/header.html +60 -0
package/templates/page.html +134 -0
package/templates/sections/cta.html +15 -0
package/templates/sections/faq.html +24 -0
package/templates/sections/features.html +32 -0
package/templates/sections/hero.html +25 -0
package/templates/sections/logos.html +15 -0
package/templates/sections/pricing.html +39 -0
package/templates/sections/quote.html +13 -0
package/templates/sections/showcase.html +24 -0
package/templates/sections/split.html +25 -0
package/templates/sections/stats.html +26 -0
package/templates/sections/steps.html +17 -0
package/website.css +1064 -0
package/website.min.css +1 -0

package/demo/theme-example.html ADDED Viewed

@@ -0,0 +1,133 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Theme example · website UI kit</title>
+  <meta name="description" content="The same kit markup with a GemPages-style accent: only the --gw-accent variables change.">
+  <script>try{var t=localStorage.getItem('gw-theme');if(t==='light'||t==='dark')document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;650;700&display=swap">
+  <link rel="stylesheet" href="../website.css">
+  <style>
+    /* The whole brand theme: the accent family, light and dark, in one :root block (docs/theming.md).
+       Contrast checked: #1e5eff on #ffffff is 5.1:1, #6b98ff on #0d0d12 is 7.0:1. */
+    :root {
+      --gw-accent-light: #1e5eff;
+      --gw-accent-strong-light: #1547d1;
+      --gw-accent-soft-light: #eaf0ff;
+      --gw-accent-dark: #6b98ff;
+      --gw-accent-strong-dark: #a8c0ff;
+      --gw-accent-soft-dark: #16213d;
+    }
+  </style>
+</head>
+<body class="gw-page">
+  <a class="gw-skip" href="#main">Skip to content</a>
+  <div class="gw-announce" role="region" aria-label="Announcement">Theme example: the markup of the GemBoss demo, with only the accent changed. <a href="index.html">Back to the full demo</a></div>
+  <header class="gw-header" data-gw-header>
+    <div class="gw-wrap gw-header__bar">
+      <a class="gw-brand" href="index.html"><svg class="gw-brand__mark" viewBox="0 0 26 26" aria-hidden="true"><rect width="26" height="26" rx="6" style="fill:var(--gw-accent)"/><path d="M8 8h10M8 13h10M8 18h6" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round"/></svg><span class="gw-brand__name">GemPages</span></a>
+      <nav class="gw-nav" aria-label="Main">
+        <ul class="gw-nav__list">
+          <li class="gw-nav__item"><a class="gw-nav__link" href="https://gemboss.ai/gempages" aria-current="page">Page builder</a></li>
+          <li class="gw-nav__item"><a class="gw-nav__link" href="https://gemboss.ai/gemthemes">Section library</a></li>
+          <li class="gw-nav__item"><a class="gw-nav__link" href="https://gemboss.ai/pricing">Pricing</a></li>
+        </ul>
+      </nav>
+      <div class="gw-header__actions">
+        <button class="gw-theme-toggle" type="button" data-gw-theme-toggle aria-label="Switch to dark theme"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><circle cx="12" cy="12" r="8"/><path d="M12 4a8 8 0 0 1 0 16z" fill="currentColor"/></svg></button>
+        <a class="gw-nav__link gw-header__signin" href="https://admin.gemboss.ai/login">Sign in</a>
+        <a class="gw-btn gw-btn--secondary gw-btn--sm" href="https://gemboss.ai/contact">Book a demo</a>
+        <a class="gw-btn gw-btn--sm" href="https://admin.gemboss.ai/signup">Start free</a>
+        <button class="gw-menu-toggle" type="button" aria-expanded="false" aria-controls="gw-mobile-menu" data-gw-menu-toggle aria-label="Open menu"><svg class="gw-menu-toggle__open" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" aria-hidden="true"><path d="M4 7h16M4 12h16M4 17h16"/></svg><svg class="gw-menu-toggle__close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" aria-hidden="true"><path d="M6 6l12 12M18 6 6 18"/></svg></button>
+      </div>
+    </div>
+    <div class="gw-mobile-menu" id="gw-mobile-menu" hidden>
+      <nav class="gw-wrap" aria-label="Main, mobile">
+        <a class="gw-mobile-menu__top" href="https://gemboss.ai/gempages" aria-current="page">Page builder</a>
+        <a class="gw-mobile-menu__top" href="https://gemboss.ai/gemthemes">Section library</a>
+        <a class="gw-mobile-menu__top" href="https://gemboss.ai/pricing">Pricing</a>
+        <div class="gw-mobile-menu__actions">
+          <a class="gw-btn gw-btn--block" href="https://admin.gemboss.ai/signup">Start free</a>
+          <a class="gw-btn gw-btn--secondary gw-btn--block" href="https://gemboss.ai/contact">Book a demo</a>
+          <a class="gw-mobile-menu__link" href="https://admin.gemboss.ai/login">Sign in</a>
+        </div>
+      </nav>
+    </div>
+  </header>
+  <main id="main">
+    <section class="gw-hero" aria-labelledby="hero-h">
+      <div class="gw-hero__wash" aria-hidden="true"></div>
+      <div class="gw-wrap">
+        <p class="gw-label">Page builder</p>
+        <h1 id="hero-h"><span class="gw-dim">Describe it. Watch the page change.</span> Ship it.</h1>
+        <p class="gw-lead">The page builder in GemBoss is a chat beside your live page: ask for a section, a headline or a photo, and watch it change. Nothing reaches shoppers until you press Publish live.</p>
+        <div class="gw-actions">
+          <a class="gw-btn" href="https://admin.gemboss.ai/signup">Start free</a>
+          <a class="gw-btn gw-btn--secondary" href="https://gemboss.ai/contact">Book a demo</a>
+        </div>
+      </div>
+    </section>
+    <section class="gw-section gw-section--soft" aria-labelledby="how-h">
+      <div class="gw-wrap">
+        <div class="gw-section__head">
+          <p class="gw-label">How a change happens</p>
+          <h2 id="how-h"><span class="gw-dim">Ask, watch, publish.</span> You are the one who ships.</h2>
+          <div class="gw-actions">
+            <button class="gw-chip" type="button" aria-pressed="true">New section</button>
+            <button class="gw-chip" type="button" aria-pressed="false">Copy</button>
+            <button class="gw-chip" type="button" aria-pressed="false">Media</button>
+            <span class="gw-badge gw-badge--accent">Draft, not live yet</span>
+          </div>
+        </div>
+        <div class="gw-grid--3">
+          <div class="gw-card">
+            <h3>Ask</h3>
+            <p>Type it in plain words, or click a section and ask about that one.</p>
+          </div>
+          <div class="gw-card">
+            <h3>Watch</h3>
+            <p>It edits the page in front of you and checks how it looks.</p>
+          </div>
+          <a class="gw-card gw-card--link" href="https://gemboss.ai/gempages">
+            <h3>Publish</h3>
+            <p>Changes stay a draft until you press Publish live. Undo any step.</p>
+            <span class="gw-link gw-link--arrow">See the page builder</span>
+          </a>
+        </div>
+      </div>
+    </section>
+    <section class="gw-section gw-band--night" aria-labelledby="cta-h">
+      <div class="gw-wrap gw-cta">
+        <p class="gw-label">One engine underneath</p>
+        <h2 id="cta-h">Looks like your store. Because it is built from it.</h2>
+        <p class="gw-lead">Every page uses your storefront's sections and brand settings. Read the <a href="https://gemboss.ai/docs">docs</a> for the MCP tools.</p>
+        <div class="gw-actions">
+          <a class="gw-btn" href="https://admin.gemboss.ai/signup">Start free</a>
+          <a class="gw-btn gw-btn--secondary" href="https://gemboss.ai/contact">Book a demo</a>
+        </div>
+      </div>
+    </section>
+  </main>
+  <footer class="gw-footer">
+    <div class="gw-wrap">
+      <div class="gw-footer__bottom">
+        <span>© 2026 GemBoss. All rights reserved.</span>
+        <ul aria-label="Legal">
+          <li><a href="https://gemboss.ai/privacy">Privacy</a></li>
+          <li><a href="https://gemboss.ai/terms">Terms</a></li>
+        </ul>
+      </div>
+    </div>
+  </footer>
+  <script src="../js/website.js" defer></script>
+</body>
+</html>

package/docs/components.md ADDED Viewed

@@ -0,0 +1,299 @@
+# Components and sections
+Every class in `website.css`, what it is for, its variants, a minimal example and what not to do with it. Open
+`demo/index.html` to see all of them on one page, and start pages from `templates/`. The markup that the script
+(`js/website.js`) relies on is fixed in `docs/markup-contract.md`; this file follows it.
+Conventions: kit classes start with `gw-`, variants are `--name`, parts are `__name`, states set by the script are
+`is-*`. Never style a `.gw-*` class in your site's CSS: if the kit's version is wrong for you, that is a gap
+(`AGENTS.md` section 9).
+Spacing between the children of text blocks is automatic: inside `.gw-section__head`, the hero, a split column,
+`.gw-cta`, `.gw-card`, `.gw-feature` and `.gw-plan`, each child is 16px below the previous one, a `.gw-actions` row
+32px, a `.gw-list--check` 24px. Do not add margins to fix rhythm; reorder or remove content instead.
+## Page
+| class | for |
+|---|---|
+| `.gw-page` | on `<body>`: the footer stays at the bottom of a short page |
+| `.gw-skip` | the first element in `<body>`: "Skip to content", visible only on keyboard focus |
+```html
+<body class="gw-page">
+  <a class="gw-skip" href="#main">Skip to content</a>
+  …
+  <main id="main">…</main>
+```
+Don't remove the skip link, and don't leave out `id="main"`.
+## Type and text
+| class | for |
+|---|---|
+| `h1`, `h2` (and `.gw-h1`, `.gw-h2`) | display sizes: h1 `clamp(40px, 4.6vw, 68px)`, h2 `clamp(32px, 3.4vw, 52px)`, weight 600, tracking −0.03em |
+| `h3`, `h4` (and `.gw-h3`, `.gw-h4`) | 24px / 650 and 20px / 600 |
+| `.gw-dim` | the muted first sentence of the house headline shape |
+| `.gw-label` | the label above a heading: 13px, muted, led by the 8px accent square |
+| `.gw-lead` | the one or two lines under a heading (18px, 20px in the hero, muted, max 60ch) |
+| `.gw-note` | a short reassurance under actions (14px, muted) |
+| `.gw-link` | an inline link in the accent, underlined |
+| `.gw-link--arrow` | a standalone "go there" link with a → that moves 2px on hover |
+```html
+<p class="gw-label">How it works</p>
+<h2><span class="gw-dim">Give it a product.</span> Watch the engine work.</h2>
+<p class="gw-lead">One or two lines, no more.</p>
+<a class="gw-link gw-link--arrow" href="/funnel">See the funnel builder</a>
+```
+Plain links inside `p`, `dd`, `td`, `figcaption` and check-list items get the link style without a class.
+`.gw-h1`…`.gw-h4` exist so the visual size can differ from the heading level: keep one `<h1>` per page and headings in
+order, then choose the look.
+Don't: uppercase or letter-spaced labels; a label longer than a few words; the accent as body text; "Learn more" or
+"Click here" as the whole link text; more than two lines under a heading.
+## Layout
+| class | for |
+|---|---|
+| `.gw-wrap` | content width: 1120px max with 22px gutters |
+| `.gw-wrap--narrow` | 780px max, for FAQ and long reading; use alone or with `.gw-wrap` |
+| `.gw-section` | a section's vertical rhythm (`--gw-space-section`) |
+| `.gw-section--soft` | on `--gw-bg-soft`, to separate a section without a line |
+| `.gw-section--tight` | less padding (40px, 64px from 768px), for proof strips and follow-on tables |
+| `.gw-section__head` | label + h2 + lead, max 660px; 40–48px above the content |
+| `.gw-section__head--center` | the same, centred |
+| `.gw-grid`, `.gw-grid--2`, `.gw-grid--3`, `.gw-grid--4` | equal columns: one on phones; 2 and 3 from 768px; 4 is 2 from 480px and 4 from 1080px |
+| `.gw-actions` | a row of actions that wraps; on phones the hero and CTA buttons go full width |
+| `.gw-band--night` | a dark band: the dark palette on the night ground, in both themes |
+```html
+<section class="gw-section gw-section--soft">
+  <div class="gw-wrap">
+    <div class="gw-section__head">…</div>
+    <div class="gw-grid--3">…</div>
+  </div>
+</section>
+```
+Don't: more than three night bands on a page (the closing CTA does not count), or two in a row; a grey or cream page background (white or
+`--gw-bg-soft` only); a grid with a single item (use a narrower wrap instead); fixed widths in px on content.
+## Components
+### Buttons `.gw-btn`
+40px tall, radius 8, 14px/600, sentence case, ink fill. Variants: `--secondary` (hairline, transparent), `--ghost`
+(no frame), `--on-night` (light fill for a dark surface that is not a `.gw-band--night`), `--sm` (36px, with a 44px
+hit area), `--lg` (48px, 16px type), `--block` (full width). On touch screens every button is at least 44px tall and
+its label may wrap. Inside a night band the default button turns light by itself.
+```html
+<div class="gw-actions">
+  <a class="gw-btn" href="/signup">Start free</a>
+  <a class="gw-btn gw-btn--secondary" href="/contact">Book a demo</a>
+</div>
+```
+Don't: an accent, gradient or wash fill; pill-shaped buttons; uppercase; two filled buttons side by side (one
+`.gw-btn` per view, the second is `--secondary` or a link); a `<div>` with a click handler instead of `<a>`/`<button>`.
+### Chips `.gw-chip`
+A small selectable token, a pill. Active: `.is-active`, `aria-pressed="true"` or `aria-selected="true"` (accent
+hairline on accent-soft). As a `<button>`, `<a>` or `<label>` it is 44px tall on touch screens.
+```html
+<button class="gw-chip" type="button" aria-pressed="true">Serum</button>
+```
+Don't: use a chip as the page's action; square it; more than about six in a row.
+### Badges `.gw-badge`
+Small status, a pill, 12px. Variants: `--accent` (a test, the recommended plan), `--success` and `--warning` (state:
+a coloured dot, ink words, because the state hues fail 4.5:1 as small text on a tint).
+```html
+<span class="gw-badge gw-badge--success">Live</span>
+```
+Don't: make a badge clickable; write a sentence in it; use success or warning for anything but state.
+### Cards `.gw-card`
+A white box with a 1px hairline, radius 12, the resting shadow `--gw-shadow` (as the dashboard's cards), 24px padding
+(32px from 768px). It sits: no hover lift. `--soft` is a tint and has no shadow.
+Variants: `--soft` (on `--gw-bg-soft`), `--link` (the whole card is one `<a>`; the border darkens on hover).
+```html
+<a class="gw-card gw-card--link" href="/mcp">
+  <h3>Open to your team and agents</h3>
+  <p>100+ MCP tools, so your team, your agency or your own AI can drive the engine.</p>
+  <span class="gw-link gw-link--arrow">See MCP and agents</span>
+</a>
+```
+Don't: put links or buttons inside a `--link` card (one card, one destination); a bigger shadow or a hover lift; radius
+other than 12 (16 is for large panels: plans, quote).
+### Window `.gw-window`
+A framed screen: `__bar` (three dots and where the screen lives) and `__body` (16px padding, none around a single
+`<img>`). Use it around real product screenshots, or around a drawn mock-up built in the site's CSS with the tokens.
+```html
+<div class="gw-window">
+  <div class="gw-window__bar">Funnels / Radiance Serum</div>
+  <div class="gw-window__body"><img src="/img/funnels.webp" alt="The funnel list with four steps" width="1200" height="750"></div>
+</div>
+```
+Don't: put interactive controls inside a mock-up; show made-up numbers without "Illustrative" under them.
+### Icon `.gw-icon`
+A 20px box for an inline stroke SVG (1.7–2px stroke, `currentColor`, `aria-hidden="true"`). Inside `.gw-feature` it
+becomes a 40px tile with a hairline.
+```html
+<span class="gw-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7">…</svg></span>
+```
+Don't: emoji as icons; filled multi-colour icons; icon-only buttons without `aria-label`.
+### Check list `.gw-list--check`
+A `<ul>` whose items are led by an accent check mark.
+```html
+<ul class="gw-list--check"><li>Checkout stays on Shopify</li><li>No overage fees</li></ul>
+```
+Don't: more than five or six items; full paragraphs as items.
+### Table `.gw-table`
+A wrapper around a plain `<table>`: hairline, radius 12, and it scrolls inside its own box when the table is wider
+than the screen. `--compare`: centred values, a 640px minimum width and a sticky first column, for plan comparisons.
+Give the wrapper `role="region"`, an accessible name and `tabindex="0"` so keyboard users can scroll it.
+```html
+<div class="gw-table gw-table--compare" role="region" aria-labelledby="compare-h" tabindex="0">
+  <table>
+    <thead><tr><th scope="col">Plan</th><th scope="col">Starter</th></tr></thead>
+    <tbody><tr><th scope="row">Price a month</th><td>$49</td></tr></tbody>
+  </table>
+</div>
+```
+Don't: put the class on the `<table>` itself; tables for layout; colour cells to show "yes".
+### FAQ `.gw-faq`
+Native `<details class="gw-faq__item">` with a `<summary>`, no script. The + turns into × when open.
+```html
+<div class="gw-faq">
+  <details class="gw-faq__item"><summary>Does GemBoss run my ads?</summary><p>No. …</p></details>
+</div>
+```
+Don't: hide content a reader needs to decide (prices, terms) only inside a closed answer; more than eight questions.
+### Not in 0.1.0
+`.gw-tabs` does not exist yet. If a page needs tabs, build a stopgap (`kitgap-tabs`) and report the gap.
+## Header
+| class | for |
+|---|---|
+| `.gw-announce` | optional one-sentence bar above the header, with one link |
+| `.gw-header` (`data-gw-header`) | the sticky, flat 64px bar with one hairline; `.is-scrolled` darkens the hairline |
+| `.gw-header__bar` | the row inside (`.gw-wrap gw-header__bar`) |
+| `.gw-brand`, `__mark`, `__name` | logo (26px) and name, linking home |
+| `.gw-nav`, `__list`, `__item`, `__trigger`, `__link` | the desktop nav (from 1080px); `__trigger` opens a mega panel, `__link` is a plain link; `aria-current="page"` underlines it in the accent |
+| `.gw-mega`, `__grid`, `__col`, `__heading`, `__link`, `__icon`, `__feature` | a floating card centred under the bar (radius 20, raised shadow, as on gemboss.ai): columns of links with an icon and one line each, and at most one feature card |
+| `.gw-header__actions` | theme toggle, Sign in, Book a demo, Start free, menu button |
+| `.gw-header__signin` | with `.gw-nav__link`: hidden below 1080px (it moves into the mobile menu) |
+| `.gw-theme-toggle` | icon button (`data-gw-theme-toggle`), 40px, 44px on touch |
+| `.gw-menu-toggle`, `__open`, `__close` | the menu button below 1080px; it shows `__open` or `__close` from `aria-expanded` |
+| `.gw-mobile-menu` | the full-height sheet under the bar (`hidden` until opened); `html.is-menu-open` locks the page |
+| `.gw-mobile-menu__group` | a `<details>` group with a `<summary>` row |
+| `.gw-mobile-menu__list`, `__link` | the links inside a group, 44px rows |
+| `.gw-mobile-menu__top` | a top-level row without a group (Pricing) |
+| `.gw-mobile-menu__actions` | the buttons and Sign in at the end of the sheet |
+Header buttons: the secondary one shows from 768px, the primary one from 480px; below that they live in the mobile
+menu. Full markup: `templates/header.html`.
+Don't: a floating, rounded or blurred header; more than five top-level items; a second filled button in the bar; a
+hero pulled up under the header.
+## Footer
+| class | for |
+|---|---|
+| `.gw-footer` | the footer: one hairline on top, white like the page |
+| `.gw-footer__grid` | brand block and link columns: 2 columns on phones, 3 from 768px, one row from 1080px |
+| `.gw-footer__brand` | the brand and one sentence, full width on phones |
+| `.gw-footer__col`, `__heading` | a `<nav>` column: a sentence-case heading and a `<ul>` of links |
+| `.gw-footer__bottom` | copyright, legal links, social links; alone (no grid above), it drops its top rule |
+Full markup: `templates/footer.html`. Don't: uppercase column headings; a newsletter form that stores nothing.
+## Sections
+| class | for |
+|---|---|
+| `.gw-hero` | the first screen and the only `<h1>`; `.gw-dim` in its h1 sits on its own line |
+| `.gw-hero__wash` | an empty `aria-hidden` div, first in the hero: the soft colour wash (the one place for wash hues) |
+| `.gw-hero--center`, `--compact` | centred; less height and an h2-sized h1 for subpages |
+| `.gw-logos` | a proof strip: a short line and a `<ul>` of logos (28px tall) or wordmarks |
+| `.gw-stats`, `__item`, `__value`, `__label`, `__source` | three or four facts, each with its source |
+| `.gw-features` + `.gw-feature` | with a `.gw-grid--*`: icon, title, one or two lines |
+| `.gw-split`, `--reverse` | words beside a figure; two columns from 768px, words first on phones |
+| `.gw-showcase` | a night band with one large `.gw-window` and two or three `.gw-feature` points |
+| `.gw-steps` | an `<ol>` of three or four steps, numbered by the list |
+| `.gw-quote` | one real testimonial: `<figure>`, `<blockquote>`, `<figcaption>` with name, role, company |
+| `.gw-pricing` + `.gw-plan`, `--featured`, `__price` | plan cards; the featured one has an accent hairline and its badge sits on the top edge |
+| `.gw-cta` | the closing call to action, centred; put it in a night band or a soft section |
+```html
+<section class="gw-section">
+  <div class="gw-wrap">
+    <ul class="gw-stats">
+      <li class="gw-stats__item">
+        <p class="gw-stats__value">2.1 s</p>
+        <p class="gw-stats__label">Largest Contentful Paint on mobile</p>
+        <p class="gw-stats__source">Live GemBoss store, simulated 4G, median of 8 Lighthouse runs, 10 Oct 2026</p>
+      </li>
+    </ul>
+  </div>
+</section>
+```
+One snippet per section, with its limits in a comment, is in `templates/sections/`.
+Don't: a number without a source; logos or quotes you do not have permission for; a filled button on every plan
+(only the featured one); a hero without a real first line of content above the fold on a 390px phone.
+## Motion
+| class | for |
+|---|---|
+| `.gw-reveal` | fades and rises 24px into place when 15% visible (the script adds `.is-in`); shown anyway after 2.5s, and still under `prefers-reduced-motion` |
+Put it on a block (a grid, a list, a window), not on each card in a grid. Don't use it on the hero or anything in
+the first screen, and don't animate anything but `transform` and `opacity`.
+## Additions to the markup contract in 0.1.0
+The contract names the classes the script relies on; these CSS-only helpers were added with it: `.gw-page`
+(sticky footer), `.gw-h1`…`.gw-h4`, `.gw-lead`, `.gw-note`, `.gw-actions`, `.gw-footer__brand`,
+`.gw-stats__source`, `.gw-plan__price`, `.gw-menu-toggle__open` / `__close`, and the mobile menu parts
+`__group`, `__list`, `__link`, `__top`, `__actions`. `.gw-table` is the scrolling wrapper around a `<table>`.

package/docs/markup-contract.md ADDED Viewed

@@ -0,0 +1,115 @@
+# Markup contract (CSS ↔ JS ↔ templates)
+The full class list, including the CSS-only helpers added while building 0.1.0 (`.gw-h1`–`.gw-h4`, `.gw-lead`,
+`.gw-note`, `.gw-actions`, `.gw-stats__source`, `.gw-plan__price`, the mobile menu parts…), is `docs/components.md`.
+The CSS (`css/*.css`), the script (`js/website.js`) and the templates (`templates/`) agree on exactly this. Change it
+here first, then in all three.
+Prefixes: kit classes `gw-`, kit CSS variables `--gw-`, state classes `is-` (set by the script), hooks `data-gw-*`.
+BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
+## Page
+```html
+<html lang="en" data-theme?="light|dark">     <!-- absent = follow the system; the toggle sets it -->
+<body class="gw-page">
+  <a class="gw-skip" href="#main">Skip to content</a>
+  <div class="gw-announce" role="region" aria-label="Announcement">…<a href="…">…</a></div>   <!-- optional -->
+  <header class="gw-header" data-gw-header> … </header>
+  <main id="main"> sections </main>
+  <footer class="gw-footer"> … </footer>
+  <script src="…/website.js" defer></script>
+```
+## Header
+```html
+<header class="gw-header" data-gw-header>
+  <div class="gw-wrap gw-header__bar">
+    <a class="gw-brand" href="/"><img class="gw-brand__mark" src="…" alt="" width="26" height="26"><span class="gw-brand__name">GemBoss</span></a>
+    <nav class="gw-nav" aria-label="Main">
+      <ul class="gw-nav__list">
+        <li class="gw-nav__item">
+          <button class="gw-nav__trigger" type="button" aria-expanded="false" aria-controls="gw-mega-product" data-gw-mega="gw-mega-product">Product</button>
+          <div class="gw-mega" id="gw-mega-product" hidden>
+            <div class="gw-wrap gw-mega__grid">
+              <div class="gw-mega__col"><p class="gw-mega__heading">Build</p>
+                <a class="gw-mega__link" href="…"><span class="gw-mega__icon" aria-hidden="true">svg</span><span><b>Title</b><i>One line</i></span></a>
+              </div>
+              <a class="gw-mega__feature" href="…">…</a>   <!-- optional card on the right -->
+            </div>
+          </div>
+        </li>
+        <li class="gw-nav__item"><a class="gw-nav__link" href="/pricing" aria-current?="page">Pricing</a></li>
+      </ul>
+    </nav>
+    <div class="gw-header__actions">
+      <button class="gw-theme-toggle" type="button" data-gw-theme-toggle aria-label="Switch to dark theme">svg</button>
+      <a class="gw-nav__link gw-header__signin" href="…">Sign in</a>
+      <a class="gw-btn gw-btn--secondary gw-btn--sm" href="…">Book a demo</a>
+      <a class="gw-btn gw-btn--sm" href="…">Start free</a>
+      <button class="gw-menu-toggle" type="button" aria-expanded="false" aria-controls="gw-mobile-menu" data-gw-menu-toggle aria-label="Open menu">svg</button>
+    </div>
+  </div>
+  <div class="gw-mobile-menu" id="gw-mobile-menu" hidden> …the same links as lists, and the actions… </div>
+</header>
+```
+Script behaviour:
+- **Mega menu**: click on a trigger toggles its panel (`hidden` removed, `aria-expanded="true"`, `.is-open` on the
+  `.gw-nav__item`). Hover opens on fine pointers after 80ms and closes 160ms after leaving item and panel. Only one
+  open at a time. `Escape` closes and returns focus to the trigger. A click outside closes. Arrow keys are not required.
+- **Mobile menu** (below 1080px the `.gw-nav` and sign-in hide, `.gw-menu-toggle` shows): the toggle flips `hidden`
+  on `#gw-mobile-menu`, `aria-expanded`, `.is-menu-open` on `<html>` (the CSS locks scroll), and its `aria-label`
+  (Open menu / Close menu). `Escape` closes. Resizing above 1080px closes it.
+- **Labels in other languages**: the script never writes English over a translated page. Give the toggles their
+  words with `data-gw-label-open` / `data-gw-label-close` (menu toggle) and `data-gw-label-dark` /
+  `data-gw-label-light` (theme toggle); without them it keeps the markup's own `aria-label`, then falls back to English.
+- **Theme toggle**: cycles light ↔ dark by setting `data-theme` on `<html>`, stores the choice in `localStorage`
+  (`gw-theme`, every access in try/catch), updates `aria-label`. On load, a stored choice is applied before paint by a
+  one-line inline script in `<head>` that the template carries (`templates/page.html`).
+- **Reveal**: elements with `.gw-reveal` get `.is-in` when 15% visible (IntersectionObserver, once). Failsafe: after
+  2.5s, or if IntersectionObserver is missing, all get `.is-in`. Under `prefers-reduced-motion` the CSS shows them
+  without motion.
+- **Header**: `.is-scrolled` on `[data-gw-header]` once the page scrolled more than 8px (the CSS may use it for the
+  hairline only; the bar does not change height or colour).
+- **Current page**: the script marks `aria-current="page"` on `.gw-nav__link` / `.gw-mega__link` whose `href`
+  pathname equals `location.pathname` (when the markup did not already).
+## Components (CSS only)
+| class | what |
+|---|---|
+| `.gw-btn` (+ `--secondary`, `--ghost`, `--on-night`, `--sm`, `--lg`, `--block`) | actions; rectangle 8px, ink fill by default |
+| `.gw-link` (+ `--arrow`) | inline text link in the accent; `--arrow` adds → that moves 2px on hover |
+| `.gw-label` | the label above a heading: 13px muted, 8px accent square before it |
+| `.gw-dim` | the muted first sentence inside a headline |
+| `.gw-chip` (+ `.is-active`) | selectable token, pill |
+| `.gw-badge` (+ `--accent`, `--success`, `--warning`) | small status, pill |
+| `.gw-card` (+ `--soft`, `--link`) | white box, 1px hairline, radius 12; `--link` makes the whole card an `<a>` |
+| `.gw-window` (+ `__bar`, `__body`) | a framed screenshot/mock-up, like a browser or app window |
+| `.gw-icon` | 20px inline stroke SVG wrapper |
+| `.gw-list--check` | list with check marks |
+| `.gw-table` (+ `--compare`) | data / comparison table; scrolls inside its box on phones |
+| `.gw-faq` (`<details class="gw-faq__item"><summary>`) | FAQ accordion with no script |
+| `.gw-tabs` (`role="tablist"`) | NOT in 0.1.0 (a reported gap would add it) |
+## Sections
+| class | what |
+|---|---|
+| `.gw-section` (+ `--soft`, `--tight`) | vertical rhythm; `--soft` on `--gw-bg-soft` |
+| `.gw-band--night` | a dark band (max three per page plus the closing CTA, never adjacent) |
+| `.gw-section__head` (+ `--center`) | label + h2 + one or two lines, max 660px |
+| `.gw-hero` (+ `__wash`, `--center`, `--compact`) | first screen; `__wash` is the soft colour wash behind it |
+| `.gw-logos` | proof strip of customer or partner logos (real ones only) |
+| `.gw-stats` (`__item`, `__value`, `__label`) | 3–4 facts in a row, each with its source |
+| `.gw-features` (`.gw-grid--3` of `.gw-feature`) | icon, title, one or two lines |
+| `.gw-split` (+ `--reverse`) | text beside a figure; stacks on phones |
+| `.gw-showcase` | night band with a large screen and two or three points |
+| `.gw-steps` (`<ol>`) | numbered steps, how it works |
+| `.gw-quote` | one real testimonial with name, role, company |
+| `.gw-pricing` (`.gw-plan`, `--featured`) | plan cards; the featured one has a hairline in the accent, not a fill |
+| `.gw-cta` | closing call to action band |
+| `.gw-footer` (`__grid`, `__col`, `__heading`, `__bottom`) | footer columns + bottom row |

package/docs/philosophy.md ADDED Viewed

@@ -0,0 +1,69 @@
+# Why the kit looks the way it does
+`AGENTS.md` says what to do. This page says why, so that when a case is not covered you can decide in the same
+spirit. Each rule came from measuring real pages, not from taste alone.
+## One language for the site and the product
+A visitor crosses from the website into the product in one click. If the two disagree (a cream site and a white app,
+a purple button outside and a black one inside), the seam is exactly where trust is decided. So the website uses the
+product's language: white canvas, ink actions, one accent, hairlines, almost no shadow.
+## The thing you click is ink
+A page has one thing it wants you to do. Near-black is the strongest mark on white and stays readable in every
+light; the accent colour is louder but weaker as an instruction, and a page full of accent-coloured buttons has no
+hierarchy left. The accent marks where you are and what is interactive in text: links, focus, the active item, the
+small square before a label.
+## Shapes carry meaning
+Rectangles act, pills choose. When every button is a rectangle and every chip is a pill, people stop reading the
+shape and read the words. A radius scale with seven steps means two cards side by side never differ by 2px, which is
+the kind of drift that makes a page feel assembled rather than designed.
+## Separation by line and space, light only at rest
+A shadow says "this floats above". Cards on a page do not float; they sit on it. A 1px hairline and the dashboard's
+resting shadow (two faint pixels) separate a card and keep the page calm; nothing lifts on hover. Larger light is
+spent where it means something: a popover such as the mega menu, an illustration that lights itself.
+## Scales instead of eyeballing
+On gemboss.ai, before the scales, the four most common paddings were 9, 5, 12 and 15 pixels: spacing tuned by eye,
+one element at a time. 1,291 of 2,076 spacing values belonged to no scale. Nobody sees one 15px; everybody feels a
+page made of hundreds of them. The scales (4px base, the type steps) make "a bit more space" a choice between two
+real values.
+## Sentence case and a quiet label
+Uppercase tracked labels ("FEATURES") shout and say nothing. A label in sentence case, muted, led by a small accent
+square, tells the reader where they are and lets the headline do the talking. The house headline shape, a muted
+first sentence and an ink second one, gives every section the same rhythm: context, then the point.
+## One idea per section
+Visitors scan. A section that makes one point, with one action, survives scanning; a section with three ideas loses
+all three. Fewer, clearer sections beat a long page of everything.
+## Real words, or a visible gap
+A made-up number or a fake testimonial is found out, and then every other claim on the page is doubted. A visible
+`[PRICE]` is honest and gets filled; an invented one ships.
+## Motion that does not cost
+Only `transform` and `opacity` move, because they do not re-layout the page and stay at 60 fps on a cheap phone.
+Everything stops for people who ask the system for reduced motion. Motion explains (a panel opens from its
+trigger, a section arrives as you reach it); it never decorates.
+## Phones first in the checking, not just in the CSS
+Most visitors from ads arrive on a phone. A label that fits at 1366px and overflows at 320px is a broken page for
+most of them. That is why the kit is checked at 320, 390, 768 and 1366px, and why translated labels must not grow.
+## When the kit is not enough
+A kit that people work around stops being a kit. The workaround is allowed, in the site, with the tokens, under a
+`kitgap-` name, and it is reported. The next version of the kit gets the real thing, every site gets it, and the
+workaround is deleted. That loop, not the first release, is what keeps all GemCommerce websites one family.