# Accordion Grouped disclosure of independent expandable sections driven by an items array, with animated panels. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/organization/Accordion/Accordion.tsx ## Guidance { "summary": "Grouped disclosure of independent expandable sections driven by an items array, with animated panels.", "guidance": [ { "heading": "Overview", "body": "Standalone grouped disclosure — independent collapsible sections, each with its own chrome, driven\nby an `items` array." }, { "heading": "When to use", "body": "Reach for `Accordion` when you have several sections whose bodies should stay hidden until tapped —\nFAQ panels, settings groups, \"learn more\" blocks. `multiple` (the default) lets panels open\nindependently; set it `false` for radio-style single-open.\n\n- Rows that are always visible and just stack flat? Use `List` — the container owns the hairlines.\n- One \"show more\" row that reveals extra rows _inside_ an existing `List`? Use `List.Disclosure`,\n which shares the list's separators instead of adding its own chrome.\n- Peer panels the user switches between (only one shown at a time, no stacking)? Use `Tabs`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/organization/Accordion/Accordion.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "items", "type": "AccordionItem[]", "declared_type": "AccordionItem[]", "required": true, "description": "Rows in render order. Each `id` must be unique and stable — it keys React and the open set.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 42 } }, { "name": "openItemIds", "type": "string[] | undefined", "declared_type": "string[]", "required": false, "description": "Controlled open item ids.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 44 } }, { "name": "defaultOpenItemIds", "type": "string[] | undefined", "declared_type": "string[]", "required": false, "description": "Initial open item ids for uncontrolled usage.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 46 }, "default": "[]", "default_kind": "source-expression" }, { "name": "multiple", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Allows more than one item to be open. Defaults to true.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 48 }, "values": [ false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "onOpenChange", "type": "((openItemIds: string[]) => void) | undefined", "declared_type": "(openItemIds: string[]) => void", "required": false, "description": "Fires on every toggle with the full next open set, including while controlled.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 50 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for row toggles. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 52 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 53 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 54 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Root selector, and the prefix each row and panel selector falls back to.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 56 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Accordion", "public_path": "Accordion", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Accordion", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 63 }, "props_type": "AccordionProps", "props": [ { "name": "items", "type": "AccordionItem[]", "declared_type": "AccordionItem[]", "required": true, "description": "Rows in render order. Each `id` must be unique and stable — it keys React and the open set.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 42 } }, { "name": "openItemIds", "type": "string[] | undefined", "declared_type": "string[]", "required": false, "description": "Controlled open item ids.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 44 } }, { "name": "defaultOpenItemIds", "type": "string[] | undefined", "declared_type": "string[]", "required": false, "description": "Initial open item ids for uncontrolled usage.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 46 }, "default": "[]", "default_kind": "source-expression" }, { "name": "multiple", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Allows more than one item to be open. Defaults to true.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 48 }, "values": [ false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "onOpenChange", "type": "((openItemIds: string[]) => void) | undefined", "declared_type": "(openItemIds: string[]) => void", "required": false, "description": "Fires on every toggle with the full next open set, including while controlled.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 50 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for row toggles. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 52 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 53 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 54 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Root selector, and the prefix each row and panel selector falls back to.", "source": { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 56 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 16, "name": "AccordionItem", "code": "export interface AccordionItem {\n /** The value callers put in `openItemIds` / `defaultOpenItemIds`, and the suffix of the generated trigger and panel element ids that wire up aria. */\n id: string;\n /** Element shown before the copy, such as an `Avatar` or a brand logo. */\n leading?: React.ReactNode;\n /** Primary row copy, on the `body` ramp above `description`. */\n title: React.ReactNode;\n /** Optional supporting copy shown in the trigger row. */\n description?: React.ReactNode;\n /** Panel body. Always mounted — a collapsed panel is hidden, not unmounted. */\n content: React.ReactNode;\n /** Dims the row and blocks toggling. A panel that is already open stays open. */\n disabled?: boolean;\n /**\n * Row test selector, and `-panel` for its panel. Defaults to the Accordion's own `testId`\n * suffixed with `id` — pass this when `id` is a raw value that would not read as kebab-case.\n */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/organization/Accordion/Accordion.tsx", "line": 40, "name": "AccordionProps", "code": "export interface AccordionProps {\n /** Rows in render order. Each `id` must be unique and stable — it keys React and the open set. */\n items: AccordionItem[];\n /** Controlled open item ids. */\n openItemIds?: string[];\n /** Initial open item ids for uncontrolled usage. */\n defaultOpenItemIds?: string[];\n /** Allows more than one item to be open. Defaults to true. */\n multiple?: boolean;\n /** Fires on every toggle with the full next open set, including while controlled. */\n onOpenChange?: (openItemIds: string[]) => void;\n /** Haptic feedback for row toggles. Defaults to `true` (`selection`). */\n haptic?: HapticFeedback;\n className?: string;\n style?: React.CSSProperties;\n /** Root selector, and the prefix each row and panel selector falls back to. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Accordion", "status": "preview", "version": "1.0.0", "summary": "Grouped disclosure of independent expandable sections driven by an items array, with animated panels." }, "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." } ], "allowedDesignChoices": { "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": [], "measurements": [ { "id": "trigger-gap", "label": "Trigger content gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "trigger" ] }, { "id": "trigger-min-height", "label": "Trigger minimum height", "kind": "at-least", "token": "--cds-size-48", "value": 48, "unit": "px", "appliesTo": [ "trigger" ] }, { "id": "trigger-inset", "label": "Trigger horizontal inset", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "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." ] }, "typographyAndColor": { "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." } ], "contentAdaptation": [ { "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." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-space-12", "light": "12px", "dark": "12px" }, { "name": "--cds-size-48", "light": "48px", "dark": "48px" }, { "name": "--cds-space-20", "light": "20px", "dark": "20px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-bg-surface", "light": "#ffffff", "dark": "#1b1b18" }, { "name": "--cds-divider", "light": "#e0ddd6", "dark": "#ffffff1a" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Playground](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx - [Initially Open](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--initially-open&viewMode=story) | export: InitiallyOpen | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx - [Single Open](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--single-open&viewMode=story) | export: SingleOpen | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx - [With Leading](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--with-leading&viewMode=story) | export: WithLeading | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx - [With Disabled Item](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--with-disabled-item&viewMode=story) | export: WithDisabledItem | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx - [Many Items](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--many-items&viewMode=story) | export: ManyItems | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx - [Long Text](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--long-text&viewMode=story) | export: LongText | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-organization-accordion--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/organization/Accordion/Accordion.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.