From b121c00998e4e839828553eae99d042f16097f80 Mon Sep 17 00:00:00 2001 From: Jan Maarten <83665577+janmaarten-a11y@users.noreply.github.com> Date: Thu, 10 Sep 2026 10:54:44 -0700 Subject: [PATCH 1/3] Add repository accessibility statement --- ACCESSIBILITY.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 115 insertions(+) create mode 100644 ACCESSIBILITY.md diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md new file mode 100644 index 0000000..d8ac1a7 --- /dev/null +++ b/ACCESSIBILITY.md @@ -0,0 +1,114 @@ +# Accessibility + +## Commitment + +The GitHub Annotation Toolkit aims to support disabled designers, engineers, +and other collaborators in creating, reading, and discussing annotations. This +statement covers the Figma library and its documentation, rather than the +accessibility of products that use its annotations. + +### Figma + +Figma [documents keyboard and screen-reader support for canvas objects](https://www.figma.com/blog/introducing-screenreader-and-accessibility-features/). +Its [accessibility guidance](https://help.figma.com/hc/en-us/articles/35063862380311-Accessibility-at-Figma) +covers navigation, screen-reader settings, canvas zoom, interface scaling, and +enhanced interface contrast. + +Canvas zoom enlarges annotations, while interface scaling enlarges Figma's +controls. Enhanced interface contrast changes Figma's interface, not the +library's stamp colors. + +### Library design + +Stamps mark design elements. Details components hold accompanying written +explanations. + +- Text labels and icons distinguish annotation types without relying on color + alone. +- The palette pairs stamp labels with contrasting backgrounds. Outlines and + shadows help separate stamps from the canvas and the designs they overlap. +- Pin, Bracket, and Lasso formats offer different ways to point to an element + or group. Adjustable label positions help keep the underlying design visible. +- Matching note numbers connect Stamps and Details visually. Optional fields + let authors adjust the amount of detail without crowding the design. + +The [Getting started guide](./basics/getting-started.md) explains these options. + +### Documentation + +[Tutorials and checklists](./README.md#tutorials-training-and-documentation) +provide written guidance outside Figma. They explain how to use annotations +and what information to capture; they do not reproduce the content of each +annotated design. + +## Report an accessibility issue + +Report barriers through the [public issue tracker](https://github.com/github/annotation-toolkit/issues). +Include the affected component or documentation page, the task, and a written +explanation of what blocks or complicates it. + +Screenshots, recordings, and details about Figma, the browser, operating system, +or assistive technology are optional. Do not include confidential designs or +medical information in public reports. + +## Known barriers + +### Visual relationships on the canvas + +Stamps and Details rely on canvas position, connecting lines, and matching note +numbers to communicate relationships. Access to an individual canvas object is +not equivalent to understanding which element an annotation describes or how +it relates to other notes. + +These are library components, not Figma's native annotations. Accessibility +features for native annotations or prototypes do not automatically apply to +those relationships. + +For collaborators who cannot follow the canvas, provide a structured text +description alongside the design. Identify the element, its intended semantics +and behavior, and any relevant ordering. Agree on a format that collaborators +can use; a walkthrough can supplement that written record. + +### Dense or overlapping annotations + +Complex designs with many annotations are difficult to follow when stamps +overlap, obscure content, or sit far from their Details. The +[best practices for annotating](./deep-dives/best-practices-for-annotating.md) +describe ways to reduce clutter by moving labels outside the design, keeping +Details in the margins, and separating complex annotations across frames. + +Outlines and shadows do not guarantee legibility on every background. Review +contrast and readability in context, especially after changing colors, effects, +or placement. + +## Testing + +The [contribution process](./CONTRIBUTING.md) includes maintainer review and +testing of library changes before merge and publication. The project has not +conducted keyboard-only or screen-reader testing of this library, and the +repository does not run automated accessibility checks. + +This statement describes design choices, not measured contrast ratios or a +claim of conformance with the Web Content Accessibility Guidelines (WCAG). + +Annotations describe intended semantics and interactions; they do not implement +them in Figma or production code. Products built from annotated designs need +their own accessibility evaluation. [Annotation theory](./deep-dives/annotation-theory.md) +explains the role of annotations as a communication tool. + +## Contributing + +The [contribution guide](./CONTRIBUTING.md) explains how to propose library +changes. This project accepts direct Figma library contributions from GitHub +staff; other contributors can share suggestions and examples through issues. + +For accessibility-related changes, describe the barrier or access need and +distinguish observed behavior from assumptions. Documentation improvements can +include clearer instructions, descriptive links, and text alternatives for +illustrations. + +## Contact + +GitHub's Accessibility Design team [maintains the toolkit](./README.md#maintainers). +[Support guidance](./SUPPORT.md) lists the public feedback route and additional +channels for GitHub staff. diff --git a/README.md b/README.md index 56d7eae..bc1d9b3 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,7 @@ For GitHub staff, the "Annotation Toolkit" is enabled in the Figma Asset panel ### Toolkit basics - [Features](basics/features.md) - What's in the Toolkit? - [Getting Started](basics/getting-started.md) - How to use the Annotation Toolkit components +- [Accessibility](./ACCESSIBILITY.md) - Figma support, library design choices, and known barriers ### Deep dives and training - [Annotation Theory](deep-dives/annotation-theory.md) - What annotations are and how they can transform our work From 01beba51c257e7d81ab528aa0590167c24a54830 Mon Sep 17 00:00:00 2001 From: Jan Maarten <83665577+janmaarten-a11y@users.noreply.github.com> Date: Thu, 10 Sep 2026 11:02:19 -0700 Subject: [PATCH 2/3] Remove fixed-width wrapping from accessibility statement --- ACCESSIBILITY.md | 92 ++++++++++++------------------------------------ 1 file changed, 22 insertions(+), 70 deletions(-) diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md index d8ac1a7..eb20603 100644 --- a/ACCESSIBILITY.md +++ b/ACCESSIBILITY.md @@ -2,113 +2,65 @@ ## Commitment -The GitHub Annotation Toolkit aims to support disabled designers, engineers, -and other collaborators in creating, reading, and discussing annotations. This -statement covers the Figma library and its documentation, rather than the -accessibility of products that use its annotations. +The GitHub Annotation Toolkit aims to support disabled designers, engineers, and other collaborators in creating, reading, and discussing annotations. This statement covers the Figma library and its documentation, rather than the accessibility of products that use its annotations. ### Figma -Figma [documents keyboard and screen-reader support for canvas objects](https://www.figma.com/blog/introducing-screenreader-and-accessibility-features/). -Its [accessibility guidance](https://help.figma.com/hc/en-us/articles/35063862380311-Accessibility-at-Figma) -covers navigation, screen-reader settings, canvas zoom, interface scaling, and -enhanced interface contrast. +Figma [documents keyboard and screen-reader support for canvas objects](https://www.figma.com/blog/introducing-screenreader-and-accessibility-features/). Its [accessibility guidance](https://help.figma.com/hc/en-us/articles/35063862380311-Accessibility-at-Figma) covers navigation, screen-reader settings, canvas zoom, interface scaling, and enhanced interface contrast. -Canvas zoom enlarges annotations, while interface scaling enlarges Figma's -controls. Enhanced interface contrast changes Figma's interface, not the -library's stamp colors. +Canvas zoom enlarges annotations, while interface scaling enlarges Figma's controls. Enhanced interface contrast changes Figma's interface, not the library's stamp colors. ### Library design -Stamps mark design elements. Details components hold accompanying written -explanations. +Stamps mark design elements. Details components hold accompanying written explanations. -- Text labels and icons distinguish annotation types without relying on color - alone. -- The palette pairs stamp labels with contrasting backgrounds. Outlines and - shadows help separate stamps from the canvas and the designs they overlap. -- Pin, Bracket, and Lasso formats offer different ways to point to an element - or group. Adjustable label positions help keep the underlying design visible. -- Matching note numbers connect Stamps and Details visually. Optional fields - let authors adjust the amount of detail without crowding the design. +- Text labels and icons distinguish annotation types without relying on color alone. +- The palette pairs stamp labels with contrasting backgrounds. Outlines and shadows help separate stamps from the canvas and the designs they overlap. +- Pin, Bracket, and Lasso formats offer different ways to point to an element or group. Adjustable label positions help keep the underlying design visible. +- Matching note numbers connect Stamps and Details visually. Optional fields let authors adjust the amount of detail without crowding the design. The [Getting started guide](./basics/getting-started.md) explains these options. ### Documentation -[Tutorials and checklists](./README.md#tutorials-training-and-documentation) -provide written guidance outside Figma. They explain how to use annotations -and what information to capture; they do not reproduce the content of each -annotated design. +[Tutorials and checklists](./README.md#tutorials-training-and-documentation) provide written guidance outside Figma. They explain how to use annotations and what information to capture; they do not reproduce the content of each annotated design. ## Report an accessibility issue -Report barriers through the [public issue tracker](https://github.com/github/annotation-toolkit/issues). -Include the affected component or documentation page, the task, and a written -explanation of what blocks or complicates it. +Report barriers through the [public issue tracker](https://github.com/github/annotation-toolkit/issues). Include the affected component or documentation page, the task, and a written explanation of what blocks or complicates it. -Screenshots, recordings, and details about Figma, the browser, operating system, -or assistive technology are optional. Do not include confidential designs or -medical information in public reports. +Screenshots, recordings, and details about Figma, the browser, operating system, or assistive technology are optional. Do not include confidential designs or medical information in public reports. ## Known barriers ### Visual relationships on the canvas -Stamps and Details rely on canvas position, connecting lines, and matching note -numbers to communicate relationships. Access to an individual canvas object is -not equivalent to understanding which element an annotation describes or how -it relates to other notes. +Stamps and Details rely on canvas position, connecting lines, and matching note numbers to communicate relationships. Access to an individual canvas object is not equivalent to understanding which element an annotation describes or how it relates to other notes. -These are library components, not Figma's native annotations. Accessibility -features for native annotations or prototypes do not automatically apply to -those relationships. +These are library components, not Figma's native annotations. Accessibility features for native annotations or prototypes do not automatically apply to those relationships. -For collaborators who cannot follow the canvas, provide a structured text -description alongside the design. Identify the element, its intended semantics -and behavior, and any relevant ordering. Agree on a format that collaborators -can use; a walkthrough can supplement that written record. +For collaborators who cannot follow the canvas, provide a structured text description alongside the design. Identify the element, its intended semantics and behavior, and any relevant ordering. Agree on a format that collaborators can use; a walkthrough can supplement that written record. ### Dense or overlapping annotations -Complex designs with many annotations are difficult to follow when stamps -overlap, obscure content, or sit far from their Details. The -[best practices for annotating](./deep-dives/best-practices-for-annotating.md) -describe ways to reduce clutter by moving labels outside the design, keeping -Details in the margins, and separating complex annotations across frames. +Complex designs with many annotations are difficult to follow when stamps overlap, obscure content, or sit far from their Details. The [best practices for annotating](./deep-dives/best-practices-for-annotating.md) describe ways to reduce clutter by moving labels outside the design, keeping Details in the margins, and separating complex annotations across frames. -Outlines and shadows do not guarantee legibility on every background. Review -contrast and readability in context, especially after changing colors, effects, -or placement. +Outlines and shadows do not guarantee legibility on every background. Review contrast and readability in context, especially after changing colors, effects, or placement. ## Testing -The [contribution process](./CONTRIBUTING.md) includes maintainer review and -testing of library changes before merge and publication. The project has not -conducted keyboard-only or screen-reader testing of this library, and the -repository does not run automated accessibility checks. +The [contribution process](./CONTRIBUTING.md) includes maintainer review and testing of library changes before merge and publication. The project has not conducted keyboard-only or screen-reader testing of this library, and the repository does not run automated accessibility checks. -This statement describes design choices, not measured contrast ratios or a -claim of conformance with the Web Content Accessibility Guidelines (WCAG). +This statement describes design choices, not measured contrast ratios or a claim of conformance with the Web Content Accessibility Guidelines (WCAG). -Annotations describe intended semantics and interactions; they do not implement -them in Figma or production code. Products built from annotated designs need -their own accessibility evaluation. [Annotation theory](./deep-dives/annotation-theory.md) -explains the role of annotations as a communication tool. +Annotations describe intended semantics and interactions; they do not implement them in Figma or production code. Products built from annotated designs need their own accessibility evaluation. [Annotation theory](./deep-dives/annotation-theory.md) explains the role of annotations as a communication tool. ## Contributing -The [contribution guide](./CONTRIBUTING.md) explains how to propose library -changes. This project accepts direct Figma library contributions from GitHub -staff; other contributors can share suggestions and examples through issues. +The [contribution guide](./CONTRIBUTING.md) explains how to propose library changes. This project accepts direct Figma library contributions from GitHub staff; other contributors can share suggestions and examples through issues. -For accessibility-related changes, describe the barrier or access need and -distinguish observed behavior from assumptions. Documentation improvements can -include clearer instructions, descriptive links, and text alternatives for -illustrations. +For accessibility-related changes, describe the barrier or access need and distinguish observed behavior from assumptions. Documentation improvements can include clearer instructions, descriptive links, and text alternatives for illustrations. ## Contact -GitHub's Accessibility Design team [maintains the toolkit](./README.md#maintainers). -[Support guidance](./SUPPORT.md) lists the public feedback route and additional -channels for GitHub staff. +GitHub's Accessibility Design team [maintains the toolkit](./README.md#maintainers). [Support guidance](./SUPPORT.md) lists the public feedback route and additional channels for GitHub staff. From dba6f378e20c7d44f4fccc204030d7e549de9808 Mon Sep 17 00:00:00 2001 From: Jan Maarten <83665577+janmaarten-a11y@users.noreply.github.com> Date: Thu, 10 Sep 2026 11:19:46 -0700 Subject: [PATCH 3/3] Update ACCESSIBILITY.md Applying suggestion from code review --- ACCESSIBILITY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md index eb20603..9a19339 100644 --- a/ACCESSIBILITY.md +++ b/ACCESSIBILITY.md @@ -27,7 +27,7 @@ The [Getting started guide](./basics/getting-started.md) explains these options. ## Report an accessibility issue -Report barriers through the [public issue tracker](https://github.com/github/annotation-toolkit/issues). Include the affected component or documentation page, the task, and a written explanation of what blocks or complicates it. +Report any issues through the [public issue tracker](https://github.com/github/annotation-toolkit/issues). Include the affected component or documentation page, the task, and a written explanation of what blocks or complicates it. Screenshots, recordings, and details about Figma, the browser, operating system, or assistive technology are optional. Do not include confidential designs or medical information in public reports.