@usableapp/cardds 0.2.2 → 0.4.0

package/css/numbers.css

@@ -31,8 +31,8 @@
   mask: radial-gradient(farthest-side, transparent calc(100% - var(--_w) - 1px), currentColor calc(100% - var(--_w)));
   -webkit-mask: radial-gradient(farthest-side, transparent calc(100% - var(--_w) - 1px), currentColor calc(100% - var(--_w)));
 }
-.ring__value { font: var(--type-stat); letter-spacing: var(--track-display); }
-.ring__label { font: var(--type-caption); color: var(--card-muted); }
+.ring__value { font: var(--ring-value-font, var(--type-stat)); letter-spacing: var(--track-display); }
+.ring__label { font: var(--ring-label-font, var(--type-caption)); color: var(--ring-label-ink, var(--card-muted)); }
 .card--3 .ring__label { color: inherit; opacity: 0.7; }
 .ring--sm { --_size: var(--avatar-xl); --_w: var(--sp-3); }
 .ring--sm .ring__value { font: 800 var(--fs-2xl)/1 var(--font-display); }
@@ -52,10 +52,10 @@
   --on-accent: var(--_bg);
   list-style: none;
   margin: 0;
-  padding: var(--sp-2);
+  padding: var(--track-pad, var(--sp-2));
   display: flex;
   align-items: center;
-  border-radius: var(--r-chip);
+  border-radius: var(--track-radius, var(--r-chip));
   background: var(--_bg);
   color: var(--_ink);
 }
@@ -96,9 +96,9 @@
   grid-template-areas: "label num" "foot num";
   align-items: end;
   gap: var(--sp-2) var(--sp-4);
-  min-height: var(--tile-h);
+  min-height: var(--card-band-min-h, var(--tile-h));
 }
-.band__label { grid-area: label; align-self: start; font: var(--type-label); font-size: var(--fs-body); line-height: 1.2; }
+.band__label { grid-area: label; align-self: start; font: var(--band-label-font, var(--type-label)); font-size: var(--band-label-font-size, var(--fs-body)); line-height: 1.2; }
 .band__num {
   grid-area: num;
   font: 800 var(--fs-giant) / 0.9 var(--font-display);
@@ -106,14 +106,14 @@
   font-variant-numeric: tabular-nums;
 }
 .band__num small { font-size: 0.5em; font-weight: 700; margin-right: 0.1em; } /* unit or % */
-.band__foot { grid-area: foot; font: var(--type-caption); color: var(--card-muted); }
+.band__foot { grid-area: foot; font: var(--band-foot-font, var(--type-caption)); color: var(--band-foot-ink, var(--card-muted)); }
 .card--3 .band__foot { color: inherit; opacity: 0.7; }
 /* band stack: ONE card boundary; bands are frameless inside it, a hairline
    between each. Bands may still carry slot tints (card--2 / card--3). */
 .band-stack {
   display: grid;
-  border: var(--border-w) solid var(--card-border);
-  border-radius: var(--r-card);
+  border: var(--border-w) solid var(--band-stack-border, var(--card-border));
+  border-radius: var(--band-stack-radius, var(--r-card));
   overflow: hidden;
 }
 .band-stack > .card--band { border: 0; border-radius: 0; box-shadow: none; }
@@ -164,7 +164,7 @@
 
 /* ---- picker: horizontal snap picker, centre value big ----
    <div class="picker"><div class="picker__rail"><button class="picker__item">100</button>…</div><span class="picker__unit">ml</span></div> */
-.picker { display: grid; gap: var(--sp-1); justify-items: center; position: relative; }
+.picker { display: grid; gap: var(--picker-gap, var(--sp-1)); justify-items: center; position: relative; }
 .picker__rail {
   width: 100%;
   display: grid;
@@ -172,7 +172,7 @@
   /* side padding = one third of the rail, so the first and last value can sit
      in the centre; the content box is then one third wide, and each column
      fills it (percent columns resolve against the content box) */
-  padding-inline: calc(100% / 3);
+  padding-inline: var(--picker-rail-pad-x, calc(100% / 3));
   grid-auto-columns: 100%;
   overflow-x: auto;
   scroll-snap-type: x mandatory;
@@ -185,8 +185,8 @@
   border: 0;
   background: transparent;
   color: inherit;
-  padding: var(--sp-2) 0;
-  font: var(--type-stat);
+  padding: var(--picker-item-pad-y, var(--sp-2)) var(--picker-item-pad-x, 0);
+  font: var(--picker-item-font, var(--type-stat));
   letter-spacing: var(--track-display);
   font-variant-numeric: tabular-nums;
   opacity: 0.3;
@@ -205,7 +205,7 @@
   left: calc(100% / 3);
 }
 .picker::after { left: auto; right: calc(100% / 3); }
-.picker__unit { font: var(--type-caption); color: var(--card-muted); }
+.picker__unit { font: var(--picker-unit-font, var(--type-caption)); color: var(--picker-unit-ink, var(--card-muted)); }
 .card--3 .picker__unit { color: inherit; opacity: 0.7; }
 /* the scrolled-to item lights up by position — no JS */
 @supports (animation-timeline: view(x)) {
@@ -221,30 +221,30 @@
 .badge {
   display: inline-grid;
   place-items: center;
-  min-width: var(--badge);
-  height: var(--badge);
-  padding: 0 var(--sp-2);
-  border-radius: var(--r-chip);
-  background: var(--accent);
-  color: var(--on-accent);
-  font: var(--type-label);
+  min-width: var(--badge-min-w, var(--badge));
+  height: var(--badge-h, var(--badge));
+  padding: var(--badge-pad-y, 0) var(--badge-pad-x, var(--sp-2));
+  border-radius: var(--badge-radius, var(--r-chip));
+  background: var(--badge-bg, var(--accent));
+  color: var(--badge-ink, var(--on-accent));
+  font: var(--badge-font, var(--type-label));
   font-variant-numeric: tabular-nums;
   vertical-align: middle;
 }
-.badge--soft { background: var(--ink-tint); color: inherit; }
+.badge--soft { background: var(--badge-soft-bg, var(--ink-tint)); color: inherit; }
 
 /* ---- bars: three or four bars with a count on top — the glance chart ----
    <div class="bars"><div class="bar" style="--v: 16"><span>+16</span></div>… --max on the parent */
-.bars { --max: 20; --_h: 5rem; display: flex; align-items: end; gap: var(--sp-2); height: calc(var(--_h) + var(--sp-8)); }
+.bars { --max: 20; --_h: 5rem; display: flex; align-items: end; gap: var(--bars-gap, var(--sp-2)); height: calc(var(--_h) + var(--sp-8)); }
 .bar {
   flex: 1;
   min-width: 0;
   display: grid;
   align-content: end;
   justify-items: center;
-  gap: var(--sp-1);
+  gap: var(--bar-gap, var(--sp-1));
   height: 100%;
-  font: var(--type-caption);
+  font: var(--bar-font, var(--type-caption));
   font-weight: 700;
 }
 .bar::after {

package/css/people.css

@@ -15,9 +15,9 @@
   border-radius: 50%;
   display: grid;
   place-items: center;
-  background: var(--card-2-bg);
-  color: var(--card-2-ink);
-  font: var(--type-label);
+  background: var(--avatar-bg, var(--card-2-bg));
+  color: var(--avatar-ink, var(--card-2-ink));
+  font: var(--avatar-font, var(--type-label));
   font-size: calc(var(--_size) * 0.3);
   text-transform: uppercase;
   letter-spacing: 0.02em;
@@ -30,10 +30,10 @@
 .avatar--lg { --_size: var(--avatar-lg); }
 .avatar--xl { --_size: var(--avatar-xl); } /* sheet head icon ring */
 /* outline avatar: no fill, an edge — icons in a ring, "add" slots */
-.avatar--outline { background: transparent; color: inherit; border: var(--border-w) solid var(--outline); }
-.avatar--add { background: transparent; color: inherit; border: var(--border-w) dashed var(--outline); cursor: pointer; }
+.avatar--outline { background: transparent; color: inherit; border: var(--border-w) solid var(--avatar-outline-border, var(--outline)); }
+.avatar--add { background: transparent; color: inherit; border: var(--border-w) dashed var(--avatar-add-border, var(--outline)); cursor: pointer; }
 /* accent avatar: the "+7" tail, the selected person */
-.avatar--on { background: var(--accent); color: var(--on-accent); }
+.avatar--on { background: var(--avatar-on-bg, var(--accent)); color: var(--avatar-on-ink, var(--on-accent)); }
 /* halo: faint concentric rings behind a hero avatar (decorative) */
 .avatar--halo::before {
   content: "";
@@ -55,7 +55,7 @@
    <div class="avatar-pick"><button class="avatar-pick__item"><span class="avatar avatar--lg avatar--add">+</span><span class="avatar-pick__name">Add</span><span class="avatar-pick__role">member</span></button>…</div> */
 .avatar-pick {
   display: flex;
-  gap: var(--sp-4);
+  gap: var(--avatar-pick-gap, var(--sp-4));
   overflow-x: auto;
   scroll-snap-type: x proximity;
   scrollbar-width: none; /* starts at the card's padding edge, like every row */
@@ -64,16 +64,16 @@
 .avatar-pick__item {
   scroll-snap-align: start;
   flex: none;
-  width: var(--avatar-lg);
+  width: var(--avatar-pick-item-w, var(--avatar-lg));
   display: grid;
   justify-items: center;
-  gap: var(--sp-2);
+  gap: var(--avatar-pick-item-gap, var(--sp-2));
   border: 0;
   background: transparent;
   color: inherit;
   padding: 0;
   text-align: center;
 }
-.avatar-pick__name { font: var(--type-label); font-size: var(--fs-sm); }
-.avatar-pick__role { font: var(--type-caption); color: var(--card-muted); margin-top: calc(-1 * var(--sp-1)); }
+.avatar-pick__name { font: var(--avatar-pick-name-font, var(--type-label)); font-size: var(--avatar-pick-name-font-size, var(--fs-sm)); }
+.avatar-pick__role { font: var(--avatar-pick-role-font, var(--type-caption)); color: var(--avatar-pick-role-ink, var(--card-muted)); margin-top: calc(-1 * var(--sp-1)); }
 .card--3 .avatar-pick__role { color: inherit; opacity: 0.7; }

package/css/sheet.css

@@ -28,7 +28,7 @@
    page. Many sheets stacked as the app's menu are the other system,
    .sheet-stack (stack.css): the same material, its own class and file.
 
-   <article class="card sheet sheet--half" data-sheet-states="peek half 3q full">
+   <article class="card sheet sheet--half">
    A tap on the handle TOGGLES the sheet between its own state and peek
    (Lh 2026-09-16) — never a step-by-step climb; a drag snaps to any of
    the listed states, and the state it lands on becomes the one a tap
@@ -46,14 +46,12 @@
    ============================================================ */
 
 .sheet {
-  --_handle: var(--sp-1);
   /* the strip a peeked sheet shows: the card's own top padding, the handle,
      the gap, one title row (--tap — the head rule below makes every head at
      least that tall) and the gap under it, so the cut lands exactly where
      the first control starts and nothing of it leaks through. Published
      (and registered in tokens.css) so a sheet whose head is taller can
      retune it: .my-sheet { --sheet-peek: … } */
-  --sheet-peek: calc(var(--card-pad) + var(--_handle) + 2 * var(--card-gap) + var(--tap));
   --sheet-half: 0.5;              /* a share of the sheet's own height */
   --sheet-3q: 0.25;               /* three quarters showing: slid by a quarter */
   /* the sheet's own height, seen from inside it: the box it slides in is the
@@ -82,20 +80,22 @@
   overflow: clip;
   border-radius: var(--r-card) var(--r-card) 0 0;
   border-bottom: 0;
-  box-shadow: var(--shadow-sheet);
+  box-shadow: var(--sheet-shadow, var(--shadow-sheet));
 }
 .sheet--full { --_y: 0%; --_cover: 0rem; }
 .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)); }
+/* --sheet-peek is declared on the BOX the sheet slides in, not on the sheet: the words behind a peeked sheet
+   have to read it too (step.css keeps that much room under them), and a token only flows down. The sheet
+   inherits it. A sheet whose head is taller retunes it on the box. */
+:is(.step, .sheet-stage) { --_handle: var(--sp-1); --sheet-peek: calc(var(--card-pad-rest) + var(--_handle) + 2 * var(--card-gap-rest) + var(--tap)); }
+
 /* ---- 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).
+   with `inert` (the React Sheet does). WHO brings it onto the screen is the app's business — a button, a route:
+   cardds ties no component to another. Nothing waits at peek before the first call.
    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:
@@ -178,7 +178,7 @@
   opacity: 0.3;
   width: var(--tap-sm);
   height: var(--_handle);
-  border-radius: var(--r-chip);
+  border-radius: var(--sheet-handle-radius, var(--r-chip));
   margin: 0 auto;
   padding: 0;
   touch-action: none;
@@ -210,8 +210,8 @@
   min-height: var(--tap);
   text-align: center;
 }
-.sheet__title { font: var(--type-h2); letter-spacing: var(--track-h2); margin: 0; }
-.sheet__sub { font: var(--type-caption); color: var(--card-muted); }
+.sheet__title { font: var(--sheet-title-font, var(--type-h2)); letter-spacing: var(--track-h2); margin: 0; }
+.sheet__sub { font: var(--sheet-sub-font, var(--type-caption)); color: var(--sheet-sub-ink, var(--card-muted)); }
 
 /* ============================================================
    .sheet-stage — the overlay stage: a page-height box the sheet
@@ -233,7 +233,7 @@
   margin-inline: auto;
   overflow: clip; /* not hidden: a clipped box is not a scroll container, so revealing a focused field never shifts the stage */
   container-type: size; /* the sheet's body reads this box's height as 100cqh (--_box above) */
-  background: var(--surface);
+  background: var(--sheet-stage-bg, var(--surface));
 }
 /* on an app screen the stage is the page: it takes the screen's inset back (edge to
    edge, like a step) and, after a fixed .appbar, the room the screen reserved for
@@ -268,7 +268,7 @@
   position: absolute;
   inset: 0;
   isolation: isolate; /* the ring and the hint stack inside the map only — a sheet over the map covers them */
-  color: var(--on-surface);
+  color: var(--map-ink, var(--on-surface));
   background:
     repeating-linear-gradient(75deg,  transparent 0 5.5rem,  var(--hairline) 5.5rem 6.25rem),
     repeating-linear-gradient(-18deg, transparent 0 8.75rem, var(--ink-tint) 8.75rem 9.25rem),
@@ -286,9 +286,9 @@
   height: var(--map-ring);
   translate: -50% -50%;
   border-radius: 50%;
-  border: var(--border-w) solid var(--accent);
-  background: color-mix(in srgb, var(--accent) 22%, transparent);
-  box-shadow: var(--shadow-float);
+  border: var(--border-w) solid var(--map-ring-border, var(--accent));
+  background: var(--map-ring-bg, color-mix(in srgb, var(--accent) 22%, transparent));
+  box-shadow: var(--map-ring-shadow, var(--shadow-float));
   pointer-events: none;
   z-index: 1; /* above the engine's panes (Leaflet's tiles sit at 200, but inside their own stacking context) */
 }
@@ -297,10 +297,10 @@
   right: var(--sp-2);
   bottom: var(--sp-2);
   padding: var(--sp-0) var(--sp-2);
-  border-radius: var(--r-chip);
-  background: color-mix(in srgb, var(--surface) 80%, transparent);
-  color: var(--on-surface-muted);
-  font: var(--type-caption);
+  border-radius: var(--map-credit-radius, var(--r-chip));
+  background: var(--map-credit-bg, color-mix(in srgb, var(--surface) 80%, transparent));
+  color: var(--map-credit-ink, var(--on-surface-muted));
+  font: var(--map-credit-font, var(--type-caption));
   pointer-events: none;
   z-index: 1;
 }
@@ -311,12 +311,12 @@
   translate: -50% 0;
   max-width: calc(100% - 2 * var(--sp-4));
   padding: var(--sp-2) var(--sp-4);
-  border-radius: var(--r-chip);
-  background: var(--card-3-bg);
-  color: var(--card-3-ink);
-  font: var(--type-label);
+  border-radius: var(--map-hint-radius, var(--r-chip));
+  background: var(--map-hint-bg, var(--card-3-bg));
+  color: var(--map-hint-ink, var(--card-3-ink));
+  font: var(--map-hint-font, var(--type-label));
   text-align: center;
-  box-shadow: var(--shadow-float);
+  box-shadow: var(--map-hint-shadow, var(--shadow-float));
   pointer-events: none;
   z-index: 1;
 }
@@ -330,7 +330,7 @@
    the sheet gives it up itself, as --_lift — the same token a raised sheet floats on. */
 .sheet-stage > .sheet { --_lift: var(--kb, 0rem); bottom: var(--_lift); }
 .sheet-stage > .sheet--raised { --_lift: calc(var(--tap-lg) + var(--kb, 0rem)); }
-.sheet--raised { --_lift: var(--tap-lg); bottom: var(--_lift); border-radius: var(--r-card); border-bottom: var(--border-w) solid var(--card-border); }
+.sheet--raised { --_lift: var(--tap-lg); bottom: var(--_lift); border-radius: var(--sheet-raised-radius, var(--r-card)); border-bottom: var(--border-w) solid var(--card-border); }
 .sheet-stage__foot {
   position: absolute;
   inset-inline: 0;
@@ -339,8 +339,8 @@
   margin: 0;
   display: grid;
   place-items: center;
-  font: var(--type-caption);
-  color: var(--card-3-ink);
+  font: var(--sheet-stage-foot-font, var(--type-caption));
+  color: var(--sheet-stage-foot-ink, var(--card-3-ink));
   z-index: 2;
 }
 

package/css/step.css

@@ -62,8 +62,9 @@
 :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. */
+   (sheet.css), and a form lives whole in ONE sheet, never item by item on the base. That is how cardds's
+   own screens are composed (the guide); the framework does not police it — a component never changes
+   because another one is there. */
 
 /* 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;
@@ -82,11 +83,10 @@
   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. */
+   (card.css). Behind a PEEKED sheet the words keep the strip's room under them, so whatever is down there
+   (the buttons that call the other sheets) scrolls clear of it — CSS alone: the box declares --sheet-peek. */
+.step:has(> .sheet--peek) > :is(.base-content, .pages) { padding-bottom: var(--sheet-peek); }
 .step > :is(.base-content, .pages) {
-  padding-bottom: var(--sheet-room, 0rem);
   flex: 0 1 auto;
 }
 .step > :is(.base-content, .pages) {

package/css/theme.template.css

@@ -4,9 +4,12 @@
    Not part of the bundle: copy this file into the project as its own
    `theme.css` and load it AFTER cardds.css. It is the whole public
    surface of the system — the four size bases and the colour roles.
-   Everything else in tokens.css is derived from these; a project never
-   sets a derived token (--sp-4, --fs-h1, --r-card, --tap, --sheet-*…)
-   and never a multiplier.
+   Widest first: a BASE moves a whole family; a role / root token one meaning
+   everywhere (--accent, --btn-h, --header-h…); a KNOB one component
+   (--btn-pad-x, --chip-bg… — docs/knobs.md lists them; also settable on any
+   element, for the components inside it). Never a step of the scale
+   (--sp-4, --fs-h1, --r-card), a multiplier, a private --_* or a published
+   value (--card-pad, --bar-reserve, --sheet-*).
 
    The values below are the defaults (the wireframe): as shipped, this
    file changes nothing (tests/tokens.spec.js holds it to that).

package/css/tokens.css

@@ -49,6 +49,8 @@
   --chip-h: calc(var(--tap-base) * 19 / 24);  /* 38 chip height */
   --bar-h: calc(var(--tap-base) * 4 / 3);     /* 64 float bar, day cell, deck actions */
   --header-h: calc(var(--tap-base) * 5 / 4);  /* 60 top bar — .topbar and .appbar alike */
+  --card-pad-rest: var(--sp-5);  /* 20 a card's padding before any variant — .card publishes it as --card-pad; the sheet's peek strip is built from it where no card is in scope */
+  --card-gap-rest: var(--sp-4);  /* 16 …and its gap */
   --screen-pad: var(--sp-4); /* 16 the screen's inset — .sheet-stack cancels it */
   --map-ring: calc(var(--tap-base) * 10 / 3);    /* the rough-area ring on a map (sheet.css .map__ring) — a neighbourhood, not a house */
   --fab: calc(var(--tap-base) * 3 / 2); /* 72 square floating action */