@noxlovette/material 0.5.1 → 0.6.0

package/dist/animation/TransitionPatterns.stories.svelte

@@ -203,27 +203,30 @@
       <button
         type="button"
         data-demo="ct-card"
-        class="bg-md-sys-color-primary-container text-md-sys-color-on-primary-container absolute top-4 left-4 flex items-center gap-3 rounded-lg p-3"
+        class="bg-md-sys-color-primary-container text-md-sys-color-on-primary-container top-spacing-200 left-spacing-200 gap-spacing-150 p-spacing-150 absolute flex items-center rounded-lg"
         onclick={runContainer}
       >
-        {@render shape(pathFourSidedCookie, 'size-10 text-md-sys-color-primary')}
+        {@render shape(pathFourSidedCookie, 'size-spacing-500 text-md-sys-color-primary')}
         <span class="md-sys-typescale-label-large">Open</span>
       </button>
     {:else}
       <div
         data-demo="ct-detail"
-        class="bg-md-sys-color-surface-container-highest text-md-sys-color-on-surface absolute inset-3 flex flex-col items-center justify-center gap-3 rounded-xl"
+        class="bg-md-sys-color-surface-container-highest text-md-sys-color-on-surface inset-spacing-150 gap-spacing-150 absolute flex flex-col items-center justify-center rounded-xl"
       >
         {@render shape(pathFourSidedCookie, 'size-24 text-md-sys-color-primary')}
         <span class="md-sys-typescale-title-medium">Detail</span>
       </div>
     {/if}
   {:else if pattern.id === 'axis'}
-    <div data-demo="axis" class="absolute inset-0 flex flex-col items-center justify-center gap-3">
+    <div
+      data-demo="axis"
+      class="inset-spacing-0 gap-spacing-150 absolute flex flex-col items-center justify-center"
+    >
       {@render shape(
         pathPentagon,
         [
-          'size-16 text-md-sys-color-primary',
+          'size-spacing-800 text-md-sys-color-primary',
           'size-20 text-md-sys-color-secondary',
           'size-24 text-md-sys-color-tertiary'
         ][level]
@@ -233,7 +236,9 @@
       </span>
     </div>
   {:else if pattern.id === 'lateral'}
-    <div class="absolute inset-x-0 top-0 flex justify-center gap-6 pt-3">
+    <div
+      class="inset-x-spacing-0 top-spacing-0 gap-spacing-300 pt-spacing-150 absolute flex justify-center"
+    >
       {#each tabs as name, i (name)}
         <span
           class={[
@@ -245,7 +250,7 @@
     </div>
     <div
       data-demo="lateral"
-      class="bg-md-sys-color-surface-container absolute inset-x-3 top-11 bottom-3 flex items-center justify-center rounded-lg"
+      class="bg-md-sys-color-surface-container inset-x-spacing-150 bottom-spacing-150 absolute top-11 flex items-center justify-center rounded-lg"
     >
       {@render shape(pathFourLeafClover, 'size-24 text-md-sys-color-primary')}
       <span
@@ -257,7 +262,7 @@
     <div
       data-demo="top"
       class={[
-        'absolute inset-3 flex flex-col items-center justify-center gap-3 rounded-lg',
+        'inset-spacing-150 gap-spacing-150 absolute flex flex-col items-center justify-center rounded-lg',
         destinations[destination].color
       ]}
     >
@@ -267,23 +272,25 @@
   {:else if pattern.id === 'enter-exit'}
     {#if pop.mounted}
       <div
-        class="bg-md-sys-color-surface-container-high shadow-elevation-3 absolute inset-x-8 inset-y-6 flex items-center justify-center rounded-xl"
+        class="bg-md-sys-color-surface-container-high shadow-elevation-3 inset-x-spacing-400 inset-y-spacing-300 absolute flex items-center justify-center rounded-xl"
         {@attach pop.attach(enterExit.scale)}
       >
         {@render shape(pathSoftBurst, 'size-24 text-md-sys-color-tertiary')}
       </div>
     {/if}
   {:else if pattern.id === 'skeleton'}
-    <div class="absolute inset-3 grid [&>*]:[grid-area:1/1]">
+    <div class="inset-spacing-150 absolute grid [&>*]:[grid-area:1/1]">
       {#if !loaded}
-        <div class="flex flex-col items-center justify-center gap-3" {@attach skeleton}>
+        <div class="gap-spacing-150 flex flex-col items-center justify-center" {@attach skeleton}>
           <div class="bg-md-sys-color-surface-container-highest size-24 rounded-full"></div>
-          <div class="bg-md-sys-color-surface-container-highest h-4 w-28 rounded-full"></div>
+          <div
+            class="bg-md-sys-color-surface-container-highest h-spacing-200 w-28 rounded-full"
+          ></div>
         </div>
       {/if}
       {#if content.mounted}
         <div
-          class="flex flex-col items-center justify-center gap-3"
+          class="gap-spacing-150 flex flex-col items-center justify-center"
           {@attach content.attach(enterExit.fade)}
         >
           {@render shape(pathGem, 'size-24 text-md-sys-color-secondary')}
@@ -296,10 +303,10 @@
 
 {#snippet demo(pattern: Pattern, tall = false)}
   <section
-    class="bg-md-sys-color-surface-container-low text-md-sys-color-on-surface flex flex-col gap-3 rounded-xl p-4"
+    class="bg-md-sys-color-surface-container-low text-md-sys-color-on-surface gap-spacing-150 p-spacing-200 flex flex-col rounded-xl"
   >
-    <header class="flex items-start justify-between gap-3">
-      <div class="flex flex-col gap-1">
+    <header class="gap-spacing-150 flex items-start justify-between">
+      <div class="gap-spacing-50 flex flex-col">
         <Title size="medium">{pattern.title}</Title>
         <Body size="small" class="text-md-sys-color-on-surface-variant">{pattern.summary}</Body>
       </div>
@@ -320,7 +327,7 @@
 {/snippet}
 
 {#snippet toolbar()}
-  <div class="flex items-center justify-between gap-4">
+  <div class="gap-spacing-200 flex items-center justify-between">
     <Title size="large">M3 transition patterns</Title>
     <Button variant={looping ? 'filled' : 'outlined'} onclick={() => (looping = !looping)}>
       {looping ? 'Pause loop' : 'Loop'}
@@ -329,9 +336,12 @@
 {/snippet}
 
 <Story name="Overview" asChild>
-  <div class="bg-md-sys-color-surface flex min-h-dvh flex-col gap-6 p-6" {@attach roundRobin}>
+  <div
+    class="bg-md-sys-color-surface gap-spacing-300 p-spacing-300 flex min-h-dvh flex-col"
+    {@attach roundRobin}
+  >
     {@render toolbar()}
-    <div class="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+    <div class="gap-spacing-200 grid md:grid-cols-2 xl:grid-cols-3">
       {#each all as pattern (pattern.id)}
         {@render demo(pattern)}
       {/each}
@@ -341,7 +351,7 @@
 
 {#snippet single(pattern: Pattern)}
   <div
-    class="bg-md-sys-color-surface flex min-h-dvh flex-col gap-6 p-6"
+    class="bg-md-sys-color-surface gap-spacing-300 p-spacing-300 flex min-h-dvh flex-col"
     {@attach loop(pattern.run)}
   >
     {@render toolbar()}

package/dist/animation/containerTransform.d.ts

@@ -23,8 +23,10 @@ export interface ContainerTransformOptions {
  * the DOM at the same time — `update` swaps one for the other. Browsers without the API just run
  * `update`. A second call while one is running is queued, not interrupted.
  *
- * Not built into any component: `Search` is a plain field with no search view to expand into, and
- * card → detail is the app's own navigation.
+ * Not built into any component. FAB → sheet is the FAB's own morph (a clip-path on Motion, in
+ * `FAB.svelte`), because M3 keeps that container opaque and changes its colour, which a
+ * snapshot cross-fade can't. Card → detail is the app's own navigation, and `Search` is a plain
+ * field with no search view to expand into.
  *
  * ```ts
  * containerTransform(

package/dist/animation/containerTransform.js

@@ -15,8 +15,10 @@ import { springTokens, springTransition } from './spring.js';
  * the DOM at the same time — `update` swaps one for the other. Browsers without the API just run
  * `update`. A second call while one is running is queued, not interrupted.
  *
- * Not built into any component: `Search` is a plain field with no search view to expand into, and
- * card → detail is the app's own navigation.
+ * Not built into any component. FAB → sheet is the FAB's own morph (a clip-path on Motion, in
+ * `FAB.svelte`), because M3 keeps that container opaque and changes its colour, which a
+ * snapshot cross-fade can't. Card → detail is the app's own navigation, and `Search` is a plain
+ * field with no search view to expand into.
  *
  * ```ts
  * containerTransform(

package/dist/animation/enterExit.js

@@ -53,9 +53,12 @@ export const enterExit = {
         enter: enterWith(springTokens.spatial),
         exit
     },
-    /** Side sheet anchored to the inline-end edge. Slides only: no opacity (M3: don't fade sheets). */
+    /**
+     * Side sheet anchored to the inline-end edge. Slides only: no opacity (M3: don't fade sheets).
+     * The extra 1rem clears a detached sheet's 16dp margin, so no sliver is left at the edge.
+     */
     sideSheet: {
-        hidden: { transform: 'translateX(100%)' },
+        hidden: { transform: 'translateX(calc(100% + 1rem))' },
         shown: { transform: 'translateX(0%)' },
         enter: springTransition(springTokens.spatial),
         exit: springTransition(springTokens.effects)

package/dist/animation/skeleton.d.ts

@@ -10,7 +10,7 @@ import type { Attachment } from 'svelte/attachments';
  * 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

@@ -14,7 +14,7 @@ const PULSE_HOLD_S = 0.5;
  * 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.