{"id":2004,"date":"2025-05-09T17:30:34","date_gmt":"2025-05-09T17:30:34","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2025\/05\/09\/design-system-annotations-part-1-how-accessibility-gets-left-out-of-components\/"},"modified":"2025-05-09T17:30:34","modified_gmt":"2025-05-09T17:30:34","slug":"design-system-annotations-part-1-how-accessibility-gets-left-out-of-components","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2025\/05\/09\/design-system-annotations-part-1-how-accessibility-gets-left-out-of-components\/","title":{"rendered":"Design system annotations, part 1: How accessibility gets left out of components"},"content":{"rendered":"

When it comes to design systems, every organization tends to be at a different place in their accessibility journey. Some have put a great deal of work into making their design system accessible while others have a long way to go before getting there. To help on this journey, many organizations rely on accessibility annotations<\/a> to make sure there are no access barriers when a design is ready to be built.\u00a0<\/p>\n

However, it\u2019s a common misconception (especially for organizations with mature design systems) that accessible components will result in accessible designs. While design systems are fantastic for scaling standards and consistency, they can\u2019t prevent every issue with our designs or how we build them. Access barriers can still slip through the cracks and make it into production.<\/p>\n

This is the root of the problem our Accessibility Design team set out to solve.\u00a0<\/p>\n

In this two-part series, we\u2019ll show you exactly how accessible design system components can produce inaccessible designs. Then we\u2019ll demonstrate our solution: integrating annotations with our Primer<\/a> components. This allows us to spend less time annotating, increases design system adoption, and reaches teams who may not have accessibility support. And in our next post, we\u2019ll walk you through how you can do the same for your own components.<\/p>\n

Let\u2019s dig in.<\/p>\n

What are annotations and their benefits?\u00a0<\/h2>\n

Annotations are notes included in design projects that help make the unseen explicit by conveying design intent that isn\u2019t shown visually. They improve the usability of digital experiences by providing a holistic picture for developers of how an experience should function. Integrating annotations into our design process helps our teams work better together by closing communication gaps and preventing quality issues, accessibility audit issues<\/a>, and expensive re-work.\u00a0<\/p>\n

Some of the questions annotations help us answer include:<\/p>\n

How is assistive technology<\/a> meant to navigate a page from one element to another?<\/p>\n

What\u2019s the alternative text for informative images and buttons without labels?<\/p>\n

How does content shift depending on viewport size, screen orientation, or zoom level?<\/p>\n

Which virtual keyboard<\/a> should be used for a form input on mobile?<\/p>\n

How should focus be managed for complex interactions?<\/p>\n

Our answers to questions like this\u2014or the lack thereof\u2014can make or break<\/strong> the experience of the web for a lot of people, especially users with disabilities. Some annotation tools are built specifically to help with this by guiding designers to include key details about web standards, platform functionality, and accessibility (a11y).\u00a0<\/p>\n

Most public annotation kits are well suited for teams who are creating new design system components, teams who aren\u2019t already using a design system, or teams who don\u2019t have specialized accessibility knowledge. They usually help annotate things like:<\/p>\n

Controls such as buttons and links<\/p>\n

Structural elements such as headings and landmarks<\/a><\/p>\n

Decorative images<\/a> and informative descriptions\u00a0<\/p>\n

Forms and other elements that require labels and semantic roles\u00a0<\/p>\n

Focus order for assistive technology and keyboard navigation<\/p>\n

GitHub\u2019s annotation\u2019s toolkit<\/h3>\n

One of our top priorities is to meet our colleagues where they\u2019re at<\/strong>. We wanted all our designers to be able to use annotations out of the box because we believe they shouldn\u2019t need to be a certified accessibility specialist in order to get things built in an accessible way.\u00a0<\/p>\n

To this end, last year we began creating an internal Figma library\u2014the GitHub Annotation Toolkit<\/a> (which we aim to release to the public soon). Our toolkit builds on the legacy of the former Inclusive Design team at CVS Health. Their two open source annotation kits<\/a> help make documentation that\u2019s easy to create and consume, and are among the most widely used annotation libraries in the Figma Community.\u00a0<\/p>\n

While they add clarity, annotations can also add overhead. If teams are only relying on specialists to interpret designs and technical specifications for developers, the hand-off process can take longer than it needs to. To create our annotation toolkit, we rebuilt its predecessor from the ground up to avoid that overhead, making extensive improvements and adding inline documentation to make it more intuitive and helpful for all of our designers\u2014not just accessibility specialists.\u00a0<\/p>\n

Design systems can also help reduce that overhead. When you audit your design systems for accessibility<\/a>, there\u2019s less need for specialist attention on every product feature, since you\u2019re using annotations to add technical semantics and specialist knowledge into every component. This means that designers and developers only need to adhere to the usage guidelines consistently, right?<\/p>\n

The problems with annotations and design system components<\/h2>\n

Unfortunately, it\u2019s not that simple.\u00a0<\/p>\n

Accessibility is not binary<\/h3>\n

While design systems can help drive more accessible design at scale, they are constantly evolving and the work on them is never done. The accessibility of any component isn\u2019t binary. Some may have a few severe issues that create access barriers, such as being inoperable with a keyboard or missing alt text. Others may have a few trivial issues, such as generic control labels.\u00a0<\/p>\n

Most of the time, it will be a misnomer to claim that your design system is \u201cfully accessible.\u201d There\u2019s always more work to do\u2014it\u2019s just a question of how much. The Web Content Accessibility Guidelines<\/a> (WCAG) are a great starting point, but their \u201cSuccess Criteria\u201d isn\u2019t tailored for the unique context that is your website or product or audience.\u00a0<\/p>\n

While the WCAG should be used as a foundation to build from, it\u2019s important to understand that it can\u2019t capture every nuance<\/a> of disabled users\u2019 needs because your<\/strong> users\u2019 needs are not every<\/strong> user\u2019s needs. It would be very easy to believe that your design system is \u201cfully accessible\u201d if you never look past WCAG to talk to your<\/strong> users. If Primer has accessible components, it\u2019s because we feel that direct participation and input from daily assistive technology users is the most important aspect of our work<\/a>. Testing plans with real users\u2014with and without disabilities\u2014is where you really find what matters most.\u00a0<\/p>\n

Accessible components<\/em> do not guarantee accessible designs<\/em><\/h3>\n

Arranging a series of accessible components on a page does not automatically create an accurate and informative heading hierarchy. There\u2019s a good chance that without additional documentation, the heading structure won\u2019t make sense visually\u2014nor as a medium for navigating with assistive technology.<\/a><\/p>\n

It\u2019s great when accessible components are flexible and responsive, but what about when they\u2019re placed in a layout that the component guidance doesn\u2019t account for? Do they adapt to different zoom levels, viewport sizes, and screen orientations? Do they lose any functionality or context when any of those things change?<\/p>\n

Component usage is contextual. You can add an image or icon to your design, but the design system docs can\u2019t write descriptive text for you. You can use the same image in multiple places, but the image description may need to change depending on context.\u00a0<\/p>\n

Similarly, forms built using the same input components may do different things and require different error validation messages. It\u2019s no wonder that adopting design system components doesn\u2019t get rid of all audit issues.<\/a><\/p>\n

Design system components in Figma don\u2019t include all the details<\/h3>\n

Annotation kits don\u2019t include components for specific design systems because almost every organization is using their own. When annotation kits are adopted, teams often add ways to label their design system components.\u00a0<\/p>\n

This labeling lets developers know they can use something that\u2019s already been built, and that they don\u2019t need to build something from scratch. It also helps identify any design system components that get \u2018detached\u2019 in Figma. And it reduces the number of things that need to be annotated.\u00a0<\/p>\n

Let\u2019s look at an example:<\/p>\n

If we\u2019re using this Primer Button<\/a> component from the Primer Web Figma library<\/a>, there are a few important things that we won\u2019t know just by looking at the design or the component properties:<\/p>\n

Functional differences when components are implemented.<\/strong> Is this a link that just looks visually like a button? If so, a developer would use the <LinkButton><\/a> React component instead of <Button>.<\/p>\n

Accessible labels for folks using assistive technology.<\/strong> The icon may need alt text. In some cases, the button text might need some visually-hidden text<\/a> to differentiate it from similar buttons. How would we know what that text is? Without annotations, the Figma component doesn\u2019t have a place to display this.<\/p>\n

Whether user data is submitted.<\/strong> When a design doesn\u2019t include an obvious form with input fields, how do we convey that the button needs specific attributes to submit data?\u00a0<\/p>\n

It\u2019s risky to leave questions like this unanswered, hoping someone notices and guesses the correct answer.\u00a0<\/p>\n

A solution that streamlines the annotation process while minimizing risk<\/h2>\n

When creating new components, a set of detailed annotations can be a huge factor in how robust and accessible they are. Once the component is built, design teams can start to add instances of that component in their designs. When those designs are ready to be annotated, those new components shouldn\u2019t need to be annotated again. In most cases, it would be redundant and unnecessary\u2014but not in every case.\u00a0<\/p>\n

There are some important details in many Primer components that may change from one instance to another. If we use the CVS Health annotation kit out of the box, we should be able to capture those variations, but we wouldn\u2019t be able to avoid those redundant and unnecessary annotations. As we built our own annotation toolkit, we built a set of annotations for each Primer component to do both of those things at once.\u00a0<\/p>\n

This accordion component has been thoroughly annotated so that an engineer has everything they need to build it the first time. These include heading levels, semantics for <detail> and <summary> elements, landmarks, and decorative icons. All of this is built into the component so we don\u2019t need to annotate most of this when adding the accordion to our new designs.<\/p>\n

However, there are two important things we need to annotate, as they can change from one instance to another:<\/p>\n

The optional title at the top.<\/p>\n

The heading level of each item within the accordion.<\/p>\n

If we don\u2019t specify these things, we\u2019re leaving it to chance that the page\u2019s heading structure will break or that the experience will be confusing for people to understand and navigate the page. The risks may be low for a single button or basic accordion, but they grow with pattern complexity, component nesting, interaction states, duplicated instances, and so on.\u00a0<\/p>\n

Instead of annotating what\u2019s already built into the component or leaving these details to chance, we can add two quick annotations. One Stamp to point to the component, and one Details annotation where we fill in some blanks to make the heading levels clear.\u00a0<\/p>\n

Because the prompts for specific component details are pre-set<\/strong> in the annotation, we call them Preset annotations.<\/p>\n

Introducing our Primer A11y Preset annotations<\/h2>\n

With this proof of concept, we selected ten frequently used Primer components for the same treatment and built a new set of Preset annotations to document these easily missed accessibility details\u2014our Primer A11y Presets.\u00a0<\/p>\n

Those Primer components tend to contribute to more accessibility audit issues when key details are missing on implementation. Issues for these components relate to things like lack of proper labels, error validation messages, or missing HTML or ARIA attributes<\/a>.\u00a0<\/p>\n

Each of our Preset annotations is linked to component docs and Storybook<\/a> demos. This will hopefully help developers get straight to the technical info they need without designers having to find and add links manually. We also included guidance for how to fill out each Preset, as well as how to use the component in an accessible way. This helps designers get support inline without leaving their Figma canvas.\u00a0<\/p>\n

Want to create your own? Check out Design system annotations, part 2<\/h2>\n

Button components in Google\u2019s Material Design<\/a> and Shopify\u2019s Polaris<\/a>, IBM\u2019s Carbon<\/a>, or our Primer design system are all very different from one another. Because Preset annotations are based on specific components, they only work if you\u2019re also using the design system they\u2019re made for.\u00a0<\/p>\n

In part 2 of this series<\/a><\/strong>, we\u2019ll walk you through how you can build your own set of Preset annotations for your design system, as well as some different ways to document important accessibility details before development starts.<\/p>\n

You may also like:\u00a0<\/h2>\n

If you\u2019re more of a visual learner, you can watch Alexis Lucio<\/a> explore Preset annotations during GitHub\u2019s Dev Community Event<\/a> to kick off Figma\u2019s Config 2024.\u00a0<\/p>\n

\n<\/div>\n

The post Design system annotations, part 1: How accessibility gets left out of components<\/a> appeared first on The GitHub Blog<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"

When it comes to design systems, every organization tends to be at a different place in their accessibility journey. Some […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[8],"tags":[],"class_list":["post-2004","post","type-post","status-publish","format-standard","hentry","category-github-engineering"],"_links":{"self":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/2004","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/comments?post=2004"}],"version-history":[{"count":0,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/2004\/revisions"}],"wp:attachment":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media?parent=2004"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/categories?post=2004"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/tags?post=2004"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}