How not to integrate annotations and design systems

I recently wrote a 2-part series over on the GitHub Blog about Design System Annotations. Part one outlines the various ways accessibility gets left out of components and how our team uses a new type of "Preset annotations" to mitigate that. Part two walks through how you can create the same type of annotations for your design system.

During the course of our work creating Preset annotations for Primer, we explored with a number of other methods of enhancing Primer's components with annotations. Only one of three experiments worked out. It involved using Figma's Code Connect feature to embed some accessibility attributes directly in the component, and it's detailed at the end of the second post.

With our other experiments, we found more problems than benefits. I thought they might be instructive for others who are into annotations and design systems. This is some extremely niche design system theory about design system accessibility, but if that's your thing, do make sure to read the Design System Annotations series on the GitHub Blog before reading further.

Experiment #1: Hiding annotations directly in components

The first experiment, started by my colleagues Chelsea Adelman and Lukas Oppermann, involved building a hidden layer of annotations directly into a design system component. This allowed us to toggle a component property in Figma to show or hide annotations for any individual component.

The idea was that this could save designers time assembling the annotations a component would need. The hope was that something like this could also help capture the details that Preset annotations are able to, without the investment of creating a bespoke annotation for each component.

In practice, this idea also came with more potential problems than benefits:

1. If you've adopted design system components well, you'll be designing interfaces full of them. The more there are, the more tedious it becomes to toggle annotation visibility on or off for every individual component, whether annotating as a designer or consuming annotations as a developer.
2. Because the placement of the annotations is relative to individual components and not the frame they're placed in, they all overlap one another and become unreadable when made visible all at once.
3. This made it very difficult to fully grasp—let alone see all at once—a complete set of annotations for a page. One of our best practices is to keep the label of annotation stamps partially or fully outside of the edge of a design frame to increase legibility. When annotations are children of components, it's impossible to resize or move them.
4. Nested components add layers of complexity and dependency. If this announcement banner has a button and a link in it, the annotations may need to be added directly into the Button and Link components. Otherwise the boolean property that controls annotation visibility won't take into account the variations of the component itself. In other words, you could place an announcement banner on the canvas and hide the button and link, but when you reveal the annotations, the annotations for Button and Link would still be there.
5. Because toggling properties counts as an "edit" in Figma, a developer or stakeholder can't utilize this if their Figma account has a read-only seat.
6. The most risk comes from the potential fragility and complexity they added to the Primer components themselves. Future library maintenance and component updates would encounter more layers and properties, and thus more points of failure.
7. There's a continual and hard to quantify maintenance cost, because these annotations would become a source of truth. Anytime the component is updated (either the Figma asset or the code), the annotations would need to be updated in kind.

Any one of these things on their own is enough to make the experiment not worth the effort. In lieu of this, our teams currently rely on the Preset annotations and Code Connect solutions outlined in the GitHub Blog post series.

Potential applications

I can see this solution being potentially useful for components that are shared across multiple features/pages, but have not been formally adopted to the design system itself. In those cases, there may not be a central home for usage guidance or accessibility requirements and there wouldn’t be any maintenance risk, but this only addresses some of the problems.

This could also be useful as a read-only reference. In a previous role, teams were working with a design system where the components weren't yet fully coded. There was only annotated designs and usage guidance, so developers were using those to build semi-consistent implementations. This experiment would have helped consolidate documentation and provided consistent annotations even if designers didn't include them or link to an external source.

Having annotations that accompany the core design system components is also a powerful teaching tool for anyone in an accessibility design role. It can help them not only deepen their applied accessibility knowledge, but onboard to a design system they might not be familiar with. But annotated components can also serve this purpose from the design system Figma library file itself, or separate file dedicated to this purpose.

Experiment #2: Toggling the visibility of all annotations

While we were trying to make the hidden layer of annotations less tedious to interact with, before we had ruled it as an option, we started another experiment. Instead of toggling the visibility of the annotations for every individual component, we updated the annotation library itself with a new set of Figma variables. Similar to switching variable modes between “light mode” and “dark mode” themes, we used our new “Annotation Mode” to show and hide all annotations with a single action.

I've gotten a lot of requests from designers and developers for this sort of functionality. It comes up for various reasons. Sometimes people need to look at a design without any annotations overlapping it. Sometimes they don't want to duplicate design frames to have one with annotations and one without.

But even with our new variable-based Annotation Mode, we encountered many of the same problems as well as some new ones.

• It doesn’t solve the problem of overlapping annotations when they are hidden within the components themselves.
• When vital design and accessibility documentation is obfuscated, annotated designs can more easily get updates while the accompanying annotations remain ignored.
• Again, because toggling variable modes counts as an "edit" in Figma, a developer or stakeholder can't utilize this if their Figma account has a read-only seat.

Even worse, it trades convenience for a discovery problem.

When using it in tandem with the previous experiment (where annotations are hidden within a design system component), the default setting for Annotation Mode must be hidden. This makes it alarmingly easy to miss that a design has annotations at all.

When we abandoned the first experiment, we tried using this new variable mode on all of our annotation components. This meant that the default state would be visible and that there was now a way to hide them all at once if need be. But this relies on consistent user behavior, which is not a foolproof heuristic. It was still too easy for anyone to hide all annotations and forget to make them visible again.

We learned that any obscuring of annotations–even optional ones–presented risks for overall discoverability and for annotations falling out of sync with designs. If we were solving any problems with this experiment, we were also creating a lot of needless potential debt.

Potential applications

While I can see the idea itself being worthwhile, the main hurdle is in the implementation. If there were a way to toggle the visibility of annotations in a way that was temporary and/or only affected the current user's view rather than everyone's view of the canvas, this may be less risky. Perhaps a companion plugin to an annotation library could do this.

It's also heartening to see that Figma has validated the lessons we learned by making their own Annotation feature visible outside of Dev Mode. They also added a UI shortcut to toggle native Annotation visibility with Shift + Y

Conclusion

These experiments attempted to address shortcomings with component-library-based-annotations where the more appropriate solution would be with a Plugin or at the Figma UI layer.

The experiments also tried to address some issues with canvas hygiene that can be better solved with healthy team agreements about how things should be organized. You don't need fancy tooling if you can agree as a team about how annotations should be shown in relation to design frames. They can overlap finalized work, be in an adjacent duplicated frame, or duplicated to a separate page specifically for annotations. There isn't a wrong way–just the way that works for your team.

We encourage designers to give annotations a home with the main design specs, and we're not overly specific about the technique or information architecture. If annotations do end up far from the main designs, or even on another page, we have a component that can be placed with the main design to help direct stakeholders and developers to them.

Thanks for reading! While I learned a lot from the things that didn't work, I'm excited to see how far Code Connect can go in addition to our new Preset annotations.