Proposal for a WCAG Content API

[mpaiva]

Background

The Web Content Accessibility Guidelines (WCAG) have been instrumental in guiding web developers and designers towards creating more accessible content. With the upcoming release of WCAG 3.0, there's an opportunity to further enhance accessibility practices by providing a programmatic way to access these guidelines.

Proposal

I propose the development of an API that allows the community to programmatically access WCAG content. This API would serve as a centralized, authoritative source for the guidelines, enabling developers to integrate accessibility standards directly into their tools and applications.

Key Features

1. Guideline Retrieval: Access detailed information about specific WCAG guidelines, including descriptions, success criteria, and examples.
2. Search Functionality: Search for guidelines based on keywords, criteria, or tags.
3. Updates and Notifications: Receive updates on changes or additions to the guidelines.
4. Integration Support: Enable integration with popular development tools and platforms (e.g., Figma, Penpot, Tokens Studio).
5. Design Recommendations: Provide WCAG-based recommendations for design decisions, available as design tokens for use in design systems.

Benefits

• Improved Accessibility: Facilitate the creation of accessible web content by providing easy access to WCAG guidelines.
• Community Engagement: Encourage collaboration and innovation within the accessibility community.
• Consistency: Ensure that applications adhere to standardized guidelines, promoting uniformity in accessibility practices.
• Design Guidance: Empower designers with WCAG-based recommendations, enhancing their ability to create accessible designs.

Technical Specifications

• API Endpoints: Define endpoints for accessing guidelines, searching, retrieving updates, and fetching design recommendations.
• Authentication and Authorization: Implement security measures to protect the API and its content.
• Documentation: Provide comprehensive API documentation for developers, including usage examples and best practices.

Community Involvement

To ensure the success of this API, we invite the community to contribute ideas on how this API could be used. For instance, I have already created a Figma plugin using a local static JSON version of WCAG 2.2. This plugin enhances the accessibility of digital designs by integrating accessibility guidelines directly into your design processes and systems. It's a simple Figma plugin that offers three key features:

• Guideline Search: Quickly find relevant guidelines as a conversation starter and to ensure your designs are providing an equitable experience for all users.
• Notation Cards: Annotate Figma design files with WCAG guideline cards to increase your knowledge of accessibility requirements and best practices.
• Utility Tokens: Import accessibility utility tokens as Figma variables to ensure accessible design decisions across various design elements and components.

Note on Design Tokens: Building on this, we propose extending the utility tokens feature to provide WCAG-based recommendations for design decisions. These recommendations will be made available as design tokens, which can be easily integrated into design systems. Design tokens are a way to store design decisions as reusable variables, ensuring consistency and accessibility across all design elements and components.

Examples of how the Community could use the API:

I'd encourage everyone who reads this post to contribute additional ideas on how the WCAG Content API could be utilized. Whether you're a developer, designer, educator, or accessibility advocate, your insights and suggestions are invaluable. Here are some initial ideas:

• Creating Plugins for Other Design Tools: Similar to the Figma plugin, develop plugins for other popular design tools to integrate WCAG guidelines and recommendations.
• Automating Accessibility Checks: Use the API to build tools that automatically check and suggest accessibility improvements in real-time during the design and development process.
• Developing Educational Resources: Create interactive learning materials and resources that leverage the API to teach accessibility best practices based on WCAG guidelines.
• Building Accessible Design Systems: Utilize the API to develop comprehensive design systems that incorporate WCAG guidelines into every component, ensuring accessibility from the ground up.
• Generating Accessibility Reports: Develop tools that use the API to generate detailed accessibility reports for websites and applications, highlighting areas that meet or need improvement based on WCAG criteria.
• Enhancing Content Management Systems (CMS): Integrate the API into popular CMS platforms to provide real-time accessibility guidance and validation as content is created and edited.
• Creating Accessibility Dashboards: Use the API to build dashboards that track and visualize the accessibility compliance status of multiple projects, making it easier to manage and monitor accessibility efforts.
• Supporting Inclusive User Testing: Develop tools that leverage the API to facilitate inclusive user testing, providing testers with relevant WCAG guidelines and criteria to assess.
• Enabling Voice and AI Assistants: Integrate the API with voice and AI assistants to provide real-time accessibility guidance and recommendations through conversational interfaces.
• Developing Customizable Accessibility Widgets: Create widgets that can be embedded in websites and applications to provide users with tools and information to enhance their accessibility experience based on WCAG standards.

The community contributions and feedback will be invaluable in refining the API and making it more useful for a wide range of users.

Conclusion

By developing a WCAG Content API, we can make it easier for developers to create accessible web content and foster a more inclusive digital environment. I look forward to hearing your thoughts and collaborating on this initiative.

[GreggVan]

I'm sure this will be more difficult than it first sounds, and there may be some unintended consequences -- but I think it could be a really useful tool/capability to explore. It can't be THE authoritative reference I don't think (replacing the published document) - but it could be the best way to incorporate (accurately) the guidelines and recommendations.

AND with WCAG3 and our intention to couple recommendations with requirements to extend them beyond the "testable" limits -- this could be really helpful --- AS LONG AS you can't pull just the required and not get the recommended along with them....

[mpaiva]

Agreed @GreggVan - developing this API will have its challenges and we need to be mindful of any unintended consequences. The API isn't meant to replace the official WCAG documents but to make it easier to use the guidelines accurately in different tools.

It's important that the API includes both the required guidelines and the recommended best practices, especially with the new WCAG 3.0 updates. This way, users will get a complete picture of what’s needed for accessibility.

Here's an example of an absolute recommendation (WCAG 2.5.8) that could be readily integrated into design systems:

 [ 
 "2-5-8 Target Size (AA)/wcag-target-size-minimum-px": {
    "$type": "number",
    "$value": "24",
    "$description": "WCAG 2.5.8 (AA v2.2) - Specifies the minimum size for target areas of pointer inputs, ensuring ease of interaction."
  },
  "2-5-8 Target Size (AA)/wcag-target-size-minimum-half-px": {
    "$type": "number",
    "$value": "12",
    "$description": "WCAG 2.5.8 (AA v2.2) - Specifies the minimum size for target areas of pointer inputs, ensuring ease of interaction."
  },
  "2-5-8 Target Size (AA)/wcag-target-size-minimum-quarter-px": {
    "$type": "number",
    "$value": "6",
    "$description": "WCAG 2.5.8 (AA v2.2) - Specifies the minimum size for target areas of pointer inputs, ensuring ease of interaction."
  }
]

This uses the proposed Design Tokens Format Module (Draft)

https://design-tokens.github.io/community-group/format/

[mraccess77]

An API would be helpful in pulling in techniques, methods, or tests into accessibility testing tools and platforms. I believe today there are some XML indexes that can be used for some of this but a more modern approach would be beneficial.

[patrickhlauke]

Providing an API (with actual endpoints that can be queried dynamically), versus just providing the entire structure in a machine-readable format (as @mraccess77 mentions, there's XML today, but perhaps something like JSON). I'd say my preference would be for this, rather than trying to design endpoints/functions

[patrickhlauke]

while this is tangential, @mpaiva i'm wondering in your example above about the half and quarter pixel variants of the SC ... and noting that that criterion uses density-independent CSS pixels, so not quite sure what to make of those half/quarter measures

[mpaiva]

When creating and building design systems we could use multiples or partials of a unit to provide spacing definitions for padding, gaps, margins, etc.

In the example above, if a designer is not using a graph engine like Tokens Studio, which has a robust math support, they can add those partials directly as Figma variables when creating the sufficient target size for buttons, inputs or links.

[mpaiva]

Here's another example I use as a "team ritual" during stand-ups. At the end of each stand-up gathering, I share one WCAG guideline with the team. Discuss use-cases, best-practices, then ask if there are any questions. This ritual takes less than 5 min and we all learn together.

Having an API like this would foster creativity in how technologists consume and understand the WCAG content.

For the WCAG Quotes example, I created a static JSON file and augmented the additional content, like quotes, images, captions, etc.

The attached image is a screenshot of four slides for a presentation on the recommendation 1.4.7. The theme for this application is to use the end-users perspective when they face the barriers the SC is trying to solve.

• Slide 1: A meme of a person shushing the reader with the text, "If I wanted to listen to a reading, I'd buy tickets!"
• Slide 2: A screenshot of the WebAIM article on low or no background audio.
• Slide 3: A summary of the WebAIM article.
• Slide 4: A thank you note from a user who is happy that they can now concentrate without background noises.