@usableapp/cardds 0.7.103 → 0.7.104

package/dist/sheets/stackCard.js

@@ -71,6 +71,67 @@ const armSwallow = (swallow) => {
     swallow.current = true;
     requestAnimationFrame(() => { swallow.current = false; });
 };
+/* the finger let go short of the commit (or was cancelled): the card eases back from the frame just read */
+const releaseCard = (card, live, prop) => {
+    live.current = null;
+    card.classList.remove('is-dragging');
+    readFrame(card);
+    card.style.removeProperty(prop);
+};
+/* a finger on a head, the open sheet's (down, `--_pull`, folds it) or a peeked one's (up, `--_lift`, opens it): the card follows it up to
+   `cap`; let go past the commit, `settle` asks the app, and a card the app left where it was (`unmoved`) eases back */
+function pullHead(e, { card, head, doc, held, live, swallow, way, prop, cap, settle, unmoved }) {
+    const slop = pxFromRem(SLOP_REM);
+    const commit = pxFromRem(COMMIT_REM);
+    const pull = { pointerId: e.pointerId, startY: e.clientY, last: 0, cap: Math.max(cap, commit), commit, slop, moved: false };
+    held.current = pull;
+    const onMove = (ev) => {
+        if (ev.pointerId !== pull.pointerId || held.current !== pull)
+            return;
+        const d = along(way, pull.startY, ev.clientY);
+        pull.last = d;
+        if (d < pull.slop)
+            return;
+        pull.moved = true;
+        ev.preventDefault();
+        try {
+            if (!head.hasPointerCapture(ev.pointerId))
+                head.setPointerCapture(ev.pointerId);
+        }
+        catch { /* the pointer is already gone */ }
+        live.current = { prop, px: `${Math.min(d, pull.cap)}px` };
+        card.classList.add('is-dragging');
+        card.style.setProperty(prop, live.current.px);
+    };
+    const onUp = (ev) => {
+        if (ev.pointerId !== pull.pointerId || held.current !== pull)
+            return;
+        const d = Math.max(pull.last, along(way, pull.startY, ev.clientY));
+        const moved = pull.moved || d >= pull.slop;
+        held.current = null;
+        doc.stop();
+        if (moved && d >= pull.commit) {
+            card.classList.remove('is-dragging');
+            readFrame(card);
+            live.current = null;
+            flushSync(settle);
+            if (card.isConnected && unmoved() && card.style.getPropertyValue(prop))
+                releaseCard(card, live, prop);
+        }
+        else
+            releaseCard(card, live, prop);
+        if (moved)
+            armSwallow(swallow);
+    };
+    const onCancel = (ev) => {
+        if (ev.pointerId !== pull.pointerId || held.current !== pull)
+            return;
+        held.current = null;
+        doc.stop();
+        releaseCard(card, live, prop);
+    };
+    doc.listen(onMove, onUp, onCancel);
+}
 /**
  * The card's own pull, refresh and focus. Listeners sit on this card's head and body.
  * `--_pull` / `--_lift` are written while a finger is down, the same way a single Sheet writes `--_drag`.
@@ -113,68 +174,14 @@ export function useStackCard(ref, place, swallow) {
         const scroller = card.querySelector(':scope > .sheet__body') ?? card;
         const doc = docPointer();
         const primary = (e) => e.isPrimary && e.button === 0;
-        const release = (prop) => {
-            live.current = null;
-            card.classList.remove('is-dragging');
-            readFrame(card);
-            card.style.removeProperty(prop);
-        };
         const onHeadDown = (e) => {
             e.stopPropagation();
             if (!head || !stack || !primary(e) || headPull.current || bodyPull.current)
                 return;
             if (!pullsHead(e.target, head))
                 return;
-            const slop = pxFromRem(SLOP_REM);
-            const commit = pxFromRem(COMMIT_REM);
-            const pull = { pointerId: e.pointerId, startY: e.clientY, last: 0, cap: Math.max(restPullPx(card, stack), commit), commit, slop, moved: false };
-            headPull.current = pull;
-            const onMove = (ev) => {
-                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                    return;
-                const dy = along('down', pull.startY, ev.clientY);
-                pull.last = dy;
-                if (dy < pull.slop)
-                    return;
-                pull.moved = true;
-                ev.preventDefault();
-                try {
-                    if (head && !head.hasPointerCapture(ev.pointerId))
-                        head.setPointerCapture(ev.pointerId);
-                }
-                catch { /* the pointer is already gone */ }
-                live.current = { prop: '--_pull', px: `${Math.min(dy, pull.cap)}px` };
-                card.classList.add('is-dragging');
-                card.style.setProperty('--_pull', live.current.px);
-            };
-            const onUp = (ev) => {
-                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                    return;
-                const dy = Math.max(pull.last, along('down', pull.startY, ev.clientY));
-                const moved = pull.moved || dy >= pull.slop;
-                headPull.current = null;
-                doc.stop();
-                if (moved && dy >= pull.commit) {
-                    card.classList.remove('is-dragging');
-                    readFrame(card);
-                    live.current = null;
-                    flushSync(() => placeRef.current?.onClose());
-                    if (card.isConnected && card.classList.contains('is-open') && card.style.getPropertyValue('--_pull'))
-                        release('--_pull');
-                }
-                else
-                    release('--_pull');
-                if (moved)
-                    armSwallow(swallow);
-            };
-            const onCancel = (ev) => {
-                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                    return;
-                headPull.current = null;
-                doc.stop();
-                release('--_pull');
-            };
-            doc.listen(onMove, onUp, onCancel);
+            pullHead(e, { card, head, doc, held: headPull, live, swallow, way: 'down', prop: '--_pull', cap: restPullPx(card, stack),
+                settle: () => placeRef.current?.onClose(), unmoved: () => card.classList.contains('is-open') });
         };
         const onBodyDown = (e) => {
             const ask = placeRef.current;
@@ -279,7 +286,7 @@ export function useStackCard(ref, place, swallow) {
             scroller.style.removeProperty('--_refresh');
             setPulling(false);
             if (live.current?.prop === '--_pull')
-                release('--_pull');
+                releaseCard(card, live, '--_pull');
             head?.removeEventListener('pointerdown', onHeadDown);
             scroller.removeEventListener('pointerdown', onBodyDown);
         };
@@ -295,12 +302,6 @@ export function useStackCard(ref, place, swallow) {
         if (!head || !stack)
             return;
         const doc = docPointer();
-        const release = () => {
-            live.current = null;
-            card.classList.remove('is-dragging');
-            readFrame(card);
-            card.style.removeProperty('--_lift');
-        };
         const onDown = (e) => {
             if (!e.isPrimary || e.button !== 0 || headPull.current)
                 return;
@@ -329,64 +330,15 @@ export function useStackCard(ref, place, swallow) {
                 return;
             }
             e.stopPropagation();
-            const slop = pxFromRem(SLOP_REM);
-            const commit = pxFromRem(COMMIT_REM);
-            const travel = card.getBoundingClientRect().top - stack.getBoundingClientRect().top;
-            const pull = { pointerId: e.pointerId, startY: e.clientY, last: 0, cap: Math.max(travel, commit), commit, slop, moved: false };
-            headPull.current = pull;
-            const onMove = (ev) => {
-                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                    return;
-                const upPx = along('up', pull.startY, ev.clientY);
-                pull.last = upPx;
-                if (upPx < pull.slop)
-                    return;
-                pull.moved = true;
-                ev.preventDefault();
-                try {
-                    if (!head.hasPointerCapture(ev.pointerId))
-                        head.setPointerCapture(ev.pointerId);
-                }
-                catch { /* the pointer is already gone */ }
-                live.current = { prop: '--_lift', px: `${Math.min(upPx, pull.cap)}px` };
-                card.classList.add('is-dragging');
-                card.style.setProperty('--_lift', live.current.px);
-            };
-            const onUp = (ev) => {
-                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                    return;
-                const upPx = Math.max(pull.last, along('up', pull.startY, ev.clientY));
-                const moved = pull.moved || upPx >= pull.slop;
-                headPull.current = null;
-                doc.stop();
-                if (moved && upPx >= pull.commit) {
-                    card.classList.remove('is-dragging');
-                    readFrame(card);
-                    live.current = null;
-                    flushSync(() => placeRef.current?.onOpen());
-                    if (card.isConnected && !card.classList.contains('is-open') && card.style.getPropertyValue('--_lift'))
-                        release();
-                }
-                else
-                    release();
-                if (moved)
-                    armSwallow(swallow);
-            };
-            const onCancel = (ev) => {
-                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                    return;
-                headPull.current = null;
-                doc.stop();
-                release();
-            };
-            doc.listen(onMove, onUp, onCancel);
+            pullHead(e, { card, head, doc, held: headPull, live, swallow, way: 'up', prop: '--_lift', cap: card.getBoundingClientRect().top - stack.getBoundingClientRect().top,
+                settle: () => placeRef.current?.onOpen(), unmoved: () => !card.classList.contains('is-open') });
         };
         head.addEventListener('pointerdown', onDown);
         return () => {
             doc.stop();
             headPull.current = null;
             if (live.current?.prop === '--_lift')
-                release();
+                releaseCard(card, live, '--_lift');
             head.removeEventListener('pointerdown', onDown);
         };
     }, [place?.open, place?.before, place?.after, ref, swallow]);

package/dist/state.d.ts

@@ -25,6 +25,27 @@ export declare function watchSize(targets: Array<Element | null | undefined>, fn
 export declare const warnOnce: (key: string, text: string) => void;
 /** the member asked for less motion (false where there is no window, e.g. a server render) */
 export declare const reducedMotion: () => boolean;
+/** `--motion-sheet` in ms, read from `cs` (the document's by default); 350 where it reads as none */
+export declare const sheetMs: (cs?: CSSStyleDeclaration) => number;
+/** cancel the moves tagged `id` on `els`, so what is read next is where they rest */
+export declare const stopMoves: (els: HTMLElement[], id: string) => void;
+/** a reordered element glides from `dy` px off to its place, at the `--motion-sheet` and `--ease-settle` of its list (`cs`); tagged `id` for stopMoves */
+export declare function glide(el: HTMLElement, dy: number, cs: CSSStyleDeclaration, id: string): Animation;
+/** how far a press travelled along `axis` from `from` to `to` — 0 when it is no swipe: shorter than `min` px, or not `ratio` times its travel across */
+export declare function swipeOf(from: {
+    x: number;
+    y: number;
+}, to: {
+    clientX: number;
+    clientY: number;
+}, axis: 'x' | 'y', min: number, ratio?: number): number;
+/** a rail that comes to rest: `settled()` on each scroll, and `then` runs `ms` after the last one; `cancel` drops the wait, and so does unmounting */
+export declare function useSettled(then: () => void, ms?: number): {
+    settled: () => void;
+    cancel: () => void;
+};
+/** the bottom of what the member sees — the keyboard's top while it is up (Infinity where the browser has no visualViewport) */
+export declare const visibleBottom: () => number;
 /** give `box` the cursor once it has settled: after its own `translate` transition (600ms at most), or after `wait` ms. It lands on the field
  *  marked `data-autofocus`, else the first field inside `scope` (a selector under `box`; default: all of it), else `fallback`. A field in
  *  `box` that already has the cursor keeps it. Inside `[data-standby="off"]` no field is looked for: `fallback` only. Nothing moves the page (`preventScroll`). Returns the cancel — `true` when it had already

package/dist/state.js

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 export function useControlled(value, initial, onChange) {
     const [own, setOwn] = useState(initial);
     const shown = value !== undefined ? value : own;
@@ -63,6 +63,33 @@ export const warnOnce = (key, text) => { if (!warned.has(key)) {
 } };
 /** the member asked for less motion (false where there is no window, e.g. a server render) */
 export const reducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+/** `--motion-sheet` in ms, read from `cs` (the document's by default); 350 where it reads as none */
+export const sheetMs = (cs = getComputedStyle(document.documentElement)) => (parseFloat(cs.getPropertyValue('--motion-sheet')) || 0.35) * 1000;
+/** cancel the moves tagged `id` on `els`, so what is read next is where they rest */
+export const stopMoves = (els, id) => els.forEach((el) => el.getAnimations().forEach((a) => { if (a.id === id)
+    a.cancel(); }));
+/** a reordered element glides from `dy` px off to its place, at the `--motion-sheet` and `--ease-settle` of its list (`cs`); tagged `id` for stopMoves */
+export function glide(el, dy, cs, id) {
+    const a = el.animate([{ translate: `0 ${dy}px` }, { translate: '0 0' }], { duration: sheetMs(cs), easing: cs.getPropertyValue('--ease-settle').trim() || 'ease' });
+    a.id = id;
+    return a;
+}
+/** how far a press travelled along `axis` from `from` to `to` — 0 when it is no swipe: shorter than `min` px, or not `ratio` times its travel across */
+export function swipeOf(from, to, axis, min, ratio = 0) {
+    const dx = to.clientX - from.x, dy = to.clientY - from.y;
+    const [along, across] = axis === 'x' ? [dx, dy] : [dy, dx];
+    return Math.abs(along) < min || Math.abs(along) < ratio * Math.abs(across) ? 0 : along;
+}
+/** a rail that comes to rest: `settled()` on each scroll, and `then` runs `ms` after the last one; `cancel` drops the wait, and so does unmounting */
+export function useSettled(then, ms = 120) {
+    const wait = useRef(null);
+    const cancel = () => { if (wait.current)
+        clearTimeout(wait.current); };
+    useEffect(() => cancel, []);
+    return { settled: () => { cancel(); wait.current = setTimeout(then, ms); }, cancel };
+}
+/** the bottom of what the member sees — the keyboard's top while it is up (Infinity where the browser has no visualViewport) */
+export const visibleBottom = () => { const vv = window.visualViewport; return vv ? vv.offsetTop + vv.height : Infinity; };
 /* THE RULE (Lh 2026-09-29): a part of the screen that has just become ACTIVE — a sheet come up, a step opened, a stack sheet opened, a
    modal asking — has its field waiting with the cursor. ONE mechanic for every such part; the component only says WHEN it became active.
    THE SWITCH (Lh 2026-10-06): under `data-standby="off"` (on any box around the part) no field is given the cursor — the part's

package/dist/sticky/Sticky.js

@@ -2,9 +2,9 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
 import { pressable } from '../pressable.js';
-import { setRefs, watchSize } from '../state.js';
+import { setRefs } from '../state.js';
 import { word } from '../words.js';
-import { holdRoom } from '../room.js';
+import { holdRoomWhile } from '../room.js';
 import { fitSticky } from './fit.js';
 /**
  * Sticky — a paper note: a flat pastel SQUARE of one size (168, the knob `--sticky-size`), square corners, a soft shadow under it.
@@ -31,11 +31,7 @@ export function Sticky({ tone = 'custard', flat, unreadLabel, head, date, tilt,
         if (!note || !paper)
             return;
         const measure = () => setSmall(fitSticky(note) !== 'full');
-        room.current = holdRoom(paper, fieldOf, () => fitSticky(note) === 'over', measure);
-        const body = paper.querySelector('.sticky__body');
-        const stop = watchSize([body], measure);
-        document.fonts?.ready.then(measure);
-        return () => { room.current?.stop(); room.current = null; stop(); };
+        return holdRoomWhile(room, [paper.querySelector('.sticky__body')], measure, paper, fieldOf, () => fitSticky(note) === 'over', measure);
     }, []);
     const notched = corner != null;
     const { tap, Box, boxProps } = pressable(notched ? undefined : onClick, 'div', rest);

package/dist/templates/Home.d.ts

@@ -9,7 +9,7 @@ export interface HomeSheet {
     icon?: ReactNode;
     /** the tone slot — see `Tone` (default: 2, 3, 1, 2, 3 by place). The head shows it */
     tone?: Tone;
-    /** white content, the head keeps `tone`. The same look as `Sheet paper` */
+    /** content on the theme's paper (`--action-bg`, the ground of its fields), the head keeps `tone`. The same look as `Sheet paper` */
     paper?: boolean;
     /** the sheet's pages as icon tabs in its head (a count shows as a small circle over the icon) — see `StackSheet` */
     tabs?: StackSheetTab[];

package/dist/templates/Splash.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
-import { reducedMotion, useLatest } from '../state.js';
+import { reducedMotion, sheetMs, useLatest } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { cx } from '../cx.js';
 /**
@@ -24,7 +24,7 @@ export function Splash({ mark, text, done, min = 0, onLeft, className, ...rest }
         if (!leaving)
             return;
         const still = reducedMotion();
-        const ms = still ? 0 : parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--motion-sheet')) * 1000 || 350;
+        const ms = still ? 0 : sheetMs();
         const t = setTimeout(() => left.current?.(), ms);
         return () => clearTimeout(t);
     }, [leaving]);

package/dist/templates/Walkthrough.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useLayoutEffect, useRef } from 'react';
-import { useControlled } from '../state.js';
+import { swipeOf, useControlled } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { Step } from '../sheets/Step.js';
 import { Page } from '../scaffold/Page.js';
@@ -40,10 +40,9 @@ export function Walkthrough({ pages, at: atProp, defaultAt = 0, onAtChange, cta,
             start.current = null;
             if (!s0)
                 return;
-            const dx = e.clientX - s0.x, dy = e.clientY - s0.y;
-            if (Math.abs(dx) < 48 || Math.abs(dx) < 1.5 * Math.abs(dy))
-                return;
-            go(dx < 0 ? at + 1 : at - 1);
+            const dx = swipeOf(s0, e, 'x', 48, 1.5);
+            if (dx)
+                go(dx < 0 ? at + 1 : at - 1);
         },
         onPointerCancel: () => { start.current = null; },
     };

package/docs/reference.md

@@ -341,9 +341,9 @@ whose markup has rules, because the sheet's box is the step itself:
   padding, the same distance from the edge, so the title stays put. `refreshing`
   (off unless the app sets it) changes the mark's colour while the app reloads
   what the sheet shows, as a stack sheet's does; the sheet does not fetch. `paper` makes
-  the content white while the head keeps the sheet's colour (`tone`, as a card).
+  the content the theme's paper (`--action-bg`) while the head keeps the sheet's colour (`tone`, as a card).
   The same prop on a `StackSheet`, or on a `Card` in a stack: the head keeps the
-  tone, the body and the foot are white, and the gap under the head stays the tone.
+  tone, the body and the foot are the paper, and the gap under the head stays the tone.
   While that sheet is closed, the corners the next sheet does not cover show the
   card's colour. That colour fades in as the sheet returns, and is done when it stops.
   A sheet with no head (the dim page sheet) is a body alone.
@@ -693,8 +693,8 @@ it up. cardds draws the paper; the pictures, their words and which stamp a membe
   narrower, so at the standard size only `name` shows, and it is larger.
 - **`StampPlace`** — an empty place the size of a stamp, its edge a ring of round dots: a word inside, `onClick` for "make
   yours", `faint` for a gap nobody is asked to fill. The edge is a drawn stroke, so the dots are yours: `--stamp-place-dot`
-  is how wide each is (default `--rule-w`, 2px), `--stamp-place-gap` the distance from one dot's centre to the next
-  (default 6px), and a `--stamp-place-dash` above 0 stretches each dot into a round-ended dash. Its corner is
+  is how wide each is (default `--rule-w`), `--stamp-place-gap` the distance from one dot's centre to the next
+  (default three `--sp-0`), and a `--stamp-place-dash` above 0 stretches each dot into a round-ended dash. Its corner is
   `--stamp-place-radius`. The dots' outer edge is the box's edge whatever their width.
 - **`StampBook`** + **`StampCell`** — the album page: cells three across on an album ground, a `label` under each stamp,
   the free places drawn up to `places`. A cell with `onClick` is a button; `on` marks it pressed. Each stamp stands in
@@ -719,8 +719,8 @@ it up. cardds draws the paper; the pictures, their words and which stamp a membe
   it lies on. With `onRemove` the stamp can be taken off: when a drag ends or an arrow key moves it, a cross stands on
   its top right corner for `removeFor` ms (default 3000). A press on the cross, or Delete / Backspace on the focused
   stamp, asks, and the app takes the `StampOn` away. A stamp with `onRemove` and no `onAtChange` shows the cross on a
-  press. The cross is a 24 disc (`--stamp-on-remove-size`, `--stamp-on-remove-bg` #141414, `--stamp-on-remove-ink`
-  #ffffff) in a 44 target, centred on the corner and upright whatever the stamp's `turn`. Its name is cardds's word
+  press. The cross is a 24 disc (`--stamp-on-remove-size`, `--stamp-on-remove-bg` `--ink-onlight`, `--stamp-on-remove-ink`
+  `--ink-ondark`) in a 44 target, centred on the corner and upright whatever the stamp's `turn`. Its name is cardds's word
   ("Remove" / "เอาออก"), or `removeLabel`. A press or a drag on a removable stamp never reaches what lies under it.
   A stamp that is still arriving cannot be taken off yet: its cross waits until it has landed.
 
@@ -741,7 +741,7 @@ struck over its edge) proves the trip. Three components, one for each thing a me
 the older `Postcard` (a member's cover card that turns over) is another component and shares nothing with these.
 
 - **`PostLetter`**: reading one that arrived. Two upright 2:3 sheets, one in front. The picture side is `picture` (the
-  app's img or svg) in a white margin with `caption` under it; the written side is the address (`kicker`, `to` lines) over
+  app's img or svg) in a margin of its paper (`--post-paper-bg`) with `caption` under it; the written side is the address (`kicker`, `to` lines) over
   the message (`children`, set large, `sign` at its end), with `stamp` and `postmark` on the corner. The tab over the
   card, or a tap on the card, turns it: the sheet in front swings to its edge and the other swings in. `face` +
   `onFaceChange`, or `defaultFace`. `voice` is a voice note's time as the app words it; with it the picture side has a
@@ -910,6 +910,34 @@ question and hunts for its answer. Rules 11–13 serve that:
     the card's ground, a note is a `Banner` (a light band, a rule above and
     below, edge to edge), a count is words (`Text caption muted`), never a
     chip. A chip or tile that looks pressable and is not lies.
+15. **A component adjusts another only through its knobs.** A component that
+    holds another (a sheet holding a card, a stack holding a sheet) sets the
+    child's knobs (`.sheet { --card-pad: … }`), never the child's own
+    property (`.sheet .card__head { color: … }`). The child's file is the one
+    place its look is written, so what a story shows is what a project gets.
+    Missing the knob? Add it in the child's file. No `!important` either, but
+    `[hidden]`'s. A component belongs to the file that writes its bare class
+    (`.card` → `css/card.css`). A knob the holder sets is still the child's
+    knob: it is read, with its default, in the child's file and never
+    declared there. Where a child SITS in a holder that places it (its
+    position, inset, grid cell, layer, margins, how it scrolls or moves in
+    each of the holder's states) is not a look the holder retunes: the
+    child's own file writes it, as `.screen--fill > .action-bar { … }` in
+    `css/actions.css` and the stack's sheets in `css/card.css`. A part or a
+    variant of a block (`.card--cover`, `.screen__centre`) is written in the
+    block's file too. One kind of rule names many components and is no
+    override: a **trait**, one behaviour every control shares, kept as one
+    list so a new control joins it there. There are five, each in its own
+    file and writing only its own properties: press (cursor, touch-action,
+    the transition, scale, opacity, filter) and the focus ring (outline) in
+    `css/actions.css`; the button reset (border, background, font, colour,
+    padding), the hidden scrollbar and user-select in `css/base.css`. A trait
+    is a zero-specificity `:where()` list (the user-select list is a plain
+    list of single selectors), so a component's own rule always wins.
+    `tests/overrides.spec.js` fails on any override; `tests/overrides.json`,
+    which held the 184 there were on 2026-10-20, is empty and stays so.
+    One rule that can do neither is named, with why, in `KEPT`
+    (`tests/helpers.js`).
 
 ## A project's theme
 
@@ -1093,8 +1121,11 @@ Every length token resolves to rem — a multiplier × one of four rem bases
 `--r-base` × 2, `--fs-h1` = `--fs-base` × 1.2; see "A project's theme") — so the
 whole system scales with the root font size. `base.css` keeps it at `100%` (the browser's setting, 16px by
 default) and steps narrow phones (≤360px) to `93.75%`, which keeps the
-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.
+column, its 48px taps and its type in proportion on 320–360 screens. No
+length is written in px, the edges included (Lh 2026-10-20: "units are always rem"): `--border-w`,
+`--hairline-w`, `--rule-w`, the focus ring and one device pixel, `--px`, are rem. Two px stay, both the
+platform's: the initial value of a registered length (`@property`), which may not be relative, and the
+lengths a script measures off the page (`--kb`, a sheet's peek, a pulled sheet).
 An app with its own text-size setting calls `setTextScale(percent)`, which writes
 `--fs-base` on `<html>` from the theme's base (100% = the theme's; 160% = 2.2rem by default): the type and its holders (the count
 badge, the inline icon) grow, the controls grow half as much (`--tap-base`), spacing and radii keep their size.
@@ -1109,6 +1140,37 @@ so no component ever writes `px` to consume it (`.action-bar` rides up by it,
 `.step` grows its room by it). The narrow-phone step is an `em` breakpoint,
 so it follows the text size too: at 131% a 390px phone counts as narrow.
 
+## A component brings no value of its own
+
+The gallery is a catalog of components, not of designs: what a story shows must be what a project gets when
+it imports the piece (Lh 2026-10-20: "a component that slips out of the tokens or the theme is a problem,
+because that is how a hard-coded look gets made that cannot be taken out and used"). So a component's css
+reads every value from a token in `css/tokens.css` (or a palette, a finish, a project's theme), and writes none:
+
+- **colour**: the roles, the inks of each side, the signals, and the nine pastels of a note or a stamp
+  (`--pastel-*`, `--stamp-paper`). A paper sheet's content is the theme's paper, `--action-bg`, the ground of
+  its fields; never a fixed white. A shadow is mixed from the onlight ink (`--shadow-paper`, `--shadow-lift`,
+  `--shadow-fold`), never from black.
+- **length**: a multiple of a base, in rem (above).
+- **time**: `--motion-*`. **easing**: `--ease`, `--ease-in`, `--ease-out`, `--ease-in-out`, `--ease-linear`,
+  `--ease-settle` for a row or card that lands where it moved, and `--ease-step` for on or off with nothing between (a caret).
+- **angle**: a multiple of `--tilt-base` (1deg): a note, a stamp, a letter, a card sent away. A theme that wants
+  everything straight sets it to 0deg. A quarter or half turn is an orientation, not a tilt (an arrow, a face turned over).
+- **layer**: `--z-under-2` … `--z-over-3`, the order of things inside one piece; `--z-pile`, a sticky pile's top note.
+- **scale**: `--press-scale` under the finger, `--scale-lift` (a stamp held), `--scale-pick` (a mood's dot picked), `--scale-arrive` (where a stamp's remove button grows from).
+- **fade**: `--off` (a disabled control) and `--fade-*`, one name per use.
+- **type**: the eight kinds (display, h1, h2, title, body, label, caption, stat) each have `--face-<kind>`, `--fw-<kind>`,
+  `--fs-<kind>`, `--lh-<kind>` and `--track-<kind>`, and `--type-<kind>` is made of them. A piece set on a size outside the
+  kinds composes its `font:` from the scales: `--fs-*`, weight `--fw-regular` … `--fw-black`, leading `--lh-mark` … `--lh-ruled`.
+  Gallery `Text · Kinds` shows them resolved.
+
+A knob's default is one of these too, so a knob read from nowhere still shows the theme. `npm run check` reads
+every declaration of every component file and every literal of an inline `style` in `src/` and `.design-sync/previews/`
+(`lint/values.mjs`, before the tests run) and fails on a value written in place, naming the file, the line, the kind and
+the value: a knob's fallback (`z-index: var(--x, 5)`), a number inside `calc()` in a leading or a tracking, `scale` and
+`scale()`, `filter: opacity()`, a fade in %, a unit in capitals and every CSS colour name included; a number on a length
+in a `style` object is px. A sign or an identity (`* -1`, `0`, `1`, `100%`) is not a value. `tests/tokens.spec.js` holds it at none.
+
 ## Icons & touch targets
 
 Icons come from `icons.svg` (Lucide, ISC — monochrome stroke, currentColor):

package/lib/catalog.mjs

@@ -83,10 +83,20 @@ export function get(cat, name, { html = false, all = false } = {}) {
 }
 
 const words = (text) => text.replace(/([a-z\d])([A-Z])/g, '$1 $2').toLowerCase().match(/[\p{L}\p{M}\p{N}]+/gu) ?? [];
-const STOP = new Set(['the', 'and', 'for', 'with', 'from', 'that', 'this', 'into', 'of', 'to', 'in', 'on', 'an', 'a']);
-const tokens = (query) => [...new Set(words(String(query)).filter((t) => t.length > 1 && !STOP.has(t)))];
-const stem = (t) => (t.length > 3 && t.endsWith('s') ? t.slice(0, -1) : t);
-const hits = (text, token) => words(text).some((w) => w.startsWith(token) || w.startsWith(stem(token)));
+// the words of a request that carry no intention: "the user switches something on or off" is asked by "switches" and "off", and "on", "user", "something" matched every row that says them
+const STOP = new Set(['the', 'and', 'for', 'with', 'from', 'that', 'this', 'into', 'of', 'to', 'in', 'on', 'an', 'a', 'at', 'by', 'as', 'is', 'are', 'be', 'it', 'its', 'can', 'my', 'your', 'their', 'some', 'user', 'users', 'member', 'someone', 'something']);
+// a request says a value of the roles' closed vocabulary (docs/roles.md) in its own words: "choose" is the job pick, "date" represents time, "read" is show.
+// Such a word also matches every component whose role has the value; "or" ("a or b", "on or off") is a choice, and matches nothing but the role
+const SAYS = {
+  pick: ['choose', 'pick', 'select', 'switch', 'tick', 'or'], write: ['fill', 'type', 'write', 'enter'], show: ['read', 'see', 'show'], act: ['press', 'tap', 'send'], navigate: ['go', 'navigate'],
+  number: ['number', 'count', 'amount', 'total'], time: ['date', 'day', 'time', 'when'], place: ['place', 'where'], person: ['person', 'who'], glance: ['glance'],
+};
+const ROLE_ONLY = new Set(['or']);
+const tokens = (query) => [...new Set(words(String(query)).filter((t) => (t.length > 1 || ROLE_ONLY.has(t)) && !STOP.has(t)))];
+const stem = (t) => (/(?:ch|sh|x|ss)es$/.test(t) ? t.slice(0, -2) : t.length > 3 && t.endsWith('s') ? t.slice(0, -1) : t);
+const hits = (text, token) => !ROLE_ONLY.has(token) && words(text).some((w) => w.startsWith(token) || w.startsWith(stem(token)));
+/** the role's values (what it represents, its density, its job) said by the token, as the value or in a request's words for it */
+const plays = (role, token) => [...role.represents, ...role.density, ...role.job].some((v) => v === stem(token) || SAYS[v]?.includes(stem(token)));
 const isName = (name, token) => name.toLowerCase() === token || name.toLowerCase() === stem(token);
 
 const TOP = 8; // answers per kind; the components that match every axis are never cut
@@ -135,13 +145,18 @@ export function find(cat, query, axes = {}) {
   const roles = new Map(cat.components.map((c) => [c.name, roleOf(c)]));
   const toks = tokens(query);
   const axisWords = [...(asked.want.represents ?? []), ...(asked.want.interact || [])]; // the axis values as words: a screen's own description may say them
-  const rank = (items, fields, level, said = () => 0) => { // a field is [text, weight, match = hits]
+  // every three words of the request in a row, function words kept: a note that says "a or b" or "at a glance" as asked is the piece the request describes
+  const all = words(String(query));
+  const phrases = all.slice(2).map((w, i) => ` ${all[i]} ${all[i + 1]} ${w} `);
+  const rank = (items, fields, level, said = () => 0, saysIt = () => '') => { // a field is [text, weight, match = hits]; saysIt is the text whose phrases count
     const scored = items.map((item) => {
       let matched = 0, score = 0;
       for (const t of toks) {
         const w = fields(item).filter(([text, , match = hits]) => match(text, t)).reduce((sum, [, weight]) => sum + weight, 0);
         if (w) { matched++; score += w; }
       }
+      const own = ` ${words(saysIt(item)).join(' ')} `;
+      score += 3 * phrases.filter((p) => own.includes(p)).length;
       return { item, matched, score, level: active ? level(item) : 0, said: active ? said(item) : 0 };
     });
     const byWords = (a, b) => b.matched - a.matched || b.score - a.score;
@@ -159,8 +174,9 @@ export function find(cat, query, axes = {}) {
   const said = (s) => axisWords.filter((v) => hits(s.description, v)).length;
   const [screenAxis, screenRest] = tier(rank(screens, (s) => [[s.id, 5], [s.description, 3], [s.uses.join(' '), 1]], level, said), TOP);
   // a component is found by its name (the name that IS the word counts as much again as one that contains it: "card" is Card before FeedCard, whatever
-  // their other words say), its description, its role's note (what it is FOR, in the words of a request: "a setting turned on or off") and what it stands in for, then its prop names
-  const components = rank(cat.components, (c) => [[c.name, 6, isName], [c.name, 6], [c.description, 2], [c.role?.note ?? '', 2], [(c.role?.standsInFor ?? []).map((s) => `${s.name} ${s.condition}`).join(' '), 1], [c.props.map((p) => p.name).join(' '), 1]], (c) => Number(matches(roles.get(c.name), asked.want)));
+  // their other words say), its description, its role's note (what it is FOR, in the words of a request: "a setting turned on or off"), the values of its role
+  // a word says ("choose" → pick, "number"), what it stands in for, then its prop names
+  const components = rank(cat.components, (c) => [[c.name, 6, isName], [c.name, 6], [c.description, 2], [c.role?.note ?? '', 2], ...(c.role ? [[c.role, 2, plays]] : []), [(c.role?.standsInFor ?? []).map((s) => `${s.name} ${s.condition}`).join(' '), 1], [c.props.map((p) => p.name).join(' '), 1]], (c) => Number(matches(roles.get(c.name), asked.want)), undefined, (c) => `${c.description} ${c.role?.note ?? ''}`);
   const [componentAxis, componentRest] = tier(components, Math.max(TOP, components.axis.length));
   // a screen drawn comes before the components when it answers the words as well as the best component does; one that answers FEWER of them
   // comes after (a question by intention, "a setting turned on or off", is answered by Toggle, not by eight screens that say "off" or "or")

package/lint/rules.mjs

@@ -15,7 +15,7 @@ export const CONTROL_NAMES = {
   Calendar: ['prevLabel', 'nextLabel'], SheetStep: ['skipLabel'], Sticky: ['unreadLabel'], StampOn: ['removeLabel'], Card: ['removeLabel', 'toBackLabel', 'toFrontLabel'], PostLetter: ['backLabel', 'pictureLabel', 'playLabel', 'pauseLabel', 'toLabel'],
 };
 
-const lineOf = (text, idx) => text.slice(0, idx).split('\n').length;
+export const lineOf = (text, idx) => text.slice(0, idx).split('\n').length;
 
 /** the classes a selector names; a bare state word (`is-open`) is every project's too — it only matters beside a cardds class, which is caught */
 export const selectorClasses = (selector) => [...selector.matchAll(/(?<!\\)\.(-?[a-zA-Z_][\w-]*)/g)].map((m) => m[1]).filter((c) => !/^(is|has)-/.test(c));
@@ -72,7 +72,7 @@ function elementAt(text, start) {
 }
 
 /** the expression of a `{…}` attribute value from its opening brace */
-function braceAt(text, start) {
+export function braceAt(text, start) {
   let depth = 0, quote = null;
   for (let i = start; i < text.length; i++) {
     const c = text[i];
@@ -98,7 +98,7 @@ function classWords(text, at) {
 }
 
 /** a style object's or attribute's `key: value` entries from its body (`at` = where the body starts in the text): split on the commas / semicolons that are not inside a string, bracket or call */
-function* styleEntries(body, at, sep) {
+export function* styleEntries(body, at, sep) {
   let depth = 0, quote = null, from = 0;
   for (let i = 0; i <= body.length; i++) {
     const c = body[i];
@@ -114,6 +114,9 @@ function* styleEntries(body, at, sep) {
   }
 }
 
+/** comments out, lines kept; a string is stepped over whole, so `accept="image/*"` opens no comment */
+export const blankComments = (source) => source.replace(/"[^"\n]*"|'[^'\n]*'|`[^`]*`|\/\*[\s\S]*?\*\/|(?<![:'"`\\])\/\/[^\n]*/g, (c) => /^["'`]/.test(c) ? c : c.replace(/[^\n]/g, ' '));
+
 /**
  * @param {string} text  a source file
  * @param {string} file  its name, for the findings
@@ -122,8 +125,7 @@ function* styleEntries(body, at, sep) {
 export function checkSource(source, file, { classes = carddsClasses() } = {}) {
   const findings = [];
   const lines = source.split('\n');
-  // comments out, lines kept; a string is stepped over whole, so `accept="image/*"` opens no comment
-  let text = source.replace(/"[^"\n]*"|'[^'\n]*'|`[^`]*`|\/\*[\s\S]*?\*\/|(?<![:'"`\\])\/\/[^\n]*/g, (c) => /^["'`]/.test(c) ? c : c.replace(/[^\n]/g, ' '));
+  let text = blankComments(source);
   const add = (rule, level, idx, message) => {
     const line = lineOf(text, idx);
     if (!/cardds-ignore-next-line/.test(lines[line - 2] ?? '')) findings.push({ rule, level, file, line, message }); // `// cardds-ignore-next-line` — a deliberate case (a story that shows the wrong way)