diff --git a/content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md b/content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md index 83f8c85d70e7..b7df1115dae9 100644 --- a/content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md +++ b/content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md @@ -143,11 +143,12 @@ Octicons are icons used across {% data variables.product.prodname_dotcom %}’s If you're referencing an Octicon that appears in the UI, identify whether the Octicon is the entire label of the UI element (for example, a button that is labeled only with "+") or whether it's only decorative, in addition to another label (for example, 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` (for example, `{% 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 `` or `
` tag will. + - Some Octicons used as labels have dynamic `aria-label` elements that change based on the state of the UI element or a user input. For example, when someone has two security policies-`Policy A` and `Policy B`-their UI will show two trash Octicons labelled `{% octicon "trash" aria-label="Delete Policy A" %}` and `{% octicon "trash" aria-label="Delete Policy B" %}`. For dynamic `aria-label` elements, since we can't document the exact `aria-label` that people will encounter, describe the Octicon and a placeholder example of the label (for example, `"{% octicon "trash" aria-label="The trash icon, labelled 'Delete YOUR-POLICY-NAME'." %}"`). This will help people identify both the Octicon and how it is labelled, and give context for collaborating with people who are visually describing the Octicon. - 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 (for example, `"{% 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 "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#tables)." -### Example usage of octicons +### Example usage of Octicons ```text {% raw %}{% octicon "" %}