User needs and assistive technologies
When solving problems and developing new features, it's important not to design solely from the perspective of our own abilities. We must be empathetic toward users who may face limitations when interacting with digital interfaces. Disabilities can be permanent, temporary, or situational, so it’s essential to offer multiple modes of interaction. Users may experience barriers due to various impairments, including: auditory, cognitive, neurological, physical, visual.
The WCAG 2.1 guidelines outline how to design for inclusivity and define levels of accessibility through measurable success criteria. Contentful aims to meet WCAG 2.1 Level AA standards.
Operating systems offer assistive technologies—like screen readers, braille display support, and contrast modes—to help users interact with content. Our responsibility is to ensure that our interfaces are both semantically meaningful and technically supportive of these tools.
Checklist
This checklist provides a foundation—it’s a starting point, not the finish line. It outlines key accessibility considerations to help you design not just for compliance, but for genuinely usable, enjoyable, and effective experiences for people with disabilities.
Text alternatives
Provide meaningful alt text for all non-text content.
Use appropriate ARIA attributes (
aria-label,aria-describedby) for custom controls or non-standard elements.Avoid using text embedded in images unless it’s part of a logo or decorative graphic.
Adaptable content
Ensure content and relationships (e.g., form labels and descriptions) are conveyed through semantic HTML or accessible markup.
Use headings to logically divide content and reflect the page’s structure.
Present content in a meaningful order to support screen reader navigation.
Keyboard accessibility
All interactive components should be usable with a keyboard alone.
Ensure focus indicators are visible (e.g., outlines or styling).
Avoid keyboard traps—users must be able to navigate to and from every focusable element.
For character key shortcuts, allow users to disable or remap them.
Distinguishable design
Never rely on color alone to convey meaning (e.g., status indicators must also have text).
Maintain a minimum contrast ratio:
Text: 4.5:1 (3:1 for large text)
UI components and icons: 3:1
Use tools like WebAIM Contrast Checker.
Text should be resizable up to 200% without losing functionality or clarity.
Navigable interfaces
Provide skip links or landmarks to bypass repetitive content.
Ensure pages have clear and descriptive titles.
The tab/focus order should follow a logical reading sequence.
Headings
Use semantic heading elements (
<h1>through<h6>) that reflect the content hierarchy.Avoid choosing heading levels purely for stylistic reasons.
Links
Link text must describe its destination or purpose clearly. Avoid vague terms like “click here.”
Color and contrast
Pair color with other indicators (like text or icons) for errors, statuses, and categories.
Ensure links are visually distinct from body text using more than color alone.
All actionable elements must have a clear, visible focus state.
Magnification and responsive design
Design should support browser zooming without loss of content or functionality.
Avoid horizontal scrolling when zoomed.
Interfaces should work in both portrait and landscape orientations.
Images
Informative images must have descriptive alt text.
Functional images (e.g., buttons or links) must explain their purpose via alt text or labels.
Complex graphics should be explained in nearby text and summarized in alt text.
Decorative images should be marked as such (e.g.,
alt=""orrole="presentation").
Tables
Data tables should include a caption and use proper markup for headers (
<th>,scopeattributes).Simplify complex tables to reduce reliance on compound headers.
Forms
Each field must have a persistent, visible label.
Labels must be descriptive and placed next to their inputs.
Controls (e.g., Edit/Delete) should be near the content they affect.
Provide meaningful error messages and instructions.
Support browser autofill where applicable.
Dynamic content and feedback
Notify users of dynamic changes or insert new content in a logical order after the triggering element.
Ensure interactions provide clear feedback (e.g., success/failure messages, state changes).
Feedback should be accessible to all users, including screen reader users.
Custom widgets
Use Forma 36 components wherever possible. They offer built-in accessibility.
Custom widgets must:
Be fully keyboard operable
Follow WAI-ARIA Authoring Practices 1.1
Click targets
Interactive elements must have adequate size and spacing (44Ă—44 CSS pixels if possible).
Ensure touch targets are not too close together. Spacing helps more than just size.
Automated testing
To help meet these accessibility requirements, we use automated testing tools:
axe for WCAG-compliant accessibility audits
Jest snapshot tests included by default in all new Forma 36 React components
All components scaffolded via the CLI (yarn add-component) come with basic accessibility testing built in. Â