@cometchat/skills 4.1.0 → 4.2.0

package/skills/cometchat-a11y/SKILL.md

@@ -0,0 +1,476 @@
+---
+name: cometchat-a11y
+description: Accessibility (a11y) for CometChat UI Kit integrations across all families — React, React Native, Angular, Android (V5/V6), iOS, Flutter. Covers WCAG 2.1 AA targets, keyboard navigation in chat, screen reader announcements (live regions for new messages), color contrast, focus management on call screens, motion-reduction support, and the cross-family checks that catch the common production a11y bugs. Cross-family — applies wherever the agent is checking accessibility.
+license: "MIT"
+compatibility: "All CometChat UI Kit families v4.x / v5.x / v6.x"
+allowed-tools: "shell, file-read, file-search, file-list, ask-user"
+metadata:
+  author: "CometChat"
+  version: "4.0.0"
+  tags: "cometchat a11y accessibility wcag aa keyboard screen-reader voiceover talkback aria live-region focus-management contrast prefers-reduced-motion cross-family"
+---
+
+## Purpose
+
+Accessibility for CometChat integrations. Out-of-the-box, the UI Kit components are mostly accessible — the kit's own buttons, inputs, and lists ship with semantic markup. Production gaps appear in the wiring **around** the kit: custom call surfaces, navigation, focus management on screen transitions, and contrast in custom themes.
+
+Target: **WCAG 2.1 AA**. The skill writes code that meets this baseline.
+
+---
+
+## The five gaps that trip integrations (any family)
+
+1. **Color contrast in custom themes.** A brand color picked for "looks nice in the brand book" may be 3.2:1 against the text — fails AA's 4.5:1 minimum.
+2. **Focus management on chat screen entry.** Tab/screen reader user lands on the chat screen but focus stays on the previous trigger button. They have to manually navigate into the message list every time.
+3. **No live region announcement for new messages.** Screen reader users don't know a new message arrived unless they navigate the message list and hear the new item.
+4. **Keyboard-only users can't navigate the conversation list.** Click handlers bound to `<div>` instead of `<button>` skip keyboard events.
+5. **Reduced-motion users see decorative animations.** Typing-indicator dots, message bubble entrance animations, transition effects — should respect `prefers-reduced-motion`.
+
+This skill addresses each one across families.
+
+---
+
+## 1. Color contrast — the theme audit
+
+CometChat themes are CSS variables (web/RN) or color tokens (native/Flutter). Override a single color and you might fail AA.
+
+### Web / Angular — CSS variable contrast check
+
+```ts
+// scripts/check-contrast.ts (run in CI or as a one-shot)
+function contrastRatio(hex1: string, hex2: string): number {
+  const luminance = (hex: string) => {
+    const rgb = hex.match(/\w\w/g)!.map(c => parseInt(c, 16) / 255).map(c =>
+      c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+    );
+    return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2];
+  };
+  const l1 = luminance(hex1);
+  const l2 = luminance(hex2);
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+
+// Pull the values from your CSS variables
+const fg = getComputedStyle(document.documentElement).getPropertyValue("--cometchat-text-color").trim();
+const bg = getComputedStyle(document.documentElement).getPropertyValue("--cometchat-background-color").trim();
+const ratio = contrastRatio(fg, bg);
+if (ratio < 4.5) {
+  console.warn(`Text/background contrast ${ratio.toFixed(2)}:1 fails WCAG AA (need ≥4.5:1)`);
+}
+```
+
+In CI, add this to your test suite. The skill writes a starter version into `tests/a11y/contrast.test.ts`.
+
+### React Native / native / Flutter — manual audit at theme-design time
+
+Use a contrast-checker tool (browser extensions, https://webaim.org/resources/contrastchecker/) on the theme tokens before shipping. There's no runtime DOM to audit on native.
+
+The kit's default theme tokens pass AA. Custom palettes need the audit.
+
+**Common fail:** brand purple #6750A4 against white background = 6.6:1 (passes). Same purple against `#F0F0F0` light gray = 5.7:1 (passes). Same purple against `#999999` muted gray = 2.8:1 (FAILS). Watch for muted backgrounds in dark-mode toggles, secondary buttons, and "subtle" surfaces.
+
+---
+
+## 2. Focus management on chat screen entry
+
+When the user navigates to a chat screen (clicked a conversation, opened the chat tab, accepted a deep link), focus should land on a meaningful control — usually the message composer or the latest message.
+
+### React (web)
+
+```tsx
+import { useEffect, useRef } from "react";
+
+export function ChatScreen() {
+  const composerRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    // After mount + animations, focus the composer
+    const timer = setTimeout(() => {
+      composerRef.current?.focus();
+    }, 100);
+    return () => clearTimeout(timer);
+  }, []);
+
+  return (
+    <div>
+      <CometChatMessageHeader />
+      <CometChatMessageList />
+      <CometChatMessageComposer ref={composerRef} />
+    </div>
+  );
+}
+```
+
+The kit's `CometChatMessageComposer` accepts a forwarded ref in v6; if not, query for the input via `composerRef.current?.querySelector("input, [contenteditable]")?.focus()`.
+
+### React Native
+
+```tsx
+import { useRef, useEffect } from "react";
+import { findNodeHandle, AccessibilityInfo } from "react-native";
+
+export function ChatScreen() {
+  const composerRef = useRef(null);
+
+  useEffect(() => {
+    const handle = findNodeHandle(composerRef.current);
+    if (handle) {
+      AccessibilityInfo.setAccessibilityFocus(handle);
+    }
+  }, []);
+
+  return (
+    <View>
+      <CometChatMessageHeader />
+      <CometChatMessageList />
+      <CometChatMessageComposer ref={composerRef} />
+    </View>
+  );
+}
+```
+
+### Angular
+
+```ts
+@Component({...})
+export class ChatComponent implements AfterViewInit {
+  @ViewChild("composer") composer!: ElementRef;
+
+  ngAfterViewInit() {
+    setTimeout(() => this.composer.nativeElement.focus(), 100);
+  }
+}
+```
+
+### Native Android (Kotlin)
+
+```kotlin
+override fun onResume() {
+  super.onResume()
+  composerView.requestFocus()
+  composerView.sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_FOCUSED)
+}
+```
+
+### Native iOS (Swift)
+
+```swift
+override func viewDidAppear(_ animated: Bool) {
+  super.viewDidAppear(animated)
+  UIAccessibility.post(notification: .screenChanged, argument: composerView)
+}
+```
+
+### Flutter
+
+```dart
+final FocusNode _composerFocus = FocusNode();
+
+@override
+void initState() {
+  super.initState();
+  WidgetsBinding.instance.addPostFrameCallback((_) {
+    _composerFocus.requestFocus();
+  });
+}
+
+// Then on the composer widget: focusNode: _composerFocus
+```
+
+---
+
+## 3. Live region for new messages
+
+Screen reader users need an audible announcement when a new message arrives — otherwise they have to navigate to the message list and re-read it.
+
+### Web / Angular — ARIA live region
+
+```html
+<!-- A visually-hidden region that screen readers announce -->
+<div
+  aria-live="polite"
+  aria-atomic="true"
+  style="position: absolute; left: -9999px; height: 1px; width: 1px; overflow: hidden;"
+  id="message-announcer"></div>
+```
+
+```ts
+// Listen for new messages and announce
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+
+const listenerId = "a11y-message-announcer";
+CometChat.addMessageListener(listenerId, new CometChat.MessageListener({
+  onTextMessageReceived: (msg: CometChat.TextMessage) => {
+    const senderName = msg.getSender().getName();
+    const text = msg.getText();
+    const region = document.getElementById("message-announcer");
+    if (region) {
+      // Clearing first ensures the same text re-announces
+      region.textContent = "";
+      setTimeout(() => {
+        region.textContent = `New message from ${senderName}: ${text}`;
+      }, 100);
+    }
+  },
+}));
+```
+
+`aria-live="polite"` waits for the user to finish speaking before announcing. Use `aria-live="assertive"` only for urgent messages (like incoming calls) — too aggressive for chat.
+
+### React Native
+
+```ts
+import { AccessibilityInfo } from "react-native";
+
+CometChat.addMessageListener(listenerId, new CometChat.MessageListener({
+  onTextMessageReceived: (msg) => {
+    const text = `New message from ${msg.getSender().getName()}: ${msg.getText()}`;
+    AccessibilityInfo.announceForAccessibility(text);
+  },
+}));
+```
+
+### Native Android / iOS / Flutter
+
+Each platform has an equivalent — Android `View.announceForAccessibility(text)`, iOS `UIAccessibility.post(notification: .announcement, argument: text)`, Flutter `SemanticsService.announce(text, TextDirection.ltr)`. Same shape; the SDK callback is the trigger.
+
+---
+
+## 4. Keyboard navigation
+
+The kit's components are keyboard-accessible by default. Custom wrapping is what breaks it.
+
+### Anti-pattern — `<div onClick>` for clickable items
+
+```tsx
+// ✗ WRONG — keyboard users can't activate
+<div onClick={() => openConversation(c)}>{c.name}</div>
+
+// ✓ RIGHT — `<button>` is keyboard + screen-reader native
+<button onClick={() => openConversation(c)}>{c.name}</button>
+
+// ✓ ALSO RIGHT — div with explicit ARIA + keyboard handlers
+<div
+  role="button"
+  tabIndex={0}
+  onClick={() => openConversation(c)}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      openConversation(c);
+    }
+  }}
+>
+  {c.name}
+</div>
+```
+
+### Skip links
+
+For long conversation lists, add a skip-to-message-composer link:
+
+```html
+<a href="#message-composer" class="skip-link">Skip to message composer</a>
+```
+
+```css
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  z-index: 999;
+}
+.skip-link:focus {
+  left: 0;
+  top: 0;
+  background: white;
+  padding: 8px;
+}
+```
+
+The kit's components already include skip links where applicable; custom wrapping should preserve them.
+
+### Keyboard shortcuts
+
+For productivity apps:
+
+```ts
+useEffect(() => {
+  const handler = (e: KeyboardEvent) => {
+    // Cmd/Ctrl + K → focus search
+    if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+      e.preventDefault();
+      searchRef.current?.focus();
+    }
+    // Escape → close any open thread / modal
+    if (e.key === "Escape") {
+      closeOpenThread();
+    }
+  };
+  window.addEventListener("keydown", handler);
+  return () => window.removeEventListener("keydown", handler);
+}, []);
+```
+
+Document the shortcuts in your in-app help — discoverability matters.
+
+---
+
+## 5. Reduced motion
+
+Animations help most users; they cause physical discomfort or distraction for users with vestibular disorders, ADHD, or who simply prefer less movement. WCAG 2.1 AA requires honoring the OS preference.
+
+### Web / Angular — CSS
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Disable kit animations + your custom ones */
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### React Native
+
+```ts
+import { AccessibilityInfo } from "react-native";
+
+const [reduceMotion, setReduceMotion] = useState(false);
+
+useEffect(() => {
+  AccessibilityInfo.isReduceMotionEnabled().then(setReduceMotion);
+  const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduceMotion);
+  return () => sub.remove();
+}, []);
+
+// In animations
+<Animated.View
+  style={{
+    transform: [{ scale: reduceMotion ? 1 : animatedValue }],
+  }}
+/>
+```
+
+### Native iOS
+
+```swift
+let reduceMotion = UIAccessibility.isReduceMotionEnabled
+if !reduceMotion {
+  UIView.animate(withDuration: 0.3) { ... }
+} else {
+  // Apply final state without animation
+}
+```
+
+### Native Android
+
+```kotlin
+val reduceMotion = Settings.Global.getFloat(
+  contentResolver, Settings.Global.ANIMATOR_DURATION_SCALE, 1.0f
+) == 0.0f
+```
+
+### Flutter
+
+```dart
+final reduceMotion = MediaQuery.of(context).disableAnimations;
+```
+
+The skill defaults to wrapping the typing indicator + message-bubble entrance animations in reduce-motion guards. Other kit animations need similar treatment if you've customized them.
+
+---
+
+## Calls a11y
+
+Calls have specific a11y considerations beyond chat:
+
+1. **Focus on call screen entry → end-call button.** Avoids accidental hangup but ensures the user can quickly exit.
+2. **Announce incoming calls.** Live region (web/RN) or `UIAccessibility.post(.announcement)` (iOS) — "Incoming call from Alice."
+3. **Mute/end button labels.** "Mute microphone" not just "Mute" — clarify what's being toggled.
+4. **No flashing — recording indicator uses dot, not strobe.** WCAG 2.3 forbids more than 3 flashes/sec to prevent seizures.
+5. **Caption support if recording.** Production calling apps with live captioning hook in via the platform's speech-recognition API and overlay text on the call screen.
+
+---
+
+## Testing — automated + manual
+
+### Web automated
+
+```bash
+npm install --save-dev @axe-core/playwright
+```
+
+```ts
+import { test, expect } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+test("chat screen passes axe AA", async ({ page }) => {
+  await page.goto("/messages");
+  const results = await new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa"]).analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+### Native automated
+
+iOS: Xcode → Accessibility Inspector → Audit. Android: Accessibility Scanner app on a real device.
+
+### Manual
+
+- **Keyboard-only navigation** — unplug your mouse, complete a full chat flow. Tab through every control.
+- **VoiceOver (iOS) / TalkBack (Android) / NVDA (Windows) / VoiceOver (macOS)** — listen to the kit; verify announcements make sense.
+- **Browser zoom 200%** — kit should remain usable at 200% zoom on a 1280×720 viewport (WCAG 1.4.10 reflow).
+
+---
+
+## Anti-patterns
+
+1. **Custom themes without a contrast audit.** Brand colors silently fail AA.
+2. **`<div onClick>` for clickable items.** Keyboard users can't activate.
+3. **No live region for new messages.** Screen reader users miss messages.
+4. **Auto-playing video on call screen.** Some users browse with autoplay disabled — kit handles this; custom UI must too.
+5. **Focus stays on the trigger button after opening chat.** User has to manually re-navigate.
+6. **Ignoring `prefers-reduced-motion`.** Vestibular-disorder users get disoriented.
+7. **`aria-live="assertive"` for chat messages.** Interrupts the user mid-sentence; reserve for genuinely urgent (incoming call).
+8. **Skipping label specificity.** "Mute" alone is ambiguous; "Mute microphone" / "Unmute microphone" is clear.
+9. **Color-only signals.** "Read" status as just a checkmark color — add a visible text label for color-blind users.
+10. **No test coverage for a11y.** Regressions slip in. Automate the easy checks (axe-core); manual-test the rest per release.
+
+---
+
+## Verification checklist
+
+**Cross-family:**
+- [ ] Custom theme passes AA contrast (4.5:1 text, 3:1 large text + UI components)
+- [ ] Focus lands on a meaningful control on chat screen entry
+- [ ] Live region / accessibility announcement on new message receive
+- [ ] No `<div onClick>` patterns — buttons are buttons
+- [ ] `prefers-reduced-motion` / `isReduceMotionEnabled` honored for animations
+- [ ] Mute/end/camera labels are specific (not just "Mute")
+- [ ] Incoming-call announcement (`assertive` live region OR platform announcement API)
+- [ ] No flashing > 3 Hz (recording dot uses fade, not strobe)
+
+**Web/Angular:**
+- [ ] axe-core / Playwright a11y test in CI; passes WCAG AA tags
+- [ ] `<html lang="...">` set to current locale (consumes `cometchat-i18n` skill output)
+- [ ] Skip-to-composer link present
+- [ ] Browser zoom 200% smoke test
+
+**Native (Android/iOS/Flutter):**
+- [ ] TalkBack / VoiceOver smoke test on a real device
+- [ ] Reduced motion preference observed (`UIAccessibility.isReduceMotionEnabled`, etc.)
+- [ ] Focus restored on screen pop (not just push)
+- [ ] Touch targets ≥ 44×44 pt (iOS) / 48×48 dp (Android) — kit defaults pass; custom UI must too
+
+---
+
+## Pointers
+
+- `cometchat-i18n` — sister skill; `<html lang>` and screen-reader pronunciation of translated strings depend on locale set correctly
+- `cometchat-{family}-customization` — when customizing kit components, preserve their built-in a11y attributes
+- `cometchat-{family}-troubleshooting` — when a11y tools report issues that look kit-internal
+- WCAG 2.1 AA reference — https://www.w3.org/WAI/WCAG21/quickref/?levels=aa
+- Material Design accessibility — https://m3.material.io/foundations/accessible-design
+- Apple HIG accessibility — https://developer.apple.com/design/human-interface-guidelines/accessibility

package/skills/cometchat-android-v5/SKILL.md

@@ -3,7 +3,7 @@ name: cometchat-android-v5
 description: "Entry-point dispatcher for CometChat Android UI Kit v5. Detects project setup, understands what the dev is building, and routes to the right sub-skills."
 license: "MIT"
 compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
-allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"