{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"6"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"463a62a8-ee50-49cc-a09d-92d40b8b9bb1"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"145b397e-84b1-48b2-becd-410dff00084e"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"General accessibility","type":"text"}]},{"type":"paragraph","content":[{"text":"Heading markup (e.g. native hN elements) is utilized by Assistive Technologies (AT) to construct a table of contents for a document. This provides an accessible method of in-page navigation.","type":"text"}]},{"type":"paragraph","content":[{"text":"AT will also be able to provide an appropriate alternate visual display that can be identified by heading markup. Screen readers use the headings to jump quickly around the page and understand its content.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"You can quickly review a page’s heading hierarchy with the ","type":"text"},{"text":"a11y-outline bookmarklet","type":"text","marks":[{"type":"strong"}]},{"text":" at ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://xi.github.io/a11y-outline/"}},{"text":" . Just drag the link that is on that page to your Bookmarks bar, and then click it to see a list of Headings, Landmarks, or Links. Note that it doesn’t work with iframes, though, and learning unit content is in an iframe in the Learning MFE.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Nesting","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#nesting"}}]},{"text":" headings properly ensures that a screen reader can pick up on the hierarchy of the content and generate an ordered list for the user to browse.","type":"text"}]},{"type":"paragraph","content":[{"text":"Generally headings should be used for chunking related information. There are some occasions when we use headings for other purposes, but there are exceptions to the rule / usability compromises. Start with the assumption that headings should be chunking hierarchical info, and check with the Accessibility team if you think there is a good exception.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"When to use which ","type":"text"},{"text":"hN","type":"text","marks":[{"type":"code"}]},{"text":" tag","type":"text"}]},{"type":"paragraph","content":[{"text":"Native heading elements are NOT intended to be used as a way to style or resize text. See below section “","type":"text"},{"text":"hN","type":"text","marks":[{"type":"code"}]},{"text":" tags as CSS classes” for Paragon classes that DO resize text to match heading levels.","type":"text"}]},{"type":"paragraph","content":[{"text":"Avoid skipping heading levels (","type":"text"},{"text":"h1","type":"text","marks":[{"type":"code"}]},{"text":" followed by ","type":"text"},{"text":"h2","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"h2","type":"text","marks":[{"type":"code"}]},{"text":" followed by ","type":"text"},{"text":"h3","type":"text","marks":[{"type":"code"}]},{"text":",...):","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Levels should only be skipped when closing subsections (i.e. an h4 tag followed by an h2 tag to start a new section)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If a heading level is skipped, this could provide a negative experience to users as they may feel compelled to go back and look for the “missing” heading","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An exception to this rule is headings for fixed content (e.g. sidebars) where the rankings should not change depending on the ranks of the content area. Consistency across pages is more important","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"There should ONE ","type":"text"},{"text":"h1","type":"text","marks":[{"type":"code"}]},{"text":" per page/view and it should describe the overall purpose of the content.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If there is no ","type":"text"},{"text":"h1","type":"text","marks":[{"type":"code"}]},{"text":" in a mockup, you can add one with ","type":"text"},{"text":"className=\"sr-only\"","type":"text","marks":[{"type":"code"}]},{"text":" so only screen readers “see” it.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"

Hello world

","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Will be hidden from the view but AT will still pick up on it","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This doesn’t have to be the first heading element in the document but it usually is (see ","type":"text"},{"text":"this example","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://www.w3.org/WAI/tutorials/page-structure/headings/#main-heading-after-navigation"}}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The page title attribute (in the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element) should generally reflect or be a superset of the ","type":"text"},{"text":"h1","type":"text","marks":[{"type":"code"}]},{"text":" content. Example: ","type":"text"},{"text":"

Notes

","type":"text","marks":[{"type":"code"}]},{"text":" has ","type":"text"},{"text":"Notes | edx.org","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Change the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" whenever the H1 changes.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If possible, also push a new route onto the Back stack when the ","type":"text"},{"text":"h1","type":"text","marks":[{"type":"code"}]},{"text":" changes","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Aria attributes","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"aria-level","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Defines the hierarchical level of an element within a structure; when combined with ","type":"text"},{"text":"role=\"heading\"","type":"text","marks":[{"type":"code"}]},{"text":" will tell AT that the element is a heading. The “heading” role requires use of the ","type":"text"},{"text":"aria-level","type":"text","marks":[{"type":"code"}]},{"text":" attribute to indicate its position in the hierarchy.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"role=\"heading\"","type":"text","marks":[{"type":"code"}]},{"text":" without an ","type":"text"},{"text":"aria-level","type":"text","marks":[{"type":"code"}]},{"text":" attribute will default to an ","type":"text"},{"text":"h2","type":"text","marks":[{"type":"code"}]},{"text":", but you should include the ","type":"text"},{"text":"aria-level","type":"text","marks":[{"type":"code"}]},{"text":" attribute for clarity anyway.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This can even be done to ","type":"text"},{"text":"hN","type":"text","marks":[{"type":"code"}]},{"text":" tags if necessary","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"<div role=\"heading\" aria-level=\"3\">Hello World</div>","type":"text","marks":[{"type":"code"}]},{"text":" is the same as using an ","type":"text"},{"text":"h3","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This also enables devs to level headings beyond what is provided natively (","type":"text"},{"text":"h1","type":"text","marks":[{"type":"code"}]},{"text":" - ","type":"text"},{"text":"h6","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We could theoretically create an ","type":"text"},{"text":"h7","type":"text","marks":[{"type":"code"}]},{"text":" this way using ","type":"text"},{"text":"aria-level","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"All this being said, ","type":"text"},{"text":"you should still prioritize using native hN elements over ","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://www.a11y-collective.com/the-first-rule-for-using-aria/"}}]},{"text":"aria-level","type":"text","marks":[{"type":"underline"},{"type":"strong"},{"type":"link","attrs":{"href":"https://www.a11y-collective.com/the-first-rule-for-using-aria/"}}]},{"text":".","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"When this might be useful:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The main header for dialogs is, by convention, an ","type":"text"},{"text":"h2","type":"text","marks":[{"type":"code"}]},{"text":". If there is a request to use a different tag as the top-level in the dialog, then add ","type":"text"},{"text":"role=\"heading\"","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"aria-level=N","type":"text","marks":[{"type":"code"}]},{"text":" attributes to all headers as appropriate to start from level 2","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"aria-labelledby","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Can be used to associate headings with their page region","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This can be useful when there is more than one of the same sectioning element on a page (e.g. ","type":"text"},{"text":"<nav> <main> <header> <footer> <article>","type":"text","marks":[{"type":"code"}]},{"text":", full ","type":"text"},{"text":"list here","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTML/Element#content_sectioning"}}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"id","type":"text","marks":[{"type":"code"}]},{"text":" of the ","type":"text"},{"text":"hN","type":"text","marks":[{"type":"code"}]},{"text":" tag will need match the value of the parent element’s ","type":"text"},{"text":"aria-labelledby","type":"text","marks":[{"type":"code"}]},{"text":" attribute, and must be unique to the page.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"this example","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://www.w3.org/WAI/tutorials/page-structure/example/"}}]},{"text":" of ","type":"text"},{"text":"aria-labelledby","type":"text","marks":[{"type":"code"}]},{"text":" being used to differentiate two different <nav> elements","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You should generally use ","type":"text"},{"text":"aria-labelledby","type":"text","marks":[{"type":"code"}]},{"text":" to name all ","type":"text"},{"text":"<section>","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"<nav>","type":"text","marks":[{"type":"code"}]},{"text":" elements in this way when appropriate visible DOM elements are present (i.e. headings). If they're not present, then you can either use ","type":"text"},{"text":"aria-labelledby","type":"text","marks":[{"type":"code"}]},{"text":" with sr-only elements, or use ","type":"text"},{"text":"aria-label","type":"text","marks":[{"type":"code"}]},{"text":" (which takes a human-readable string, not a DOM ID)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Dialogs (","type":"text"},{"text":"div role=\"dialog\"","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"or ","type":"text"},{"text":"<dialog>`","type":"text","marks":[{"type":"code"}]},{"text":") need an accessible name, which generally comes from an ","type":"text"},{"text":"aria-label","type":"text","marks":[{"type":"code"}]},{"text":" attribute or ","type":"text"},{"text":"aria-labelledby","type":"text","marks":[{"type":"code"}]},{"text":" (pointing to the main header in the dialog).","type":"text"}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"hN","type":"text","marks":[{"type":"code"}]},{"text":" tags as CSS classes","type":"text"}]},{"type":"paragraph","content":[{"text":"Paragon provides a CSS class for each ","type":"text"},{"text":"hN","type":"text","marks":[{"type":"code"}]},{"text":" element (.h1, .h2, .h3,...). These do not provide any information for screen readers or accessibility. They are intended to change font-size and styling.","type":"text"}]},{"type":"paragraph","content":[{"text":"Because of this, you may encounter instances such as an ","type":"text"},{"text":"<h3>","type":"text","marks":[{"type":"code"}]},{"text":" tag being styled with an ","type":"text"},{"text":".h4","type":"text","marks":[{"type":"code"}]},{"text":" class:","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"<h3 className=\"h4\">Hello world</h3>","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"There is also a ","type":"text"},{"text":".heading-label","type":"text","marks":[{"type":"code"}]},{"text":" class. Worth noting that this doesn’t effect accessibility (has no relation to ","type":"text"},{"text":"aria-label","type":"text","marks":[{"type":"code"}]},{"text":") and is primarily for styling purposes.","type":"text"}]},{"type":"paragraph","content":[{"text":"See Paragon ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://paragon-openedx.netlify.app/foundations/typography"}},{"text":" for more information on which properties are provided in each class and how they can be implemented. ","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Resources","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://www.tpgi.com/heading-off-confusion-when-do-headings-fail-wcag/"}}]},{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://www.w3.org/WAI/tutorials/page-structure/headings/"}},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#nesting"}},{"text":" ","type":"text"}]}],"version":1}</article></body></html>