accessibility-inclusive-design

Imported from hueyexe/frontend-agent-skills (accessibility-inclusive-design/SKILL.md). Install upstream with npx skills add hueyexe/frontend-agent-skills --skill accessibility-inclusive-design. Copyright stays with the author (MIT).

Accessibility Inclusive Design

Purpose

Help an agent design and critique interfaces that are accessible, inclusive, keyboard-friendly, screen-reader-aware, and usable by diverse people.

Use this skill to turn accessibility into normal design practice. Treat accessibility as part of product quality, not as a late QA task or legal checkbox.

When to use this skill

Use this skill when the user asks for help with:

• UI, UX, frontend implementation, product design, or design-system work.
• Accessibility critique, audit, remediation, redesign, or conformance planning.
• Forms, navigation, menus, filters, product lists, media, tables of contents, dynamic loading, or interactive widgets.
• Keyboard interaction, focus management, screen reader behavior, semantic HTML, ARIA, color contrast, typography, responsive behavior, or inclusive content.
• Design defaults for users with visual, auditory, motor, cognitive, language, device, bandwidth, or situational constraints.

When not to use this skill

Do not use this skill as the primary skill for:

• Broad UX research planning unrelated to inclusion or accessibility.
• Brand-only visual exploration where no interface behavior, content, or user task is being designed.
• Backend-only architecture with no user-facing accessibility impact.
• Legal advice. You may identify accessibility risk and recommend standards-aligned review, but do not make legal determinations.

Core principles

1. Design for real diversity, not an average user. People differ in ability, technology, language, attention, literacy, device, bandwidth, and environment. Avoid solutions that only work for the designer’s setup.
2. Start with purpose and user task. Clear purpose reduces complexity, cognitive load, and implementation waste.
3. Prefer native semantics and standard web behavior. Use HTML elements that already include roles, states, keyboard behavior, and platform integration before recreating behavior with JavaScript and ARIA.
4. Make structure machine-readable. Headings, landmarks, lists, labels, form controls, alt text, captions, and document metadata are part of the interface.
5. Progressively enhance. Begin with meaningful content and working HTML. Add CSS and JavaScript only when they improve the experience without destroying the baseline.
6. Give users control. Do not block zoom, trap focus, autoplay media, force motion, impose infinite scroll, or decide display preferences when user choice is feasible.
7. Use convention as an accessibility feature. Familiar navigation, link styling, button affordance, form patterns, and predictable placement reduce cognitive effort.
8. Make hidden state explicit. If something expands, loads, errors, becomes selected, or changes dynamically, communicate the state visually and programmatically.
9. Content is part of design. Clear headings, descriptive links, plain language, usable labels, and helpful errors are accessibility features.
10. Test beyond automation. Automated checks help, but keyboard walkthroughs, screen reader checks, device/browser testing, and disabled participant feedback uncover issues automation misses.

See references/principle-cards.md for each principle as a reusable card.

Default recommendations

Use these defaults unless the user provides stronger product context or constraints.

Required user questions

Do not ask users to approve routine best practices. Apply the default and explain it.

Ask one focused question only when the answer affects a material recommendation. Use a question tool or equivalent when available.

Ask when:

1. Regulatory or organizational target is unknown and compliance is central.
   • Default: WCAG AA-level design and current product standard.
2. Audience, assistive technologies, language, geography, or platform materially changes the design.
   • Default: broad web audience, keyboard and screen reader support, responsive browser behavior.
3. A component may need a custom interaction pattern rather than native HTML.
   • Default: native HTML or simpler pattern.
4. Brand voice conflicts with clear labels, plain language, or recognizable affordances.
   • Default: clear task language with brand personality secondary.
5. A dynamic behavior could change user control, focus, or orientation.
   • Default: explicit user-triggered action with visible and programmatic feedback.
6. The user requests a legal/conformance claim.
   • Default: provide design/implementation recommendations and recommend expert/legal validation.

Use the question-tool-ready prompts in references/decision-prompts.md.

Workflow

A. Critique existing UI, screenshots, code, or flows

Inspect in this order:

1. Task and purpose
   • What is the user trying to do?
   • Is the primary path obvious and unnecessary complexity removed?
2. Structure and semantics
   • Are document title, language, headings, landmarks, lists, controls, labels, and relationships meaningful?
   • Does source order match reading and focus order?
3. Keyboard and focus
   • Can every interactive element be reached, seen, operated, and exited by keyboard?
   • Are focus states visible and not removed?
   • Is focus managed after disclosures, in-page links, validation, and dynamic loading?
4. Interaction behavior
   • Are controls recognizable?
   • Are states and changes communicated visually and programmatically?
   • Does the interface preserve user control?
5. Content and labels
   • Are headings, links, form labels, button names, instructions, and errors clear out of context?
   • Is brand language secondary to task clarity?
6. Visual presentation
   • Are contrast, text size, line height, measure, spacing, and grouping readable?
   • Is information conveyed by more than color, position, or sound alone?
7. Forms and errors
   • Are labels persistent and associated?
   • Are required fields clear?
   • Are errors announced, located near the user’s work, and actionable?
8. Media and alternatives
   • Are images, icons, video, audio, and non-text cues available through appropriate alternatives?
9. Responsive and environmental resilience
   • Does it work with zoom, text resizing, narrow/wide viewports, slow networks, disabled CSS/JS, and user font/color preferences?
10. Testing and maintainability

• Are accessibility checks embedded in the component/design-system workflow?

Output critique as:

• Severity: blocker, major, moderate, minor.
• Who is affected: keyboard users, screen reader users, low-vision users, cognitive load, motor access, language/literacy, low bandwidth, etc.
• Why it matters.
• Recommended fix.
• Implementation note.
• Test to verify.

B. Create or improve a design

Proceed in this order:

1. Clarify the feature and user task.
   • If missing, ask one focused question and propose the default.
2. Choose the simplest useful pattern.
   • Prefer native controls and familiar conventions.
3. Establish structure.
   • Define headings, regions, reading order, navigation, form groups, and content relationships before styling.
4. Write labels and content.
   • Use direct, descriptive, context-independent copy.
5. Define interaction and state.
   • Specify keyboard behavior, focus order, visible focus, state announcements, loading, errors, and recovery.
6. Apply visual design.
   • Tune typography, contrast, spacing, grouping, affordance, and responsive behavior.
7. Add progressive enhancement.
   • Add JavaScript only after the HTML baseline works.
8. Validate edge cases.
   • Test zoom, long content, localization, RTL if relevant, slow network, disabled CSS/JS, and alternative input.
9. Explain decisions.
   • Tie recommendations to user impact, not just standards.

Decision framework

When choosing a pattern, prefer the first option that satisfies the user task:

1. No interaction needed: Use semantic static content.
2. Native interaction exists: Use the native element.
3. Native interaction can be styled: Keep native behavior and style labels/containers rather than replacing controls.
4. Progressive enhancement is enough: Keep the baseline form/link behavior and enhance with JS.
5. Custom interaction is unavoidable: Implement the full pattern: role, name, state, keyboard behavior, focus management, visible affordance, instructions, and tests.
6. The pattern hides content or takes control: Reconsider. Ask whether the product context truly requires it.
7. The pattern depends on user preferences: Provide choice or respect browser/OS settings.

Practical rules

Document and page structure

• Include a valid doctype.
• Declare the page language with lang; declare dir for right-to-left languages.
• Use one meaningful document <title> that names the current page or result state.
• Use one primary <main> region for the unique page content.
• Provide a skip link to main content for sighted keyboard users.
• Use headings for structure, not visual size. Do not skip heading levels just to achieve a style.
• Use lists for grouped navigation and grouped content.
• Ensure source order makes sense when read top-to-bottom.

Navigation and wayfinding

• Put primary navigation in a nav landmark.
• Label multiple navigation landmarks uniquely, such as “site” and “contents”.
• Keep familiar placement and recognizable shapes.
• Indicate the current page/section with more than color.
• For current-page links, avoid redundant reload behavior; use a same-page link to main content when appropriate, or a clear described current state.
• Use tables of contents for long pages instead of complex dropdown submenus when the goal is section navigation.

Buttons, links, and controls

• Use button for actions and a href for navigation.
• Do not use a clickable div or span when a native element fits.
• Do not remove button or link affordance without replacing it with an equally clear affordance.
• Icon-only controls need an accessible name. Prefer visible text when space allows.
• Keep touch targets generous and separated; use full-row vertical navigation on narrow touch viewports.
• Invisible elements must not be focusable.

Keyboard and focus

• Every actionable control must be reachable by keyboard.
• Every focused control must have a visible focus indicator.
• Do not set outline: none unless you provide a stronger replacement.
• Do not use positive tabindex to rearrange navigation. Fix the source order instead.
• Use tabindex="-1" only for programmatic focus targets such as in-page headings after smooth scroll or newly loaded content.
• When JavaScript hijacks native behavior, restore focus movement, URL updates, and expected keyboard behavior.

Forms

• Every input has a persistent, associated label.
• Placeholder text is only a hint; never use it as the only label.
• Use fieldset and legend when they clarify multiple related controls; avoid them when they add noise without benefit.
• Ask only for information needed to complete the task.
• Mark required fields visibly and programmatically.
• Put errors near the user’s current work, not only at the top of the page.
• Separate “there are errors” from “how to fix this field.”
• Use aria-invalid and aria-describedby for invalid fields and remediation text when appropriate.
• Use live regions for asynchronous form or loading feedback, but do not over-announce every keystroke.
• Debounce live validation and avoid noisy, aggressive validation.
• Prefer “show password” to duplicate password fields unless policy prevents it.

Dynamic content

• Prefer explicit actions such as “Apply filters” and “Load more” when changes are consequential.
• Announce loading and completion to screen readers.
• Prevent duplicate loading actions while requests are pending.
• After new content loads, move focus to the first meaningful new item when the trigger is displaced.
• Avoid infinite scroll by default.
• If using live regions, choose polite/assertive behavior based on urgency and avoid interrupting routine reading unless necessary.

Visual design and readability

• Use real content early. Do not design only with idealized placeholder text.
• Choose typefaces for legibility, character distinction, language support, and required weights/styles.
• Use relative units for text, spacing, and layout.
• Keep line length comfortable; avoid overly wide or narrow text blocks.
• Use unitless line-height, typically around 1.5 for body text unless typography testing supports another value.
• Avoid justified text for web body copy unless hyphenation and language support are reliable and tested.
• Use enough contrast for text and UI states, but avoid unnecessary harshness as the only reading mode.
• Convey state with shape, text, icon, placement, or pattern, not color alone.
• Use whitespace and proximity to clarify grouping.

Media and non-text content

• Decorative images use empty alt text.
• Informative images get concise alt text that communicates purpose or content.
• Linked images describe the link destination or action, not merely the image.
• Complex images, infographics, and charts need surrounding explanation or structured text alternatives.
• Video with speech needs captions and a transcript.
• Captions should identify speaker changes and important non-speech audio.
• Media players must be keyboard operable, visibly focusable, and screen-reader labeled.

Internationalization and environmental resilience

• Do not assume one language, address format, name format, date format, device, connection speed, pointer type, or viewport.
• Use flexible data structures and UI labels where international variation is likely.
• Test long labels, translated strings, names, product titles, and variable content lengths.
• Support RTL layout when targeting RTL languages; prefer layout systems that respond to dir.
• Do not block browser zoom, text resizing, user font choices, or high-contrast settings.
• Treat web fonts, icons, and scripts as enhancements, not requirements for reading or basic operation.

Accessibility and inclusion requirements

Before finalizing, verify:

• The product can be used without a mouse.
• Focus order follows visual and logical order.
• Focus is visible at all times.
• Interactive elements have accessible names, roles, states, and values.
• Important content is not hidden in background images, pseudo-elements, color, audio, or layout position alone.
• Page structure can be navigated by headings and landmarks.
• Forms can be understood, completed, corrected, and submitted with assistive technology.
• Error, loading, expanded/collapsed, selected, and invalid states are communicated visually and programmatically.
• Text remains readable under zoom, text resizing, small screens, user font settings, and slow networks.
• Media alternatives are provided.
• Automated checks are complemented by manual keyboard and assistive-technology checks.

Frontend implementation guidance

• Start with semantic HTML; then add CSS; then add JavaScript.
• Keep controls native where possible. Style labels or wrappers instead of replacing inputs.
• Use CSS attribute selectors tied to semantic state, such as [aria-invalid="true"], [aria-expanded="true"], or [aria-pressed="true"], to reduce drift between state and styling.
• Do not create controls that require JavaScript for basic access when a working form/link fallback is possible.
• If a component hides content, ensure hidden content is removed from the focus order.
• If a component reveals content, place the revealed content near the trigger in source order unless there is a strong reason not to.
• If a component changes page content asynchronously, provide live-region feedback and deliberate focus management.
• Use design tokens for focus, contrast, spacing, disabled state, error state, and touch target sizing so accessibility is built into the system.
• Test components with long content, different languages, missing assets, disabled CSS, failed scripts, high contrast mode, zoom, and keyboard-only operation.
• For design systems, document expected markup, keyboard behavior, ARIA states, focus behavior, content rules, and anti-patterns for each component.

Quality checklist

Use the full checklists in references/checklists.md. At minimum, before answering:

• The recommendation starts from the user task.
• Native semantics are preferred over custom controls.
• Keyboard and focus behavior are specified.
• Screen reader names, states, and relationships are specified where relevant.
• Color is never the only cue.
• Text and labels are clear out of context.
• Errors, loading, and empty states are included.
• Responsive, zoom, and variable-content behavior are addressed.
• The response explains user impact and gives test steps.

Common mistakes to avoid

See the full anti-pattern list in references/anti-patterns.md. The highest-risk mistakes are:

• Clickable div controls.
• Placeholder-only labels.
• Removing focus styles.
• Disabling zoom.
• Hiding navigation unnecessarily.
• Icon-only controls without accessible names.
• Color-only states.
• Infinite scroll without an explicit alternative.
• JavaScript-dependent static content.
• Visual order that differs from source/focus order.
• ARIA used to patch a broken native pattern.
• Relying on automated tests alone.

How to explain recommendations to the user

Use practical, user-impact language:

• “This is not just compliance; it prevents keyboard and screen reader users from getting stuck.”
• “The native element is simpler and more reliable because the browser already provides role, keyboard behavior, and platform integration.”
• “This label needs to make sense out of context because screen readers can list controls and links independently.”
• “The visual state also needs a programmatic state so assistive technology receives the same information.”
• “This pattern preserves user control; the alternative would make the interface act unexpectedly.”
• “The default is inclusive for more users, and it does not prevent brand expression.”

When recommending a tradeoff, state:

1. the default,
2. the user groups protected,
3. the cost or constraint,
4. the condition that would justify an override,
5. how to test the override.