Drupal

--- schema: spec/v1 id: drupal.component.accordion version: 1.0.0 title: Accordion Component for Drupal description: WCAG-Compliant Accordion Component for Drupal (SDC + Tailwind) tags: - drupal - module - component - sdc visibility: public requires: tools: - ddev - composer - drush runtime: {} --- ## 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