@noxlovette/material 0.4.2 → 0.4.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danila Volkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,88 @@
-# Google's Material Design System in Svelte
+# @noxlovette/material
+
+**Google's [Material Design 3](https://m3.material.io/) system, built for Svelte.**
+
+Every component is a real MD3 citizen — the token vocabulary (color roles, typescale,
+elevation, shape, motion), the state layers, the canonical layouts — implemented on top of
+[Bits UI](https://bits-ui.com/)'s headless primitives and styled with
+[`tailwind-variants`](https://www.tailwind-variants.org/). You get the accessibility and
+interaction behavior Bits UI already gets right, with Material's actual look and feel on top.
+
+[![npm version](https://img.shields.io/npm/v/%40noxlovette%2Fmaterial.svg)](https://www.npmjs.com/package/@noxlovette/material)
+[![npm downloads](https://img.shields.io/npm/dm/%40noxlovette%2Fmaterial.svg)](https://www.npmjs.com/package/@noxlovette/material)
+[![CI](https://github.com/noxlovette/material/actions/workflows/ci.yml/badge.svg)](https://github.com/noxlovette/material/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/npm/l/%40noxlovette%2Fmaterial.svg)](./LICENSE)
+
+**[📖 Docs & overview](https://material.noxlovette.com)** · **[🧩 Storybook — browse every component live](https://material.noxlovette.com/storybook/)**
+
+Storybook is the canonical place to actually look at things: every component, every variant,
+with Controls to poke at props and an a11y panel to check contrast and roles as you go. The
+docs site is prose — install steps, theming, rationale — and links out to Storybook rather
+than re-implementing a gallery of its own.
+
+## Install
+
+```bash
+npm i @noxlovette/material
+```
+
+```css
+/* your root stylesheet */
+@import 'tailwindcss';
+@import '@noxlovette/material/styles';
+@import '@noxlovette/material/theme/light';
+@import '@noxlovette/material/theme/dark';
+```
+
+```svelte
+<script lang="ts">
+  import { App, Button, Card, Title } from '@noxlovette/material';
+</script>
+
+<App>
+  <Card class="p-4">
+    <Title>Hello world</Title>
+    <Button>Click me</Button>
+  </Card>
+</App>
+```
+
+`App` wires up theming, dark-mode detection, and icon loading. Dynamic theming (generate a
+whole MD3 theme from a source color or an image, toggle light/dark/contrast at runtime) is
+covered on the [docs site](https://material.noxlovette.com), along with the SSR setup that
+avoids a flash of unstyled content.
+
+## What's inside
+
+Buttons, cards, dialogs, navigation rail/bar, side sheets, snackbars, tabs, sliders, chips,
+menus, text fields, and the rest of the MD3 component set, plus `Pane`/`PaneGrid` for
+Material's [canonical layouts](https://m3.material.io/foundations/layout/canonical-layouts)
+(list-detail, supporting-pane, feed) without hand-rolling flex/sticky positioning yourself.
+The full list, with live previews, is in [Storybook](https://material.noxlovette.com/storybook/).
+
+A Claude Code skill ships alongside the library — `npx @noxlovette/material material-claude-skill`
+installs it into `.claude/skills/material-design`, so an agent working in your app gets the
+same token vocabulary and variant-selection rules this library was built with.
+
+## Credits
+
+- [**Material Design 3**](https://m3.material.io/) — the design system itself. All token
+  names, color roles, and layout patterns here are Google's, not reinvented.
+- [**Bits UI**](https://bits-ui.com/) — the headless primitives underneath every interactive
+  component. This library owes its accessibility behavior and interaction correctness to it;
+  ours is the Material skin on top.
+
+## Contributing
+
+```bash
+bun run dev              # showcase site: landing page + prose docs
+bun run storybook        # component workbench — the canonical way to view/QA components
+bun run check             # svelte-check + tsc
+bun run test              # vitest
+```
+
+See [`CLAUDE.md`](./CLAUDE.md) for the fuller architecture rundown and known pitfalls.
+
+## License
+
+[MIT](./LICENSE)

package/dist/components/containers/bottom-sheet/BottomSheet.svelte

@@ -61,7 +61,7 @@ while keeping the main screen content visible.
 />
 
 <dialog
-  class="bg-md-sys-color-surface-container-low mx-auto mt-auto w-full max-w-2xl overflow-hidden rounded-t-md"
+  class="bg-md-sys-color-surface-container-low text-md-sys-color-on-surface mx-auto mt-auto w-full max-w-2xl overflow-hidden rounded-t-md"
   style:max-height="{height}px"
   use:open
   use:outroClass

package/dist/components/containers/side-sheet/SideSheet.svelte

@@ -34,7 +34,7 @@ rendering the component ({#if open}<SideSheet ...>{/if}).
 </script>
 
 <dialog
-  class="bg-md-sys-color-surface-container-low fixed inset-y-0 right-0 left-auto m-0 h-full w-full max-w-sm rounded-l-md"
+  class="bg-md-sys-color-surface-container-low text-md-sys-color-on-surface fixed inset-y-0 right-0 left-auto m-0 h-full w-full max-w-sm rounded-l-md"
   use:open
   use:outroClass
   oncancel={(e) => {

package/dist/components/nav/appbar/AppBar.svelte

@@ -21,6 +21,8 @@ comment.
     children,
     title,
     subtitle,
+    titleProps,
+    subtitleProps,
     trailing,
     leading,
     class: className,
@@ -74,11 +76,13 @@ comment.
       {@render leading?.()}
     </div>
     <div class={textContainer()}>
-      <h1 class={titleCLs()}>
+      <h1 class={titleCLs({ class: clsx(titleProps?.class) })} {...titleProps}>
         {title}
       </h1>
       {#if subtitle}
-        <p class={subtitleCls()}>{subtitle}</p>
+        <p class={subtitleCls({ class: clsx(subtitleProps?.class) })} {...subtitleProps}>
+          {subtitle}
+        </p>
       {/if}
     </div>
     <div class={trailingCls()}>

package/dist/components/nav/appbar/types.d.ts

@@ -11,6 +11,10 @@ export type AppBarProps = AppbarVariants & HTMLAttributes<HTMLElementTagNameMap[
     title: string;
     /** An optional subtitle displayed below the title. */
     subtitle?: string;
+    /** Additional props for the title `<h1>` element (e.g. `data-cy`). */
+    titleProps?: HTMLAttributes<HTMLHeadingElement>;
+    /** Additional props for the subtitle `<p>` element (e.g. `data-cy`). */
+    subtitleProps?: HTMLAttributes<HTMLParagraphElement>;
     /** A snippet to be rendered on the left side (e.g., navigation icon). */
     leading?: Snippet;
     /** A snippet to be rendered on the right side (e.g., action icons). */

package/dist/utils/Theme.svelte.d.ts

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    generateCSS?: boolean;
+};
+declare const Theme: import("svelte").Component<$$ComponentProps, {}, "">;
+type Theme = ReturnType<typeof Theme>;
+export default Theme;

package/package.json

@@ -1,13 +1,30 @@
 {
   "name": "@noxlovette/material",
-  "version": "0.4.2",
+  "version": "0.4.7",
   "type": "module",
+  "description": "A Material Design 3 component library for Svelte, built on Bits UI.",
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "material-design",
+    "material-you",
+    "md3",
+    "component-library",
+    "bits-ui",
+    "ui"
+  ],
   "license": "MIT",
+  "homepage": "https://material.noxlovette.com",
   "repository": {
-    "url": "git+https://codeberg.org/noxlovette/material.git"
+    "type": "git",
+    "url": "git+https://github.com/noxlovette/material.git"
+  },
+  "bugs": {
+    "url": "https://github.com/noxlovette/material/issues"
   },
   "scripts": {
     "build": "svelte-package",
+    "build:site": "vite build",
     "watch": "svelte-package --watch",
     "prepublishOnly": "bun run build",
     "check": "svelte-kit sync && svelte-check",
@@ -16,6 +33,7 @@
     "dev": "vite dev",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
+    "publint": "publint",
     "index": "bun run scripts/generate-components-index.ts"
   },
   "files": [

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

@@ -1,65 +0,0 @@
----
-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
-- Building a showcase route or docs page for a component — these MUST be built from
-  `@noxlovette/material` components (`SinglePane`/`SplitPane`/`SupportingPane` 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 duration/easing pair from `motion.css`. Decision rules in `references/motion-guide.md`.
-
-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}`.
-- 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`).
-- Motion durations/easings: `--md-sys-motion-duration{,-fast,-slow}` (standard, non-spatial) and `-fast-spatial/-spatial/-slow-spatial` (expressive, for things that move/resize), plus the M3 emphasized easing curve.
-- 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) — which animation primitive and timing pair to reach for
-- [`references/accessibility-checklist.md`](references/accessibility-checklist.md) — pre-delivery checklist

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

@@ -1,28 +0,0 @@
-# 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-10`/`h-14`); 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`: decorative-only motion should be gated (see `references/motion-guide.md`); motion that carries meaning (e.g. confirming a drag-drop) can stay.
-- 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

@@ -1,52 +0,0 @@
-# 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 already has a `containers/panes`
-component. Reach for these instead of a hand-rolled `flex`/`aside`/`sticky` div, and if none fits,
-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                                                                   | `SinglePane`                                      | `centered` variant for max-width, `padding`/`gap` for spacing                                                 |
-| User-resizable two-column split                                                                     | `SplitPane` (`resizable` default)                 | Drag handle + `localStorage` persistence                                                                      |
-| Static, non-draggable sidebar fixed to the true viewport edge                                       | `SplitPane` `anchor="viewport" resizable={false}` | Only correct if this is the outermost positioned element (nothing else is already offsetting content)         |
-| Static sidebar absolutely positioned in a bounded/contained box                                     | `SplitPane` `anchor="parent" resizable={false}`   | Does not stay visible while the page scrolls — for embedded demos, not full-page nav                          |
-| Static sidebar nested inside other already-offset content, that should stay visible while scrolling | `SplitPane` `anchor="sticky" resizable={false}`   | e.g. the docs secondary component-list nav, nested inside the root layout's Rail-offset column                |
-| Main content + fixed-width side panel (TOC, filters, details)                                       | `SupportingPane` `anchor="parent"`                | The M3 [supporting-pane](https://m3.material.io/foundations/layout/canonical-layouts/supporting-pane) pattern |
-
-## 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

@@ -1,25 +0,0 @@
-# Motion guide
-
-Source: `src/lib/animation/` (barrel-exported via `src/lib/animation/index.ts`) + duration/easing tokens in `src/lib/styles/motion.css`. M3 motion principle to apply: motion should be **spatial** (things visibly move/resize/morph) when the UI's structure is changing, and **standard/non-spatial** (opacity/color only) when it's a simple state change — spatial motion on a small state change reads as sluggish; standard easing on a big layout change reads as a jump-cut.
-
-## Picking a primitive
-
-| Situation                                                                                                | Primitive              | Notes                                                                                                                                                                                                                                                                                  |
-| -------------------------------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A surface expands into another (card → dialog, thumbnail → detail view, FAB → sheet)                     | `containerTransform`   | Crossfades + morphs bounds/radius/color between the two elements sharing a `key`. Needs two DOM nodes in a Svelte `{#key}`/list-transition context, not a single toggled element.                                                                                                      |
-| Stepped/sequential navigation (wizard steps, tabs, paginated content)                                    | `sharedAxisTransition` | Pick `direction: 'X'` for horizontal steps, `'Y'` for vertical, `'Z'` for depth (e.g. modal-like overlays that don't share geometry). Set `rightSeam`/`leaving` per the doc-comment in `sharedAxisTransition.ts` — getting the boolean backwards makes both directions look identical. |
-| Simple show/hide with no structural relationship between what's leaving and entering                     | `enterExit`            | `mode` options: `fade` (default), `scale`, `slide-up`, `dialog`, `dialog-m3`. Use `dialog-m3` for actual M3 dialogs/sheets (scale-only, no vertical translate) — `dialog`/`slide-up` are for non-M3-spec popovers/toasts.                                                              |
-| A list item needs a CSS hook while it's animating out (e.g. to suppress hover/press styles during outro) | `outroClass`           | Svelte action; adds/removes a `leaving` class on `outrostart`/`outroend`.                                                                                                                                                                                                              |
-
-All three transition functions default their `easing` to `easeEmphasized` (from `easing.ts`) already — only override `easing`/`duration` when the default doesn't fit, and when you do, pull from the named exports (`easeEmphasized`, `easeEmphasizedAccel`, `easeEmphasizedDecel`, `easeStandard`, `easeStandardAccel`, `easeStandardDecel`), not a raw `cubic-bezier(...)`.
-
-## Picking a duration when hand-rolling CSS transitions
-
-For anything not going through the animation module (e.g. a plain CSS `transition` on `theme.ts`-driven classes), use the `--md-sys-motion-easing*` custom properties from `motion.css` directly, chosen by what's animating:
-
-- **Standard** (`easing` 200ms / `easing-fast` 150ms / `easing-slow` 300ms) — color, opacity, elevation, focus ring: small/local, non-spatial changes. `.state-layer` and `.text-link` already use these.
-- **Expressive/spatial** (`easing-fast-spatial` 350ms / `easing-spatial` 500ms / `easing-slow-spatial` 650ms) — anything that changes position, size, or shape. Bigger/farther-traveling elements get the slower tier; small in-place morphs (like the button's press-radius morph in `.md-btn-morph`) use a fast, hand-tuned duration instead of these tiers because they're driven by direct user press feedback, not a triggered transition.
-
-## Reduced motion
-
-`Layer.svelte`'s ripple already checks `prefers-reduced-motion` and no-ops. The `containerTransform`/`sharedAxisTransition`/`enterExit` functions do **not** self-guard — if you use them for a transition that isn't purely decorative (i.e. skipping it would leave the UI in a confusing state), that's fine as-is, but for a purely decorative flourish, gate it on `prefers-reduced-motion` at the call site rather than assuming the animation module handles it for you.

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

@@ -1,57 +0,0 @@
-# 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`)
-
-`md-sys-typescale-{display,headline,title,body,label}-{large,medium,small}`, plus a one-off `md-sys-typescale-fab-label`. Each bakes in the correct font size, line height, tracking, and (for title/label) weight — don't set `text-*`/`leading-*`/`tracking-*` manually when one of these fits.
-
-## 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`)
-
-Two families of duration/easing pairs, exposed as `--md-sys-motion-easing*` custom properties combining a timing function + duration:
-
-- **Standard** (color/opacity/simple UI changes): `easing` (200ms), `easing-fast` (150ms), `easing-slow` (300ms)
-- **Expressive/spatial** (things that move, resize, or morph): `easing-fast-spatial` (350ms), `easing-spatial` (500ms), `easing-slow-spatial` (650ms)
-- The M3 "emphasized" curve is also available as three raw timing functions (`emphasized`, `emphasized-accel`, `emphasized-decel`) for hand-rolled transitions — see `references/motion-guide.md` for when to use these vs. the animation module.
-
-Full decision guidance for motion lives in `references/motion-guide.md` — don't just guess a duration.