entasis 0.11.0 → 0.12.0

package/dist/components/Accordion/accordion.mcp.js

@@ -27,6 +27,9 @@ The Accordion component provides an interactive collapsible container for organi
 - **titleKey**: string - Key to extract title from items (default: 'title')
 - **contentKey**: string - Key to extract content from items (default: 'content')
 - **descriptionKey**: string - Key to extract description from items (default: 'description')
+- **disabledKey**: string - Key whose boolean disables one item (default: 'disabled')
+- **disabled**: boolean (default: false) - Disables every item
+- **headingLevel**: 2 | 3 | 4 | 5 | 6 (default: 3) - Level of the heading element that wraps each trigger
 
 ### Layout Props
 - **variant**: 'classic' | 'card' | 'outline' (default: 'classic')
@@ -43,8 +46,10 @@ The Accordion component provides an interactive collapsible container for organi
 - **splitted**: boolean (default: false) - Breaks the list into one surface per item with a gap: each item gets its own raised card (card), its own border (outline), or its own underline (classic)
 
 ### Event Props
-- **onValueChange**: (value: string[]) => void - Called once when expanded item ids change
-- **onItemOpenChange**: (options: { item: Item; index: number; open: boolean }) => void - Called after one item's open state changes
+- **onValueChange**: (value: string[]) => void - Called once after the expanded item ids change, with the new ids. Not called for initialization or for ids a parent assigns.
+- **onItemOpenChange**: (payload: { item: Item; index: number; open: boolean; details: OpenChangeDetails }) => void - Called before one item opens or closes. \`details.reason\` is \`'trigger-press'\` or \`'find-in-page'\`, \`details.event\` carries the DOM event, and \`details.cancel()\` keeps the item as it was (\`onValueChange\` is then not called). See \`entasis/types\` for \`OpenChangeDetails\`.
+- **onItemAfterOpen**: (payload: { item: Item; index: number }) => void - Called once each time an item finishes opening: after its slide, or at once when no animation plays (reduced motion, zero duration, find-in-page). Not called for items open at the start.
+- **onItemAfterClose**: (payload: { item: Item; index: number }) => void - Called once each time an item finishes closing, also when no animation plays or the panel is removed mid-close.
 
 ### Slot Props
 - **title**: Snippet - Custom title rendering
@@ -54,6 +59,8 @@ The Accordion component provides an interactive collapsible container for organi
 
 ### Behavior Props
 - **oneAtATime**: boolean (default: true) - Whether only one item can be expanded at a time
+- **hiddenUntilFound**: boolean (default: false) - Keeps collapsed panels in the DOM under \`hidden="until-found"\`, so the browser's find-in-page, text fragments and \`#id\` links reach their content and open the item (reason \`find-in-page\`, no animation). Collapsed content stays out of the accessibility tree and the tab order until then. A disabled item is not findable: its collapsed panel stays under plain \`hidden\`.
+- **keepMounted**: boolean (default: false) - Keeps collapsed panels mounted under \`hidden\`, preserving their state (form values, scroll). Not findable by the browser.
 
 ### Visual Props
 - **icon**: 'chevron' | 'plus-minus' | 'none' | Snippet (default: 'chevron')
@@ -73,18 +80,22 @@ The Accordion component provides an interactive collapsible container for organi
 \`\`\`
 <Accordion>
 	<AccordionItem>
-		<AccordionTrigger>
-			<AccordionHeader>
-				<Title />
-				<Description />
-			</AccordionHeader>
-			<Icon />
-		</AccordionTrigger>
-		<AccordionContent />
+		<Heading>                       <!-- h2 to h6, headingLevel -->
+			<AccordionTrigger>          <!-- button: id, aria-expanded, aria-controls, data-index -->
+				<AccordionHeader>
+					<Title />
+					<Description />
+				</AccordionHeader>
+				<Icon />
+			</AccordionTrigger>
+		</Heading>
+		<AccordionContent />            <!-- region: id, aria-labelledby the trigger -->
 	</AccordionItem>
 </Accordion>
 \`\`\`
 
+The heading wraps the button, as the WAI-ARIA accordion pattern asks, so assistive technology lists the headings. A collapsed item has no panel in the DOM unless \`hiddenUntilFound\` or \`keepMounted\` is set, so its content is neither read nor tabbable; \`aria-controls\` is present while the panel exists.
+
 ## Examples
 
 ### Basic Example
@@ -206,6 +217,22 @@ The Accordion component provides an interactive collapsible container for organi
 />
 \`\`\`
 
+### Find-in-page and disabled items
+
+\`\`\`svelte
+<script>
+	import { Accordion } from './index.ts';
+
+	let items = [
+		{ title: 'Shipping', content: 'Orders ship within two days.' },
+		{ title: 'Returns', content: 'Free returns for 30 days.', disabled: true }
+	];
+</script>
+
+<!-- Ctrl+F finds "two days" and opens Shipping; Returns is skipped by Tab. -->
+<Accordion {items} hiddenUntilFound />
+\`\`\`
+
 ### With Event Handler
 
 \`\`\`svelte
@@ -216,8 +243,9 @@ The Accordion component provides an interactive collapsible container for organi
 		{ title: 'Section 1', content: 'Content 1' }
 	];
 	
-	function handleToggle({ item, index, open }) {
-		console.log(\`Item \${item.title} at index \${index} is now \${open ? 'open' : 'closed'}\`);
+	function handleToggle({ item, index, open, details }) {
+		console.log(\`Item \${item.title} at index \${index} is opening: \${open} (\${details.reason})\`);
+		// details.cancel() would keep it as it was.
 	}
 </script>
 
@@ -251,18 +279,45 @@ The Accordion component provides an interactive collapsible container for organi
 </Accordion>
 \`\`\`
 
+## Styling hooks
+
+Every item, trigger and panel carries its own open state.
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
+
+**Data attributes**
+- \`data-open\`: On an item, its trigger, its panel and the panel's content: present while the item is expanded.
+- \`data-closed\`: On an item, its trigger, its panel and the panel's content: present while the item is collapsed, including during the exit transition.
+- \`data-entering\`: On a panel: present while its opening animation plays.
+- \`data-exiting\`: On a panel: present while its closing animation plays.
+- \`data-disabled\`: On an item and its trigger: present while the item is disabled.
+- \`data-state\`: On a trigger: \`open\` or \`closed\` (kept for compatibility; prefer \`data-open\` / \`data-closed\`).
+- \`data-index\`: On an item and its trigger: the item index.
+- \`data-slot\`: The part: \`accordion\`, \`accordion-item\`, \`accordion-trigger\`, \`accordion-icon-wrapper\` or \`accordion-panel\`.
+- \`data-size\`: On the root: the resolved \`size\`.
+- \`data-density\`: On the root: the resolved \`density\`.
+- \`data-variant\`: On the root: the resolved \`variant\`.
+
+**CSS variables**
+- \`--disclosure-panel-height\`: On a panel: its measured height in px while it animates, \`auto\` once open and \`0px\` once closed.
+
+The typed maps \`accordionDataAttributes\` and \`accordionCssVariables\` (from \`entasis/accordion\`) list each name with its meaning.
+
 ## Accessibility
 
-- Automatically handles ARIA attributes
-- Keyboard navigation support (Enter/Space to toggle)
-- Focus management for expanded items
-- Screen reader friendly with proper roles
+- Each trigger is a native \`<button>\` inside a heading element (\`headingLevel\`), with \`aria-expanded\` and, while its panel exists, \`aria-controls\`.
+- Each panel is a \`role="region"\` labelled by its trigger.
+- Enter and Space toggle an item. Tab moves between triggers and into open content; arrow, Home and End keys are left to the page (they neither move focus nor block scrolling), following the current WAI-ARIA guidance.
+- A disabled item's trigger has the native \`disabled\` attribute: it is skipped by Tab and announced as unavailable.
+- Collapsed content is not copied anywhere for screen readers. Use \`hiddenUntilFound\` to make it findable.
+- Migration: the \`accessible\` prop is removed (collapsed content is no longer duplicated into screen-reader-only text).
 
 ## Notes
 
 - Items are automatically assigned IDs if not provided
-- Uses Melt UI's Accordion builder for accessibility
-- Smooth transitions with the library's themed slide transition
+- Expanded ids are tracked by the component itself; there is no builder dependency
+- Panels animate their height through the shared disclosure panel (\`--disclosure-panel-height\` is set on the panel)
+- Styling hooks: \`data-open\` / \`data-closed\` on the item, trigger and content, \`data-disabled\`, \`data-index\`, and \`data-entering\` / \`data-exiting\` on the panel
 - Supports bindable items for dynamic updates
 
 ## Theme Customization
@@ -275,11 +330,12 @@ The theme object contains the following parts:
 - **root**: Main accordion container styles
 - **item**: Individual accordion item styles
 - **trigger**: Accordion trigger button styles
-- **header**: Header section styles (contains title and description)
+- **heading**: The \`h2\`-\`h6\` element that wraps each trigger (margin-free by default)
+- **header**: Header section styles (contains title and description, inside the trigger)
 - **title**: Title text styles
 - **description**: Description text styles
 - **icon**: Expand/collapse icon styles
-- **content**: Content panel styles
+- **content**: Content styles, on the element inside the region panel (so a hidden-until-found panel reserves no space)
 
 ### Available Variants
 
@@ -384,8 +440,8 @@ The theme object contains the following parts:
 
 ## Motion
 
-- **motion** theme slot: a slide keyed by \`axis\` (\`y\` by default, \`x\` for a horizontal list).
-- Takes \`in\` / \`out\` slide params plus a \`duration\` / \`easing\` motion token.
+- **motion** theme slot: the panel's height animation. \`duration\`, \`delay\` and \`easing\` apply; the preset's slide offsets and opacity do not (panels collapse along their height only).
+- Takes \`in\` / \`out\` params plus a \`duration\` / \`easing\` motion token.
 - Ladder: \`<Theme components={{ accordion: { motion } }}>\` → \`setAccordionTheme({ motion })\` →
   \`theme.motion\` → the \`transition\` prop. Reduced motion collapses it to 0.
 `;

package/dist/components/Accordion/accordion.props.d.ts

@@ -3,9 +3,10 @@ import type { Slot, WithSlot } from '../Slot/slot.js';
 import type { FSOProps } from '../../transitions/transition.js';
 import type { ResponsiveProps } from '../Theme/theme.js';
 import type { WithAttachments } from '../../types/props.js';
+import type { OpenChangeDetails } from '../../utils/openChange.js';
 import type { AccordionThemeProps } from './accordion.theme.js';
 export type ConditionalKeys<Base, Condition> = NonNullable<{
-    [Key in keyof Base]: Base[Key] extends Condition ? Key : never;
+    [Key in keyof Base]: NonNullable<Base[Key]> extends Condition ? Key : never;
 }[keyof Base]>;
 export type AccordionProps<Item extends Record<string, unknown>> = WithAttachments<WithSlot<{
     /**
@@ -20,21 +21,69 @@ export type AccordionProps<Item extends Record<string, unknown>> = WithAttachmen
     value?: string[];
     /** Initially expanded item ids when `value` is omitted. */
     defaultValue?: string[];
-    /** Called after the expanded item ids change. */
+    /** Called after the expanded item ids change, with the new ids. */
     onValueChange?: (value: string[]) => void;
     /**
-     * Called after one item's open state changes. Receives the item, its index, and the
-     * resulting open state; `onValueChange` reports the whole expanded set.
+     * Called before one item opens or closes. Receives the item, its index, the requested open
+     * state and the open-change `details`: `details.reason` says why (`trigger-press`, or
+     * `find-in-page` for the browser's find), `details.event` carries the DOM event, and
+     * `details.cancel()` keeps the item as it was (then `onValueChange` is not called).
+     * `onValueChange` reports the whole expanded set once the change is applied.
      */
     onItemOpenChange?: (payload: {
         item: Item;
         index: number;
         open: boolean;
+        details: OpenChangeDetails;
+    }) => void;
+    /**
+     * Called once each time an item finishes opening: after its slide, or at once when no
+     * animation runs (reduced motion, a zero duration, find-in-page). Not called for items open
+     * at the start.
+     */
+    onItemAfterOpen?: (payload: {
+        item: Item;
+        index: number;
+    }) => void;
+    /**
+     * Called once each time an item finishes closing: after its slide, at once when no
+     * animation runs, or when the panel is removed mid-close.
+     */
+    onItemAfterClose?: (payload: {
+        item: Item;
+        index: number;
     }) => void;
     /**
      * Whether the accordion should only allow one item to be open at a time.
      */
     oneAtATime?: boolean;
+    /**
+     * Disables every item: the triggers get the native `disabled` attribute, leave the tab
+     * order and cannot be toggled.
+     */
+    disabled?: boolean;
+    /**
+     * The key whose boolean marks one item as disabled. By default the accordion reads the
+     * `disabled` property of each item. A disabled item's trigger has the native `disabled`
+     * attribute, so it is skipped by Tab and announced as unavailable.
+     */
+    disabledKey?: ConditionalKeys<Item, boolean> | (string extends keyof Item ? keyof Item & string : never);
+    /**
+     * Keeps collapsed panels in the DOM under `hidden="until-found"`, so the browser's
+     * find-in-page, text fragments and `#id` links can reach their content and open the item
+     * (reason `find-in-page`, no animation). Collapsed content stays out of the accessibility
+     * tree and the tab order until then. A disabled item is not findable: its collapsed panel
+     * stays under plain `hidden`, so the browser never opens it. A parent that refuses the
+     * change leaves the item closed.
+     * @default false
+     */
+    hiddenUntilFound?: boolean;
+    /**
+     * Keeps collapsed panels mounted under `hidden`, preserving their state (form values,
+     * scroll, media). Not findable by the browser; use `hiddenUntilFound` for that.
+     * @default false
+     */
+    keepMounted?: boolean;
     /**
      * The key to use to get the title from the item. By default, the accordion will use the 'title' property of the item.
      * Usefull if the title is a string but you can pass a slot to display a custom title.
@@ -73,7 +122,7 @@ export type AccordionProps<Item extends Record<string, unknown>> = WithAttachmen
      */
     variant?: 'classic' | 'card' | 'outline';
     /**
-     * Heading level announced for each item title (`aria-level` on the item heading).
+     * Level of the heading element (`h2` to `h6`) that wraps each trigger button.
      * @default 3
      */
     headingLevel?: 2 | 3 | 4 | 5 | 6;
@@ -91,11 +140,6 @@ export type AccordionProps<Item extends Record<string, unknown>> = WithAttachmen
      * Theme overrides for the accordion root and item sub-parts (header, trigger, title, description, icon, content).
      */
     theme?: AccordionThemeProps;
-    /**
-     * Whether the accordion should be accessible when not expanded.
-     * This is useful for screen readers to skip the content when not expanded.
-     */
-    accessible?: boolean;
 }, 'title' | 'description' | 'content', {
     /** Current accordion item passed to the slot. */
     item: Item;

package/dist/components/Accordion/accordion.theme.d.ts

@@ -72,6 +72,7 @@ export declare const accordionTheme: {
             false: string;
         };
     }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
+    heading: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     header: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
         size: {
             small: string;
@@ -208,6 +209,7 @@ export declare const setAccordionTheme: (theme: InferComponentTheme<{
             false: string;
         };
     }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
+    heading: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     header: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
         size: {
             small: string;
@@ -342,6 +344,7 @@ export declare const useAccordionTheme: import("../../utils/cva/theme.js").UseCo
             false: string;
         };
     }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
+    heading: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     header: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
         size: {
             small: string;

package/dist/components/Accordion/accordion.theme.js

@@ -117,6 +117,9 @@ const defaultAccordionTrigger = cva({
         variant: 'classic'
     }
 });
+// The heading element (`h2`-`h6`) that wraps each trigger button. Headings render without browser
+// margins or type scale; the trigger owns the row's look.
+const defaultAccordionHeading = cva({ base: 'm-0 w-full text-[length:inherit] font-[inherit]' });
 const defaultAccordionHeader = cva({
     base: 'flex-1 flex flex-col items-start',
     variants: {
@@ -225,6 +228,7 @@ export const accordionTheme = {
     motion: defaultAccordionMotion,
     root: defaultAccordion,
     item: defaultAccordionItem,
+    heading: defaultAccordionHeading,
     header: defaultAccordionHeader,
     trigger: defaultAccordionTrigger,
     title: defaultAccordionTitle,

package/dist/components/Accordion/index.d.ts

@@ -1,3 +1,4 @@
 export { default as Accordion } from './Accordion.svelte';
 export type { AccordionProps, ConditionalKeys } from './accordion.props.js';
 export { accordionTheme, setAccordionTheme, useAccordionTheme, type AccordionTheme, type AccordionThemeProps } from './accordion.theme.js';
+export { accordionDataAttributes, accordionCssVariables, type AccordionDataAttribute, type AccordionCssVariable } from './accordion.attributes.js';

package/dist/components/Accordion/index.js

@@ -1,2 +1,3 @@
 export { default as Accordion } from './Accordion.svelte';
 export { accordionTheme, setAccordionTheme, useAccordionTheme } from './accordion.theme.js';
+export { accordionDataAttributes, accordionCssVariables } from './accordion.attributes.js';

package/dist/components/AudioPlayer/audioPlayerVolumeControl.slider.theme.d.ts

@@ -2,6 +2,30 @@ export declare const audioPlayerVolumeControlSliderTheme: {
     valueLabel: {
         base: string;
     };
+    motion?: {
+        in?: {
+            delay?: number | undefined;
+            duration?: number | undefined;
+            easing?: import("../../transitions/easingFunctions.js").Easing | undefined;
+            x?: number | `${number}%` | undefined;
+            y?: number | `${number}%` | undefined;
+            scale?: number | undefined;
+            opacity?: number | undefined;
+            axis?: "x" | "y" | undefined;
+        } | undefined;
+        out?: {
+            delay?: number | undefined;
+            duration?: number | undefined;
+            easing?: import("../../transitions/easingFunctions.js").Easing | undefined;
+            x?: number | `${number}%` | undefined;
+            y?: number | `${number}%` | undefined;
+            scale?: number | undefined;
+            opacity?: number | undefined;
+            axis?: "x" | "y" | undefined;
+        } | undefined;
+        duration?: (keyof import("../Theme/theme.designTokens.js").MotionTokens["duration"] | number) | undefined;
+        easing?: (keyof import("../Theme/theme.designTokens.js").MotionTokens["easing"] | import("../../transitions/easingFunctions.js").Easing) | undefined;
+    } | undefined;
     root?: ({
         density?: Partial<{
             normal: string;
@@ -46,6 +70,7 @@ export declare const audioPlayerVolumeControlSliderTheme: {
         base?: string;
     }) | undefined;
     label?: ({
+        disabled?: Partial<{}> | undefined;
         size?: Partial<{
             small: string;
             normal: string;
@@ -146,12 +171,12 @@ export declare const audioPlayerVolumeControlSliderTheme: {
             normal: string;
             large: string;
         }> | undefined;
-        active?: Partial<{}> | undefined;
         edge?: Partial<{
             none: string;
             start: string;
             end: string;
         }> | undefined;
+        active?: Partial<{}> | undefined;
     } & {
         base?: string;
     } & {
@@ -173,6 +198,7 @@ export declare const audioPlayerVolumeControlSliderTheme: {
         base?: string;
     }) | undefined;
     description?: ({
+        disabled?: Partial<{}> | undefined;
         size?: Partial<{
             small: string;
             normal: string;
@@ -184,6 +210,7 @@ export declare const audioPlayerVolumeControlSliderTheme: {
         base?: string;
     }) | undefined;
     helper?: ({
+        disabled?: Partial<{}> | undefined;
         size?: Partial<{
             small: string;
             normal: string;
@@ -237,6 +264,7 @@ export declare const audioPlayerVolumeControlSliderTheme: {
             thick: string;
             contained: string;
         }> | undefined;
+        readOnly?: Partial<{}> | undefined;
         orientation?: Partial<{
             horizontal: string;
             vertical: string;
@@ -303,6 +331,7 @@ export declare const audioPlayerVolumeControlSliderTheme: {
             thick: string;
             contained: string;
         }> | undefined;
+        readOnly?: Partial<{}> | undefined;
         orientation?: Partial<{
             horizontal: string;
             vertical: string;
@@ -324,6 +353,7 @@ export declare const audioPlayerVolumeControlSliderTheme: {
             thick: string;
             contained: string;
         }> | undefined;
+        readOnly?: Partial<{}> | undefined;
         orientation?: Partial<{
             horizontal: string;
             vertical: string;

package/dist/components/Avatar/Avatar.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
-	import type { AvatarProps } from './avatar.props.js';
+	import type { AvatarProps, AvatarStatus } from './avatar.props.js';
 	import { useAvatarTheme } from './avatar.theme.js';
 	import Slot from '../Slot/Slot.svelte';
+	import { untrack } from 'svelte';
 	import type { Attachment } from 'svelte/attachments';
 
 	let {
@@ -12,7 +13,10 @@
 		loading = $bindable(false),
 		suffix,
 		prefix,
-		delay = 0,
+		image,
+		fallbackDelay = 0,
+		revealDelay,
+		delay,
 		class: className,
 		theme,
 		...attachments
@@ -22,20 +26,35 @@
 	// the initials, so neither is part of the public prop surface the way `loading` is.
 	let loaded = $state(false);
 	let errored = $state(false);
+	// Set once `fallbackDelay` has run out while the image is still loading.
+	let fallbackReady = $state(false);
+
+	// `delay` is the old name of `revealDelay`; the new prop wins when both are given.
+	const effectiveRevealDelay = $derived(Math.max(0, revealDelay ?? delay ?? 0));
+	const effectiveFallbackDelay = $derived(Math.max(0, fallbackDelay));
 
 	const imageLoading = $derived.by<Attachment<HTMLImageElement>>(() => {
-		const revealDelay = delay;
+		const revealMs = effectiveRevealDelay;
+		const fallbackMs = effectiveFallbackDelay;
 		// Reading `src` here re-creates the attachment for every new image, which is what resets
 		// the per-image state below: a failed URL must not decide the outcome of the next one.
 		void src;
 
 		return (image) => {
 			let revealTimer: ReturnType<typeof setTimeout> | undefined;
+			let fallbackTimer: ReturnType<typeof setTimeout> | undefined;
 			const setLoading = (next: boolean) => {
-				if (loading !== next) loading = next;
+				if (untrack(() => loading) !== next) loading = next;
 			};
 			loaded = false;
 			errored = false;
+			fallbackReady = fallbackMs === 0;
+
+			const clearFallbackTimer = () => {
+				if (fallbackTimer === undefined) return;
+				clearTimeout(fallbackTimer);
+				fallbackTimer = undefined;
+			};
 
 			const clearRevealTimer = () => {
 				if (revealTimer === undefined) return;
@@ -44,17 +63,21 @@
 			};
 
 			const settle = (failed: boolean) => {
+				clearFallbackTimer();
 				errored = failed;
 				loaded = !failed;
 				setLoading(false);
 			};
 
 			const handleLoad = () => {
+				// A received image ends the fallback wait: the initials must not appear while the
+				// reveal delay is still running for an image that already arrived.
+				clearFallbackTimer();
 				clearRevealTimer();
 				revealTimer = setTimeout(() => {
 					settle(false);
 					revealTimer = undefined;
-				}, revealDelay);
+				}, revealMs);
 			};
 
 			const handleError = () => {
@@ -69,10 +92,17 @@
 				settle(image.naturalWidth === 0 || image.naturalHeight === 0);
 			} else {
 				setLoading(true);
+				if (fallbackMs > 0) {
+					fallbackTimer = setTimeout(() => {
+						fallbackTimer = undefined;
+						fallbackReady = true;
+					}, fallbackMs);
+				}
 			}
 
 			return () => {
 				clearRevealTimer();
+				clearFallbackTimer();
 				setLoading(false);
 				image.removeEventListener('load', handleLoad);
 				image.removeEventListener('error', handleError);
@@ -88,18 +118,38 @@
 			.map((word: string) => word[0])
 			.join('') || ''
 	);
-	const showsImage = $derived(!!src && loaded && !errored);
+	const status = $derived<AvatarStatus>(
+		!src ? 'idle' : errored ? 'error' : loaded ? 'loaded' : 'loading'
+	);
+	// The initials wait for `fallbackDelay` while the image loads and are never rendered for an
+	// image that arrives inside it. A failed image or a missing `src` shows them at once, and a
+	// loaded image keeps already-visible initials mounted underneath for the crossfade.
+	const showsInitials = $derived(
+		status === 'idle' || status === 'error' || fallbackReady || effectiveFallbackDelay === 0
+	);
+	const decorative = $derived(alt === '');
 </script>
 
-<div data-avatar class={classes.root({ size, className })} data-size={size} {...attachments}>
+<!-- The avatar is one image with one name: the `<img>` is empty-alt and the initials are
+     hidden from assistive technology, so a loading, loaded or failed image reads the same. -->
+<div
+	data-avatar
+	role={decorative ? undefined : 'img'}
+	aria-label={decorative ? undefined : (alt ?? name)}
+	aria-hidden={decorative ? 'true' : undefined}
+	class={classes.root({ size, className })}
+	data-size={size}
+	data-status={status}
+	{...attachments}
+>
 	<Slot render={prefix} class={classes.avatarPrefix({ size })} />
 	{#if src}
 		<!-- The image stays mounted for as long as `src` is set: unmounting it on failure would
 		     tear down the listeners that a later `src` needs. The initials cover it instead. -->
-		<img {@attach imageLoading} {src} alt={alt ?? name} class={classes.avatarImage({ size })} />
+		<img {...image} {@attach imageLoading} {src} alt="" class={classes.avatarImage({ size })} />
 	{/if}
-	{#if !showsImage}
-		<div class={classes.avatarInitials({ size })}>
+	{#if showsInitials}
+		<div aria-hidden="true" class={classes.avatarInitials({ size })}>
 			{initials}
 		</div>
 	{/if}

package/dist/components/Avatar/AvatarGroup.svelte

@@ -12,6 +12,9 @@
 		theme,
 		size,
 		delay,
+		revealDelay,
+		fallbackDelay,
+		image,
 		loading,
 		prefix,
 		suffix,
@@ -34,6 +37,9 @@
 				index,
 				avatarProps: {
 					delay,
+					revealDelay,
+					fallbackDelay,
+					image,
 					size,
 					loading,
 					prefix,
@@ -43,6 +49,9 @@
 		{:else}
 			<Avatar
 				{delay}
+				{revealDelay}
+				{fallbackDelay}
+				{image}
 				{size}
 				{loading}
 				{prefix}

package/dist/components/Avatar/avatar.mcp.d.ts

@@ -1 +1 @@
-export declare const avatarDescription = "\n# Avatar Component\n\nThe Avatar component displays a user's profile picture with fallback initials. It supports a bindable loading flag, various sizes, and badges (prefix/suffix). The AvatarGroup component displays multiple avatars with overlap.\n\n## Basic Usage\n\n```svelte\n<Avatar name=\"John Doe\" src=\"https://example.com/avatar.png\" />\n```\n\n## Props\n\n### Core Props\n- **name**: string (required) - Display name; its initials are the fallback when no image renders\n- **src**: string - Image URL; omit it, or let it fail, to render the initials instead\n- **alt**: string - Alternative text for the image (defaults to `name`)\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: 24px (1.5rem)\n  - normal: 32px (2rem)\n  - large: 40px (2.5rem)\n\n### Loading Props\n- **delay**: number (default: 0) - Delay in milliseconds before showing avatar\n- **loading**: boolean (default: false, bindable) - True while the image request is in flight; false with no `src`, and false once the image has loaded or failed. A failed image is reported by rendering the initials.\n\n### Content Slots\n- **prefix**: Slot - Badge/icon positioned at bottom-left\n- **suffix**: Slot - Badge/icon positioned at bottom-right\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Avatar Structure\n\n```\n<Avatar>\n\t<AvatarImage />        <!-- Profile picture -->\n\t<AvatarPrefix />       <!-- Behind the image (bottom-left) -->\n\t<AvatarSuffix />       <!-- Absolute position (bottom-right) -->\n\t<AvatarInitials />     <!-- Fallback initials -->\n</Avatar>\n```\n\n## AvatarGroup Props\n\n### Core Props\n- **items**: Array<{ src?: string; alt?: string; name: string } & T> (required) - Avatar items\n- **max**: number - Maximum number of avatars to show before \"+N\" indicator\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n\n### Content Slots\n- **avatar**: Snippet<{ item: T; index: number; avatarProps }> - Custom avatar rendering\n- **remainingCount**: Snippet<{ items: T[]; remaining: number }> - Custom \"+N\" counter rendering\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## AvatarGroup Structure\n\n```\n<AvatarGroup>\n\t<Avatar />\n\t<Avatar />\n\t<Avatar />\n\t<AvatarGroupCount />   <!-- \"+N\" indicator -->\n</AvatarGroup>\n```\n\n## Examples\n\n### Basic Avatar\n```svelte\n<Avatar name=\"Jane Smith\" src=\"/images/jane.jpg\" />\n```\n\n### Without Image (Initials)\n```svelte\n<Avatar name=\"John Doe\" />\n<!-- Displays \"JD\" -->\n```\n\n### Different Sizes\n```svelte\n<Avatar size=\"small\" name=\"Small User\" />\n<Avatar size=\"normal\" name=\"Normal User\" />\n<Avatar size=\"large\" name=\"Large User\" />\n```\n\n### With Status Badge (Prefix)\n```svelte\n<Avatar name=\"John Doe\">\n\t{#snippet prefix()}\n\t\t<div class=\"w-2 h-2 rounded-full bg-success\"></div>\n\t{/snippet}\n</Avatar>\n```\n\n### With Icon Badge (Suffix)\n```svelte\n<script lang=\"ts\">\n\timport { Avatar } from 'entasis/avatar';\n\timport { checkIcon } from 'entasis/icons/check';\n</script>\n\n<Avatar name=\"Jane Smith\">\n\t{#snippet suffix()}\n\t\t{@render checkIcon({ class: 'text-success' })}\n\t{/snippet}\n</Avatar>\n```\n\n### With Loading State\n```svelte\n<script lang=\"ts\">\n\tlet loading = $state(false);\n</script>\n\n<Avatar name=\"John Doe\" src=\"/avatar.jpg\" bind:loading />\n{loading}\n```\n\n### Avatar Group\n```svelte\n<script>\n\tlet items = [\n\t\t{ name: 'John Doe', src: '/john.jpg' },\n\t\t{ name: 'Jane Smith', src: '/jane.jpg' },\n\t\t{ name: 'Bob Johnson', src: '/bob.jpg' }\n\t];\n</script>\n\n<AvatarGroup {items} />\n```\n\n### Avatar Group with Max Limit\n```svelte\n<AvatarGroup \n\titems={[\n\t\t{ name: 'User 1' },\n\t\t{ name: 'User 2' },\n\t\t{ name: 'User 3' },\n\t\t{ name: 'User 4' },\n\t\t{ name: 'User 5' }\n\t]}\n\tmax={3}\n/>\n<!-- Shows 3 avatars + \"+2\" indicator -->\n```\n\n### Custom Avatar in Group\n```svelte\n<script lang=\"ts\">\n\timport { Avatar, AvatarGroup } from 'entasis/avatar';\n\n\tlet items = [{ name: 'John Doe' }, { name: 'Jane Smith' }];\n</script>\n\n<AvatarGroup {items}>\n\t{#snippet avatar({ item, index, avatarProps })}\n\t\t<Avatar {...avatarProps} {...item}>\n\t\t\t{#snippet suffix()}\n\t\t\t\t<span class=\"text-xs\">{index + 1}</span>\n\t\t\t{/snippet}\n\t\t</Avatar>\n\t{/snippet}\n</AvatarGroup>\n```\n\n### Custom Remaining Count\n```svelte\n<script lang=\"ts\">\n\timport { AvatarGroup } from 'entasis/avatar';\n\n\tlet items = [{ name: 'User 1' }, { name: 'User 2' }, { name: 'User 3' }, { name: 'User 4' }];\n</script>\n\n<AvatarGroup {items} max={3}>\n\t{#snippet remainingCount({ remaining })}\n\t\t<div class=\"avatar-count\">\n\t\t\t+{remaining} more\n\t\t</div>\n\t{/snippet}\n</AvatarGroup>\n```\n\n### Status Indicators\n```svelte\n<Avatar name=\"Online User\">\n\t{#snippet suffix()}\n\t\t<div class=\"w-3 h-3 rounded-full bg-success border-2 border-surface\"></div>\n\t{/snippet}\n</Avatar>\n\n<Avatar name=\"Away User\">\n\t{#snippet suffix()}\n\t\t<div class=\"w-3 h-3 rounded-full bg-warning border-2 border-surface\"></div>\n\t{/snippet}\n</Avatar>\n```\n\n## Accessibility\n\n- `alt` defaults to `name`, so the image always carries alt text\n- Fallback to initials when image fails to load\n- Proper foreground for initials display\n- The image loading flag is bindable\n\n## Notes\n\n- Initials are automatically extracted from the name (first letter of first two words)\n- Avatar image uses object-cover to maintain aspect ratio\n- Prefix badge is positioned at bottom-left, behind the image\n- Suffix badge is positioned at bottom-right, absolute positioning\n- Avatar group creates overlapping effect with negative margins\n- `loading` is true only while the image request is in flight; a failed image falls back to the initials\n- Each new `src` is loaded from scratch: `loading` goes true again and a working URL recovers the picture after a broken one\n\n## Theme Customization\n\nThe Avatar component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main avatar container styles\n- **avatarImage**: Avatar image element styles\n- **avatarPrefix**: Prefix badge styles (bottom-left)\n- **avatarSuffix**: Suffix badge styles (bottom-right)\n- **avatarInitials**: Fallback initials display styles\n\n### Theme Type Definition\n\n```typescript\nimport type { AvatarThemeProps } from 'entasis/avatar';\n\n// Example theme customization\nconst customTheme: AvatarThemeProps = {\n  root: {\n    base: 'custom-base-classes',\n    size: {\n      small: 'size-6',\n      normal: 'size-8',\n      large: 'size-10'\n    }\n  },\n  avatarImage: {\n    size: {\n      small: '',\n      normal: '',\n      large: ''\n    }\n  },\n  avatarPrefix: {\n    size: {\n      small: 'size-5 right-[-0.25rem] bottom-[-0.25rem]',\n      normal: 'size-4 right-[-0.3rem] bottom-[-0.2rem]',\n      large: 'size-5 left-[-0.4rem] bottom-[-0.4rem]'\n    }\n  },\n  avatarSuffix: {\n    size: {\n      small: 'size-3.5 left-[-0.25rem] bottom-[-0.25rem]',\n      normal: 'size-4 right-[-0.3rem] bottom-[-0.3rem]',\n      large: 'size-3.5 right-[-0.4rem] bottom-[-0.4rem]'\n    }\n  },\n  avatarInitials: {\n    size: {\n      small: 'text-xs',\n      normal: 'text-sm',\n      large: 'text-base'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes applied to all avatars\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls avatar dimensions (6/8/10)\n\n**avatarImage**:\n- base: Base classes for avatar image\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Inherited from avatar size\n\n**avatarPrefix**:\n- base: Base classes for prefix badge\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Badge size and positioning based on avatar size\n\n**avatarSuffix**:\n- base: Base classes for suffix badge\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Badge size and positioning based on avatar size\n\n**avatarInitials**:\n- base: Base classes for initials fallback\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size based on avatar size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Avatar \n  name=\"John Doe\"\n  theme={{\n    root: {\n      base: 'ring-2 ring-primary',\n      size: {\n        large: 'size-12'\n      }\n    },\n    avatarInitials: {\n      size: {\n        large: 'text-lg'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Badge Styling**:\n```svelte\n<Avatar\n  name=\"Jane Smith\"\n  theme={{\n    avatarSuffix: {\n      size: {\n        normal: 'size-5 ring-2 ring-white'\n      }\n    }\n  }}\n>\n  {#snippet suffix()}\n    <div class=\"w-3 h-3 bg-success rounded-full\"></div>\n  {/snippet}\n</Avatar>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setAvatarTheme } from './index.ts';\n  \n  setAvatarTheme({\n    root: {\n      base: 'ring-2 ring-neutral-muted transition-all',\n      size: {\n        normal: 'size-10'\n      }\n    },\n    avatarInitials: {\n      base: 'font-bold'\n    }\n  });\n</script>\n```\n";
+export declare const avatarDescription = "\n# Avatar Component\n\nThe Avatar component displays a user's profile picture with fallback initials. It supports a bindable loading flag, various sizes, and badges (prefix/suffix). The AvatarGroup component displays multiple avatars with overlap.\n\n## Basic Usage\n\n```svelte\n<Avatar name=\"John Doe\" src=\"https://example.com/avatar.png\" />\n```\n\n## Props\n\n### Core Props\n- **name**: string (required) - Display name; its initials are the fallback when no image renders\n- **src**: string - Image URL; omit it, or let it fail, to render the initials instead\n- **alt**: string - Accessible name of the whole avatar (defaults to `name`). An empty string makes the avatar decorative: it is hidden from assistive technology\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: 24px (1.5rem)\n  - normal: 32px (2rem)\n  - large: 40px (2.5rem)\n\n### Image Props\n- **image**: { srcset, sizes, crossorigin, referrerpolicy, loading, decoding, fetchpriority } - Native attributes forwarded to the `<img>`. Use `image={{ loading: 'lazy' }}` to defer offscreen images: the initials stay on screen until the browser has fetched the picture. (The avatar's own `loading` prop is the bindable in-flight flag, not the `<img>` attribute.)\n\n### Loading Props\n- **fallbackDelay**: number (default: 0) - Delay in milliseconds before the initials render while the image is still loading. Until then the surface stays empty, so a fast image never flashes the fallback. A failed image or a missing `src` shows the initials immediately\n- **revealDelay**: number (default: 0) - Delay in milliseconds before a loaded image is revealed\n- **delay**: number - Deprecated alias of `revealDelay`; it never delays the initials\n- **loading**: boolean (default: false, bindable) - True while the image request is in flight; false with no `src`, and false once the image has loaded or failed. A failed image is reported by rendering the initials.\n\n### Content Slots\n- **prefix**: Slot - Badge/icon positioned at bottom-left\n- **suffix**: Slot - Badge/icon positioned at bottom-right\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Avatar Structure\n\n```\n<Avatar>\n\t<AvatarImage />        <!-- Profile picture -->\n\t<AvatarPrefix />       <!-- Behind the image (bottom-left) -->\n\t<AvatarSuffix />       <!-- Absolute position (bottom-right) -->\n\t<AvatarInitials />     <!-- Fallback initials -->\n</Avatar>\n```\n\n## AvatarGroup Props\n\n### Core Props\n- **items**: Array<{ src?: string; alt?: string; name: string } & T> (required) - Avatar items\n- **max**: number - Maximum number of avatars to show before \"+N\" indicator\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n- **image**, **fallbackDelay**, **revealDelay**, **loading**: forwarded to every avatar\n\n### Content Slots\n- **avatar**: Snippet<{ item: T; index: number; avatarProps }> - Custom avatar rendering\n- **remainingCount**: Snippet<{ items: T[]; remaining: number }> - Custom \"+N\" counter rendering\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## AvatarGroup Structure\n\n```\n<AvatarGroup>\n\t<Avatar />\n\t<Avatar />\n\t<Avatar />\n\t<AvatarGroupCount />   <!-- \"+N\" indicator -->\n</AvatarGroup>\n```\n\n## Examples\n\n### Basic Avatar\n```svelte\n<Avatar name=\"Jane Smith\" src=\"/images/jane.jpg\" />\n```\n\n### Without Image (Initials)\n```svelte\n<Avatar name=\"John Doe\" />\n<!-- Displays \"JD\" -->\n```\n\n### Different Sizes\n```svelte\n<Avatar size=\"small\" name=\"Small User\" />\n<Avatar size=\"normal\" name=\"Normal User\" />\n<Avatar size=\"large\" name=\"Large User\" />\n```\n\n### With Status Badge (Prefix)\n```svelte\n<Avatar name=\"John Doe\">\n\t{#snippet prefix()}\n\t\t<div class=\"w-2 h-2 rounded-full bg-success\"></div>\n\t{/snippet}\n</Avatar>\n```\n\n### With Icon Badge (Suffix)\n```svelte\n<script lang=\"ts\">\n\timport { Avatar } from 'entasis/avatar';\n\timport { checkIcon } from 'entasis/icons/check';\n</script>\n\n<Avatar name=\"Jane Smith\">\n\t{#snippet suffix()}\n\t\t{@render checkIcon({ class: 'text-success' })}\n\t{/snippet}\n</Avatar>\n```\n\n### With Loading State\n```svelte\n<script lang=\"ts\">\n\tlet loading = $state(false);\n</script>\n\n<Avatar name=\"John Doe\" src=\"/avatar.jpg\" bind:loading />\n{loading}\n```\n\n### Avatar Group\n```svelte\n<script>\n\tlet items = [\n\t\t{ name: 'John Doe', src: '/john.jpg' },\n\t\t{ name: 'Jane Smith', src: '/jane.jpg' },\n\t\t{ name: 'Bob Johnson', src: '/bob.jpg' }\n\t];\n</script>\n\n<AvatarGroup {items} />\n```\n\n### Avatar Group with Max Limit\n```svelte\n<AvatarGroup \n\titems={[\n\t\t{ name: 'User 1' },\n\t\t{ name: 'User 2' },\n\t\t{ name: 'User 3' },\n\t\t{ name: 'User 4' },\n\t\t{ name: 'User 5' }\n\t]}\n\tmax={3}\n/>\n<!-- Shows 3 avatars + \"+2\" indicator -->\n```\n\n### Custom Avatar in Group\n```svelte\n<script lang=\"ts\">\n\timport { Avatar, AvatarGroup } from 'entasis/avatar';\n\n\tlet items = [{ name: 'John Doe' }, { name: 'Jane Smith' }];\n</script>\n\n<AvatarGroup {items}>\n\t{#snippet avatar({ item, index, avatarProps })}\n\t\t<Avatar {...avatarProps} {...item}>\n\t\t\t{#snippet suffix()}\n\t\t\t\t<span class=\"text-xs\">{index + 1}</span>\n\t\t\t{/snippet}\n\t\t</Avatar>\n\t{/snippet}\n</AvatarGroup>\n```\n\n### Custom Remaining Count\n```svelte\n<script lang=\"ts\">\n\timport { AvatarGroup } from 'entasis/avatar';\n\n\tlet items = [{ name: 'User 1' }, { name: 'User 2' }, { name: 'User 3' }, { name: 'User 4' }];\n</script>\n\n<AvatarGroup {items} max={3}>\n\t{#snippet remainingCount({ remaining })}\n\t\t<div class=\"avatar-count\">\n\t\t\t+{remaining} more\n\t\t</div>\n\t{/snippet}\n</AvatarGroup>\n```\n\n### Status Indicators\n```svelte\n<Avatar name=\"Online User\">\n\t{#snippet suffix()}\n\t\t<div class=\"w-3 h-3 rounded-full bg-success border-2 border-surface\"></div>\n\t{/snippet}\n</Avatar>\n\n<Avatar name=\"Away User\">\n\t{#snippet suffix()}\n\t\t<div class=\"w-3 h-3 rounded-full bg-warning border-2 border-surface\"></div>\n\t{/snippet}\n</Avatar>\n```\n\n## Accessibility\n\n- The root is `role=\"img\"` named by `alt ?? name`, so a loading, loaded or failed image and an avatar without `src` are all announced as one image with one name\n- The inner `<img>` has an empty `alt` and the initials are `aria-hidden`, so nothing is read twice\n- `alt=\"\"` marks the avatar decorative (`aria-hidden` on the root), for an avatar next to its visible name\n- Because the root is an image, prefix and suffix content is presentational to assistive technology; keep interactive controls outside the avatar\n- The root carries `data-status=\"idle | loading | loaded | error\"` (`idle` means no `src`). The default theme crossfades the image over the initials on it; style it with `group-data-[status=loaded]/avatar:` or `[data-status=error]`\n- The image loading flag is bindable\n\n## Notes\n\n- Initials are automatically extracted from the name (first letter of first two words)\n- Avatar image uses object-cover to maintain aspect ratio\n- Prefix badge is positioned at bottom-left, behind the image\n- Suffix badge is positioned at bottom-right, absolute positioning\n- Avatar group creates overlapping effect with negative margins\n- `loading` is true only while the image request is in flight; a failed image falls back to the initials\n- Each new `src` is loaded from scratch: `loading` goes true again and a working URL recovers the picture after a broken one\n\n## Theme Customization\n\nThe Avatar component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main avatar container styles\n- **avatarImage**: Avatar image element styles\n- **avatarPrefix**: Prefix badge styles (bottom-left)\n- **avatarSuffix**: Suffix badge styles (bottom-right)\n- **avatarInitials**: Fallback initials display styles\n\n### Theme Type Definition\n\n```typescript\nimport type { AvatarThemeProps } from 'entasis/avatar';\n\n// Example theme customization\nconst customTheme: AvatarThemeProps = {\n  root: {\n    base: 'custom-base-classes',\n    size: {\n      small: 'size-6',\n      normal: 'size-8',\n      large: 'size-10'\n    }\n  },\n  avatarImage: {\n    size: {\n      small: '',\n      normal: '',\n      large: ''\n    }\n  },\n  avatarPrefix: {\n    size: {\n      small: 'size-5 right-[-0.25rem] bottom-[-0.25rem]',\n      normal: 'size-4 right-[-0.3rem] bottom-[-0.2rem]',\n      large: 'size-5 left-[-0.4rem] bottom-[-0.4rem]'\n    }\n  },\n  avatarSuffix: {\n    size: {\n      small: 'size-3.5 left-[-0.25rem] bottom-[-0.25rem]',\n      normal: 'size-4 right-[-0.3rem] bottom-[-0.3rem]',\n      large: 'size-3.5 right-[-0.4rem] bottom-[-0.4rem]'\n    }\n  },\n  avatarInitials: {\n    size: {\n      small: 'text-xs',\n      normal: 'text-sm',\n      large: 'text-base'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes applied to all avatars\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls avatar dimensions (6/8/10)\n\n**avatarImage**:\n- base: Base classes for avatar image\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Inherited from avatar size\n\n**avatarPrefix**:\n- base: Base classes for prefix badge\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Badge size and positioning based on avatar size\n\n**avatarSuffix**:\n- base: Base classes for suffix badge\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Badge size and positioning based on avatar size\n\n**avatarInitials**:\n- base: Base classes for initials fallback\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size based on avatar size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Avatar \n  name=\"John Doe\"\n  theme={{\n    root: {\n      base: 'ring-2 ring-primary',\n      size: {\n        large: 'size-12'\n      }\n    },\n    avatarInitials: {\n      size: {\n        large: 'text-lg'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Badge Styling**:\n```svelte\n<Avatar\n  name=\"Jane Smith\"\n  theme={{\n    avatarSuffix: {\n      size: {\n        normal: 'size-5 ring-2 ring-white'\n      }\n    }\n  }}\n>\n  {#snippet suffix()}\n    <div class=\"w-3 h-3 bg-success rounded-full\"></div>\n  {/snippet}\n</Avatar>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setAvatarTheme } from './index.ts';\n  \n  setAvatarTheme({\n    root: {\n      base: 'ring-2 ring-neutral-muted transition-all',\n      size: {\n        normal: 'size-10'\n      }\n    },\n    avatarInitials: {\n      base: 'font-bold'\n    }\n  });\n</script>\n```\n";