# Cowork UI Kit — Accessibility Rules > Target: WCAG 2.1 AA. Mọi component phải pass 4 nguyên tắc POUR: **P**erceivable · **O**perable · **U**nderstandable · **R**obust. > > Cross-reference: [[feedback_ui_visual_proof_required]] (UI task BẮT BUỘC visual proof) · [[checklist-mobile.md]] § A11Y --- ## 1. Color contrast | Element | Min ratio | Token check | |---|---|---| | Body text trên surface | 4.5:1 | `--text` on `--surface` | | Large text 18pt+ bold (hoặc 24px regular) | 3:1 | display tokens | | UI component (button border, input border) | 3:1 | `--primary` on `--bg` | | Focus indicator | 3:1 vs adjacent | `--primary` on `--bg` | | Disabled element | No requirement | (visual only, vẫn cần đọc được context) | **Tool verify:** - Chrome DevTools → Inspect → Accessibility tab → Contrast ratio - 🌐 https://webaim.org/resources/contrastchecker/ - 🌐 https://www.tpgi.com/color-contrast-checker/ (APCA + WCAG2) **Common bug (đã xảy ra 2026-05-20):** Body thiếu class `aesthetic-warm` hoặc `aesthetic-dark` → `--text` undefined → fallback `canvastext` (đen mặc định OS) → render đen trên dark bezel = invisible. **Fix BẮT BUỘC:** ```html ``` --- ## 2. Keyboard navigation **Rule cứng:** - Mọi interactive element (button, link, input, custom widget) phải focusable qua Tab - Tab order theo visual flow (top-to-bottom, left-to-right trong LTR) - KHÔNG dùng `tabindex` > 0 (gây confused order) - `tabindex="0"` cho custom interactive elements (vd `
`) - `tabindex="-1"` cho elements focusable qua JS only (vd modal escape catch target) **Keyboard shortcuts chuẩn:** | Phím | Hành động | |---|---| | `Tab` / `Shift+Tab` | Navigate forward / backward | | `Enter` | Activate button / link / submit form | | `Space` | Toggle checkbox / switch / expand accordion / activate button | | `Esc` | Close modal / drawer / popover / tooltip | | `Arrow keys` | Navigate list / menu / tabs / radio group / slider | | `Home` / `End` | First / last item trong list hoặc menu | | `Page Up` / `Page Down` | Scroll lớn trong long list | --- ## 3. Focus management **Rule cứng:** - `:focus-visible` always visible (outline 2px + offset 2px tinted primary) - KHÔNG `outline: none` without replacement (vi phạm WCAG 2.4.7) - Modal / drawer open → trap focus inside, return focus to trigger on close - Skip-to-content link cho keyboard users (first focusable element, visually-hidden until focus) **Implementation chuẩn Cowork:** ```css .focusable:focus-visible, button:focus-visible, a:focus-visible, input:focus-visible, [role="button"]:focus-visible { outline: 2px solid var(--primary); outline-offset: 2px; border-radius: var(--radius-md); } /* Skip-to-content */ .skip-link { position: absolute; top: -40px; left: 0; background: var(--primary); color: var(--on-primary); padding: 8px 16px; z-index: 100; } .skip-link:focus { top: 0; } ``` --- ## 4. Touch targets **Rule cứng:** - Min **44×44 CSS px** (Apple HIG) / 48×48 dp (Material) — Cowork dùng 44px qua `--touch-min` - Spacing giữa touch targets ≥ 8px (accidental tap prevention) - Icon-only button cần `aria-label` mô tả action - Mobile breakpoint (375px) BẮT BUỘC, desktop có thể nhỏ hơn (32×32) nhưng nên giữ ≥40px cho consistency **Token:** ```css :root { --touch-min: 44px; --touch-spacing-min: 8px; } .btn-icon { min-width: var(--touch-min); min-height: var(--touch-min); } ``` --- ## 5. Screen reader support **ARIA roles cần thiết per component:** | Component | Required ARIA | |---|---| | Modal | `role="dialog"` + `aria-modal="true"` + `aria-labelledby` (point to title) | | Drawer | `role="dialog"` + `aria-label` hoặc `aria-labelledby` | | Toast (info) | `role="status"` + `aria-live="polite"` | | Toast (urgent / error) | `role="alert"` + `aria-live="assertive"` | | Tabs | container `role="tablist"` + each tab `role="tab"` + `aria-selected` + panel `role="tabpanel"` | | Accordion | trigger `aria-expanded` + `aria-controls` pointing to panel ID | | Tooltip | `role="tooltip"` + trigger có `aria-describedby` pointing to tooltip ID | | Loading spinner | `role="status"` + `aria-live="polite"` + visually-hidden text "Đang tải" | | Icon button | `aria-label` mô tả action (vd `aria-label="Đóng modal"`) | | Breadcrumb | `