DonnyAvatar

The assistant's animated avatar with thinking, speaking, and idle mood states, used inside ChatWidget and Donny surfaces.

Status: stable. Group: display. Markdown version: /design-system/components/donny-avatar.md

When to use

The assistant's animated avatar with mood and lifecycle states used inside ChatWidget and Donny surfaces. DONNY_STATES and isDonnyState expose the complete validated state vocabulary to hosts.

When not to use

Do not set decorative on a DonnyAvatar unless the parent control carries its own accessible name; a decorative avatar is hidden from assistive technology and names nothing.
Do not drive lifecycle-only states such as loading or typing from decorative marketing copy.
Do not use random emotional states to imply work or success that has not occurred.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

DonnyAvatar props
Prop	Type	Default	Description	Required
`state`	`"success" \| "error" \| "loading" \| "idle" \| "listening" \| "thinking" \| "searching" \| "confused" \| "handoff" \| "greeting" \| "acknowledging" \| "suggesting" \| "confident" \| "curious" \| "celebrating" \| "apologetic" \| "typing" \| "waving" \| "remembering" \| "focused" \| "playful" \| "impressed" \| "skeptical" \| "sleepy" \| "sleeping"`	`idle`	Current expression or assistant lifecycle state.	No
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`md`	Rendered avatar size: xs 28px (chat toggle), sm 32px, md 48px, lg 64px, xl 96px.	No
`className`	`string`	none	Additional CSS class.	No
`onTransitionEnd`	`() => void`	none	Called when the state transition animation ends.	No
`showLabel`	`boolean`	`false`	Shows the current state label for diagnostics.	No
`trackMouse`	`boolean`	`false`	Makes the eyes follow the pointer.	No
`proximitySelectors`	`string[]`	`[]`	CSS selectors whose pointer proximity can trigger curious or playful behavior.	No
`onProximityChange`	`(isNearTarget: boolean, targetSelector?: string) => void`	none	Called when proximity to a tracked target changes.	No
`proximityThreshold`	`number`	`150`	Pointer proximity threshold in pixels (default 150).	No
`enableIdleExpressions`	`boolean`	`false`	Enables one randomized idle expression before the avatar settles.	No
`idleExpressionInterval`	`number`	`12000`	Delay before the one idle expression, in milliseconds (default 12000), randomized by 50 percent.	No
`isSpeaking`	`boolean`	`false`	Animates the mouth during streaming responses.	No
`enableSleepDetection`	`boolean`	`false`	Enables sleepy and sleeping states after pointer inactivity.	No
`sleepyDelay`	`number`	`120000`	Inactivity delay before the sleepy state, in milliseconds (default 120000).	No
`sleepDelay`	`number`	`150000`	Inactivity delay before the sleeping state, in milliseconds (default 150000).	No
`decorative`	`boolean`	`false`	Sets aria-hidden and removes role and label when a parent control owns the accessible name (e.g. the chat toggle). Otherwise the avatar is an img named by its translated state, such as "Donny is thinking".	No

Variants

Available sizes: xs, sm, md, lg, xl (default md).
Allowed state values: success, error, loading, idle, listening, thinking, searching, confused, handoff, greeting, acknowledging, suggesting, confident, curious, celebrating, apologetic, typing, waving, remembering, focused, playful, impressed, skeptical, sleepy, sleeping (default idle).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

DonnyAvatar rules
Level	Rule	How it is checked
MUST	ARIA: When not decorative, the root is role=img named by a translated sentence for its state (`donnyAvatar.state.<state>`, for example "Donny is thinking", "Donny miettii", "Donny tänker"); raw state ids are never announced.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Decorative sets aria-hidden on the root and removes the role and the name, so the parent control must carry the accessible name.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Use lifecycle states such as listening, thinking, searching, typing, and loading to reflect actual assistant work.	Not stated in the contract.
SHOULD	Set decorative when Donny sits inside an already-labelled button or link.	Not stated in the contract.
SHOULD	Validate external state strings with isDonnyState before rendering.	Not stated in the contract.

Install and import

In-repo only. DonnyAvatar is not exported from @digitaltableteur/react, so there is no public import path.