accessibility-inclusive-design
Skill6 starsChanged 4 months agoMITView on GitHub
Use when designing, critiquing, implementing, or revising UI/UX/frontend work for accessibility and inclusion.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- phazurlabs/sumitheir own version, first seen Oct 24, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- phazurlabs/sumi★ 58same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
The file
Show its rules and text
We split this skill into the rules it gives an agent
79 rules. About 0 are common, 67 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈67
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Use this skill to turn accessibility into normal design practice.
- Distinctive: line 19
Use this skill when the user asks for help with:
- Distinctive: line 29
Do not use this skill as the primary skill for:
- Distinctive: line 40
Prefer native semantics and standard web behavior: Use HTML elements that already include roles, states, keyboard behavior, and platform …
- Distinctive: line 43
Give users control: Do not block zoom, trap focus, autoplay media, force motion, impose infinite scroll, or decide display preferences when …
- Distinctive: line 45
Make hidden state explicit: If something expands, loads, errors, becomes selected, or changes dynamically, communicate the state visually …
- Distinctive: line 53
Use these defaults unless the user provides stronger product context or constraints.
- Distinctive: line 78
Do not ask users to approve routine best practices.
- Very specific: line 80
Ask one focused question only when the answer affects a material recommendation.
- Distinctive: line 85
Default: WCAG AA-level design and current product standard.
- Distinctive: line 87
Default: broad web audience, keyboard and screen reader support, responsive browser behavior.
- Distinctive: line 89
Default: native HTML or simpler pattern.
- Distinctive: line 91
Default: clear task language with brand personality secondary.
- Distinctive: line 93
Default: explicit user-triggered action with visible and programmatic feedback.
- Distinctive: line 95
Default: provide design/implementation recommendations and recommend expert/legal validation.
- Distinctive: line 97
Use the question-tool-ready prompts in references/decision-prompts.md.
- Distinctive: line 149
If missing, ask one focused question and propose the default.
- Distinctive: line 151
Prefer native controls and familiar conventions.
- Distinctive: line 155
Use direct, descriptive, context-independent copy.
- Distinctive: line 161
Add JavaScript only after the HTML baseline works.
- Distinctive: line 163
Test zoom, long content, localization, RTL if relevant, slow network, disabled CSS/JS, and alternative input.
- Distinctive: line 169
When choosing a pattern, prefer the first option that satisfies the user task:
- Distinctive: line 171
No interaction needed: Use semantic static content.
- Distinctive: line 172
Native interaction exists: Use the native element.
- Distinctive: line 173
Native interaction can be styled: Keep native behavior and style labels/containers rather than replacing controls.
- Distinctive: line 174
Progressive enhancement is enough: Keep the baseline form/link behavior and enhance with JS.
- Very specific: line 185
Use one meaningful document <title> that names the current page or result state.
- Very specific: line 186
Use one primary <main> region for the unique page content.
- Distinctive: line 188
Use headings for structure, not visual size.
- Distinctive: line 189
Use lists for grouped navigation and grouped content.
- Distinctive: line 190
Ensure source order makes sense when read top-to-bottom.
- Very specific: line 194
Put primary navigation in a nav landmark.
- Distinctive: line 196
Keep familiar placement and recognizable shapes.
- Distinctive: line 199
Use tables of contents for long pages instead of complex dropdown submenus when the goal is section navigation.
- Very specific: line 203
Use button for actions and a href for navigation.
- Very specific: line 204
Do not use a clickable div or span when a native element fits.
- Distinctive: line 205
Do not remove button or link affordance without replacing it with an equally clear affordance.
- Distinctive: line 207
Keep touch targets generous and separated.
- Distinctive: line 212
Every actionable control must be reachable by keyboard.
- Distinctive: line 213
Every focused control must have a visible focus indicator.
- Very specific: line 214
Do not set outline: none unless you provide a stronger replacement.
- Very specific: line 215
Do not use positive tabindex to rearrange navigation.
- Very specific: line 216
Use tabindex="-1" only for programmatic focus targets such as in-page headings after smooth scroll or newly loaded content.
- Distinctive: line 217
When JavaScript hijacks native behavior, restore focus movement, URL updates, and expected keyboard behavior.
- Distinctive: line 221
Every input has a persistent, associated label.
- Very specific: line 223
Use fieldset and legend when they clarify multiple related controls.
- Distinctive: line 224
Ask only for information needed to complete the task.
- Distinctive: line 226
Put errors near the user’s current work, not only at the top of the page.
- Very specific: line 228
Use aria-invalid and aria-describedby for invalid fields and remediation text when appropriate.
- Distinctive: line 229
Use live regions for asynchronous form or loading feedback, but do not over-announce every keystroke.
- Distinctive: line 231
Prefer “show password” to duplicate password fields unless policy prevents it.
- Distinctive: line 235
Prefer explicit actions such as “Apply filters” and “Load more” when changes are consequential.
- Distinctive: line 238
After new content loads, move focus to the first meaningful new item when the trigger is displaced.
- Distinctive: line 239
Avoid infinite scroll by default.
- Distinctive: line 240
If using live regions, choose polite/assertive behavior based on urgency and avoid interrupting routine reading unless necessary.
- Distinctive: line 244
Use real content early. Do not design only with idealized placeholder text.
- Distinctive: line 246
Use relative units for text, spacing, and layout.
- Distinctive: line 247
Keep line length comfortable.
- Distinctive: line 248
Use unitless line-height, typically around 1.5 for body text unless typography testing supports another value.
- Distinctive: line 249
Avoid justified text for web body copy unless hyphenation and language support are reliable and tested.
- Distinctive: line 250
Use enough contrast for text and UI states, but avoid unnecessary harshness as the only reading mode.
- Distinctive: line 252
Use whitespace and proximity to clarify grouping.
- Distinctive: line 266
Do not assume one language, address format, name format, date format, device, connection speed, pointer type, or viewport.
- Distinctive: line 267
Use flexible data structures and UI labels where international variation is likely.
- Distinctive: line 268
Test long labels, translated strings, names, product titles, and variable content lengths.
- Distinctive: line 270
Do not block browser zoom, text resizing, user font choices, or high-contrast settings.
- Distinctive: line 271
Treat web fonts, icons, and scripts as enhancements, not requirements for reading or basic operation.
- Distinctive: line 291
Start with semantic HTML; then add CSS.
- Distinctive: line 292
Keep controls native where possible.
- Very specific: line 293
Use CSS attribute selectors tied to semantic state, such as [aria-invalid="true"], [aria-expanded="true"], or [aria-pressed="true"], to …
- Distinctive: line 294
Do not create controls that require JavaScript for basic access when a working form/link fallback is possible.
- Distinctive: line 295
If a component hides content, ensure hidden content is removed from the focus order.
- Distinctive: line 296
If a component reveals content, place the revealed content near the trigger in source order unless there is a strong reason not to.
- Distinctive: line 297
If a component changes page content asynchronously, provide live-region feedback and deliberate focus management.
- Distinctive: line 298
Use design tokens for focus, contrast, spacing, disabled state, error state, and touch target sizing so accessibility is built into the …
- Distinctive: line 299
Test components with long content, different languages, missing assets, disabled CSS, failed scripts, high contrast mode, zoom, and …
- Distinctive: line 304
Use the full checklists in references/checklists.md.
- Distinctive: line 335
Use practical, user-impact language:
- Distinctive: line 344
When recommending a tradeoff, state:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- 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.
- Start with purpose and user task. Clear purpose reduces complexity, cognitive load, and implementation waste.
- 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.
- Make structure machine-readable. Headings, landmarks, lists, labels, form controls, alt text, captions, and document metadata are part of the interface.
- Progressively enhance. Begin with meaningful content and working HTML. Add CSS and JavaScript only when they improve the experience without destroying the baseline.
- 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.
- Use convention as an accessibility feature. Familiar navigation, link styling, button affordance, form patterns, and predictable placement reduce cognitive effort.
- Make hidden state explicit. If something expands, loads, errors, becomes selected, or changes dynamically, communicate the state visually and programmatically.
- Content is part of design. Clear headings, descriptive links, plain language, usable labels, and helpful errors are accessibility features.
- 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.
| Area | Default | Why it is usually best | Override only when |
| Accessibility target | Design to WCAG AA-level expectations and current product/platform standard; treat legal conformance as a floor, not the goal. | Uploaded sources repeatedly frame accessibility as built-in quality and identify AA as a common conformance target. | The user has a regulated context, internal standard, or specific conformance target. |
| Product goal | Clarify the primary user task before layout or styling. | Clear purpose simplifies decisions and reduces barriers. | The user is only asking for a narrow component fix. |
| Semantics | Use native HTML first: button, a, label, input, fieldset, legend, nav, main, headings, lists. | Native elements include expected keyboard and assistive-technology behavior. | The needed interaction has no suitable native pattern. |
| ARIA | Use ARIA only to add missing names, relationships, live updates, and states to otherwise sound markup. | ARIA changes semantics but does not automatically add behavior. | A custom component truly needs ARIA roles/states and matching keyboard behavior. |
| Layout | Use flexible, content-driven, responsive layouts; avoid fixed widths/heights. | Content, device sizes, zoom, and text settings vary. | A fixed dimension is intrinsic to media or a constrained platform surface. |
| Breakpoints | Add breakpoints where content breaks, not for named devices. | Device-specific breakpoints cannot cover all setups. | A native app or embedded surface has fixed known constraints. |
| Typography | Use readable type, relative units, generous line height, comfortable measure, and real content. | Readability supports low vision, dyslexia, cognitive load, language learners, and everyone else. | Brand type is constrained; then test and tune size, spacing, weight, and contrast. |
| Contrast | Ensure sufficient contrast and never use color alone; avoid unnecessary low contrast and avoid extreme glare as the only option. | Low contrast excludes many users; excessive glare can harm some readers. | A brand palette is fixed; then adapt tokens to meet contrast and comfort. |
| Links | Keep inline links visually identifiable, usually underlined, and make link text meaningful out of context. | Screen readers list links independently; color-only links fail many users. | Button-like CTAs may use button affordance, but still need clear text. |
| Navigation | Use landmarked, list-based navigation with familiar placement and clear current-location cues. | It works visually, without CSS, and in assistive technologies. | A very small flow genuinely needs no navigation. |
| Menus | Do not hide a short menu. For disclosure menus, use a real button, visible label, aria-expanded, adjacent menu, and robust hidden state. | Hidden navigation adds an action cost and state complexity. | Screen space is severely constrained or the menu is large. |
| Forms | Use persistent labels, grouped controls when useful, clear required indicators, forgiving validation, and error recovery. | Forms are high-risk for cognitive, motor, and screen reader barriers. | Extremely short forms may not need grouping; labels still remain required. |
| Validation | Validate on submit first; after errors exist, give supportive inline feedback while the user corrects. | Premature live validation can be noisy and stressful. | The field is high-cost or security-sensitive and immediate feedback is clearly helpful. |
| Passwords | Prefer a show-password control over forcing duplicate password entry. | It reduces cognitive and motor burden while preserving user control. | Security policy prohibits reveal controls. |
| Dynamic loading | Prefer explicit “Load more” or user-triggered updates over infinite scroll. Announce loading and move focus after new content appears. | Infinite scroll undermines keyboard navigation, control, and orientation. | Research proves auto-loading is expected and an accessible fallback is provided. |
| Media | Provide captions, transcripts, and meaningful image alternatives. | Different users need different sensory channels and contexts. | Decorative images should use empty alt text rather than a description. |
| Motion | Keep motion optional, purposeful, and controllable. | Motion can distract, disorient, or trigger symptoms. | Motion conveys essential state; still provide reduced-motion handling. |
| Testing | Run at least keyboard-only, focus, semantic/DOM, contrast, responsive/zoom, and screen reader smoke checks. | Automation cannot validate real interaction quality. | The task is conceptual only; still mention testing needed before launch. |
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:
- Regulatory or organizational target is unknown and compliance is central.
- Default: WCAG AA-level design and current product standard.
- Audience, assistive technologies, language, geography, or platform materially changes the design.
- Default: broad web audience, keyboard and screen reader support, responsive browser behavior.
- A component may need a custom interaction pattern rather than native HTML.
- Default: native HTML or simpler pattern.
- Brand voice conflicts with clear labels, plain language, or recognizable affordances.
- Default: clear task language with brand personality secondary.
- A dynamic behavior could change user control, focus, or orientation.
- Default: explicit user-triggered action with visible and programmatic feedback.
- 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:
- Task and purpose
- What is the user trying to do?
- Is the primary path obvious and unnecessary complexity removed?
- Structure and semantics
- Are document title, language, headings, landmarks, lists, controls, labels, and relationships meaningful?
- Does source order match reading and focus order?
- 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?
- Interaction behavior
- Are controls recognizable?
- Are states and changes communicated visually and programmatically?
- Does the interface preserve user control?
- Content and labels
- Are headings, links, form labels, button names, instructions, and errors clear out of context?
- Is brand language secondary to task clarity?
- Visual presentation
- Are contrast, text size, line height, measure, spacing, and grouping readable?
- Is information conveyed by more than color, position, or sound alone?
- Forms and errors
- Are labels persistent and associated?
- Are required fields clear?
- Are errors announced, located near the user’s work, and actionable?
- Media and alternatives
- Are images, icons, video, audio, and non-text cues available through appropriate alternatives?
- Responsive and environmental resilience
- Does it work with zoom, text resizing, narrow/wide viewports, slow networks, disabled CSS/JS, and user font/color preferences?
- 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:
- Clarify the feature and user task.
- If missing, ask one focused question and propose the default.
- Choose the simplest useful pattern.
- Prefer native controls and familiar conventions.
- Establish structure.
- Define headings, regions, reading order, navigation, form groups, and content relationships before styling.
- Write labels and content.
- Use direct, descriptive, context-independent copy.
- Define interaction and state.
- Specify keyboard behavior, focus order, visible focus, state announcements, loading, errors, and recovery.
- Apply visual design.
- Tune typography, contrast, spacing, grouping, affordance, and responsive behavior.
- Add progressive enhancement.
- Add JavaScript only after the HTML baseline works.
- Validate edge cases.
- Test zoom, long content, localization, RTL if relevant, slow network, disabled CSS/JS, and alternative input.
- 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:
- No interaction needed: Use semantic static content.
- Native interaction exists: Use the native element.
- Native interaction can be styled: Keep native behavior and style labels/containers rather than replacing controls.
- Progressive enhancement is enough: Keep the baseline form/link behavior and enhance with JS.
- Custom interaction is unavoidable: Implement the full pattern: role, name, state, keyboard behavior, focus management, visible affordance, instructions, and tests.
- The pattern hides content or takes control: Reconsider. Ask whether the product context truly requires it.
- 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; declaredirfor 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
navlandmark. - 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
buttonfor actions anda hreffor navigation. - Do not use a clickable
divorspanwhen 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: noneunless you provide a stronger replacement. - Do not use positive
tabindexto 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
fieldsetandlegendwhen 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-invalidandaria-describedbyfor 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
divcontrols. - 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:
- the default,
- the user groups protected,
- the cost or constraint,
- the condition that would justify an override,
- how to test the override.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

