@noxlovette/material 0.5.1 → 0.6.0

package/dist/components/forms/slider/Slider.stories.svelte

@@ -36,14 +36,14 @@
 
 <Story name="Playground">
   {#snippet template(args)}
-    <div class="max-w-sm p-10">
+    <div class="p-spacing-500 max-w-sm">
       <Slider {...args} />
     </div>
   {/snippet}
 </Story>
 
 <Story name="Sizes" asChild>
-  <div class="flex max-w-sm flex-col gap-8 p-10">
+  <div class="gap-spacing-400 p-spacing-500 flex max-w-sm flex-col">
     <Slider value={30} size="xs" />
     <Slider value={30} size="s" />
     <Slider value={30} size="m" />
@@ -52,8 +52,8 @@
   </div>
 </Story>
 
-<Story name="With Icons" asChild>
-  <div class="max-w-sm p-10">
+<Story name="With Icons" exportName="WithIcons" asChild>
+  <div class="p-spacing-500 max-w-sm">
     <Slider
       value={60}
       size="m"
@@ -63,14 +63,14 @@
   </div>
 </Story>
 
-<Story name="Discrete With Stops" asChild>
-  <div class="max-w-sm p-10">
+<Story name="Discrete With Stops" exportName="DiscreteWithStops" asChild>
+  <div class="p-spacing-500 max-w-sm">
     <Slider value={40} step={20} stops />
   </div>
 </Story>
 
 <Story name="Disabled" asChild>
-  <div class="max-w-sm p-10">
+  <div class="p-spacing-500 max-w-sm">
     <Slider value={40} disabled />
   </div>
 </Story>

package/dist/components/forms/slider/Slider.svelte

@@ -41,13 +41,18 @@ the track, a new `value` from outside) springs to it on the fast spatial spring.
 
   /* M3 slider geometry, in px. */
   const HANDLE_PX = 4;
+  /* Pressed and focused handles narrow to 2dp. */
+  const HANDLE_NARROW_PX = 2;
   const GAP_PX = 6;
-  const ICON_PADDING_PX = 8;
-  /* Stops closer than this to the handle's center are hidden under its gap. */
-  const STOP_CLEARANCE_PX = HANDLE_PX / 2 + GAP_PX;
+  /* Stop indicators are 4dp with 4dp trailing space, so their centers sit 6dp in from each end. */
+  const STOP_INSET_PX = 6;
 
-  const iconSize = $derived(size === 'xl' ? 'lg' : 'md');
-  const iconPx = $derived(size === 'xl' ? 40 : 24);
+  /* Inset icons exist only on M, L and XL: 24dp/6dp padding, 32dp/8dp on XL. */
+  const hasIcons = $derived(size === 'm' || size === 'l' || size === 'xl');
+  const iconPx = $derived(size === 'xl' ? 32 : 24);
+  const iconPaddingPx = $derived(size === 'xl' ? 8 : 6);
+  const leadingIcon = $derived(hasIcons ? leadingIconProps : undefined);
+  const trailingIcon = $derived(hasIcons ? trailingIconProps : undefined);
 
   const stepValue = $derived(typeof step === 'number' ? step : undefined);
   const range = $derived(max - min);
@@ -60,17 +65,21 @@ the track, a new `value` from outside) springs to it on the fast spatial spring.
     pressed, the handle is being dragged and tracks it directly.
   */
   let dragging = $state(false);
+  let pressed = $state(false);
+  let focusVisible = $state(false);
 
   const trackDrag: Attachment<HTMLElement> = (node) => {
     const move = () => (dragging = true);
     const release = () => {
       dragging = false;
+      pressed = false;
       window.removeEventListener('pointermove', move);
       window.removeEventListener('pointerup', release);
       window.removeEventListener('pointercancel', release);
     };
     const press = () => {
       if (disabled) return;
+      pressed = true;
       window.addEventListener('pointermove', move);
       window.addEventListener('pointerup', release);
       window.addEventListener('pointercancel', release);
@@ -92,6 +101,15 @@ the track, a new `value` from outside) springs to it on the fast spatial spring.
   /* The spring may overshoot the ends; the track can't. */
   const pos = $derived(Math.min(1, Math.max(0, fraction.current)));
 
+  /** Handle thickness: 4dp at rest, 2dp while pressed or keyboard-focused. */
+  const handleThickness = new SpringValue(
+    () => (pressed || focusVisible ? HANDLE_NARROW_PX : HANDLE_PX),
+    springTokens.fastSpatial
+  );
+  const handlePx = $derived(Math.max(1, handleThickness.current));
+  /* The gap is measured from the handle's current edge, so it stays 6dp as the handle narrows. */
+  const clearPx = $derived(handlePx / 2 + GAP_PX);
+
   /* ---- geometry -------------------------------------------------------------------------- */
 
   let trackWidth = $state(0);
@@ -101,21 +119,19 @@ the track, a new `value` from outside) springs to it on the fast spatial spring.
   const start = $derived(vertical ? 'bottom' : 'left');
   const extent = $derived(vertical ? 'height' : 'width');
 
-  /** Handle center: travels the track inset by half a handle so it never overhangs the ends. */
+  /** Handle center: travels the track inset by half a resting handle so it never overhangs the ends. */
   const center = (f: number) => `calc(${HANDLE_PX / 2}px + ${f} * (100% - ${HANDLE_PX}px))`;
   const centerPx = $derived(HANDLE_PX / 2 + pos * (length - HANDLE_PX));
 
-  const activePx = $derived(centerPx - HANDLE_PX / 2 - GAP_PX);
-  const inactivePx = $derived(length - centerPx - HANDLE_PX / 2 - GAP_PX);
+  const activePx = $derived(centerPx - clearPx);
+  const inactivePx = $derived(length - centerPx - clearPx);
 
-  const activeStyle = $derived(
-    `${extent}: max(0px, calc(${pos} * (100% - ${HANDLE_PX}px) - ${GAP_PX}px))`
-  );
-  const inactiveStyle = $derived(
-    `${extent}: max(0px, calc(${1 - pos} * (100% - ${HANDLE_PX}px) - ${GAP_PX}px))`
-  );
+  const trackStyle = (f: number) =>
+    `${extent}: max(0px, calc(${f} * (100% - ${HANDLE_PX}px) + ${HANDLE_PX / 2 - clearPx}px))`;
+  const activeStyle = $derived(trackStyle(pos));
+  const inactiveStyle = $derived(trackStyle(1 - pos));
 
-  /* Stops sit inset by half the track thickness so the end stops land in the rounded caps. */
+  /* Stops span the track inset by STOP_INSET_PX, so the end stops keep their 4dp trailing space. */
   const stopList = $derived.by(() => {
     const output: number[] = [];
     if (stops && stepValue && range > 0) {
@@ -124,24 +140,24 @@ the track, a new `value` from outside) springs to it on the fast spatial spring.
       output.push(1);
     }
     return output.filter((s) => {
-      if (leadingIconProps && s === 0) return false;
-      if (trailingIconProps && s === 1) return false;
-      return !length || Math.abs(s - pos) * length > STOP_CLEARANCE_PX;
+      if (leadingIcon && s === 0) return false;
+      if (trailingIcon && s === 1) return false;
+      return !length || Math.abs(s - pos) * length > clearPx;
     });
   });
 
   /* Icons ride inside their track; when it gets too short they hop across the handle. */
-  const iconFits = (trackPx: number) => trackPx >= iconPx + ICON_PADDING_PX * 2;
+  const iconFits = (trackPx: number) => trackPx >= iconPx + iconPaddingPx * 2;
   const leadingOnActive = $derived(!length || iconFits(activePx));
   const trailingOnInactive = $derived(!length || iconFits(inactivePx));
 
   const leadingOffset = $derived(
-    leadingOnActive ? ICON_PADDING_PX : centerPx + HANDLE_PX / 2 + GAP_PX + ICON_PADDING_PX
+    leadingOnActive ? iconPaddingPx : centerPx + clearPx + iconPaddingPx
   );
   const trailingOffset = $derived(
     trailingOnInactive
-      ? length - ICON_PADDING_PX - iconPx
-      : centerPx - HANDLE_PX / 2 - GAP_PX - ICON_PADDING_PX - iconPx
+      ? length - iconPaddingPx - iconPx
+      : centerPx - clearPx - iconPaddingPx - iconPx
   );
 
   const sliderDir = $derived(dir === null || dir === 'auto' ? undefined : dir);
@@ -175,26 +191,26 @@ the track, a new `value` from outside) springs to it on the fast spatial spring.
       {#each stopList as s (s)}
         <div
           class={cls.stop({ class: s < pos ? cls.stopOnActive() : cls.stopOnInactive() })}
-          style="{start}: calc(var(--track) / 2 + {s} * (100% - var(--track)))"
+          style="{start}: calc({STOP_INSET_PX}px + {s} * (100% - {STOP_INSET_PX * 2}px))"
         ></div>
       {/each}
 
-      {#if leadingIconProps}
+      {#if leadingIcon}
         <span
           class={cls.icon({ class: leadingOnActive ? cls.iconOnActive() : cls.iconOnInactive() })}
           style="{start}: {leadingOffset}px"
         >
-          <Icon size={iconSize} {...leadingIconProps} />
+          <Icon {...leadingIcon} class={cls.iconGlyph({ class: clsx(leadingIcon.class) })} />
         </span>
       {/if}
-      {#if trailingIconProps}
+      {#if trailingIcon}
         <span
           class={cls.icon({
             class: trailingOnInactive ? cls.iconOnInactive() : cls.iconOnActive()
           })}
           style="{start}: {trailingOffset}px"
         >
-          <Icon size={iconSize} {...trailingIconProps} />
+          <Icon {...trailingIcon} class={cls.iconGlyph({ class: clsx(trailingIcon.class) })} />
         </span>
       {/if}
 
@@ -204,7 +220,9 @@ the track, a new `value` from outside) springs to it on the fast spatial spring.
             {...thumbProps}
             class={cls.handle()}
             data-active={active || undefined}
-            style="{start}: {center(pos)}"
+            style="{start}: {center(pos)}; {extent}: {handlePx}px"
+            onfocus={(e) => (focusVisible = e.currentTarget.matches(':focus-visible'))}
+            onblur={() => (focusVisible = false)}
           ></div>
         {/snippet}
       </Slider.Thumb>

package/dist/components/forms/slider/theme.d.ts

@@ -1,6 +1,8 @@
 import { type VariantProps } from 'tailwind-variants';
 /**
  * M3 Expressive slider: an active and an inactive track separated from a bar handle by a 6dp gap.
+ * Per-size tokens (track / handle / outer corner / inset icon): XS 16/44/8/–, S 24/44/8/–,
+ * M 40/52/12/24, L 56/68/16/24, XL 96/108/28/32. The value indicator sits 12dp above the handle.
  * Track/handle positions are set inline by `Slider.svelte` from one animated value; these slots
  * only carry size, shape and color.
  *
@@ -16,12 +18,15 @@ export declare const slider: import("tailwind-variants").TVReturnType<{
         };
         m: {
             root: string;
+            iconGlyph: string;
         };
         l: {
             root: string;
+            iconGlyph: string;
         };
         xl: {
             root: string;
+            iconGlyph: string;
         };
     };
     vertical: {
@@ -60,6 +65,7 @@ export declare const slider: import("tailwind-variants").TVReturnType<{
     stopOnActive: string;
     stopOnInactive: string;
     icon: string;
+    iconGlyph: string;
     iconOnActive: string;
     iconOnInactive: string;
     handle: string;
@@ -74,12 +80,15 @@ export declare const slider: import("tailwind-variants").TVReturnType<{
         };
         m: {
             root: string;
+            iconGlyph: string;
         };
         l: {
             root: string;
+            iconGlyph: string;
         };
         xl: {
             root: string;
+            iconGlyph: string;
         };
     };
     vertical: {
@@ -118,6 +127,7 @@ export declare const slider: import("tailwind-variants").TVReturnType<{
     stopOnActive: string;
     stopOnInactive: string;
     icon: string;
+    iconGlyph: string;
     iconOnActive: string;
     iconOnInactive: string;
     handle: string;
@@ -132,12 +142,15 @@ export declare const slider: import("tailwind-variants").TVReturnType<{
         };
         m: {
             root: string;
+            iconGlyph: string;
         };
         l: {
             root: string;
+            iconGlyph: string;
         };
         xl: {
             root: string;
+            iconGlyph: string;
         };
     };
     vertical: {
@@ -176,6 +189,7 @@ export declare const slider: import("tailwind-variants").TVReturnType<{
     stopOnActive: string;
     stopOnInactive: string;
     icon: string;
+    iconGlyph: string;
     iconOnActive: string;
     iconOnInactive: string;
     handle: string;

package/dist/components/forms/slider/theme.js

@@ -1,6 +1,8 @@
 import { tv } from 'tailwind-variants';
 /**
  * M3 Expressive slider: an active and an inactive track separated from a bar handle by a 6dp gap.
+ * Per-size tokens (track / handle / outer corner / inset icon): XS 16/44/8/–, S 24/44/8/–,
+ * M 40/52/12/24, L 56/68/16/24, XL 96/108/28/32. The value indicator sits 12dp above the handle.
  * Track/handle positions are set inline by `Slider.svelte` from one animated value; these slots
  * only carry size, shape and color.
  *
@@ -12,22 +14,22 @@ export const slider = tv({
         track: 'pointer-events-none absolute',
         activeTrack: 'bg-md-sys-color-primary group-data-[disabled]:bg-md-sys-color-on-surface/38',
         inactiveTrack: 'bg-md-sys-color-secondary-container group-data-[disabled]:bg-md-sys-color-on-surface/12',
-        stop: 'pointer-events-none absolute size-1 rounded-full',
+        stop: 'pointer-events-none absolute size-spacing-50 rounded-full',
         stopOnActive: 'bg-md-sys-color-on-primary group-data-[disabled]:bg-md-sys-color-inverse-on-surface',
         stopOnInactive: 'bg-md-sys-color-on-secondary-container group-data-[disabled]:bg-md-sys-color-on-surface/38',
-        icon: 'pointer-events-none absolute',
+        icon: 'pointer-events-none absolute flex',
+        iconGlyph: '',
         iconOnActive: 'text-md-sys-color-on-primary',
         iconOnInactive: 'text-md-sys-color-on-secondary-container',
         handle: `
       absolute rounded-full bg-md-sys-color-primary outline-none
-      transition-[width,height] md-sys-motion-fast-spatial
       focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-md-sys-color-secondary
       group-data-[disabled]:bg-md-sys-color-on-surface/38
     `,
         value: `
-      pointer-events-none absolute z-10 flex min-w-12 items-center justify-center rounded-full
-      bg-md-sys-color-inverse-surface px-4 py-3
-      md-sys-typescale-label-large text-md-sys-color-inverse-on-surface
+      pointer-events-none absolute z-10 flex min-w-spacing-600 items-center justify-center rounded-full
+      bg-md-sys-color-inverse-surface px-spacing-200 py-spacing-150
+      md-sys-typescale-body-medium tracking-[0.5px] text-md-sys-color-inverse-on-surface
       opacity-0 transition-opacity md-sys-motion-effects
       group-has-[[data-slider-thumb]:focus-visible]:opacity-100
     `
@@ -36,30 +38,39 @@ export const slider = tv({
         size: {
             xs: { root: '[--track:1rem] [--handle:2.75rem] [--outer:var(--radius-sm)]' },
             s: { root: '[--track:1.5rem] [--handle:2.75rem] [--outer:var(--radius-sm)]' },
-            m: { root: '[--track:2.5rem] [--handle:3.25rem] [--outer:var(--radius-md)]' },
-            l: { root: '[--track:3.5rem] [--handle:4.25rem] [--outer:var(--radius-lg)]' },
-            xl: { root: '[--track:6rem] [--handle:6.75rem] [--outer:var(--radius-xl)]' }
+            m: {
+                root: '[--track:2.5rem] [--handle:3.25rem] [--outer:var(--radius-md)]',
+                iconGlyph: 'size-spacing-300 text-[24px]'
+            },
+            l: {
+                root: '[--track:3.5rem] [--handle:4.25rem] [--outer:var(--radius-lg)]',
+                iconGlyph: 'size-spacing-300 text-[24px]'
+            },
+            xl: {
+                root: '[--track:6rem] [--handle:6.75rem] [--outer:var(--radius-xl)]',
+                iconGlyph: 'size-spacing-400 text-[32px]'
+            }
         },
         vertical: {
             false: {
                 root: 'h-[var(--handle)] w-full min-w-40',
                 track: 'top-1/2 h-[var(--track)] -translate-y-1/2',
-                activeTrack: 'left-0 rounded-l-[var(--outer)] rounded-r-[2px]',
-                inactiveTrack: 'right-0 rounded-l-[2px] rounded-r-[var(--outer)]',
+                activeTrack: 'left-spacing-0 rounded-l-[var(--outer)] rounded-r-[2px]',
+                inactiveTrack: 'right-spacing-0 rounded-l-[2px] rounded-r-[var(--outer)]',
                 stop: 'top-1/2 -translate-x-1/2 -translate-y-1/2',
                 icon: 'top-1/2 -translate-y-1/2',
-                handle: 'top-0 h-full w-1 -translate-x-1/2 data-[active]:w-0.5',
-                value: 'bottom-[calc(100%+4px)] -translate-x-1/2'
+                handle: 'top-spacing-0 h-full -translate-x-1/2',
+                value: 'bottom-[calc(100%+12px)] -translate-x-1/2'
             },
             true: {
                 root: 'h-full min-h-40 w-[var(--handle)]',
                 track: 'left-1/2 w-[var(--track)] -translate-x-1/2',
-                activeTrack: 'bottom-0 rounded-t-[2px] rounded-b-[var(--outer)]',
-                inactiveTrack: 'top-0 rounded-t-[var(--outer)] rounded-b-[2px]',
+                activeTrack: 'bottom-spacing-0 rounded-t-[2px] rounded-b-[var(--outer)]',
+                inactiveTrack: 'top-spacing-0 rounded-t-[var(--outer)] rounded-b-[2px]',
                 stop: 'left-1/2 -translate-x-1/2 translate-y-1/2',
                 icon: 'left-1/2 -translate-x-1/2',
-                handle: 'left-0 h-1 w-full translate-y-1/2 data-[active]:h-0.5',
-                value: 'left-[calc(100%+4px)] translate-y-1/2'
+                handle: 'left-spacing-0 w-full translate-y-1/2',
+                value: 'left-[calc(100%+12px)] translate-y-1/2'
             }
         },
         active: {

package/dist/components/forms/slider/types.d.ts

@@ -30,11 +30,12 @@ export type SliderProps = Omit<SliderVariants, 'active'> & Omit<HTMLAttributes<H
      */
     showValue?: boolean;
     /**
-     * Props for the leading icon.
+     * Props for the leading inset icon. M3 only defines inset icons for sizes `m`, `l` and `xl`
+     * (24dp, or 32dp on XL); it is ignored on `xs` and `s`.
      */
     leadingIconProps?: IconProps;
     /**
-     * Props for the trailing icon.
+     * Props for the trailing inset icon. Only rendered on sizes `m`, `l` and `xl`.
      */
     trailingIconProps?: IconProps;
     /**

package/dist/components/forms/switch/Switch.mdx

@@ -0,0 +1,38 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as SwitchStories from './Switch.stories.svelte';
+
+<Meta of={SwitchStories} />
+
+<Title />
+
+<Subtitle>Switches toggle a single setting on or off.</Subtitle>
+
+[M3 spec](https://m3.material.io/components/switch/specs) ·
+`import { Switch } from '@noxlovette/material';`
+
+<Canvas of={SwitchStories.Playground} />
+
+<Controls of={SwitchStories.Playground} />
+
+## Icons
+
+`icons` controls the thumb icon: `checked` (the default) shows a check only when on, `both`
+shows a check when on and a close icon when off, and `none` shows a plain thumb. Showing icons
+gives a signal that doesn't depend on color alone.
+
+<Canvas of={SwitchStories.IconModes} />
+
+## Dragging
+
+Besides click and tap, the thumb can be dragged: moving it more than 16px toward the other side
+flips the state, like a native mobile switch.
+
+```svelte
+<Switch bind:checked={notifications} />
+```
+
+## Accessibility
+
+- **Role.** The control is a `role="switch"` from bits-ui; Space and Enter toggle it.
+- **Label.** The switch has no built-in label. Wrap it in a `<label>` with visible text, or give
+  it an `aria-label`.

package/dist/components/forms/switch/Switch.stories.svelte

@@ -23,14 +23,14 @@
 
 <Story name="Playground">
   {#snippet template(args)}
-    <div class="p-6">
+    <div class="p-spacing-300">
       <Switch {...args} />
     </div>
   {/snippet}
 </Story>
 
 <Story name="Icon Modes" asChild>
-  <div class="flex flex-col gap-4 p-6">
+  <div class="gap-spacing-200 p-spacing-300 flex flex-col">
     <Switch checked icons="checked" />
     <Switch checked icons="both" />
     <Switch checked icons="none" />
@@ -38,7 +38,7 @@
 </Story>
 
 <Story name="States" asChild>
-  <div class="flex flex-col gap-4 p-6">
+  <div class="gap-spacing-200 p-spacing-300 flex flex-col">
     <Switch checked={false} />
     <Switch checked={true} />
     <Switch checked={false} disabled />

package/dist/components/forms/switch/theme.js

@@ -5,10 +5,10 @@ import { tv } from 'tailwind-variants';
 // Hover  — 40dp state layer ring around thumb
 export const toggle = tv({
     slots: {
-        root: 'group relative inline-flex h-8 w-[3.25rem] shrink-0 [print-color-adjust:exact]',
+        root: 'group relative inline-flex h-spacing-400 w-[3.25rem] shrink-0 [print-color-adjust:exact]',
         // The input IS the track — styled as the pill background
         input: [
-            'absolute inset-0 m-0 h-full w-full appearance-none rounded-full',
+            'absolute inset-spacing-0 m-spacing-0 h-full w-full appearance-none rounded-full',
             'border-2 border-md-sys-color-outline bg-md-sys-color-surface-container-highest',
             'group-data-[state=checked]:border-md-sys-color-primary group-data-[state=checked]:bg-md-sys-color-primary',
             'group-data-[disabled]:cursor-not-allowed',
@@ -18,7 +18,7 @@ export const toggle = tv({
         ].join(' '),
         // Thumb — absolute over track
         handle: [
-            'pointer-events-none absolute left-2 top-1/2 flex h-4 w-4 -translate-y-1/2',
+            'pointer-events-none absolute left-spacing-100 top-1/2 flex h-spacing-200 w-spacing-200 -translate-y-1/2',
             'items-center justify-center rounded-full relative',
             'bg-md-sys-color-outline',
             'transition-[left,transform,background-color] md-sys-motion-fast-spatial',
@@ -36,17 +36,17 @@ export const toggle = tv({
         ].join(' '),
         // State layer ring around thumb
         hover: [
-            'pointer-events-none absolute left-4 top-1/2 h-12 w-12',
+            'pointer-events-none absolute left-spacing-200 top-1/2 h-spacing-600 w-spacing-600',
             '-translate-x-1/2 -translate-y-1/2 rounded-full',
             'transition-[left,background-color] md-sys-motion-fast-spatial',
-            'group-data-[state=checked]:left-9',
+            'group-data-[state=checked]:left-spacing-450',
             'group-data-[disabled]:hidden',
             'group-hover:bg-md-sys-color-on-surface/8',
             'group-data-[state=checked]:group-hover:bg-md-sys-color-primary/8'
         ].join(' '),
         // Icon inside thumb - shared base (sized via size="xs" prop on Icon, not here)
         icon: [
-            'absolute inset-0 m-auto pointer-events-none flex items-center justify-center',
+            'absolute inset-spacing-0 m-auto pointer-events-none flex items-center justify-center',
             'opacity-0 transition-opacity md-sys-motion-fast-effects shrink-0'
         ].join(' '),
         // Specific icon states - colour matches M3 spec for each thumb background

package/dist/components/forms/textfield/Textfield.mdx

@@ -0,0 +1,53 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as TextfieldStories from './Textfield.stories.svelte';
+
+<Meta of={TextfieldStories} />
+
+<Title />
+
+<Subtitle>Text fields let users enter and edit text.</Subtitle>
+
+[M3 spec](https://m3.material.io/components/text-fields/specs) ·
+`import { Textfield } from '@noxlovette/material';`
+
+<Canvas of={TextfieldStories.Playground} />
+
+<Controls of={TextfieldStories.Playground} />
+
+## Outlined or filled
+
+`variant` defaults to `outlined`: a bordered field whose floating label opens a gap in the border.
+`filled` has a container and a bottom indicator line, and carries more emphasis. Use outlined in
+busy surroundings (over an image, in dense forms) or next to a filled field that should stand
+out.
+
+<Canvas of={TextfieldStories.Outlined} />
+
+The `label` starts inside the field and floats up on focus or once there's a value.
+
+```svelte
+<Textfield label="Email" bind:value={email} required>
+  {#snippet supportingText()}
+    We'll never share your email.
+  {/snippet}
+</Textfield>
+```
+
+## Icons and supporting text
+
+`leadingIconProps` and `trailingIconProps` add icons (a trailing icon is a good place for a clear
+button). The `supportingText` snippet renders helper or error text below the field. Other native
+`<input>` attributes (`type`, `maxlength`, `autocomplete`…) pass through to the input.
+
+<Canvas of={TextfieldStories.WithIcons} />
+
+<Canvas of={TextfieldStories.CharacterLimit} />
+
+## Accessibility
+
+- **Label.** The floating label is a real `<label for>` tied to the input's id (generated when you
+  don't pass one), not an `aria-label`.
+- **Errors.** `error` sets `aria-invalid`. Say what's wrong in `supportingText`, not just with
+  color.
+- **Required.** `required` sets `required` and `aria-required`, and shows an asterisk that screen
+  readers skip.

package/dist/components/forms/textfield/Textfield.stories.svelte

@@ -26,14 +26,14 @@
 
 <Story name="Playground">
   {#snippet template(args)}
-    <div class="max-w-sm p-6">
+    <div class="p-spacing-300 max-w-sm">
       <Textfield {...args} />
     </div>
   {/snippet}
 </Story>
 
 <Story name="With Supporting Text" asChild>
-  <div class="max-w-sm p-6">
+  <div class="p-spacing-300 max-w-sm">
     <Textfield label="Email">
       {#snippet supportingText()}
         We'll never share your email.
@@ -43,7 +43,7 @@
 </Story>
 
 <Story name="With Icons" asChild>
-  <div class="max-w-sm p-6">
+  <div class="p-spacing-300 max-w-sm">
     <Textfield
       label="Search"
       leadingIconProps={{ name: 'search' }}
@@ -53,7 +53,7 @@
 </Story>
 
 <Story name="Character Limit" asChild>
-  <div class="max-w-sm p-6">
+  <div class="p-spacing-300 max-w-sm">
     <Textfield label="Bio" characterLimit={80} value="">
       {#snippet supportingText()}
         Keep it short.
@@ -63,7 +63,7 @@
 </Story>
 
 <Story name="States" asChild>
-  <div class="flex max-w-sm flex-col gap-6 p-6">
+  <div class="gap-spacing-300 p-spacing-300 flex max-w-sm flex-col">
     <Textfield label="Default" />
     <Textfield label="Required" required />
     <Textfield label="Error" error value="Invalid value">
@@ -76,7 +76,7 @@
 </Story>
 
 <Story name="Outlined" asChild>
-  <div class="flex max-w-sm flex-col gap-6 p-6">
+  <div class="gap-spacing-300 p-spacing-300 flex max-w-sm flex-col">
     <Textfield variant="outlined" label="Default" />
     <Textfield variant="outlined" label="With value" value="Hello" />
     <Textfield variant="outlined" label="Required" required />

package/dist/components/forms/textfield/Textfield.svelte

@@ -70,6 +70,7 @@ Text fields allow users to enter and edit text.
       {@render trailingIcon()}
     {:else if trailingIconProps}
       <ButtonIcon
+        variant="standard"
         type="button"
         onclick={trailingOnClick}
         class={cls.trailingIcon()}