WCAG-Compliant Accordion Component for Drupal (SDC + Tailwind)

Create an accessible accordion component implemented as a Drupal module using Drupal Single Directory Components (SDC). The component must meet WCAG 2.2 AA requirements and follow WAI-ARIA Authoring Practices for accordions. Styling must be done using Tailwind CSS utility classes only.

---

Architecture & Drupal requirements

• Implement the accordion as a Drupal module exposing one or more SDC components.
• Each accordion is an SDC component with:
  • component.yml
  • Twig template
  • Optional JS behavior
  • Tailwind-based styling
• Component must be renderable via:
  • Twig includes
  • Render arrays
  • Field formatter or block (optional, but architecture-ready)
• Component input data should be passed via SDC props (e.g. items, allow_multiple, expanded_by_default).

---

Markup & semantics

• Accordion headers must be real <button> elements, not divs or links.
• Each accordion item consists of:
  • A header button
  • A content panel
• Panels must be present in the DOM at all times (no conditional rendering that removes content).

Required relationships

• Each header button:
  • Controls exactly one panel
  • Has a unique ID
• Each panel:
  • References its header
  • Is hidden from assistive tech when collapsed

---

ARIA & accessibility requirements

Apply ARIA only where needed and correctly.

Header buttons

• aria-expanded="true | false" reflects current state
• aria-controls="panel-id"

Panels

• role="region"
• aria-labelledby="header-id"
• Use hidden, inert, or equivalent to hide collapsed panels accessibly

Do not duplicate native semantics (e.g. no role="button" on <button>).

---

Keyboard interaction (WCAG 2.1.1, 2.4.3)

The accordion must be fully keyboard-operable:

Required

• Tab / Shift+Tab: enter and exit accordion normally
• Enter or Space: toggle the focused header

Recommended (ARIA pattern)

• ArrowDown: move focus to next header
• ArrowUp: move focus to previous header
• Home: move focus to first header
• End: move focus to last header

Focus must remain on the header button when toggling.

---

State management

• Support:
  • Single-open mode (opening one panel closes others)
  • Multi-open mode
• State must stay in sync across:
  • DOM visibility
  • aria-expanded
  • Tailwind state classes

---

Styling (Tailwind CSS)

• Use Tailwind utility classes exclusively.
• No inline styles.
• Visual states must be distinguishable without color alone:
  • Expanded vs collapsed
  • Focused vs unfocused
• Focus styles must be clearly visible and meet contrast requirements.
• Use Tailwind variants or state classes to reflect expanded state.

---

Motion & reduced motion

• If transitions are used:
  • Respect prefers-reduced-motion
  • Avoid height animations that break screen readers
• Animations must never interfere with focus or announcements.

---

JavaScript behavior (Drupal-friendly)

• Attach JS using Drupal behaviors.
• Must support:
  • Multiple accordions on the same page
  • Dynamic rendering (AJAX, BigPipe, etc.)
• No global state leakage.
• Component must function without JS (all panels expanded by default).

---

Screen reader expectations

• Screen readers must announce:
  • Header as “button”
  • Expanded / collapsed state
• Content inside expanded panels must be read in natural order.
• Collapsed panels must not be reachable by screen readers.

---

Robustness & degradation

• Works with mouse, keyboard, touch, and assistive technologies.
• Graceful fallback if JavaScript fails.
• No reliance on CSS-only hacks that break accessibility.

---

Install Drupal modules

• Install drupal/paragraphs module

Configurations

• Create text paragraph type - it consists of a long formatted text field - field_text_body.
• Create accordion_item paragraph type, this contains field_accordion_item_title and field_accordion_item_body
• The field_accordion_item_body supports referencing paragraphs and, by default, allows text paragraph type.
• Create an accordion paragraph type.
• Add accordion main title field field_accordion_title
• Add field_field_accordion_item, and this needs to reference the accordion_item paragraph type

---

Integrate Drupal SDC accordion component

• Use the hook class to create paragraphs view alter and make it to use the newly created accordion component.

---

Deliverables

• Drupal module structure
• SDC component files
• Twig markup with proper semantics
• Tailwind-based styling
• Drupal behavior JS
• Accessibility rationale explaining:
  • ARIA usage
  • Keyboard handling
  • WCAG success criteria addressed
• List of common accessibility pitfalls avoided