An accordion provides a way for authors to organize content into collapsible sections, allowing users to expand one or more sections at a time. Each section MUST contain a chickadee-accordion-item with a header slot. Accordion items SHOULD have descriptive header content for screen readers. By default, only one item can be expanded; set multiple to allow several. Keyboard interaction: Tab moves focus between accordion headers; Enter or Space toggles the focused item. The element manages ARIA expanded state on each item.

Displays a status-driven alert for communicating important information. Authors SHOULD set status to convey severity. Uses role="alert" for danger/warning and role="status" for others. When dismissable, authors MUST handle the close event. Keyboard: Tab to dismiss, Enter/Space to activate.

An avatar displays a user image, initials derived from their name, or a generic person placeholder. Use the src attribute for a photo, the name attribute for initials, or leave both unset for the fallback icon. Authors SHOULD provide alt text when src is set for screen reader accessibility. When only name is provided, the element sets role="img" and an ARIA label automatically. The avatar is not focusable and does not accept keyboard interaction; Tab and focus behavior is inherited from the surrounding context.

A banner for status messages and alerts. Provides severity variants (info, success, warning, danger, neutral). Authors SHOULD choose the variant matching the message severity. Danger banners use role="alert" (assertive); others use role="status" (polite). When dismissable is set, authors MUST handle the close event. Tab moves focus to the dismiss button when present.

A breadcrumb trail for showing the current page within a site hierarchy. Provides a <nav> landmark with an ordered list. Authors SHOULD supply <a> elements for ancestors and a <span> for the current page. The last item SHOULD have aria-current="page". Separators render automatically via CSS. Tab and Enter allow keyboard navigation of links.

A button for triggering actions on the page or in the background. Provides primary, secondary, tertiary, and plain variants for visual hierarchy. The danger attribute SHOULD be used when the action is destructive or irreversible. Authors MUST ensure button text clearly describes the action.

Form-associated: supports type, name, and value attributes for native form submission and reset. Uses ElementInternals for ARIA and form state management.

Keyboard interaction: activates on Enter or Space. Focus delegates to the internal button element via delegatesFocus. Screen readers announce the slotted text content as the accessible name, or the label attribute if provided.

Groups related content in an elevated container with optional header, body, image, and footer sections. Authors SHOULD use the variant attribute to match elevation context. Selectable cards provide keyboard interaction via Enter and Space keys. Screen readers announce the selected state through aria-pressed on the interactive overlay.

A call-to-action for navigation. Authors MUST provide href. AVOID using this for actions -- use chickadee-button instead. Focus delegates to the inner anchor. Screen readers announce it as a link.

Keyboard: Enter activates (native anchor). Tab focuses via delegatesFocus.

Provides a styled description list for displaying key-value pairs. Authors SHOULD provide <dt> and <dd> pairs. The orientation attribute controls layout. Screen readers announce item count and navigate between terms via the semantic <dl> element.

A two-pane list transfer component for moving items between "available" and "selected" lists, allowing users to build a curated selection from a larger set. Each pane provides search filtering and multi-select via checkboxes. Transfer buttons move checked items between panes. Authors SHOULD set available-label and selected-label when the default headings do not describe the domain.

Each listbox uses role="listbox" with aria-multiselectable="true". Screen readers announce the pane headings and selection counts. Tab moves focus between search fields and transfer buttons. Space toggles item selection within a pane.

Provides a placeholder for empty content areas. Authors SHOULD use this when a page or container has no content to display. Focus SHOULD be managed by action buttons in the actions slot. The icon is decorative and SHOULD use aria-hidden to hide from screen readers.

A drag-and-drop file upload area with a browse button fallback, for collecting user files in forms or standalone flows. Provides file type and size constraints via attributes. When files are added, they appear in a removable list below the drop zone. Authors SHOULD set accept to restrict allowed file types. Authors SHOULD set max-size when server-side limits apply.

Screen readers announce the upload button and file list. Each file remove button includes an aria-label with the file name. Tab moves focus between the upload button and individual remove buttons.

A hint provides contextual feedback to the user. Status variants convey the nature of the message (info, success, warning, danger, or neutral). When dismissable, a close button is rendered and a close event is dispatched on click. Authors SHOULD use the default slot for hint text and the actions slot for inline action links or buttons. Authors MUST choose a status that matches the severity of the message. The dismiss button is keyboard-focusable and activates on Enter or Space. Screen readers SHOULD be able to reach the hint content and its ARIA label.

A decorative icon element. Renders SVG icons from the bundled icon set. Icons are lazy-loaded on first use. The icon SHOULD be treated as decorative by default (hidden from the accessibility tree). When the icon conveys meaning, authors MUST set the accessible-label attribute, which adds role="img" and aria-label via ElementInternals.

Keyboard interaction: none (icons are not interactive). Use chickadee-icon-button for interactive icon actions.

An icon-only button for toolbar actions, menus, and compact UI controls. Authors MUST provide an accessible-label attribute, since there is no visible text for screen readers to announce. The accessible-label value SHOULD describe the action (e.g. "Close dialog"), not the icon (e.g. "X icon"). AVOID using this element when a text label would fit -- prefer chickadee-button with an icon slot instead.

Keyboard interaction: activates on Enter or Space. Focus delegates to the internal button element via delegatesFocus. The accessible-label attribute sets aria-label on the inner button for WCAG compliance.

A label for categorizing, tagging, or marking status. Provides filled and outlined variants with a range of semantic colors. The closable attribute adds a dismiss button that fires a close event. Authors SHOULD choose a color that conveys the label's semantic meaning. Authors MUST ensure label text is concise. The close button is keyboard-focusable and activates on Enter or Space. Screen readers announce the close button via its aria-label.

An application header/toolbar that provides branding, primary navigation, and utility actions for a page or application shell. Establishes elevation level 1 via style container queries, using --chickadee-color-surface-raised for the background. When sticky, remains fixed at the top of the viewport. Authors SHOULD place the masthead as the first landmark in the page.

The header element uses role="banner" for screen readers. Navigation slot content SHOULD use <nav> with an aria-label. Tab order follows the slot order: hamburger, logo, default, utility.

A dropdown menu for presenting a list of actions or options. Provides ARIA role="menu" for screen reader navigation. Authors SHOULD pair this with a trigger button. Keyboard: Arrow keys move focus, Home/End jump to first/last, Escape closes, Enter/Space activates.

An overlay dialog for presenting focused content or gathering user input. Uses the native <dialog> for focus trapping and Escape handling. Authors SHOULD provide a heading for screen reader context. AVOID using modals for non-critical content. Keyboard: Escape closes, Tab cycles focus. ARIA dialog role announced on open.

A sidebar navigation for application-level page navigation. Provides a <nav> ARIA landmark with an accessible label for screen readers. Authors SHOULD set label to describe purpose. Use collapsed when space is limited. Keyboard: Tab navigates items in DOM order.

A notification badge provides a numeric count overlay for its slotted content. Intended for use with icon buttons or similar interactive elements. When the count exceeds the threshold, it displays "N+" instead. The badge is hidden when count is 0 or unset. Authors SHOULD set accessible-label on the slotted content to ensure screen readers convey the notification context. The badge itself is aria-hidden; the element sets an ARIA label via ElementInternals when count is positive. Tab and focus behavior is delegated to the slotted interactive element.

A single step in a progress stepper. Each step MUST have text content (the step title). Steps SHOULD have a state attribute. The step icon is derived from the state, or can be overridden with icon.

Use inside chickadee-progress-stepper. Screen readers announce each step as a listitem with aria-current="step" on the active step.

A progress stepper shows the steps needed to complete a process and the status of each step. Authors SHOULD use 3-5 steps. Each step MUST have a title. The stepper uses role="list" for screen reader navigation.

Supports horizontal and vertical orientations. In horizontal mode, the stepper automatically switches to vertical below 768px container width via container queries.

A range slider for selecting a numeric value. Provides a form-associated control wrapping a native range input for full keyboard and assistive technology support. Authors SHOULD set a label for screen readers. Arrow keys allow fine-grained control; Tab moves focus to the thumb.

A spinner indicates an action is in progress. It SHOULD be used when loading content or processing a request. Authors SHOULD provide a text label via the default slot to describe what is loading. Screen readers announce the spinner via role="status" and aria-live="polite" on the SVG element.

A toggle switch for binary on/off choices. Authors SHOULD provide a visible label via the default slot or the label attribute for accessibility. Form-associated via ElementInternals; supports name and value for native form submission.

A tabbed interface container that provides a way for authors to organize content into panels, allowing users to switch between views. Tab elements MUST be placed in the tab slot; panels go in the default slot. Arrow keys navigate between tabs using roving tabindex. The element automatically wires ARIA attributes between tabs and panels for screen reader accessibility. Supports horizontal and vertical orientations, plus a boxed variant.

A group of toggle buttons that provides a way for users to select one or more options from a set. In single-selection mode (default), toggles behave like radio buttons. When multiple is set, toggles behave like checkboxes. Authors MUST provide an accessible label via aria-label or aria-labelledby on the host element. Authors SHOULD ensure each slotted toggle has a descriptive label for screen readers. Keyboard interaction: Tab moves focus into the group; individual toggle buttons are focusable via Tab and activate on Enter or Space.

A multi-step form flow that guides users through a sequential process, for workflows like registration, onboarding, or configuration wizards. Provides step progress via a composed chickadee-progress-stepper and manages navigation between chickadee-wizard-step children. When linear is set, steps MUST be completed in order. Authors SHOULD give each step a name attribute for the stepper labels.

The progress stepper announces step state to screen readers. Tab moves focus between Back, Next, and Finish buttons in the footer.