@usableapp/cardds 0.7.55 → 0.7.57

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 > For: a project that consumes `@usableapp/cardds` and its AI — what changed between versions, written as before → after, so a screen can be brought up to date without reading the source. Newest first. A consumer never edits cardds; if something here leaves you without a way to do what you did before, report the gap.
 
+## 0.7.57 — 2026-10-06
+
+### Added
+- **`paper` on a sheet in a stack.** The same prop as the single sheet, on `StackSheet`, on a `Card` in a `SheetStack`, and on each sheet of `Home`. The head keeps `tone`. The body and the foot are white. The gap under the head stays the sheet's colour. The first row sits `--sp-6` (24px at the default spacing) down into the white. A pull to refresh adds its own room on top of that inset. Pass `paper` on the sheets that should look this way. A sheet without it is unchanged.
+
+### Fixed
+- **A dark `paper` head no longer paints its light ink onto the white body.** The words on the white use the page's ink (`--color-ink`, or the wireframe dark when that is unset). A theme that already sets `--color-ink` is unchanged.
+
+## 0.7.56 — 2026-10-06
+
+### Changed
+- **A `paper` sheet keeps 24px of white above its first field.** The head stays the sheet's colour. The gap under the head stays that colour (`--card-gap`). The body's top padding is `--sp-6`, so a field no longer sits on the colour seam. A sheet without `paper` is unchanged. Nothing to change in a screen.
+
 ## 0.7.55 — 2026-10-06
 
 ### Fixed

package/README.md

@@ -275,8 +275,10 @@ whose markup has rules, because the sheet's box is the step itself:
   pinned; the body is the one thing that scrolls, to the card's own edges. The
   handle is a line, or four dots (`mark="dots"`): both sit in the card's top
   padding, the same distance from the edge, so the title stays put. `paper` makes
-  the content white while the head keeps the sheet's colour (`tone`, as a card). A
-  sheet with no head (the dim page sheet) is a body alone.
+  the content white 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.
+  A sheet with no head (the dim page sheet) is a body alone.
 - **The step follows its top bar directly, and touches it.** `full` means
   the sheet's top edge at the bar's bottom edge — nothing above it but the
   bar. So the room the screen would have left between the bar and the step

package/css/sheet.css

@@ -199,15 +199,23 @@
   cursor: grab;
 }
 /* paper: the head keeps the sheet's own colour, the content is white (Lh 2026-10-05).
-   The body and the foot read as paper; the handle and the head stay on the card. */
+   The body and the foot read as paper; the handle and the head stay on the card.
+   The flex gap under the head is outside the body, so it stays the sheet's tint.
+   The first field would sit on that colour seam. The white inset is --sp-6 (24px at
+   the default spacing), the body's own top padding, and only when the sheet is paper.
+   A plain sheet keeps padding-top 0. A sheet in a stack wears the same class; its padding
+   is the stack's own rule, because a pull adds --_refresh on top of this inset.
+   The ink falls back to the wireframe word colour: an unset --color-ink would otherwise
+   inherit a dark card's light ink, and the words would vanish on the white. */
 .sheet--paper > .sheet__body {
   --card-bg: var(--color-paper, #fff);
-  --card-ink: var(--color-ink);
-  --card-muted: var(--_muted-on-paper);
+  --card-ink: var(--color-ink, #141414);
+  --card-muted: var(--_muted-on-paper, #555555);
   background: var(--card-bg);
   color: var(--card-ink);
+  padding-top: var(--sp-6);
 }
-.sheet--paper > .card__foot { --card-bg: var(--color-paper, #fff); color: var(--color-ink); }
+.sheet--paper > .card__foot { --card-bg: var(--color-paper, #fff); color: var(--color-ink, #141414); }
 .sheet__handle--dots {
   --_dot: var(--sp-1);
   --_step: calc(var(--_dot) * 2.5);

package/css/stack.css

@@ -177,6 +177,10 @@
 .sheet-stack--tap > .card > .card__head { touch-action: none; }
 /* a pull in the content, already at the top: the words move down, the card stays. --_refresh is the finger, private. */
 .sheet-stack > .card > .sheet__body { padding-top: var(--_refresh, 0px); transition: padding-top var(--motion-sheet) ease; }
+/* paper on a stacked sheet is the same class as the single sheet (Lh 2026-10-06). The head keeps the card's
+   colour. The body is white, from the rule in sheet.css, and its top inset is --sp-6. A pull still adds
+   --_refresh: this rule wins on padding, because the pull's rule above is more specific than the single sheet's. */
+.sheet-stack > .card.sheet--paper > .sheet__body { padding-top: calc(var(--sp-6) + var(--_refresh, 0px)); }
 .sheet-stack--tap > .card.is-open:not(:has(> .sheet__body)) {
   padding-top: calc(var(--card-pad) + var(--_refresh, 0px));
   transition: translate var(--motion-sheet) ease, padding-top var(--motion-sheet) ease;
@@ -311,6 +315,19 @@
 .sheet-stack--tap > .card:has(> .sheet__body).is-open { overflow: clip; }
 .sheet-stack > .card:has(> .sheet__body) > :not(.sheet__body) { flex-shrink: 0; }
 .sheet-stack > .card > .sheet__body { --_cover: 0rem; } /* nothing slid under here: the stack's sheet is always whole */
+/* a paper stack's foot is white to the card's edges, and it covers the tinted flex gap above it so the
+   button does not sit on a colour stripe. The head's gap stays: it is outside this foot. The button stays
+   where it was — the padding gives back what the bleed takes. */
+.sheet-stack > .card.sheet--paper > .card__foot {
+  background: var(--color-paper, #fff);
+  color: var(--color-ink, #141414);
+  margin-top: calc(-1 * var(--card-gap));
+  margin-inline: calc(-1 * var(--card-pad));
+  margin-bottom: calc(-1 * var(--card-pad));
+  padding-top: var(--card-gap);
+  padding-inline: var(--card-pad);
+  padding-bottom: var(--card-pad);
+}
 
 /* ---- StackSheet's tabs (Lh 2026-09-23): the head's end is a row of small icon buttons, the sheet's pages — the chosen one
    filled (.icon-btn--invert) only while the sheet is open; a count is a small circle over the icon's top right corner ---- */

package/dist/cardds.css

@@ -1178,6 +1178,10 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .sheet-stack--tap > .card > .card__head { touch-action: none; }
 /* a pull in the content, already at the top: the words move down, the card stays. --_refresh is the finger, private. */
 .sheet-stack > .card > .sheet__body { padding-top: var(--_refresh, 0px); transition: padding-top var(--motion-sheet) ease; }
+/* paper on a stacked sheet is the same class as the single sheet (Lh 2026-10-06). The head keeps the card's
+   colour. The body is white, from the rule in sheet.css, and its top inset is --sp-6. A pull still adds
+   --_refresh: this rule wins on padding, because the pull's rule above is more specific than the single sheet's. */
+.sheet-stack > .card.sheet--paper > .sheet__body { padding-top: calc(var(--sp-6) + var(--_refresh, 0px)); }
 .sheet-stack--tap > .card.is-open:not(:has(> .sheet__body)) {
   padding-top: calc(var(--card-pad) + var(--_refresh, 0px));
   transition: translate var(--motion-sheet) ease, padding-top var(--motion-sheet) ease;
@@ -1312,6 +1316,19 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .sheet-stack--tap > .card:has(> .sheet__body).is-open { overflow: clip; }
 .sheet-stack > .card:has(> .sheet__body) > :not(.sheet__body) { flex-shrink: 0; }
 .sheet-stack > .card > .sheet__body { --_cover: 0rem; } /* nothing slid under here: the stack's sheet is always whole */
+/* a paper stack's foot is white to the card's edges, and it covers the tinted flex gap above it so the
+   button does not sit on a colour stripe. The head's gap stays: it is outside this foot. The button stays
+   where it was — the padding gives back what the bleed takes. */
+.sheet-stack > .card.sheet--paper > .card__foot {
+  background: var(--color-paper, #fff);
+  color: var(--color-ink, #141414);
+  margin-top: calc(-1 * var(--card-gap));
+  margin-inline: calc(-1 * var(--card-pad));
+  margin-bottom: calc(-1 * var(--card-pad));
+  padding-top: var(--card-gap);
+  padding-inline: var(--card-pad);
+  padding-bottom: var(--card-pad);
+}
 
 /* ---- StackSheet's tabs (Lh 2026-09-23): the head's end is a row of small icon buttons, the sheet's pages — the chosen one
    filled (.icon-btn--invert) only while the sheet is open; a count is a small circle over the icon's top right corner ---- */
@@ -1595,15 +1612,23 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   cursor: grab;
 }
 /* paper: the head keeps the sheet's own colour, the content is white (Lh 2026-10-05).
-   The body and the foot read as paper; the handle and the head stay on the card. */
+   The body and the foot read as paper; the handle and the head stay on the card.
+   The flex gap under the head is outside the body, so it stays the sheet's tint.
+   The first field would sit on that colour seam. The white inset is --sp-6 (24px at
+   the default spacing), the body's own top padding, and only when the sheet is paper.
+   A plain sheet keeps padding-top 0. A sheet in a stack wears the same class; its padding
+   is the stack's own rule, because a pull adds --_refresh on top of this inset.
+   The ink falls back to the wireframe word colour: an unset --color-ink would otherwise
+   inherit a dark card's light ink, and the words would vanish on the white. */
 .sheet--paper > .sheet__body {
   --card-bg: var(--color-paper, #fff);
-  --card-ink: var(--color-ink);
-  --card-muted: var(--_muted-on-paper);
+  --card-ink: var(--color-ink, #141414);
+  --card-muted: var(--_muted-on-paper, #555555);
   background: var(--card-bg);
   color: var(--card-ink);
+  padding-top: var(--sp-6);
 }
-.sheet--paper > .card__foot { --card-bg: var(--color-paper, #fff); color: var(--color-ink); }
+.sheet--paper > .card__foot { --card-bg: var(--color-paper, #fff); color: var(--color-ink, #141414); }
 .sheet__handle--dots {
   --_dot: var(--sp-1);
   --_step: calc(var(--_dot) * 2.5);

package/dist/cards/Card.d.ts

@@ -7,6 +7,8 @@ export type Tone = 1 | 2 | 3 | 4 | 5;
 export interface CardProps extends ComponentProps<'article'> {
     /** the tone slot — see `Tone` */
     tone?: Tone;
+    /** the content is white paper and the head keeps the card's colour. The same look as `Sheet paper`. Omit it and the content matches the head */
+    paper?: boolean;
     /** compact: a small card inside a card or a sheet body (a note, a promo) */
     sm?: boolean;
     /** a list row that is its own card: thumb · body · end, in a CardList */
@@ -45,7 +47,7 @@ export interface CardProps extends ComponentProps<'article'> {
  * boundary). The order is the card's, never the writer's. A head of its own shape: write `<CardHead>` as the first child instead.
  * A page with one feature and one CTA may be a single card. Keep everything big.
  */
-export declare function Card({ tone, sm, row, cover, fold, centre, band, as, heading, caption, end, level, foot, footLink, stack, className, style, children, onClick, ref, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
+export declare function Card({ tone, paper, sm, row, cover, fold, centre, band, as, heading, caption, end, level, foot, footLink, stack, className, style, children, onClick, ref, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
     onClick: import("react").MouseEventHandler<HTMLElement> | undefined;
     "aria-busy"?: (boolean | "true" | "false") | undefined;
     ref: (node: HTMLElement | null) => void;

package/dist/cards/Card.js

@@ -12,7 +12,7 @@ import { StackHeadCtx, StackPullCtx, stackPaint, useStackCard } from '../sheets/
  * boundary). The order is the card's, never the writer's. A head of its own shape: write `<CardHead>` as the first child instead.
  * A page with one feature and one CTA may be a single card. Keep everything big.
  */
-export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, stack, className, style, children, onClick, ref, ...rest }) {
+export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, stack, className, style, children, onClick, ref, ...rest }) {
     const head = heading != null || caption != null || end != null;
     const tail = foot != null || footLink != null;
     if (head || tail) {
@@ -54,7 +54,7 @@ export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article',
     const props = {
         ...rest,
         ref: setRef,
-        className: cx('card', tone && tone !== 1 && `card--${tone}`, sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', painted.className, className),
+        className: cx('card', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', painted.className, className),
         style: painted.style || style ? { ...painted.style, ...style } : undefined,
         ...(stack ? { 'aria-busy': painted.busy } : {}),
         onClick: stack ? click : onClick,

package/dist/sheets/Sheet.d.ts

@@ -25,7 +25,7 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
     mark?: 'line' | 'dots';
     /** the card tone slot, as `Card tone` — 2 and up add `card--N`. The head shows it; with `paper` the content does not */
     tone?: 1 | 2 | 3 | 4 | 5;
-    /** the content is white paper and the head keeps the sheet's colour. Omit it and the content is the same colour as the head */
+    /** the content is white paper and the head keeps the sheet's colour. The same prop on a `StackSheet` or a `Card` in a stack. Omit it and the content is the same colour as the head */
     paper?: boolean;
 }
 /**

package/dist/sheets/StackSheet.d.ts

@@ -13,8 +13,10 @@ export interface StackSheetTab {
 export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'> {
     /** the SHEET HEAD's title — an h2 (the page's h1 is its own) */
     title: ReactNode;
-    /** the paper — see `Tone` */
+    /** the tone slot — see `Tone`. The head shows it */
     tone?: Tone;
+    /** the content is white paper and the head keeps the sheet's colour. The same look as `Sheet paper`. Omit it and the content matches the head */
+    paper?: boolean;
     /** the head's end when the sheet has no tabs: an Icon, an IconRow */
     icon?: ReactNode;
     /** TABS in the head: icon buttons at the end — the sheet's pages. A tap on one in a peeked head opens the sheet on it */
@@ -40,4 +42,4 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
  * A count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
-export declare function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, backAt, stack, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;
+export declare function StackSheet({ title, tone, paper, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, backAt, stack, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;

package/dist/sheets/StackSheet.js

@@ -19,7 +19,7 @@ import { word } from '../words.js';
  * A count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
-export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = word('back'), backAt = 'none', stack, className, children, ...rest }) {
+export function StackSheet({ title, tone, paper, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = word('back'), backAt = 'none', stack, className, children, ...rest }) {
     const [tab, pick] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id, onTabChange);
     // a title longer than its room does not wrap: it runs sideways, like a song title in a short slot — the room it overflows by
     // is measured here (the tabs may grow with the text size) and handed to the CSS as --_over
@@ -38,5 +38,5 @@ export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab,
         measure();
         return watchSize([h, run], measure);
     }, [title]);
-    return (_jsxs(Card, { stack: stack, tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [backAt === 'start' && _jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: cx('stack-sheet__title', long && 'is-long'), children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs(IconBtn, { sm: true, invert: t.id === tab, role: "tab", "aria-selected": t.id === tab, label: t.label, className: "stack-sheet__tab", onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon, backAt === 'end' && _jsx(StackBack, { end: true, label: backLabel })] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
+    return (_jsxs(Card, { stack: stack, tone: tone, paper: paper, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [backAt === 'start' && _jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: cx('stack-sheet__title', long && 'is-long'), children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs(IconBtn, { sm: true, invert: t.id === tab, role: "tab", "aria-selected": t.id === tab, label: t.label, className: "stack-sheet__tab", onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon, backAt === 'end' && _jsx(StackBack, { end: true, label: backLabel })] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
 }

package/dist/templates/Home.d.ts

@@ -7,8 +7,10 @@ export interface HomeSheet {
     title: ReactNode;
     /** the sheet head's end when it has no tabs: an Icon, an IconRow */
     icon?: ReactNode;
-    /** the paper — see `Tone` (default: 2, 3, 1, 2, 3 by place) */
+    /** 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` */
+    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[];
     /** the tab shown first (default: the first) */

package/dist/templates/Home.js

@@ -50,5 +50,5 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
     }, [leaving]);
     const [tabs, setTabs] = useState(() => Object.fromEntries(sheets.map((x, i) => [i, x.defaultTab ?? x.tabs?.[0]?.id])));
     const shows = (i) => i === shown || i === leaving || (keep && seen.has(i));
-    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: shown, onOpenChange: request, onRefresh: onRefresh, refreshing: refreshing, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, backAt: backAt, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
+    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: shown, onOpenChange: request, onRefresh: onRefresh, refreshing: refreshing, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], paper: s.paper, title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, backAt: backAt, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.55",
+  "version": "0.7.57",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",