CSC Design System Skills & Best Practices
Ctrl K
CS
On this page

Proposed CSC Standards · 0.1.0

Accordions

A disclosure that shows and hides a section.

Shorten a page when most sections are optional reading.

Live componentResponsive playground

What this describes

Default

Bordered

Minimal

Separated

When to use

  • Frequently asked questions.
  • Optional details under a heading.

When not to use

  • Content the person must read to complete a task. Keep that visible.
  • Peer views of equal importance. Use Tabs.

Allowed variants

Bordered

A list of questions.

Hierarchy
Divided rows.
Use in
Help pages.
Restriction
Headers are buttons.
Accessibility
aria-expanded.
Responsive
Full width.

Minimal

A quiet list.

Hierarchy
Less chrome.
Use in
Inside a card.
Restriction
The expanded state is still programmatic.
Accessibility
Same button headers.
Responsive
Full width.

Separated

Items that are distinct topics.

Hierarchy
Gaps between items.
Use in
Long FAQs.
Restriction
Do not hide required steps.
Accessibility
Same pattern.
Responsive
Gaps do not cause overflow.

Mandatory rules

ACC-001RequiredARIA

The header is a button that exposes expanded state

Each trigger is a button with aria-expanded.

Implementation detail

The disclosure pattern. Accordion uses Radix Accordion.

The header is a button with aria-expanded. Do not toggle a div with a click handler.

Check: The header is a button and aria-expanded matches the panel.

Source

ACC-002ProhibitedProposed CSC convention

Do not hide required instructions

Required steps stay outside the collapsed panel.

Implementation detail

Proposed CSC Standard. People miss collapsed requirements.

Put required text in the page, not only inside a closed item.

Check: Completing the task does not depend on opening an accordion.

ACC-003RecommendedProposed CSC convention

Keep headers full width and wrapped

Long questions wrap inside the header button.

Implementation detail

Proposed CSC Standard. A nowrap header overflows at 320px.

Allow the button label to wrap. The hit area includes the wrapped lines.

Check: At 320px the header is fully visible.

Restrictions

  • ACC-002 Do not hide required instructions. Required steps stay outside the collapsed panel.

Accessibility

  • Button headers.
  • Expanded state is exposed.
  • Required content is not collapsed.

Responsive behavior

  • Headers wrap.
  • Panels use the column width.

Component states

Collapsed

aria-expanded false. Panel content is not readable until opened.

Expanded

The panel is visible.

Correct implementation

Bordered accordionCorrect implementation · TSX

The header is a button. aria-expanded matches the open panel.

Imports: None. Dependencies: None. Rules: ACC-001.

export function HelpList() {
  return (
    <div style={{ border: '1px solid #E7EBF2', borderRadius: 10 }}>
      <button type="button" aria-expanded="false">What is a reference number?</button>
    </div>
  );
}

Incorrect implementation

No incorrect example is published for this component.

Common mistakes

  • Clickable headings that are not buttons.
  • Required instructions inside a closed item.

Testing checklist

Agent prompts for this component are in the AI Development Hub.