@usableapp/cardds 0.7.56 → 0.7.58

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.58 — 2026-10-06
+
+### Changed
+- **A closed paper sheet in a stack shows the card's colour where the next sheet's round top does not cover it.** The white body used to show in those corners. While the sheet is closed that body is clear. On the way back into the stack the card colour fades in over `--motion-quick`, and the fade ends as the sheet stops. Open, the body is white at once. The first row still sits `--sp-6` down. Nothing to change in a screen.
+
+## 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

package/README.md

@@ -275,8 +275,12 @@ 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.
+  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.
 - **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

@@ -203,16 +203,19 @@
    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 plain sheet keeps padding-top 0. A sheet in a stack wears the same class and the same
+   inset: the stack's own gap under the head is the card's colour, so the row still needs this white.
+   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

@@ -175,7 +175,9 @@
 }
 .sheet-stack--tap > .card.is-open.is-dragging { transition: none; }
 .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. */
+/* a pull in the content, already at the top: the words move down, the card stays. --_refresh is the finger, private.
+   A paper body adds its own --sp-6 on top of this (the rule below): the stack's gap under the head is the
+   card's colour, so without the white inset the first row sits on that seam. */
 .sheet-stack > .card > .sheet__body { padding-top: var(--_refresh, 0px); transition: padding-top var(--motion-sheet) ease; }
 .sheet-stack--tap > .card.is-open:not(:has(> .sheet__body)) {
   padding-top: calc(var(--card-pad) + var(--_refresh, 0px));
@@ -311,6 +313,42 @@
 .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 closed paper sheet's body stays clear (Lh 2026-10-06). The next sheet's round top does not
+   cover the corners, and a white body showed there beside the head. Clear, the card's own colour
+   shows in that pocket. Open, the body is white, and the first row sits --sp-6 down, the same white
+   inset a single paper sheet keeps: the flex gap under the head is the card's colour, so the row
+   would otherwise sit on that seam. A pull adds --_refresh on top of the inset. On the way back
+   into the stack the card colour fades in quickly (--motion-quick) and that fade ends with the
+   sheet's own slide (--motion-sheet, plus the same stagger), so the corner is the head colour
+   at the moment the sheet stops. Rising, the body is white at once. */
+.sheet-stack > .card.sheet--paper > .sheet__body {
+  padding-top: calc(var(--sp-6) + var(--_refresh, 0px));
+  transition: padding-top var(--motion-sheet) ease, background-color 0s linear;
+}
+.sheet-stack > .card.sheet--paper:not(.is-open) > .sheet__body {
+  background-color: transparent;
+  transition:
+    padding-top var(--motion-sheet) ease,
+    background-color var(--motion-quick) ease calc(var(--stagger, 0) * 70ms + var(--motion-sheet) - var(--motion-quick));
+}
+@media (prefers-reduced-motion: reduce) {
+  .sheet-stack > .card.sheet--paper:not(.is-open) > .sheet__body {
+    transition: padding-top var(--motion-sheet) ease, background-color 0s linear;
+  }
+}
+/* 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

@@ -1176,7 +1176,9 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 }
 .sheet-stack--tap > .card.is-open.is-dragging { transition: none; }
 .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. */
+/* a pull in the content, already at the top: the words move down, the card stays. --_refresh is the finger, private.
+   A paper body adds its own --sp-6 on top of this (the rule below): the stack's gap under the head is the
+   card's colour, so without the white inset the first row sits on that seam. */
 .sheet-stack > .card > .sheet__body { padding-top: var(--_refresh, 0px); transition: padding-top var(--motion-sheet) ease; }
 .sheet-stack--tap > .card.is-open:not(:has(> .sheet__body)) {
   padding-top: calc(var(--card-pad) + var(--_refresh, 0px));
@@ -1312,6 +1314,42 @@ 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 closed paper sheet's body stays clear (Lh 2026-10-06). The next sheet's round top does not
+   cover the corners, and a white body showed there beside the head. Clear, the card's own colour
+   shows in that pocket. Open, the body is white, and the first row sits --sp-6 down, the same white
+   inset a single paper sheet keeps: the flex gap under the head is the card's colour, so the row
+   would otherwise sit on that seam. A pull adds --_refresh on top of the inset. On the way back
+   into the stack the card colour fades in quickly (--motion-quick) and that fade ends with the
+   sheet's own slide (--motion-sheet, plus the same stagger), so the corner is the head colour
+   at the moment the sheet stops. Rising, the body is white at once. */
+.sheet-stack > .card.sheet--paper > .sheet__body {
+  padding-top: calc(var(--sp-6) + var(--_refresh, 0px));
+  transition: padding-top var(--motion-sheet) ease, background-color 0s linear;
+}
+.sheet-stack > .card.sheet--paper:not(.is-open) > .sheet__body {
+  background-color: transparent;
+  transition:
+    padding-top var(--motion-sheet) ease,
+    background-color var(--motion-quick) ease calc(var(--stagger, 0) * 70ms + var(--motion-sheet) - var(--motion-quick));
+}
+@media (prefers-reduced-motion: reduce) {
+  .sheet-stack > .card.sheet--paper:not(.is-open) > .sheet__body {
+    transition: padding-top var(--motion-sheet) ease, background-color 0s linear;
+  }
+}
+/* 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 ---- */
@@ -1599,16 +1637,19 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
    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 plain sheet keeps padding-top 0. A sheet in a stack wears the same class and the same
+   inset: the stack's own gap under the head is the card's colour, so the row still needs this white.
+   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.56",
+  "version": "0.7.58",
   "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.",