Cloaked Design SystemOrganization

Accordion

Grouped disclosure of independent expandable sections driven by an items array, with animated panels.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

8 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/organization/Accordion/Accordion.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

Grouped disclosure of independent expandable sections driven by an items array, with animated panels.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Accordion } from '@cloakedinc/design-system';

AccordionAccordionProps

packages/design-system/src/components/organization/Accordion/Accordion.tsx:63

Prop	Type	Presence	Notes
`items`	`AccordionItem[]`	Required	Rows in render order. Each `id` must be unique and stable — it keys React and the open set.
`openItemIds`	`string[] \| undefined`	Optional	Controlled open item ids.
`defaultOpenItemIds`	`string[] \| undefined`	Optional	Initial open item ids for uncontrolled usage.Source default: `[]`
`multiple`	`boolean \| undefined`	Optional	Allows more than one item to be open. Defaults to true.Source default: `true`
`onOpenChange`	`((openItemIds: string[]) => void) \| undefined`	Optional	Fires on every toggle with the full next open set, including while controlled.
`haptic`	`HapticFeedback \| undefined`	Optional	Haptic feedback for row toggles. Defaults to `true` (`selection`).Source default: `true`
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Root selector, and the prefix each row and panel selector falls back to.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

Standalone grouped disclosure — independent collapsible sections, each with its own chrome, driven by an items array.

When to use

Reach for Accordion when you have several sections whose bodies should stay hidden until tapped — FAQ panels, settings groups, "learn more" blocks. multiple (the default) lets panels open independently; set it false for radio-style single-open.

Rows that are always visible and just stack flat? Use List — the container owns the hairlines.
One "show more" row that reveals extra rows inside an existing List? Use List.Disclosure, which shares the list's separators instead of adding its own chrome.
Peer panels the user switches between (only one shown at a time, no stacking)? Use Tabs.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: root
Label: Root
Description: Edge-to-edge surface stacking disclosure items with separators; carries no radius or inset of its own.
Required: true

Id: item
Label: Item
Description: A single expandable section.

Id: trigger
Label: Trigger
Description: Row button that toggles its panel and rotates the chevron.

Id: leading
Label: Leading
Description: Optional element before the trigger copy, such as an avatar or brand logo.

Id: panel
Label: Panel
Description: Animated region revealed when the item is open.

Allowed Design Choices

Variants

Grouped

Label: Grouped
Description: The single grouped-disclosure treatment.

Sizes

Variants

Id: grouped
Label: Grouped
Description: Independent expandable sections with shared chrome.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: trigger-gap
Label: Trigger content gap
Kind: exact
Token: --cds-space-12
Value: 12
Unit: px
Applies To: trigger

Id: trigger-min-height
Label: Trigger minimum height
Kind: at-least
Token: --cds-size-48
Value: 48
Unit: px
Applies To: trigger

Id: trigger-inset
Label: Trigger horizontal inset
Kind: exact
Token: --cds-space-20
Value: 20
Unit: px
Applies To: trigger
panel

Layout

Alignment: An optional leading element sits first at a fixed width, trigger copy is flexible, and the chevron stays trailing.
Flow: Items stack vertically with a hairline between adjacent rows and an animated panel per item.
Notes: Use List.Disclosure for a single show-more row that shares a list's separators.
Edge to edge like ListRoot: the enclosing Screen.Section or Card owns radius and inset. Rows match List.Item padding='card' metrics.

Typography And Color

Typography

Label: Title
Description: Trigger titles use the body ramp.
Token: --cds-type-body-size

Label: Description
Description: Trigger descriptions use the body-small ramp.
Token: --cds-type-body-small-size

Colors

Label: Surface
Description: The accordion paints the raised surface edge to edge; the parent owns shape and inset.
Token: --cds-bg-surface

Label: Separator
Description: Adjacent items are divided with the shared list divider tone.
Token: --cds-divider

Label: Chevron
Description: The chevron uses secondary text color.
Token: --cds-text-secondary

States

Id: closed
Label: Closed
Description: Collapsed item with a downward chevron.

Id: open
Label: Open
Description: Expanded item, aria-expanded true, chevron rotated.

Id: disabled
Label: Disabled
Description: Inert item that cannot be toggled.

Behavior

Label: Multiple open
Description: multiple (default) lets several panels stay open; false collapses siblings.

Label: Controlled or uncontrolled
Description: Drive openItemIds for controlled use or defaultOpenItemIds for uncontrolled.

Accessibility

Label: Disclosure semantics
Description: Each trigger sets aria-expanded and aria-controls; the panel is a labelled region.

Label: Keyboard
Description: Triggers are buttons reachable and toggleable by keyboard.

Content Adaptation

Label: Wrapping copy
Description: Long titles and descriptions wrap without widening the container.

Label: Optional description
Description: The description line renders only when provided.

Label: Optional leading element
Description: The leading slot renders only when provided and never shrinks under long copy.

Motion Haptics

Motion

Label: Expand and collapse
Description: Panels open on a 500ms decelerating curve and close on a 400ms ease-in; disabled under reduced motion.

Haptics

Label: Toggle haptic
Description: Toggling a row requests the selection haptic.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1