npm - @usableapp/cardds - Versions diffs - 0.1.0 - Mend

@usableapp/cardds 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (170) hide show

package/README.md +562 -0
package/cardds.css +18 -0
package/cardds.js +473 -0
package/css/actions.css +292 -0
package/css/base.css +128 -0
package/css/card.css +283 -0
package/css/choice.css +297 -0
package/css/fonts.css +37 -0
package/css/forms.css +64 -0
package/css/journey.css +61 -0
package/css/layover.css +243 -0
package/css/lists.css +142 -0
package/css/media.css +232 -0
package/css/numbers.css +258 -0
package/css/palette.css +112 -0
package/css/people.css +79 -0
package/css/sheet.css +295 -0
package/css/stack.css +262 -0
package/css/step.css +71 -0
package/css/tokens.css +177 -0
package/dist/actions/Btn.d.ts +311 -0
package/dist/actions/Btn.js +14 -0
package/dist/actions/BtnRow.d.ts +5 -0
package/dist/actions/BtnRow.js +6 -0
package/dist/actions/Chip.d.ts +328 -0
package/dist/actions/Chip.js +25 -0
package/dist/actions/Dot.d.ts +7 -0
package/dist/actions/Dot.js +6 -0
package/dist/actions/Dropdown.d.ts +34 -0
package/dist/actions/Dropdown.js +19 -0
package/dist/actions/Fab.d.ts +9 -0
package/dist/actions/Fab.js +7 -0
package/dist/actions/IconBtn.d.ts +308 -0
package/dist/actions/IconBtn.js +8 -0
package/dist/actions/Link.d.ts +301 -0
package/dist/actions/Link.js +8 -0
package/dist/actions/Segment.d.ts +11 -0
package/dist/actions/Segment.js +10 -0
package/dist/cardds.css +3068 -0
package/dist/cards/Card.d.ts +310 -0
package/dist/cards/Card.js +14 -0
package/dist/cards/CardFoot.d.ts +5 -0
package/dist/cards/CardFoot.js +6 -0
package/dist/cards/CardHead.d.ts +21 -0
package/dist/cards/CardHead.js +11 -0
package/dist/cards/CardParts.d.ts +25 -0
package/dist/cards/CardParts.js +26 -0
package/dist/cards/Placeholder.d.ts +9 -0
package/dist/cards/Placeholder.js +6 -0
package/dist/cards/Stat.d.ts +17 -0
package/dist/cards/Stat.js +14 -0
package/dist/choice/Calendar.d.ts +23 -0
package/dist/choice/Calendar.js +7 -0
package/dist/choice/Check.d.ts +14 -0
package/dist/choice/Check.js +10 -0
package/dist/choice/DayStrip.d.ts +16 -0
package/dist/choice/DayStrip.js +10 -0
package/dist/choice/Mood.d.ts +11 -0
package/dist/choice/Mood.js +6 -0
package/dist/choice/Slider.d.ts +11 -0
package/dist/choice/Slider.js +14 -0
package/dist/cx.d.ts +2 -0
package/dist/cx.js +2 -0
package/dist/forms/AddRow.d.ts +5 -0
package/dist/forms/AddRow.js +7 -0
package/dist/forms/Composer.d.ts +13 -0
package/dist/forms/Composer.js +6 -0
package/dist/forms/Field.d.ts +17 -0
package/dist/forms/Field.js +10 -0
package/dist/forms/FileBtn.d.ts +18 -0
package/dist/forms/FileBtn.js +10 -0
package/dist/forms/Pin.d.ts +19 -0
package/dist/forms/Pin.js +27 -0
package/dist/index.d.ts +72 -0
package/dist/index.js +75 -0
package/dist/journey/NoteRow.d.ts +7 -0
package/dist/journey/NoteRow.js +7 -0
package/dist/journey/Route.d.ts +18 -0
package/dist/journey/Route.js +8 -0
package/dist/journey/TileBadge.d.ts +15 -0
package/dist/journey/TileBadge.js +6 -0
package/dist/layover/Banner.d.ts +9 -0
package/dist/layover/Banner.js +6 -0
package/dist/layover/Callout.d.ts +10 -0
package/dist/layover/Callout.js +6 -0
package/dist/layover/Deck.d.ts +9 -0
package/dist/layover/Deck.js +10 -0
package/dist/lists/Kv.d.ts +27 -0
package/dist/lists/Kv.js +19 -0
package/dist/lists/Legend.d.ts +11 -0
package/dist/lists/Legend.js +11 -0
package/dist/lists/Row.d.ts +319 -0
package/dist/lists/Row.js +17 -0
package/dist/lists/Timeline.d.ts +11 -0
package/dist/lists/Timeline.js +10 -0
package/dist/media/MapArea.d.ts +20 -0
package/dist/media/MapArea.js +11 -0
package/dist/media/Mosaic.d.ts +11 -0
package/dist/media/Mosaic.js +10 -0
package/dist/media/Postcard.d.ts +20 -0
package/dist/media/Postcard.js +10 -0
package/dist/media/Quote.d.ts +11 -0
package/dist/media/Quote.js +6 -0
package/dist/media/Tile.d.ts +320 -0
package/dist/media/Tile.js +16 -0
package/dist/numbers/Badge.d.ts +7 -0
package/dist/numbers/Badge.js +6 -0
package/dist/numbers/Band.d.ts +16 -0
package/dist/numbers/Band.js +10 -0
package/dist/numbers/Bars.d.ts +14 -0
package/dist/numbers/Bars.js +10 -0
package/dist/numbers/DotGrid.d.ts +12 -0
package/dist/numbers/DotGrid.js +6 -0
package/dist/numbers/Picker.d.ts +13 -0
package/dist/numbers/Picker.js +18 -0
package/dist/numbers/Ring.d.ts +15 -0
package/dist/numbers/Ring.js +6 -0
package/dist/numbers/Track.d.ts +12 -0
package/dist/numbers/Track.js +10 -0
package/dist/people/Avatar.d.ts +314 -0
package/dist/people/Avatar.js +13 -0
package/dist/people/AvatarPick.d.ts +18 -0
package/dist/people/AvatarPick.js +10 -0
package/dist/scaffold/ActionBar.d.ts +21 -0
package/dist/scaffold/ActionBar.js +16 -0
package/dist/scaffold/AppBar.d.ts +18 -0
package/dist/scaffold/AppBar.js +10 -0
package/dist/scaffold/Centre.d.ts +30 -0
package/dist/scaffold/Centre.js +41 -0
package/dist/scaffold/EmptyState.d.ts +14 -0
package/dist/scaffold/EmptyState.js +8 -0
package/dist/scaffold/FilterRow.d.ts +5 -0
package/dist/scaffold/FilterRow.js +6 -0
package/dist/scaffold/FloatBar.d.ts +310 -0
package/dist/scaffold/FloatBar.js +15 -0
package/dist/scaffold/PagerAt.d.ts +11 -0
package/dist/scaffold/PagerAt.js +6 -0
package/dist/scaffold/Screen.d.ts +299 -0
package/dist/scaffold/Screen.js +11 -0
package/dist/scaffold/Section.d.ts +12 -0
package/dist/scaffold/Section.js +13 -0
package/dist/scaffold/TopBar.d.ts +15 -0
package/dist/scaffold/TopBar.js +9 -0
package/dist/sheets/CardBack.d.ts +7 -0
package/dist/sheets/CardBack.js +7 -0
package/dist/sheets/Drawer.d.ts +17 -0
package/dist/sheets/Drawer.js +16 -0
package/dist/sheets/Sheet.d.ts +21 -0
package/dist/sheets/Sheet.js +13 -0
package/dist/sheets/SheetBody.d.ts +5 -0
package/dist/sheets/SheetBody.js +6 -0
package/dist/sheets/SheetHead.d.ts +13 -0
package/dist/sheets/SheetHead.js +6 -0
package/dist/sheets/SheetStack.d.ts +21 -0
package/dist/sheets/SheetStack.js +14 -0
package/dist/sheets/SheetStage.d.ts +20 -0
package/dist/sheets/SheetStage.js +11 -0
package/dist/sheets/Step.d.ts +15 -0
package/dist/sheets/Step.js +15 -0
package/dist/type/Icon.d.ts +16 -0
package/dist/type/Icon.js +12 -0
package/dist/type/Text.d.ts +302 -0
package/dist/type/Text.js +16 -0
package/dist/type/icons.d.ts +6 -0
package/dist/type/icons.js +2 -0
package/fonts/LICENSES.md +44 -0
package/fonts/fc-pride-medium.otf +0 -0
package/fonts/pk-nonthaburi-demo.ttf +0 -0
package/icons.svg +61 -0
package/package.json +62 -0

package/README.md ADDED Viewed

@@ -0,0 +1,562 @@
+# cardds
+Card-first mobile design system, **React-first**: `src/` is the component
+library — one thin component per pattern, emitting exactly the markup the CSS
+documents — and `app/` is the Commons Time Bank PWA built from it (the twelve
+screens of the Claude Design handoff, as real routes). The CSS (`css/*.css`)
+stays the only truth: a component never styles anything, it only picks classes
+from props. The CSS also works alone, with no build, for a host that wants
+class names rather than components; `demo/` keeps the CSS spec pages the
+acceptance tests drive.
+Repo: **https://github.com/everysundays/cardds** (private — this is the
+source of truth; every consuming project vendors a copy from here, never
+the other way round).
+**Wireframe by default** — grayscale with visible outlines. Color is opt-in,
+lives only in one file, applied with one attribute. Two faces ship with it
+(`fonts/`, `css/fonts.css`): PK Nonthaburi for text, FC Pride for headings
+and big numbers — both Thai + Latin, both single-weight demo/non-commercial
+licences (`fonts/LICENSES.md`).
+## Use
+```bash
+npm install
+npm run dev          # the app (app/) on http://localhost:5174 — the twelve screens, /screens lists them
+npm run build        # the library: icons → src/type/icons.ts · tsc → dist/ (ESM + .d.ts) · dist/cardds.css (flattened)
+npm run build:app    # the PWA → app/dist (manifest, service worker, icons)
+npm test             # Playwright: the step/sheet/centre geometry on demo/, the app's screens and the four handoff upgrades
+```
+```tsx
+import { Screen, TopBar, Step, StepCard, Sheet, SheetBody, CardHead, Field, Pin, ActionBar, Btn } from 'cardds';
+import 'cardds/dist/cardds.css';   // or cardds/cardds.css with the css/ folder beside it
+```
+`src/index.ts` imports `cardds.js` for its side effects, so a React host gets
+the behaviours for free: the `.sheet` handle (tap, drag, keyboard) with the
+focus and on-screen-keyboard raises, `.sheet-stack--tap` opening and closing,
+the `.pin` auto-advance (a digit moves on, Backspace moves back, a paste fills
+the code), a card heading that needs more than two lines squeezing its type
+(see *Anatomy*), and the `.dropdown` writing its picked value back. `Icon`
+inlines the 56 symbols of `icons.svg` at build time, so no sprite file ships.
+**The app** (`app/`): Vite + React Router, `cardds` aliased to `src/` so the
+app and the package share one truth with no build between them. Twelve
+screens from `docs/handoff/commons-time-bank-SPEC.md` — welcome, install (the
+real `beforeinstallprompt`), verify phone, home, browse, detail, matches,
+empty, the two menus (sheet stacks), post, profile. `app/README.md` records
+what the port changed against the mockups and why.
+**CSS only** (no React, no build):
+```html
+<link rel="stylesheet" href="cardds.css">
+<script src="cardds.js" defer></script>   <!-- optional: the behaviours above -->
+<html data-palette="clay">                <!-- omit for b&w wireframe -->
+```
+Everything renders without `cardds.js`: a dropdown still opens (a native
+popover) but won't update its label, a stack still displays but won't open, a
+sheet renders every state but only moves when a class changes, a pin is six
+plain inputs.
+`demo/index.html` is the CSS spec — every component in one page, palette
+switcher top-right. `demo/sheet.html` — the single sheet at phone height: a step
+that reads, a step that acts, the overlay stage; `demo/stack.html` — the sheet
+stack: the menu and the display variant; `demo/elements.html` — in-card
+elements and layovers grown from the timebanking board. Serve the repo root
+(`python3 -m http.server 4174`) and open `/demo/`. These pages are the fixtures
+of `tests/step.spec.js` and `tests/centre.spec.js`; `tests/app.spec.js` drives
+the app. Nothing here is verified by eye.
+### In another project
+**React (the main way, 2026-09-16):** the package is `@usableapp/cardds` on npm
+(published from a `v*` tag by `.github/workflows/publish.yml`, trusted publishing).
+```bash
+npm i @usableapp/cardds
+```
+```tsx
+import { Card, CardHead, Btn } from '@usableapp/cardds';
+import '@usableapp/cardds/dist/cardds.css';   // the CSS, fonts resolve from the package
+```
+Browse what exists at `npm run dev` → `/gallery` in this repo (every component, every story, searchable).
+**CSS only:** there's no build and no dependencies, so installing is cloning once, then
+copying the static files into your project — never edit the clone, never
+fork the CSS:
+```bash
+# once, wherever you keep it (~/Sites/cardds is the convention on this machine)
+git clone git@github.com:everysundays/cardds.git ~/Sites/cardds
+# to update it later
+git -C ~/Sites/cardds pull
+# then vendor the static files into the consuming project
+cp -R ~/Sites/cardds/css ~/Sites/cardds/fonts ~/Sites/cardds/cardds.css \
+      ~/Sites/cardds/cardds.js ~/Sites/cardds/icons.svg \
+      ./assets/
+```
+`cardds.css` is just the import bundle for `css/*.css`, so keep the `css/`
+folder next to it, and `fonts/` beside that (`css/fonts.css` reaches the faces
+as `../fonts/`). `icons.svg` is referenced by path from your markup
+(`<use href="icons.svg#bell">`), so put it where those references resolve.
+Then follow the rules below — the short version is: tune `palette.css` and
+nothing else, and never write a raw hex or px in a component.
+The repo is private, so cloning needs an account with access (`everysundays`
+on GitHub) — set that up as an SSH host alias if you already use a different
+account for `git@github.com` day to day, the way this machine's `~/.ssh/config`
+does it for other `everysundays` repos.
+**Recording what you copied matters.** A vendored copy with no record of which
+commit it came from can't be told apart from a fork. timebank's
+`scripts/cardds-vendor.mjs` is the reference: `npm run cardds:sync` copies the
+files above from a local checkout (`CARDDS_SRC`, default `~/Sites/cardds`) and
+writes `VENDORED.json` — commit hash, date, a sha256 per file — so
+`npm run check:cardds` can catch a hand edit or a stale copy. `git pull` that
+checkout before syncing to pick up what's been pushed here.
+Working with Claude in another project? The `/cardds` skill
+(`~/.claude/skills/cardds/`) carries the install and the contract, and points
+back here. It is deliberately thin — **this repo stays the source of truth**,
+so new components and rule changes go here, and the skill only gets updated
+if the contract itself changes.
+### React adapter — how a component is written
+`src/<group>/<Name>.tsx`, one export per class family; sub-parts are their own
+components (`CardHead`, `KvRow`, `TrackStep`, `SheetBody`). A component
+chooses classes from props (`tone`, `state`, `primary`, `sm`…) and lays the
+contract's children in order — nothing else. Behaviour lives in `cardds.js`
+(delegated, class toggles) and a component only surfaces it: `Pin` listens
+for `cardds:pin` and calls `onChange(code, complete)`; `Sheet` sets the state
+class, `cardds.js` moves it. Never fix a look in a wrapper: fix the CSS, the
+wrapper follows. **Claude Design** builds with these components through
+`/design-sync` (`.design-sync/`: the sync config, the authored preview
+stories, the conventions the design agent reads) — a new component needs a
+preview story there.
+## Sheet stack markup
+The sheet stack (`.sheet-stack`, `stack.css` — the menu, see *Anatomy*) is the
+one component whose markup has rules, since a sheet's place in the stack comes
+from its position among its siblings. A stacked sheet is written as a `.card`:
+the card is the material, the sheet is what it is in the stack.
+```html
+<div class="sheet-stack sheet-stack--tap">   <!-- drop --tap for a static stack -->
+  <article class="card card--2">
+    <div class="card__head">
+      <button class="icon-btn icon-btn--sm card__back" aria-label="Back">…</button>
+      <h2 class="t-h2 t-caps">Shopping</h2>
+      <span class="icon-row">…</span>       <!-- optional trailing icons -->
+    </div>
+    …the sheet's own content…
+  </article>
+  <article class="card card--3">…</article>
+  <article class="card">…</article>        <!-- last = the front sheet -->
+</div>
+```
+- **Sheets must be direct children** of `.sheet-stack`. Order is the stack
+  order: first = back, last = the front sheet that shows its full content.
+- **`--closed`** (with `--tap`): nothing open on arrival — every sheet, the
+  front one too, peeks at the stack's bottom; the headroom above is the base's.
+  An optional `<div class="sheet-stack__base">` — written AFTER the sheets, so
+  it takes no sheet slot — is what the base shows there, behind every sheet.
+  A tap opens any sheet over it; back drops it home.
+- **Five sheets max.** Slots are declared per `:nth-child` in `stack.css`; a
+  sixth would render at slot 0, on top of the first.
+- **Every head needs its own `.card__back`** if the stack is `--tap`. It stays
+  hidden until that sheet is open, then slides into a reserved header slot.
+- **No ids, no wiring.** `cardds.js` finds any `.sheet-stack--tap` on the page.
+- **`.card-stack` is gone.** That was this component's first name and the wrong
+  one — the members are sheets and the stack is the menu, not a list of cards.
+  Never bring it back, not even as an alias.
+## Step markup
+A step is one screen, one task (see *Anatomy*). It is the other component
+whose markup has rules, because the sheet's box is the step itself:
+```html
+<!-- reads: card only -->
+<section class="step">
+  <article class="card step__card">
+    <div class="card__head"><div><span class="t-overline t-muted">ขั้นที่ 2 จาก 4</span><h2 class="t-h2">…</h2></div></div>
+    <p class="t-body">…</p>
+  </article>
+</section>
+<div class="action-bar action-bar--pager">…</div>
+<!-- acts: card + sheet -->
+<section class="step">
+  <article class="card step__card">…the words…</article>
+  <article class="card sheet sheet--half" data-sheet-states="peek half full">
+    <button class="sheet__handle" type="button" aria-label="ปรับความสูง"></button>
+    <div class="card__head"><h2 class="t-h2">…</h2><span class="chip">…</span></div>
+    <div class="sheet__body">
+      …cardds controls (.field / .pin / .composer / .rows + .check / .segment /
+      .chip-grid), or small content cards (.card--sm)…
+    </div>
+  </article>
+</section>
+<div class="action-bar">…one wide button…</div>
+```
+- **`.step` needs a bounded column**: a direct child of `.screen--fill`, or
+  of an app section with a definite height. It is a flex child that fills the
+  column between the top bar's reserve and the bar's, and clips at its own
+  bottom edge — which is what makes the sheet stop above the bar. In a plain
+  scrolling `.screen` it has nothing to fill.
+- **The sheet is full-width; the card keeps the inset.** The step bleeds to
+  the screen's edges (reading `--screen-pad`, as `.sheet-stack` does) and the
+  card takes the inset back as its side margins — so the card and the bar's
+  buttons stand on the inset line, and the sheet runs edge to edge like the
+  bar and like a sheet in a `.sheet-stage`.
+- **`.step__card` first, `.sheet` last.** The card carries the step's words
+  and is a normal card: head · content · optional foot. The sheet is
+  **handle · head · body**: the handle, then a `.card__head` title row (that
+  row is what `peek` shows — heading left, the contextual thing right), then
+  `.sheet__body` with what the member acts on. The handle and the head are
+  pinned; the body is the one thing that scrolls, to the card's own edges. 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
+  moves inside the step, above the card: `.topbar + .step` cancels the
+  screen's gap (`--screen-gap`), `.appbar + .step` cancels the reserve's
+  breathing (`--header-gap`), and the card takes that room as its lead. A
+  step that follows anything else keeps the screen's gap, and the sheet
+  stops under that thing.
+- **The bar is outside the step**, after it. `.step` reads the bar's room
+  from `--bar-reserve`; any parent that hosts the `.action-bar` counts
+  (`<body>`, an app shell, a demo frame).
+- **A sheet inside a step never carries the step's action.** The bar is the
+  one move. A sheet gets its own buttons only on a screen that has no bar —
+  the map sheet in `sheet.html`, whose "Directions" is that screen's move.
+- **Never write a sheet's height, and never a `.sheet-stage` inside a step.**
+  State is a class (`sheet--peek` / `--half` / `--full`); the sheet is always
+  the step's full height and only slides. `carddsSheetSet(sheet, state)` is
+  the one way to change it from script, so listeners hear `cardds:sheet`.
+## Centred card markup
+One card at the human centre — the introduction screens, and any screen with
+one thing to read and one move. The heading above, the bar below, the card
+between at 40% down the screen (see *Anatomy*, "Where the centre is"):
+```html
+<div class="screen screen--fill">
+  <header class="topbar"><h1 class="t-h1">ธนาคารเวลายินดีต้อนรับ</h1></header>
+  <article class="card card--centre">
+    <div class="card__head"><div><span class="t-overline t-muted">ขั้นที่ 1 จาก 4</span><h2 class="t-h2">ปรับขนาดตัวหนังสือ</h2></div></div>
+    <p class="t-body">…</p>
+  </article>
+</div>
+<div class="action-bar action-bar--tiers">
+  <div class="action-bar__tier"><label class="slider"><input class="slider__range" type="range" min="100" max="160" step="15" aria-label="ขนาดตัวหนังสือ"></label></div>
+  <div class="action-bar__tier action-bar__tier--pager">
+    <button class="icon-btn" aria-label="ย้อนกลับ">…</button>
+    <button class="icon-btn icon-btn--invert" aria-label="ถัดไป">…</button>
+  </div>
+</div>
+```
+- **The card floats in the fill screen** (`.screen--fill` is its box), hugs its
+  words, keeps the screen's inset, and is capped so it never reaches the title
+  bar above it nor the bar's room below — past that it scrolls inside. Never
+  give it a height; never move it with a margin. The cap is twice the room
+  above the centre (2 × (40% − the title bar)): a card taller than that is
+  not a centred card — it is a plain scrolling `.screen` (the detail view).
+- **A small group at the same centre** — an empty state; a card with its quiet
+  second button and the pager dots under it; a deck with its two round
+  buttons — is `.screen__centre` (React: `Centre`), a block in the fill
+  screen after the topbar. Same placement and cap; it runs edge to edge with
+  the inset as padding, so a deck's fanned cards may overhang and clip at the
+  screen's edges (the fold visual, not a bug), and stacks its children at the
+  screen's gap. Never hand-lay `top: 40%` on a screen.
+- **The bar is outside, as always.** Plain `.action-bar` for one move; with a
+  control that belongs to the screen (a slider), `.action-bar--tiers` stacks a
+  control tier above the buttons and publishes the taller reserve
+  (`--bar-reserve`) from whatever parent hosts the bar.
+- **The round pager** is `.action-bar--pager` (or an `.action-bar__tier--pager`)
+  holding two `.icon-btn`s and nothing else: they stand at the two edges. The
+  step that commits still goes back to one wide button (rule 3).
+## Files
+| file | what | touch it? |
+|---|---|---|
+| `css/fonts.css` + `fonts/` | the two `@font-face`s: PK Nonthaburi (body, `--font-ui`), FC Pride (display, `--font-display`); the font files and their licences | when swapping a face |
+| `css/tokens.css` | spacing, radius, type levels, motion (`--motion-sheet`), the human centre (`--screen-centre`), grayscale role defaults; registers the two sheet tokens (`--sheet-peek`, `--sheet-half`) so script can read them resolved | rarely |
+| `css/palette.css` | **color settings — palettes as role-token overrides** | yes, this one |
+| `css/base.css` | reset, surface, typography classes, `.section` | rarely |
+| `css/card.css` | `.card` + its skeleton (`.card__head` / content / `.card__foot`, heading squeeze), `.card-list`, `.card--row`, `.icon-row`, stats, `.card--centre` (one card at the human centre of a fill screen) and `.screen__centre` (a small group there) | when adding variants |
+| `css/stack.css` | **sheet stack** — `.sheet-stack`: the menu, sheets stacked (heads peek, up to 5; `--tap` tap-to-open, the back button dissolves in; `--closed` nothing open, heads at the bottom, the base above (`.sheet-stack__base`); `--display` the title is the peek, `--fanned` wider peeks); always edge to edge; a stacked sheet is a `.card` | rarely |
+| `css/sheet.css` | **sheet single** — `.sheet`: a card as bottom sheet, full height always, a state is how far it slid: `--peek` / `--half` / `--full` (translate only); handle · head · `.sheet__body` (the head pinned, the body scrolls); `.sheet-stage` (overlay stage: map sheet, a `__hero` — one thing centred in the band a half sheet leaves open, `--dim`, `--raised`, ask drawer) | when adding states |
+| `css/step.css` | `.step` — one screen, one task: `.step__card` (reads) + optional `.sheet` (acts), the bar's room, the keyboard's room | rarely |
+| `css/forms.css` | `.field` (outlined input, label = placeholder), `.add-row` | when adding controls |
+| `css/journey.css` | `.route`, `.tile-badge`, `.note-row` — trip/status primitives | when adding variants |
+| `css/actions.css` | topbar, chips, buttons (`.btn--xl`), `.dropdown` (the standard select: pill + `.menu` popover), `.action-bar` (+ `--pager` for previous/next, as labels or as two round buttons; `--tiers` for a control row above the buttons), `.fab` | when adding actions |
+| `css/numbers.css` | `.ring` gauge, `.track` steps, `.card--band` + `.band-stack`, `.dotgrid`, `.picker`, `.badge`, `.bars` | big numbers |
+| `css/people.css` | `.avatar` (sm/lg/xl, outline, add, on, halo), `.avatar-stack`, `.avatar-pick` | people |
+| `css/choice.css` | `.check`, `.toggle`, `.chip--toggle`, `.chip-grid` + `.chip--pick`, `.day-strip`, `.calendar`, `.mood`, `.pin`, `.composer`, `.slider` | choice controls |
+| `css/lists.css` | `.row` / `.rows` (frameless rows in a card), `.kv`, `.kv-grid`, `.timeline`, `.legend`, `.link` | lists inside cards |
+| `css/media.css` | `.card--cover`, `.quote`, `.tile-grid` + `.tile`, `.card--fold`, `.mosaic`, `.wave` | media & display |
+| `css/layover.css` | `.drawer` (ask), `.menu` (popover), `.banner` (details), `.float-bar`, `.callout`, `.chip--bubble`, `.deck` | cards over content |
+| `icons.svg` | Lucide sprite (ISC), 56 minimal stroke icons | add symbols as needed |
+| `src/` → `dist/` | the React library: `src/<group>/<Name>.tsx`, one thin component per pattern, JSDoc = the rule; built by `npm run build` (tsc) into `dist/` with `.d.ts`; `src/type/icons.ts` is generated from `icons.svg` | when adding a component |
+| `app/` | the Commons Time Bank PWA: `app/src/screens/*.tsx` (the twelve screens), `App.tsx` (the routes), `install.ts` (the install prompt), `public/` (manifest, `sw.js`, icons); `npm run dev` / `build:app` | the product |
+| `demo/` | the CSS spec pages (`index`, `sheet`, `stack`, `elements`) — CSS only, and the fixtures of the geometry tests | when the CSS contract changes |
+| `docs/handoff/` | the Claude Design handoff spec the app was ported from | reference |
+| `scripts/` | `build-icons.mjs` (icons.svg → `src/type/icons.ts`), `flatten-css.mjs` (`cardds.css` + imports → `dist/cardds.css`) | rarely |
+| `docs/guides/` | `building-with-cardds.md` — the anatomy, the step, the two sheet systems and the vocabulary in React terms; shipped to Claude Design as its guidelines | when the contract changes |
+| `cardds.js` | the behaviours (delegated, class/property toggles only — everything renders without it): dropdown value sync, `.sheet-stack--tap` open/close (tolerates one wrapper per sheet; close reads the tapped sheet), `.pin` auto-advance / Backspace / paste + `cardds:pin`, card-heading squeeze (`--squeeze`), the sheet handle (tap / drag-snap / Enter / Space), the focus and keyboard raises (`--kb`), `cardds:sheet` | rarely |
+## Anatomy — base, menus, content, and the card skeleton
+Every screen is the same four things, and every card the same three:
+- A screen is **base, top menu, bottom menu, content**. The base is the
+  surface; the menus are the chrome above and below (`.topbar` / `.appbar`,
+  `.action-bar` / `.float-bar`); content is everything between.
+- Content has three homes: **on the base**, **in a card**, **in a bottom
+  sheet**. Content normally comes in cards; static data (a blurb, a legal
+  note, help steps) may sit on the base directly.
+- **A card is head · content · foot.**
+  - **Head** (`.card__head`): the heading on the left; hints, actions or a
+    more-menu — the contextual info — at the far right. Two lines is the
+    heading's budget; with nothing at the far right it runs all the way
+    across. Hard maximum three lines: when the words need more than two,
+    the type squeezes to fit (`cardds.js` sets `--squeeze`, `card.css`
+    multiplies the level's `--fs-self` by it, and clamps at three).
+  - **Content**: whatever the card frames — rows, key-values, a gauge, a
+    paragraph. Frameless, per rule 9.
+  - **Foot** (`.card__foot`): the card's action buttons on one line. One
+    button takes the width; up to four share it in even parts; from three
+    on they drop their side padding so the labels keep the room.
+- A page with **one feature and one CTA** (an install page, a single
+  decision) may be contained in one card: head, the pitch, foot.
+- **A bottom sheet holds what the member acts on** — controls, or small
+  content cards to pick from or read more — and it opens to the full height
+  of its box. **Cards are content the system offers**: the words, the
+  explanation, the thing to read. Do not put a form in a card when a sheet
+  would do, and do not put the step's explanation in a sheet.
+- **Two sheet systems, one material.** *Sheet single* (`.sheet`, `sheet.css`)
+  is ONE sheet the member acts in, whatever it holds: a short entry in front
+  of a step's card, a place on a map, a payment on a dim page — in a `.step`
+  or a `.sheet-stage`, and its state is how far it slid (peek / half / full).
+  *Sheet stack* (`.sheet-stack`, `stack.css`) is MANY sheets, each a main
+  section of the app, stacked like paper at the middle of the home screen:
+  the menu. Heads peek, a tap brings one sheet to the front, back returns it;
+  each sheet is the metaphor for the section it opens. Both are cut from the
+  same material — a stacked sheet is written as a `.card`, and the single
+  sheet is `.card.sheet` — and both obey rule 8: rigid, full height, moved
+  by `translate` only. (The stack was first named "card stack": wrong, and
+  retired.) Demos: `sheet.html`, `stack.html`.
+- **A step is one screen, one task: `.step`.** What the member reads is a
+  card (`.step__card`); what the member does, if the step asks for it, is a
+  `.sheet` in front of it; the screen's one move is `.action-bar`, outside
+  the step, below it. A step where the member only READS is the card alone.
+  A step where the member ACTS (types, picks, shoots a photo, records) adds
+  the sheet: peek shows its handle and title row, half shows half of it,
+  full slides up until its top edge touches the top bar — and at every one
+  of those it stops above the bottom bar, because the step is the box it
+  slides in: it starts where the top bar ends and ends where the bar's room
+  begins. Nobody lays a step out by hand and nobody writes a
+  sheet's height. In short: **member acts → card + sheet, member reads →
+  card.** Markup: *Step markup*. Demo: `sheet.html`, `elements.html` #ask,
+  `index.html` "step".
+- **Where the centre is.** To the person holding a phone, the bottom fifth of
+  the screen is the thumb's — the bar, the controls — so what is meant to be
+  read sits at the middle of the four fifths above it: **the human centre is
+  40% down the screen, not 50%** (`--screen-centre`, Lh 2026-09-10). A screen
+  with one card and nothing else to read puts it there (`.card--centre`, the
+  introduction screens); a splash puts its mark there.
+Demo: the *skeleton* block at the top of `elements.html`.
+## Rules of the system
+1. **One card = one boundary.** A card frames one thing: a category, a stat
+   group, a list row. Tone slots: `.card` (card-1), `.card--2`, `.card--3`.
+2. **Sections are not cards.** Page sections = frameless on-surface content
+   (`.section`) + a lone/packed CTA (`.cta-pack`).
+3. **Surrounding UI is separate.** `.topbar`, `.filter-row`, `.chip-row`,
+   `.action-bar` live outside cards, above/below. The bottom bar has two
+   arrangements and they mean different things: the default pack (one wide
+   CTA, optional round icon) is **one action** on this screen, and
+   `.action-bar--pager` (two equal buttons at the edges, indicator between)
+   is **a sequence you can walk both ways**. A wide button next to a small
+   round one reads as an action plus an afterthought — wrong whenever back
+   and next are peers. The step that commits goes back to the default pack.
+4. **Components reference role tokens only** (`--surface`, `--card-1-bg`,
+   `--accent`…), never hex. Derived tints are tokens too (`--outline`,
+   `--hairline`, `--ink-tint`, `--ink-rail`, `--accent-soft`, `--scrim`), and
+   masks use `currentColor` as "opaque". So palettes swap freely.
+5. **`.screen` carries the horizontal inset and nothing vertical.** The inset
+   is `--screen-pad`; cards and on-surface UI sit flush inside it, with no
+   per-component side padding. Top and bottom are zero: vertical room only
+   exists as a reserve for something fixed parked over the screen, so each bar
+   adds its own — `.appbar` the top (`.screen:has(> .appbar)`), `.action-bar`
+   and `.float-bar` the bottom, each from its own height token. Whatever
+   parent hosts the bar counts (`:has(> .action-bar) .screen`): `<body>` or an
+   app shell alike. A page with no bars needs no override, and `.screen--fill`
+   is excluded from the bottom reserves — there a `.step` carries the bar's
+   room itself, as a bottom margin, reading the same `--bar-reserve`. The
+   reserves use the nominal control height, so a bar whose button wraps to two
+   lines can still overlap the last line of content.
+   **Padding is published, not copied.** `.screen` sets `--screen-pad` and
+   `--screen-gap`, its appbar reserve sets `--header-gap`, and `.card` sets
+   `--card-pad` and `--card-gap`; anything that has to cancel a container's
+   padding or gap reads the token rather than repeating its value. `.sheet-stack` uses it to
+   break out full-bleed when the column touches the viewport edges (≤27em /
+   432px), and `.bleed` uses it for a scrolling track inside a card:
+   ```html
+   <div class="avatar-pick bleed">…</div>
+   ```
+   The track runs to the card's edges so it reads as scrollable, while the
+   first and last item stay on the same line as the heading. Works for any
+   horizontal strip — `.chip-row`, a tile grid — in any container that
+   publishes `--card-pad`.
+6. **The sheet stack is the menu, and a sheet is rigid material.**
+   `.sheet-stack` (`stack.css`) sheets are tall: heads peek (`--stack-step`,
+   up to 5 layers), each head = title + `.icon-row` functions (head text =
+   icon height, 28px). On a `.screen--fill` the stack stretches and bleeds
+   off the bottom edge — bottom corners square. Markup rules: see *Sheet
+   stack markup* above; the two sheet systems: *Anatomy*.
+   `.screen--fill` is exactly one phone height — a height, not a minimum, so
+   a `.step` inside it has a bound to fill and its card and sheet scroll inside
+   rather than growing the page — and it clips (`overflow: clip`, never
+   `hidden`): a clipped box is not a scroll container, so nothing, not even
+   the browser revealing a focused field, can shift the screen up.
+   In a `.sheet-stack--tap`, a sheet is rigid material — it moves in, moves
+   out, or is covered, but **never changes size**. Every sheet is the same
+   full height, set once; a peek is not a short sheet, it's a full sheet the
+   next one covers. So `translate` is the only animated property, and
+   **z-index is the resting `--level` order and is never touched** — because
+   whatever sits in front of the tapped card is exactly what has to leave.
+   Opening slides the tapped card up by its own `--slot` × `--stack-step`;
+   cards after it move out below (`.is-after`); cards before it tuck one
+   step down, staggered nearest-first via `--stagger` (`.is-before`), and
+   get covered. Closing reverses it in two phases: the after-pack returns
+   while the card drops into its slot, then the before-pack slides back up
+   from behind. Slots, offsets and paint order are all CSS `:nth-child`, so
+   a stack renders correctly with no script; `cardds.js` only toggles the
+   state classes. Don't reintroduce height, `display` or z-index switching
+   here — every past bug in this animation came from exactly that.
+7. **Everything shrinks to 320px.** `.screen > *`, `.card` and `.card > *`
+   carry `min-width: 0`, so no child's min-content (an input, a fixed row)
+   can widen a card's grid track past its padding; topbar titles ellipsize;
+   segment items share width. Never give a component a fixed width that can
+   beat the viewport — let it `flex: 1` up to a `max-width` token instead.
+8. **A single sheet is rigid material, like a sheet in the stack.** It is always the full
+   height of the box that holds it (`inset: 0`, set once, never written
+   again) and a state is nothing but how far that full card slid:
+   `sheet--full` slid nowhere, `sheet--half` slid down by `--sheet-half`
+   (50% of itself), `sheet--peek` slid down until only `--sheet-peek` shows —
+   the handle and the title row. `translate` is the only animated property
+   (`--motion-sheet`), and nothing toggles height, display or z-index for a
+   state — the stack's rule, inherited. The box clips whatever slid below its
+   bottom edge, so a sheet at any height is still a card: rounded top, a
+   straight cut at the box's edge — and its shape is handle · head · body:
+   the handle and the title row are pinned, `.sheet__body` scrolls beneath
+   them, and the body's `scroll-padding-bottom` is the slid-under part (in
+   the sheet's own container units, `--_cover`), so a focused control is
+   revealed above the cut, not under it. `--sheet-half` is a share of the
+   sheet's height (`0.5`), one number serving both the translate and that
+   padding. Two boxes hold sheets and the states
+   mean the same in both: `.step` (an app screen, the bar outside — Anatomy)
+   and `.sheet-stage` (a page-level overlay: a sheet over a map, the dim page
+   sheet `--dim` + `--raised`, the ask drawer `--ask` + `.lift` + `.drawer`).
+   A stage keeps the top bar's line free (`--_top`), so `--full` stops under
+   `--header-h` and keeps its corners. Both sheet tokens are published — a
+   sheet with a taller head retunes `--sheet-peek` — and registered in
+   `tokens.css`, which is how `cardds.js` reads them to snap a drag. Demo:
+   `sheet.html`, `elements.html`.
+9. **Elements inside a card are frameless.** Rows, key-values, pickers,
+   gauges and tiles never draw a second card boundary; hairlines
+   (`--hairline`) separate rows, `--outline` keeps controls legible on
+   colored palettes. Data goes in as unitless custom properties
+   (`--value`, `--done`, `--total`); the math lives in CSS.
+10. **The dark slot re-points the accent.** `.card--3` sets `--accent` /
+    `--on-accent` to its own ink and bg, so every accent consumer (buttons,
+    checks, toggles, rings, selected days) inverts without extra rules.
+## New palette
+Copy any block in `palette.css`, rename, retune:
+```css
+[data-palette="mine"] {
+  --surface: …; --on-surface: …;
+  --card-1-bg: …; --card-1-ink: …;   /* + card-2, card-3 */
+  --accent: …;  --on-accent: …;
+  --action-bg: …; --action-ink: …;
+}
+```
+## Scale: everything is rem
+Every length token is rem (`--sp-4: 1rem`, `--tap: 3rem`, `--r-card: 2rem`,
+`--fs-h1: 1.75rem` …), so the whole system resizes from one number: the root
+font size. `base.css` keeps it at `100%` (the user's text-size setting, 16px by
+default) and steps narrow phones (≤360px) to `93.75%`, which keeps the 25rem
+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.
+An app with its own text-size setting publishes it as `--text-scale` on
+`<html>` — a unitless number, `1` by default — and `base.css` multiplies it into
+the root, so a member's "larger" composes with the narrow-phone step rather
+than overwriting it, and the app never writes a length from script.
+Components never write a raw length: spacing from `--sp-*`, control sizes from
+`--tap`, `--tap-lg`, `--btn-h`, `--bar-h`, `--header-h`, `--fab`, `--badge`, container
+padding from `--screen-pad` / `--card-pad`, radii from
+`--r-*`, type from `--fs-*` / `--type-*`. Data (progress, counts) enters as
+unitless custom properties. One measured length comes from script: `--kb`,
+the height an on-screen keyboard covers, published on `:root` by `cardds.js`
+from the visual viewport — as a px length, since only the browser knows it,
+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.
+## Icons & touch targets
+Icons come from `icons.svg` (Lucide, ISC — monochrome stroke, currentColor):
+```html
+<svg class="icon" aria-hidden="true"><use href="icons.svg#bell"/></svg>
+```
+`.icon` = `--icon` (1.75rem / 28px), `.icon--xs` = 1rem inside captions and chips,
+`.icon--lg` = 2rem for empty states. Never raw emoji/unicode glyphs — they
+render as colored emoji on phones. Add icons by appending `<symbol>`s
+(grab from lucide.dev, paste path data).
+Touch targets: `--tap` 3rem (`.icon-btn`), `--tap-sm` 2.75rem floor (`.icon-btn--sm`,
+selects, add-row), `--tap-lg` 3.5rem for hero controls. `.btn` ≥ `--btn-h` (3.25rem).
+Everything thumb-first.
+The two bars across the top of a screen — `.topbar` (screen title) and
+`.appbar` (app context) — share one rule and one floor, `--header-h` (3.75rem /
+60px), so a title-only bar stands as tall as one carrying an icon button, a
+dropdown or a `.btn`. `.screen` reserves its top padding from the same token.
+## Typography levels
+`t-display` 34–42/800 · `t-h1` 28 · `t-h2` 22 · `t-title` 17 · `t-body` 15 ·
+`t-label` 13 · `t-caption` 12 · `t-overline` 11 mono caps · `t-stat` big tabular
+numbers (`t-stat--mono`, `t-stat--xl`). Pixel values are at the default root;
+each is an `--fs-*` rem token. Swap `--font-display` per app for character.

package/cardds.css ADDED Viewed

@@ -0,0 +1,18 @@
+/* cardds — card-first mobile design system. One import. */
+@import url("css/fonts.css");    /* the two faces: PK Nonthaburi (body), FC Pride (display) */
+@import url("css/tokens.css");   /* structure + wireframe defaults */
+@import url("css/palette.css");  /* color settings — the file you tune */
+@import url("css/base.css");     /* reset, surface, type levels, section */
+@import url("css/card.css");     /* card boundary + list variants */
+@import url("css/stack.css");    /* sheet stack: .sheet-stack — the menu, sheets stacked, heads peek, tap opens */
+@import url("css/sheet.css");    /* sheet single: .sheet — one card as a bottom sheet, peek / half / full */
+@import url("css/step.css");     /* .step: one screen, one task — card, optional sheet, bar outside */
+@import url("css/forms.css");    /* outlined fields, add-row */
+@import url("css/journey.css");  /* route, tile badge, note row */
+@import url("css/actions.css");  /* topbar, chips, buttons, CTA pack */
+@import url("css/numbers.css");  /* ring, track, band, dot grid, picker, badge, bars */
+@import url("css/people.css");   /* avatar, avatar stack, chooser row */
+@import url("css/choice.css");   /* check, toggle, toggle chip, chip grid, days, calendar, mood, pin, composer */
+@import url("css/lists.css");    /* row, rows, key-value, kv grid, timeline, legend, link */
+@import url("css/media.css");    /* cover card, quote, tile grid, fold, mosaic, wave */
+@import url("css/layover.css");  /* ask drawer, popover menu, banner, float bar, callout, deck */