coding-os 0.3.2__py3-none-any.whl

core/skills/a11y/references/rn-accessibility.md

@@ -0,0 +1,343 @@
+# React Native Accessibility Patterns
+
+Concrete patterns for VoiceOver (iOS) + TalkBack (Android) on React Native 0.76+.
+
+## The Five Props You Use Constantly
+
+```tsx
+<Pressable
+  accessibilityRole="button"          // 'button' | 'link' | 'header' | 'image' | 'text' | 'search' | 'none' | ...
+  accessibilityLabel="Save changes"    // primary spoken label
+  accessibilityHint="Saves and returns"// secondary, optional
+  accessibilityState={{                // disabled | selected | checked | busy | expanded
+    disabled: isSaving,
+    busy: isSaving,
+  }}
+  accessibilityValue={{ min: 0, max: 100, now: progress }}
+  onPress={handleSave}>
+  <Text>Save</Text>
+</Pressable>
+```
+
+## Hide Decorative Elements
+
+Icons and dividers shouldn't be announced.
+
+```tsx
+<View>
+  <Image
+    source={require('./divider.png')}
+    accessibilityElementsHidden={true}                    // iOS
+    importantForAccessibility="no-hide-descendants"      // Android
+    accessible={false}
+  />
+  <Text>Content</Text>
+</View>
+```
+
+For an `<Icon>` paired with text:
+
+```tsx
+{/* The icon is decorative; the text label is enough */}
+<Pressable accessibilityRole="button" accessibilityLabel="Notifications">
+  <Icon name="bell" accessible={false} />
+</Pressable>
+
+{/* The icon IS the button */}
+<Pressable accessibilityRole="button" accessibilityLabel="Open notifications">
+  <Icon name="bell" accessible={false} />
+</Pressable>
+```
+
+## Group Related Elements
+
+```tsx
+{/* SR reads "Lesson: Hexagons. 3 of 10 completed." as one unit */}
+<View
+  accessible={true}
+  accessibilityLabel={`Lesson: ${lesson.title}. ${lesson.completed} of ${lesson.total} completed.`}>
+  <Text>{lesson.title}</Text>
+  <Text>{lesson.completed} of {lesson.total} completed</Text>
+</View>
+```
+
+Without `accessible={true}`, SR reads each child separately — slower, less coherent.
+
+## Headers — Navigation by Heading
+
+VoiceOver / TalkBack let users jump heading-to-heading. Mark them.
+
+```tsx
+<Text accessibilityRole="header" style={styles.title}>
+  Profile
+</Text>
+
+<Text accessibilityRole="header" accessibilityLevel={2} style={styles.section}>
+  Account
+</Text>
+```
+
+Use `accessibilityLevel` (1-6) when meaningful; defaults to 1.
+
+## Screen-Reader-Only Text
+
+Sometimes you want extra info ONLY for SR (not visible). Use a visually-hidden Text:
+
+```tsx
+<Pressable accessibilityRole="button">
+  <Icon name="trash" accessible={false} />
+  <Text style={visuallyHidden}>Delete this lesson</Text>
+</Pressable>
+
+const visuallyHidden = {
+  position: 'absolute' as const,
+  width: 1, height: 1,
+  overflow: 'hidden' as const,
+};
+```
+
+## Live Region (Status Updates)
+
+```tsx
+const [status, setStatus] = useState('');
+
+<View
+  accessible={true}
+  accessibilityLiveRegion="polite">       // Android only; iOS uses announce
+  <Text>{status}</Text>
+</View>
+
+// Cross-platform announce:
+import { AccessibilityInfo } from 'react-native';
+AccessibilityInfo.announceForAccessibility('Saved successfully');
+```
+
+`AccessibilityInfo.announceForAccessibility(...)` works on both platforms, doesn't move focus, doesn't interrupt unless very recent.
+
+## Forms
+
+```tsx
+<View>
+  <Text accessibilityRole="header">Sign In</Text>
+
+  {/* Label is rendered + tied via accessibilityLabel */}
+  <Text>Email</Text>
+  <TextInput
+    accessibilityLabel="Email address"
+    autoComplete="email"
+    autoCapitalize="none"
+    keyboardType="email-address"
+    returnKeyType="next"
+    value={email}
+    onChangeText={setEmail}
+  />
+  {emailError && (
+    <Text
+      accessibilityLiveRegion="polite"
+      accessibilityRole="alert"
+      style={styles.errorText}>
+      {emailError}
+    </Text>
+  )}
+
+  <Text>Password</Text>
+  <TextInput
+    accessibilityLabel="Password"
+    autoComplete="current-password"
+    secureTextEntry
+    returnKeyType="done"
+    value={password}
+    onChangeText={setPassword}
+    onSubmitEditing={handleSubmit}
+  />
+
+  <Pressable
+    accessibilityRole="button"
+    accessibilityLabel="Sign in"
+    accessibilityState={{ disabled: isSubmitting, busy: isSubmitting }}
+    onPress={handleSubmit}
+    disabled={isSubmitting}>
+    <Text>{isSubmitting ? 'Signing in…' : 'Sign in'}</Text>
+  </Pressable>
+</View>
+```
+
+`autoComplete` matters: `email`, `username`, `current-password`, `new-password`, `name`, `tel`, `street-address`, `cc-number`, `one-time-code` (for SMS OTP autofill), `birthdate-full`.
+
+## Modal — Focus Trap + Initial Focus
+
+RN modals via React Navigation:
+
+```tsx
+<Stack.Screen
+  name="ConfirmDelete"
+  component={ConfirmDeleteScreen}
+  options={{
+    presentation: 'modal',
+    headerTitle: 'Confirm delete',
+    headerBackAccessibilityLabel: 'Cancel',
+  }}
+/>
+```
+
+Inside the modal, focus the primary button on mount + announce purpose:
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { AccessibilityInfo, findNodeHandle, View } from 'react-native';
+
+export function ConfirmDeleteScreen() {
+  const titleRef = useRef<View>(null);
+
+  useEffect(() => {
+    requestAnimationFrame(() => {
+      const tag = findNodeHandle(titleRef.current);
+      if (tag) AccessibilityInfo.setAccessibilityFocus(tag);
+    });
+    AccessibilityInfo.announceForAccessibility('Confirm delete');
+  }, []);
+
+  return (
+    <View>
+      <Text accessibilityRole="header" ref={titleRef}>Confirm delete</Text>
+      <Text>This action cannot be undone.</Text>
+      <Pressable accessibilityRole="button" accessibilityLabel="Cancel" onPress={cancel}>
+        <Text>Cancel</Text>
+      </Pressable>
+      <Pressable accessibilityRole="button" accessibilityLabel="Delete permanently" onPress={confirm}>
+        <Text>Delete</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+Native modals from React Navigation handle focus return on dismiss automatically.
+
+## Touch Targets
+
+WCAG 2.5.8: minimum 24×24 CSS px. iOS HIG recommends 44×44pt. Android Material recommends 48×48dp.
+
+```tsx
+<Pressable
+  hitSlop={{ top: 12, right: 12, bottom: 12, left: 12 }}    // expand effective tap area
+  style={styles.icon}>
+  <Icon name="close" size={20} />
+</Pressable>
+```
+
+`hitSlop` is the pragmatic answer when the visible icon is small but the touch area should be larger.
+
+## Long Lists — FlashList Accessibility
+
+FlashList recycles rows. Each cell needs explicit accessibility props or SR may read the wrong content.
+
+```tsx
+<FlashList
+  data={lessons}
+  estimatedItemSize={88}
+  renderItem={({ item }) => (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`${item.title}, ${item.completed ? 'completed' : 'not started'}`}
+      onPress={() => navigate('Lesson', { lessonId: item.id })}>
+      <Text>{item.title}</Text>
+    </Pressable>
+  )}
+  keyExtractor={(item) => item.id}
+/>
+```
+
+## Dynamic Type
+
+iOS users can scale text up to ~310% via Settings → Accessibility → Display & Text Size. RN's `<Text>` respects this by default (`allowFontScaling={true}`).
+
+```tsx
+{/* Default: scales with user setting */}
+<Text style={{ fontSize: 16 }}>Body</Text>
+
+{/* OPT OUT (rare — only for fixed UI like number-pad keys) */}
+<Text style={{ fontSize: 16 }} allowFontScaling={false}>1</Text>
+
+{/* Cap the scale to avoid layout breakage */}
+<Text style={{ fontSize: 16 }} maxFontSizeMultiplier={1.6}>...</Text>
+```
+
+Test at the largest accessibility setting (`AX5`). Fix layout breakage by allowing wrap, scrollable containers, conditional element hiding.
+
+## Reduce Motion
+
+```tsx
+import { AccessibilityInfo } from 'react-native';
+
+const [reduceMotion, setReduceMotion] = useState(false);
+useEffect(() => {
+  AccessibilityInfo.isReduceMotionEnabled().then(setReduceMotion);
+  const sub = AccessibilityInfo.addEventListener('reduceMotionChanged', setReduceMotion);
+  return () => sub.remove();
+}, []);
+
+// Use in animations:
+const transition = reduceMotion ? withTiming(target, { duration: 0 })
+                                : withSpring(target);
+```
+
+Reanimated 3 worklets respect this if you check inside the worklet.
+
+## Color + Dark Mode
+
+`useColorScheme()` returns 'light' | 'dark' from system pref.
+
+```tsx
+import { useColorScheme } from 'react-native';
+
+const scheme = useColorScheme();
+const styles = scheme === 'dark' ? darkStyles : lightStyles;
+```
+
+Verify contrast in BOTH modes — colors that pass AA on white may fail on near-black.
+
+## Testing — Per Flow
+
+Run through each critical flow with VoiceOver / TalkBack on:
+
+- **Sign-in**: focus reaches each field, errors announced, success navigates correctly.
+- **Browse → start lesson**: list announces title + status, can tap to open.
+- **Settings**: every toggle / button reachable + correctly labeled.
+- **Modal**: opens with focus on title, Esc / back button closes, focus restored.
+- **Form**: required fields announced, errors announced, submit works.
+
+For automated checks: add `@testing-library/react-native` accessibility queries to component tests.
+
+```typescript
+import { render, screen } from '@testing-library/react-native';
+
+test('save button has accessible label', () => {
+  render(<SaveButton />);
+  const button = screen.getByRole('button', { name: 'Save changes' });
+  expect(button).toBeOnTheScreen();
+});
+```
+
+## Common RN a11y Failures
+
+1. **`<View onPress>`** instead of `<Pressable>` — no role, no SR feedback.
+2. **Icon button without `accessibilityLabel`** — SR reads nothing.
+3. **`accessibilityRole` not set** on custom-styled Pressable — SR doesn't know it's a button.
+4. **Decorative image not hidden** — SR reads "image" with no value.
+5. **Text in nested Pressable + Text not grouped** — SR reads each separately.
+6. **`accessibilityLabel` doesn't include state** — "Save" instead of "Save, disabled".
+7. **Modal opens, focus stays on the trigger** — SR user lost.
+8. **No `setAccessibilityFocus` after route change** — same.
+9. **Scroll target not focused after auto-scroll** — SR doesn't follow scroll.
+10. **Long async load with no announcement** — user thinks app froze.
+11. **`maxFontSizeMultiplier` not set on tight UI** — Dynamic Type breaks layout.
+12. **Color-only state (selected tab, error)** — color blind users miss it.
+
+## Source Material
+
+- React Native — *Accessibility*: <https://reactnative.dev/docs/accessibility>
+- Apple — *Accessibility on iOS*: <https://developer.apple.com/accessibility/>
+- Android — *Accessibility*: <https://developer.android.com/guide/topics/ui/accessibility>
+- Callstack — *Accessible mobile apps* blog series.
+- Shopify FlashList docs — recycler-aware accessibility patterns.

core/skills/a11y/references/screen-reader-testing.md

@@ -0,0 +1,190 @@
+# Screen Reader Testing — Practical Protocol
+
+The shortest path to genuine accessibility confidence: turn on a screen reader, complete the critical flows eyes-closed, fix every place you got stuck.
+
+## Setup — Per Platform
+
+### macOS — VoiceOver
+
+- **Toggle**: `Cmd + F5` (or triple-tap Touch ID).
+- **VO key**: `Caps Lock` (a.k.a. "VO"). Press with arrows to navigate.
+- **Quick start**:
+  - VO + A → read all
+  - VO + Right Arrow → next item
+  - VO + Space → activate
+  - VO + Shift + Down Arrow → enter group
+  - Tab → next interactive
+  - VO + U → rotor (jump by headings, links, etc.)
+
+### iOS — VoiceOver
+
+- **Toggle**: Settings → Accessibility → VoiceOver. OR triple-press the home/side button (Settings → Accessibility → Accessibility Shortcut).
+- **Gestures**:
+  - Single tap → focus + announce
+  - Double tap → activate
+  - Swipe right / left → next / previous element
+  - Two-finger swipe up → read all from top
+  - Three-finger swipe → scroll
+  - Two-finger Z (rotor scrub) → cycle reading mode
+- **Rotor**: two-finger twist → switch between Words / Characters / Headings / Links / etc.
+
+### Windows — NVDA (free, recommended)
+
+- **Install**: <https://www.nvaccess.org/download/>
+- **Toggle**: launches in system tray; `Insert + Q` to quit.
+- **NVDA key**: `Insert` (configurable to Caps Lock).
+- **Quick start**:
+  - NVDA + Down → read all
+  - Down arrow → next line
+  - Tab → next interactive
+  - H → next heading (NVDA browse mode)
+  - F → next form field
+  - K → next link
+  - NVDA + Space → toggle Browse / Focus mode
+
+### Android — TalkBack
+
+- **Toggle**: Settings → Accessibility → TalkBack. Or hold both volume buttons (Settings → Accessibility → Volume key shortcut).
+- **Gestures**:
+  - Tap once → focus + announce
+  - Double-tap → activate
+  - Swipe right / left → next / previous
+  - Swipe down + right → open TalkBack menu
+  - Two-finger swipe → scroll
+
+### Chrome — ChromeVox (dev only)
+
+- Extension; not real VO/NVDA. OK for quick checks; don't ship-test on it alone.
+
+## The Test Protocol
+
+For each critical flow: **complete the entire flow with the screen on, but don't look at it.** If you get stuck or can't complete, that's a bug.
+
+### Flow 1: Sign-in
+
+- Launch app → screen reader announces page title.
+- Find the email field via swipe or rotor.
+- Type email (use keyboard / external keyboard preferred).
+- Find password field, type.
+- Find sign-in button, activate.
+- On success → land on home; SR announces home page title.
+- On failure → SR announces error inline.
+
+**Common failures**:
+- Inputs without labels → SR reads "edit text" without context.
+- Errors not announced → user submits, hears nothing, doesn't know.
+- Sign-in button activates but loading state isn't announced → user re-taps.
+
+### Flow 2: Main Navigation
+
+- Tab / swipe through nav items at the top.
+- SR announces "Home, tab, 1 of 3 selected" / "Lessons, tab" / etc.
+- Activate each tab; SR announces new context.
+
+**Common failures**:
+- Tab role missing → SR reads as plain button.
+- Selected state not announced.
+- Tab change doesn't refocus content area.
+
+### Flow 3: List Browse + Item Open
+
+- Scroll list with SR.
+- SR reads each item including state ("Hexagons, completed" / "Setup, not started").
+- Activate one.
+- Detail screen opens; SR announces title.
+
+**Common failures**:
+- List items don't include state.
+- After tapping, SR stays on the list (no focus shift).
+- Long list never reaches the end with SR (focus loss).
+
+### Flow 4: Form Submission
+
+- Open form.
+- SR announces required fields.
+- Fill all fields; on each, SR re-announces validity.
+- Submit.
+- On error → SR announces summary and focuses first invalid field.
+- On success → SR announces success.
+
+**Common failures**:
+- Required not announced.
+- Errors visible but not announced.
+- Focus stays on submit button after error.
+
+### Flow 5: Modal / Dialog
+
+- Trigger modal.
+- SR announces modal title + role.
+- Focus is inside modal (verify by trying to navigate out — Esc / back closes).
+- Cancel and Confirm buttons reachable.
+- After close, focus returns to trigger.
+
+**Common failures**:
+- Focus stays on the page behind.
+- No focus trap → user navigates to underlying content.
+- Close doesn't return focus.
+
+### Flow 6: Settings + Sign-out
+
+- Reach settings via main nav.
+- Toggle a setting (e.g., notifications).
+- SR announces new state ("On" / "Off").
+- Sign out button activates; redirected to sign-in.
+
+## Mobile-Specific Flows
+
+For RN apps, ALSO check:
+
+### Push Notification Tap → App Opens to Specific Screen
+
+- Receive a notification.
+- Tap with screen reader on.
+- App opens; SR announces the destination screen title.
+- Back goes to the screen you'd expect (typically Home).
+
+### Background → Foreground
+
+- App in foreground.
+- Switch to another app, come back.
+- SR re-announces context (page title) on resume.
+
+### Biometric Prompt
+
+- Trigger Face ID / Touch ID / fingerprint.
+- SR announces the prompt purpose ("Use Face ID to sign in").
+- Cancel works; falls back to passcode.
+
+### Modal from Notification
+
+- Tap in-app notification.
+- Modal opens; SR announces and focuses correctly.
+
+## Common Issues + How to Spot Them
+
+| Symptom | Likely cause |
+|---|---|
+| SR reads "button" with no context | Missing `accessibilityLabel` / `aria-label` |
+| SR reads filename ("logo.png") | Missing `alt` / `accessibilityLabel` on image |
+| SR skips an element you can see | Element has `aria-hidden` / `accessibilityElementsHidden` set wrongly |
+| SR reads same text twice | Both visible Text and aria-label are set |
+| Cannot reach element via swipe | Element is not focusable or `tabindex="-1"` blocks |
+| Activated but nothing happens | Button doesn't have proper role; `onPress` not wired |
+| User stuck after page change | No focus management on route change |
+| Live update silent | Missing `aria-live` / `accessibilityLiveRegion` / `announceForAccessibility` |
+| Tab order is weird | DOM doesn't match visual; explicit `tabindex` overriding |
+
+## Test Cadence
+
+- **Per-feature PR**: dev runs SR briefly on the new screen.
+- **Per-sprint**: QA runs SR through one critical flow start-to-finish.
+- **Per-release**: full SR test of all critical flows on iOS + Android.
+- **Annual**: external accessibility audit (good practice; legal cover in regulated industries).
+
+## Source Material
+
+- Apple — *Test Accessibility on Your Device with VoiceOver*: <https://developer.apple.com/library/archive/technotes/TestingAccessibilityOfiOSApps/TestAccessibilityonYourDevicewithVoiceOver/TestAccessibilityonYourDevicewithVoiceOver.html>
+- Android — *Test your app's accessibility*: <https://developer.android.com/guide/topics/ui/accessibility/testing>
+- WebAIM — *VoiceOver Quick Reference*: <https://webaim.org/articles/voiceover/>
+- WebAIM — *NVDA Quick Reference*: <https://webaim.org/articles/nvda/>
+- *Empathy Lab* — disability simulation tools at Slack / Google for periodic team practice.