@fpkit/acss 0.5.12 → 0.5.13

package/src/components/details/ACCESSIBILITY-REVIEW.md

@@ -0,0 +1,502 @@
+# 🔍 Accessibility Review: Details Component
+
+**Review Date:** 2025-10-20
+**WCAG Version:** 2.1 Level AA
+**Reviewer:** Claude Code (WCAG Compliance Reviewer)
+
+---
+
+## Executive Summary
+
+**Overall Rating: ✅ Excellent** - The Details component demonstrates strong accessibility practices by leveraging native HTML `<details>` and `<summary>` elements, which provide built-in keyboard support and ARIA semantics.
+
+**Issues Found:** 0 errors, 2 warnings, 3 recommendations
+
+---
+
+## ✅ What's Working Well
+
+### 1. **Semantic HTML Foundation (WCAG 4.1.2, 1.3.1)**
+The component uses native `<details>` and `<summary>` elements, which provide:
+- Built-in `aria-expanded` state management by the browser
+- Native keyboard support (Space, Enter)
+- Automatic screen reader announcements as "disclosure" or "expandable" widget
+- Proper role semantics without additional ARIA
+
+### 2. **Keyboard Accessibility (WCAG 2.1.1)**
+✅ Native `<details>` element handles all keyboard interactions
+✅ No custom JavaScript required for basic keyboard functionality
+✅ No keyboard traps
+
+### 3. **Focus Indicators (WCAG 2.4.7)**
+From `details.scss:77-81`:
+```scss
+&:focus-within {
+  outline: none;
+  border-bottom: solid 2px currentColor;
+  background-color: whitesmoke;
+}
+```
+✅ Custom focus indicator with visible border and background change
+✅ Uses `currentColor` which adapts to text color
+
+### 4. **Component Forwarding (React Best Practice)**
+From `details.tsx:54`:
+```tsx
+export const Details = React.forwardRef<HTMLDetailsElement, DetailsProps>(
+```
+✅ Properly forwards refs to enable programmatic focus management
+
+### 5. **Accordion Behavior (WCAG 4.1.2)**
+The component supports the native `name` attribute for accordion groups where only one details can be open at a time - this is a modern HTML feature with excellent accessibility.
+
+---
+
+## ⚠️ Warnings (Should Fix)
+
+### Warning 1: Focus Indicator Contrast Not Guaranteed
+
+**Location:** `details.scss:77-81`
+
+**Issue (WCAG 2.4.7 - Level AA):**
+```scss
+&:focus-within {
+  outline: none;  // ← Removes native outline
+  border-bottom: solid 2px currentColor;  // ← Uses currentColor
+  background-color: whitesmoke;
+}
+```
+
+**Problem:**
+- The custom focus indicator uses `currentColor`, which means the border color depends on the text color
+- If text color has low contrast with the background, the focus indicator might fall below the required 3:1 contrast ratio
+- `whitesmoke` (#f5f5f5) background might not provide sufficient contrast in all color schemes
+
+**Recommended Fix:**
+```scss
+&:focus-within {
+  outline: 2px solid #0066CC; /* Specific high-contrast color */
+  outline-offset: 2px;
+  background-color: #e8f4f8; /* Light blue tint */
+}
+
+/* Or use focus-visible for better UX */
+&:focus-visible {
+  outline: 2px solid #0066CC;
+  outline-offset: 2px;
+  background-color: #e8f4f8;
+}
+
+&:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+**Why:** WCAG 2.4.7 requires focus indicators to have at least 3:1 contrast ratio against adjacent colors. Using a specific color ensures this requirement is consistently met.
+
+---
+
+### Warning 2: Optional `aria-label` May Cause Confusion
+
+**Location:** `details.tsx:94`
+
+**Issue (WCAG 4.1.2 - Best Practice):**
+```tsx
+<UI
+  as="details"
+  aria-label={ariaLabel}  // ← Applied to <details> element
+  ...>
+```
+
+**Problem:**
+- The native `<details>` element already has proper semantics
+- Adding `aria-label` to the `<details>` element might override the automatic screen reader announcement
+- The label should typically be on the `<summary>` element, not the `<details>` wrapper
+- Most screen readers announce: "Disclosure: [summary content], collapsed/expanded"
+
+**Current Type Definition:** `details.types.ts:49-61`
+```tsx
+/**
+ * Accessible label for screen readers.
+ * If not provided, the native `<details>` semantic will be used.
+ *
+ * Note: Native `<details>` elements are already semantic and announced properly
+ * by screen readers. Only provide this if you need to override the default behavior.
+ */
+ariaLabel?: string;
+```
+
+**Recommended Fix:**
+
+Option A - Remove `aria-label` from details (preferred):
+```tsx
+<UI
+  as="details"
+  // Remove aria-label from details element
+  ...>
+  <UI
+    as="summary"
+    onPointerDown={handlePointerDown}
+    aria-label={ariaLabel}  // Move here if needed
+  >
+```
+
+Option B - Keep current implementation with better documentation:
+The documentation is actually quite good! It warns users this should rarely be used. Consider moving the `ariaLabel` to apply to the summary element instead for better screen reader support.
+
+**Why:** Adding `aria-label` to `<details>` can interfere with the native semantic announcement. If additional labeling is needed, it should be on the `<summary>` element.
+
+---
+
+## 💡 Recommendations (Best Practices)
+
+### Recommendation 1: Add `aria-controls` Relationship
+
+**Enhancement:** Strengthen the relationship between summary and content for screen readers.
+
+**Suggested Implementation:**
+```tsx
+export const Details = React.forwardRef<HTMLDetailsElement, DetailsProps>(
+  ({ summary, icon, styles, classes, ariaLabel, name, open, onPointerDown, onToggle, children, ...props }, ref) => {
+    const contentId = React.useId(); // Generate unique ID
+
+    return (
+      <UI as="details" ...>
+        <UI
+          as="summary"
+          onPointerDown={handlePointerDown}
+          aria-controls={contentId}  // ← Links to content
+        >
+          {icon}
+          {summary}
+        </UI>
+        <UI as="section" id={contentId}>  {/* ← Receives ID */}
+          {children}
+        </UI>
+      </UI>
+    );
+  }
+);
+```
+
+**Benefit:** Explicitly declares the relationship between trigger and content for assistive technologies.
+
+---
+
+### Recommendation 2: Consider `aria-hidden` for Decorative Icons
+
+**Enhancement:** If the `icon` prop is purely decorative (like a chevron), it should be hidden from screen readers.
+
+**Current Usage Example:**
+```tsx
+<Details
+  summary="Shipping Information"
+  icon={<ChevronDownIcon />}  // ← Should this be announced?
+>
+```
+
+**Recommendation:**
+Add guidance in documentation or automatically apply `aria-hidden`:
+
+```tsx
+// Option 1: Document in examples
+<Details
+  summary="Shipping Information"
+  icon={<ChevronDownIcon aria-hidden="true" />}
+>
+
+// Option 2: Wrap icon automatically (recommended)
+<UI as="summary" onPointerDown={handlePointerDown}>
+  {icon && <span aria-hidden="true">{icon}</span>}
+  {summary}
+</UI>
+```
+
+**Why:** Decorative icons add visual context but should not be announced by screen readers, as the summary text already conveys the meaning (WCAG 1.1.1).
+
+---
+
+### Recommendation 3: Add Example with ARIA Live Region for Dynamic Content
+
+**Enhancement:** Document how to handle dynamically loaded content within details.
+
+**Add to JSDoc documentation:**
+```tsx
+/**
+ * @example
+ * ```tsx
+ * // Details with async content loading
+ * <Details summary="Load More Data" onToggle={handleLoadData}>
+ *   {isLoading ? (
+ *     <div role="status" aria-live="polite">Loading...</div>
+ *   ) : (
+ *     <div>{data}</div>
+ *   )}
+ * </Details>
+ * ```
+ */
+```
+
+**Why:** Users may load content dynamically when details open. Screen readers need to be informed of loading states (WCAG 4.1.3).
+
+---
+
+## 🎨 CSS Accessibility Review
+
+### ✅ Good Practices Found:
+
+1. **rem Units Throughout** - Text and spacing use relative units for zoom compatibility (WCAG 1.4.4)
+2. **CSS Custom Properties** - Themeable design supports user customization (WCAG 1.4.12)
+3. **Smooth Transitions** - Visual feedback for state changes aids understanding
+4. **Marker Removal** - Custom styling without breaking semantics
+5. **Responsive Design** - Proper border and radius handling for stacked details
+
+### ⚠️ CSS Concern: Text Spacing Support (WCAG 1.4.12)
+
+The component should be tested with increased text spacing requirements:
+```css
+/* Test with these overrides */
+* {
+  line-height: 1.5 !important;
+  letter-spacing: 0.12em !important;
+  word-spacing: 0.16em !important;
+  margin-bottom: 2em !important; /* Paragraph spacing */
+}
+```
+
+**Recommendation:** Add to testing documentation to ensure content doesn't overflow or become clipped.
+
+---
+
+## 🧪 Testing Recommendations
+
+### Automated Testing
+
+**Install Dependencies:**
+```bash
+npm install --save-dev jest-axe @axe-core/react @testing-library/user-event
+```
+
+**Component Test Example:**
+```tsx
+import { render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { Details } from './details';
+
+expect.extend(toHaveNoViolations);
+
+describe('Details - Accessibility', () => {
+  test('has no accessibility violations', async () => {
+    const { container } = render(
+      <Details summary="Test Summary">
+        <p>Test content</p>
+      </Details>
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  test('is keyboard accessible', async () => {
+    const user = userEvent.setup();
+    const { getByText } = render(
+      <Details summary="Click to expand">
+        <p>Hidden content</p>
+      </Details>
+    );
+
+    const summary = getByText('Click to expand');
+
+    // Tab to summary
+    await user.tab();
+    expect(summary).toHaveFocus();
+
+    // Press Enter to open
+    await user.keyboard('{Enter}');
+    expect(getByText('Hidden content')).toBeVisible();
+  });
+
+  test('accordion mode works correctly', async () => {
+    const { container } = render(
+      <>
+        <Details name="accordion" summary="Item 1">Content 1</Details>
+        <Details name="accordion" summary="Item 2" open>Content 2</Details>
+        <Details name="accordion" summary="Item 3">Content 3</Details>
+      </>
+    );
+
+    const allDetails = container.querySelectorAll('details');
+    const openDetails = container.querySelectorAll('details[open]');
+
+    expect(allDetails).toHaveLength(3);
+    expect(openDetails).toHaveLength(1);
+  });
+});
+```
+
+### Manual Testing Checklist
+
+#### Keyboard Navigation
+- [ ] Tab to summary - should receive focus with visible indicator
+- [ ] Press Space - should toggle open/closed
+- [ ] Press Enter - should toggle open/closed
+- [ ] Tab when open - should move to content inside
+- [ ] Shift+Tab - should move focus backwards correctly
+- [ ] No keyboard traps when navigating through content
+
+#### Screen Reader Testing (NVDA/VoiceOver/JAWS)
+- [ ] Announces as "disclosure", "expandable", or similar widget type
+- [ ] Announces current state (expanded/collapsed)
+- [ ] Summary text is read correctly
+- [ ] Content is accessible and announced when expanded
+- [ ] Icon (if present) is not announced if decorative
+- [ ] State changes are announced when toggling
+
+#### Visual Testing
+- [ ] Focus indicator visible with sufficient contrast (minimum 3:1)
+- [ ] Focus indicator works in dark mode (if applicable)
+- [ ] Works at 200% browser zoom without horizontal scrolling
+- [ ] Content reflows properly at 320px viewport width
+- [ ] Works with increased text spacing (1.5 line-height, 0.12em letter-spacing)
+- [ ] Custom CSS properties can be overridden for theming
+
+#### Accordion Mode Testing
+- [ ] Only one details open at a time when using `name` attribute
+- [ ] Opening one closes the others in the same group
+- [ ] State changes announced to screen readers
+- [ ] Keyboard navigation works between accordion items
+
+#### Browser Testing
+- [ ] Chrome/Edge (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Mobile Safari (iOS)
+- [ ] Chrome Mobile (Android)
+
+---
+
+## 📊 WCAG 2.1 AA Compliance Summary
+
+| Criterion | Level | Status | Notes |
+|-----------|-------|--------|-------|
+| **1.1.1 Non-text Content** | A | ✅ Pass | No images in component core; icon handling documented |
+| **1.3.1 Info & Relationships** | A | ✅ Pass | Semantic `<details>` and `<summary>` elements |
+| **1.3.2 Meaningful Sequence** | A | ✅ Pass | Logical DOM order maintained |
+| **1.4.3 Contrast (Minimum)** | AA | ⚠️ Warning | Focus indicator contrast not guaranteed with `currentColor` |
+| **1.4.10 Reflow** | AA | ✅ Pass | Uses flexible layout; recommend testing at 320px |
+| **1.4.11 Non-text Contrast** | AA | ⚠️ Warning | Focus indicator needs contrast verification |
+| **1.4.12 Text Spacing** | AA | ✅ Pass | Uses rem units; recommend manual testing |
+| **1.4.13 Content on Hover/Focus** | AA | N/A | No hover/focus tooltips |
+| **2.1.1 Keyboard** | A | ✅ Pass | Native keyboard support via `<details>` |
+| **2.1.2 No Keyboard Trap** | A | ✅ Pass | No traps detected |
+| **2.4.3 Focus Order** | A | ✅ Pass | Logical DOM and focus order |
+| **2.4.7 Focus Visible** | AA | ⚠️ Warning | Custom focus indicator needs guaranteed contrast |
+| **3.2.1 On Focus** | A | ✅ Pass | No unexpected context changes |
+| **3.2.2 On Input** | A | ✅ Pass | Toggle requires explicit activation |
+| **4.1.2 Name, Role, Value** | A | ✅ Pass | Native semantics provide all required properties |
+| **4.1.3 Status Messages** | AA | 💡 Recommend | Document pattern for dynamic content loading |
+
+**Legend:**
+- ✅ Pass - Meets requirement
+- ⚠️ Warning - Needs attention to ensure compliance
+- 💡 Recommend - Optional enhancement
+- N/A - Not applicable to this component
+
+---
+
+## 🎯 Quick Wins (Priority Fixes)
+
+### High Priority (5-15 minutes total)
+
+1. **Update focus indicator for guaranteed contrast** (5 min)
+   ```scss
+   summary {
+     &:focus-visible {
+       outline: 2px solid #0066CC;
+       outline-offset: 2px;
+       background-color: #e8f4f8;
+     }
+
+     &:focus:not(:focus-visible) {
+       outline: none;
+     }
+   }
+   ```
+
+2. **Consider moving `ariaLabel` to summary or removing** (10 min)
+   - Review if `aria-label` on `<details>` is truly needed
+   - If needed, apply to `<summary>` instead
+   - Update TypeScript types accordingly
+
+### Medium Priority (15-30 minutes)
+
+3. **Add `aria-controls` relationship** (10 min)
+   - Use `React.useId()` to generate unique IDs
+   - Link summary to content section
+
+4. **Auto-hide decorative icons from screen readers** (10 min)
+   ```tsx
+   {icon && <span aria-hidden="true">{icon}</span>}
+   ```
+
+5. **Add automated accessibility tests** (10 min)
+   - Install jest-axe
+   - Add basic axe tests to existing test file
+
+### Low Priority (Optional Enhancements)
+
+6. **Document dynamic content patterns** (5 min)
+   - Add JSDoc examples for loading states
+   - Show ARIA live region usage
+
+7. **Create comprehensive manual test checklist** (Already done in this document!)
+
+---
+
+## 📚 Additional Resources
+
+### WCAG Guidelines
+- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.1&levels=aa)
+- [Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/)
+- [ARIA Authoring Practices Guide - Disclosure Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)
+
+### HTML Details Element
+- [MDN: The Details Disclosure Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)
+- [HTML Spec: The details element](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-details-element)
+
+### Testing Tools
+- [axe DevTools Browser Extension](https://www.deque.com/axe/devtools/)
+- [WAVE Browser Extension](https://wave.webaim.org/extension/)
+- [NVDA Screen Reader](https://www.nvaccess.org/) (Windows, Free)
+- [VoiceOver Screen Reader](https://www.apple.com/accessibility/voiceover/) (macOS/iOS, Built-in)
+
+---
+
+## 💡 Key Insights
+
+### 1. Native HTML Wins
+This component brilliantly leverages `<details>` and `<summary>`, which are among the most accessible HTML5 elements. The browser handles `aria-expanded`, keyboard events, and screen reader semantics automatically - no custom JavaScript needed! This is a perfect example of "use platform features first."
+
+### 2. Focus-visible Pattern
+Modern CSS supports `:focus-visible` which shows focus indicators only for keyboard users (not mouse clicks), providing better UX without compromising accessibility. This is preferable to the older `:focus-within` approach used currently.
+
+### 3. Progressive Enhancement
+The `name` attribute for accordion behavior is a modern HTML feature with excellent accessibility built-in. It's a perfect example of progressive enhancement where newer browsers get richer functionality while older browsers still work perfectly with independent details elements.
+
+---
+
+## Summary
+
+The Details component is **already highly accessible** thanks to its use of semantic HTML. The warnings are minor and relate to ensuring consistent contrast in all theming scenarios. The recommendations are optional enhancements that would make an already excellent component even better.
+
+**Estimated time to address all warnings:** 15-20 minutes
+**Current accessibility grade:** A- (Excellent, with minor improvements possible)
+
+---
+
+**Next Steps:**
+1. Review and address the two warnings (focus indicator contrast)
+2. Consider implementing the recommended enhancements
+3. Add automated accessibility tests to CI/CD pipeline
+4. Conduct manual screen reader testing with NVDA and VoiceOver
+5. Test with users who rely on assistive technologies (if possible)