TechPrufer
Get started
GitHub
GitHub logoGitHub · Feature trail

Design System Annotations

8 posts · Apr 2018 – May 2025

What this trail covers

This feature thread tracks the evolution of design system annotations, focusing on how to enrich components with contextual information beyond visual design and code properties. This post details advanced methods for creating 'Preset annotations' for design system components, including prioritizing components, mapping out necessary properties by cross-referencing documentation, code demos, and Figma assets, and integrating learnings about maintenance and potential automation. It also addresses the problem of accessible design system components producing inaccessible designs by demonstrating the integration of annotations with Primer components to streamline the annotation process, increase design system adoption, and reach teams without dedicated accessibility support. The next post will detail how to implement this for other components.

All GitHub trails
  1. Design system annotations, part 2: Advanced methods of annotating componentsThis post details advanced methods for creating 'Preset annotations' for design system components. It outlines a process for prioritizing components that would benefit most from these annotations, using internal tools like Primer Query and criteria such as alignment to organization priorities, frequency in audit issues, React implementation, and implementation frequency. The post also details how to map out necessary properties by cross-referencing component documentation on Primer.style, coded demos in Storybook, and component properties in Figma assets, as well as other potential sources like team experiences and audit findings. It provides a concrete example with the TextInput component, detailing its Preset annotation and learnings about maintenance and potential automation. It also addresses the confusion arising from overlap with other annotation types and suggests solutions.
  2. Design system annotations, part 1: How accessibility gets left out of componentsThis post details the problem of accessible design system components leading to inaccessible designs due to a lack of contextual information in annotations. It introduces the concept of 'Preset annotations' and demonstrates how integrating them with GitHub's Primer components can streamline the annotation process, increase design system adoption, and improve accessibility by providing crucial details beyond visual design and code properties. The post highlights the limitations of current annotation kits and design system components in capturing functional differences, accessible labels, and data submission requirements, and sets the stage for a follow-up post on implementation.
  3. Considerations for making a tree view component accessibleThis post details the engineering effort to make GitHub's tree view component accessible. It covers adopting Windows File Explorer's interaction patterns, using semantic HTML (`ul`, `li`) as a foundation, implementing composite widgets and landmark regions (`nav`), employing a roving `tabindex` approach, and enhancing with ARIA roles (`tree`, `treeitem`, `group`) and states (`aria-expanded`, `aria-selected`, `aria-current`). It also outlines support for expected keyboard navigation techniques (Tab, Enter, arrow keys, Home, End, typeahead) and middle-clicking behavior, as well as handling loading states with live region announcements.
  4. Design's journey towards accessibilityThis post details GitHub Design's journey towards accessibility, highlighting a cultural shift supported by leadership, the establishment of full-time accessibility specialists, and the empowerment of individuals through programs like the Accessibility Design Bootcamp and Design Champions. It emphasizes leveraging design systems, specifically Primer, to build leverage and propagate design changes, including updates to the color system to address contrast issues. The post also discusses the importance of designing for 'all developers, not average developers' and advocates for progress over perfection, encouraging experimentation and feedback from users with diverse abilities. It details the integration of accessibility into design reviews and org-wide meetings, and the hiring of an Accessibility Program Manager to scale enablement.
  5. Unlocking inclusive design: how Primer's color system is making GitHub.com more inclusiveThis post details the engineering effort to improve color contrast within GitHub's Primer design system to meet WCAG guidelines. It covers the audit of color pairs across themes, the development of an automated script to check contrast ratios (including handling semi-transparent colors with a blend algorithm), integration of this script as a GitHub Action for PRs, and a phased rollout using feature flags. The work resulted in resolving hundreds of accessibility issues across over a thousand use cases.
  7. Creating an accessible search experience with the QueryBuilder componentIntroduced the QueryBuilder component, a fully accessible component designed for complex search inputs with filtering capabilities. Detailed accessibility considerations including semantics (Combobox pattern), styled input implementation using a hidden div and spans, handling items with different actions ('Jump to' vs. 'Autocomplete') via aria-labels, group support with visual headers and screen reader specific aria-labels, and screen reader feedback using aria-live regions for suggestion counts and input clearing.
  8. How we use Web Components at GitHubThis post details the extensive use of Web Components at GitHub, covering their adoption from jQuery, the development of custom elements like `<relative-time>`, `<local-time>`, and `<details-dialog>`, and the creation of the Catalyst library to simplify Web Component authoring. It also outlines the lifecycle of components from monolith to open source, emphasizing dependency-free, framework-agnostic design, and the use of linters and tests to enforce best practices. The post also mentions the migration of specific components and the use of ViewComponent for Rails integration.
  9. Using Figma designs to build the Octicons icon libraryThis post details the migration of the Octicons icon library from a Git-based workflow with macOS-specific software dependencies to Figma. It describes how Figma's API is used to automate the export and distribution of icons via CI/CD pipelines and Probot for before/after image diffing on pull requests. The post also outlines the future plan to leverage Figma's write API to maintain code-based components and publish them as Figma components.