fancy-ui-svelte 0.12.0 → 0.14.0

package/dist/fancy-ui/button/Button.svelte

@@ -48,8 +48,11 @@
 </script>
 
 <script lang="ts">
+	import { fade } from "svelte/transition";
 	import { cn } from "../../utils.js";
 	import { sound as soundFx } from "../sound/sound.svelte.js";
+	import { prefersReducedMotion } from "../_internals/motion/anchored.js";
+	import { DURATIONS } from "../_internals/motion/tokens.js";
 
 	let {
 		variant = "primary",
@@ -93,7 +96,14 @@
 		cn(
 			"ft-btn",
 			"inline-flex items-center justify-center gap-2 whitespace-nowrap font-medium",
-			"cursor-pointer transition-colors",
+			// No `transition-colors` here: the scoped style block below declares a
+			// `transition` shorthand on this same element (it has to, so the press
+			// scale can join the colour channel under `prefers-reduced-motion:
+			// no-preference`), and Svelte's scoped CSS is unlayered while Tailwind's
+			// utilities sit in `@layer utilities` — the utility would lose silently
+			// and read as a colour transition that never ran. The colour channel is
+			// re-declared by hand at exactly the values it resolved to.
+			"cursor-pointer",
 			"focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-[var(--ft-btn-accent)]/35",
 			// `data-disabled` covers the anchor branch, which has no native `:disabled`
 			// pseudo-class to hang the same dimmed treatment off. It tracks `disabled`
@@ -132,6 +142,21 @@
 	// can't drift out of sync with each other.
 	const anchorInert = $derived(disabled || loading);
 
+	// The one duration the lead slot's cross-fade runs on: `DURATIONS.micro`, the
+	// glyph-scale rung, collapsed to 0 when the user has asked for less motion —
+	// at 0 Svelte skips `element.animate()` entirely and the swap is synchronous,
+	// which is the same behaviour this button had before the fade existed.
+	//
+	// Deliberately a plain function, never a `$derived`: `prefersReducedMotion()`
+	// resolves `window.matchMedia` fresh on every call and its own contract
+	// (`_internals/motion/anchored.ts`) forbids reading it from a `$derived`,
+	// where the answer would be computed once and then never revisited. A
+	// transition's params thunk runs once per transition, at the instant that
+	// transition starts — exactly the call site that contract sanctions.
+	function leadFade() {
+		return prefersReducedMotion() ? 0 : DURATIONS.micro;
+	}
+
 	// The single guard both branches funnel through. A native `disabled` button
 	// already refuses real pointer/keyboard input, but a synthetic `.click()` (or
 	// an anchor, which has no disabled state at all) walks straight past that —
@@ -160,10 +185,29 @@
 		tabindex={anchorInert ? -1 : undefined}
 		onclick={handleClick}
 	>
-		{#if loading}
-			<span class="ft-btn-spinner" aria-hidden="true"></span>
-		{:else if iconStart}
-			{@render iconStart()}
+		<!--
+			The lead slot. Both branches of this component render it identically —
+			see the button branch below for why the split `in:` / `out:` pair is
+			the right shape here rather than one bidirectional `transition:`.
+		-->
+		{#if loading || iconStart}
+			<span class="ft-btn-lead" aria-hidden={loading ? "true" : undefined}>
+				{#if loading}
+					<span
+						class="ft-btn-spinner"
+						in:fade={{ duration: leadFade() }}
+						out:fade={{ duration: leadFade() }}
+					></span>
+				{:else}
+					<span
+						class="ft-btn-lead-icon"
+						in:fade={{ duration: leadFade() }}
+						out:fade={{ duration: leadFade() }}
+					>
+						{@render iconStart?.()}
+					</span>
+				{/if}
+			</span>
 		{/if}
 		{@render children?.()}
 		{#if iconEnd}
@@ -180,10 +224,46 @@
 		aria-busy={loading ? "true" : undefined}
 		onclick={handleClick}
 	>
-		{#if loading}
-			<span class="ft-btn-spinner" aria-hidden="true"></span>
-		{:else if iconStart}
-			{@render iconStart()}
+		<!--
+			The lead slot: one fixed-size cell that holds the spinner and
+			`iconStart` at the same time, so `loading` swaps them by cross-fading
+			in place instead of cutting, and the label beside it never shifts.
+
+			A split `in:` / `out:` pair rather than one bidirectional
+			`transition:`, which is the shape the rest of this campaign uses. Two
+			reasons, both structural: the spinner and the icon are DIFFERENT
+			elements, so there is no single node whose transition could be
+			bidirectional; and a cross-fade wants both halves running at once
+			rather than one after the other. The outer `{#if loading || iconStart}`
+			keeps a button with neither from paying for an empty grid cell — and,
+			because a local transition never plays on the initial render of the
+			block that owns it, a button that starts out `loading` still renders
+			its spinner instantly, with no fade in from nothing.
+
+			`aria-hidden` sits on the slot rather than on the spinner so that it
+			covers the whole cell for the length of the fade: mid-swap the
+			outgoing icon is still mounted, and a screen reader has no business
+			reading a glyph that is on its way out of a control already marked
+			`aria-busy`.
+		-->
+		{#if loading || iconStart}
+			<span class="ft-btn-lead" aria-hidden={loading ? "true" : undefined}>
+				{#if loading}
+					<span
+						class="ft-btn-spinner"
+						in:fade={{ duration: leadFade() }}
+						out:fade={{ duration: leadFade() }}
+					></span>
+				{:else}
+					<span
+						class="ft-btn-lead-icon"
+						in:fade={{ duration: leadFade() }}
+						out:fade={{ duration: leadFade() }}
+					>
+						{@render iconStart?.()}
+					</span>
+				{/if}
+			</span>
 		{/if}
 		{@render children?.()}
 		{#if iconEnd}
@@ -198,6 +278,113 @@
 			--ft-accent,
 			light-dark(oklch(0.5432 0.2528 300.22), oklch(0.604 0.2606 301.75))
 		);
+		/* 150ms = tokens.DURATIONS.fast, cubic-bezier(0.4, 0, 0.2, 1) =
+		   tokens.EASINGS.inout — the reversible-state pair. It runs the colour
+		   channel, and the release half of the press: letting go settles, it
+		   does not snap back. */
+		--ft-btn-motion: var(--ft-duration-fast, 150ms)
+			var(--ft-ease-inout, cubic-bezier(0.4, 0, 0.2, 1));
+		/* The down-stroke only. 150ms = tokens.DURATIONS.fast,
+		   cubic-bezier(0.16, 1, 0.3, 1) = tokens.EASINGS.out — the arrival
+		   curve, which spends most of the scale in the first frames. Same clock
+		   as the release, but the button is already down by the time the eye
+		   reads it, so the press bites instead of easing in. Pressing is an
+		   arrival; releasing is what resolves either way. */
+		--ft-btn-press: var(--ft-duration-fast, 150ms) var(--ft-ease-out, cubic-bezier(0.16, 1, 0.3, 1));
+		/*
+		 * Replaces the `transition-colors` utility removed from the class string
+		 * above, at exactly the values that utility already resolved to. Colour is
+		 * a state change, not motion, so it stays OUTSIDE the reduced-motion query
+		 * — gating it would only make a theme flip look broken for the people who
+		 * asked for less movement.
+		 *
+		 * `box-shadow` is deliberately absent, and must stay absent: this button's
+		 * focus ring is `focus-visible:ring-*`, which compiles to a `box-shadow`,
+		 * and a focus ring must never animate. `text-decoration-color`, `fill` and
+		 * `stroke` never change on this control, so the three listed here are the
+		 * faithful subset of what the utility covered.
+		 */
+		transition:
+			color var(--ft-btn-motion),
+			background-color var(--ft-btn-motion),
+			border-color var(--ft-btn-motion);
+		/* Kills the ~300ms tap delay without blocking scroll — the same rule, for
+		   the same reason, as `.ft-pressable` and `.ft-toggle`. A press that
+		   answers a third of a second late is not press feedback. */
+		touch-action: manipulation;
+	}
+
+	/*
+	 * The press. Pressable's contract inlined as a plain rule on the native
+	 * control rather than wrapping a `<button>` in a `<Pressable>` div — same
+	 * `0.97`, same clock, one element instead of two.
+	 *
+	 * Only the property list is re-declared in here: `transform` joins the colour
+	 * channel under `no-preference` and nowhere else, so with motion reduced the
+	 * colours still cross and the button simply does not move. The resting state
+	 * (no `transform` at all) is the ungated fallback.
+	 *
+	 * The two strokes are timed apart. The rule below carries the release curve,
+	 * because that is the transition the button runs on its way back to rest;
+	 * `:active` overrides `transform` with the arrival curve for the way down.
+	 */
+	@media (prefers-reduced-motion: no-preference) {
+		.ft-btn {
+			transition:
+				color var(--ft-btn-motion),
+				background-color var(--ft-btn-motion),
+				border-color var(--ft-btn-motion),
+				transform var(--ft-btn-motion);
+		}
+
+		/* Both inert states are excluded so a press that does nothing does not
+		   pretend to. `[data-disabled]` is the anchor branch, which has no native
+		   `:disabled` to hang this off; `[aria-busy]` is the loading one, on both
+		   branches. A native disabled `<button>` never matches `:active` anyway —
+		   the attribute selectors are what make the anchor behave like it. */
+		.ft-btn:not([data-disabled="true"]):not([aria-busy="true"]):active {
+			transform: scale(0.97);
+			/* The whole list is re-declared rather than just
+			   `transition-timing-function`, which has no per-property form here:
+			   a single value would retime the colour channel too, and a
+			   four-value one would restate the same three curves to change the
+			   fourth. Only `transform` differs from the rule above. */
+			transition:
+				color var(--ft-btn-motion),
+				background-color var(--ft-btn-motion),
+				border-color var(--ft-btn-motion),
+				transform var(--ft-btn-press);
+		}
+	}
+
+	/*
+	 * The lead slot: one fixed cell the spinner and `iconStart` share, sized
+	 * exactly like the spinner it holds (`calc(1em + 1px)`, read from the
+	 * button's own font-size, so it follows the size variant for free). Fixed
+	 * rather than content-sized on purpose — a slot that measured whichever
+	 * child happened to be mounted would grow while both are cross-fading and
+	 * snap back the frame the fade ended, moving the label twice for one swap.
+	 */
+	.ft-btn-lead {
+		display: grid;
+		place-items: center;
+		flex: none;
+		width: calc(1em + 1px);
+		height: calc(1em + 1px);
+	}
+
+	/* Both children occupy the one cell at once — that overlap IS the
+	   cross-fade. Named rather than `> *` so a caller's own `iconStart` markup,
+	   which is one level further down, is never caught by it. */
+	.ft-btn-lead > .ft-btn-spinner,
+	.ft-btn-lead > .ft-btn-lead-icon {
+		grid-area: 1 / 1;
+	}
+
+	.ft-btn-lead-icon {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
 	}
 
 	.ft-btn--accent {

package/dist/fancy-ui/button/Button.test.js

@@ -1,7 +1,8 @@
-import { render, cleanup, fireEvent } from "@testing-library/svelte";
-import { createRawSnippet } from "svelte";
+import { render, cleanup, fireEvent, waitFor } from "@testing-library/svelte";
+import { createRawSnippet, tick } from "svelte";
 import { afterEach, describe, it, expect, vi, beforeEach } from "vitest";
 import Button from "./Button.svelte";
+import LeadHarness from "./ButtonLeadHarness.test.svelte";
 import { sound } from "../sound/sound.svelte.js";
 function snippet(html) {
     return createRawSnippet(() => ({ render: () => html }));
@@ -9,8 +10,27 @@ function snippet(html) {
 function root(container) {
     return container.firstElementChild;
 }
+/** Replaces `window.matchMedia` wholesale — the pattern the rest of the repo
+ * uses. `prefersReducedMotion()` resolves it fresh on every call, and the
+ * lead fade reads it from its transition params thunk, so an override
+ * installed before a render is visible to the very next swap. */
+function stubReducedMotion(matches) {
+    vi.stubGlobal("matchMedia", (query) => ({
+        matches,
+        media: query,
+        onchange: null,
+        addEventListener: () => { },
+        removeEventListener: () => { },
+        dispatchEvent: () => false,
+        addListener: () => { },
+        removeListener: () => { },
+    }));
+}
 describe("Button", () => {
-    afterEach(cleanup);
+    afterEach(() => {
+        cleanup();
+        vi.unstubAllGlobals();
+    });
     it("renders a real button with children as its label", () => {
         const { container } = render(Button, { props: { children: snippet("<span>Save</span>") } });
         const el = root(container);
@@ -229,6 +249,100 @@ describe("Button", () => {
         // alone; only the base `bg-primary` is a real conflict with `bg-red-500`.
         expect(classList).not.toContain("bg-primary");
     });
+    // The scoped `<style>` now declares a `transition` shorthand on this same
+    // element, so the press scale can join the colour channel under
+    // `prefers-reduced-motion: no-preference`. Svelte's scoped CSS is unlayered
+    // and Tailwind's utilities sit in `@layer utilities`, so leaving
+    // `transition-colors` on the class string would read as a colour transition
+    // that silently never ran.
+    it("drops the transition-colors utility in favour of the hand-written channel", () => {
+        const { container } = render(Button, { props: { children: snippet("<span>Go</span>") } });
+        expect(root(container).className).not.toContain("transition-colors");
+    });
+    describe("lead slot", () => {
+        const leadProps = {
+            iconStart: snippet('<span class="my-icon-start">+</span>'),
+            children: snippet("<span>Save</span>"),
+        };
+        function toggleOf(container) {
+            return container.querySelector('[data-testid="toggle"]');
+        }
+        it("wraps iconStart in the shared lead cell, exposed to assistive tech", () => {
+            const { container } = render(Button, { props: leadProps });
+            const lead = container.querySelector(".ft-btn-lead");
+            expect(lead).toBeTruthy();
+            expect(lead?.querySelector(".my-icon-start")).toBeTruthy();
+            // Not loading: nothing here is decorative, so the caller's own icon
+            // markup keeps whatever accessible treatment the caller gave it.
+            expect(lead?.hasAttribute("aria-hidden")).toBe(false);
+        });
+        it("renders no lead cell at all when there is neither a spinner nor an iconStart", () => {
+            const { container } = render(Button, {
+                props: { children: snippet("<span>Save</span>") },
+            });
+            expect(container.querySelector(".ft-btn-lead")).toBeNull();
+        });
+        it("keeps aria-busy on the control and aria-hidden on the cell, never the other way round", () => {
+            const { container } = render(Button, { props: { ...leadProps, loading: true } });
+            const el = root(container);
+            const lead = container.querySelector(".ft-btn-lead");
+            expect(el.getAttribute("aria-busy")).toBe("true");
+            expect(el.hasAttribute("aria-hidden")).toBe(false);
+            expect(lead.getAttribute("aria-hidden")).toBe("true");
+            expect(lead.hasAttribute("aria-busy")).toBe(false);
+        });
+        it("renders the same lead cell on the anchor branch", () => {
+            const { container } = render(Button, {
+                props: { ...leadProps, href: "https://example.com" },
+            });
+            const lead = container.querySelector(".ft-btn-lead");
+            expect(root(container).tagName).toBe("A");
+            expect(lead?.querySelector(".my-icon-start")).toBeTruthy();
+        });
+        // The proof the cross-fade exists at all. Every static-render assertion
+        // above and at `:101` stays green whether or not the fade was ever wired
+        // up, because a local transition never plays on the initial render of the
+        // block that owns it — only a live toggle can tell the two apart.
+        it("holds the icon and the spinner in the DOM together for the length of the cross-fade", async () => {
+            const { container } = render(LeadHarness);
+            const toggle = toggleOf(container);
+            expect(container.querySelector(".my-icon-start")).toBeTruthy();
+            expect(container.querySelector(".ft-btn-spinner")).toBeNull();
+            toggle.click();
+            await tick();
+            // Both mounted, sharing the one grid cell: that overlap IS the fade.
+            // Without it the icon would already be gone in this same flush.
+            expect(container.querySelector(".ft-btn-spinner")).toBeTruthy();
+            expect(container.querySelector(".my-icon-start")).toBeTruthy();
+            // And it settles on the spinner alone once the fade finishes.
+            await waitFor(() => expect(container.querySelector(".my-icon-start")).toBeNull());
+            expect(container.querySelector(".ft-btn-spinner")).toBeTruthy();
+        });
+        it("cross-fades back the other way when loading clears", async () => {
+            const { container } = render(LeadHarness);
+            const toggle = toggleOf(container);
+            toggle.click();
+            await waitFor(() => expect(container.querySelector(".my-icon-start")).toBeNull());
+            toggle.click();
+            await tick();
+            expect(container.querySelector(".my-icon-start")).toBeTruthy();
+            expect(container.querySelector(".ft-btn-spinner")).toBeTruthy();
+            await waitFor(() => expect(container.querySelector(".ft-btn-spinner")).toBeNull());
+            expect(container.querySelector(".my-icon-start")).toBeTruthy();
+        });
+        it("reduced motion: the swap is synchronous, with no window where both are mounted", async () => {
+            stubReducedMotion(true);
+            const { container } = render(LeadHarness);
+            const toggle = toggleOf(container);
+            toggle.click();
+            await tick();
+            // Duration 0 makes Svelte skip `element.animate()` entirely, so the
+            // outgoing icon is gone in the same flush that mounts the spinner —
+            // exactly the behaviour this button had before the fade existed.
+            expect(container.querySelector(".ft-btn-spinner")).toBeTruthy();
+            expect(container.querySelector(".my-icon-start")).toBeNull();
+        });
+    });
     describe("sound", () => {
         let play;
         beforeEach(() => {

package/dist/fancy-ui/button/ButtonLeadHarness.test.svelte

@@ -0,0 +1,32 @@
+<!--
+  Test-only rig for the lead slot's spinner ↔ `iconStart` cross-fade.
+
+  `loading` is held as local `$state` and flipped from a button inside this
+  component, deliberately, rather than driven from the test through
+  `rerender()`: `rerender` awaits a tick of its own, so a test using it can
+  never observe the ONE flush the cross-fade lives in — by the time it returns,
+  the stubbed Web Animations chain (a dummy animation on one microtask, the
+  real one on the next) has already resolved and the outgoing node has left
+  either way. A raw `.click()` flips the state synchronously, so a single
+  `await tick()` after it lands inside the fade window.
+
+  Starts NOT loading on purpose: a local transition never plays on the initial
+  render of the block that owns it, so the first click is the first genuine
+  swap, and the second click the genuine swap back.
+
+  Not exported from index.ts, and not collected by Vitest directly (the run
+  includes `*.test.ts` only) — imported and rendered from Button.test.ts.
+-->
+<script lang="ts">
+	import Button from "./Button.svelte";
+
+	let isLoading = $state(false);
+</script>
+
+<button type="button" data-testid="toggle" onclick={() => (isLoading = !isLoading)}>toggle</button>
+
+{#snippet plus()}
+	<span class="my-icon-start">+</span>
+{/snippet}
+
+<Button loading={isLoading} iconStart={plus}>Save</Button>

package/dist/fancy-ui/button/ButtonLeadHarness.test.svelte.d.ts

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

package/dist/fancy-ui/button/README.md

@@ -20,7 +20,7 @@ The library's foundational push-button: six variants, three sizes, a loading sta
 ```
 
 ```svelte
-<!-- Loading: swaps the leading icon for a spinner, keeps the button's own colours -->
+<!-- Loading: cross-fades the leading icon into a spinner, keeps the button's own colours -->
 <Button loading={saving} onclick={save}>Save changes</Button>
 ```
 
@@ -93,10 +93,21 @@ Set `sound` to play the `press` cue on activation, through the shared sound cont
 
 It is opt-in and silent by default: nothing plays unless both `sound` is set on the button **and** the user has turned sound on globally (through `SoundToggle` or `sound.enable()`). `disabled` and `loading` block the cue exactly like they block `onclick` — nothing plays for a click that never fires the callback either.
 
+## Motion
+
+- **The lead slot cross-fades.** `iconStart` and the spinner share one fixed-size cell — `calc(1em + 1px)`, the same box the spinner already drew itself in, so it follows the size variant for free. Flipping `loading` fades one out while the other fades in, over the same 80 ms, in place. Both are mounted at once for the length of that fade; the cell never resizes, so the label beside it never shifts. A button that starts out `loading` renders its spinner immediately, with no fade in from nothing, and a button given neither a spinner nor an `iconStart` renders no cell at all.
+- **Pressing scales the button to `0.97`** for as long as it is held. The two strokes are timed apart: going down runs on `--ft-ease-out`, the arrival curve, which spends most of the scale in the first frames so the press bites rather than easing in; coming back up runs on `--ft-ease-inout`, the reversible-state curve, so letting go settles instead of snapping. Same 150 ms clock either way. A disabled button and a `loading` one are both excluded: a press that does nothing should not pretend to.
+- The press transition lists `transform` and the three colour properties, and deliberately never `box-shadow`. This button's focus ring _is_ a `box-shadow` (`focus-visible:ring-*` compiles to one), and a focus ring must never animate.
+- **Reduced motion.** The press scale is declared entirely inside `@media (prefers-reduced-motion: no-preference)`; without that preference the button simply does not move, and the resting state is the ungated fallback. The lead cross-fade collapses to a duration of `0`, which makes the swap synchronous — exactly the instant cut this button did before the fade existed. The spinner's own rotation is likewise gated, and with motion reduced the ring is still drawn, just still, so `aria-busy` keeps a visible companion. Colour is the one channel that stays ungated in both places: a colour change is not motion, and gating it would only make a theme flip look broken for the people who asked for less movement.
+- **Touch and coarse pointers.** `:active` is exactly the affordance a finger gets, so the press feedback is not suppressed on touch. The button carries `touch-action: manipulation`, which removes the browser's ~300 ms tap delay without blocking scrolling — a button inside a scrollable list stays scrollable while it press-reacts.
+- **Timing.** 80 ms, linear, for the lead cross-fade (a fade needs no curve); 150 ms everywhere else. The colour channel and the press release run on `--ft-ease-inout` (`cubic-bezier(0.4, 0, 0.2, 1)`), the press down-stroke on `--ft-ease-out` (`cubic-bezier(0.16, 1, 0.3, 1)`). The `:active` rule re-declares the whole transition list to retime that one property, because `transition-timing-function` has no per-property form that would not restate the other three curves anyway.
+
 ## Implementation notes
 
 - `href` switches the rendered element from `<button>` to `<a>` — the two share one class list and one `onclick` guard, so behaviour does not fork with the markup.
 - An anchor cannot be `disabled`, and half its activation paths — middle-click firing `auxclick`, "open link in new tab" from the context menu — act on `href`/`target` directly and never reach `onclick` at all. So `disabled` and `loading` are combined into one `anchorInert` flag that strips `href` and `target`, sets `aria-disabled="true"` and `tabindex="-1"`; the click handler still swallows the event too, as a second line of defence for whatever does reach it. `loading` alone must be just as inert as `disabled` — a caller can't tell those attack surfaces apart, so the fix can't either.
 - `loading` is deliberately not `disabled` — the mockup keeps a loading button at full strength (no dimming), because "working" and "unavailable" read as different things. On the button branch this falls out naturally: `loading` never touches the native `disabled` attribute, so `disabled:opacity-50` never triggers, and the shared click guard is what actually stops the callback (proven by a synthetic dispatch that bypasses jsdom's own disabled handling in the test suite). On the anchor branch, `aria-disabled` goes true for `loading` too — inertness has to be visible to assistive tech regardless of _why_ the link is inert — but the dimmed look stays tied to `disabled` alone through a separate `data-disabled` attribute, so a loading anchor reads as busy, not unavailable, exactly like a loading button does.
 - `target="_blank"` always widens `rel` to include `noopener noreferrer`, on top of whatever tokens the caller already passed, closing the `window.opener` reverse-tabnabbing hole even when a caller forgets.
-- The spinner reads its own `font-size` (`calc(1em + 1px)`), so its diameter follows the size variant automatically rather than needing a per-size override; its top edge is `currentColor` and the rest of the ring is `currentColor` at 30% via `color-mix`, so it always matches whichever variant it is drawn on. The spin itself lives behind `prefers-reduced-motion: no-preference`; with motion reduced the ring is still drawn, just still, so `aria-busy` keeps a visible companion.
+- The spinner reads its own `font-size` (`calc(1em + 1px)`), so its diameter follows the size variant automatically rather than needing a per-size override; its top edge is `currentColor` and the rest of the ring is `currentColor` at 30% via `color-mix`, so it always matches whichever variant it is drawn on. See [Motion](#motion) for the spin's reduced-motion gate.
+- `aria-hidden` sits on the lead cell rather than on the spinner inside it, so it covers the whole cell for the length of the cross-fade: mid-swap the outgoing icon is still mounted, and a screen reader has no business reading a glyph on its way out of a control already marked `aria-busy`. With `loading` false the cell carries no `aria-hidden` at all, so a caller's own `iconStart` markup keeps whatever accessible treatment the caller gave it.
+- The `transition-colors` utility is deliberately absent from the class string. Svelte's scoped `<style>` is unlayered and Tailwind's utilities live in `@layer utilities`, so the scoped `transition` shorthand this button needs (the press scale has to join the colour channel) would win over that utility silently and leave a colour transition that never ran. The colour channel is re-declared by hand instead, at exactly the values the utility resolved to.