ChatWidget

Collapsible AI assistant with first-interaction transparency, session-only history and streaming replies.

Status: beta. Group: overlay. Markdown version: /design-system/components/chat-widget.md

When to use

The site's collapsible assistant widget: streaming chat with Donny, grapheme-safe burst smoothing for the active reply, tool-action buttons, localized UI, and mobile sheet behavior. One instance per page, mounted by the app shell.

When not to use

Do not gate the widget behind user authentication. The widget is for anonymous visitors; auth-gated chat is a different pattern.
Do not store chat history in cookies or persistent localStorage. The current storage is sessionStorage.
Do not tamper with the email-workflow reducer state from outside. The reducer has invariants (e.g. "review can only follow compose") that direct mutation breaks.

Look-alikes

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

Props

ChatWidget props
Prop	Type	Default	Description	Required
`title`	`string`	none	No description in the contract.	No
`description`	`string`	none	No description in the contract.	No
`endpoint`	`string`	none	Optional override for the API endpoint. Defaults to VITE_DONNY_CHAT_ENDPOINT, otherwise falls back to the secure proxy or /api/chat.	No

Variants

No variant dimensions and no props with a fixed set of values.

Invalid combinations

The contract records no invalid combinations.

Keyboard

ChatWidget keyboard behaviour
Key	Behaviour
Tab	Moves focus to the control and on to the next focusable element. (standard)
Enter	Activates the focused control. (standard)
Escape	Closes or dismisses the open layer. (standard)

Rows marked (standard) name a key the contract lists without a description; the behaviour shown is the usual one for that key.

Rules

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

ChatWidget rules
Level	Rule	How it is checked
MUST	ARIA: Launcher button labeled.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Chat region when open.	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	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-07-14.
MUST	A request with no first token after the acknowledge-delay threshold shows a polite status saying it is taking longer than usual, next to the Stop control; the notice clears as soon as the reply starts or the request ends.	Automated by `ChatWidget.temporal.test.tsx`.

Install and import

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