--- name: axiomui-accessibility description: Use Axiom UI’s accessibility guidance to check keyboard focus, its visibility and its return when an overlay closes, target size and spacing, text and control contrast, meaning beyond color, underlined links in running text, heading levels, a click path for every drag, pausing content that moves on its own, field labels and input purpose, accessible authentication, chart alternatives, modal dismissal, reflow at 320 CSS px and reduced motion. Consult the sources on the linked rule page when checking a conformance claim. license: MIT metadata: author: Nischal Skanda homepage: https://axiomui.nischal.fyi source: https://github.com/RexO77/axiomUI group: domain --- # Axiom UI: Accessibility & inclusivity Follow a task with the input method or presentation the rule addresses. Close a dialog with Escape and note where focus lands, reorder a list without dragging, paste a sign-in code from the clipboard, or zoom to 400% at 1280px wide and check that nothing scrolls sideways. For a WCAG finding, identify the applicable success criterion, its level and exceptions, and record what happened on the tested path. ## How to use these rules 1. Find the rule that governs the decision in front of you. 2. Read the rule’s description and compare its example with the task, platform, language and state you are working on. 3. Test the failure the comparison illustrates. For a standard, verify the applicable requirement and its exceptions. For a design convention, judge the outcome with representative content and input. 4. Read the file on its Reasoning line when the case is ambiguous or high-stakes, or when you have to justify the choice. Cite the rule id and URL when you explain a change. Where the project already has a token or component for the decision, use it. When that token contradicts a rule, flag the conflict instead of quietly rewriting the system. ## Rules ### Keep keyboard focus visible (`a11y-1`) Keep a visible indicator on keyboard focus. A custom focus treatment should remain identifiable across the surfaces and display modes where the control appears. - Do: focus-visible:outline-2 outline-offset-2 - Don't: outline: none with no replacement - Reasoning: `references/rules/a11y-1.md` · https://axiomui.nischal.fyi/rules/a11y-1 ### Carry meaning beyond color (`a11y-2`) When color communicates an error, state or category, add a second cue someone can perceive without distinguishing the hues. For a detected form error, identify the field and describe the problem in text. - Do: Red text + error icon + message - Don't: Only a red border on the input - Reasoning: `references/rules/a11y-2.md` · https://axiomui.nischal.fyi/rules/a11y-2 ### Separate competing touch targets (`a11y-3`) Leave space between nearby actions when an unintended tap would be costly. An 8px gutter protects the particular miss shown here. WCAG sets size and spacing tests rather than one minimum gap for every button. - Do: Buttons: 8px gutter - Don't: Buttons: 0px gutter - Reasoning: `references/rules/a11y-3.md` · https://axiomui.nischal.fyi/rules/a11y-3 ### Offer a click or tap path for every drag (`a11y-4`) Offer clicks or taps for tasks such as reordering a list, moving cards between columns or setting a slider. A drag can be required when the drawn path itself is essential to the task. - Do: Drag handle + Move up / Move down - Don't: Drag handle only - Reasoning: `references/rules/a11y-4.md` · https://axiomui.nischal.fyi/rules/a11y-4 ### Choose heading levels by outline, not size (`a11y-5`) Choose heading levels from the page's section hierarchy. Style the headings independently so the visual sizes and the screen reader's heading list can both reflect the design. - Do: h1 Settings → h2 Billing → h3 Invoices - Don't: h1 Settings → h4 Billing → h4 Invoices - Reasoning: `references/rules/a11y-5.md` · https://axiomui.nischal.fyi/rules/a11y-5 ### Let people pause what moves or updates on its own (`a11y-6`) For nonessential content presented alongside other content, offer a way to pause, stop or hide automatic movement, blinking or scrolling that lasts more than five seconds. For automatic updates, offer a control at any interval. Adjusting the update frequency also works. - Do: Testimonial strip with Pause - Don't: Quote changes every 4s · no control - Reasoning: `references/rules/a11y-6.md` · https://axiomui.nischal.fyi/rules/a11y-6 ### Underline links in running text (`a11y-7`) Underline inline links so readers can spot them as they read. Navigation menus can use their layout and placement to identify links. - Do: p a { text-decoration: underline } - Don't: p a { text-decoration: none } · color only - Reasoning: `references/rules/a11y-7.md` · https://axiomui.nischal.fyi/rules/a11y-7 ### Return focus when an overlay closes (`a11y-8`) When an overlay closes, return keyboard focus to the control that opened it. If closing removes that control, such as when a row is deleted, focus the next logical control in the workflow. - Do: Esc → focus back on "Edit" - Don't: Esc, then Tab → focus restarts at "New project" - Reasoning: `references/rules/a11y-8.md` · https://axiomui.nischal.fyi/rules/a11y-8 ## Cross-listed from other domains These rules cover specific accessibility decisions in other domains. Check the conditions and exceptions in each rule before making a conformance finding. ### Keep scroll and focus targets clear of sticky headers (`layout-12`) Account for the height of sticky headers and footers in the scroll container. After an anchor jump or keyboard focus, the entire target should be visible. - From: Layout & spacing - Do: scroll-padding-top: 64px - Don't: scroll-padding-top: 0px - Reasoning: `references/rules/layout-12.md` · https://axiomui.nischal.fyi/rules/layout-12 ### Give essential control edges enough contrast (`color-6`) When a boundary is needed to identify an enabled control, WCAG AA requires at least 3:1 contrast against its adjacent color. A decorative divider may be quieter. Check the actual pair in each theme. - From: Color & depth - Do: input border: neutral-500 · divider: neutral-200 - Don't: input border: neutral-100 · divider: neutral-200 - Reasoning: `references/rules/color-6.md` · https://axiomui.nischal.fyi/rules/color-6 ### Accessible contrast ratios (`color-9`) For WCAG AA, ordinary text needs at least 4.5:1 contrast. Large text qualifies at 3:1. Measure unrounded values against the actual background, including overlays and images behind the text. - From: Color & depth - Do: #737373 on #ffffff (4.7:1) - Don't: #aaaaaa on #ffffff (2.3:1) - Reasoning: `references/rules/color-9.md` · https://axiomui.nischal.fyi/rules/color-9 ### Make overlay dismissal discoverable (`comp-12`) Give dismissible dialogs a visible Close or Cancel action and support Escape. Choose outside-click behavior according to the cost of an accidental dismissal. - From: Components & actions - Do: X button + backdrop close + Esc key - Don't: No close button, only backdrop click - Reasoning: `references/rules/comp-12.md` · https://axiomui.nischal.fyi/rules/comp-12 ### Make the chart’s question answerable in text (`comp-13`) Identify what the chart shows and describe the comparison readers need. When the task calls for individual values, offer them in a labeled table or another accessible representation that follows the selected period. - From: Components & actions - Do: Summarize the trend and offer the monthly counts - Don't: Leave the trend and counts in the bars alone - Reasoning: `references/rules/comp-13.md` · https://axiomui.nischal.fyi/rules/comp-13 ### Navigate with links, act with buttons (`comp-14`) If activating a control takes someone to another URL, make it a link with an href, however it is styled. The browser then offers Open in new tab and Copy link, and shows the address before the click. Keep buttons for actions that change something on the current page. - From: Components & actions - Do: View invoice - Don't: