@usableapp/cardds 0.7.95 → 0.7.97

package/css/tokens.css

@@ -103,9 +103,6 @@
   --motion-quick: 0.2s;  /* a small state flip that isn't a press: a chevron turning, a popover/banner opening */
   --motion-slide: 0.22s; /* a centred card sliding out and the next in (card.css) — quick, a page turn (Lh, 2026-09-12) */
   --motion-flip: 0.45s;  /* a postcard turning over (media.css) — slow enough to read as a card in the hand */
-  --dim: 0.7; /* secondary words dimmed on a ground whose muted ink does not fit (the dark card --3, a drawer, a tile's sub line): ONE share for all */
-  --rest: 0.6;  /* an unpicked choice at rest: .day, .segment__item, .float-bar__item */
-  --faint: 0.3; /* further still: rails, far dots, unselected picker items */
   --motion-press: 0.12s; /* a control giving under the finger and springing back (actions.css PRESS) */
   --press-scale: 0.96;   /* how far a finger-sized control gives — a share of its size */
   --press-dim: 0.6;      /* how far a card-wide one (a row, a summary line, a card) fades under the finger */
@@ -174,40 +171,45 @@
      value. That is what the fallbacks are for — a private mix (--_*) that
      reads an unset base is invalid, so var(--_x, #grey) lands on the grey.
      Set, the roles derive: tone 2 = the brand washed into the surface, the
-     muted inks = the ink washed into their ground. A role set directly
+     muted inks = the ink washed into its ground. A role set directly
      (a palette, or a project's theme.css) always wins over its derivation.
      ============================================================ */
-  --_muted-on-surface: color-mix(in srgb, var(--color-ink) 66%, var(--color-surface, #f2f2f0));
-  --_muted-on-paper: color-mix(in srgb, var(--color-ink) 66%, var(--color-paper, #ffffff));
   --_tone-2: color-mix(in srgb, var(--color-brand) 14%, var(--color-surface, #f2f2f0));
-  --_muted-on-tone-2: color-mix(in srgb, var(--color-ink, #141414) 72%, var(--_tone-2));
-  --_muted-on-brand: color-mix(in srgb, var(--color-on-brand) 70%, var(--color-brand)); /* the tone-3 card's secondary words: on-brand faded into brand — was opacity 0.7, which no theme could set (timebank #132, 2026-09-22) */
+  --_onlight-muted: color-mix(in srgb, var(--color-ink) 70%, var(--_tone-2));
+  --_ondark-muted: color-mix(in srgb, var(--color-on-brand) 70%, var(--color-brand));
+
+  /* INK: TWO SETS, ONLIGHT AND ONDARK (Lh 2026-10-18: "there are text colours ONLIGHT and ONDARK. When the ground is light, use
+     onlight; when the ground is dark, use ondark"). Words and glyphs alike (icons, marks, dots, a check, a knob). Each set holds its
+     ink and its muted shade to 4.5:1 on every ground of its side. docs/reference.md "Ink follows its ground". */
+  --ink-onlight: var(--color-ink, #141414);
+  --ink-onlight-muted: var(--_onlight-muted, #575757);   /* 4.6:1 on the water note and 4.9 on tone 4's grey, the darkest light grounds */
+  --ink-ondark: var(--color-on-brand, #ffffff);
+  --ink-ondark-muted: var(--_ondark-muted, #a8a8a8);     /* 4.6:1 on tone 5's grey, the lightest dark ground */
+
+  /* SIDES: every ground says whether it is dark (1) or light (0); nothing else. Its words and glyphs follow from the side
+     (the surface list below). Dark mode is these switches turned to 1 with darker fills, and no rule per piece. */
+  --surface-dark: 0;
+  --card-1-dark: 0;  --card-2-dark: 0;  --card-3-dark: 1;  --card-4-dark: 0;  --card-5-dark: 1;
+  --accent-dark: 1;   /* the brand fill: a primary button, a picked chip, a picked day */
+  --action-dark: 0;   /* the paper fill of neutral controls: a button, a chip, a field, a plain tile */
+  --neg-dark: 1;      /* a falling Delta's fill */
 
   /* app background ("earth-toned surface or shiny color, up to the app") */
   --surface: var(--color-surface, #f2f2f0);
-  --on-surface: var(--color-ink, #141414);
-  --on-surface-muted: var(--_muted-on-surface, #6b6b6b);
 
-  /* card boundaries — 3 slots so stacked/adjacent cards can differ */
-  --card-1-bg: var(--color-paper, #ffffff);  --card-1-ink: var(--color-ink, #141414);
-  --card-2-bg: var(--_tone-2, #e6e6e3);  --card-2-ink: var(--color-ink, #141414);
-  --card-3-bg: var(--color-brand, #141414);  --card-3-ink: var(--color-on-brand, #ffffff);
+  /* card boundaries — five tones; each one's words follow its side */
+  --card-1-bg: var(--color-paper, #ffffff);
+  --card-2-bg: var(--_tone-2, #e6e6e3);
+  --card-3-bg: var(--color-brand, #141414);
   /* tones 4 · 5 (Lh 2026-09-25): more card colours for a palette that has them — the wireframe keeps them grey */
-  --card-4-bg: #d4d4d0;  --card-4-ink: var(--color-ink, #141414);  --card-4-muted: #555555;
-  --card-5-bg: #3d3d3d;  --card-5-ink: #ffffff;                    --card-5-muted: #c4c4c4;
+  --card-4-bg: #d4d4d0;
+  --card-5-bg: #3d3d3d;
 
-  --card-border: #141414;      /* wireframe: visible outline; palettes may set transparent */
-  --card-muted: var(--_muted-on-paper, #6b6b6b);       /* secondary text inside cards (the default, tone-1 card) */
-  --card-3-muted: var(--_muted-on-brand, #b9b9b9);      /* the same text on the tone-3 card — a real colour, like the two above: a theme whose brand is not near-black sets it to reach its contrast (the wireframe's #b9b9b9 = white at 0.7 on #141414, what the opacity gave) */
-  --card-2-muted: var(--_muted-on-tone-2, #5f5f5f);     /* the same text on the tone-2 card — 5.1:1 on its grey (#6b6b6b is 4.3:1, under AA);
-                                  a palette whose tone-2 ground is strong
-                                  sets this to its tone-2 ink — a muted shade cannot reach AA there (clay) */
+  --card-border: #141414;      /* wireframe: visible outline; coloured mode: --on-surface-muted (palette.css). Its edge, or the fill, holds 3:1 on the ground: cardGrounds() */
 
   /* actions */
   --accent: var(--color-brand, #141414);           /* primary CTA fill */
-  --on-accent: var(--color-on-brand, #ffffff);
   --action-bg: var(--color-paper, #ffffff);        /* neutral buttons/chips/inputs */
-  --action-ink: var(--color-ink, #141414);
   --action-border: #141414;
 
   /* signals (chip dots, deltas) */
@@ -218,12 +220,15 @@
   /* THE SIGNAL SET (Lh 2026-09-25; the standard, Lh 2026-10-02): ok (green) · warn (yellow) · error (red) · info (blue) — the same four
      meanings in every project, wireframe included; a theme may retune the shade, never the meaning. Each is dark enough for words and
      edges and comes with an icon and words, never the colour alone. `--signal-*-soft` (below :root) = its light ground. */
-  --signal-warn: #8a6d00;
-  --signal-ok: #2e7d32;
-  --signal-info: #2f5f9e;
+  --signal-warn-onlight: #705903;  /* each onlight shade 4.5:1 on every light ground, tone 4's grey the darkest (#7f6400 was 3.8 there) */
+  --signal-ok-onlight: #27692a;
+  --signal-info-onlight: #2e5c98;
   /* highlights (Lh 2026-09-25): four atmosphere colours a palette may set for decoration — a count, a mark, a chart dot; the wireframe keeps them grey */
   --highlight-1: #3d3d3d;  --highlight-2: #8a8a8a;  --highlight-3: #5f5f5f;  --highlight-4: #b0b0b0;
-  --signal-error: #c62828;  /* something went wrong — a field's edge, the words that say what */
+  --signal-error-onlight: #af2525;  /* something went wrong — a field's edge, the words that say what */
+  /* on a dark ground no shade of one hue holds 4.5:1 on every palette's dark fill and stays itself: a signal there is the ondark ink,
+     and the icon and the words carry the meaning. A palette may give its own (orchard) */
+  --signal-ok-ondark: var(--ink-ondark);  --signal-warn-ondark: var(--ink-ondark);  --signal-error-ondark: var(--ink-ondark);  --signal-info-ondark: var(--ink-ondark);
 
   /* derived tints — read the element's own ink, so they work on any slot */
   --outline: var(--action-border);                                 /* control edges (palette.css softens) */
@@ -252,14 +257,43 @@
    bars take over the page when the app runs edge to edge (viewport-fit=cover: Android Chrome, an iPhone home-screen app).
    PUBLISHED: backgrounds still run to the edge; what the member reads or taps stands clear of them. 0 without cover.
    --_safe-b-open = the bottom inset the keyboard does NOT already cover (a keyboard up hides the gesture bar). */
-/* a signal's SOFT ground: the signal washed 14% into the surface (tone 2's formula) — what a Snackbar stands on. Re-derived where a
-   palette is set, so a palette's own signal shade gives its own soft */
-:root, [data-palette] {
-  --signal-ok-soft: color-mix(in srgb, var(--signal-ok) 14%, var(--surface));
-  --signal-warn-soft: color-mix(in srgb, var(--signal-warn) 14%, var(--surface));
-  --signal-error-soft: color-mix(in srgb, var(--signal-error) 14%, var(--surface));
-  --signal-info-soft: color-mix(in srgb, var(--signal-info) 14%, var(--surface));
+/* THE ROLES OF THE SCREEN AND OF THE PAPER CONTROLS, from their sides. Re-derived wherever a palette or a mode is set, since one may
+   sit on <body>: a custom property is resolved where it is declared. A signal's SOFT ground (what a Snackbar stands on) is its
+   onlight shade washed 14% into the surface (tone 2's formula) */
+:root, [data-palette], [data-mode] {
+  --on-surface: color-mix(in srgb, var(--ink-ondark) calc(var(--surface-dark) * 100%), var(--ink-onlight));
+  --on-surface-muted: color-mix(in srgb, var(--ink-ondark-muted) calc(var(--surface-dark) * 100%), var(--ink-onlight-muted));
+  --action-ink: color-mix(in srgb, var(--ink-ondark) calc(var(--action-dark) * 100%), var(--ink-onlight));
+  --action-muted: color-mix(in srgb, var(--ink-ondark-muted) calc(var(--action-dark) * 100%), var(--ink-onlight-muted));
+  /* the brand as a glyph on the paper (a typed PIN digit, a map's place mark): the brand on a light paper, ondark on a dark one. It stays
+     the paper's on a brand card, where --accent turns to the card's ink */
+  --action-accent: color-mix(in srgb, var(--ink-ondark) calc(var(--action-dark) * 100%), var(--accent));
+  --signal-ok-soft: color-mix(in srgb, var(--signal-ok-onlight) 14%, var(--surface));
+  --signal-warn-soft: color-mix(in srgb, var(--signal-warn-onlight) 14%, var(--surface));
+  --signal-error-soft: color-mix(in srgb, var(--signal-error-onlight) 14%, var(--surface));
+  --signal-info-soft: color-mix(in srgb, var(--signal-info-onlight) 14%, var(--surface));
 }
+/* INK FOLLOWS ITS GROUND (Lh 2026-10-18: "When the ground is light, use onlight; when the ground is dark, use ondark"). A surface
+   says only which side it is, `--dark: 0` (light) or `1` (dark), from its fill's side token above; it does so in its own file
+   (card.css, media.css…) and is named in this list, which gives it the inks every piece on it reads: --card-ink (words, icons,
+   marks, dots: currentColor), --card-muted (secondary words), the four signals, --on-accent (the ink on the accent fill, whose
+   side is --accent-dark) and --accent-ink (the brand as a glyph). A piece with no fill of its own reads only these, so a dark
+   surface turns everything on it to ondark with no rule per piece. A piece with no fill that stands in for a surface (a stat
+   tile) takes its ground's side: `--dark: inherit`. inkGrounds() measures it; docs/reference.md "Ink follows its ground" */
+:where(body, [data-palette], [data-mode], .card, .tile, .modal__drawer, .postcard__front, .postcard__back, .sticky, .post-paper,
+  .float-bar__pill, .snackbar__body, .delta, .track, .tile-badge, .avatar, .bubble__body, .map__hint, .sheet--paper > .sheet__body,
+  .postcard__band, .track__step, .toggle, .chip) {
+  --card-ink: color-mix(in srgb, var(--ink-ondark) calc(var(--dark) * 100%), var(--ink-onlight));
+  --card-muted: color-mix(in srgb, var(--ink-ondark-muted) calc(var(--dark) * 100%), var(--ink-onlight-muted));
+  --on-accent: color-mix(in srgb, var(--ink-ondark) calc(var(--accent-dark) * 100%), var(--ink-onlight));
+  --accent-ink: color-mix(in srgb, var(--ink-ondark) calc(var(--dark) * 100%), var(--accent));
+  --signal-ok: color-mix(in srgb, var(--signal-ok-ondark) calc(var(--dark) * 100%), var(--signal-ok-onlight));
+  --signal-warn: color-mix(in srgb, var(--signal-warn-ondark) calc(var(--dark) * 100%), var(--signal-warn-onlight));
+  --signal-error: color-mix(in srgb, var(--signal-error-ondark) calc(var(--dark) * 100%), var(--signal-error-onlight));
+  --signal-info: color-mix(in srgb, var(--signal-info-ondark) calc(var(--dark) * 100%), var(--signal-info-onlight));
+}
+:where(body, [data-palette], [data-mode]) { --dark: var(--surface-dark); }
+
 :root { --safe-top: calc(env(safe-area-inset-top, 0px) + var(--vv-top, 0px)); /* + the phone's pan while a keyboard is up (cardds.js) */ --safe-bottom: env(safe-area-inset-bottom, 0px); }
 * { --_safe-b-open: max(0px, var(--safe-bottom) - var(--kb, 0px)); }
 

package/dist/actions/Chip.d.ts

@@ -3,7 +3,7 @@ import { type DotTone } from './Dot.js';
 export interface ChipProps extends ComponentProps<'span'> {
     /** filled accent: the selected / live state */
     on?: boolean;
-    /** quiet: an untouched default value — muted words, the thin edge, nothing to find the eye (README rule 13) */
+    /** quiet: an untouched default value — muted words, the thin edge, nothing to find the eye (docs/reference.md rule 13) */
     muted?: boolean;
     /** a leading signal dot: `a` (the accent signal), `b` (the secondary), or one of the signal set — ok · warn · error · info */
     dot?: 'a' | 'b' | DotTone;

package/dist/actions/Dropdown.d.ts

@@ -13,7 +13,7 @@ export interface DropdownProps extends Omit<ComponentProps<'div'>, 'onChange' |
     label?: ReactNode;
     /** right-aligned trigger: the panel grows leftwards (in TopBar actions) */
     end?: boolean;
-    /** quiet: the value is still the default — muted words; drop it once the member picks (README rule 13) */
+    /** quiet: the value is still the default — muted words; drop it once the member picks (docs/reference.md rule 13) */
     muted?: boolean;
     /** MenuItems, each with a `value` */
     children?: ReactNode;