Merge pull request #30 from github/kh-better-heading-structure

docs: add recent primer common patterns links and better heading structures

Author: khiga8

docs/rules/accessibility/avoid-both-disabled-and-aria-disabled.md

@@ -9,14 +9,15 @@ HTML elements with `disabled` are ignored when a screen reader uses tab navigati
 
 This linter will raise when both `aria-disabled` and `disabled` are set on HTML elements that natively support `disabled` including `button`, `fieldset`, `input`, `optgroup`, `option`, `select`, and `textarea`.
 
-### 👎 Examples of **incorrect** code for this rule:
+## Examples
+### **Incorrect** code for this rule 👎
 
 ```erb
 <button aria-disabled="true" disabled="true">
 <input aria-disabled="true" disabled="true">
 ```
 
-### 👍 Examples of **correct** code for this rule:
+### **Correct** code for this rule  👍
 
 ```erb
 <button disabled="true">

docs/rules/accessibility/iframe-has-title.md

@@ -4,13 +4,14 @@
 
 `<iframe>` should have a unique title attribute that identifies the content. The title will help screen reader users determine whether to explore the frame in detail. If an `<iframe>` contains no meaningful content, hide it by setting `aria-hidden="true"`.
 
-### 👎 Examples of **incorrect** code for this rule:
+## Examples
+### **Incorrect** code for this rule 👎
 
 ```erb
 <iframe src="../welcome-video"></iframe>
 ```
 
-### 👍 Examples of **correct** code for this rule:
+### **Correct** code for this rule  👍
 
 ```erb
 <!-- good -->

docs/rules/accessibility/image-has-alt.md

@@ -4,15 +4,19 @@
 
 `<img>` should have an alt prop with meaningful text or an empty string for decorative images.
 
-Learn more at [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/).
+## Resources
 
-### 👎 Examples of **incorrect** code for this rule:
+- [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/)
+- [Primer: Alternative text for images](https://primer.style/design/accessibility/alternative-text-for-images)
+
+## Examples
+### **Incorrect** code for this rule 👎
 
 ```erb
 <img src="logo.png">
 ```
 
-### 👍 Examples of **correct** code for this rule:
+### **Correct** code for this rule  👍
 
 ```erb
 <!-- good -->

docs/rules/accessibility/no-aria-label-misuse-counter.md

@@ -6,24 +6,21 @@ This rule aims to discourage common misuse of the `aria-label` and `aria-labelle
 
 ### "Help! I'm trying to set a tooltip on a static element and this rule flagged it!"
 
-Please do not use tooltips on static elements. It is a highly discouraged, inaccessible pattern for the following reasons:
-
-- Static elements are not tab-focusable so keyboard-only users will not be able to access the tooltip at all. (Note: setting `tabindex="0"` to force a generic element to be focusable is not a solution.)
-- It's likely that tooltip is inappropriate for your usecase to begin with. Tooltips are not accessible at all on mobile devices so if you're trying to convey critical information, use something else. Additionally, implementing tooltip as `aria-label` is rarely appropriate and has potential to cause accessibility issues for screen reader users.
-
-If you've determined the tooltip content is not critical, simply remove it. If you determine the tooltip content is important to keep, we encourage you to reach out to a design or accessibility team who can assist in finding an alternate, non-tooltip pattern.
+Please do not use tooltips on static elements. It is a highly discouraged, inaccessible pattern.
+See [Primer: Tooltip alternatives](https://primer.style/design/accessibility/tooltip-alternatives) for what to do instead.
 
 ### Resources
 
 - [w3c/aria Consider prohibiting author naming certain roles #833](https://github.com/w3c/aria/issues/833)
 - [Not so short note on aria-label usage - Big Table Edition](https://html5accessibility.com/stuff/2020/11/07/not-so-short-note-on-aria-label-usage-big-table-edition/)
 - [Your tooltips are bogus](https://heydonworks.com/article/your-tooltips-are-bogus/)
+- [Primer: Tooltip alternatives](https://primer.style/design/accessibility/tooltip-alternatives)
 
 ### Disclaimer
 
 There are conflicting resources and opinions on what elements should support these naming attributes. For now, this rule will operate under a relatively simple heuristic aimed to minimize false positives. This may have room for future improvements. Learn more at [W3C Name Calcluation](https://w3c.github.io/aria/#namecalculation).
 
-### 👎 Examples of **incorrect** code for this rule:
+### **Incorrect** code for this rule 👎
 
 ```erb
 <span class="tooltipped" aria-label="This is a tooltip">I am some text.</span>
@@ -41,7 +38,7 @@ There are conflicting resources and opinions on what elements should support the
 <h1 aria-label="This will override the page title completely">Page title</h1>
 ```
 
-### 👍 Examples of **correct** code for this rule:
+### **Correct** code for this rule  👍
 
 ```erb
 <button aria-label="Close">

docs/rules/accessibility/no-positive-tab-index.md

@@ -9,14 +9,15 @@ Learn more at:
 - [A11yProject: Use the tabindex attribute](https://www.a11yproject.com/posts/how-to-use-the-tabindex-attribute/)
 - [Deque: Avoid using Tabindex with positive numbers](https://dequeuniversity.com/tips/tabindex-positive-numbers)
 
-### 👎 Examples of **incorrect** code for this rule:
+## Examples
+### **Incorrect** code for this rule 👎
 
 ```erb
 <button tabindex="3"></button>
 <button tabindex="1"></button>
 ```
 
-### 👍 Examples of **correct** code for this rule:
+### **Correct** code for this rule  👍
 
 ```erb
 <!-- good -->

docs/rules/accessibility/no-redundant-image-alt.md

@@ -7,9 +7,13 @@
 This rule does not discourage conveying the _medium_ of the image which may be considered important to help a user better understand the content.
 For example, this rule will not flag terms including `screenshot`, `painting`, or `photograph`.
 
-Learn more at [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/).
+## Resources
 
-### 👎 Examples of **incorrect** code for this rule:
+- [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/)
+- [Primer: Alternative text for images](https://primer.style/design/accessibility/alternative-text-for-images)
+
+## Examples
+### **Incorrect** code for this rule 👎
 
 ```erb
 <img alt="picture of Mona Lisa" src="monalisa.png">
@@ -20,7 +24,7 @@ Learn more at [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/
 <img alt="image of a fluffy dog" src="monalisa.png">
 ```
 
-### 👍 Examples of **correct** code for this rule:
+### **Correct** code for this rule  👍
 
 ```erb
 <!-- good -->

docs/rules/accessibility/no-title-attribute-counter.md

@@ -12,12 +12,13 @@ If you are considering the`title` attribute to provide supplementary description
 
 Use a `<title>` element instead of the `title` attribute, or an `aria-label`.
 
-### Resources
+## Resources
 
 - [TPGI: Using the HTML title attribute ](https://www.tpgi.com/using-the-html-title-attribute/)
 - [The Trials and Tribulations of the Title Attribute](https://www.24a11y.com/2017/the-trials-and-tribulations-of-the-title-attribute/)
 
-### 👎 Examples of **incorrect** code for this rule:
+## Examples
+### **Incorrect** code for this rule 👎
 
 ```erb
 <a title="A home for all developers" href="github.com">GitHub</a>
@@ -27,7 +28,7 @@ Use a `<title>` element instead of the `title` attribute, or an `aria-label`.
 <a href="/" title="github.com">GitHub</a>
 ```
 
-### 👍 Examples of **correct** code for this rule:
+### **Correct** code for this rule  👍
 
 ```erb
 <a href="github.com" aria-describedby="description">GitHub</a>