@cahyo-dimas/freeday 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 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

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.17.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.17.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,8 +49,18 @@ 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`. Layout (stack/grid/gap) dari layer-mu sendiri —
+> 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

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.17.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.17.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,13 +49,23 @@ 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`. Bring your own layout 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).
+> 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`

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.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;
 }
 
@@ -534,14 +546,14 @@ a { color: var(--color-primary); }
  * 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(--chart-1);}
-.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--chart-2);}
-.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--chart-3);}
-.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--chart-4);}
-.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--chart-5);}
-.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--chart-6);}
-.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--chart-7);}
-.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--chart-8);}
+.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);}
@@ -661,6 +673,9 @@ 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). */
@@ -816,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);}
@@ -865,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;}

package/dist/freeday.css

@@ -189,14 +189,14 @@ a { color: var(--color-primary); }
  * 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(--chart-1);}
-.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--chart-2);}
-.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--chart-3);}
-.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--chart-4);}
-.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--chart-5);}
-.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--chart-6);}
-.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--chart-7);}
-.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--chart-8);}
+.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);}
@@ -316,6 +316,9 @@ 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). */
@@ -471,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);}
@@ -520,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;}

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.17.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/components/avatar.css

@@ -11,11 +11,11 @@
  * 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(--chart-1);}
-.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--chart-2);}
-.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--chart-3);}
-.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--chart-4);}
-.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--chart-5);}
-.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--chart-6);}
-.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--chart-7);}
-.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--chart-8);}
+.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,9 @@
 .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). */

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/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" }
 }