{"id":2003,"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-2-advanced-methods-of-annotating-components\/"},"modified":"2025-05-09T17:30:34","modified_gmt":"2025-05-09T17:30:34","slug":"design-system-annotations-part-2-advanced-methods-of-annotating-components","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2025\/05\/09\/design-system-annotations-part-2-advanced-methods-of-annotating-components\/","title":{"rendered":"Design system annotations, part 2: Advanced methods of annotating components"},"content":{"rendered":"

In part one of our design system annotation series, we discussed the ways in which accessibility can get left out of design system components<\/a> from one instance to another. Our solution? Using a set of \u201cPreset annotations\u201d<\/a> for each component with Primer. This allows designers to include specific pre-set details that aren\u2019t already built into the component and visually communicated in the design itself.\u00a0<\/p>\n

That being said, Preset annotations are unique to each design system \u2014 and while ours may be a helpful reference for how to build them \u2014 they\u2019re not something other organizations can utilize if you\u2019re not also using the Primer<\/a> design system.\u00a0<\/p>\n

Luckily, you can build your own. Here\u2019s how.\u00a0<\/p>\n

How to make Preset annotations for your<\/em> design system<\/h2>\n

Start by assessing components to understand which ones would need Preset annotations\u2014not all of them will. Prioritize components that would benefit most from having a Preset annotation, and build that key information into each one. Next, determine what properties should be included. Only include key information that isn\u2019t conveyed visually, isn\u2019t in the component properties, and isn\u2019t already baked into a coded component.\u00a0<\/p>\n

Prioritizing components<\/h3>\n

When a design system has 60+ components, knowing where to start can be a challenge. Which components need these annotations the most? Which ones would have the highest impact for both design teams and our users?\u00a0<\/p>\n

When we set out to create a new set of Preset annotations based on our proof of concept, we decided to use ten Primer components that would benefit the most. To help pick them, we used an internal tool called Primer Query that tracks all component implementations across the GitHub codebase as well as any audit issues connected to them. Here is a video breakdown<\/a> of how it works, if you\u2019re curious.\u00a0<\/p>\n

We then prioritized new Preset annotations based on the following criteria:<\/p>\n

Components that align to organization priorities (i.e. high value products and\/or those that receive a lot of traffic).<\/p>\n

Components that appear frequently in accessibility audit issues.<\/p>\n

Components with React implementations (as our preferred development framework).<\/p>\n

Most frequently implemented components.\u00a0<\/p>\n

Mapping out the properties<\/h3>\n

For each component, we cross-referenced multiple sources to figure out what component properties and attributes would need to be added in each Preset annotation. The things we were looking for may only exist in one or two of those places, and thus are less likely to be accounted for all the way through the design and development lifecycle. The sources include:<\/p>\n

Component documentation on Primer.style<\/strong><\/h4>\n

Design system docs should contain usage guidance for designers and developers, and accessibility requirements should be a part of this guidance as well. Some of the guidance and requirements get built into the component\u2019s Figma asset, while some only end up in the coded component.\u00a0<\/p>\n

Look for any accessibility requirements that are not built into either Figma or code. If it\u2019s built in, putting the same info in the Preset annotation may be redundant or irrelevant.<\/p>\n

Presets can account for rare use cases<\/p>\n

While building a Preset annotation for the TextInput<\/a> component, we found that implementations may use an icon alone or have a hidden input label. With GitHub\u2019s global search or filter inputs, the magnifying glass icon alone can act as the visible label, but the fields still need an accessible label for assistive technology users.<\/p>\n

Coded demos in Storybook\u00a0<\/strong><\/h4>\n

Our component sandbox<\/a> helped us see how each component is built in React or Rails, as well as what the HTML output is. We looked for any code structure or accessibility attributes that are not included in the component documentation or the Figma asset itself\u2014especially when they may vary from one implementation to another.\u00a0<\/p>\n

Code attributes a designer may not see or set<\/p>\n

Storybook helped us craft our TextInput component\u2019s Preset annotation by showing some important attributes that don\u2019t get any mention elsewhere. The type<\/strong> attribute is to the value of text. by default. Depending on the purpose of the field, an input\u2019s type<\/strong> could also be search, email, number, tel, date, or time. This should be set intentionally so that users are able to use the most appropriate virtual keyboard.<\/p>\n

Component properties in the Figma asset library<\/strong><\/h4>\n

Library assets provide a lot of flexibility through text layers, image fills, variants, and elaborate sets of component properties. We paid close attention to these options to understand what designers can and can\u2019t change. Worthwhile additions to a Preset Annotation are accessibility attributes, requirements, and usage guidance in other sources that aren\u2019t built into the Figma component.\u00a0<\/p>\n

What\u2019s missing from the TextInput\u2019s Figma component<\/p>\n

When a TextInput is added to a design, the Figma component comes with many customizable options. There is an inputTextType property, which is about visual design and typography, not the type of form input. It\u2019s possible to set the value of the Label and input field in Figma\u2019s sidebar, but because it\u2019s hidden by default, there\u2019s no option to set the text of an error validation message.<\/p>\n

We can\u2019t assume that every design delivered in Figma will come with examples of a form showing all of its error states, so these error messages may not get the attention they require. If this message can\u2019t be built into the component as a text property, it can be added to the Preset annotation.<\/p>\n

Other potential sources\u00a0<\/strong><\/h4>\n

Experiences from team members: <\/strong>The designers, developers, and accessibility specialists you work with may have insight into things that the docs and design tools may have missed. If your team and design system have been around for a while, their insights may be more valuable than those you\u2019ll find in the docs, component demos, or asset libraries. Take some time to ask which components have had challenging bugs and which get intentionally broken when implemented.<\/p>\n

Findings from recent audits: <\/strong>Design system components themselves may have unresolved audit issues and remediation recommendations. If that\u2019s the case, those issues are likely present in Storybook demos and may be unaccounted for in the component documentation. Design system audit issues may have details that both help create a Preset annotation and offer insights about what should not<\/strong> be carried over from existing resources.<\/p>\n

Putting it all together<\/h3>\n

Our new Preset annotation for the TextInput component included links to usage guidance and Storybook as well as an optional tutorial for how the component is best used in a design to avoid potential issues. There are two mandatory prompts for input type and error text, and an optional one for the occasional hidden form label.<\/p>\n

What we learned from creating Preset annotations<\/h2>\n

Preset annotations may not be for every team or organization. However, they are especially well suited for younger design systems and those that aren\u2019t well adopted.\u00a0<\/p>\n

Mature design systems like Primer have frequent updates. This means that without close monitoring, the design system components themselves may fall out of sync with how a Preset annotation is built. This can end up causing confusion and rework after development starts, so it may be wise to make sure there\u2019s some capacity to maintain these annotations after they\u2019ve been created.\u00a0<\/p>\n

For newer teams at GitHub, new members of existing teams, and team members who were less familiar with the design system, the built-in guidance and links to documentation and component demos proved very useful. Those who are more experienced are also able to fine-tune the Presets and how they\u2019re used.<\/p>\n

If you don\u2019t already have extensive experience with the design system components (or peers to help build them), it can take a lot of time to assess and map out the properties needed to build a Preset. It can also be challenging to name a component property succinctly enough that it doesn\u2019t get truncated in Figma\u2019s properties panel<\/a>. If the context is not self-evident, some training or additional documentation may help.<\/p>\n

It\u2019s not always clear that you need a Preset annotation<\/h3>\n

There may be enough overlap between the Preset annotation for a component and types of annotations that aren\u2019t specific to the design system.\u00a0
For example, the GitHub Annotation Toolkit has components to annotate basic <textarea> form elements in addition to a Preset annotation for our <TextArea> Primer component:<\/p>\n

In many instances, this flexibility may be confusing because you could use either annotation. For example, the Primer <TextArea> Preset has built-in links to specific Primer docs, and while the non-Preset version doesn\u2019t, you could always add the links manually. While there\u2019s some overlap between the two, using either one is better than none.\u00a0<\/p>\n

One way around this confusion is to add Primer-specific properties to the default set of annotations. This would allow you to do things like toggle a boolean property on a normal Button annotation and have it show links and properties specific to your design system\u2019s button component.\u00a0<\/p>\n

Our Preset creation process may unlock automation<\/h3>\n

There are currently a number of existing Figma plugins that advertise the ability to scan a design file to help with annotations. That being said, the results are often mixed and contain an unmanageable amount of noise and false positives. One of the reasons these issues happen is that these public plugins are design system agnostic.<\/p>\n

Current automated annotation tools aren\u2019t able to understand that any design system components are being used without bespoke programming or thorough training of AI models. For plugins like this to be able to label design elements accurately, they first need to understand how to identify the components on the canvas, the variants used, and the set properties.\u00a0<\/p>\n

With that in mind, perhaps the most exciting insight is that the process of mapping out component properties for a Preset annotation\u2014the things that don\u2019t get conveyed in the visual design or in the code\u2014is also something that would need to be done in any attempt to automate more usable annotations.\u00a0<\/p>\n

In other words, if a team uses a design system and wants to automate adding annotations, the tool they use would need to understand their components. In order for it to understand their components well enough to automate accurately<\/em>, these hidden component properties would need to be mapped out. The task of creating a set of Preset annotations may be a vital stepping stone to something even more streamlined.\u00a0<\/p>\n

A promising new method: Figma\u2019s Code Connect\u00a0<\/h2>\n

While building our new set of Preset annotations, we experimented with other ways to enhance Primer with annotations. Though not all of those experiments worked out<\/a>, one of them did: adding accessibility attributes through Code Connect.\u00a0<\/p>\n

Primer was one of the early adopters<\/a> of Figma\u2019s new Code Connect feature in Dev Mode. Says Lukas Oppermann<\/a>, our staff systems designer, \u201cWith Code Connect, we can actually move the design and the code a little bit further apart again. We can concentrate on creating the best UX for the designers working in Figma with design libraries and, on the code side, we can have the best developer experience.\u201d\u00a0<\/p>\n

To that end, Code Connect allows us to bypass much of our Preset annotations, as well as the downsides of some of our other experiments. It does this by adding key accessibility details directly into the code that developers can export from Figma.<\/p>\n

GitHub\u2019s Octicons<\/a> are used in many of our Primer components. They are decorative by default, but they sometimes need alt text or aria-label attributes depending on how they\u2019re used. In the IconButton<\/a> component, that button uses an Octicon and needs an accessible name to describe its function.\u00a0<\/p>\n

When using a basic annotation kit, this may mean adding stamps for a Button<\/strong> and Decorative Image<\/strong> as well as a note in the margins that specifies what the aria-label should be. When using Preset annotations, there are fewer things to add to the canvas and the annotation process takes less time.<\/p>\n

With Code Connect set up, Lukas added a hidden layer in the IconButton Figma component. It has a text property for aria-label which lets designers add the value directly from the component properties panel. No annotations needed. The hidden layer doesn\u2019t disrupt any of the visuals, and the aria-label property gets exported directly with the rest of the component\u2019s code.<\/p>\n

It takes time to set up Code Connect with each of your design system components. Here are a few tips to help:<\/p>\n

Consistency is key. <\/strong>Make sure that the properties you create and how you place hidden layers is consistent across components. This helps set clear expectations so your teams can understand how these hidden layers and properties function.\u00a0<\/p>\n

Use a branch of your design system library to experiment.<\/strong> Hiding attributes like aria-label is quite simple compared to other complex information that Preset annotations are capable of handling.\u00a0<\/p>\n

Use <\/strong>visual regression testing<\/strong><\/a> (VRT).<\/strong> Adding complexity directly to a component comes with increased risk of things breaking in the future, especially for those with many variants. Figma\u2019s merge conflict UI is helpful, but may not catch everything.<\/p>\n

As we continue to innovate with annotations and make our components more accessible, we are aiming to release our GitHub Annotation Toolkit in the near future. Stay tuned!<\/p>\n

Further reading<\/h2>\n

Accessibility annotation kits are a great resource, provided they\u2019re used responsibly. Eric Bailey<\/a>, one of the contributors to our forthcoming GitHub Annotation Toolkit, has written extensively about how annotations can highlight and amplify deeply structural issues<\/a> when you\u2019re building digital products.<\/p>\n

The post Design system annotations, part 2: Advanced methods of annotating components<\/a> appeared first on The GitHub Blog<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"

In part one of our design system annotation series, we discussed the ways in which accessibility can get left out […]<\/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-2003","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\/2003","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=2003"}],"version-history":[{"count":0,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/2003\/revisions"}],"wp:attachment":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media?parent=2003"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/categories?post=2003"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/tags?post=2003"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}