components / accordion

Accordion

Data-driven disclosure list with contained open-panel layouts and reliable target sizing.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Accordion reveals or hides related content in place without switching context.
  • Use it when the page benefits from progressive disclosure rather than permanent expansion.

Aliases

disclosure

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Accordion when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Accordion contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Accordion label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Accordion behind decorative copy or overloaded surface treatments.
  • Do not stretch Accordion into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Accordion for stacked sections where people may open one or a few items at a time.
  • Use descriptions when the item titles alone do not tell people what is inside.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Accordion when the user needs rapid side-by-side comparison across all content.
  • Do not use Accordion for major page-level view switching; use Tabs.

Anti-patterns

  • Using Accordion as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy accordion usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

disclosure item

item

Single accordion row with trigger and panel.

disclosure control

trigger

Interactive row that opens or closes its panel.

revealed content

panel

Associated content region for the item.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
itemsArray<{ value: string; label: string; content: string; description?: string; disabled?: boolean }>—Accordion item definitions.
valuestring | string[]—Controlled open item or items.
size'sm' | 'md''md'Chooses the accordion size recipe.
allowMultiplebooleanfalseAllows multiple items to remain open.
onChange(detail: { value: string | undefined }) => void—Callback fired when open state changes.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
change{ value: string | undefined }Fires when the component commits a new value.

Slots

NameDescription
defaultAccordion is data-driven in v1 and does not expose compound item slots.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • single: One open item at a time
  • multiple: Multiple items can remain open

Sizes

  • sm: Compact disclosure
  • md: Default disclosure

States

  • closed: Panel hidden
  • open: Panel visible
  • disabled: Item unavailable

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Uses disclosure-style controls paired with associated content regions.

Keyboard

  • Trigger controls remain keyboard reachable and togglable.

Screen readers

  • Expanded and collapsed state remains explicit through the trigger relationship.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-accordion-gap
0.75rem

item

--dk-accordion-item-bg
#f2f5fb
--dk-accordion-item-border
#95989d
--dk-accordion-item-border-width
1px
--dk-accordion-item-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

trigger

--dk-accordion-trigger-bg
#f2f5fb
--dk-accordion-trigger-fg
#16181c
--dk-accordion-trigger-bg-open
#d7e9ff
--dk-accordion-trigger-fg-open
#000f4d
--dk-accordion-trigger-fg-disabled
#95989d
--dk-accordion-trigger-gap
0.75rem
--dk-accordion-trigger-inline-padding
1rem
--dk-accordion-trigger-block-size
48px
--dk-accordion-trigger-size
1rem
--dk-accordion-trigger-weight
650

indicator

--dk-accordion-indicator-size
1rem
--dk-accordion-indicator-color
#2072e4
--dk-accordion-indicator-color-open
#000f4d

label

--dk-accordion-label-color
inherit
--dk-accordion-label-size
inherit
--dk-accordion-label-weight
inherit

description

--dk-accordion-description-color
#16181c
--dk-accordion-description-size
0.8125rem

panel

--dk-accordion-panel-bg
#f2f5fb
--dk-accordion-panel-fg
#16181c
--dk-accordion-panel-padding
1rem
--dk-accordion-panel-size
0.9375rem

Implementation notes

  • Accordion stays data-driven in v1 so disclosure content remains deterministic for tests and examples.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: single-open disclosure

A standard disclosure list with one open item at a time.

Copy snippet

<Accordion items={faqItems} />

Common patterns

1 example

common

Common: multi-open content

Allow multiple open items when comparing content matters more than compression.

Copy snippet

<Accordion items={faqItems} allowMultiple={true} value={['overview', 'timeline']} />

Edge cases

1 example

edge

Edge: unavailable section

Individual items can be disabled without removing them.

Copy snippet

<Accordion items={[{ value: 'overview', label: 'Overview', content: 'Ready' }, { value: 'timeline', label: 'Timeline', content: 'Locked', disabled: true }]} />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

accordion-sm

pass

size=sm

  • Contrast: 98.5 Lc, 98.5 Lc
  • Target: 44px
  • Layout: 267 / 320, 420

accordion-md-open

pass

size=md

  • Contrast: 98.5 Lc, 98.5 Lc
  • Target: 48px
  • Layout: 399 / 320, 420