cometchat-a11y— agent skill

Ground truth: the UI Kit components are documented as designed targeting WCAG 2.1 Level AA with keyboard navigation built in (the Angular component docs state this most explicitly; note the docs' own caveat that full conformance still requires manual testing — do not assert a blanket AA/VPAT claim to the user without it). Treat AA as the design target, not a certified guarantee. Accessibility failures in a CometChat app are almost always host-side regressions — global CSS, a broken focus order, a container with no accessible name, or motion that ignores the user's preference. Verify component-level a11y claims against the component's own docs page (cometchat-<family>-components → docs-map); this skill owns the host-side discipline the kit can't control.

Use this skill when

An accessibility review (WCAG / Section 508 / ADA / EN 301 549), a screen-reader or keyboard complaint, or "make our chat accessible." Procurement for public-sector, education, healthcare and large enterprises requires this.

Start from what the kit gives you

The kit ships accessible components: keyboard-operable lists/composer, focus handling, and semantics designed targeting AA (the design target — not a certified guarantee; see above). On web it sets ARIA roles and names itself — the conversation/user rosters render as a labelled listbox and manage roving focus — so don't override or strip them. Your job is to not break it and to make the surrounding app equally accessible. Two rules first:

1. Don't let global CSS leak into the `.cometchat` subtree (web) — a global outline:none, a low-contrast override, a text-align/flex reset, or a Tailwind base can strip focus rings or break contrast the kit set correctly. Scope your resets away from the kit (RULES.md → CSS isolation).
2. Give the chat container a real, labelled home — a sized region (a11y needs a visible, non-collapsed surface too) with an accessible name (e.g. an aria-label/landmark on web, an accessibility label on native) so screen-reader users can find and enter it.

The checklist (host-side)

• Keyboard: every path reachable and operable by keyboard — open a conversation, type, send, open thread, close. Don't trap focus; return focus sensibly when a panel/dialog closes. Don't remove focus outlines; if you restyle them, keep a visible focus indicator.
• Screen reader: the surface and its regions have accessible names; your own buttons around the kit have labels (not icon-only with no aria-label/accessibility label). New-message announcements: verify the kit's live-region behavior on your target reader (VoiceOver/NVDA/TalkBack) and don't suppress it with aria-hidden on an ancestor.
• Contrast: if you theme the kit (cometchat-<family>-customization), keep text/UI contrast at AA (4.5:1 text, 3:1 large text/UI). Check both light and dark themes — a brand color that passes on light can fail on dark.
• Reduced motion: honor prefers-reduced-motion (web) / the OS "reduce motion" setting (native) in any animation you add around the chat; don't force motion the user opted out of.
• Text scaling / zoom: the surface must remain usable at 200% zoom / large Dynamic Type — don't cap font sizes or clip at large text.
• RTL: direction-correct for RTL locales (pairs with cometchat-i18n).
• Targets: your custom controls meet the minimum touch-target size; don't shrink the kit's.

Calls accessibility (if you use calling)

• Request camera/mic with clear, user-visible prompts and reasons.
• Provide accessible labels for call controls you add (mute, end, camera).
• Where available, surface captions/transcription; ensure incoming-call UI is announced and keyboard/AT-operable.

Test it

• Automated (web): run axe/Lighthouse on the chat screen — fix contrast, missing names, and ARIA misuse it flags. (Automated tools catch ~a third of issues; do the manual pass too.)
• Manual: tab through the whole flow with the mouse unplugged; drive it with VoiceOver / NVDA / TalkBack; zoom to 200%; toggle reduced motion; switch to dark. Fix what breaks in YOUR wiring; if a genuine kit-component gap appears, verify against the component docs and report it (don't hand-patch kit internals).

Common pitfalls

1. Global CSS stripping focus rings or contrast inside .cometchat — scope resets away.
2. Icon-only custom buttons with no label — add accessible names.
3. Unlabelled, collapsed, or unreachable chat container — size it and name it.
4. Animations ignoring reduced-motion.
5. Contrast checked in one theme only — check light and dark.
6. Assuming automated tools are enough — they miss keyboard/reader flow; test manually.

Verify it works

The chat flow is fully keyboard-operable with a visible focus indicator · a screen reader announces the surface, messages, and your controls · contrast passes AA in light and dark · the UI holds at 200% zoom / large type · reduced-motion is honored · RTL mirrors correctly · axe/Lighthouse on the chat screen is clean of contrast/name/ARIA errors.