@noxlovette/material 0.5.1 → 0.6.1

package/bin/material-claude-skill.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Installs the `material-design` Claude skill shipped with @noxlovette/material into the current
+// project's .claude/skills/. Usage: npx @noxlovette/material material-claude-skill [--force]
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const source = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'claude-skill',
+  'material-design'
+);
+const dest = path.resolve(process.cwd(), '.claude', 'skills', 'material-design');
+const force = process.argv.includes('--force');
+
+if (!fs.existsSync(source)) {
+  console.error(`Skill not found at ${source}; this package build doesn't include it.`);
+  process.exit(1);
+}
+if (fs.existsSync(dest) && !force) {
+  console.error(
+    `${path.relative(process.cwd(), dest)} already exists. Re-run with --force to overwrite it.`
+  );
+  process.exit(1);
+}
+
+fs.rmSync(dest, { recursive: true, force: true });
+fs.mkdirSync(path.dirname(dest), { recursive: true });
+fs.cpSync(source, dest, { recursive: true });
+console.log(`Installed the material-design skill into ${path.relative(process.cwd(), dest)}`);

package/claude-skill/material-design/SKILL.md

@@ -0,0 +1,68 @@
+---
+background: false
+description: Grounds UI/UX decisions in Material Design 3 (m3.material.io) and this repo's actual token/component system when creating or editing components in src/lib/components/, choosing a color role/variant/emphasis level, adding a transition or animation, laying out a showcase or docs page, or reviewing existing UI for M3 compliance. Does NOT apply to pure logic/state changes with no visual surface. For Cypress test authoring use cypress-author/cypress-explain/cypress-docs instead.
+model: inherit
+name: material-design
+---
+
+# Material Design 3 for @noxlovette/material
+
+## Purpose
+
+This repo is a single, already-opinionated M3 component library, not a blank canvas. Every visual decision (color, type, elevation, shape, motion) already has a token or utility class for it. The job here is never "invent a look" — it's "find the right existing primitive and apply it correctly." This skill encodes that mapping so you don't re-derive M3 from general knowledge or, worse, hardcode a hex/px/ms value that already has a token.
+
+## When to use
+
+- Creating or editing a component under `src/lib/components/`
+- Deciding which variant (filled/tonal/outlined/text/elevated) or color role (primary/secondary/tertiary/error) fits a given action or emphasis level
+- Adding a transition, page transition, or list/expand animation, or choosing between transition patterns (container transform vs forward/backward vs lateral vs top level vs enter/exit)
+- Building a showcase route or docs page for a component — these MUST be built from
+  `@noxlovette/material` components (`Pane`/`PaneGrid` for layout), never
+  hand-rolled flex/aside divs; see `references/component-patterns.md` for the pane decision table
+- Reviewing UI for M3 correctness (contrast, touch targets, focus, motion)
+
+**Skip this skill** for changes with no visual surface (pure logic, data layer, config), and for Cypress test work (use the `cypress-*` skills instead).
+
+## Reasoning flow
+
+1. **Map the ask to a category.** This repo groups components by M3 concept, not by page: `buttons/`, `forms/` (textfield, select, checkbox, switch, slider, radio-group, search, command, pin, tooltip), `containers/` (dialogue, side-sheet, bottom-sheet, popover, menu, list, panes, stack, scroll-area), `nav/` (appbar, navbar, rail, tabs), `cards/`, `badge/`, `pill/`, `snackbar/`, `progress/`, `table/`, `date/`, `time/`, `typography/`. Check the target category's existing `theme.ts` before writing a new one — the pattern you need probably already exists one file over.
+
+2. **Pick emphasis → variant + color role.** See the decision table below and `references/component-patterns.md` for the full reasoning and a worked example (`buttons/theme.ts`).
+
+3. **Only use existing tokens.** Never hardcode a color, shadow, radius, or duration — every one of those has a utility class already. Full inventory in `references/tokens-and-styles.md`.
+
+4. **Pick a motion primitive** from `src/lib/animation/` and a spring utility from `motion.css`. For any transition (a surface appearing, or content/screen changing), first choose the M3 pattern from the relationship between the two states. Is it a component entering this screen, a hero expanding, a parent/child step, peers in one set, or unrelated top-level destinations? Then check it against the qualities of a good transition: consistent, stable layout, no jump cuts, one direction, clean fades and a simple style. Both are covered in `references/motion-guide.md` → "Applying transitions", which is based on [m3.material.io → Applying transitions](https://m3.material.io/styles/motion/transitions/applying-transitions).
+
+5. **Run the pre-delivery checklist** in `references/accessibility-checklist.md` before calling the work done.
+
+## Color-role decision table
+
+| Emphasis                                                    | Variant    | Color role                             | Example use                                   |
+| ----------------------------------------------------------- | ---------- | -------------------------------------- | --------------------------------------------- |
+| Highest — one primary action per screen                     | `filled`   | `primary` (or `error` for destructive) | "Save", "Submit", "Delete account"            |
+| High but not _the_ action                                   | `filled`   | `secondary` / `tertiary`               | secondary CTA next to a filled-primary        |
+| Medium, wants to look "chosen"/selected                     | `tonal`    | matches the concept's color            | selected chip, toggle-on state, secondary FAB |
+| Medium, needs a visible boundary but low fill               | `outlined` | `primary`/matches concept              | "Cancel" next to a filled "Confirm"           |
+| Low, inline/repeated actions                                | `text`     | `primary` (default)                    | list-item trailing action, dialog "Cancel"    |
+| Needs to visually separate from a colored surface behind it | `elevated` | matches concept                        | FAB or card floating over a tonal surface     |
+
+`color: default` in this codebase's `tv()` variants resolves to the same classes as `primary` — pass `primary` explicitly when in doubt.
+
+## Quick reference
+
+- Color tokens: `md-sys-color-{primary,secondary,tertiary,error}`, each with a `-container` tonal pair and `on-*` text/icon pair (guarantees AA contrast by construction).
+- Type: `md-sys-typescale-{display,headline,title,body,label}-{large,medium,small}`, plus `md-sys-typescale-emphasized-*` for selected/active/unread states.
+- Spacing: `*-spacing-{0,25,50,75,100,…,900}` (M3 `md.sys.measurement.space*`, 8dp base: `p-spacing-200` = 16dp).
+- Elevation: `shadow-elevation-{0..5}`.
+- Shape: `radius-{none,xs,sm,md,lg,xl,full}` (buttons instead drive shape via the `--btn-shape`/`--btn-pressed-shape` CSS vars in `.md-btn-morph`).
+- Expressive shapes (circle, cookie, sunny, heart…): `animatableShapes`/`animatableShapesSmall` + `shapeMorph` for morphs. See motion-guide.md → "Shape morphing".
+- Motion: M3 Expressive springs only (`springTokens` in `animation/spring.ts`). JS: `presence`/`Presence` + `enterExit` presets, `containerTransform`, `sharedAxis`, `lateral`, `fadeThrough`, `skeleton` — all on Motion, never Svelte transitions. CSS: `transition-* md-sys-motion-{fast-spatial,spatial,slow-spatial,fast-effects,effects,slow-effects}` utilities, never `duration-*`/`ease-*`.
+- Transition pattern choice: appearing on this screen → enter/exit. Hero expands into its detail → container transform (only in shallow hierarchies). Parent/child or sequential steps → forward/backward (`sharedAxis`). Peers in one set → lateral, which never fades. Navbar/rail/drawer destinations → top level (`fadeThrough`), never lateral. Never use enter/exit or lateral for hierarchical navigation. Sheets slide without fading. Don't use bouncy (`fastSpatial`) springs for navigation transitions.
+- Shared primitives: wrap interactive surfaces with `Layer.svelte` (state layer + ripple, already skips itself under `prefers-reduced-motion`), render icons with `Icon.svelte`, use `Divider.svelte` instead of Bits UI's `Separator`.
+
+## References
+
+- [`references/tokens-and-styles.md`](references/tokens-and-styles.md) — full token/utility inventory
+- [`references/component-patterns.md`](references/component-patterns.md) — `tv()` slots/variants/compoundVariants pattern + variant decision tree
+- [`references/motion-guide.md`](references/motion-guide.md) — applying transitions (qualities of a good transition, choosing a pattern), which animation primitive and spring to reach for, reduced-motion target behavior
+- [`references/accessibility-checklist.md`](references/accessibility-checklist.md) — pre-delivery checklist

package/claude-skill/material-design/references/accessibility-checklist.md

@@ -0,0 +1,29 @@
+# Pre-delivery checklist
+
+Run through this before calling a component/UI change done.
+
+## Contrast
+
+- Text/icon color on a colored surface should always be the matching `on-*` token (`on-primary` on `primary`, `on-primary-container` on `primary-container`, etc.), never a manually chosen color — the `on-*` tokens are generated to meet contrast requirements per theme (including the `-hc`/`-mc` high/medium-contrast variants). A manual override bypasses that guarantee.
+- If a design calls for a color combination with no existing `on-*` pair, that's a sign it doesn't map to an M3 role cleanly — reconsider the role choice before improvising a color.
+
+## Touch targets
+
+- Interactive elements should hit the M3 minimum 48dp target. The existing `size` scales already encode this (e.g. button `sm`/`md` = `h-spacing-500`/`h-spacing-700`); when adding a new interactive size below that, either pad the hit area (see `.text-link`'s `min-height: 44px` + padding trick) or confirm it's genuinely dense-UI/desktop-only and document why.
+
+## Focus
+
+- Anything focusable needs a visible focus state — use `md-sys-state-focus-indicator`, don't rely on the browser default or remove `outline` without replacing it.
+- Verify keyboard operability, not just click handlers — Bits UI primitives (dialogs, menus, selects) handle this by default; if you're building something interactive from scratch, check it against Bits UI's docs (https://bits-ui.com/llms.txt) for the expected keyboard model first.
+
+## Motion
+
+- `prefers-reduced-motion`: M3 asks for subtle fades instead of intense slides or scales, and for decorative effects (parallax, shape morphing) to be turned off. Motion that carries meaning, such as confirming a drag-drop, can stay. Don't turn transitions into jump cuts. See `references/motion-guide.md` → "Reduced motion".
+- Transitions: is the pattern right for how the two states relate, and is it the same pattern this kind of change uses elsewhere? Is there no jump cut, no layout shift or content popping in, one primary direction of movement, no slow cross-fade (sheets slide without fading) and no bouncy spring on a navigation transition? See `references/motion-guide.md` → "Applying transitions".
+- Don't introduce a new hand-tuned duration/easing when an existing token fits — inconsistent timing across components is one of the more noticeable ways an M3 implementation starts to feel "off."
+
+## Consistency
+
+- No hardcoded hex/rgb colors, px shadows, px border-radius, or ms durations in new component code — every one of those should trace back to a token or utility from `references/tokens-and-styles.md`.
+- New multi-element components use `tv()` with `slots`, not string concatenation or `clsx` with inline conditionals.
+- Icons via `Icon.svelte`, dividers via `Divider.svelte`, state layers via `Layer.svelte` — grep for a raw `material-symbols-` class, a hand-rolled `<hr>`/border-based divider, or manual hover/press opacity as signs one of these was skipped.

package/claude-skill/material-design/references/component-patterns.md

@@ -0,0 +1,55 @@
+# Component patterns
+
+## The `tv()` shape
+
+Every component's styles live in the category's `theme.ts`, built with `tv()` from `tailwind-variants`:
+
+- `slots` — one key per rendered element (`base`, `icon`, `label`, ...) so multi-element components can vary each part independently
+- `variants` — one axis per meaningful design decision (`variant`, `color`, `size`, `shape`, `selected`, ...); each value maps to either a class string (single-slot components) or an object keyed by slot (multi-slot components)
+- `compoundVariants` — combinations that need a class not expressible as a union of independent axes (almost everything about color composition lives here, since `variant` × `color` isn't a clean cross-product of independent classes)
+
+Worked example: `src/lib/components/buttons/theme.ts`. The `button` export has slots `base`/`icon`; variants `variant` (elevated/filled/tonal/outlined/text/bare), `color` (default/primary/secondary/tertiary/error), `usage` (selection/default), `size` (xs/sm/md/lg/xl), `shape` (round/square), `selected` (true/false); and ~25 `compoundVariants` entries, one per `variant`×`color` pair, each pointing at the pre-built `md-component-button-*` class from `component.css`. Match this structure exactly for new component families — don't hand-roll `clsx` strings or inline conditional classes.
+
+When adding a `size` axis, follow the existing scale's _shape_, not just its numbers: each size variant sets height, gap, padding, typescale, and (for shape-driving components) the shape CSS vars together, in one slot-scoped string — not spread across multiple variant axes that a consumer could combine incorrectly.
+
+## Variant selection tree
+
+Ask, in order:
+
+1. **Is this the single highest-priority action on the screen/section?** → `filled`, `color: primary` (or `error` if destructive).
+2. **Is it a secondary but still prominent action, or a persistent selected/toggled state?** → `tonal`.
+3. **Does it need a visible boundary but shouldn't compete visually with a filled sibling?** → `outlined`.
+4. **Is it a low-emphasis, often-repeated action** (list rows, inline links, dialog dismiss)? → `text`.
+5. **Does it need to visually float above a surface that's already tonal/colored** (a FAB over a colored app bar, a card menu trigger)? → `elevated`.
+
+Only fall back to `bare` (no color/background at all) when the component supplies its own coloring downstream (e.g. an icon button whose color comes from a parent's `selected` state).
+
+## Reuse before you build
+
+- **State layer / ripple** — wrap the interactive element with `Layer.svelte` (`src/lib/utils/Layer.svelte`) rather than writing hover/press opacity by hand. It listens for `.m3-layer` on its parent, already respects `prefers-reduced-motion` for the ripple, and its tint intensity (hover 0.08 / pressed·focus 0.12) matches the M3 state-layer spec — don't retune those numbers per component.
+- **Icons** — always `Icon.svelte` (`name`, `fill`, `wght`, `size` props), never a raw `<span class="material-symbols-...">` or an inline SVG for a Material Symbol.
+- **Dividers** — `Divider.svelte`, not Bits UI's `Separator` (per project CLAUDE.md — it already implements the same primitive).
+- **Focus ring** — the `md-sys-state-focus-indicator` utility, not a custom `:focus` style.
+- **Disabled state** — `.md-component-button-base`'s disabled handling (via `disabled:`/`aria-disabled`/`data-disabled` selectors in `component.css`), not a manually-toggled opacity class.
+
+## Laying out a showcase or docs page (`src/routes/**`)
+
+Routes are not a blank canvas either — every page-level layout shape is built from the two
+`containers/pane` primitives, `Pane` and `PaneGrid`. Reach for these instead of a hand-rolled
+`flex`/`aside`/`sticky` div, and if a shape genuinely doesn't fit, that's a sign the pattern belongs
+in the library, not in a one-off route file:
+
+| Shape you need                                                  | Component                                                                            | Notes                                                                                                                                                                     |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Centered/full-width single column                               | `Pane` (standalone, no `PaneGrid`)                                                   | `centered` variant for max-width, `padding`/`gap` for spacing                                                                                                             |
+| User-resizable two-column split                                 | `PaneGrid` + `Pane width={...} resizable`                                            | The resizable `Pane` owns its own drag handle and width state; add `persistKey` for `localStorage` persistence                                                            |
+| Static sidebar that stays visible while its sibling scrolls     | `PaneGrid` + `Pane width={...} sticky`                                               | Native `position: sticky` — works inside any scrolling ancestor (the true page scroll or a bounded box), so this one prop covers what used to be two anchor modes         |
+| Main content + fixed-width side panel (TOC, filters, details)   | `PaneGrid direction={{ small: 'column', large: 'row' }}` + a `width`+`sticky` `Pane` | Stacks on small viewports, moves to a row from `large` up — the M3 [supporting-pane](https://m3.material.io/foundations/layout/canonical-layouts/supporting-pane) pattern |
+| List-detail, or any pane that should only show at certain sizes | `Pane visibleFrom="medium"` / `hiddenFrom="medium"`                                  | Toggles CSS display only, per Tailwind-aligned breakpoint (`small`/`medium`/`large`/`extraLarge` → unprefixed/`md:`/`lg:`/`xl:`)                                          |
+| Floating panel the user repositions (inspector, tool palette)   | `DraggablePane`                                                                      | Not a `PaneGrid` child — `position: fixed`, dragged by its header via `x`/`y` (bindable); `bounds`/`boundsPadding` clamp the drag, `persistKey` persists position         |
+
+See `/docs/pane` in the showcase site for the full prop reference and worked examples.
+
+## Before exporting a new component
+
+Follow CLAUDE.md's "Adding a New Component" steps as the mechanical checklist (create `.svelte` + `types.ts`, define `theme.ts` with `tv()`, export from the category `index.ts`, run `bun scripts/generate-components-index.ts`, add a showcase route and a docs page) — this skill governs the _design_ decisions (which variant/color/motion) that should be made before or while writing that `theme.ts`, not the export mechanics themselves.

package/claude-skill/material-design/references/motion-guide.md

@@ -0,0 +1,163 @@
+# Motion guide
+
+Source: `src/lib/animation/` (barrel-exported via `src/lib/animation/index.ts`) + spring tokens and utilities in `src/lib/styles/motion.css`. Live reference: Storybook → **Motion/Transition patterns** (one looping demo per M3 pattern).
+
+Two rules frame everything below:
+
+- **M3 Expressive springs are the only motion scheme.** There are no Standard-scheme springs and no hand-picked `ms` durations. Every animation — JS or CSS — resolves to one of the six spring tokens in `springTokens` (`spring.ts`).
+- **No Svelte transitions.** `in:`/`out:`/`transition:`/`animate:` are not used anywhere in the library. Mount/unmount and navigation motion goes through Motion (`motion` package, hybrid `animate()`/`animateView()`); state-driven motion (hover, press, selected, focus) stays as CSS transitions on the spring tokens.
+
+## Applying transitions
+
+Source: [m3.material.io → Transitions → Applying transitions](https://m3.material.io/styles/motion/transitions/applying-transitions). Read this section before picking a primitive, and use it to review any transition. M3 notes that its transition pages still describe the legacy easing-and-duration system and will move to the physics (spring) system. This library already runs on springs, so read "duration" below as "spring token" (see the spring table).
+
+### What makes a good transition
+
+| Quality                            | M3 rule                                                                                                                                                                                                                                                                                  | What it means here                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Follows accessibility settings** | With reduced motion on, use subtle fades instead of intense slides or scales, and turn off decorative effects such as parallax and shape morphing.                                                                                                                                       | This is not implemented yet (see [Reduced motion](#reduced-motion)). Don't add new parallax or morph effects that you couldn't easily switch off.                                                                                                                                                                    |
+| **Consistent**                     | Use the same transition type for the same kind of change everywhere, so the app feels like one cohesive family.                                                                                                                                                                          | Always use one primitive for one relationship. Every hierarchy step uses `sharedAxis` on the same axis, and every navbar/rail destination uses `fadeThrough`. Never mix patterns for the same kind of navigation.                                                                                                    |
+| **Stable layouts**                 | Use skeleton loaders so the layout holds still during a transition. Content shouldn't pop in or move around.                                                                                                                                                                             | Reserve the loaded content's footprint with `{@attach skeleton}` placeholders, then reveal the content with `presence(…, enterExit.fade)`. The content shouldn't be conditionally inserted in a way that shifts its siblings.                                                                                        |
+| **No jarring jump cuts**           | By default, avoid instant screen swaps because they disorient users. A jump cut is fine only when pure efficiency matters most, such as opening a menu in a productivity app.                                                                                                            | Surfaces and navigation always animate, which is why the ownership table below is mandatory. A jump cut has to be an explicit, documented choice, never the result of leaving the animation out.                                                                                                                     |
+| **Coherent spatial model**         | Transitions should teach the app's physical layout.                                                                                                                                                                                                                                      | A given relationship always moves along the same axis. For example, don't switch between horizontal and vertical when a collapsed view expands. If forward is `x`, backward is `x` reversed and never `y`.                                                                                                           |
+| **Unified direction**              | Group elements so they move along one primary axis. Only important elements, such as hero images, stay persistent. Don't animate many persistent elements independently.                                                                                                                 | Transition one `target` region as a unit. Don't give several children their own `animateView` targets or view-transition names. The only element that gets its own identity is the hero, which becomes the `containerTransform` `from`/`to`.                                                                         |
+| **Clean fades**                    | Fully fade out the old content before fading the new content in. If a cross-fade can't be avoided, keep it short and hide it in the fastest part of the motion. Don't slowly fade a component over other content while it enters or exits. A centered dialog may fade, but only briefly. | The view-transition helpers already do this: `old` fades on `fastEffects`, `new` fades on `effects` after a delay. Opacity on enter/exit presets always uses `fastEffects`. **Edge-anchored surfaces (bottom and side sheets) slide without any opacity.** Keep it that way, and never put opacity on a slow spring. |
+| **Simple style**                   | Transitions happen often, cover large parts of the screen and exist to help users finish a task. Common transitions shouldn't use overt style effects such as bouncy springs.                                                                                                            | Navigation primitives default to `spatial` (damping 0.8). Don't pass `fastSpatial` (damping 0.6, the bounciest spring) as the `spring` for `sharedAxis`/`lateral`/`fadeThrough`/`containerTransform`. Keep noticeable overshoot for small parts and direct feedback.                                                 |
+
+### Choosing a transition pattern
+
+| Pattern                  | Use for                                                                                                                                                                                                              | Don't use for                                                                                                                                                                                                                                                                                                                      |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Container transform**  | Hero moments that should feel expressive, shallow hierarchies where an element expands for detail and then collapses back, and creating a seamless connection between two elements. It is the most dramatic pattern. | Apps with deep hierarchies, where the motion becomes excessive, and utility-focused navigation. It needs a custom implementation and feels heavy when used often.                                                                                                                                                                  |
+| **Forward and backward** | Common hierarchical navigation. M3 recommends the platform default. On the web that's `sharedAxis` (`x` for steps, `z` for parent → child), because its motion style is simple.                                      | Hero moments, such as opening a photo memory. Use container transform for those.                                                                                                                                                                                                                                                   |
+| **Lateral**              | Browsing peer content in the same set, such as tabs in a media library or carousel pages. The horizontal slide suggests the area can be swiped.                                                                      | Hierarchical screens: a full-width slide is too much for a frequent transition and falsely suggests a peer relationship. Top-level destinations: it suggests a swipe that conflicts with carousels and swipeable list items. **Never fade while sliding**, because it hides the peer relationship and looks like forward/backward. |
+| **Top level**            | Moving between destinations from a navigation bar, rail or drawer, which use a quick fade (`fadeThrough`). The destinations aren't necessarily related, so the motion deliberately doesn't connect them.             | Anything that should read as related (use lateral or forward/backward).                                                                                                                                                                                                                                                            |
+| **Enter and exit**       | Bringing a component into the context of the current screen. It can be modal (a dialog that needs an action) or non-modal (a standard bottom sheet over a map, where both regions stay usable).                      | Navigating between hierarchical screens: a full-height slide is excessive and leaves the relationship between screens unclear.                                                                                                                                                                                                     |
+| **Skeleton loaders**     | Holding the layout still while content loads (see "Stable layouts").                                                                                                                                                 | Content that's already available. Animate it in instead of faking a load.                                                                                                                                                                                                                                                          |
+
+Quick decision: is a component appearing on this screen? **Enter/exit.** Is the user changing screens? Ask how the screens relate. If one element expands into its own detail as a hero moment, use **container transform**. If the screens are parent/child or sequential steps, use **forward/backward**. If they're siblings in one set, use **lateral**. If they're unrelated navbar/rail/drawer destinations, use **top level**.
+
+## Springs: spatial vs effects
+
+M3 principle: motion is **spatial** when something moves, resizes or reshapes; **effects** when only color/opacity change.
+
+| Token (`springTokens.*`) | Stiffness / damping ratio | Use for                                                                    |
+| ------------------------ | ------------------------- | -------------------------------------------------------------------------- |
+| `fastSpatial`            | 800 / 0.6 (~410ms)        | small parts & direct feedback: handles, indicators, chevrons, shape morphs |
+| `spatial`                | 380 / 0.8 (~490ms)        | component containers: dialogs, sheets, rail, navigation content            |
+| `slowSpatial`            | 200 / 0.8 (~660ms)        | large / full-screen surfaces                                               |
+| `fastEffects`            | 3800 / 1 (~190ms)         | hover/press/focus color, state layers, exits                               |
+| `effects`                | 1600 / 1 (~270ms)         | color/opacity changes on containers, fades                                 |
+| `slowEffects`            | 800 / 1 (~370ms)          | large-surface fades                                                        |
+
+Spatial springs overshoot by design (fast spatial most, at damping ratio 0.6); effects springs are critically damped. The `ms` values are CSS settle times — JS springs have no fixed duration. **Never put opacity on a spatial spring** — split per value instead (see `enterExit.ts`).
+
+## JS: picking a primitive
+
+| M3 pattern                                                        | Primitive                                                    | Notes                                                                                                                                                                                                                                                                                              |
+| ----------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Enter and exit** — a surface appears/leaves within the screen   | `presence(() => open, enterExit.<preset>)`                   | Attachment. Presets: `fade`, `scale` (menus/popovers/tooltips — sets `transform-origin` to bits-ui's anchor side, so never add an `origin-*` class), `slideUp` (snackbar), `dialog`, `sideSheet`, `bottomSheet`. Interruptible: reopening mid-exit retargets from the current value with velocity. |
+| Same, outside bits-ui (element must stay mounted during its exit) | `new Presence(() => open)`                                   | `{#if p.mounted}<div {@attach p.attach(enterExit.x)}>`. Construct during component init. Used by Snackbar, SideSheet, BottomSheet.                                                                                                                                                                 |
+| **Container transform** — card → detail, FAB → sheet              | `containerTransform(update, { from, to })`                   | Motion `animateView()` (View Transition API). `update` swaps the DOM (`async () => { open = true; await tick(); }`); `to` may be a selector for an element that only exists after the update.                                                                                                      |
+| **Forward and backward** — hierarchy levels, wizard steps         | `sharedAxis(update, { target, axis, direction })`            | `axis: 'x' \| 'y' \| 'z'`, `direction: 'forward' \| 'backward'`. `target` is the persistent region whose content changes; omit for the whole page.                                                                                                                                                 |
+| **Lateral** — peer screens (tabs, carousels)                      | `lateral(update, { target, direction })`                     | Edge-to-edge slide, no fade.                                                                                                                                                                                                                                                                       |
+| **Top level** — unrelated destinations (navigation bar)           | `fadeThrough(update, { target })`                            | Old fades out, new fades in scaling from 92%.                                                                                                                                                                                                                                                      |
+| **Skeleton loaders**                                              | `{@attach skeleton}` on the placeholder                      | Pulses until replaced; reveal the content with `presence(…, enterExit.fade)`.                                                                                                                                                                                                                      |
+| Anything custom                                                   | `animate(node, keyframes, springTransition(springTokens.x))` | `springTransition` converts a token to Motion's physics spring (`stiffness`/`damping`), which inherits velocity on interruption.                                                                                                                                                                   |
+
+### Which components must use which pattern
+
+A pattern belongs in a component only when that component owns both states of the change. When the content that changes lives outside the component (a route, an app screen), the app applies the pattern, not the library. Keep this table in sync when a component gains or loses one of these patterns; each primitive's JSDoc in `src/lib/animation/` repeats its own row.
+
+| Pattern                  | Built into (must use it)                                                                                                                                                       | Left to the app                                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| **Enter and exit**       | Dialogue, BottomSheet, SideSheet, Menu, MenuSub, ContextMenu, Popover, Tooltip, LinkPreview, Select, FABMenu, SplitButton, Snackbar, DateField/DateRangeField/TimeField popups | —                                                                                                              |
+| **Lateral**              | TabHolder (switching content panels); DateField/DateRangeField (changing the visible month, via `date/calendarMotion.ts`)                                                      | Navigation (`href`) tabs: the route change is the app's                                                        |
+| **Container transform**  | FAB → its `surface` (`FAB.svelte`: a clip-path and colour morph on Motion, not `containerTransform`)                                                                           | Card → detail, Carousel item → detail. `Search` has no search view to expand into; add it here if one is built |
+| **Forward and backward** | —                                                                                                                                                                              | Hierarchy levels, wizard steps                                                                                 |
+| **Top level**            | —                                                                                                                                                                              | Page changes from `Navbar`/`Rail`: they don't own the content region                                           |
+| **Skeleton loaders**     | —                                                                                                                                                                              | Placeholders for data the app loads                                                                            |
+
+A new component that mounts a surface must use enter/exit; one that pages between peer views (a stepper of equal steps) must use lateral. `Carousel` is not a pager: its motion is the scroll itself, items resizing through keylines. Opening a tapped item into its detail is a container transform the app applies.
+
+### bits-ui content
+
+bits-ui's presence layer waits for the content element's `getAnimations()` before unmounting, and Motion runs `transform`/`opacity` on WAAPI. So for any bits-ui `*.Content`: **drop `forceMount`, drop the `{#if open}` wrapper**, and attach `presence` to the element that receives `props`:
+
+```svelte
+<Popover.Content>
+  {#snippet child({ wrapperProps, props, open })}
+    <div {...wrapperProps}>
+      <div {...props} {@attach presence(() => open, enterExit.scale)}>…</div>
+    </div>
+  {/snippet}
+</Popover.Content>
+```
+
+Keep enter/exit keyframes to `transform` and `opacity` — a non-accelerated property falls back to a JS animation that `getAnimations()` can't see, and bits-ui will unmount before the exit plays.
+
+### View-transition patterns: limits
+
+`containerTransform`, `sharedAxis`, `lateral`, `fadeThrough` use the View Transition API: one transition per document at a time (Motion queues the next one rather than interrupting), snapshot-based, and a no-op animation (DOM update still runs) in browsers without the API.
+
+## Shape morphing
+
+The 35 M3 Expressive shapes (https://m3.material.io/styles/shape) ship in three sets in `src/lib/animation/`:
+
+| Set                                                                          | Points, viewBox                 | Morphable                            | Use for                                               |
+| ---------------------------------------------------------------------------- | ------------------------------- | ------------------------------------ | ----------------------------------------------------- |
+| `shapes.ts` (`pathCircle`, …)                                                | original Béziers, `0 0 380 380` | no, each path has its own structure  | static shapes only                                    |
+| `shapesAnimatable.ts` (`pathAnimatable*`, `animatableShapes`)                | 720, `0 0 380 380`              | yes, with any other path in this set | hero-sized shapes                                     |
+| `shapesAnimatableSmall.ts` (`pathAnimatableSmall*`, `animatableShapesSmall`) | 120, `0 0 48 48`                | yes, with any other path in this set | icons, avatars, indicators, FABs; about 1/8 the bytes |
+
+Within a set, every path has the same point count, start point and winding, so Motion's `mix` interpolates any pair without flipping or twisting. Never morph across sets.
+
+- **Morph with `shapeMorph(() => path)`** (attachment on a `<path>`) or `morphShape(pathEl, to)`. Both use `fastSpatial` by default, stop the previous morph and start from the shape on screen, and swap instantly under `prefers-reduced-motion`.
+- **Pick by name** with `animatableShapes[name]` / `animatableShapesSmall[name]` (`ShapeName`, `shapeNames`). A map pulls in its whole set, so import individual `pathAnimatable*` constants when bundle size matters.
+- `LoadingIndicator` morphs through seven of the small shapes (`LOADING_SHAPES`) on its own component spring.
+- Live demo: Storybook → Motion/Shapes.
+
+## CSS: state-driven transitions
+
+For hover/press/selected/focus motion driven by pseudo-classes or `data-*` state, use a Tailwind transition-property utility plus one spring utility from `motion.css`:
+
+```ts
+'transition-colors md-sys-motion-fast-effects'; // state color
+'transition-transform md-sys-motion-fast-spatial'; // indicator / chevron / handle
+'transition-[width,padding] md-sys-motion-spatial'; // container resize
+```
+
+Utilities: `md-sys-motion-{fast-spatial,spatial,slow-spatial,fast-effects,effects,slow-effects}`. They set duration + timing function together (and Tailwind's `--tw-duration`/`--tw-ease`, so they win over `transition-*` regardless of order). Never write `duration-200`, `ease-in-out`, bare `transition-colors` (Tailwind's 150ms default), or `transition-all`.
+
+In plain CSS (`component.css`, `<style>` blocks) use the variables directly: `transition: border-radius var(--md-sys-motion-duration-fast-spatial) var(--md-sys-motion-timing-function-fast-spatial);`. Button shape morphs use `fast-spatial` for both press and release — no separate accelerate/decelerate curves.
+
+**Don't hand-edit the spring tokens.** They sit between `@generated:springs` markers in `motion.css`. Change `springTokens` in `spring.ts`; the lefthook pre-commit job (`motion-springs`) regenerates and stages `motion.css` whenever `spring.ts`, the generator or `motion.css` is committed, and `bun run build` regenerates before packaging. To run it by hand: `bun run generate:springs`.
+
+The legacy easing-and-duration tokens (`--md-sys-motion-duration{,-fast,-slow}`, `-timing-function-emphasized*`) no longer exist.
+
+### Where the numbers come from
+
+m3.material.io describes the patterns but doesn't list scales or offsets; its reference implementation, Material Components Android (`lib/java/com/google/android/material/transition/`), does. Use these, don't invent new ones:
+
+| Value                                                 | Source                                                               |
+| ----------------------------------------------------- | -------------------------------------------------------------------- |
+| Enter from `scale(0.8)`, exit by fade only (`exited`) | `MaterialFade` / `ScaleProvider`                                     |
+| Shared axis X/Y: 30px slide                           | `mtrl_transition_shared_axis_slide_distance`                         |
+| Shared axis Z: in 0.8 → 1, out 1 → 1.1                | `ScaleProvider`                                                      |
+| Fade through: in from `scale(0.92)`                   | `MaterialFadeThrough`                                                |
+| Snackbar: slide by own height                         | `BaseTransientBottomBar` (slide mode)                                |
+| Spring tokens                                         | `motion/res/values/tokens.xml` (`m3_sys_motion_expressive_spring_*`) |
+
+MDC's own durations/easings (`short1`…`extraLong4` × `emphasized`/`standard`) are replaced by the spring tokens here. Still invented and flagged in code: the skeleton pulse hold (`skeleton.ts`), the 0.05s/0.09s fade-in delays in the view-transition patterns.
+
+`Layer.svelte`'s ripple also runs on Motion (scale + fade on `slowEffects`), so there's no fixed-curve animation left in the library.
+
+## Reduced motion
+
+Not implemented yet — tracked in https://github.com/noxlovette/material/issues/24. `Layer.svelte`'s ripple is the only thing that currently checks `prefers-reduced-motion`.
+
+Target behavior, per [Applying transitions](https://m3.material.io/styles/motion/transitions/applying-transitions). When `prefers-reduced-motion: reduce` is set:
+
+- **Swap movement for subtle fades rather than removing the transition** (a jump cut would break the "no jarring jump cuts" rule). `enterExit.scale`/`dialog`/`slideUp`/`sideSheet`/`bottomSheet` fall back to `enterExit.fade`. `sharedAxis`, `lateral` and `containerTransform` fall back to a `fadeThrough`-style opacity-only fade, with no translate or scale.
+- **Disable decorative effects**: shape morphing (button `--btn-shape` morphs; `morphShape`/`shapeMorph` already swap instantly), parallax, the ripple (already done).
+- Keep effects-spring color/opacity feedback (state layers, hover/press color), since that motion carries meaning and isn't intense.

package/claude-skill/material-design/references/tokens-and-styles.md

@@ -0,0 +1,68 @@
+# Tokens and styles inventory
+
+Source of truth: `src/lib/styles/*.css`. Rule: **never hardcode a color, shadow, radius, or duration value in a component — every one of these already has a token or utility class.** If you think you need a new value, check these files first; you're almost certainly missing an existing one.
+
+## Color roles (`src/lib/styles/theme/*.css`)
+
+Defined per theme variant (`light.css`, `dark.css`, `light-hc.css`, `dark-hc.css`, `light-mc.css`, `dark-mc.css` — high-contrast and medium-contrast accessibility variants) as `--md-sys-color-*` custom properties, consumed via Tailwind utilities of the form `bg-md-sys-color-*` / `text-md-sys-color-*` / `outline-md-sys-color-*`.
+
+- Core roles: `primary`, `secondary`, `tertiary`, `error`
+- Each has a low-emphasis tonal pair: `{role}-container`
+- Each (including containers) has a guaranteed-contrast text/icon pair: `on-{role}`, `on-{role}-container`
+- Surface roles: `surface`, `surface-variant`, `surface-container` (`-lowest`, `-low`, `-high`, `-highest`), `on-surface`, `on-surface-variant`
+- Structural: `outline`, `outline-variant`, `shadow`
+
+Because `on-*` pairs are generated to meet contrast requirements, **any manual color override that doesn't go through an `on-*`/role pair is a contrast bug waiting to happen** — flag it in review.
+
+## Component color composition (`src/lib/styles/component.css`)
+
+Components don't reference `md-sys-color-*` directly for every state — they compose pre-built classes:
+
+```
+md-component-button-filled-{default,primary,secondary,tertiary,error}
+md-component-button-tonal-{default,primary,secondary,tertiary,error}
+md-component-button-outline-{default,primary,secondary,tertiary,error}
+md-component-button-text-{default,primary,secondary,tertiary,error}
+md-component-button-elevated-{default,primary,secondary,tertiary,error}
+```
+
+`filled` = `bg-md-sys-color-{role} text-md-sys-color-on-{role}`. `tonal` = the `-container`/`on-{role}-container` pair. `outlined` = `text-md-sys-color-{role} outline-md-sys-color-{role}` (default outline uses `on-surface-variant`/`outline-variant`). `text` = text color only, transparent background. `elevated` = `bg-md-sys-color-surface-container-low` + role text color + `shadow-elevation-1`. When adding a new component family with the same emphasis levels, follow this exact composition rather than reinventing it.
+
+Other reusable utilities in this file:
+
+- `.state-layer` — the `::before` overlay hook that `Layer.svelte` and hover/press states build on
+- `md-sys-state-focus-indicator` — the `:focus-visible` outline (3px solid, `on-secondary` color, 2px offset) — apply to anything focusable that doesn't already get it via a shared base class
+- `.md-component-button-base` — disabled-state handling (`on-surface` at reduced opacity) + cursor — reuse for any new interactive component base
+
+## Typescale (`src/lib/styles/typescale.css`)
+
+The full M3 type scale (https://m3.material.io/styles/typography/type-scale-tokens), in rem:
+
+- `md-sys-typescale-{display,headline,title,body,label}-{large,medium,small}`: the 15 baseline styles. Each sets font family, weight, size, line height, and tracking. Don't set `text-*`/`leading-*`/`tracking-*`/`font-*` next to one; pick a different style instead.
+- `md-sys-typescale-emphasized-<style>`: the 15 emphasized styles. They have the same metrics and a heavier weight (400 → 500, 500 → 700). Components use baseline by default. Swap in the emphasized style for selected or active states, unread items, primary-action buttons, badges and the extended FAB. Don't add `font-bold` to a baseline style.
+- `md-sys-typescale-label-{large,medium}-prominent`: the `weight.prominent` (700) label tokens.
+- Typefaces: display, headline and title-large use `--md-ref-typeface-brand`; everything else uses `--md-ref-typeface-plain`. Both default to `--font-sans`; M3's own default is Roboto.
+- Line heights follow the language-height category of the element's `lang`: small (Latin, Cyrillic, Greek, Hebrew), medium (CJK, Arabic, Indic, Thai, Vietnamese…), large (Burmese, Telugu), extra-large (Urdu/Nastaliq). Force a category with `data-md-language-height="small|medium|large|extra-large"`.
+
+## Spacing (`src/lib/styles/spacing.css`)
+
+`md.sys.measurement.space<N>` (N/100 × the 8dp base) is registered in Tailwind's spacing namespace. Every spacing utility therefore takes it: `p-spacing-200` (16dp), `gap-spacing-50` (4dp), `mr-spacing-300` (24dp), `size-spacing-600` (48dp). The available numbers are 0, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 400, 450, 500, 600, 700, 800 and 900. The number is M3's token number, not Tailwind's 4px multiplier.
+
+## Elevation (`src/lib/styles/elevation.css`)
+
+`shadow-elevation-{0..5}`, each a two-layer (spot + ambient) shadow scaled to the M3 elevation spec, using `color-mix` against the `shadow` color role so it adapts per theme automatically. Elevation communicates depth/priority — reach for a higher level when a surface should read as "above" its neighbors (menus, FABs, dialogs), not as a decorative effect.
+
+## Shape (`src/lib/styles/rounding.css`)
+
+`radius-{none,xs,sm,md,lg,xl,full}` = `0 / 4px / 8px / 12px / 16px / 28px / 9999px`, matching the M3 shape scale (extra-small through extra-large, plus full/pill). Buttons don't use these directly — they use CSS custom properties (`--btn-shape`, `--btn-shape-override`, `--btn-pressed-shape` set per `size`/`shape` variant in `theme.ts`) consumed by the `.md-btn-morph` utility, which also animates the radius on press (a deliberate M3 "morph" detail — don't remove it when adding button variants).
+
+## Motion (`src/lib/styles/motion.css`)
+
+M3 Expressive springs only, generated from `springTokens` in `src/lib/animation/spring.ts` (never hand-edited — a lefthook pre-commit job regenerates them). Each spring exposes `--md-sys-motion-timing-function-<name>` (a `linear()` curve), `--md-sys-motion-duration-<name>` (its settle time) and `--md-sys-motion-easing-<name>` (both combined):
+
+- **Spatial** (things that move, resize, or morph — overshoot): `fast-spatial` (410ms), `spatial` (490ms), `slow-spatial` (660ms)
+- **Effects** (color/opacity — no overshoot): `fast-effects-spring` (190ms), `effects-spring` (270ms), `slow-effects-spring` (370ms)
+
+In Tailwind classes use the utilities instead: `md-sys-motion-{fast-spatial,spatial,slow-spatial,fast-effects,effects,slow-effects}` alongside a `transition-*` property utility. There are no standard/emphasized easing tokens.
+
+Full decision guidance for motion lives in `references/motion-guide.md` — don't just guess a duration.

package/dist/animation/Shapes.stories.svelte

@@ -26,26 +26,30 @@
 </script>
 
 <Story name="Shape library" asChild>
-  <div class="flex flex-col gap-6">
-    <div class="flex items-center gap-6">
+  <div class="gap-spacing-300 flex flex-col">
+    <div class="gap-spacing-300 flex items-center">
       <svg viewBox="0 0 380 380" class="text-md-sys-color-primary size-48" aria-hidden="true">
         <path fill="currentColor" {@attach shapeMorph(() => animatableShapes[selected])} />
       </svg>
-      <svg viewBox="0 0 48 48" class="text-md-sys-color-tertiary size-12" aria-hidden="true">
+      <svg
+        viewBox="0 0 48 48"
+        class="text-md-sys-color-tertiary size-spacing-600"
+        aria-hidden="true"
+      >
         <path fill="currentColor" {@attach shapeMorph(() => animatableShapesSmall[selected])} />
       </svg>
       <Body>{selected}</Body>
     </div>
 
-    <div class="grid grid-cols-5 gap-2 sm:grid-cols-7">
+    <div class="gap-spacing-100 grid grid-cols-5 sm:grid-cols-7">
       {#each shapeNames as name (name)}
         <button
           type="button"
           aria-pressed={selected === name}
           onclick={() => (selected = name)}
-          class="md-sys-typescale-label-small text-md-sys-color-on-surface-variant aria-pressed:bg-md-sys-color-secondary-container aria-pressed:text-md-sys-color-on-secondary-container flex flex-col items-center gap-1 rounded-md p-2"
+          class="md-sys-typescale-label-small text-md-sys-color-on-surface-variant aria-pressed:bg-md-sys-color-secondary-container aria-pressed:text-md-sys-color-on-secondary-container gap-spacing-50 p-spacing-100 flex flex-col items-center rounded-md"
         >
-          <svg viewBox="0 0 48 48" class="size-10" aria-hidden="true">
+          <svg viewBox="0 0 48 48" class="size-spacing-500" aria-hidden="true">
             <path fill="currentColor" d={animatableShapesSmall[name]} />
           </svg>
           {name}