


We have recently finished our latest accessibility review on the platformOS Developer Portal. This article describes our approach to accessibility. As our developer portal is open source and all planning, issue tracking, and code and content contributions happen through GitHub, you can get a detailed understanding of our practices and use those insights in your own projects. (And we’d love you to share any of your accessibility learnings, too.)
We address accessibility right from the design phase, where we use Figma’s Able accessibility plugin. We follow the rules for foreground and background color contrast, font size, and graphical objects (like icons, form fields, etc.) to ensure that our site conforms with WCAG AAA. The number of words or characters per line also contributes to readability. That’s why we aim to have 65-75 characters per line.
As another foundation for accessibility, we make sure to only use and correctly use semantic HTML — this helps assistive technologies (like screen readers) convey information to their users by following the semantic structure. In addition to providing and ensuring a consistent structure, semantic HTML ensures that web browsers apply default accessibility features for specific HTML elements. For example, buttons get keyboard accessibility (can be navigated to and clicked using the keyboard).
We regularly test for accessibility with various tools and ensure that the site complies with all accessibility requirements.
Test results of the platformOS Developer Portal:
These automated accessibility checkers perform a series of audits on the site and result in a weighted average score and a list of recommendations for improving accessibility. The tests check, for example:
Find a full list of Lighthouse checks with detailed explanations of each test on web.dev.
We make sure to follow all of these technical recommendations and fix any issues we find.
As semantic HTML is essential for accessibility, we make sure not to style text any other way than through Markdown, which is then translated into HTML. We provide ready-to-use templates for all content types that include all non-changeable content and placeholders with explanations for the parts to add. Placeholders provide information on the recommended format (for example, title) and any requirements or limitations (for example, the maximum number of characters). The templates define the headings structure and levels.
The technical aspects we described so far are only the foundation. To have a truly accessible site, you need to write for accessibility.
We defined the following guidelines in our Documentation Style Guide.
Be inclusive and global. Use language that reflects your users’ diversity (including, for example, race, gender, ability, location, etc.).
We thought it might be helpful to show some examples of these guidelines in action from our latest accessibility edits. One of the larger tasks was to replace the word “see”, and for this we examined each instance of “see” in our documentation and replaced it with a more fitting, accessible alternative. For example:
Instead of: | We now have: |
---|---|
There is a point in troubleshooting when you just can’t see new approaches anymore. | There is a point in troubleshooting when you just can’t think of new approaches anymore. |
You should see that the background color of the page has changed to the color specified in the `app.css` file. | The background color of the page has changed to the color specified in the `app.css` file. |
You can also use the `admin_third_party_integrations` query to see the current configuration of any third party integration. | You can also use the `admin_third_party_integrations` query to learn about the current configuration of any third party integration. |
After setting up domain authentication, your recipients will no longer see the “via sendgrid.net” message on your emails. | After setting up domain authentication, your emails will not include the “via sendgrid.net” message. |
In the Audience ID section, you see a string of letters and numbers. | In the Audience ID section, you find a string of letters and numbers. |
Let's use the example to see exactly what is happening at each stage of the Model Schema definition life cycle. | Let's use the example to follow exactly what is happening at each stage of the Model Schema definition life cycle. |
It helps to turn off word-wrap in your editor to see those patterns easier. | It helps to turn off word-wrap in your editor to recognize those patterns easier. |
You can find all the changes we made during our latest review in pull requests collected on our ticket in GitHub.
We found that these changes not only made our content more accessible but clearer and more precise.
We close this article with a collection of resources that we found helpful in making our developer portal more accessible.
We are continuously working to make our documentation more accessible and usable to the widest possible audience. Please let us know if you have any suggestions for improving accessibility. Thank you!
Ensure your project’s success with the power of platformOS.