@cahyo-dimas/freeday 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -3,6 +3,75 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.18.0] — 2026-08-11
+### Fixed
+- **`FdyModal` / `FdyDrawer` (Vue) were non-dismissible when `dismissible` was omitted — an
+  accessibility defect.** Vue's boolean-cast delivers an omitted Boolean prop as `false`, not
+  `undefined`, so the defensive `props.dismissible !== false` evaluated to `false`: no Escape, no
+  backdrop close, and (modal) no close button rendered — the opposite of the documented
+  `dismissible: true` default. Both now use `withDefaults(…, { dismissible: true })`. React was
+  unaffected (it leaves omitted props `undefined`); `FdyCombo`/`FdyDatepicker` use `=== true`, which
+  is correct for an intended-`false` default.
+- **`.fdy-card--interactive` hover transform now respects reduced motion** — the `-3px` lift is dropped
+  under `prefers-reduced-motion` (the shadow still signals the affordance).
+### Added
+- **Page-composition primitives + type roles (`src/components/composition.css`).** `.fdy-page`,
+  `.fdy-page__header`, `.fdy-page-section`, `.fdy-toolbar`, `.fdy-stats`/`.fdy-stat` (a KPI tile that is
+  deliberately *not* a card, so a metric strip doesn't become an identical-card grid), and three title
+  roles `.fdy-title-page` / `-section` / `-card` (+ `.fdy-eyebrow`, `.fdy-text-muted`/`-caption`). They
+  encode *how a page is assembled* so independently-built screens cohere.
+- **`USAGE.md` — the usage doctrine.** Which token/role/shadow to use when: type roles, spacing rhythm,
+  elevation, one-primary-per-screen, semantic-vs-categorical colour, density, and the shell-down
+  composition order. The line where a component library becomes a design system.
+- **General categorical palette `--tone-1`…`--tone-8`** (a chart-neutral alias of the validated,
+  theme-aware `--chart-1`…`8`) + **`.fdy-chip--tone-N`** to match `.fdy-avatar--tone-N` — non-semantic
+  category colours (chips, tags, legends), WCAG AA in light & dark (gated).
+- **`FdyTable` surfaces its processed rows** — a `process` event (Vue) / `onProcess` callback (React),
+  `{ rows, total }`, in **both** client and server modes — so the same filtered/sorted/paged set can
+  drive a responsive card list, a selection summary, or CSV export without re-deriving the pipeline.
+- **`./table-model` export.** The pure `filterRows`/`sortRows`/`paginate`/`cellValue`/… functions
+  (`adapters/core/table-model.js`) are now reachable as `@cahyo-dimas/freeday/table-model`, so a consumer
+  can pre-compute exactly what `FdyTable` does instead of re-deriving it and risking drift.
+### Changed
+- **`data-density="compact"` now steps the mid-range spacing scale** (`--space-3`…`--space-6`) as well as
+  `--control-h`, so Freeday components — and a utility theme built on `var(--space-N)` — actually densify;
+  previously it changed only control height.
+- **Docs:** getting-started leads with the `.fdy-app` shell + a loud "load the fonts yourself" step (the
+  package names Sora / IBM Plex Sans / JetBrains Mono but bundles none); README links `USAGE.md`.
+
+Additive except the two bug fixes (which restore documented behaviour). Gate: `node --test` 22/22 ·
+`typecheck:react` 0 · `test:browser` 6/6 · new CSS browser-verified in real Chrome. From real-app
+consumption feedback (three instalments).
+
+## [1.17.0] — 2026-08-11
+### Added
+- **Avatar identity tones (`--tone-1`…`--tone-8`).** Decorative tints (from the categorical chart
+  palette) with a theme-aware, text-leaning foreground, so same-initial avatars — common where many
+  names share a prefix — stay distinguishable. Verified WCAG **AA** (≥4.5:1) in light **and** dark,
+  guarded by `test/contrast.test.mjs` (which gained a `color-mix()` evaluator). Hash a stable index
+  off the full name, not the initials.
+- **Size-matched skeletons (`.fdy-skeleton--avatar` + `--avatar-sm`/`--avatar-lg`).** Reserve the exact
+  `.fdy-avatar` box (2 / 2.5 / 3.5rem) so data landing causes no layout shift (a bare `--circle` has no
+  dimensions of its own).
+- **`.fdy-card--button`.** When the whole card *is* the control — a real `<button>` picker row, so it is
+  keyboard-reachable and announced — this resets the UA button box **without** stripping the card's own
+  surface/border.
+- **`.fdy-list-reset`.** Opt-in list reset for consumers who pair Freeday with a utility framework run
+  preflight-off (`base.css` is intentionally a *light* reset — it does not strip `ul`/`ol`/`p` margins).
+- **Toast `key` + `Freeday.dismiss()`.** `toast({ …, key })` replaces an existing same-key toast in
+  place instead of stacking a duplicate (a burst of identical failures shows one, refreshed);
+  `Freeday.dismiss(node | key)` closes one early. `toast()` already returned the element — both are now
+  in the `window.Freeday` type declarations.
+### Docs
+- State the scope boundary (components + tokens, **not** layout; pair with a utility framework run
+  preflight-off) in the README and getting-started; document that `--space-*`/`--radius-*` are public
+  tokens to build a utility theme on, and that `data-density` only re-scales control height.
+- Input docs now lead with `aria-invalid="true"` as the canonical accessible-field pattern (it does
+  both the visual state and the one screen readers act on); `.fdy-input--error` is the fallback.
+
+Additive; no breaking changes. Gate: `node --test` 22/22 (incl. avatar-tone contrast, both themes) ·
+`typecheck:react` 0 · new CSS/JS browser-verified in real Chrome. From real-app consumption feedback.
+
 ## [1.16.0] — 2026-08-11
 ### Added
 - **Native Blazor component library (`adapters/blazor/`) — first release, 10/10 parity.** A Razor

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.16.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.16.0)
+[![Release](https://img.shields.io/badge/release-v1.18.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.18.0)
 
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
@@ -49,6 +49,24 @@ ter-publish → install tanpa build step; minify diserahkan ke bundler konsumen.
 Kelas komponen berprefix `fdy-` (mis. `fdy-btn`, `fdy-card`, `fdy-badge`). Pakai langsung di
 markup framework apa pun — Vue, React, Blazor, atau HTML polos.
 
+> **⚠️ Muat font-nya sendiri — paket ini tidak.** Token tipe menamai **Sora** / **IBM Plex Sans** /
+> **JetBrains Mono** tapi Freeday tak membundel file font. Muat (mis. `@import '@fontsource/sora/700.css'`
+> …) atau override `--font-display`/`--font-body`/`--font-mono` — kalau tidak, kit jatuh ke fallback
+> sistem dan terlihat "belum jadi". Detail: [`docs/getting-started.md`](docs/getting-started.md).
+
+> **Token/role mana dipakai kapan → [`USAGE.md`](USAGE.md).** Freeday menjaga konsistensi *nilai*;
+> `USAGE.md` = doktrin yang menjaga konsistensi *keputusan* — role tipe (`.fdy-title-page/-section/-card`),
+> ritme spasi, elevasi, satu-primary-per-layar, palet kategorikal `--tone-1…8`, dan primitif komposisi
+> halaman (`.fdy-page`, `.fdy-page-section`, `.fdy-stats`). Tiap app mulai di `.fdy-app`.
+
+> **Scope: komponen + token, bukan layout.** Freeday punya komponen & design token; helper layout
+> cuma `.fdy-hidden` / `.fdy-visually-hidden` plus primitif komposisi di atas. Layout grid dari layer-mu sendiri —
+> pasangkan dengan utility framework (Tailwind, UnoCSS…) mode **utilities-only, preflight OFF**
+> (`base.css` Freeday = reset-nya). `base.css` itu reset *ringan* (tak me-reset margin `ul`/`ol`/`p` —
+> pakai `.fdy-list-reset` atau komponen list Freeday), dan skala spacing/radius/durasi adalah custom
+> property publik (`--space-0`…`--space-24`, …) yang bisa jadi dasar theme utility-mu. Detail:
+> [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
+
 > `.fdy-btn` **sudah** tombol primary — tak ada modifier `.fdy-btn--primary` terpisah.
 > Modifier untuk varian lain: `--ghost`, `--danger`, `--text`, `--sm`, `--lg`, `--icon`
 > (lihat `docs/index.html`).
@@ -126,17 +144,19 @@ import { useFreeday } from '@cahyo-dimas/freeday/react';
 const root = useRef<HTMLDivElement>(null);
 useFreeday(root);                     // event fdy-* bubbling → listen di root
 ```
-```csharp
-// Blazor — @cahyo-dimas/freeday/blazor (window.FreedayBlazor via JS interop)
-await JS.InvokeVoidAsync("FreedayBlazor.initAll", _root);
-await JS.InvokeAsync<int>("FreedayBlazor.on", _root, "fdy-cascade-change", _self, nameof(OnCascade));
+```razor
+@* Blazor — RCL Freeday.Blazor (net8.0): komponen native typed <FdyX> dengan @bind, 10/10 parity *@
+@using Freeday.Blazor
+<FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl" />
+<FdyTable TRow="Invoice" Columns="_cols" Rows="_rows" RowKey="@(i => i.Code)" PageSize="10" />
+@* Fallback untuk markup mentah: interop window.FreedayBlazor.initAll / .on *@
 ```
 
 | Framework | Adapter | Contoh jalan |
 |---|---|---|
-| Vue 3 | `@cahyo-dimas/freeday/vue` | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
-| React 19 | `@cahyo-dimas/freeday/react` | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
-| Blazor WASM (.NET 10) | `@cahyo-dimas/freeday/blazor` | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
+| Vue 3 | `@cahyo-dimas/freeday/vue` (`useFreeday` + komponen `v-model`) | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
+| React 19 | `@cahyo-dimas/freeday/react` (`useFreeday` + komponen `value`/`onChange`) | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
+| Blazor WASM (net8.0) | RCL `Freeday.Blazor` (`<FdyX>` + `@bind`) · interop `/blazor` | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
 
 Peta library & pola lengkap: [`docs/integrations.md`](docs/integrations.md).
 

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.16.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.16.0)
+[![Release](https://img.shields.io/badge/release-v1.18.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.18.0)
 
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
@@ -49,6 +49,24 @@ bundler. Because it's on **public npm**, `npm ci` runs in CI without auth or an
 Component classes are prefixed `fdy-` (e.g. `fdy-btn`, `fdy-card`, `fdy-badge`). Use them directly
 in any framework's markup — Vue, React, Blazor, or plain HTML.
 
+> **⚠️ Load the fonts — the package doesn't.** The type tokens name **Sora** / **IBM Plex Sans** /
+> **JetBrains Mono** but Freeday bundles no font files. Load them (e.g. `@import '@fontsource/sora/700.css'`
+> …) or override `--font-display`/`--font-body`/`--font-mono` — otherwise the kit renders in the system
+> fallback and looks unfinished. See [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
+
+> **Which token/role to use when → [`USAGE.md`](USAGE.md).** Freeday enforces consistent *values*;
+> `USAGE.md` is the doctrine that also makes *decisions* consistent — type roles (`.fdy-title-page/-section/-card`),
+> spacing rhythm, elevation, one-primary-per-screen, the `--tone-1…8` categorical palette, and the page-
+> composition primitives (`.fdy-page`, `.fdy-page-section`, `.fdy-stats`). Every app starts in `.fdy-app`.
+
+> **Scope: components + tokens, not layout.** Freeday owns components and design tokens; the only
+> layout helpers are `.fdy-hidden` / `.fdy-visually-hidden` plus the page-composition primitives above.
+> Bring your own grid layer — pair it with a utility framework (Tailwind, UnoCSS…) run **utilities-only
+> with preflight OFF** (Freeday's `base.css` is the reset). `base.css` is a *light* reset (it doesn't
+> strip `ul`/`ol`/`p` margins — use `.fdy-list-reset` or a Freeday list component), and the
+> spacing/radius/duration scales are public custom properties (`--space-0`…`--space-24`, …) you can
+> build your utility theme on. Full notes: [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
+
 > `.fdy-btn` is **already** the primary button — there's no separate `.fdy-btn--primary` modifier.
 > Modifiers for other variants: `--ghost`, `--danger`, `--text`, `--sm`, `--lg`, `--icon`
 > (see `docs/index.html`).
@@ -126,17 +144,19 @@ import { useFreeday } from '@cahyo-dimas/freeday/react';
 const root = useRef<HTMLDivElement>(null);
 useFreeday(root);                     // fdy-* events bubble → listen at the root
 ```
-```csharp
-// Blazor — @cahyo-dimas/freeday/blazor (window.FreedayBlazor via JS interop)
-await JS.InvokeVoidAsync("FreedayBlazor.initAll", _root);
-await JS.InvokeAsync<int>("FreedayBlazor.on", _root, "fdy-cascade-change", _self, nameof(OnCascade));
+```razor
+@* Blazor — Freeday.Blazor RCL (net8.0): native typed <FdyX> with @bind, 10/10 parity *@
+@using Freeday.Blazor
+<FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl" />
+<FdyTable TRow="Invoice" Columns="_cols" Rows="_rows" RowKey="@(i => i.Code)" PageSize="10" />
+@* Fallback for raw markup: window.FreedayBlazor.initAll / .on interop *@
 ```
 
 | Framework | Adapter | Working example |
 |---|---|---|
-| Vue 3 | `@cahyo-dimas/freeday/vue` | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
-| React 19 | `@cahyo-dimas/freeday/react` | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
-| Blazor WASM (.NET 10) | `@cahyo-dimas/freeday/blazor` | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
+| Vue 3 | `@cahyo-dimas/freeday/vue` (`useFreeday` + `v-model` components) | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
+| React 19 | `@cahyo-dimas/freeday/react` (`useFreeday` + `value`/`onChange` components) | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
+| Blazor WASM (net8.0) | `Freeday.Blazor` RCL (`<FdyX>` + `@bind`) · `/blazor` interop | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
 
 Full library map and patterns: [`docs/integrations.md`](docs/integrations.md).
 

package/USAGE.md

@@ -0,0 +1,104 @@
+# Freeday — Usage doctrine
+
+Freeday ships tokens and components. This file ships the **decisions** — which token to use when,
+how a page is assembled, what earns emphasis. A component library enforces consistent *values*; a
+design system also enforces consistent *decisions*. Skim this once before building a screen; it is
+what makes screens built by different people (or different sessions) look like one product.
+
+The rules are opinionated on purpose. When one conflicts with a real need, break it deliberately —
+but start here, not from a blank page.
+
+---
+
+## 1. Type roles — three title levels, not eleven
+
+Do **not** reuse `.fdy-card__title` for a page title. Collapsing page/section/card into one style is
+the single biggest cause of "flat grey mush". Pick the role, not the size:
+
+| Role | Class | When |
+|---|---|---|
+| Eyebrow | `.fdy-eyebrow` | A small uppercase label above a page/section title. Optional. |
+| Page title | `.fdy-title-page` | One per screen. The `<h1>`. |
+| Section title | `.fdy-title-section` | A region within the page (`<h2>`). |
+| Card / row title | `.fdy-title-card` (or `.fdy-card__title`) | A title inside a card or list row (`<h3>`). |
+| Body | *(default)* | Running text. |
+| Muted / caption | `.fdy-text-muted`, `.fdy-text-caption` | Secondary text, timestamps, help. |
+
+Everything else is body. If you reach for a fourth title size, you probably need a section, not a
+font size.
+
+## 2. Spacing rhythm — three gaps, always from the scale
+
+Never a loose value; always `var(--space-N)` (a 4px scale). Three rhythms carry most layouts, and the
+composition primitives apply them for you:
+
+- **Between page sections:** `--space-8` — `.fdy-page` sets this gap between its children.
+- **Within a group** (heading ↔ its body, cards in a list): `--space-4` — `.fdy-page-section` sets it.
+- **Inside a control/card** (label ↔ input, icon ↔ text): `--space-2` / `--space-3`.
+
+Reserve `--space-1` for hairline pairs and `--space-10`+ for deliberate breathing room (a hero, an
+empty state). Don't scatter `--space-6` everywhere — a page with one gap value has no rhythm.
+
+## 3. Elevation — most surfaces are flat
+
+Shadow is a signal, not decoration. Spend it sparingly:
+
+- **Flat** (no shadow, border only, or nothing): the default. Page sections, list rows, the app shell.
+- **`--shadow-1`:** a card that is a distinct object you could pick up — a workspace tile, a panel.
+- **`--shadow-2`/`3`:** something that *floats over* the page — a popover, menu, or dropdown.
+- **`--shadow-4`:** a modal / drawer overlay only.
+
+If every box on the screen has the same card shadow, none of them read as special — that's the
+"identical card grid" failure. Prefer flat sections with **one** raised element that matters.
+
+## 4. Emphasis — exactly one primary per screen
+
+`.fdy-btn` is *already* the primary action (there is no `--primary` modifier). Use it **once** per
+screen — the one thing you want the user to do. Everything else is `--ghost` or `--text`. Two primary
+buttons on a screen means neither is. The same rule governs colour fills and `--shadow`: one focal
+point, everything around it quiet.
+
+## 5. Colour — semantic is reserved; categorical is `--tone`
+
+- **Accent** (`--color-primary`, and `--color-accent` sparingly): interactive + brand. This is your
+  one accent hue.
+- **Semantic is reserved** and is *not* your accent: `--color-success` = good only, `--color-warning`
+  = caution only, `--color-danger` = destructive/error only. Never decorative. Encode state in a pill
+  or chip, not just colour.
+- **Categorical** (`--tone-1` … `--tone-8`, the general alias of the validated chart palette): N
+  visually-distinct **non-semantic** colours — avatar tones, category chips, tags, legend swatches.
+  Use the modifiers `.fdy-avatar--tone-N` / `.fdy-chip--tone-N` (both stay WCAG AA in light & dark),
+  and hash a stable index off the full string so the same category always gets the same colour.
+- **Surfaces:** most backgrounds are `--color-surface`; `--color-surface-2`/`-3` for a recessed area;
+  `--color-primary-soft` only when you want a tinted callout, not as a default panel colour.
+
+## 6. Density — `compact` for data-dense screens
+
+`data-density="compact"` on `<html>` tightens control height **and** the mid-range spacing scale
+(`--space-3`…`--space-6` step down a notch), so cards, toolbars and tables get denser. Use it on
+table-heavy back-office screens; leave `comfortable` (the default) for forms and marketing-adjacent
+pages. Set it once at the app root, not per component.
+
+## 7. Assemble the page from the frame down
+
+1. **Shell:** every application starts inside **`.fdy-app`** (`__topbar`, `__sidebar`, `__main`,
+   `__content`, `__navtoggle`, `__backdrop`). Don't hand-roll a shell from flexbox — the toggle and
+   backdrop plumbing are already there. See `docs/getting-started.md`.
+2. **Page:** wrap the screen body in **`.fdy-page`** (vertical section rhythm), opening with a
+   **`.fdy-page__header`** (eyebrow + `.fdy-title-page` + `.fdy-page__desc` on the left, the one
+   primary action on the right).
+3. **Sections:** each region is a **`.fdy-page-section`** (a `.fdy-title-section` + optional
+   `.fdy-toolbar`, then its body).
+4. **KPIs:** a **`.fdy-stats`** grid of **`.fdy-stat`** tiles — deliberately *not* cards, so a metric
+   strip doesn't become an identical-card grid. Wrap in `.fdy-stats--boxed` for one shared strip.
+5. **Content:** components (`.fdy-card`, `.fdy-datatable`, `.fdy-chart`, …) go inside sections.
+
+Freeday deliberately owns **components + tokens, not layout**. Everything above is layout in the kit's
+own language; for the rest (grids, one-off spacing), pair a utility framework run **utilities-only,
+preflight-off** — and build its theme on `var(--space-N)` so the two systems agree. See
+`docs/getting-started.md` §Core concepts.
+
+---
+
+*Layout classes here live in `src/components/composition.css`. If a screen needs a primitive that
+isn't here, it probably belongs here — open an issue rather than re-inventing it per screen.*

package/adapters/react/components/FdyTable.tsx

@@ -57,6 +57,10 @@ export interface FdyTableProps<Row extends object> {
   rowClass?: (row: Row) => string | undefined;
   /** A row was activated (click, or Enter/Space while the row itself is focused). */
   onRowActivate?: (row: Row) => void;
+  /** Called with the processed page of rows (after filter/sort/paginate) plus the total row count —
+   *  in BOTH modes, whenever they change. Lets a consumer render the SAME processed set elsewhere
+   *  (a `< md` card list, a "selected" summary, export-to-CSV) without re-deriving the pipeline. */
+  onProcess?: (result: { rows: Row[]; total: number }) => void;
   /** Controlled: row keys whose detail is shown as a full-width row beneath them. */
   expandedKeys?: ReadonlyArray<string | number>;
   /** Renders the expandable detail row for an expanded row (React equivalent of Vue's `row-detail` slot). */
@@ -110,6 +114,13 @@ export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Ele
     if (!serverPaged && internalPageIndex > totalPages - 1) setInternalPageIndex(Math.max(0, totalPages - 1));
   }, [serverPaged, internalPageIndex, totalPages]);
 
+  // Surface the processed page + total to the parent (both modes), so the same result can drive a
+  // responsive card list / summary / export without re-implementing filter/sort/paginate.
+  const onProcess = props.onProcess;
+  useEffect((): void => {
+    onProcess?.({ rows: displayRows, total: totalCount });
+  }, [onProcess, displayRows, totalCount]);
+
   function ariaSortOf(col: FdyTableColumn<Row>): 'ascending' | 'descending' | undefined {
     if (effectiveSort === null || effectiveSort.key !== col.key) return undefined;
     return effectiveSort.dir === 'asc' ? 'ascending' : 'descending';

package/adapters/vue/components/FdyDrawer.vue

@@ -8,12 +8,15 @@ import { computed, onMounted, useId, watch, type ComputedRef, type Ref, ref } fr
 // focus trap, focus restore, top-layer stacking and inert background; `dismissible` (default true)
 // gates Esc + backdrop dismissal.
 
-const props = defineProps<{
+// dismissible MUST go through withDefaults: Vue's boolean-cast gives an omitted Boolean prop
+// `false`, not `undefined`, so a bare `props.dismissible !== false` would make an un-annotated
+// drawer non-dismissible (no Esc, no backdrop, no close button) — the opposite of the default.
+const props = withDefaults(defineProps<{
   open: boolean;
   title: string;
   side?: 'left' | 'right';
   dismissible?: boolean;
-}>();
+}>(), { dismissible: true });
 
 const emit = defineEmits<{
   close: [];

package/adapters/vue/components/FdyModal.vue

@@ -10,12 +10,15 @@ import { computed, onMounted, useId, watch, type ComputedRef, type Ref, ref } fr
 // Native <dialog> already provides the focus trap, focus restore, top-layer stacking and inert
 // background — the wrapper only avoids breaking them. `dismissible` (default true) gates Esc + backdrop.
 
-const props = defineProps<{
+// dismissible MUST go through withDefaults: Vue's boolean-cast gives an omitted Boolean prop
+// `false`, not `undefined`, so a bare `props.dismissible !== false` would make an un-annotated
+// modal non-dismissible (no Esc, no backdrop, no close button) — the opposite of the default.
+const props = withDefaults(defineProps<{
   open: boolean;
   title: string;
   size?: 'sm' | 'md' | 'lg' | 'wide';
   dismissible?: boolean;
-}>();
+}>(), { dismissible: true });
 
 const emit = defineEmits<{
   close: [];

package/adapters/vue/components/FdyTable.vue

@@ -58,6 +58,10 @@ const emit = defineEmits<{
   'update:page': [page: FdyPageState];
   /** A row was activated (click, or Enter/Space while the row itself is focused). */
   'row-activate': [row: Row];
+  /** The processed page of rows (after filter/sort/paginate) plus the total row count — fires in
+   *  BOTH modes whenever they change. Lets a consumer render the SAME processed set elsewhere
+   *  (a `< md` card list, a "selected" summary, export-to-CSV) without re-deriving the pipeline. */
+  'process': [result: { rows: Row[]; total: number }];
 }>();
 
 const internalSort: Ref<FdySortState | null> = ref(null);
@@ -125,6 +129,14 @@ watch(totalPages, (tp: number): void => {
   if (!serverPaged.value && internalPageIndex.value > tp - 1) internalPageIndex.value = Math.max(0, tp - 1);
 });
 
+// Surface the processed page + total to the parent (both modes), so the same result can drive a
+// responsive card list / summary / export without re-implementing filter/sort/paginate.
+watch(
+  [displayRows, totalCount],
+  (): void => emit('process', { rows: displayRows.value, total: totalCount.value }),
+  { immediate: true },
+);
+
 function ariaSortOf(col: FdyTableColumn<Row>): 'ascending' | 'descending' | undefined {
   const s: FdySortState | null = effectiveSort.value;
   if (s === null || s.key !== col.key) return undefined;

package/dist/freeday-toast.js

@@ -1,14 +1,24 @@
 /* Freeday — toast API (optional, zero-dependency).
- * Freeday.toast({ variant, title, message, timeout }) shows a transient
+ * Freeday.toast({ variant, title, message, timeout, key }) shows a transient
  * notification in a live region (created on first use). Returns the element.
  *   variant: 'success' | 'warning' | 'danger' | 'info' (default: neutral)
  *   timeout: ms before auto-dismiss (default 4000; 0 = sticky)
+ *   key:     optional stable id — a new toast with the same key REPLACES the
+ *            existing one in place instead of stacking a duplicate (e.g. a burst
+ *            of identical failures shows one toast, refreshed).
+ * Freeday.dismiss(nodeOrKey) closes a toast early (pass the returned element or its key).
  * Danger toasts use role="alert"; others role="status".
  */
 (function () {
   'use strict';
 
   var region = null;
+  var keyed = {}; // key -> current node, for replace-in-place + dismiss-by-key
+
+  function forget(node) {
+    var k = node && node._fdyKey;
+    if (k != null && keyed[k] === node) delete keyed[k];
+  }
 
   function ensureRegion() {
     if (region && document.body.contains(region)) return region;
@@ -24,7 +34,9 @@
   }
 
   function dismiss(toast) {
+    if (typeof toast === 'string') toast = keyed[toast]; // dismiss by key
     if (!toast || toast.dataset.leaving === '1') return;
+    forget(toast);
     toast.dataset.leaving = '1';
     toast.classList.add('is-leaving');
     var remove = function () { if (toast.parentNode) toast.parentNode.removeChild(toast); };
@@ -64,6 +76,14 @@
     node.appendChild(accent);
     node.appendChild(body);
     node.appendChild(close);
+
+    // Replace-in-place: a same-key toast removes the previous one so bursts don't stack.
+    if (opts.key != null) {
+      var prev = keyed[opts.key];
+      if (prev && prev.parentNode) prev.parentNode.removeChild(prev);
+      node._fdyKey = opts.key;
+      keyed[opts.key] = node;
+    }
     region.appendChild(node);
 
     var timeout = opts.timeout == null ? 4000 : opts.timeout;
@@ -81,4 +101,5 @@
 
   window.Freeday = window.Freeday || {};
   window.Freeday.toast = toast;
+  window.Freeday.dismiss = dismiss; // dismiss(nodeOrKey)
 })();

package/dist/freeday.bundle.css

@@ -166,6 +166,14 @@
   --chart-8: #e34948;
   --chart-grid: var(--slate-200);
   --chart-tick: var(--slate-400);
+  --tone-1: var(--chart-1);
+  --tone-2: var(--chart-2);
+  --tone-3: var(--chart-3);
+  --tone-4: var(--chart-4);
+  --tone-5: var(--chart-5);
+  --tone-6: var(--chart-6);
+  --tone-7: var(--chart-7);
+  --tone-8: var(--chart-8);
   --focus-ring: var(--azure-600);
   --focus-ring-width: 2px;
 }
@@ -340,6 +348,10 @@
   --focus-ring: var(--azure-600);
 }
 :root[data-density="compact"] {
+  --space-3: 0.625rem;
+  --space-4: 0.75rem;
+  --space-5: 1rem;
+  --space-6: 1.25rem;
   --control-h: 2rem;
 }
 
@@ -361,6 +373,11 @@ a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
+ * margins (see the kit's own list components, which each reset themselves). If you run a utility
+ * framework with its preflight OFF (the recommended pairing), a semantic <ul>/<ol> keeps native
+ * bullets + a 40px indent; add this class (or a Freeday list component) to normalise it. */
+.fdy-list-reset { list-style: none; margin: 0; padding: 0; }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .001ms !important; transition-duration: .001ms !important; }
 }
@@ -524,6 +541,19 @@ a { color: var(--color-primary); }
 .fdy-avatar-group{display:inline-flex;}
 .fdy-avatar-group .fdy-avatar{border:2px solid var(--color-surface);margin-left:calc(var(--space-2)*-1);}
 .fdy-avatar-group .fdy-avatar:first-child{margin-left:0;}
+/* Decorative identity tones — a soft tint of a categorical chart colour with a theme-aware,
+ * text-leaning foreground so initials keep WCAG AA (verified >=4.5:1 in light & dark by
+ * test/contrast.test.mjs). Use to disambiguate same-initial avatars (e.g. many "PT …" names):
+ * hash a stable 1..8 index off the FULL name in your app, then apply .fdy-avatar--tone-<n>. */
+.fdy-avatar--tone-1,.fdy-avatar--tone-2,.fdy-avatar--tone-3,.fdy-avatar--tone-4,.fdy-avatar--tone-5,.fdy-avatar--tone-6,.fdy-avatar--tone-7,.fdy-avatar--tone-8{background:color-mix(in srgb,var(--_fdy-avatar-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-avatar-tone) 50%,var(--color-text));}
+.fdy-avatar--tone-1{--_fdy-avatar-tone:var(--tone-1);}
+.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--tone-2);}
+.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--tone-3);}
+.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--tone-4);}
+.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--tone-5);}
+.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--tone-6);}
+.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--tone-7);}
+.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--tone-8);}
 
 /* Freeday — Badge */
 .fdy-badge{display:inline-flex;align-items:center;gap:var(--space-1);font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);line-height:1;white-space:nowrap;padding:.35em .7em;border-radius:var(--radius-full);color:var(--color-primary-strong);background:var(--color-primary-soft);border:var(--bw) solid color-mix(in srgb,var(--color-primary) 22%,transparent);box-shadow:0 1px 1.5px rgba(16,14,30,.05);}
@@ -643,6 +673,13 @@ a { color: var(--color-primary); }
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* The global reduced-motion reset kills the ANIMATION; drop the -3px shift too so the card
+ * doesn't jump. The shadow still communicates the affordance. */
+@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover{transform:none;}}
+/* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
+ * announced — reset the UA button box. Note: it does NOT reset background/border, because
+ * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
+.fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -794,6 +831,18 @@ a { color: var(--color-primary); }
 /* Freeday — Chip (tag / removable filter) */
 .fdy-chip{display:inline-flex;align-items:center;gap:var(--space-2);height:1.75rem;padding:0 var(--space-3);border-radius:var(--radius-full);font-size:var(--text-xs);font-weight:var(--weight-medium);color:var(--color-text);background:var(--color-surface-3);border:var(--bw) solid var(--color-border);}
 .fdy-chip--primary{color:var(--color-primary-strong);background:var(--color-primary-soft);border-color:color-mix(in srgb,var(--color-primary) 22%,transparent);}
+/* Categorical tone chips — non-semantic category tags / legend swatches, from the general
+ * --tone-1..8 palette. Same validated AA formula as .fdy-avatar--tone-* (text >=4.5:1 both themes,
+ * gated by test/contrast.test.mjs). */
+.fdy-chip--tone-1,.fdy-chip--tone-2,.fdy-chip--tone-3,.fdy-chip--tone-4,.fdy-chip--tone-5,.fdy-chip--tone-6,.fdy-chip--tone-7,.fdy-chip--tone-8{background:color-mix(in srgb,var(--_fdy-chip-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-chip-tone) 50%,var(--color-text));border-color:color-mix(in srgb,var(--_fdy-chip-tone) 30%,var(--color-border));}
+.fdy-chip--tone-1{--_fdy-chip-tone:var(--tone-1);}
+.fdy-chip--tone-2{--_fdy-chip-tone:var(--tone-2);}
+.fdy-chip--tone-3{--_fdy-chip-tone:var(--tone-3);}
+.fdy-chip--tone-4{--_fdy-chip-tone:var(--tone-4);}
+.fdy-chip--tone-5{--_fdy-chip-tone:var(--tone-5);}
+.fdy-chip--tone-6{--_fdy-chip-tone:var(--tone-6);}
+.fdy-chip--tone-7{--_fdy-chip-tone:var(--tone-7);}
+.fdy-chip--tone-8{--_fdy-chip-tone:var(--tone-8);}
 .fdy-chip__remove{display:inline-flex;align-items:center;justify-content:center;width:1.25rem;height:1.25rem;margin-right:calc(var(--space-1)*-1);border:0;padding:0;border-radius:var(--radius-full);background:transparent;color:currentColor;opacity:.6;cursor:pointer;font-size:var(--text-sm);line-height:1;}
 .fdy-chip__remove:hover{opacity:1;background:color-mix(in srgb,currentColor 16%,transparent);}
 .fdy-chip__remove:focus-visible{outline:none;opacity:1;box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
@@ -843,6 +892,56 @@ a { color: var(--color-primary); }
 @media (prefers-reduced-motion:no-preference){.fdy-combo__listbox:not([hidden]){animation:fdy-combo-in var(--dur-fast) var(--ease-standard);}}
 @keyframes fdy-combo-in{from{opacity:0;transform:translateY(-4px);}to{opacity:1;transform:none;}}
 
+/* Freeday — Page composition & type roles.
+ *
+ * The kit stops at the component; these primitives encode *how a page is assembled* so screens
+ * built by different people cohere. They carry the usage doctrine (see USAGE.md) in markup: a
+ * named type role gets used, a doc gets skimmed. Everything here is token-driven layout — no new
+ * colours, no new shadows. Pair with .fdy-app (the shell) and the components inside.
+ */
+
+/* ---- Type roles (three title levels + supporting text) -------------------------------------
+ * One role per level of hierarchy. Reach for these instead of re-using .fdy-card__title for a
+ * page title (the mistake that collapses three levels into one grey mush). */
+.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+.fdy-title-page{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:var(--leading-tight);color:var(--color-text);margin:0;text-wrap:balance;}
+.fdy-title-section{font-family:var(--font-display);font-size:var(--text-xl);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);line-height:var(--leading-snug);color:var(--color-text);margin:0;text-wrap:balance;}
+.fdy-title-card{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0;}
+.fdy-text-muted{color:var(--color-text-muted);}
+.fdy-text-subtle{color:var(--color-text-subtle);}
+.fdy-text-caption{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;}
+
+/* ---- Page: the vertical stack of sections, with the section rhythm between them ------------- */
+.fdy-page{display:flex;flex-direction:column;gap:var(--space-8);}
+
+/* ---- Page header: eyebrow + title + description on the left, primary action(s) on the right -- */
+.fdy-page__header{display:flex;align-items:flex-end;justify-content:space-between;gap:var(--space-4);flex-wrap:wrap;}
+.fdy-page__heading{display:flex;flex-direction:column;gap:var(--space-2);min-width:0;}
+.fdy-page__desc{font-size:var(--text-base);color:var(--color-text-muted);margin:0;max-width:62ch;line-height:var(--leading-normal);}
+.fdy-page__actions{display:flex;align-items:center;gap:var(--space-2);flex-wrap:wrap;}
+
+/* ---- Page section: a heading (+ optional toolbar) and its body, with the intra-group rhythm --- */
+.fdy-page-section{display:flex;flex-direction:column;gap:var(--space-4);}
+.fdy-page-section__head{display:flex;align-items:baseline;justify-content:space-between;gap:var(--space-3);flex-wrap:wrap;}
+
+/* ---- Toolbar: a horizontal control row (search + actions), wraps cleanly ---------------------- */
+.fdy-toolbar{display:flex;align-items:center;gap:var(--space-3);flex-wrap:wrap;}
+.fdy-toolbar__spacer{flex:1;}
+.fdy-toolbar__search{max-width:18rem;flex:1 1 12rem;}
+
+/* ---- Stat tile: a KPI metric that is deliberately NOT a card, so a KPI strip doesn't become an
+ * identical-white-card grid. Flat by default; wrap the .fdy-stats grid in one card if you want a
+ * single boxed strip, or use .fdy-stats--boxed for shared surface + dividers. */
+.fdy-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));gap:var(--space-5);}
+.fdy-stat{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;}
+.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+.fdy-stat__value{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:1;color:var(--color-text);font-variant-numeric:tabular-nums;}
+.fdy-stat__value small{font-size:var(--text-lg);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
+.fdy-stat__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);}
+.fdy-stats--boxed{background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);gap:0;}
+.fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
+.fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
+
 /* Freeday — Date picker (input-styled trigger + calendar popover).
  * Built by freeday-datepicker.js from an empty [data-fdy-datepicker] wrapper. */
 .fdy-datepicker{position:relative;display:inline-block;width:100%;max-width:14rem;}
@@ -1202,6 +1301,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-skeleton--text{height:.8rem;margin:.3rem 0;}
 .fdy-skeleton--title{height:1.2rem;width:40%;}
 .fdy-skeleton--circle{border-radius:var(--radius-full);}
+/* Size-matched to .fdy-avatar (2.5rem) and its --sm/--lg, so a skeleton reserves the exact avatar
+ * box and data landing causes no layout shift (a plain --circle has no dimensions of its own). */
+.fdy-skeleton--avatar{width:2.5rem;height:2.5rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-sm{width:2rem;height:2rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-lg{width:3.5rem;height:3.5rem;border-radius:var(--radius-full);}
 @keyframes fdy-skeleton{to{background-position:-200% 0;}}
 @media (prefers-reduced-motion:reduce){.fdy-skeleton{animation:none;}}
 

package/dist/freeday.css

@@ -16,6 +16,11 @@ a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
+ * margins (see the kit's own list components, which each reset themselves). If you run a utility
+ * framework with its preflight OFF (the recommended pairing), a semantic <ul>/<ol> keeps native
+ * bullets + a 40px indent; add this class (or a Freeday list component) to normalise it. */
+.fdy-list-reset { list-style: none; margin: 0; padding: 0; }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .001ms !important; transition-duration: .001ms !important; }
 }
@@ -179,6 +184,19 @@ a { color: var(--color-primary); }
 .fdy-avatar-group{display:inline-flex;}
 .fdy-avatar-group .fdy-avatar{border:2px solid var(--color-surface);margin-left:calc(var(--space-2)*-1);}
 .fdy-avatar-group .fdy-avatar:first-child{margin-left:0;}
+/* Decorative identity tones — a soft tint of a categorical chart colour with a theme-aware,
+ * text-leaning foreground so initials keep WCAG AA (verified >=4.5:1 in light & dark by
+ * test/contrast.test.mjs). Use to disambiguate same-initial avatars (e.g. many "PT …" names):
+ * hash a stable 1..8 index off the FULL name in your app, then apply .fdy-avatar--tone-<n>. */
+.fdy-avatar--tone-1,.fdy-avatar--tone-2,.fdy-avatar--tone-3,.fdy-avatar--tone-4,.fdy-avatar--tone-5,.fdy-avatar--tone-6,.fdy-avatar--tone-7,.fdy-avatar--tone-8{background:color-mix(in srgb,var(--_fdy-avatar-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-avatar-tone) 50%,var(--color-text));}
+.fdy-avatar--tone-1{--_fdy-avatar-tone:var(--tone-1);}
+.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--tone-2);}
+.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--tone-3);}
+.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--tone-4);}
+.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--tone-5);}
+.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--tone-6);}
+.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--tone-7);}
+.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--tone-8);}
 
 /* Freeday — Badge */
 .fdy-badge{display:inline-flex;align-items:center;gap:var(--space-1);font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);line-height:1;white-space:nowrap;padding:.35em .7em;border-radius:var(--radius-full);color:var(--color-primary-strong);background:var(--color-primary-soft);border:var(--bw) solid color-mix(in srgb,var(--color-primary) 22%,transparent);box-shadow:0 1px 1.5px rgba(16,14,30,.05);}
@@ -298,6 +316,13 @@ a { color: var(--color-primary); }
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* The global reduced-motion reset kills the ANIMATION; drop the -3px shift too so the card
+ * doesn't jump. The shadow still communicates the affordance. */
+@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover{transform:none;}}
+/* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
+ * announced — reset the UA button box. Note: it does NOT reset background/border, because
+ * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
+.fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -449,6 +474,18 @@ a { color: var(--color-primary); }
 /* Freeday — Chip (tag / removable filter) */
 .fdy-chip{display:inline-flex;align-items:center;gap:var(--space-2);height:1.75rem;padding:0 var(--space-3);border-radius:var(--radius-full);font-size:var(--text-xs);font-weight:var(--weight-medium);color:var(--color-text);background:var(--color-surface-3);border:var(--bw) solid var(--color-border);}
 .fdy-chip--primary{color:var(--color-primary-strong);background:var(--color-primary-soft);border-color:color-mix(in srgb,var(--color-primary) 22%,transparent);}
+/* Categorical tone chips — non-semantic category tags / legend swatches, from the general
+ * --tone-1..8 palette. Same validated AA formula as .fdy-avatar--tone-* (text >=4.5:1 both themes,
+ * gated by test/contrast.test.mjs). */
+.fdy-chip--tone-1,.fdy-chip--tone-2,.fdy-chip--tone-3,.fdy-chip--tone-4,.fdy-chip--tone-5,.fdy-chip--tone-6,.fdy-chip--tone-7,.fdy-chip--tone-8{background:color-mix(in srgb,var(--_fdy-chip-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-chip-tone) 50%,var(--color-text));border-color:color-mix(in srgb,var(--_fdy-chip-tone) 30%,var(--color-border));}
+.fdy-chip--tone-1{--_fdy-chip-tone:var(--tone-1);}
+.fdy-chip--tone-2{--_fdy-chip-tone:var(--tone-2);}
+.fdy-chip--tone-3{--_fdy-chip-tone:var(--tone-3);}
+.fdy-chip--tone-4{--_fdy-chip-tone:var(--tone-4);}
+.fdy-chip--tone-5{--_fdy-chip-tone:var(--tone-5);}
+.fdy-chip--tone-6{--_fdy-chip-tone:var(--tone-6);}
+.fdy-chip--tone-7{--_fdy-chip-tone:var(--tone-7);}
+.fdy-chip--tone-8{--_fdy-chip-tone:var(--tone-8);}
 .fdy-chip__remove{display:inline-flex;align-items:center;justify-content:center;width:1.25rem;height:1.25rem;margin-right:calc(var(--space-1)*-1);border:0;padding:0;border-radius:var(--radius-full);background:transparent;color:currentColor;opacity:.6;cursor:pointer;font-size:var(--text-sm);line-height:1;}
 .fdy-chip__remove:hover{opacity:1;background:color-mix(in srgb,currentColor 16%,transparent);}
 .fdy-chip__remove:focus-visible{outline:none;opacity:1;box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
@@ -498,6 +535,56 @@ a { color: var(--color-primary); }
 @media (prefers-reduced-motion:no-preference){.fdy-combo__listbox:not([hidden]){animation:fdy-combo-in var(--dur-fast) var(--ease-standard);}}
 @keyframes fdy-combo-in{from{opacity:0;transform:translateY(-4px);}to{opacity:1;transform:none;}}
 
+/* Freeday — Page composition & type roles.
+ *
+ * The kit stops at the component; these primitives encode *how a page is assembled* so screens
+ * built by different people cohere. They carry the usage doctrine (see USAGE.md) in markup: a
+ * named type role gets used, a doc gets skimmed. Everything here is token-driven layout — no new
+ * colours, no new shadows. Pair with .fdy-app (the shell) and the components inside.
+ */
+
+/* ---- Type roles (three title levels + supporting text) -------------------------------------
+ * One role per level of hierarchy. Reach for these instead of re-using .fdy-card__title for a
+ * page title (the mistake that collapses three levels into one grey mush). */
+.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+.fdy-title-page{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:var(--leading-tight);color:var(--color-text);margin:0;text-wrap:balance;}
+.fdy-title-section{font-family:var(--font-display);font-size:var(--text-xl);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);line-height:var(--leading-snug);color:var(--color-text);margin:0;text-wrap:balance;}
+.fdy-title-card{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0;}
+.fdy-text-muted{color:var(--color-text-muted);}
+.fdy-text-subtle{color:var(--color-text-subtle);}
+.fdy-text-caption{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;}
+
+/* ---- Page: the vertical stack of sections, with the section rhythm between them ------------- */
+.fdy-page{display:flex;flex-direction:column;gap:var(--space-8);}
+
+/* ---- Page header: eyebrow + title + description on the left, primary action(s) on the right -- */
+.fdy-page__header{display:flex;align-items:flex-end;justify-content:space-between;gap:var(--space-4);flex-wrap:wrap;}
+.fdy-page__heading{display:flex;flex-direction:column;gap:var(--space-2);min-width:0;}
+.fdy-page__desc{font-size:var(--text-base);color:var(--color-text-muted);margin:0;max-width:62ch;line-height:var(--leading-normal);}
+.fdy-page__actions{display:flex;align-items:center;gap:var(--space-2);flex-wrap:wrap;}
+
+/* ---- Page section: a heading (+ optional toolbar) and its body, with the intra-group rhythm --- */
+.fdy-page-section{display:flex;flex-direction:column;gap:var(--space-4);}
+.fdy-page-section__head{display:flex;align-items:baseline;justify-content:space-between;gap:var(--space-3);flex-wrap:wrap;}
+
+/* ---- Toolbar: a horizontal control row (search + actions), wraps cleanly ---------------------- */
+.fdy-toolbar{display:flex;align-items:center;gap:var(--space-3);flex-wrap:wrap;}
+.fdy-toolbar__spacer{flex:1;}
+.fdy-toolbar__search{max-width:18rem;flex:1 1 12rem;}
+
+/* ---- Stat tile: a KPI metric that is deliberately NOT a card, so a KPI strip doesn't become an
+ * identical-white-card grid. Flat by default; wrap the .fdy-stats grid in one card if you want a
+ * single boxed strip, or use .fdy-stats--boxed for shared surface + dividers. */
+.fdy-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));gap:var(--space-5);}
+.fdy-stat{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;}
+.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+.fdy-stat__value{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:1;color:var(--color-text);font-variant-numeric:tabular-nums;}
+.fdy-stat__value small{font-size:var(--text-lg);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
+.fdy-stat__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);}
+.fdy-stats--boxed{background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);gap:0;}
+.fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
+.fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
+
 /* Freeday — Date picker (input-styled trigger + calendar popover).
  * Built by freeday-datepicker.js from an empty [data-fdy-datepicker] wrapper. */
 .fdy-datepicker{position:relative;display:inline-block;width:100%;max-width:14rem;}
@@ -857,6 +944,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-skeleton--text{height:.8rem;margin:.3rem 0;}
 .fdy-skeleton--title{height:1.2rem;width:40%;}
 .fdy-skeleton--circle{border-radius:var(--radius-full);}
+/* Size-matched to .fdy-avatar (2.5rem) and its --sm/--lg, so a skeleton reserves the exact avatar
+ * box and data landing causes no layout shift (a plain --circle has no dimensions of its own). */
+.fdy-skeleton--avatar{width:2.5rem;height:2.5rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-sm{width:2rem;height:2rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-lg{width:3.5rem;height:3.5rem;border-radius:var(--radius-full);}
 @keyframes fdy-skeleton{to{background-position:-200% 0;}}
 @media (prefers-reduced-motion:reduce){.fdy-skeleton{animation:none;}}
 

package/dist/freeday.d.ts

@@ -10,11 +10,16 @@ export interface FreedayToastOptions {
   message?: string;
   /** Milliseconds before auto-dismiss. Default 4000; 0 = sticky. */
   timeout?: number;
+  /** Stable id: a new toast with the same key replaces the existing one in place instead of
+   *  stacking a duplicate (e.g. a burst of identical failures shows one, refreshed). */
+  key?: string;
 }
 
 export interface FreedayGlobal {
   /** Show a transient toast in a live region (created on first use). Returns the toast element. */
   toast(opts?: FreedayToastOptions): HTMLElement;
+  /** Dismiss a toast early — pass the element returned by toast(), or a key string. */
+  dismiss(target: HTMLElement | string): void;
 }
 
 declare global {

package/dist/freeday.js

@@ -3319,16 +3319,26 @@
 })();
 
 /* Freeday — toast API (optional, zero-dependency).
- * Freeday.toast({ variant, title, message, timeout }) shows a transient
+ * Freeday.toast({ variant, title, message, timeout, key }) shows a transient
  * notification in a live region (created on first use). Returns the element.
  *   variant: 'success' | 'warning' | 'danger' | 'info' (default: neutral)
  *   timeout: ms before auto-dismiss (default 4000; 0 = sticky)
+ *   key:     optional stable id — a new toast with the same key REPLACES the
+ *            existing one in place instead of stacking a duplicate (e.g. a burst
+ *            of identical failures shows one toast, refreshed).
+ * Freeday.dismiss(nodeOrKey) closes a toast early (pass the returned element or its key).
  * Danger toasts use role="alert"; others role="status".
  */
 (function () {
   'use strict';
 
   var region = null;
+  var keyed = {}; // key -> current node, for replace-in-place + dismiss-by-key
+
+  function forget(node) {
+    var k = node && node._fdyKey;
+    if (k != null && keyed[k] === node) delete keyed[k];
+  }
 
   function ensureRegion() {
     if (region && document.body.contains(region)) return region;
@@ -3344,7 +3354,9 @@
   }
 
   function dismiss(toast) {
+    if (typeof toast === 'string') toast = keyed[toast]; // dismiss by key
     if (!toast || toast.dataset.leaving === '1') return;
+    forget(toast);
     toast.dataset.leaving = '1';
     toast.classList.add('is-leaving');
     var remove = function () { if (toast.parentNode) toast.parentNode.removeChild(toast); };
@@ -3384,6 +3396,14 @@
     node.appendChild(accent);
     node.appendChild(body);
     node.appendChild(close);
+
+    // Replace-in-place: a same-key toast removes the previous one so bursts don't stack.
+    if (opts.key != null) {
+      var prev = keyed[opts.key];
+      if (prev && prev.parentNode) prev.parentNode.removeChild(prev);
+      node._fdyKey = opts.key;
+      keyed[opts.key] = node;
+    }
     region.appendChild(node);
 
     var timeout = opts.timeout == null ? 4000 : opts.timeout;
@@ -3401,6 +3421,7 @@
 
   window.Freeday = window.Freeday || {};
   window.Freeday.toast = toast;
+  window.Freeday.dismiss = dismiss; // dismiss(nodeOrKey)
 })();
 
 /* Freeday — tree checkbox cascade (optional, zero-dependency).

package/dist/freeday.tokens.css

@@ -165,6 +165,14 @@
   --chart-8: #e34948;
   --chart-grid: var(--slate-200);
   --chart-tick: var(--slate-400);
+  --tone-1: var(--chart-1);
+  --tone-2: var(--chart-2);
+  --tone-3: var(--chart-3);
+  --tone-4: var(--chart-4);
+  --tone-5: var(--chart-5);
+  --tone-6: var(--chart-6);
+  --tone-7: var(--chart-7);
+  --tone-8: var(--chart-8);
   --focus-ring: var(--azure-600);
   --focus-ring-width: 2px;
 }
@@ -339,5 +347,9 @@
   --focus-ring: var(--azure-600);
 }
 :root[data-density="compact"] {
+  --space-3: 0.625rem;
+  --space-4: 0.75rem;
+  --space-5: 1rem;
+  --space-6: 1.25rem;
   --control-h: 2rem;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "tokens/breakpoints.d.ts",
     "README.md",
     "README.id.md",
+    "USAGE.md",
     "CHANGELOG.md"
   ],
   "exports": {
@@ -36,6 +37,7 @@
     "./css/components": { "types": "./dist/asset.d.ts", "default": "./dist/freeday.css" },
     "./tokens": { "types": "./dist/asset.d.ts", "default": "./dist/freeday.tokens.css" },
     "./breakpoints": { "types": "./tokens/breakpoints.d.ts", "default": "./tokens/breakpoints.mjs" },
+    "./table-model": { "types": "./adapters/core/table-model.d.ts", "default": "./adapters/core/table-model.js" },
     "./enhancers/*": { "types": "./dist/asset.d.ts", "default": "./dist/freeday-*.js" },
     "./vue": {
       "types": "./adapters/vue/index.d.ts",

package/src/base.css

@@ -15,6 +15,11 @@ a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
+ * margins (see the kit's own list components, which each reset themselves). If you run a utility
+ * framework with its preflight OFF (the recommended pairing), a semantic <ul>/<ol> keeps native
+ * bullets + a 40px indent; add this class (or a Freeday list component) to normalise it. */
+.fdy-list-reset { list-style: none; margin: 0; padding: 0; }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .001ms !important; transition-duration: .001ms !important; }
 }

package/src/components/avatar.css

@@ -6,3 +6,16 @@
 .fdy-avatar-group{display:inline-flex;}
 .fdy-avatar-group .fdy-avatar{border:2px solid var(--color-surface);margin-left:calc(var(--space-2)*-1);}
 .fdy-avatar-group .fdy-avatar:first-child{margin-left:0;}
+/* Decorative identity tones — a soft tint of a categorical chart colour with a theme-aware,
+ * text-leaning foreground so initials keep WCAG AA (verified >=4.5:1 in light & dark by
+ * test/contrast.test.mjs). Use to disambiguate same-initial avatars (e.g. many "PT …" names):
+ * hash a stable 1..8 index off the FULL name in your app, then apply .fdy-avatar--tone-<n>. */
+.fdy-avatar--tone-1,.fdy-avatar--tone-2,.fdy-avatar--tone-3,.fdy-avatar--tone-4,.fdy-avatar--tone-5,.fdy-avatar--tone-6,.fdy-avatar--tone-7,.fdy-avatar--tone-8{background:color-mix(in srgb,var(--_fdy-avatar-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-avatar-tone) 50%,var(--color-text));}
+.fdy-avatar--tone-1{--_fdy-avatar-tone:var(--tone-1);}
+.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--tone-2);}
+.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--tone-3);}
+.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--tone-4);}
+.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--tone-5);}
+.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--tone-6);}
+.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--tone-7);}
+.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--tone-8);}

package/src/components/card.css

@@ -3,6 +3,13 @@
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* The global reduced-motion reset kills the ANIMATION; drop the -3px shift too so the card
+ * doesn't jump. The shadow still communicates the affordance. */
+@media (prefers-reduced-motion:reduce){.fdy-card--interactive:hover{transform:none;}}
+/* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
+ * announced — reset the UA button box. Note: it does NOT reset background/border, because
+ * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
+.fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}

package/src/components/chip.css

@@ -1,6 +1,18 @@
 /* Freeday — Chip (tag / removable filter) */
 .fdy-chip{display:inline-flex;align-items:center;gap:var(--space-2);height:1.75rem;padding:0 var(--space-3);border-radius:var(--radius-full);font-size:var(--text-xs);font-weight:var(--weight-medium);color:var(--color-text);background:var(--color-surface-3);border:var(--bw) solid var(--color-border);}
 .fdy-chip--primary{color:var(--color-primary-strong);background:var(--color-primary-soft);border-color:color-mix(in srgb,var(--color-primary) 22%,transparent);}
+/* Categorical tone chips — non-semantic category tags / legend swatches, from the general
+ * --tone-1..8 palette. Same validated AA formula as .fdy-avatar--tone-* (text >=4.5:1 both themes,
+ * gated by test/contrast.test.mjs). */
+.fdy-chip--tone-1,.fdy-chip--tone-2,.fdy-chip--tone-3,.fdy-chip--tone-4,.fdy-chip--tone-5,.fdy-chip--tone-6,.fdy-chip--tone-7,.fdy-chip--tone-8{background:color-mix(in srgb,var(--_fdy-chip-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-chip-tone) 50%,var(--color-text));border-color:color-mix(in srgb,var(--_fdy-chip-tone) 30%,var(--color-border));}
+.fdy-chip--tone-1{--_fdy-chip-tone:var(--tone-1);}
+.fdy-chip--tone-2{--_fdy-chip-tone:var(--tone-2);}
+.fdy-chip--tone-3{--_fdy-chip-tone:var(--tone-3);}
+.fdy-chip--tone-4{--_fdy-chip-tone:var(--tone-4);}
+.fdy-chip--tone-5{--_fdy-chip-tone:var(--tone-5);}
+.fdy-chip--tone-6{--_fdy-chip-tone:var(--tone-6);}
+.fdy-chip--tone-7{--_fdy-chip-tone:var(--tone-7);}
+.fdy-chip--tone-8{--_fdy-chip-tone:var(--tone-8);}
 .fdy-chip__remove{display:inline-flex;align-items:center;justify-content:center;width:1.25rem;height:1.25rem;margin-right:calc(var(--space-1)*-1);border:0;padding:0;border-radius:var(--radius-full);background:transparent;color:currentColor;opacity:.6;cursor:pointer;font-size:var(--text-sm);line-height:1;}
 .fdy-chip__remove:hover{opacity:1;background:color-mix(in srgb,currentColor 16%,transparent);}
 .fdy-chip__remove:focus-visible{outline:none;opacity:1;box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}

package/src/components/composition.css

@@ -0,0 +1,49 @@
+/* Freeday — Page composition & type roles.
+ *
+ * The kit stops at the component; these primitives encode *how a page is assembled* so screens
+ * built by different people cohere. They carry the usage doctrine (see USAGE.md) in markup: a
+ * named type role gets used, a doc gets skimmed. Everything here is token-driven layout — no new
+ * colours, no new shadows. Pair with .fdy-app (the shell) and the components inside.
+ */
+
+/* ---- Type roles (three title levels + supporting text) -------------------------------------
+ * One role per level of hierarchy. Reach for these instead of re-using .fdy-card__title for a
+ * page title (the mistake that collapses three levels into one grey mush). */
+.fdy-eyebrow{font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+.fdy-title-page{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:var(--leading-tight);color:var(--color-text);margin:0;text-wrap:balance;}
+.fdy-title-section{font-family:var(--font-display);font-size:var(--text-xl);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);line-height:var(--leading-snug);color:var(--color-text);margin:0;text-wrap:balance;}
+.fdy-title-card{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0;}
+.fdy-text-muted{color:var(--color-text-muted);}
+.fdy-text-subtle{color:var(--color-text-subtle);}
+.fdy-text-caption{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;}
+
+/* ---- Page: the vertical stack of sections, with the section rhythm between them ------------- */
+.fdy-page{display:flex;flex-direction:column;gap:var(--space-8);}
+
+/* ---- Page header: eyebrow + title + description on the left, primary action(s) on the right -- */
+.fdy-page__header{display:flex;align-items:flex-end;justify-content:space-between;gap:var(--space-4);flex-wrap:wrap;}
+.fdy-page__heading{display:flex;flex-direction:column;gap:var(--space-2);min-width:0;}
+.fdy-page__desc{font-size:var(--text-base);color:var(--color-text-muted);margin:0;max-width:62ch;line-height:var(--leading-normal);}
+.fdy-page__actions{display:flex;align-items:center;gap:var(--space-2);flex-wrap:wrap;}
+
+/* ---- Page section: a heading (+ optional toolbar) and its body, with the intra-group rhythm --- */
+.fdy-page-section{display:flex;flex-direction:column;gap:var(--space-4);}
+.fdy-page-section__head{display:flex;align-items:baseline;justify-content:space-between;gap:var(--space-3);flex-wrap:wrap;}
+
+/* ---- Toolbar: a horizontal control row (search + actions), wraps cleanly ---------------------- */
+.fdy-toolbar{display:flex;align-items:center;gap:var(--space-3);flex-wrap:wrap;}
+.fdy-toolbar__spacer{flex:1;}
+.fdy-toolbar__search{max-width:18rem;flex:1 1 12rem;}
+
+/* ---- Stat tile: a KPI metric that is deliberately NOT a card, so a KPI strip doesn't become an
+ * identical-white-card grid. Flat by default; wrap the .fdy-stats grid in one card if you want a
+ * single boxed strip, or use .fdy-stats--boxed for shared surface + dividers. */
+.fdy-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));gap:var(--space-5);}
+.fdy-stat{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;}
+.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+.fdy-stat__value{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:1;color:var(--color-text);font-variant-numeric:tabular-nums;}
+.fdy-stat__value small{font-size:var(--text-lg);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
+.fdy-stat__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);}
+.fdy-stats--boxed{background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);gap:0;}
+.fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
+.fdy-stats--boxed .fdy-stat:last-child{border-right:0;}

package/src/components/skeleton.css

@@ -3,5 +3,10 @@
 .fdy-skeleton--text{height:.8rem;margin:.3rem 0;}
 .fdy-skeleton--title{height:1.2rem;width:40%;}
 .fdy-skeleton--circle{border-radius:var(--radius-full);}
+/* Size-matched to .fdy-avatar (2.5rem) and its --sm/--lg, so a skeleton reserves the exact avatar
+ * box and data landing causes no layout shift (a plain --circle has no dimensions of its own). */
+.fdy-skeleton--avatar{width:2.5rem;height:2.5rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-sm{width:2rem;height:2rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-lg{width:3.5rem;height:3.5rem;border-radius:var(--radius-full);}
 @keyframes fdy-skeleton{to{background-position:-200% 0;}}
 @media (prefers-reduced-motion:reduce){.fdy-skeleton{animation:none;}}

package/src/freeday-toast.js

@@ -1,14 +1,24 @@
 /* Freeday — toast API (optional, zero-dependency).
- * Freeday.toast({ variant, title, message, timeout }) shows a transient
+ * Freeday.toast({ variant, title, message, timeout, key }) shows a transient
  * notification in a live region (created on first use). Returns the element.
  *   variant: 'success' | 'warning' | 'danger' | 'info' (default: neutral)
  *   timeout: ms before auto-dismiss (default 4000; 0 = sticky)
+ *   key:     optional stable id — a new toast with the same key REPLACES the
+ *            existing one in place instead of stacking a duplicate (e.g. a burst
+ *            of identical failures shows one toast, refreshed).
+ * Freeday.dismiss(nodeOrKey) closes a toast early (pass the returned element or its key).
  * Danger toasts use role="alert"; others role="status".
  */
 (function () {
   'use strict';
 
   var region = null;
+  var keyed = {}; // key -> current node, for replace-in-place + dismiss-by-key
+
+  function forget(node) {
+    var k = node && node._fdyKey;
+    if (k != null && keyed[k] === node) delete keyed[k];
+  }
 
   function ensureRegion() {
     if (region && document.body.contains(region)) return region;
@@ -24,7 +34,9 @@
   }
 
   function dismiss(toast) {
+    if (typeof toast === 'string') toast = keyed[toast]; // dismiss by key
     if (!toast || toast.dataset.leaving === '1') return;
+    forget(toast);
     toast.dataset.leaving = '1';
     toast.classList.add('is-leaving');
     var remove = function () { if (toast.parentNode) toast.parentNode.removeChild(toast); };
@@ -64,6 +76,14 @@
     node.appendChild(accent);
     node.appendChild(body);
     node.appendChild(close);
+
+    // Replace-in-place: a same-key toast removes the previous one so bursts don't stack.
+    if (opts.key != null) {
+      var prev = keyed[opts.key];
+      if (prev && prev.parentNode) prev.parentNode.removeChild(prev);
+      node._fdyKey = opts.key;
+      keyed[opts.key] = node;
+    }
     region.appendChild(node);
 
     var timeout = opts.timeout == null ? 4000 : opts.timeout;
@@ -81,4 +101,5 @@
 
   window.Freeday = window.Freeday || {};
   window.Freeday.toast = toast;
+  window.Freeday.dismiss = dismiss; // dismiss(nodeOrKey)
 })();

package/tokens/tokens.json

@@ -42,8 +42,8 @@
   "weight": { "regular": { "$value": "400" }, "medium": { "$value": "500" }, "semibold": { "$value": "600" }, "bold": { "$value": "700" } },
 
   "space": {
-    "0": { "$value": "0" }, "1": { "$value": "0.25rem" }, "2": { "$value": "0.5rem" }, "3": { "$value": "0.75rem" },
-    "4": { "$value": "1rem" }, "5": { "$value": "1.25rem" }, "6": { "$value": "1.5rem" }, "8": { "$value": "2rem" },
+    "0": { "$value": "0" }, "1": { "$value": "0.25rem" }, "2": { "$value": "0.5rem" }, "3": { "$value": "0.75rem", "$compact": "0.625rem" },
+    "4": { "$value": "1rem", "$compact": "0.75rem" }, "5": { "$value": "1.25rem", "$compact": "1rem" }, "6": { "$value": "1.5rem", "$compact": "1.25rem" }, "8": { "$value": "2rem" },
     "10": { "$value": "2.5rem" }, "12": { "$value": "3rem" }, "16": { "$value": "4rem" }, "20": { "$value": "5rem" }, "24": { "$value": "6rem" }
   },
   "radius": { "xs": { "$value": "3px" }, "sm": { "$value": "4px" }, "md": { "$value": "6px" }, "lg": { "$value": "10px" }, "xl": { "$value": "14px" }, "full": { "$value": "999px" } },
@@ -118,6 +118,18 @@
     "tick": { "$value": "{slate.400}", "$dark": "{slate.600}" }
   },
 
+  "_comment_tone": "General categorical palette — the same 8 validated hues as chart, aliased under a chart-neutral name for avatars, chips, tags, legend swatches (theme-follows via chart's own $dark).",
+  "tone": {
+    "1": { "$value": "{chart.1}" },
+    "2": { "$value": "{chart.2}" },
+    "3": { "$value": "{chart.3}" },
+    "4": { "$value": "{chart.4}" },
+    "5": { "$value": "{chart.5}" },
+    "6": { "$value": "{chart.6}" },
+    "7": { "$value": "{chart.7}" },
+    "8": { "$value": "{chart.8}" }
+  },
+
   "focus-ring": { "$value": "{azure.600}", "$dark": "{azure.400}" },
   "focus-ring-width": { "$value": "2px" }
 }