@noxlovette/material 0.6.0 → 0.7.0

package/dist/components/nav/rail/theme.js

@@ -1,10 +1,35 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
+/*
+  M3 Expressive navigation rail (https://m3.material.io/components/navigation-rail/specs):
+  - Container: `surface-container`, the spec's optional container role, which is this library's
+    window colour (App), so the rail reads as part of the window beside `surface` panes rather
+    than as a strip. The modal rail's token is `surface-container` too.
+  - Collapsed: 96dp wide, no elevation or shape. Destinations sit 4dp apart.
+  - Expanded: hugs its widest destination between 220 and 360dp, destinations touching. Standard
+    (lg+, pushes content) keeps the collapsed container; modal (md, over a scrim) adds
+    elevation 3 and 16dp trailing corners.
+  - 44dp above the first element; at least 40dp between the menu/FAB header and the destinations.
+  - Header elements sit in a 56dp column 20dp from the leading edge, the same column as the
+    destinations' active indicators, so nothing shifts sideways when the rail expands.
+  Expanding is one spatial spring on a progress value, 0 collapsed to 1 expanded, which
+  Rail.svelte writes to `--rail-p` (after Compose's WideNavigationRail). The width, the gap
+  between destinations, the modal corners and each destination's geometry all follow it, so
+  nothing here transitions spatially on its own.
+*/
 export const rail = tv({
     slots: {
-        base: 'py-spacing-600 hidden bg-md-sys-color-surface-container z-40 flex-col md:flex gap-spacing-300 transition-[width,padding,background-color] md-sys-motion-spatial',
-        items: 'flex flex-col gap-spacing-150 pt-spacing-300 scrollbar-none w-full overflow-x-hidden',
-        ghost: 'hidden md:block shrink-0 transition-[width] md-sys-motion-spatial',
-        scrim: 'hidden md:block lg:hidden inset-spacing-0'
+        // Modal corners grow with the progress (0 → 16dp); the standard rail stays square.
+        base: 'rounded-r-[calc(var(--radius-lg)_*_var(--rail-p,0))] lg:rounded-r-none hidden md:flex flex-col z-layer-rail overflow-hidden pt-(--md-comp-nav-rail-collapsed-top-space) pb-spacing-250 bg-md-sys-color-surface-container transition-[box-shadow] md-sys-motion-effects',
+        // Always start-aligned: collapsed, the content box is exactly the 56dp column, so this is
+        // centred anyway. Centring it would fling the menu and FAB to the middle of the still-wide
+        // rail the moment a collapse starts.
+        header: 'flex flex-col items-start gap-spacing-300 px-spacing-250',
+        menu: 'flex w-spacing-700 justify-center',
+        nav: 'flex min-h-spacing-0 w-full flex-1 flex-col',
+        // 4dp between destinations collapsed, 0 expanded, following the progress.
+        items: 'flex w-full flex-col overflow-x-hidden overflow-y-auto [scrollbar-width:none] gap-[calc(var(--spacing-spacing-50)_*_(1_-_var(--rail-p,0)))]',
+        ghost: 'hidden md:block shrink-0 w-(--md-comp-nav-rail-collapsed-container-width) lg:w-(--rail-width)',
+        scrim: 'hidden md:block lg:hidden inset-spacing-0 z-layer-rail bg-md-sys-color-scrim/32 transition-opacity md-sys-motion-effects'
     },
     variants: {
         anchor: {
@@ -19,15 +44,19 @@ export const rail = tv({
         },
         expanded: {
             true: {
-                base: 'pl-spacing-450 w-60 items-start bg-md-sys-color-surface-container-highest lg:bg-md-sys-color-surface-container rounded-r-lg',
-                ghost: 'w-24 lg:w-60'
+                base: 'w-max min-w-(--md-comp-nav-rail-expanded-container-width-minimum) max-w-(--md-comp-nav-rail-expanded-container-width-maximum) pt-(--md-comp-nav-rail-expanded-top-space) shadow-elevation-3 lg:shadow-elevation-0',
+                scrim: 'opacity-100'
             },
             false: {
-                base: 'w-24 items-center',
-                items: 'items-center',
-                ghost: 'w-24'
+                base: 'w-(--md-comp-nav-rail-collapsed-container-width)',
+                scrim: 'pointer-events-none opacity-0'
             }
         },
+        /* Header space: only when there is a header to keep the destinations away from. */
+        header: {
+            true: { nav: 'mt-spacing-500' },
+            false: {}
+        },
         rounded: {
             true: {
                 base: 'rounded-xl'
@@ -36,81 +65,65 @@ export const rail = tv({
         }
     },
     defaultVariants: {
-        anchor: 'viewport'
+        anchor: 'viewport',
+        header: false
     }
 });
+/*
+  One destination. The link spans the rail's full width (M3: the target area always does); the
+  active indicator inside it hugs its contents. Collapsed, the indicator is 56×32 around the icon
+  with the label 4dp below; expanded, it's a 56dp pill around icon and label, 16dp padding, 8dp
+  between them. State layers are `on-secondary-container` at 8% hover and 10% focus/press, drawn
+  on the indicator but triggered anywhere on the link. Selecting a destination grows its fill
+  out from the centre (M3's active indicator, after Compose's NavigationRailItem).
+
+  Geometry isn't here: it interpolates on the rail's expand progress, in RailItem.svelte's
+  <style>. `layout` is which side of the halfway point that progress is on, and decides only
+  what may switch while the label is invisible: its typescale and colour.
+*/
 export const railElement = tv({
     slots: {
-        base: 'group relative z-30 flex w-full transition-all md-sys-motion-spatial',
-        content: 'flex items-center min-w-spacing-0 rounded-full gap-spacing-25 py-spacing-75 transition-all md-sys-motion-spatial',
-        iconContainer: 'relative rounded-full items-center justify-center inline-flex transition-all md-sys-motion-spatial',
-        icon: 'text-[24px] transition-all md-sys-motion-spatial',
-        label: 'transition-all md-sys-motion-spatial whitespace-nowrap'
+        base: 'group rail-item relative flex w-full px-spacing-250 outline-none',
+        // As wide as the expanded pill, so an expanded rail (w-max) hugs its widest destination.
+        sizer: 'relative h-full shrink-0 pl-spacing-600 pr-spacing-200',
+        measure: 'invisible md-sys-typescale-label-large whitespace-nowrap',
+        indicator: 'rail-indicator absolute left-spacing-0 isolate rounded-full state-layer before:rounded-full',
+        // The selected fill, under the state layer. It grows from the indicator's centre to its
+        // edges on select and shrinks back on deselect, on RailItem's --rail-sel spring.
+        fill: 'rail-fill absolute -z-10 rounded-full bg-md-sys-color-secondary-container',
+        icon: 'rail-icon absolute left-spacing-200 inline-flex',
+        label: 'rail-label absolute whitespace-nowrap transition-colors md-sys-motion-fast-effects'
     },
     variants: {
         active: {
             true: {
-                content: 'text-md-sys-color-on-secondary-container',
-                label: 'font-bold',
-                iconContainer: 'group-hover:text-md-sys-color-secondary  bg-md-sys-color-secondary-container'
+                icon: 'text-md-sys-color-on-secondary-container'
             },
             false: {
-                content: 'text-md-sys-color-on-surface-variant',
-                iconContainer: ''
+                icon: 'text-md-sys-color-on-surface-variant',
+                label: 'text-md-sys-color-on-surface-variant'
             }
         },
-        expanded: {
-            true: {
-                base: 'justify-start',
-                content: 'p-spacing-200 gap-spacing-150',
-                iconContainer: '',
-                label: 'md-sys-typescale-label-large'
-            },
-            false: {
-                base: 'text-center justify-center',
-                content: 'flex-col',
-                iconContainer: 'py-spacing-75 px-spacing-200',
-                label: 'md-sys-typescale-label-medium'
-            }
+        layout: {
+            top: { label: 'md-sys-typescale-label-medium' },
+            start: { label: 'md-sys-typescale-label-large' }
         },
         disabled: {
             true: {
                 base: 'cursor-not-allowed opacity-38'
-            }
-        },
-        mobile: {
-            true: {
-                base: 'flex-1 flex-col items-center justify-center h-full min-w-spacing-0 max-w-[168px]',
-                content: 'py-spacing-0 gap-spacing-50 items-center justify-center w-full',
-                iconContainer: 'h-spacing-400 w-spacing-800 py-spacing-0 px-spacing-0',
-                icon: 'size-spacing-300',
-                label: 'truncate w-full text-center'
             },
-            false: {}
+            false: {
+                // State layer and focus ring on the indicator, triggered by the full-width link.
+                indicator: 'group-hover:before:bg-md-sys-color-on-secondary-container/8 group-focus-visible:before:bg-md-sys-color-on-secondary-container/10 group-active:before:bg-md-sys-color-on-secondary-container/10 group-focus-visible:outline-3 group-focus-visible:outline-offset-2 group-focus-visible:outline-md-sys-color-secondary'
+            }
         }
     },
     compoundVariants: [
-        {
-            expanded: true,
-            active: true,
-            class: {
-                iconContainer: 'bg-transparent',
-                content: 'bg-md-sys-color-secondary-container'
-            }
-        },
-        {
-            expanded: true,
-            active: false,
-            class: {
-                content: 'group-hover:bg-md-sys-color-surface-variant'
-            }
-        },
-        {
-            expanded: false,
-            active: false,
-            class: {
-                iconContainer: 'group-hover:bg-md-sys-color-surface-variant'
-            }
-        }
-    ]
+        { active: true, layout: 'top', class: { label: 'text-md-sys-color-secondary' } },
+        { active: true, layout: 'start', class: { label: 'text-md-sys-color-on-secondary-container' } }
+    ],
+    defaultVariants: {
+        layout: 'top',
+        disabled: false
+    }
 });

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

@@ -41,6 +41,10 @@ export type RailProps = RailVariants & HTMLAttributes<HTMLDivElement> & {
     anchor?: RailVariants['anchor'];
     /** Top offset in px for viewport/parent anchor (e.g. height of a top bar). Default 0. */
     railTop?: number;
+    /** Tooltip and accessible name of the toggle while collapsed. Default 'Expand navigation'. */
+    expandLabel?: string;
+    /** Tooltip and accessible name of the toggle while expanded. Default 'Collapse navigation'. */
+    collapseLabel?: string;
     /**
      * @deprecated No effect: Rail no longer renders a navigation bar below `md`. Mount a `Navbar`
      * next to it for small windows.

package/dist/components/nav/tabs/Tabs.stories.svelte

@@ -3,6 +3,7 @@
   import TabHolder from './TabHolder.svelte';
   import TabContent from './TabContent.svelte';
   import Body from '../../typography/body/Body.svelte';
+  import type { TabProps } from './types.js';
 
   const { Story } = defineMeta({
     title: 'Navigation/Tabs',
@@ -27,7 +28,7 @@
     { value: 'flights', name: 'Flights', iconProps: { name: 'flight' } },
     { value: 'trips', name: 'Trips', iconProps: { name: 'luggage' } },
     { value: 'explore', name: 'Explore', iconProps: { name: 'explore' } }
-  ];
+  ] satisfies TabProps[];
 </script>
 
 <Story name="Playground">

package/dist/components/nav/tabs/theme.d.ts

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

package/dist/components/nav/tabs/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const tabHolder = tv({
     slots: {
         base: 'relative flex w-full bg-md-sys-color-surface',

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

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

package/dist/components/pill/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../utils/tv.js';
 export const pill = tv({
     base: 'relative inline-flex items-center justify-center px-spacing-200 py-spacing-75 md-sys-typescale-label-large select-none rounded-full whitespace-nowrap',
     variants: {

package/dist/components/progress/LinearProgress.svelte

@@ -11,7 +11,7 @@ The track always keeps a gap either side of the bar.
 -->
 <script lang="ts">
   import clsx from 'clsx';
-  import { tv } from 'tailwind-variants';
+  import { tv } from '../../utils/tv.js';
   import { Progress } from 'bits-ui';
   import { animate, type AnimationPlaybackControls } from 'motion';
   import { springTokens, springTransition } from '../../animation/spring.js';

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

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

package/dist/components/snackbar/theme.js

@@ -1,7 +1,7 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../utils/tv.js';
 export const snackbar = tv({
     slots: {
-        base: 'rounded-xs relative min-h-spacing-600 md:max-h-17 flex z-[100] items-center bg-md-sys-color-inverse-surface shadow-elevation-3 pr-spacing-100 pl-spacing-200 justify-between h-max py-spacing-150',
+        base: 'rounded-xs relative min-h-spacing-600 md:max-h-17 flex z-layer-snackbar items-center bg-md-sys-color-inverse-surface shadow-elevation-3 pr-spacing-100 pl-spacing-200 justify-between h-max py-spacing-150',
         label: 'text-md-sys-color-inverse-primary md-sys-typescale-label-large px-spacing-150 cursor-pointer ',
         actionWrapper: 'flex items-center z-40',
         supportingText: 'text-md-sys-color-inverse-on-surface md-sys-typescale-body-medium max-w-[60ch] ',

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

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../utils/tv.js';
 export declare const table: import("tailwind-variants").TVReturnType<{
     hoverable: {
         true: {

package/dist/components/table/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../utils/tv.js';
 export const table = tv({
     slots: {
         root: 'w-full border-collapse text-left md-sys-typescale-body-medium text-md-sys-color-on-surface',

package/dist/components/time/TimeField.svelte

@@ -92,7 +92,7 @@ It combines a Material 3 Textfield with a TimepickerInput for intuitive time sel
       align="start"
       sideOffset={12}
       collisionPadding={8}
-      class="z-100"
+      class="z-layer-popup"
     >
       {#snippet child({ wrapperProps, props, open })}
         <div {...wrapperProps}>

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

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../utils/tv.js';
 export type TimepickerVariants = VariantProps<typeof timepicker>;
 export declare const timepicker: import("tailwind-variants").TVReturnType<{
     [key: string]: {

package/dist/components/time/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../utils/tv.js';
 export const timepicker = tv({
     slots: {
         base: 'bg-md-sys-color-surface-container-high shadow-elevation-3 rounded-xl max-w-fit p-spacing-300 group relative',

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

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../utils/tv.js';
 export type ToolbarVariants = VariantProps<typeof toolbar>;
 export type ToolbarButtonVariants = VariantProps<typeof toolbarButton>;
 export type ToolbarGroupItemVariants = VariantProps<typeof toolbarGroupItem>;

package/dist/components/toolbar/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../utils/tv.js';
 export const toolbar = tv({
     slots: {
         // Layout/position only — no paint. Holds one implicit `segment` by default, or,
@@ -33,7 +33,7 @@ export const toolbar = tv({
         },
         variant: {
             floating: { root: 'inline-flex', segment: 'rounded-full shadow-elevation-1' },
-            docked: { root: 'fixed left-spacing-0 z-10 w-full', segment: 'w-full rounded-none' }
+            docked: { root: 'fixed left-spacing-0 z-layer-bar w-full', segment: 'w-full rounded-none' }
         },
         color: {
             standard: { segment: 'bg-md-sys-color-surface-container' },

package/dist/components/typography/body/theme.d.ts

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

package/dist/components/typography/body/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const body = tv({
     base: '',
     variants: {

package/dist/components/typography/display/theme.d.ts

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

package/dist/components/typography/display/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const display = tv({
     base: '',
     variants: {

package/dist/components/typography/headline/theme.d.ts

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

package/dist/components/typography/headline/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const headline = tv({
     base: '',
     variants: {

package/dist/components/typography/kbd/theme.d.ts

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

package/dist/components/typography/kbd/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const kbd = tv({
     base: 'md-sys-typescale-emphasized-label-small text-md-sys-color-on-surface-variant',
     variants: {

package/dist/components/typography/label/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const label = tv({
     base: '',
     variants: {

package/dist/components/typography/title/theme.d.ts

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

package/dist/components/typography/title/theme.js

@@ -1,4 +1,4 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const title = tv({
     base: '',
     variants: {

package/dist/index.css

@@ -3,5 +3,8 @@
 @import './styles/motion.css';
 @import './styles/rounding.css';
 @import './styles/elevation.css';
+@import './styles/layers.css';
+@import './styles/components.css';
+@import './styles/icon.css';
 @import './styles/prose.css';
 @import './styles/component.css';

package/dist/styles/components.css

@@ -0,0 +1,50 @@
+/*
+ * M3 component dimensions that aren't on the spacing scale (issue #30). Each property is named
+ * after its token in the M3 token database, md.comp.<component>.<…> with dots as dashes, and
+ * used as `w-(--md-comp-…)`. A dimension that lands on the spacing grid uses the spacing token
+ * instead (the rail's 4dp item gap is `gap-spacing-50`, not a property here).
+ */
+:root {
+  /* Navigation rail: https://m3.material.io/components/navigation-rail/specs */
+  --md-comp-nav-rail-collapsed-container-width: 6rem; /* 96dp */
+  --md-comp-nav-rail-collapsed-top-space: 2.75rem; /* 44dp */
+  --md-comp-nav-rail-expanded-top-space: 2.75rem; /* 44dp */
+  --md-comp-nav-rail-expanded-container-width-minimum: 13.75rem; /* 220dp */
+  --md-comp-nav-rail-expanded-container-width-maximum: 22.5rem; /* 360dp */
+}
+
+/*
+ * How far the page's content starts from the leading edge to clear a viewport-anchored Rail.
+ * The Rail writes --md-rail-width (its drawn width, every frame while it springs) on <html>;
+ * with no Rail mounted it's unset and the inset is 0. On medium windows the expanded rail is
+ * modal and overlays the content, so the inset stays at the collapsed width; from lg the
+ * standard rail pushes the content, so the inset follows its width. App's shell pads by it;
+ * fixed surfaces that span the window (AppBar) start at it. Custom layouts: `ps-(--md-rail-inset)`.
+ */
+:root {
+  --md-rail-inset: 0px;
+}
+@media (width >= 48rem) {
+  :root {
+    --md-rail-inset: var(--md-rail-rest, 0px);
+  }
+}
+@media (width >= 64rem) {
+  :root {
+    --md-rail-inset: var(--md-rail-width, 0px);
+  }
+}
+
+/*
+ * A page built on App behaves as an app, not a document: scrolling stops at its edges instead of
+ * bouncing (macOS/iOS rubber-banding) or chaining into pull-to-refresh, which showed the blank
+ * canvas past App's shell. The canvas takes the window colour anyway, for the browsers that
+ * still overscroll and the safe areas around it. Scoped to pages with an App, and in the base
+ * layer, so a consumer can restore overscroll with one `html { overscroll-behavior: auto }`.
+ */
+@layer base {
+  :root:has(.md-app) {
+    overscroll-behavior: none;
+    background-color: var(--color-md-sys-color-surface-container);
+  }
+}

package/dist/styles/icon.css

@@ -0,0 +1,13 @@
+/*
+  Default grade for Icon's `grad="auto"`. Light icons on a dark background look heavier than dark
+  ones on a light background (visual bleed), so M3 drops the grade to -25 on dark UI.
+  https://m3.material.io/styles/icons/applying-icons#grade
+*/
+:root {
+  --md-icon-grade: 0;
+}
+
+.dark,
+[data-theme^='dark'] {
+  --md-icon-grade: -25;
+}

package/dist/styles/layers.css

@@ -0,0 +1,33 @@
+/*
+ * Stacking layers for surfaces that float over the page. M3 defines no z-index tokens, so the
+ * library names its own: every fixed, sticky or portaled component takes one of these instead
+ * of a number, so their relative order is set here and nowhere else. Apply with
+ * `z-layer-<name>` (z-layer-modal); override the value on :root with `--z-layer-<name>`.
+ * Stacking inside one component (a slider thumb over its track) keeps plain z-10/z-20.
+ *
+ * Order, lowest first:
+ *   bar       Navbar, AppBar, ActionRail, docked Toolbar
+ *   rail      Rail and its tablet scrim (the expanded rail covers the bars)
+ *   sheet     standard (non-modal) BottomSheet
+ *   fab       fixed FABs such as ThemeSwitcher
+ *   pane      DraggablePane and its minimised pill, floating windows over app chrome
+ *   modal     Dialogue scrim and content, a FAB's container-transform surface
+ *   snackbar  stays readable while a dialog is open
+ *   popup     menus, selects, tooltips, popovers, date/time pickers, opened from any layer
+ *             beneath, including a dialog or a pane
+ * Modal sheets are native <dialog>s in the top layer and sit above all of these.
+ */
+@theme static {
+  --z-layer-bar: 30;
+  --z-layer-rail: 40;
+  --z-layer-sheet: 40;
+  --z-layer-fab: 50;
+  --z-layer-pane: 60;
+  --z-layer-modal: 70;
+  --z-layer-snackbar: 80;
+  --z-layer-popup: 90;
+}
+
+@utility z-layer-* {
+  z-index: --value(--z-layer-*);
+}

package/dist/utils/icon/Icon.stories.svelte

@@ -0,0 +1,97 @@
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Body from '../../components/typography/body/Body.svelte';
+  import ButtonIcon from '../../components/buttons/ButtonIcon.svelte';
+  import Icon from './Icon.svelte';
+
+  const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+  const variants = ['rounded', 'outlined', 'sharp'] as const;
+
+  const { Story } = defineMeta({
+    title: 'Utils/Icon',
+    component: Icon,
+    tags: ['autodocs'],
+    argTypes: {
+      size: { control: 'select', options: ['inline', ...sizes] },
+      variant: { control: 'inline-radio', options: variants },
+      fill: { control: { type: 'range', min: 0, max: 1, step: 0.1 } },
+      wght: { control: { type: 'range', min: 100, max: 700, step: 100 } },
+      grad: { control: 'select', options: ['auto', -50, -25, 0, 100, 200] },
+      opsz: { control: { type: 'range', min: 20, max: 48, step: 1 } },
+      transition: { control: 'inline-radio', options: ['none', 'fade', 'rotate'] }
+    },
+    args: { name: 'favorite', size: 'xl', variant: 'rounded', fill: 0, wght: 400, grad: 'auto' }
+  });
+</script>
+
+<script lang="ts">
+  let menuOpen = $state(false);
+  let adding = $state(false);
+  let playing = $state(false);
+</script>
+
+<Story name="Playground" />
+
+<!-- Toggle each button, and toggle again mid-flight: the spring reverses from where it is. -->
+<Story name="Transitions" asChild>
+  <div class="gap-spacing-300 flex items-center">
+    <ButtonIcon
+      variant="standard"
+      tooltipContent="rotate: menu ↔ menu_open"
+      iconProps={{ name: menuOpen ? 'menu_open' : 'menu', transition: 'rotate' }}
+      onclick={() => (menuOpen = !menuOpen)}
+    />
+    <ButtonIcon
+      variant="tonal"
+      tooltipContent="rotate: add ↔ close"
+      iconProps={{ name: adding ? 'close' : 'add', transition: 'rotate' }}
+      onclick={() => (adding = !adding)}
+    />
+    <ButtonIcon
+      variant="filled"
+      tooltipContent="fade: play_arrow ↔ pause"
+      iconProps={{ name: playing ? 'pause' : 'play_arrow', transition: 'fade' }}
+      onclick={() => (playing = !playing)}
+    />
+  </div>
+</Story>
+
+<Story name="Styles" asChild>
+  <div class="gap-spacing-300 flex">
+    {#each variants as variant (variant)}
+      <Icon name="home" size="lg" {variant} />
+    {/each}
+  </div>
+</Story>
+
+<Story name="Sizes" asChild>
+  <div class="gap-spacing-300 flex items-end">
+    {#each sizes as size (size)}
+      <Icon name="settings" {size} />
+    {/each}
+  </div>
+</Story>
+
+<Story name="Fill for state" asChild>
+  <div class="gap-spacing-300 flex">
+    <Icon name="favorite" size="lg" fill={0} />
+    <Icon name="favorite" size="lg" fill={1} />
+  </div>
+</Story>
+
+<Story name="Weights" asChild>
+  <div class="gap-spacing-200 flex">
+    {#each [200, 300, 400, 500, 600, 700] as wght (wght)}
+      <Icon name="search" size="lg" {wght} />
+    {/each}
+  </div>
+</Story>
+
+<Story name="Inline with text" asChild>
+  <Body size="large">
+    Saved to favorites <Icon name="favorite" size="inline" fill={1} />, shared <Icon
+      name="share"
+      size="inline"
+    />
+  </Body>
+</Story>

package/dist/utils/icon/Icon.stories.svelte.d.ts

@@ -0,0 +1,4 @@
+import Icon from './Icon.svelte';
+declare const Icon: import("svelte").Component<Record<string, never>, {}, "">;
+type Icon = ReturnType<typeof Icon>;
+export default Icon;