Purpose of These DocsThese docs are meant as a starting point for using Anvil2 accessibly. While the contents can contribute to building accessible interfaces from scratch, that is not the main goal.
Overview
Directly Related WCAG Guidelines(s):
| Anvil2 Responsibility | Implementor Responsibility |
|---|
| Anvil2 ensures built-in status announcements, loading states, and ARIA attribute management for changing states in the components. | Implementors ensure that the changing content is clearly written and can be controlled when necessary. |
Status Updates
Directly Related WCAG Guidelines(s):
| Anvil2 Responsibility | Implementor Responsibility |
|---|
| Anvil2 ensures status components, automatic ARIA live regions, and form validation status management. | Implementors ensure that the changing content is clearly written and has a logical flow. |
Best Practices
- Write clear, helpful status messages appropriate for the type of status being displayed
- Keep important messages persistent with clear next-step actions or instructions
- Use appropriate status types (success, error, warning) that match the message content
Common Pitfalls
- Using vague or unhelpful status messages that don’t guide users
- Assigning status types that don’t match the content (e.g., using “error” styling for success messages)
- Overwhelming users with too many status messages or auto-hiding critical information
Loading States
Directly Related WCAG Guidelines(s):
Loading states provide feedback to users about ongoing processes and prevent confusion about whether actions are being processed. Screen readers rely on aria-busy attributes to announce when elements are loading, while visual users need clear loading indicators to understand that work is in progress.
Proper accessibility implementation ensures that users can track progress, understand system responsiveness, and receive appropriate feedback during wait times. This includes providing clear loading indicators, progress announcements, and proper ARIA attributes that communicate loading status to assistive technologies.
Without proper loading indicators, users may attempt to repeat actions, become frustrated by apparent system failures, or abandon tasks that appear to be unresponsive.
| Anvil2 Responsibility | Implementor Responsibility |
|---|
| Anvil2 ensures automatic ARIA attributes and built-in loading spinners with state management to components that have the option. There is also a standalone Spinner component for use in other areas. | Implementors ensure that the loading state is being applied at the correct time and that the spinner is added to custom components where appropriate. |
Best Practices
- Provide clear feedback for both visual users and assistive technologies about what is loading
- For long-running processes, display a progress indicator and provide a cancel option
- Announce loading state changes to screen readers using ARIA attributes
Common Pitfalls
- Providing vague or missing feedback about state changes
- Blocking page interaction without offering a way to cancel the operation
- Failing to communicate loading status to assistive technologies
Progress Indicators
Directly Related WCAG Guidelines(s):
Progress indicators help users understand how much of a task has been completed and how much remains. Screen readers rely on proper ARIA attributes like role=“progressbar” to announce progress information, while visual users need clear visual feedback about completion status.
Proper accessibility implementation ensures that users can track completion status, understand remaining work, and make informed decisions about continuing or pausing processes. This includes providing both visual and programmatic progress information, clear completion percentages, and appropriate ARIA attributes that communicate progress to assistive technologies.
Without proper progress communication, users may become uncertain about task completion, lose track of their progress, or abandon long-running processes.
| Anvil2 Responsibility | Implementor Responsibility |
|---|
| Anvil2 ensures automatic ARIA attributes, visual styling, and accessibility support via a ProgressBar component. | Implementors ensure that there is clear messaging/controls that accompany the progress indicator and proper calculation of time. |
Best Practices
- Clearly communicate both the progress percentage and what operation is being performed
- Provide controls to pause or cancel the operation when appropriate
- Use proper ARIA attributes like
role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax
Common Pitfalls
- Using vague or overly elaborate descriptions that confuse users
- Relying solely on visual progress bars without text or ARIA attributes
- Blocking page interaction during long operations without providing a cancel option
Collapsible Content
Directly Related WCAG Guidelines(s):
Collapsible content must clearly communicate its current state and allow users to control expansion and collapse. Screen readers rely on aria-expanded attributes to announce whether content is currently visible, while all users need clear visual indicators for the expanded/collapsed state.
Proper accessibility implementation ensures that users can understand content relationships, control information disclosure, and navigate between sections effectively. This includes providing proper ARIA attributes, keyboard navigation support, and clear state communication that works for both visual and non-visual users.
Without proper collapsible content implementation, users may become disoriented about what content is available, struggle to navigate between sections, or miss important information that is hidden from view..
| Anvil2 Responsibility | Implementor Responsibility |
|---|
| Anvil2 ensures components that have proper integration with accessibility patterns for collapsible content and keyboard controls. | Implementors ensure that there is a logical flow and handles proper state management for the content being collapsed |
Best Practices
- Write clear, descriptive trigger text that indicates what content will be revealed
- Use
aria-expanded to communicate current state to assistive technologies
- Organize content in a logical way that makes sense when collapsed or expanded
- Ensure keyboard navigation works properly for expand/collapse controls
Common Pitfalls
- Using unclear trigger text that doesn’t describe the hidden content
- Grouping unrelated content together in collapsible sections
- Failing to update
aria-expanded when state changes
