jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Update our guidance on octicons (again) (#35738)

Browse Source 
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
This commit is contained in:
Laura Coursen
2023-03-21 14:10:08 -05:00
committed by GitHub
parent d851132ef5
commit bac2f9fdd5
1 changed files with 4 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
contributing/content-markup-reference.md
View File

@@ -88,9 +88,10 @@ You can also add a header that includes the name of the language and a button to
Octicons are icons used across GitHub’s interface. We reference octicons when documenting the user interface and to indicate binary values in tables. Find the name of specific octicons on the [Octicons site](https://primer.style/octicons).
If you're referencing an octicon that appears in the UI, use your browser's developer tools to check whether the octicon is hidden to screen readers with the `aria-hidden=true` attribute. For example, when a button is labeled "+ Add message" for sighted users, the plus icon is decorative and therefore hidden to screen readers, which instead read only "Add message."
- If the octicon is hidden with `aria-hidden="true"`, use `aria-hidden="true"` in the Liquid syntax for the octicon in the docs (e.g., `"{% octicon "plus" aria-hidden="true" %} Add message"`).
- If the octicon is not hidden, the screen reader will read the octicon's `aria-label`, and we should use that same `aria-label` in the docs for consistency. For example, a button may be labeled with _only_ the "plus" icon for sighted users, while a screen reader will read "Add file." We should reflect this experience in the docs with `{% octicon "plus" aria-label="Add file" %}`.
If you're referencing an octicon that appears in the UI, identify whether the octicon is the entire label of the UI element (e.g., a button that is labeled only with "+") or whether it's only decorative, in addition to another label (e.g., a button is labeled "+ Add message").
- If the octicon is the entire label, use your browser's developer tools to inspect the octicon and determine what screen reader users will hear instead. Then, use that text for the `aria-label` (e.g., `{% octicon "plus" aria-label="Add file" %}`). Occasionally, in the UI, the octicon itself will not have an `aria-label`, but a surrounding element such as a `<summary>` or `<div>` tag will.
- If the octicon is decorative, it's likely hidden to screen readers with the `aria-hidden=true` attribute. If so, for consistency with the product, use `aria-hidden="true"` in the Liquid syntax for the octicon in the docs as well (e.g., `"{% octicon "plus" aria-hidden="true" %} Add message"`).
If you're using the octicon in another way, such as using the "check" and "x" icons to reflect binary values in tables, use the `aria-label` to describe the meaning of the octicon, not its visual characteristics. For example, if you're using a "x" icon in the "Supported" column of a table, use "Not supported" as the `aria-label`. For more information, see [Tables](./content-style-guide.md#use-clear-consistent-symbols-and-labels) in the style guide.