# Collapsible Sections Best Practices

**Last Updated:** 2025-01-27

## HTML5 Details/Summary Pattern

### Basic Structure

```html
<details>
  <summary>Category Name</summary>
  <div class="content">
    <!-- Category content -->
  </div>
</details>
```

### Accessibility Requirements

#### ARIA Attributes

- `aria-expanded`: Automatically managed by browser for `<details>`
- `aria-label`: For screen reader descriptions
- `role="button"`: Implicit for `<summary>` element

#### Keyboard Navigation

- **Enter/Space**: Toggle open/closed (native browser support)
- **Tab**: Navigate to next interactive element
- **Arrow Keys**: Navigate within content (if focusable)

#### Screen Reader Support

- `<details>` element is natively accessible
- Screen readers announce "collapsed" or "expanded" state
- Summary text is read as button label

### CSS Best Practices

#### Smooth Animations

```css
details {
  transition: all 0.3s ease;
}

details[open] summary {
  /* Expanded state styles */
}

details summary::-webkit-details-marker {
  display: none; /* Hide default marker */
}

details summary::marker {
  content: ""; /* Remove default marker */
}
```

#### Performance

- Use `transform` and `opacity` for animations (GPU accelerated)
- Avoid animating `height` directly (use `max-height` trick)
- Keep animation duration 0.2s-0.3s for optimal feel

#### Icon Rotation

```css
details summary svg {
  transition: transform 0.3s ease;
}

details[open] summary svg {
  transform: rotate(180deg);
}
```

### JavaScript Enhancements

#### Optional Enhancements

- Track which sections are open/closed
- Save state to localStorage
- Smooth scroll to opened section
- Analytics tracking

#### Event Handling

```javascript
details.addEventListener("toggle", function () {
  // Handle state change
  const isOpen = this.open;
  // Update ARIA, track analytics, etc.
});
```

## Tab Navigation Best Practices

### ARIA Pattern

```html
<div role="tablist" aria-label="Feature view selection">
  <button role="tab" aria-selected="true" aria-controls="category-panel">
    Funktionen pro Kategorie
  </button>
  <button role="tab" aria-selected="false" aria-controls="plan-panel">
    Funktionen pro Plan
  </button>
</div>
```

### Keyboard Navigation

- **Arrow Keys**: Navigate between tabs
- **Enter/Space**: Activate tab
- **Home/End**: First/last tab

### Visual Indicators

- Active tab: Underline, background color, or border
- Smooth transition between tabs
- Clear focus indicators

## Animation Performance

### 60fps Target

- Use `transform` and `opacity` only
- Avoid layout-triggering properties
- Use `will-change` sparingly

### CSS Transitions

```css
/* Good */
transition: transform 0.3s ease, opacity 0.3s ease;

/* Avoid */
transition: height 0.3s ease; /* Causes layout recalculation */
```

### GPU Acceleration

```css
details summary {
  transform: translateZ(0); /* Force GPU layer */
  will-change: transform; /* Hint for browser */
}
```

## Mobile Considerations

### Touch Targets

- Minimum 44x44px touch target
- Adequate spacing between interactive elements
- Clear visual feedback on touch

### Horizontal Scroll

- Wrap table in scrollable container
- Provide visual scroll indicators
- Maintain sticky header functionality

### Collapsible Behavior

- Consider auto-expanding on mobile for better UX
- Or keep collapsed to reduce scrolling

## WCAG 2.1 Compliance

### Level AA Requirements

- **Color Contrast**: 4.5:1 for text, 3:1 for UI components
- **Keyboard Access**: All functionality via keyboard
- **Focus Indicators**: Visible focus outlines
- **Screen Reader**: Proper semantic HTML and ARIA

### Testing Checklist

- [ ] Tab through all interactive elements
- [ ] Test with screen reader (NVDA, VoiceOver)
- [ ] Verify color contrast ratios
- [ ] Test keyboard-only navigation
- [ ] Verify ARIA labels are descriptive