@noxlovette/material 0.5.0 → 0.6.0

package/dist/animation/sharedAxisTransition.d.ts

@@ -17,20 +17,42 @@ export interface SharedAxisOptions extends NavigationOptions {
  * axis while fading through each other.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#forward-and-backward
  *
+ * The default for common hierarchical navigation (https://m3.material.io/styles/motion/transitions/applying-transitions).
+ * Don't use it for hero moments; use `containerTransform` for those. Keep one axis per relationship
+ * across the app (coherent spatial model), and move one `target` region as a unit instead of
+ * animating many elements independently.
+ *
  * `update` performs the DOM change (`async () => { step++; await tick(); }`). Built on Motion's
  * `animateView()` — both states never need to coexist in the DOM.
+ *
+ * Not built into any component: hierarchy levels and wizard steps live in the consuming app.
  */
 export declare const sharedAxis: (update: () => void | Promise<void>, { target, axis, direction, spring }?: SharedAxisOptions) => import("motion-dom").ViewTransitionBuilder;
 /**
  * M3 lateral: peer screens at the same level (tabs, carousels) slide past each other edge to edge,
  * without fading — the new screen pushes the old one out.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#lateral
+ *
+ * Only for peers in one set (https://m3.material.io/styles/motion/transitions/applying-transitions). Never use it for hierarchical screens
+ * (use `sharedAxis`) or navbar/rail/drawer destinations (use `fadeThrough`, since the implied swipe
+ * conflicts with carousels and swipeable list items). Don't add a fade: it hides the peer
+ * relationship and makes the slide look like forward/backward.
+ *
+ * Built in: `TabHolder` (switching content panels) and `DateField`/`DateRangeField` (changing the
+ * visible month). Any new component that pages between peer views must use this too.
  */
 export declare const lateral: (update: () => void | Promise<void>, { target, direction, spring }?: NavigationOptions) => import("motion-dom").ViewTransitionBuilder;
 /**
  * M3 top level (fade through): destinations with no spatial relationship, e.g. navigation bar
  * items. The outgoing screen fades out, then the incoming one fades in while scaling up from 92%.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#top-level
+ *
+ * The quick fade for navigation bar, rail and drawer destinations (https://m3.material.io/styles/motion/transitions/applying-transitions).
+ * It deliberately creates no spatial connection between screens, and it's the pattern to use
+ * instead of `lateral` there.
+ *
+ * Not built into `Navbar`/`Rail`: they don't own the content region that changes, so the app wraps
+ * its own route change in this.
  */
 export declare const fadeThrough: (update: () => void | Promise<void>, { target, spring }?: Omit<NavigationOptions, "direction">) => import("motion-dom").ViewTransitionBuilder;
 export {};

package/dist/animation/sharedAxisTransition.js

@@ -5,7 +5,9 @@ const view = (update, target, spring) => {
     const builder = animateView(update, springTransition(spring));
     return target ? builder.add(target) : builder;
 };
-/* Outgoing content clears quickly; incoming content waits a beat so the two never overlap fully. */
+/* Outgoing content clears quickly; incoming content waits a beat so the two never overlap fully.
+   M3 "clean fades" (https://m3.material.io/styles/motion/transitions/applying-transitions): fade out before fading in; any cross-fade stays short
+   and hidden in the fastest part of the motion. Don't lengthen these. */
 const fadeOut = springTransition(springTokens.fastEffects);
 const fadeIn = { ...springTransition(springTokens.effects), delay: 0.05 };
 /**
@@ -13,8 +15,15 @@ const fadeIn = { ...springTransition(springTokens.effects), delay: 0.05 };
  * axis while fading through each other.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#forward-and-backward
  *
+ * The default for common hierarchical navigation (https://m3.material.io/styles/motion/transitions/applying-transitions).
+ * Don't use it for hero moments; use `containerTransform` for those. Keep one axis per relationship
+ * across the app (coherent spatial model), and move one `target` region as a unit instead of
+ * animating many elements independently.
+ *
  * `update` performs the DOM change (`async () => { step++; await tick(); }`). Built on Motion's
  * `animateView()` — both states never need to coexist in the DOM.
+ *
+ * Not built into any component: hierarchy levels and wizard steps live in the consuming app.
  */
 export const sharedAxis = (update, { target, axis = 'x', direction = 'forward', spring = springTokens.spatial } = {}) => {
     const forward = direction === 'forward';
@@ -33,6 +42,14 @@ export const sharedAxis = (update, { target, axis = 'x', direction = 'forward',
  * M3 lateral: peer screens at the same level (tabs, carousels) slide past each other edge to edge,
  * without fading — the new screen pushes the old one out.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#lateral
+ *
+ * Only for peers in one set (https://m3.material.io/styles/motion/transitions/applying-transitions). Never use it for hierarchical screens
+ * (use `sharedAxis`) or navbar/rail/drawer destinations (use `fadeThrough`, since the implied swipe
+ * conflicts with carousels and swipeable list items). Don't add a fade: it hides the peer
+ * relationship and makes the slide look like forward/backward.
+ *
+ * Built in: `TabHolder` (switching content panels) and `DateField`/`DateRangeField` (changing the
+ * visible month). Any new component that pages between peer views must use this too.
  */
 export const lateral = (update, { target, direction = 'forward', spring = springTokens.spatial } = {}) => {
     const sign = direction === 'forward' ? 1 : -1;
@@ -45,6 +62,13 @@ export const lateral = (update, { target, direction = 'forward', spring = spring
  * M3 top level (fade through): destinations with no spatial relationship, e.g. navigation bar
  * items. The outgoing screen fades out, then the incoming one fades in while scaling up from 92%.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#top-level
+ *
+ * The quick fade for navigation bar, rail and drawer destinations (https://m3.material.io/styles/motion/transitions/applying-transitions).
+ * It deliberately creates no spatial connection between screens, and it's the pattern to use
+ * instead of `lateral` there.
+ *
+ * Not built into `Navbar`/`Rail`: they don't own the content region that changes, so the app wraps
+ * its own route change in this.
  */
 export const fadeThrough = (update, { target, spring = springTokens.spatial } = {}) => view(update, target, spring)
     .old({ opacity: [1, 0] }, fadeOut)

package/dist/animation/skeleton.d.ts

@@ -4,8 +4,13 @@ import type { Attachment } from 'svelte/attachments';
  * for the content with `presence(…, enterExit.fade)` so the reveal is a fade, not a cut.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#skeleton-loaders
  *
+ * M3 "stable layouts" (https://m3.material.io/styles/motion/transitions/applying-transitions): the placeholder takes the loaded
+ * content's footprint so nothing pops in or shifts position when the data arrives.
+ *
+ * Not built into any component — none of them load their own data. Apps apply it to placeholders.
+ *
  * ```svelte
- * <div class="bg-md-sys-color-surface-container-highest h-4 rounded-sm" {@attach skeleton}></div>
+ * <div class="bg-md-sys-color-surface-container-highest h-spacing-200 rounded-sm" {@attach skeleton}></div>
  * ```
  */
 export declare const skeleton: Attachment<HTMLElement>;

package/dist/animation/skeleton.js

@@ -8,8 +8,13 @@ const PULSE_HOLD_S = 0.5;
  * for the content with `presence(…, enterExit.fade)` so the reveal is a fade, not a cut.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#skeleton-loaders
  *
+ * M3 "stable layouts" (https://m3.material.io/styles/motion/transitions/applying-transitions): the placeholder takes the loaded
+ * content's footprint so nothing pops in or shifts position when the data arrives.
+ *
+ * Not built into any component — none of them load their own data. Apps apply it to placeholders.
+ *
  * ```svelte
- * <div class="bg-md-sys-color-surface-container-highest h-4 rounded-sm" {@attach skeleton}></div>
+ * <div class="bg-md-sys-color-surface-container-highest h-spacing-200 rounded-sm" {@attach skeleton}></div>
  * ```
  */
 export const skeleton = (node) => {

package/dist/components/badge/Badge.mdx

@@ -0,0 +1,70 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as BadgeStories from './Badge.stories.svelte';
+
+<Meta of={BadgeStories} />
+
+<Title />
+
+<Subtitle>
+  Badges show notifications, counts, or status information on navigation items and icons.
+</Subtitle>
+
+[M3 spec](https://m3.material.io/components/badges/specs) ·
+`import { Badge } from '@noxlovette/material';`
+
+<Canvas of={BadgeStories.Playground} />
+
+<Controls of={BadgeStories.Playground} />
+
+## Choosing a size
+
+| Size | Looks like                        | Use for                                     |
+| ---- | --------------------------------- | ------------------------------------------- |
+| `sm` | 6dp dot, no text                  | A general notification ("something is new") |
+| `lg` | 16dp-tall pill with a label-small | A specific count                            |
+
+A large badge holds at most four characters, "+" included, so counts above `max` (999 by
+default) show as `999+` in a 16×34dp container. A zero or missing `number` hides a large badge.
+
+<Canvas of={BadgeStories.DotSmall} />
+
+<Canvas of={BadgeStories.MaxCharacterCount} />
+
+## Placement
+
+`NavbarItem` and `RailItem` take a `badge` prop (a count, or `-1` for the dot) and place it for
+you. Use `Badge` directly only on icons those components don't cover, such as a custom icon
+button.
+
+By default the badge is absolutely positioned, with offsets measured from the **icon's**
+top-trailing corner:
+
+- **Small:** its bottom-leading corner sits 6dp down and 6dp in, so the dot fills the icon's
+  top-trailing corner.
+- **Large:** its bottom-leading corner sits 14dp down and 12dp in. The badge grows away from the
+  icon as the count gets wider.
+
+So wrap the icon itself in a `relative inline-flex` element. Don't anchor the badge to a larger
+indicator or button container, or the offsets will be measured from the wrong corner.
+
+```svelte
+<span class="relative inline-flex">
+  <Icon name="mail" />
+  <Badge number={5} />
+</span>
+```
+
+In normal flow, such as a list item's trailing slot, pass `standalone`. `ListItem`'s `badge`
+prop already does this.
+
+<Canvas of={BadgeStories.Standalone} />
+
+## Accessibility
+
+- **Not announced on its own.** `Badge` renders a plain `<span>` with no role or live region.
+  Put the count in the anchor's accessible name (e.g. `aria-label="Inbox, 5 new"`), or use an
+  `aria-live` region if changes must be announced.
+- **Contrast.** The badge uses the error/on-error pair in every theme, so its label keeps
+  contrast against its own container.
+- **Clipping.** An anchored badge overhangs the icon by 2dp at the top and past the trailing edge
+  as it widens. Make sure no ancestor with `overflow: hidden` clips it.

package/dist/components/badge/Badge.stories.svelte

@@ -1,9 +1,9 @@
 <!--
-  Badge renders `absolute` (top/right offsets baked into its `size` variant), so it always needs a
-  `position: relative` ancestor to anchor against — it's an overlay primitive, not a
-  standalone/inline element. NavbarItem/RailItem already wire this up internally via their
-  `badge` prop; the stories below reproduce that same relative-wrapper pattern by hand so Badge
-  can be previewed in isolation.
+  Badge renders `absolute` by default, offset from its positioned ancestor's top-trailing corner
+  per the M3 spec, so that ancestor must hug the 24dp icon (not a larger indicator container).
+  NavbarItem/RailItem already wire this up internally via their `badge` prop; the stories below
+  reproduce that same `relative inline-flex` wrapper by hand so Badge can be previewed in
+  isolation. `standalone` renders it in normal flow instead (e.g. ListItem's trailing slot).
 -->
 <script module lang="ts">
   import { defineMeta } from '@storybook/addon-svelte-csf';
@@ -18,41 +18,59 @@
         control: 'select',
         options: ['sm', 'lg']
       },
-      number: { control: 'number' }
+      number: { control: 'number' },
+      max: { control: 'number' },
+      standalone: { control: 'boolean' }
     },
     args: {
       size: 'lg',
-      number: 5
+      number: 5,
+      max: 999,
+      standalone: false
     }
   });
 </script>
 
 <Story name="Playground">
   {#snippet template(args)}
-    <div class="relative inline-flex size-10 items-center justify-center">
+    <span class="relative inline-flex">
       <Icon name="mail" />
-      <Badge size={args.size} number={args.number} />
-    </div>
+      <Badge size={args.size} number={args.number} max={args.max} standalone={args.standalone} />
+    </span>
   {/snippet}
 </Story>
 
-<Story name="Dot (Small)" asChild>
-  <div class="relative inline-flex size-10 items-center justify-center">
+<Story name="Dot (Small)" exportName="DotSmall" asChild>
+  <span class="relative inline-flex">
     <Icon name="notifications" />
     <Badge size="sm" />
-  </div>
+  </span>
 </Story>
 
-<Story name="Numbered (Large)" asChild>
-  <div class="relative inline-flex size-10 items-center justify-center">
+<Story name="Numbered (Large)" exportName="NumberedLarge" asChild>
+  <span class="relative inline-flex">
     <Icon name="mail" />
     <Badge size="lg" number={7} />
-  </div>
+  </span>
 </Story>
 
-<Story name="Overflow (99+)" asChild>
-  <div class="relative inline-flex size-10 items-center justify-center">
+<Story name="Two digits" asChild>
+  <span class="relative inline-flex">
     <Icon name="mail" />
-    <Badge size="lg" number={128} />
-  </div>
+    <Badge size="lg" number={42} />
+  </span>
+</Story>
+
+<Story name="Max character count (999+)" exportName="MaxCharacterCount" asChild>
+  <span class="relative inline-flex">
+    <Icon name="mail" />
+    <Badge size="lg" number={1280} />
+  </span>
+</Story>
+
+<Story name="Standalone" asChild>
+  <span class="gap-spacing-100 inline-flex items-center">
+    <Badge size="sm" standalone />
+    <Badge size="lg" number={3} standalone />
+  </span>
 </Story>

package/dist/components/badge/Badge.svelte

@@ -12,15 +12,22 @@ Large badges are used for specific counts.
   import { badge } from './theme.js';
   import type { BadgeProps } from './types.js';
 
-  const { number, size = 'lg', class: className, ...restProps }: BadgeProps = $props();
+  const {
+    number,
+    size = 'lg',
+    max = 999,
+    standalone = false,
+    class: className,
+    ...restProps
+  }: BadgeProps = $props();
 
-  const styling = $derived(badge({ size }));
+  const styling = $derived(badge({ size, standalone }));
 </script>
 
 {#if size === 'sm' || number}
-  <div class={clsx(styling, className)} {...restProps}>
+  <span class={clsx(styling, className)} {...restProps}>
     {#if size !== 'sm' && number}
-      {number > 99 ? '99+' : number}
+      {number > max ? `${max}+` : number}
     {/if}
-  </div>
+  </span>
 {/if}

package/dist/components/badge/theme.d.ts

@@ -1,16 +1,39 @@
+/**
+ * M3 badge (https://m3.material.io/components/badges/specs).
+ *
+ * Anchored offsets are measured from the positioned ancestor's top-trailing corner, so that
+ * ancestor must hug the icon (24dp box), not the larger active-indicator container:
+ * - small: 6dp, its bottom-leading corner 6dp down / 6dp in from the icon's top-trailing corner,
+ *   i.e. flush with that corner (`top-spacing-0 right-spacing-0`).
+ * - large: 16dp tall, bottom-leading corner 14dp down / 12dp in from the icon's top-trailing
+ *   corner, i.e. top = 14 − 16 = −2dp, left = 100% − 12dp. Anchored by its leading edge so a
+ *   wider count grows away from the icon.
+ */
 export declare const badge: import("tailwind-variants").TVReturnType<{
     size: {
-        sm: "size-1.5 top-0 right-3";
-        lg: "h-3 min-w-3 p-1 -top-1 right-1";
+        sm: "size-spacing-75";
+        lg: "h-spacing-200 min-w-spacing-200 px-spacing-50 md-sys-typescale-label-small whitespace-nowrap tabular-nums";
     };
-}, undefined, "bg-md-sys-color-error text-md-sys-color-on-error  absolute rounded-full md-sys-typescale-label-small inline-flex items-center justify-center", {
+    standalone: {
+        true: "relative";
+        false: "absolute pointer-events-none";
+    };
+}, undefined, "bg-md-sys-color-error text-md-sys-color-on-error rounded-full inline-flex shrink-0 items-center justify-center", {
     size: {
-        sm: "size-1.5 top-0 right-3";
-        lg: "h-3 min-w-3 p-1 -top-1 right-1";
+        sm: "size-spacing-75";
+        lg: "h-spacing-200 min-w-spacing-200 px-spacing-50 md-sys-typescale-label-small whitespace-nowrap tabular-nums";
+    };
+    standalone: {
+        true: "relative";
+        false: "absolute pointer-events-none";
     };
 }, undefined, import("tailwind-variants").TVReturnTypeLike<{
     size: {
-        sm: "size-1.5 top-0 right-3";
-        lg: "h-3 min-w-3 p-1 -top-1 right-1";
+        sm: "size-spacing-75";
+        lg: "h-spacing-200 min-w-spacing-200 px-spacing-50 md-sys-typescale-label-small whitespace-nowrap tabular-nums";
+    };
+    standalone: {
+        true: "relative";
+        false: "absolute pointer-events-none";
     };
 }, undefined>>;

package/dist/components/badge/theme.js

@@ -1,10 +1,30 @@
 import { tv } from 'tailwind-variants';
+/**
+ * M3 badge (https://m3.material.io/components/badges/specs).
+ *
+ * Anchored offsets are measured from the positioned ancestor's top-trailing corner, so that
+ * ancestor must hug the icon (24dp box), not the larger active-indicator container:
+ * - small: 6dp, its bottom-leading corner 6dp down / 6dp in from the icon's top-trailing corner,
+ *   i.e. flush with that corner (`top-spacing-0 right-spacing-0`).
+ * - large: 16dp tall, bottom-leading corner 14dp down / 12dp in from the icon's top-trailing
+ *   corner, i.e. top = 14 − 16 = −2dp, left = 100% − 12dp. Anchored by its leading edge so a
+ *   wider count grows away from the icon.
+ */
 export const badge = tv({
-    base: 'bg-md-sys-color-error text-md-sys-color-on-error  absolute rounded-full md-sys-typescale-label-small inline-flex items-center justify-center',
+    base: 'bg-md-sys-color-error text-md-sys-color-on-error rounded-full inline-flex shrink-0 items-center justify-center',
     variants: {
         size: {
-            sm: 'size-1.5 top-0 right-3',
-            lg: 'h-3 min-w-3 p-1 -top-1 right-1'
+            sm: 'size-spacing-75',
+            lg: 'h-spacing-200 min-w-spacing-200 px-spacing-50 md-sys-typescale-label-small whitespace-nowrap tabular-nums'
+        },
+        standalone: {
+            true: 'relative',
+            false: 'absolute pointer-events-none'
         }
-    }
+    },
+    compoundVariants: [
+        { standalone: false, size: 'sm', class: 'top-spacing-0 right-spacing-0' },
+        { standalone: false, size: 'lg', class: '-top-spacing-25 left-[calc(100%-12px)]' }
+    ],
+    defaultVariants: { size: 'lg', standalone: false }
 });

package/dist/components/badge/types.d.ts

@@ -2,17 +2,31 @@ import type { HTMLAttributes } from 'svelte/elements';
 import type { VariantProps } from 'tailwind-variants';
 import type { badge } from './theme.js';
 export type BadgeVariants = VariantProps<typeof badge>;
-export type BadgeProps = BadgeVariants & HTMLAttributes<HTMLDivElement> & {
+export type BadgeProps = BadgeVariants & HTMLAttributes<HTMLSpanElement> & {
     /**
      * The size of the badge.
-     * - 'sm': Small badge, no number displayed.
-     * - 'lg': Large badge, displays number.
+     * - 'sm': Small badge (6dp dot), no number displayed.
+     * - 'lg': Large badge (16dp tall), displays number.
      */
     size?: BadgeVariants['size'];
     /**
      * The number to display in the badge.
-     * Values greater than 99 will be displayed as "99+".
+     * Values greater than `max` are displayed as `${max}+`.
      * If size is 'sm', the number is not displayed.
      */
     number?: number;
+    /**
+     * Largest count shown before collapsing to `${max}+`. M3 caps a large badge at four
+     * characters including the "+" (16×34dp container), so the default is 999 → "999+".
+     * @default 999
+     */
+    max?: number;
+    /**
+     * By default the badge is absolutely positioned on its nearest positioned ancestor's
+     * top-trailing corner per the M3 offsets — that ancestor should hug the icon (e.g.
+     * `<span class="relative inline-flex">` around a 24dp `Icon`). Set `standalone` to render it
+     * in normal flow instead, e.g. in a list item's trailing slot.
+     * @default false
+     */
+    standalone?: boolean;
 };

package/dist/components/buttons/Button.mdx

@@ -0,0 +1,85 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as ButtonStories from './Button.stories.svelte';
+
+<Meta of={ButtonStories} />
+
+<Title />
+
+<Subtitle>Buttons prompt most actions in a UI.</Subtitle>
+
+[M3 spec](https://m3.material.io/components/buttons/specs) ·
+`import { Button, Toggle } from '@noxlovette/material';`
+
+<Canvas of={ButtonStories.Playground} />
+
+<Controls of={ButtonStories.Playground} />
+
+## Choosing a button
+
+One high-emphasis button per screen, for its primary action. Show the rest's importance through
+their colour style.
+
+| Emphasis | Use                                                                   | For example          |
+| -------- | --------------------------------------------------------------------- | -------------------- |
+| Highest  | `FAB` or extended FAB, for the screen's main action                   | Compose, Create      |
+| High     | `Button variant="filled"`: final or unblocking actions                | Save, Confirm, Done  |
+| High     | `SplitButton`: a key action with related options                      | Send + Schedule send |
+| Medium   | `variant="tonal"`: important, a step below filled                     | Save draft           |
+| Medium   | `variant="elevated"`: only to stand apart from a patterned background | Add to cart          |
+| Medium   | `variant="outlined"`: attention without being primary; leaving a flow | View all, Cancel     |
+| Low      | `variant="text"`: optional actions                                    | Learn more           |
+| Low      | `ButtonIcon`: compact supplementary actions                           | Favourite, Print     |
+
+Put buttons side by side rather than stacked when there's room, with the higher-emphasis one
+for the more important action.
+
+<Canvas of={ButtonStories.ColourStyles} />
+
+## Sizes
+
+| `size` | Height | Padding | Icon | Label          |
+| ------ | ------ | ------- | ---- | -------------- |
+| `xs`   | 32dp   | 12dp    | 20dp | label large    |
+| `sm`   | 40dp   | 16dp    | 20dp | label large    |
+| `md`   | 56dp   | 24dp    | 24dp | title medium   |
+| `lg`   | 96dp   | 48dp    | 32dp | headline small |
+| `xl`   | 136dp  | 64dp    | 40dp | headline large |
+
+`sm` is the default. XS and S buttons keep a 48dp target area around them, so leave room
+between them (a `ButtonGroup` does). The outline thickens to 2dp at L and 3dp at XL.
+
+<Canvas of={ButtonStories.Sizes} />
+
+## Shape
+
+`round` (default) is fully rounded; `square` has 12, 12, 16, 28 and 28dp corners from XS to XL.
+While pressed, both morph to the same tighter corner (8, 8, 12, 16, 16dp) on the fast spatial
+spring, which carries its velocity when you let go mid-morph, so a quick tap still bounces.
+
+<Canvas of={ButtonStories.RoundAndSquare} />
+
+## Toggle buttons
+
+`Toggle` is a button with a selected state (`aria-pressed`). Selecting changes its colours and
+swaps its shape: round becomes square, square becomes round. It comes in the elevated, filled,
+tonal and outlined styles; there is no text toggle. See **Buttons/Toggle**.
+
+## States and accessibility
+
+- Hover, focus and press tint the container 8%, 10% and 10% in the content colour. Keyboard
+  focus draws a 3dp ring 2dp outside the button.
+- Disabled buttons drop to a 10% on-surface container and 38% on-surface content, and lose
+  their elevation. A disabled link gets `aria-disabled` and leaves the tab order.
+- `loading` swaps the icon (or the label, with no icon) for a loading indicator and sets
+  `aria-busy`.
+
+<Canvas of={ButtonStories.Disabled} />
+
+## Where this differs from the spec
+
+- The text button's disabled state has no container. Its token lists a 10% container, but the
+  spec's figures show none.
+- Shape morphs use the library's fast spatial spring (stiffness 800, damping 0.6) instead of
+  the button token's 1400 / 0.9, as every motion here uses the Expressive springs.
+- `color` (primary, secondary, tertiary, error) is gone. M3 has one colour mapping per style;
+  restyle with a class if you need another role, keeping 3:1 contrast.

package/dist/components/buttons/Button.stories.svelte

@@ -2,33 +2,22 @@
   import { defineMeta } from '@storybook/addon-svelte-csf';
   import Button from './Button.svelte';
 
+  const variants = ['elevated', 'filled', 'tonal', 'outlined', 'text'] as const;
+  const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+
   const { Story } = defineMeta({
     title: 'Buttons/Button',
     component: Button,
     argTypes: {
-      variant: {
-        control: 'select',
-        options: ['elevated', 'filled', 'tonal', 'outlined', 'text', 'bare']
-      },
-      color: {
-        control: 'select',
-        options: ['default', 'primary', 'secondary', 'tertiary', 'error']
-      },
-      size: {
-        control: 'select',
-        options: ['xs', 'sm', 'md', 'lg', 'xl']
-      },
-      shape: {
-        control: 'select',
-        options: ['round', 'square']
-      },
+      variant: { control: 'select', options: variants },
+      size: { control: 'select', options: sizes },
+      shape: { control: 'inline-radio', options: ['round', 'square'] },
       disabled: { control: 'boolean' },
       loading: { control: 'boolean' }
     },
     args: {
       variant: 'filled',
-      color: 'primary',
-      size: 'md',
+      size: 'sm',
       shape: 'round',
       disabled: false,
       loading: false
@@ -36,15 +25,61 @@
   });
 </script>
 
-<Story name="Playground">Label</Story>
+<Story name="Playground">
+  {#snippet template(args)}
+    <Button {...args}>Label</Button>
+  {/snippet}
+</Story>
+
+<Story name="Colour styles" asChild>
+  <div class="gap-spacing-200 p-spacing-300 flex flex-wrap items-center">
+    {#each variants as variant (variant)}
+      <Button {variant}>{variant[0].toUpperCase() + variant.slice(1)}</Button>
+    {/each}
+  </div>
+</Story>
+
+<Story name="With icon" asChild>
+  <div class="gap-spacing-200 p-spacing-300 flex flex-wrap items-center">
+    {#each variants as variant (variant)}
+      <Button {variant} iconProps={{ name: 'add' }}>Create</Button>
+    {/each}
+  </div>
+</Story>
+
+<Story name="Sizes" asChild>
+  <div class="gap-spacing-200 p-spacing-300 flex flex-col items-start">
+    {#each sizes as size (size)}
+      <div class="gap-spacing-200 flex items-center">
+        <Button {size} iconProps={{ name: 'send' }}>Send</Button>
+        <Button {size} shape="square" variant="tonal" iconProps={{ name: 'send' }}>Send</Button>
+        <Button {size} variant="outlined">Cancel</Button>
+      </div>
+    {/each}
+  </div>
+</Story>
+
+<Story name="Round and square" asChild>
+  <div class="gap-spacing-200 p-spacing-300 flex flex-wrap items-center">
+    <Button size="md">Round</Button>
+    <Button size="md" shape="square">Square</Button>
+    <p class="md-sys-typescale-body-medium text-md-sys-color-on-surface-variant w-full">
+      Press and hold: both morph to the same smaller corner.
+    </p>
+  </div>
+</Story>
+
+<Story name="Disabled" asChild>
+  <div class="gap-spacing-200 p-spacing-300 flex flex-wrap items-center">
+    {#each variants as variant (variant)}
+      <Button {variant} disabled>{variant}</Button>
+    {/each}
+  </div>
+</Story>
 
-<Story name="Variants" asChild>
-  <div class="flex flex-wrap items-center gap-4 p-6">
-    <Button variant="elevated" color="primary">Elevated</Button>
-    <Button variant="filled" color="primary">Filled</Button>
-    <Button variant="tonal" color="primary">Tonal</Button>
-    <Button variant="outlined" color="primary">Outlined</Button>
-    <Button variant="text" color="primary">Text</Button>
-    <Button variant="bare" color="primary">Bare</Button>
+<Story name="Link" asChild>
+  <div class="gap-spacing-200 p-spacing-300 flex">
+    <Button href="#" variant="text">Learn more</Button>
+    <Button href="#" variant="outlined" disabled>Disabled link</Button>
   </div>
 </Story>