@usableapp/cardds 0.1.7 → 0.2.1

package/README.md

@@ -1,13 +1,17 @@
 # cardds
 
+> **For:** people and AI alike — this is the reference, the one place a rule of the system is written.
+> The other docs only point here: `CLAUDE.md` (AI working IN this repo — decisions and gotchas),
+> `docs/guides/building-with-cardds.md` (AI composing screens in React; shipped to Claude Design),
+> the `/cardds` skill (AI in another project — install + contract). To LOOK at the system: `npm run dev`.
+
 Card-first mobile design system, **React-first**: `src/` is the component
 library — one thin component per pattern, emitting exactly the markup the CSS
 documents. The CSS (`css/*.css`)
 stays the only truth: a component never styles anything, it only picks classes
 from props. The CSS also works alone, with no build, for a host that wants
-class names rather than components. The demo is `/gallery` (`npm run dev`):
-every component's stories, live, searchable; `tests/fixtures/` holds the
-HTML pages the acceptance tests drive (not a demo — nobody reads them).
+class names rather than components. The demo is the gallery (`npm run dev`):
+every component's stories, live, searchable.
 
 Repo: **https://github.com/everysundays/cardds** (private — this is the
 source of truth; every consuming project vendors a copy from here, never
@@ -25,29 +29,28 @@ licences (`fonts/LICENSES.md`).
 npm install
 npm run dev          # the gallery on http://localhost:5174 — every story, searchable
 npm run build        # the library: icons → src/type/icons.ts · tsc → dist/ (ESM + .d.ts) · dist/cardds.css (flattened)
-npm test             # Playwright: the step/sheet/centre geometry on tests/fixtures/, the app's screens and the four handoff upgrades
+npm test             # Playwright: the tokens and the step/sheet/centre geometry on tests/fixtures/, the gallery's stories and behaviours
 ```
 
 ```tsx
-import { Screen, TopBar, Step, BaseContent, Sheet, SheetBody, CardHead, Field, Pin, ActionBar, Btn } from 'cardds';
-import 'cardds/dist/cardds.css';   // or cardds/cardds.css with the css/ folder beside it
+import { Screen, TopBar, Step, BaseContent, Sheet, SheetBody, CardHead, Field, Pin, ActionBar, Btn } from '@usableapp/cardds';
+import '@usableapp/cardds/dist/cardds.css';
+import './theme.css';   // the project's own look, after the system's — see "A project's theme"
 ```
 
 `src/index.ts` imports `cardds.js` for its side effects, so a React host gets
 the behaviours for free: the `.sheet` handle (tap, drag, keyboard) with the
 focus and on-screen-keyboard raises, `.sheet-stack--tap` opening and closing,
 the `.pin` auto-advance (a digit moves on, Backspace moves back, a paste fills
-the code), a card heading that needs more than two lines squeezing its type
-(see *Anatomy*), and the `.dropdown` writing its picked value back. `Icon`
+the code), the modal's close, and the `.dropdown` writing its picked value back. `Icon`
 inlines the 56 symbols of `icons.svg` at build time, so no sprite file ships.
 
-**The gallery** (`gallery/`): Vite + React Router, `cardds` aliased to `src/`
-so the gallery and the package share one truth with no build between them.
-`/` lists every story of every component, `/:Name` one component. (The
-Commons Time Bank app that used to live here — twelve screens from
-`docs/handoff/commons-time-bank-SPEC.md` — was dropped on 2026-09-16; nobody
-looked at it, the gallery is the demo. The type scale is the `Text · Scale`
-story.)
+**The gallery** (`gallery/`, `npm run dev` → http://localhost:5174): Vite + React Router, `cardds`
+aliased to `src/`, so the gallery and the package share one truth with no build between them.
+`/` every story of every component, `/:Name` one component — each `.design-sync/previews/<Name>.tsx`
+story live in a 375×812 phone cell, grouped by `src/<group>/`, searchable; switches for the palette
+(`own` = a colour well per colour base), inspect (box outlines + dimensions), text size, and a slider
+per size base. Nothing is hand-listed: add a preview file or a story and it shows.
 
 **CSS only** (no React, no build):
 
@@ -62,12 +65,7 @@ popover) but won't update its label, a stack still displays but won't open, a
 sheet renders every state but only moves when a class changes, a pin is six
 plain inputs.
 
-The one place to look is `/gallery` (`npm run dev` → `http://localhost:5174/gallery`):
-every `.design-sync/previews/<Name>.tsx` story, live, grouped by `src/<group>/`,
-searchable, in a 375×812 phone cell, with a palette switch and an inspect
-switch (box outlines + dimensions on hover). `tests/fixtures/*.html` (ex
-`demo/`) are the pages `tests/step.spec.js` and `tests/centre.spec.js` measure;
-`tests/gallery.spec.js` drives the gallery. Nothing here is verified by eye.
+`tests/fixtures/*.html` are the pages the geometry tests measure — not a demo. Nothing here is verified by eye.
 
 ### In another project
 
@@ -83,7 +81,6 @@ import { Card, CardHead, Btn } from '@usableapp/cardds';
 import '@usableapp/cardds/dist/cardds.css';   // the CSS, fonts resolve from the package
 ```
 
-Browse what exists at `npm run dev` → `/gallery` in this repo (every component, every story, searchable).
 
 **CSS only:** there's no build and no dependencies, so installing is cloning once, then
 copying the static files into your project — never edit the clone, never
@@ -105,21 +102,17 @@ cp -R ~/Sites/cardds/css ~/Sites/cardds/fonts ~/Sites/cardds/cardds.css \
 folder next to it, and `fonts/` beside that (`css/fonts.css` reaches the faces
 as `../fonts/`). `icons.svg` is referenced by path from your markup
 (`<use href="icons.svg#bell">`), so put it where those references resolve.
-Then follow the rules below — the short version is: tune `palette.css` and
-nothing else, and never write a raw hex or px in a component.
+Then follow the rules below — the short version is: tune your own `theme.css`
+(a copy of `css/theme.template.css`, see "A project's theme") and nothing else, and never write a raw hex or px in a component.
 
 The repo is private, so cloning needs an account with access (`everysundays`
 on GitHub) — set that up as an SSH host alias if you already use a different
 account for `git@github.com` day to day, the way this machine's `~/.ssh/config`
 does it for other `everysundays` repos.
 
-**Recording what you copied matters.** A vendored copy with no record of which
-commit it came from can't be told apart from a fork. timebank's
-`scripts/cardds-vendor.mjs` is the reference: `npm run cardds:sync` copies the
-files above from a local checkout (`CARDDS_SRC`, default `~/Sites/cardds`) and
-writes `VENDORED.json` — commit hash, date, a sha256 per file — so
-`npm run check:cardds` can catch a hand edit or a stale copy. `git pull` that
-checkout before syncing to pick up what's been pushed here.
+**Record what you copied.** A vendored copy with no record of the commit it came
+from can't be told apart from a fork: write the commit hash (and a sha256 per
+file) beside the copy, so a hand edit or a stale copy can be caught.
 
 Working with Claude in another project? The `/cardds` skill
 (`~/.claude/skills/cardds/`) carries the install and the contract, and points
@@ -204,9 +197,10 @@ whose markup has rules, because the sheet's box is the step itself:
       …cardds controls (.field / .pin / .composer / .rows + .check / .segment /
       .chip-grid), or small content cards (.card--sm)…
     </div>
+    <div class="card__foot"><button class="btn btn--primary btn--block">…the one button that finishes the sheet…</button></div>
   </article>
 </section>
-<div class="action-bar">…one wide button…</div>
+<!-- no .action-bar: a bar is the base's, never in front of a sheet -->
 ```
 
 - **`.step` needs a bounded column**: a direct child of `.screen--fill`, or
@@ -239,9 +233,13 @@ whose markup has rules, because the sheet's box is the step itself:
 - **The bar is outside the step**, after it. `.step` reads the bar's room
   from `--bar-reserve`; any parent that hosts the `.action-bar` counts
   (`<body>`, an app shell, a demo frame).
-- **A sheet inside a step never carries the step's action.** The bar is the
-  one move. A sheet gets its own buttons only on a screen that has no bar —
-  the map sheet in `sheet.html`, whose "Directions" is that screen's move.
+- **Layers: the base, the sheet over it, the top bar** (Lh 2026-09-20). The `.action-bar` belongs to the
+  BASE — the move of a page of words (a pager, or one wide button). It is never in front of a sheet. A
+  screen with a sheet finishes ON the sheet: a `.card__foot`, the sheet's last child — ONE row, the page's
+  conclusion. The foot stands on the screen's bottom edge at half, 3q and full alike (a layer as tall as
+  the sheet, slid up by the share the sheet slid down — `sheet.css`), and is gone at peek. Nothing inside
+  the sheet's body commits on its own (a `Composer` there takes no `send`). A bar written beside a sheet anyway
+  stands down — no pointer (`actions.css`), `inert` (`cardds.js`): a net for a mistake, not a layout.
 - **Never write a sheet's height, and never a `.sheet-stage` inside a step.**
   State is a class (`sheet--peek` / `--half` / `--full`); the sheet is always
   the step's full height and only slides. `carddsSheetSet(sheet, state)` is
@@ -290,6 +288,23 @@ between at 40% down the screen (see *Anatomy*, "Where the centre is"):
 - **The round pager** is `.action-bar--pager` (or an `.action-bar__tier--pager`)
   holding two `.icon-btn`s and nothing else: they stand at the two edges. The
   step that commits still goes back to one wide button (rule 3).
+- **BaseContent that moves** (Lh 2026-09-20) — two ways, never both on one screen:
+  - *Pages of words:* `.step > .pages > .base-content` (one `aria-current="step"`, the rest `inert`) — every page
+    one height, the round pager turns them (`slideTo()`), the words slide like a page. No sheet there.
+  - *Called sheets:* the base offers WAYS IN — sign in · new phone · join — as buttons (`.cta-pack`), each naming a
+    sheet: `<button aria-controls="signin">` … `<article id="signin" class="card sheet sheet--away" inert
+    data-sheet-states="peek full">`. Each sheet holds that way's WHOLE form and its own submit on its foot, leading
+    to the next page; the base carries no control and the screen no bar. `.sheet--away` = not on the screen (slid
+    out, hidden once gone). Nothing waits at peek. A tap raises its sheet to full and sends any other away; the
+    handle takes it down to peek and never further — the words and the other buttons are back in reach (the step
+    publishes `--sheet-room`, the peek strip, so they scroll clear of it); the same button raises it from peek to full.
+    **Never a form taken apart** — one sheet per field, a "send" left on the base: a form lives whole in ONE sheet.
+    Fixture `tests/fixtures/calls.html`, tests `tests/calls.spec.js`, stories `Step · Walks` / `Step · Calls`.
+- **A pager turns pages of words, never a screen with a sheet** (Lh 2026-09-20). A
+  sheet means this screen has work that cannot be walked past: no ← →, no bar at all — the sheet's
+  own foot finishes it. Should a pager meet a sheet anyway it stands
+  down while the sheet is on the screen, a peeking one included: dimmed, no pointer
+  (`actions.css`), `inert` (`cardds.js`).
 
 ## Files
 
@@ -297,6 +312,7 @@ between at 40% down the screen (see *Anatomy*, "Where the centre is"):
 |---|---|---|
 | `css/fonts.css` + `fonts/` | the two `@font-face`s: PK Nonthaburi (body, `--font-ui`), FC Pride (display, `--font-display`); the font files and their licences | when swapping a face |
 | `css/tokens.css` | spacing, radius, type levels, motion (`--motion-sheet`), the human centre (`--screen-centre`), grayscale role defaults; registers the two sheet tokens (`--sheet-peek`, `--sheet-half`) so script can read them resolved | rarely |
+| `css/theme.template.css` | **a project's theme** — the four size bases + the colour roles, at their defaults; NOT in the bundle: copied into the project as its `theme.css`, loaded after `cardds.css` | copy it, don't edit it |
 | `css/palette.css` | **color settings — palettes as role-token overrides** | yes, this one |
 | `css/base.css` | reset, surface, typography classes, `.base-content` | rarely |
 | `css/card.css` | `.card` + its skeleton (`.card__head` / content / `.card__foot`), `.card-list`, `.card--row`, `.icon-row`, stats, `.card--centre` (one card at the human centre of a fill screen) and `.screen__centre` (a small group there) | when adding variants |
@@ -309,9 +325,9 @@ between at 40% down the screen (see *Anatomy*, "Where the centre is"):
 | `css/numbers.css` | `.ring` gauge, `.track` steps, `.card--band` + `.band-stack`, `.dotgrid`, `.picker`, `.badge`, `.bars` | big numbers |
 | `css/people.css` | `.avatar` (sm/lg/xl, outline, add, on, halo), `.avatar-stack`, `.avatar-pick` | people |
 | `css/choice.css` | `.check`, `.toggle`, `.chip-grid` + `.chip--pick` (+ `--sign`), `.day-strip`, `.calendar`, `.mood`, `.pin`, `.composer`, `.slider` | choice controls |
-| `css/lists.css` | `.row` / `.rows` (frameless rows in a card), `.kv`, `.kv-grid`, `.timeline`, `.legend`, `.link` | lists inside cards |
+| `css/lists.css` | `.row` / `.rows` (frameless rows in a card), `.kv`, `.kv-grid`, `.thread` + `.bubble` (chat: theirs left, mine right, no tail), `.timeline`, `.legend`, `.link` | lists inside cards |
 | `css/media.css` | `.card--cover`, `.quote`, `.tile-grid` + `.tile`, `.card--fold`, `.mosaic`, `.wave` | media & display |
-| `css/layover.css` | `.modal` (the ask: `__lift` + `__drawer`, closes on any drawer button → `cardds:modal`), `.menu` (popover), `.banner` (details), `.float-bar`, `.callout`, `.chip--bubble`, `.deck` | cards over content |
+| `css/layover.css` | `.modal` (the ask: `__lift` + `__drawer`, closes on any drawer button → `cardds:modal`), `.menu` (popover), `.banner` (details), `.float-bar`, `.callout`, `.deck` | cards over content |
 | `icons.svg` | Lucide sprite (ISC), 56 minimal stroke icons | add symbols as needed |
 | `src/` → `dist/` | the React library: `src/<group>/<Name>.tsx`, one thin component per pattern, JSDoc = the rule; built by `npm run build` (tsc) into `dist/` with `.d.ts`; `src/type/icons.ts` is generated from `icons.svg` | when adding a component |
 | `gallery/` | the gallery site: `npm run dev` → `/` every story, `/:Name` one component (`gallery/src/Gallery.tsx` globs `.design-sync/previews/`) | the demo |
@@ -502,6 +518,63 @@ Demo: the *skeleton* block at the top of `elements.html`.
     `--on-accent` to its own ink and bg, so every accent consumer (buttons,
     checks, toggles, rings, selected days) inverts without extra rules.
 
+## A project's theme
+
+A project retunes cardds from ONE file of its own, and nothing else. Copy
+`css/theme.template.css` into the project as `theme.css`, load it **after**
+`cardds.css`, change values:
+
+```css
+:root {
+  --sp-base: 0.3rem;   /* roomier */
+  --r-base: 0.5rem;    /* tighter corners */
+  --color-surface: #faf6ee;  --color-ink: #1f1b16;  --color-paper: #fff;
+  --color-brand: #c2410c;    --color-on-brand: #fff;
+}
+```
+
+```html
+<html data-palette="own">   <!-- colours of your own = coloured mode; any value no stock palette uses -->
+```
+
+That file is the whole public surface:
+
+| what | tokens | moves |
+|---|---|---|
+| room **between** things | `--sp-base` (0.25rem = 4) | every `--sp-N` = base × N → paddings, gaps, the screen's inset, the bar's reserve, the sheet's peek |
+| type | `--fs-base` (1rem = 16) | every `--fs-*`, `--badge`, `--icon-xs` |
+| corners | `--r-base` (1rem = 16) | every `--r-*`; `0` = square. `--r-chip` stays fully round |
+| the size **of** things | `--tap-base` (3rem = 48) | `--tap*`, `--btn-h`, `--chip-h`, `--bar-h`, `--header-h`, `--fab`, `--icon*`, `--avatar*`, `--dot*`, `--ring*`, `--tile-*`. `--tap*` never under `--tap-floor` (44px) |
+| faces | `--font-ui`, `--font-display` | |
+| colour | `--color-surface`, `--color-ink`, `--color-paper`, `--color-brand`, `--color-on-brand` — no default: unset = the wireframe | every role: surface / words, the three card tones (paper · the brand washed 14% into the surface · the brand), the muted inks (the ink washed into their ground), accent, neutral actions, `--dot-a` |
+| colour roles (the escape hatch) | `--surface`, `--on-surface(-muted)`, `--card-{1,2,3}-{bg,ink}`, `--card-border`, `--card-muted`, `--card-2-muted`, `--accent`, `--on-accent`, `--action-{bg,ink,border}`, `--pos`, `--neg`, `--dot-{a,b}` | a role set directly wins over its derivation; the tints derive from the roles |
+
+Rules:
+
+- **A base, never a multiplier.** Every size token is `calc(base × multiplier)`
+  in `tokens.css`; the multipliers are the system's proportions. A project
+  never sets a derived token (`--sp-4`, `--fs-h1`, `--r-card`, `--tap`…), a
+  private one (`--_*`), or a published one (`--card-pad`, `--bar-reserve`, `--sheet-*`).
+- **On `:root` only.** The derived tokens are computed where they are declared
+  (`:root`), so a base set on a subtree does not reach them.
+- **After `cardds.css`.** A stock palette's block and a project's `:root` weigh
+  the same; the later file wins.
+- **Coloured mode is the attribute.** `data-palette`, whatever its value, is what
+  trades the wireframe's borders for the card's shadow and the controls' soft
+  edge (`palette.css`, `forms.css`). Colours of your own → `<html data-palette="own">`.
+  Without it the colours still apply, on wireframe borders.
+- **cardds does not judge the colours.** No contrast check, no warning — a
+  theme's values are the project's call. The derivations are only starting points;
+  any role can be set outright.
+- `--text-scale` (below) is the member's setting, not the theme's: it scales
+  everything, the bases included.
+
+Try it live: the gallery's nav (`npm run dev`) has a slider per size base, and
+palette `own` shows a colour well per colour base.
+`tests/tokens.spec.js` holds the defaults to the px they always were and the
+template to the defaults; the step / centre geometry runs at two extreme
+themes (`tight`, `loose`).
+
 ## New palette
 
 Copy any block in `palette.css`, rename, retune:
@@ -517,9 +590,10 @@ Copy any block in `palette.css`, rename, retune:
 
 ## Scale: everything is rem
 
-Every length token is rem (`--sp-4: 1rem`, `--tap: 3rem`, `--r-card: 2rem`,
-`--fs-h1: 1.75rem` …), so the whole system resizes from one number: the root
-font size. `base.css` keeps it at `100%` (the user's text-size setting, 16px by
+Every length token resolves to rem — a multiplier × one of four rem bases
+(`--sp-4` = `--sp-base` × 4 = 1rem, `--tap` = `--tap-base` = 3rem, `--r-card` =
+`--r-base` × 2, `--fs-h1` = `--fs-base` × 1.75; see "A project's theme") — so the
+whole system still resizes from one number: the root font size. `base.css` keeps it at `100%` (the user's text-size setting, 16px by
 default) and steps narrow phones (≤360px) to `93.75%`, which keeps the 25rem
 column, its 48px taps and its type in proportion on 320–360 screens. Only
 `--border-w`, `--rule-w` and the focus ring stay in px, so edges stay crisp.

package/cardds.js

@@ -207,16 +207,19 @@ function carddsSheetStates(sheet) {
 }
 
 function carddsSheetState(sheet) {
+  if (sheet.classList.contains('sheet--away')) return 'away'; // a called sheet not on the screen — a state to set, never one to snap or tap to
   return CARDDS_SHEET_STATES.find(s => sheet.classList.contains('sheet--' + s)) ?? 'half'; // the CSS default
 }
 
 function carddsSheetSet(sheet, state) {
-  if (!CARDDS_SHEET_STATES.includes(state)) return;
+  if (state !== 'away' && !CARDDS_SHEET_STATES.includes(state)) return;
   const was = carddsSheetState(sheet);
-  CARDDS_SHEET_STATES.forEach(s => sheet.classList.toggle('sheet--' + s, s === state));
+  [...CARDDS_SHEET_STATES, 'away'].forEach(s => sheet.classList.toggle('sheet--' + s, s === state));
+  sheet.inert = state === 'away';
   /* where a tap from peek returns to: the non-peek state it is going to, or the
      one it is leaving (an authored state never passed through here before) */
-  const home = state !== 'peek' ? state : was !== 'peek' ? was : null;
+  const rests = s => s !== 'peek' && s !== 'away';
+  const home = rests(state) ? state : rests(was) ? was : null;
   if (home) sheet.dataset.sheetHome = home;
   if (was !== state) sheet.dispatchEvent(new CustomEvent('cardds:sheet', { bubbles: true, detail: { state } }));
 }
@@ -375,7 +378,9 @@ function carddsSheetReveal(el, atLeast) {
   const box = sheet.parentElement.getBoundingClientRect(); // the box that clips it: .step or .sheet-stage
   const vv = window.visualViewport;
   const cut = vv ? Math.min(box.bottom, vv.offsetTop + vv.height) : box.bottom;
-  const need = el.getBoundingClientRect().height;
+  const foot = sheet.querySelector(':scope > .card__foot'); // the sheet's own button stands on the cut (sheet.css): the control has to clear it too
+  const button = foot?.firstElementChild; // the foot is a layer as tall as the sheet: what the control must clear is its strip
+  const need = (el.closest('.field') ?? el).getBoundingClientRect().height + (button ? box.bottom - button.getBoundingClientRect().top : 0); // from the button's top to the box's bottom edge, where it stands
   let to = states[states.length - 1];
   for (let i = from; i < states.length; i++) {
     if (cut - (restTop + stops[states[i]] + bodyTop) >= need) { to = states[i]; break; }
@@ -414,3 +419,56 @@ document.addEventListener('click', e => {
     stage.dispatchEvent(new CustomEvent('cardds:modal', { bubbles: true, detail: { answer: btn.dataset.answer ?? null } }));
   });
 });
+
+/* ---- called sheets (sheet.css): a button in a step's words names a sheet with aria-controls ----
+   (The base offers ways in — sign in · new phone · join — each sheet holds that way's whole form and
+   its own submit on its foot.) A tap on it sends every other sheet of that step away and raises its own to the top state it snaps
+   to (full) — from away, and from peek alike. The step then publishes --sheet-room, the strip the
+   sheet keeps at peek, so the words can scroll their buttons clear of it (step.css); the buttons say
+   aria-expanded. */
+function carddsSheetCall(sheet) {
+  const step = sheet.parentElement;
+  step.querySelectorAll(':scope > .sheet').forEach(s => { if (s !== sheet && carddsSheetState(s) !== 'away') carddsSheetSet(s, 'away'); });
+  const states = carddsSheetStates(sheet);
+  const top = states.includes('full') ? 'full' : states[states.length - 1];
+  const was = carddsSheetState(sheet);
+  if (was !== top) carddsSheetSet(sheet, top);
+  if (was === 'away') sheet.querySelector(':scope > .sheet__handle')?.focus({ preventScroll: true });
+}
+function carddsStepSync(step) {
+  const callers = [...step.querySelectorAll('[aria-controls]')].filter(b => document.getElementById(b.getAttribute('aria-controls'))?.matches('.step > .sheet'));
+  if (!callers.length) return; // a plain step: one sheet, nothing calls it, nothing to publish
+  const on = [...step.querySelectorAll(':scope > .sheet')].find(s => carddsSheetState(s) !== 'away');
+  if (on) step.style.setProperty('--sheet-room', getComputedStyle(on).getPropertyValue('--sheet-peek')); // registered: reads back in px
+  else step.style.removeProperty('--sheet-room');
+  callers.forEach(b => b.setAttribute('aria-expanded', String(carddsSheetState(document.getElementById(b.getAttribute('aria-controls'))) !== 'away')));
+}
+document.addEventListener('click', e => {
+  const caller = e.target.closest('[aria-controls]');
+  const sheet = caller && document.getElementById(caller.getAttribute('aria-controls'));
+  if (sheet && sheet.matches('.step > .sheet')) carddsSheetCall(sheet);
+});
+document.addEventListener('cardds:sheet', e => { const step = e.target.closest?.('.step'); if (step) carddsStepSync(step); });
+
+/* ---- bar guard: a bar is the base's, never in front of a sheet (actions.css, Lh 2026-09-20) ----
+   A sheet on the screen covers the bar and CSS takes the pointer away; `inert` takes the keyboard and
+   the accessibility tree too. Re-checked when a sheet changes state and when the page changes. */
+function carddsPagerGuard() {
+  document.querySelectorAll('.action-bar').forEach((bar) => {
+    const host = bar.parentElement;
+    bar.inert = !!(host && host.querySelector('.step > .sheet:not(.sheet--away)'));
+  });
+}
+if (typeof document !== 'undefined') {
+  document.addEventListener('cardds:sheet', carddsPagerGuard);
+  const start = () => {
+    carddsPagerGuard();
+    let queued = false;
+    new MutationObserver(() => {
+      if (queued) return;
+      queued = true;
+      requestAnimationFrame(() => { queued = false; carddsPagerGuard(); });
+    }).observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['class'] });
+  };
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start); else start();
+}

package/css/actions.css

@@ -239,6 +239,14 @@
      <button class="icon-btn icon-btn--invert" aria-label="ถัดไป">…</button>
    </div>   — or the same two in an .action-bar__tier--pager under a control  */
 .action-bar--pager { align-items: center; }
+/* The bar belongs to the BASE (Lh, 2026-09-20): it is the move of a page of words — a pager turning
+   them, or one wide button. It is never in front of a sheet: a sheet that is on the screen covers it
+   (step.css, "layers"), a peeking one included, and the button that finishes a sheet is the sheet's own
+   foot (sheet.css). So a pager never works beside a sheet — that screen has work that cannot be walked
+   past — and neither does any other bar: while a sheet is on (only .sheet--away, a sheet not called yet,
+   is not), the bar takes no pointer here and cardds.js makes it inert, so the keyboard cannot reach what
+   the eye cannot see. */
+:has(.step > .sheet:not(.sheet--away)) > .action-bar { pointer-events: none; }
 /* the page dots: under the card in a .screen__centre group; tight gaps */
 .pager__at { flex: 0 1 auto; min-width: 0; overflow: hidden; display: flex; align-items: center; gap: var(--sp-1); }
 .pager__at > * {

package/css/card.css

@@ -209,7 +209,7 @@
    and updates inside it; a browser without them (the floor: Chrome 105 / iOS 16)
    simply switches. Only the card is named; the rest of the page must not
    cross-fade. */
-.screen__centre > .card, .pages > .card[aria-current] { view-transition-name: centre-card; }
+.screen__centre > .card, .pages > [aria-current] { view-transition-name: centre-card; }
 
 /* ---- pages: the cards of a walk, all one height ----
    A sequence the member walks (an introduction) reads steadier when every card
@@ -223,8 +223,14 @@
      <article class="card" inert>…</article>
    </div><div class="pager__at">…</div></div> */
 .pages { display: grid; }
-.pages > .card { grid-area: 1 / 1; align-content: start; } /* stretched to the cell, the words stay at the top */
-.pages > .card[inert] { visibility: hidden; }
+.pages > :is(.card, .base-content) { grid-area: 1 / 1; align-content: start; } /* stretched to the cell, the words stay at the top */
+.pages > [inert] { visibility: hidden; }
+/* pages of WORDS (Lh, 2026-09-20): the same walk with .base-content pages, on the base — in a .step the
+   .pages is the reading block (step.css), the round pager in the bar turns it, the same slideTo().
+   <section class="step"><div class="pages">
+     <section class="base-content" aria-current="step">…</section>
+     <section class="base-content" inert>…</section>
+   </div></section> <div class="action-bar action-bar--pager">← →</div> */
 ::view-transition-old(root), ::view-transition-new(root) { animation: none; }
 ::view-transition-old(centre-card), ::view-transition-new(centre-card) {
   animation-duration: var(--motion-slide);

package/css/layover.css

@@ -271,22 +271,6 @@
 }
 .callout__title { font: var(--type-title); }
 .callout__sub { font: var(--type-caption); opacity: 0.7; }
-/* speech chip: a chip with the same tail (mascot / greeting) */
-.chip--bubble { position: relative; }
-.chip--bubble::after {
-  content: "";
-  position: absolute;
-  left: var(--sp-4);
-  bottom: calc(-1 * var(--sp-2) + var(--border-w));
-  width: var(--sp-3);
-  height: var(--sp-3);
-  rotate: 45deg;
-  background: inherit;
-  border: inherit;
-  border-top: 0;
-  border-left: 0;
-}
-
 /* ---- deck: swipe cards; the last child is on top ----
    <div class="deck"><article class="card">…</article><article class="card">…</article><article class="card card--fold">front</article></div>
    <div class="deck__actions"><button class="icon-btn">×</button><button class="icon-btn icon-btn--invert">✓</button></div> */

package/css/lists.css

@@ -87,6 +87,56 @@
 .kv-cell__key { font: var(--type-caption); color: var(--card-muted); }
 .card--3 .kv-cell__key { color: inherit; opacity: 0.7; }
 
+/* ---- bubble: a chat message — theirs on the left, mine on the right (Lh 2026-09-18, replaces the chip's tail) ----
+   No tail: a rounded block whose corner nearest the sender is square-ish
+   (bottom-left for theirs, bottom-right for mine), the way messaging apps
+   draw it. Under it a caption line (time · a tick), beside it small round
+   actions (a heart, more). A .thread stacks them.
+   <div class="thread">
+     <div class="bubble"><p class="bubble__body">…</p><span class="bubble__actions">…icon-btns…</span><span class="bubble__meta">Dec 4 · 8:15</span></div>
+     <div class="bubble bubble--right">…</div>
+   </div> */
+.thread { display: grid; gap: var(--sp-4); }
+/* two columns: the message (max-content, but it gives way — minmax(0) — so a long one shrinks
+   and wraps while the actions stay beside it) and the actions; the meta on a second row under the message */
+.bubble {
+  display: grid;
+  grid-template-columns: minmax(0, max-content) auto;
+  justify-content: start;
+  align-items: center;
+  gap: var(--sp-1) var(--sp-3);
+  max-width: 88%;
+  margin-right: auto;            /* theirs: hugs the left */
+}
+.bubble--right { grid-template-columns: auto minmax(0, max-content); justify-content: end; margin-right: 0; margin-left: auto; } /* mine: hugs the right, the actions on its left */
+.bubble__body, .bubble__meta { grid-column: 1; }
+.bubble__actions { grid-column: 2; grid-row: 1; }
+.bubble--right > :is(.bubble__body, .bubble__meta) { grid-column: 2; }
+.bubble--right > .bubble__actions { grid-column: 1; }
+.bubble__body {
+  margin: 0;
+  min-width: 0;
+  padding: var(--sp-3) var(--sp-4);
+  border-radius: var(--r-card);
+  border-bottom-left-radius: var(--r-control);
+  background: var(--card-2-bg);
+  color: var(--card-2-ink);
+  font: var(--type-body);
+  overflow-wrap: anywhere;
+}
+.bubble--right > .bubble__body {
+  border-bottom-left-radius: var(--r-card);
+  border-bottom-right-radius: var(--r-control);
+  background: var(--accent);
+  color: var(--on-accent);
+  text-align: right;
+}
+.bubble__actions { display: flex; gap: var(--sp-1); flex: none; opacity: 0.7; }
+.bubble__meta { display: flex; align-items: center; gap: var(--sp-1); font: var(--type-caption); color: var(--on-surface-muted); }
+.bubble--right > .bubble__meta { justify-self: end; }
+.bubble__meta > .icon { color: var(--accent); }
+.card--3 .bubble__meta { color: inherit; opacity: 0.7; }
+
 /* ---- timeline: a hairline with date chips, entries to the right ----
    <ol class="timeline"><li class="timeline__item"><span class="timeline__mark">Wed 14</span><p class="t-body">…</p></li>…</ol> */
 .timeline {

package/css/palette.css

@@ -108,5 +108,10 @@
 
 /* Colored palettes trade wireframe outlines for soft elevation. */
 [data-palette] :is(.card, .band-stack) { box-shadow: var(--shadow-card); }
+/* COLOURED MODE is the attribute, whatever its value: a project with colours of its own (the five
+   --color-* bases, or roles, in its theme.css) writes <html data-palette="own"> — no block here matches
+   "own", so only the three generic rules apply: the card's shadow, the soft outline, the field's soft
+   edge (forms.css); and the two wireframe borders step back, as in every stock palette. */
+[data-palette] { --card-border: transparent; --action-border: transparent; }
 /* …but controls keep a faint edge so they still read as controls */
 [data-palette] { --outline: color-mix(in srgb, currentColor 25%, transparent); }

package/css/sheet.css

@@ -88,6 +88,19 @@
 .sheet--half { --_y: calc(var(--sheet-half) * 100%); --_cover: calc(var(--sheet-half) * var(--_box)); }
 .sheet--3q { --_y: calc(var(--sheet-3q) * 100%); --_cover: calc(var(--sheet-3q) * var(--_box)); }
 .sheet--peek { --_y: calc(100% - var(--sheet-peek)); --_cover: calc(var(--_box) - var(--sheet-peek)); }
+/* ---- called sheets (Lh, 2026-09-20): a .step whose .base-content has buttons that each CALL a sheet ----
+   .sheet--away = not on the screen: slid all the way out (translate, like every state — the material never
+   changes), and hidden once it has left so its shadow does not lie on the step's bottom edge; write it
+   with `inert`. A button names its sheet — <button aria-controls="when"> … <article id="when" class="card
+   sheet sheet--away" inert data-sheet-states="peek full"> — and cardds.js does the rest: a tap slides that
+   sheet up to full and sends any other one away; the handle takes it down to peek, never further, so the
+   words and the other buttons are back in reach; the same button again raises it from peek to full.
+   Nothing waits at peek before the first call. No bar on such a screen (actions.css).
+   WHAT IT IS FOR: the base offers WAYS IN — sign in · new phone · join — and each button calls a sheet
+   that holds that way's WHOLE form, its submit on the sheet's foot, leading to the next page. The base
+   carries no control. It is NOT for a form taken apart — one sheet per field, a "send" left on the base:
+   a form lives whole in one sheet. */
+.sheet--away { --_y: 100%; --_cover: var(--_box); visibility: hidden; transition: translate var(--motion-sheet) ease, visibility 0s linear var(--motion-sheet); }
 .sheet.is-dragging { transition: none; } /* follows the finger; the snap gets the ease back */
 
 /* the body — everything under the head, the one thing in a sheet that
@@ -113,6 +126,31 @@
      cut is a share of the SHEET's height, not of the body's. */
   scroll-padding-bottom: var(--_cover);
 }
+/* ---- the sheet's foot: the button that FINISHES the sheet, on the sheet (Lh, 2026-09-20) ----
+   A screen with a sheet has no bar in front of it: the button that completes what the sheet asks — the
+   page's conclusion — is a .card__foot, the sheet's last child, on the sheet's own material. The sheet is
+   full height at every state, so its real bottom edge is under the cut unless it stands at full. So the
+   foot is a layer as tall as the sheet, its buttons at its bottom, slid UP by the very share the sheet
+   slid down (--_y, + the drag): the two cancel, and the buttons stand on the box's bottom edge at half,
+   3q and full alike while the sheet slides behind them. A percentage of the same height on both — not a
+   length — so a box that resizes (the keyboard) moves them as one, with nothing to catch up. The layer
+   takes no taps, its buttons do; the strip behind them is the sheet's ground, --_foot tall, and the body
+   stops that far above the sheet's edge. At peek there is only the handle and the title: the foot is gone.
+   One row, ≤ 2 buttons. <div class="card__foot"><button class="btn btn--primary btn--block">…</button></div> */
+.sheet { --_foot: calc(var(--card-gap) + var(--btn-h) + var(--card-pad)); }
+.sheet > .card__foot {
+  position: absolute; inset: calc(-1 * var(--border-w)) 0 0; z-index: 1; /* the sheet's border box: the same height the sheet's own % reads */
+  align-items: end;
+  padding: 0 var(--card-pad) var(--card-pad);
+  background: linear-gradient(var(--card-bg), var(--card-bg)) bottom / 100% var(--_foot) no-repeat;
+  pointer-events: none;
+  translate: 0 calc(-1 * var(--_y) - var(--_drag, 0rem));
+  transition: translate var(--motion-sheet) ease, opacity var(--motion-sheet) ease, visibility 0s;
+}
+.sheet > .card__foot > * { pointer-events: auto; }
+.sheet:has(> .card__foot) > .sheet__body { margin-bottom: calc(var(--_foot) - var(--card-pad)); } /* the body stops above the strip (the card's own padding is the rest) */
+.sheet.is-dragging > .card__foot { transition: none; }
+:is(.sheet--peek, .sheet--away) > .card__foot { opacity: 0; visibility: hidden; transition: translate var(--motion-sheet) ease, opacity var(--motion-sheet) ease, visibility 0s linear var(--motion-sheet); }
 .sheet__body > * { min-width: 0; } /* as .card > *: children shrink to the track, never widen it */
 .sheet__body:last-child { margin-bottom: calc(-1 * var(--card-pad)); padding-bottom: var(--card-pad); }
 

package/css/step.css

@@ -1,14 +1,16 @@
 /* ============================================================
    cardds/step.css — .step: one screen, one task.
    What the member reads (words on the base — not a card, Lh 2026-09-16), what the member does when the
-   step asks for it (a sheet, sheet.css), and the screen's one
-   move (.action-bar, actions.css) OUTSIDE the step, below it.
+   step asks for it (a sheet, sheet.css). The move: a page of words has
+   an .action-bar (actions.css) OUTSIDE the step, below it — the base's;
+   a step with a sheet has none: the sheet's own .card__foot finishes it
+   (see "LAYERS" below).
 
    <section class="step">
      <section class="base-content">…the words…</section>               ← first
-     <article class="card sheet sheet--half">…the controls…</article>  ← last, optional
+     <article class="card sheet sheet--half">…the controls… <div class="card__foot">…</div></article>  ← last, optional
    </section>
-   <div class="action-bar">…</div>
+   <div class="action-bar">…</div>   ← only when there is no sheet
 
    The step is the box the sheet slides in. It fills the screen
    column between the top bar's reserve (.screen already pads for
@@ -58,6 +60,10 @@
    bar. Any parent that hosts the bar counts — <body>, an app shell, a demo
    frame — the bar is fixed to the viewport wherever it sits. */
 :has(> .action-bar) .step { margin-bottom: calc(var(--bar-reserve) + var(--kb, 0rem)); }
+/* LAYERS (Lh, 2026-09-20): the base, then the sheet over it, then the top bar. A bar is the BASE's — the
+   move of a page of words — so a step with a sheet has NO bar: the sheet finishes on its own .card__foot
+   (sheet.css), and a form lives whole in ONE sheet, never item by item on the base. Should a bar be written
+   beside a sheet anyway it stands down (actions.css + cardds.js) — a net for a mistake, not a layout. */
 
 /* the reading block: a .base-content (base.css) — the same words-on-the-base
    block as anywhere else (it was .step__card, and a .card before 2026-09-16;
@@ -67,14 +73,23 @@
    gets the flex rule: it hugs its content, and when the column runs out (a
    short phone, large text) it shrinks and scrolls inside itself instead of
    pushing the bar or the sheet */
-.step > .base-content {
+.step > .base-content, .step > .pages > .base-content {
   --card-pad: 0rem;              /* published for .bleed: nothing to cancel */
   --card-gap: var(--sp-4);
   gap: var(--card-gap);
   padding-block: 0;              /* --_lead carries the top; the bar's room is the step's */
   align-content: start;
   color: var(--on-surface);
+}
+/* the reading block is the .base-content — or the .pages that holds several of them, a walk of words
+   (card.css). --sheet-room: the strip a CALLED sheet keeps at peek (sheet.css, "called sheets"), published
+   on the step by cardds.js while one is on the screen, so the buttons under it can scroll clear of it;
+   nothing without one. */
+.step > :is(.base-content, .pages) {
+  padding-bottom: var(--sheet-room, 0rem);
   flex: 0 1 auto;
+}
+.step > :is(.base-content, .pages) {
   min-height: 0;
   margin: var(--_lead, 0) var(--screen-pad) 0; /* the screen's gap, moved in here from above the step; the inset, taken back from the bleed */
   overflow-y: auto;