@noxlovette/material 0.5.1 → 0.6.1

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

@@ -1,14 +1,14 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 // M3 Switch:
 // Track  — 52×32dp, 2dp border
 // Thumb  — 16dp unchecked / 24dp checked (scale 1.5×)
 // 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()}

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

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../../utils/tv.js';
 export type TextFieldVariants = VariantProps<typeof textfield>;
 export declare const textfield: import("tailwind-variants").TVReturnType<{
     variant: {

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

@@ -1,13 +1,13 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const textfield = tv({
     slots: {
         base: `
-      group relative w-full h-14 flex items-center
+      group relative w-full h-spacing-700 flex items-center
     `,
         /* Stretches to the full field height so the label floats relative to the field's top edge,
            not the input's. */
         inputWrapper: `
-      relative flex-1 self-stretch flex items-center px-4
+      relative flex-1 self-stretch flex items-center px-spacing-200
     `,
         input: `
       peer w-full bg-transparent outline-none
@@ -15,7 +15,7 @@ export const textfield = tv({
       disabled:text-md-sys-color-on-surface/38
     `,
         label: `
-      absolute left-4 top-1/2 -translate-y-1/2
+      absolute left-spacing-200 top-1/2 -translate-y-1/2
       md-sys-typescale-body-large
       text-md-sys-color-on-surface-variant
       pointer-events-none
@@ -24,28 +24,28 @@ export const textfield = tv({
       peer-focus:text-md-sys-color-primary
     `,
         requiredAsterisk: `
-      ml-0.5
+      ml-spacing-25
       text-md-sys-color-error
       group-focus-within:text-md-sys-color-primary
       transition-colors md-sys-motion-effects
     `,
         leadingIcon: `
-      text-md-sys-color-on-surface-variant size-6
+      text-md-sys-color-on-surface-variant size-spacing-300
       group-focus-within:text-md-sys-color-primary
-      ml-3 text-[24px]
+      ml-spacing-150 text-[24px]
     `,
         trailingIcon: `
-      mr-3 text-md-sys-color-on-surface-variant size-6
+      mr-spacing-150 text-md-sys-color-on-surface-variant size-spacing-300
       group-focus-within:text-md-sys-color-primary
       z-20 text-[24px]
     `,
         supportingText: `
-      px-4 pt-1 flex justify-between
+      px-spacing-200 pt-spacing-50 flex justify-between
       md-sys-typescale-body-small
       text-md-sys-color-on-surface-variant
     `,
         fieldset: `
-      absolute -top-2 left-0 right-0 bottom-0 m-0 px-3
+      absolute -top-spacing-100 left-spacing-0 right-spacing-0 bottom-spacing-0 m-spacing-0 px-spacing-150
       pointer-events-none rounded-xs border border-md-sys-color-outline
       transition-colors md-sys-motion-fast-effects
 
@@ -61,16 +61,16 @@ export const textfield = tv({
       group-has-[input:not(:placeholder-shown)]:max-w-full
     `,
         legendLabel: `
-      px-1
+      px-spacing-50
     `
     },
     variants: {
         variant: {
             filled: {
                 base: `
-          px-0 bg-md-sys-color-surface-container-highest
+          px-spacing-0 bg-md-sys-color-surface-container-highest
           rounded-t-xs state-layer before:rounded-xs hover:before:bg-md-sys-color-on-surface/8
-          after:absolute after:bottom-0 after:left-0 after:right-0 after:h-px after:bg-md-sys-color-on-surface-variant
+          after:absolute after:bottom-spacing-0 after:left-spacing-0 after:right-spacing-0 after:h-px after:bg-md-sys-color-on-surface-variant
           after:transition-[height,background-color] after:md-sys-motion-fast-spatial
           hover:after:bg-md-sys-color-on-surface
           focus-within:after:bg-md-sys-color-primary
@@ -80,16 +80,16 @@ export const textfield = tv({
         `,
                 /* Room for the label floated inside the container. Outlined labels float into the border
                    notch instead, so their input stays vertically centered. */
-                input: 'pt-4',
+                input: 'pt-spacing-200',
                 label: `
-          peer-focus:top-2 peer-focus:md-sys-typescale-body-small peer-focus:translate-y-0
-          peer-not-placeholder-shown:top-2 peer-not-placeholder-shown:md-sys-typescale-body-small peer-not-placeholder-shown:translate-y-0
+          peer-focus:top-spacing-100 peer-focus:md-sys-typescale-body-small peer-focus:translate-y-spacing-0
+          peer-not-placeholder-shown:top-spacing-100 peer-not-placeholder-shown:md-sys-typescale-body-small peer-not-placeholder-shown:translate-y-spacing-0
         `
             },
             outlined: {
                 label: `
-          peer-focus:top-0 peer-focus:md-sys-typescale-body-small peer-focus:-translate-y-1/2
-          peer-not-placeholder-shown:top-0 peer-not-placeholder-shown:md-sys-typescale-body-small peer-not-placeholder-shown:-translate-y-1/2
+          peer-focus:top-spacing-0 peer-focus:md-sys-typescale-body-small peer-focus:-translate-y-1/2
+          peer-not-placeholder-shown:top-spacing-0 peer-not-placeholder-shown:md-sys-typescale-body-small peer-not-placeholder-shown:-translate-y-1/2
         `
             }
         },
@@ -120,12 +120,12 @@ export const textfield = tv({
     compoundVariants: [
         {
             /* M3: an outlined label floats back to the field's start edge, over the leading icon, into
-               the notch. The wrapper starts after the icon (ml-3 + size-6 = 36px), so -20px puts the
+               the notch. The wrapper starts after the icon (ml-spacing-150 + size-spacing-300 = 36px), so -20px puts the
                label at 16px from the field's edge. */
             variant: 'outlined',
             leadingIcon: true,
             class: {
-                label: 'peer-focus:-left-5 peer-not-placeholder-shown:-left-5'
+                label: 'peer-focus:-left-spacing-250 peer-not-placeholder-shown:-left-spacing-250'
             }
         }
     ],

package/dist/components/forms/toggle-group/theme.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../../utils/tv.js';
 export type ToggleGroupVariants = VariantProps<typeof toggleGroup>;
 export type ToggleGroupItemVariants = VariantProps<typeof toggleGroupItem>;
 export declare const toggleGroup: import("tailwind-variants").TVReturnType<{

package/dist/components/forms/toggle-group/theme.js

@@ -1,7 +1,7 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const toggleGroup = tv({
     slots: {
-        root: 'inline-flex h-10 overflow-hidden rounded-full border border-md-sys-color-outline'
+        root: 'inline-flex h-spacing-500 overflow-hidden rounded-full border border-md-sys-color-outline'
     },
     variants: {
         orientation: {
@@ -13,7 +13,7 @@ export const toggleGroup = tv({
 });
 export const toggleGroupItem = tv({
     slots: {
-        base: 'layer-container state-layer relative inline-flex min-w-12 flex-1 items-center justify-center gap-2 px-4 md-sys-typescale-label-large text-md-sys-color-on-surface outline-none transition-colors md-sys-motion-fast-effects disabled:cursor-not-allowed disabled:opacity-38 [&:not(:last-child)]:border-r [&:not(:last-child)]:border-md-sys-color-outline data-[state=on]:bg-md-sys-color-secondary-container data-[state=on]:text-md-sys-color-on-secondary-container',
+        base: 'layer-container state-layer relative inline-flex min-w-spacing-600 flex-1 items-center justify-center gap-spacing-100 px-spacing-200 md-sys-typescale-label-large text-md-sys-color-on-surface outline-none transition-colors md-sys-motion-fast-effects disabled:cursor-not-allowed disabled:opacity-38 [&:not(:last-child)]:border-r [&:not(:last-child)]:border-md-sys-color-outline data-[state=on]:bg-md-sys-color-secondary-container data-[state=on]:text-md-sys-color-on-secondary-container',
         checkIcon: 'size-[18px] text-[18px]',
         icon: 'size-[18px] text-[18px]'
     }

package/dist/components/forms/tooltip/Tooltip.stories.svelte

@@ -10,6 +10,7 @@
 
   const { Story } = defineMeta({
     title: 'Forms/Tooltip',
+    tags: ['autodocs'],
     component: Tooltip
   });
 </script>

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

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../../utils/tv.js';
 export type TooltipVariants = VariantProps<typeof tooltip>;
 export declare const tooltip: import("tailwind-variants").TVReturnType<{
     variant: {

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

@@ -1,7 +1,7 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const tooltip = tv({
     slots: {
-        base: 'min-w-60 py-3 px-4  shadow-elevation-2 rounded-md relative z-[100] pointer-events-auto',
+        base: 'min-w-60 py-spacing-150 px-spacing-200  shadow-elevation-2 rounded-md relative z-layer-popup pointer-events-auto',
         subhead: '',
         supportingText: '',
         textContainer: '',
@@ -10,10 +10,10 @@ export const tooltip = tv({
     variants: {
         variant: {
             rich: {
-                base: 'flex flex-col gap-3'
+                base: 'flex flex-col gap-spacing-150'
             },
             snack: {
-                base: 'inline-flex min-w-0 max-w-50 bg-md-sys-color-inverse-surface text-md-sys-color-inverse-on-surface md-sys-typescale-body-small px-3 py-2 shadow-elevation-3 before:rounded-md',
+                base: 'inline-flex min-w-spacing-0 max-w-50 bg-md-sys-color-inverse-surface text-md-sys-color-inverse-on-surface md-sys-typescale-body-small px-spacing-150 py-spacing-100 shadow-elevation-3 before:rounded-md',
                 supportingText: 'text-md-sys-color-inverse-on-surface md-sys-typescale-body-small',
                 textContainer: ''
             }

package/dist/components/misc/Avatar.stories.svelte

@@ -4,6 +4,7 @@
 
   const { Story } = defineMeta({
     title: 'Misc/Avatar',
+    tags: ['autodocs'],
     component: Avatar,
     argTypes: {
       size: { control: 'select', options: ['sm', 'md', 'lg'] },
@@ -24,7 +25,7 @@
 </Story>
 
 <Story name="Sizes" asChild>
-  <div class="flex items-end gap-4">
+  <div class="gap-spacing-200 flex items-end">
     <Avatar size="sm" seed="small" />
     <Avatar size="md" seed="medium" />
     <Avatar size="lg" seed="large" />
@@ -32,7 +33,7 @@
 </Story>
 
 <Story name="Generated Fallback" asChild>
-  <div class="flex items-end gap-4">
+  <div class="gap-spacing-200 flex items-end">
     <Avatar seed="alice" />
     <Avatar seed="bob" />
     <Avatar seed="carol" />
@@ -40,7 +41,7 @@
 </Story>
 
 <Story name="With Image" asChild>
-  <div class="flex items-end gap-4">
+  <div class="gap-spacing-200 flex items-end">
     <Avatar src="https://picsum.photos/seed/ogonek-1/200" alt="Sample user" />
     <Avatar
       src="https://this-url-does-not-resolve.example/broken.jpg"
@@ -55,7 +56,7 @@
 </Story>
 
 <Story name="Animated" asChild>
-  <div class="flex items-end gap-4">
+  <div class="gap-spacing-200 flex items-end">
     <Avatar seed="alice" dicebearStyle="gaze" tags={['animation']} />
     <Avatar seed="bob" dicebearStyle="shapes" tags={['animation']} />
     <Avatar seed="carol" dicebearStyle="blobs" tags={['animation']} />

package/dist/components/misc/ThemeSettings.svelte

@@ -37,37 +37,37 @@
   }
 </script>
 
-<div class="flex w-full flex-col gap-6">
+<div class="gap-spacing-300 flex w-full flex-col">
   <!-- Source Color -->
-  <div class="flex flex-col gap-2">
+  <div class="gap-spacing-100 flex flex-col">
     <Title size="medium">Source Color</Title>
-    <div class="flex items-center gap-4">
+    <div class="gap-spacing-200 flex items-center">
       <input
         type="color"
         bind:value={themeState.sourceColor}
-        class="size-10 cursor-pointer bg-transparent"
+        class="size-spacing-500 cursor-pointer bg-transparent"
       />
       <Body size="medium">{themeState.sourceColor}</Body>
     </div>
-    <div class="mt-2 flex flex-col gap-1">
+    <div class="mt-spacing-100 gap-spacing-50 flex flex-col">
       <Body size="medium">Or extract from image:</Body>
       <input
         type="file"
         accept="image/*"
         onchange={handleImageUpload}
-        class="file:bg-md-sys-color-primary-container file:text-md-sys-color-on-primary-container hover:file:bg-md-sys-color-primary-container/80 md-sys-typescale-body-medium file:md-sys-typescale-label-large file:mr-4 file:rounded-full file:border-0 file:px-4 file:py-2"
+        class="file:bg-md-sys-color-primary-container file:text-md-sys-color-on-primary-container hover:file:bg-md-sys-color-primary-container/80 md-sys-typescale-body-medium file:md-sys-typescale-label-large file:mr-spacing-200 file:px-spacing-200 file:py-spacing-100 file:rounded-full file:border-0"
       />
     </div>
   </div>
 
   <!-- Scheme -->
-  <div class="flex flex-col gap-2">
+  <div class="gap-spacing-100 flex flex-col">
     <Title size="medium">Scheme</Title>
     <RadioGroup items={schemeItems} bind:value={themeState.scheme as any} orientation="vertical" />
   </div>
 
   <!-- Contrast -->
-  <div class="flex flex-col gap-2">
+  <div class="gap-spacing-100 flex flex-col">
     <Title size="medium">Contrast</Title>
     <RadioGroup
       items={contrastItems}
@@ -77,7 +77,7 @@
   </div>
 
   <!-- Variant -->
-  <div class="flex flex-col gap-2">
+  <div class="gap-spacing-100 flex flex-col">
     <Title size="medium">Variant</Title>
     <RadioGroup
       items={variantItems}

package/dist/components/misc/ThemeSwitcher.svelte

@@ -6,14 +6,14 @@
   let open = $state(false);
 </script>
 
-<div class="fixed right-4 bottom-4 z-50 hidden md:block">
+<div class="right-spacing-200 bottom-spacing-200 z-layer-fab fixed hidden md:block">
   <Popover bind:open title="Theme Settings" side="top" align="end" sideOffset={16}>
     {#snippet trigger(triggerProps)}
-      <FAB iconProps={{ name: 'palette' }} config="primary" {...triggerProps} />
+      <FAB iconProps={{ name: 'palette' }} {...triggerProps} />
     {/snippet}
 
     <div
-      class="scrollbar-thumb-md-sys-color-outline-variant hover:scrollbar-thumb-md-sys-color-outline flex max-h-[80vh] w-72 scrollbar-thin flex-col overflow-y-auto p-4"
+      class="scrollbar-thumb-md-sys-color-outline-variant hover:scrollbar-thumb-md-sys-color-outline p-spacing-200 flex max-h-[80vh] w-72 scrollbar-thin flex-col overflow-y-auto"
     >
       <ThemeSettings />
     </div>

package/dist/components/misc/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../utils/tv.js';
 export const avatar = tv({
     slots: {
         root: 'relative flex aspect-square shrink-0 items-center justify-center overflow-hidden rounded-full',
@@ -9,16 +9,16 @@ export const avatar = tv({
     variants: {
         size: {
             xxs: {
-                root: 'size-5'
+                root: 'size-spacing-250'
             },
             xs: {
-                root: 'size-8'
+                root: 'size-spacing-400'
             },
             sm: {
-                root: 'size-12'
+                root: 'size-spacing-600'
             },
             md: {
-                root: 'size-18'
+                root: 'size-spacing-900'
             },
             lg: {
                 root: 'size-24'

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

@@ -0,0 +1,71 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as AppBarStories from './AppBar.stories.svelte';
+import * as BreadcrumbStories from '../breadcrumb/Breadcrumb.stories.svelte';
+
+<Meta of={AppBarStories} />
+
+<Title />
+
+<Subtitle>Top app bars show the screen's title, navigation, and actions.</Subtitle>
+
+[M3 spec](https://m3.material.io/components/app-bars/specs) ·
+`import { AppBar } from '@noxlovette/material';`
+
+<Canvas of={AppBarStories.Playground} />
+
+<Controls of={AppBarStories.Playground} />
+
+## Two kinds of bar
+
+The props form a union, so the bar is one of two kinds:
+
+- **Titled bar.** Pass `title`. `size` is `small` (64dp, one line), or the Expressive `medium` or
+  `large` flexible bars, whose headline wraps and grows. `size` is responsive: pass
+  `{ small: 'small', large: 'large' }` to grow the bar on wider windows. The switch happens in CSS,
+  so server rendering needs no JS.
+- **Search bar.** Pass `search` (the hint text) instead. The bar is always 64dp. `title` then
+  becomes a screen-reader-only heading.
+
+<Canvas of={AppBarStories.MediumFlexible} />
+
+<Canvas of={AppBarStories.Search} />
+
+## Placement
+
+The bar is fixed at the top at every window size. Pass `ghost` to render a same-height spacer
+after it, so page content doesn't start underneath. The bar also publishes its height as
+`--appbar-height` on the root element. `Pane`/`PaneGrid` read it to shrink their `min-height`, so
+nothing needs wiring. Next to a `Rail`, pass the bar's height to the rail's `railTop`.
+
+```svelte
+<AppBar title="Inbox" ghost>
+  {#snippet trailing()}
+    <ButtonIcon variant="standard" iconProps={{ name: 'search' }} />
+    <ButtonIcon variant="standard" iconProps={{ name: 'more_vert' }} />
+  {/snippet}
+</AppBar>
+```
+
+## Scroll color
+
+The bar switches to its on-scroll color once the page scrolls more than 10px. If content scrolls
+inside a container instead (a `Pane`, say), pass that element as `scrollContainer`.
+
+<Canvas of={AppBarStories.ScrollContainer} />
+
+## Breadcrumbs
+
+`children` renders in a full-width row below the title, which is where a `Breadcrumb` goes. M3
+has no breadcrumb pattern, so `Breadcrumb` uses `label-large` crumbs separated by chevrons. The
+current page uses the emphasized `label-large` and is always static text with
+`aria-current="page"`. `color` sets the current crumb's color and the links' hover color.
+
+<Canvas of={BreadcrumbStories.InAppBar} />
+
+## Accessibility
+
+- **Landmark.** The bar renders a `<nav>`, which assistive tech announces as a landmark.
+- **Heading.** The title is the page's `<h1>`. On a search bar it stays an `<h1>`, hidden
+  visually. Don't render a second `<h1>` on the page.
+- **Back button.** `showBack` renders a labelled back button that calls `onback`, or
+  `history.back()` by default.