Accessibility
Kikita UI treats accessibility as a review process, not a single automated pass. Docs examples should preserve native semantics and expose real component states.
These requirements apply to primitives, docs examples, and consumer verification pages.
| Name | Type | Default | Description |
|---|---|---|---|
| Semantics first | HTML | — | Prefer native elements and browser behavior before adding ARIA. |
| Keyboard | WCAG AA | — | Every interactive state must be reachable, operable, and escapable by keyboard. |
| Focus | Visible state | — | Focus indicators must remain visible and must not cause layout shift. |
| Contrast | WCAG AA | — | Text, icons, focus, disabled, invalid, selected, and loading states must remain distinguishable. |
A clean automated scan is only a smoke test. Do not mark a primitive fully audited without keyboard and assistive-technology review.
| Name | Type | Default | Description |
|---|---|---|---|
| DOM smoke | Automated | — | Catches broken ARIA references, duplicate ids, invalid roles, and unnamed controls. |
| Keyboard review | Manual | — | Verifies tab order, activation keys, escape behavior, and focus restoration. |
| Assistive technology | Manual | — | Uses a real screen reader or platform accessibility tool for names, roles, and states. |
| Visual review | Manual | — | Checks responsive layout, 200% zoom, reduced motion, forced colors, and contrast. |
Focus handling and required or invalid state follow one shared behaviour across the library.
- Every focusable part draws a solid 2px
outlinein--kui-color-focus, which stays visible in forced-colors mode. A ring drawn only withbox-shadowis gone, and--kui-input-focus-ringdefaults tonone. kui-fieldsetsaria-requiredfrom its merged required state on every control whose role supports it. A single radio and a slider are the documented exceptions.- Automatic focus (
kuiAutoFocus, OTPautoFocus) is opt-in and limited to places where focus on arrival is expected. - Safari on macOS does not focus a button when it is clicked with the mouse, so a modal surface opened by mouse has no trigger to return focus to on close. Focus returns to the trigger when the surface was opened with the keyboard; native dialog, Angular CDK and Angular Material behave the same way, and Kikita UI does not work around it. Test focus return in Safari by opening the surface with the keyboard.
- Right-to-left layouts are not supported in 2.0.
Nonessential motion, contrast and Windows High Contrast are part of every state-bearing component.
- Respect
prefers-reduced-motionfor nonessential animation. Essential motion has a non-motion cue, and focus, selected, invalid, disabled and loading states stay distinguishable without colour alone. - Control borders follow WCAG 1.4.11: a boundary that alone identifies a control (an input, a checkbox) reaches 3:1 in the default
strictcontrast profile. The opt-insoftprofile drops control borders below 3:1 and is documented as such, andprefers-contrast: moreselectsstrictwhile nodata-kui-contrastattribute is set. - The library ships forced-colors rules in
forced-colors.cssusing system colours, covering checked and indeterminate controls, Slider, Progress, selected cells, Tabs, Segmented, pressed Chip, Stepper and the charts. Browser emulation of forced colors only toggles the media query, so a real Windows pass is still needed. - Icons are drawn as inline SVG with
currentColor, so they take the system text colour. An icon drawn with a CSSmask-imageandbackground: currentColordisappears in Chromium in forced-colors mode. - Semi-transparent overlays and shadows are never the only way to communicate depth or modality.
Examples should use Kikita field wiring and native state attributes instead of compensating for broken markup with custom ARIA.
<kui-field label="Email" hint="Use your work address.">
<input kuiInput type="email" autocomplete="email" />
</kui-field>Record the actual level of review. Be explicit when only DOM smoke has run.
- DOM accessibility smoke has run for <primitive>, but real assistive-technology review is still pending.