Merge branch 'main' into patch-26

.markdownlint-cli2.jsonc

@@ -81,9 +81,9 @@
     }
   },
   "customRules": [
-    "./markdownlint/TOP001_descriptiveLinkText.js",
-    "./markdownlint/TOP002_noCodeInHeadings.js",
-    "./markdownlint/TOP003_defaultSectionContent.js",
-    "./markdownlint/TOP004_lessonHeadings.js"
+    "./markdownlint/TOP001_descriptiveLinkText/TOP001_descriptiveLinkText.js",
+    "./markdownlint/TOP002_noCodeInHeadings/TOP002_noCodeInHeadings.js",
+    "./markdownlint/TOP003_defaultSectionContent/TOP003_defaultSectionContent.js",
+    "./markdownlint/TOP004_lessonHeadings/TOP004_lessonHeadings.js"
   ]
 }

LAYOUT_STYLE_GUIDE.md

@@ -76,7 +76,7 @@ The following questions are an opportunity to reflect on key topics in this less
 
 ### Additional resources
 
-This section contains helpful links to related content. It isn’t required, so consider it supplemental.
+This section contains helpful links to related content. It isn't required, so consider it supplemental.
 
 - It looks like this lesson doesn't have any additional resources yet. Help us expand this section by contributing to our curriculum.
 

advanced_html_css/accessibility/accessibility_auditing.md

@@ -2,12 +2,12 @@
 
 Now that you are equipped with the necessary knowledge to make your websites more accessible to many users, the question arises: How can we verify the correct implementation of a11y features? Are there any mistakes to be corrected, or potential improvements to be made?  In this lesson, we will answer those questions to help push your a11y skills over the top.
 
-### Learning outcomes
+### Lesson overview
 
-By the end of this lesson, you should be able to:
+This section contains a general overview of topics that you will learn in this lesson.
 
-* Open the accessibility section within your browser's DevTools.
-* Audit a web page with a third-party auditing tool.
+- Open the accessibility section within your browser's DevTools.
+- Audit a web page with a third-party auditing tool.
 
 ### Accessibility DevTools
 

advanced_html_css/accessibility/accessible_colors.md

@@ -2,12 +2,13 @@
 
 Although adding color to a page can make it more visually appealing, using the wrong color combination or relying solely on color to convey information can end up making things more difficult to perceive and understand for some users. This doesn't mean you have to limit yourself when choosing color schemes for a website, but it does mean you have to take extra care when actually *using* those colors.
 
-### Learning outcomes
-By the end of this lesson, you should be able to:
+### Lesson overview
 
-* Understand what a contrast ratio is.
-* Know how to check contrast ratios.
-* Understand why color alone should not be used to convey information.
+This section contains a general overview of topics that you will learn in this lesson.
+
+- Understand what a contrast ratio is.
+- Know how to check contrast ratios.
+- Understand why color alone should not be used to convey information.
 
 ### Color contrast
 

advanced_html_css/accessibility/introduction_to_web_accessibility.md

@@ -4,9 +4,9 @@ At this point in the curriculum you've learned incredibly valuable concepts in w
 
 What you may not have too much an understanding of, though, is the topic of accessibility, often referred to as "a11y" (due to there being 11 letters between the first and last letters). Unfortunately, this is a topic that many people either don't know much about, or just don't take into account when developing websites. If you fit into either of those two categories, you may have adopted some habits that aren't exactly a11y friendly. Before we get into how you can break away from such habits and begin implementing a11y friendly concepts, it's important to first understand some basic information about web accessibility.
 
-### Learning outcomes
+### Lesson overview
 
-By the end of this lesson, you should be able to:
+This section contains a general overview of topics that you will learn in this lesson.
 
 - Explain what web accessibility is.
 

advanced_html_css/accessibility/keyboard_navigation.md

@@ -2,27 +2,29 @@
 
 Some users aren't able to use a mouse to navigate or operate their computer, and by extension the websites they visit. These users may instead rely on using a keyboard or another assistive technology that can simulate keyboard inputs, such as voice recognition software. Other users may even just prefer using a keyboard over a mouse, or may use a mix of both. These users require proper keyboard navigation, something that can easily be overlooked when developing a website.
 
-### Learning outcomes
-By the end of this lesson, you should be able to:
+### Lesson overview
 
-* Know the two things that interactive elements must have for keyboard users.
-* Understand what focus styles are and why you shouldn't completely remove them.
-* Understand what the tab order is.
-* Know how to properly hide hidden content from assistive technologies.
+This section contains a general overview of topics that you will learn in this lesson.
+
+- Know the two things that interactive elements must have for keyboard users.
+- Understand what focus styles are and why you shouldn't completely remove them.
+- Understand what the tab order is.
+- Know how to properly hide hidden content from assistive technologies.
 
 ### Focus
 
 Remember our Rock, Paper, Scissors example that *didn't* use semantic HTML from the... well, Semantic HTML lesson? Another issue with using `<div>` and `<span>` elements is that, by default, they aren't focusable and they don't have any event handling by default. In order to fix our non-semantic Rock, Paper, Scissors example for keyboard users, we would need to take some extra steps, similar to the below code snippets:
 
-~~~html
+```html
 <!-- The `tabindex` attribute makes the `<div>` elements focusable. -->
 <div class='button-container'>
   <div class='rock button' tabindex='0'>Rock</div>
   <div class='paper button' tabindex='0'>Paper</div>
   <div class='scissors button' tabindex='0'>Scissors</div>
 </div>
-~~~
-~~~javascript
+```
+
+```javascript
 // We also need to manually add in event handling for both mouse and keyboard events.
 const buttons = document.querySelectorAll('.button');
 
@@ -36,7 +38,7 @@ buttons.forEach(button => {
   button.addEventListener('click', nameAlerter)
   button.addEventListener('keydown', nameAlerter)
 })
-~~~
+```
 
 Of course, this example then makes it *less* understandable for screen reader users (remember, these "buttons" won't provide any context). Not only does using the `<button>` element provide the context screen reader users need, but they're focusable and have event handling for keyboards *by default*: pressing the <kbd>Space</kbd> or <kbd>Enter</kbd> keys on a keyboard when a `<button>` has focus will trigger the "click" event.
 
@@ -46,13 +48,13 @@ Of course, this example then makes it *less* understandable for screen reader us
 
 Another aspect of focusable elements is their focus styles, which are usually an outline or border surrounding the element when it receives focus. One of the things you may have done, or may still do, is completely remove these focus styles by using CSS rules similar to the example below:
 
-~~~css
+```css
 /* These are so ugh-ly! Let's get rid of them. */
 *:focus {
   outline: none;
   border: none;
 }
-~~~
+```
 
 You probably assume that you're about to be told not to do this. Well... **You should never completely remove focus styles**. You should either leave these default focus styles alone, or you should replace them with your own focus styles. Whether it's adding a `transform: scale()` CSS property to a button, adding an outline to a link, or increasing the border width and opacity on an input, adding your own focus styles is the only alternative you should consider to the default focus styles.
 
@@ -62,21 +64,21 @@ You probably assume that you're about to be told not to do this. Well... **You s
 
 The tab order is the order in which elements on the page will receive focus when pressing the <kbd>Tab</kbd> key, and is by default in the same order as the order of elements listed in the HTML file:
 
-~~~html
+```html
 <!-- This element is first in the tab order. -->
 <div tabindex='0'>This is the first element listed in the HTML.</div>
 
 <!-- This element is second in the tab order. -->
 <div tabindex='0'>This is the second element listed in the HTML.</div>
-~~~
+```
 
-Sometimes you may find it necessary to either change the visual order of elements on a page using CSS (the `float` or `order` properties, for example), or the tab order of elements themselves using the `tabindex` attribute. Regardless of which method you may use, you should make sure the tab order matches the visual order of elements. If the tab order is different from the visual order, users could be left confused or frustrated trying to navigate the page with a keyboard, expecting one element to receive focus based on the visual layout and instead another element receives focus. 
+Sometimes you may find it necessary to either change the visual order of elements on a page using CSS (the `float` or `order` properties, for example), or the tab order of elements themselves using the `tabindex` attribute. Regardless of which method you may use, you should make sure the tab order matches the visual order of elements. If the tab order is different from the visual order, users could be left confused or frustrated trying to navigate the page with a keyboard, expecting one element to receive focus based on the visual layout and instead another element receives focus.
 
 The best way to avoid this issue is to just place elements in your HTML file in the order that you want them to actually receive focus.
 
 ### Hidden content
 
-Sometimes you may want to hide some content until a specific event occurs, such as a user clicking on a button to open a menu or a modal box. When you want to hide content for this sort of purpose, you need to make sure the content is not only visually hidden, but also hidden from assistive technologies until that content is meant to be visible. 
+Sometimes you may want to hide some content until a specific event occurs, such as a user clicking on a button to open a menu or a modal box. When you want to hide content for this sort of purpose, you need to make sure the content is not only visually hidden, but also hidden from assistive technologies until that content is meant to be visible.
 
 If you don't properly hide such content, then keyboard users would be able to tab into that content before they're meant to, but in doing so they would lose track of any visual focus on the page. These users would be left confused or even frustrated when they're trying to tab through a page, only for their focus indicator to disappear into that hidden content.
 
@@ -91,16 +93,17 @@ One way to prevent this frustrating behavior is to give each individual item in
 </div>
 
 ### Knowledge check
-This section contains questions for you to check your understanding of this lesson. If you’re having trouble answering the questions below on your own, review the material above to find the answer.
 
-* [What are two things that interactive elements must have for keyboard users?](#interative-elements-keyboard)
-* [What are focus styles?](#focus-styles)
-* [Why should you never completely remove focus styles from an element?](#focus-never-remove)
-* [What is the tab order?](#tab-order)
-* [What is the best way to hide hidden content from assistive technologies?](#best-way-hide-content)
+The following questions are an opportunity to reflect on key topics in this lesson. If you can't answer a question, click on it to review the material, but keep in mind you are not expected to memorize or master this knowledge.
+
+- [What are two things that interactive elements must have for keyboard users?](#interative-elements-keyboard)
+- [What are focus styles?](#focus-styles)
+- [Why should you never completely remove focus styles from an element?](#focus-never-remove)
+- [What is the tab order?](#tab-order)
+- [What is the best way to hide hidden content from assistive technologies?](#best-way-hide-content)
 
 ### Additional resources
 
-This section contains helpful links to other content. It isn’t required, so consider it supplemental.
+This section contains helpful links to related content. It isn’t required, so consider it supplemental.
 
-* [Skip Links](https://webaim.org/techniques/skipnav/) are another form of accessibility for keyboard users and can be especially helpful for those who require more effort to tab through the contents of a page.
+- [Skip Links](https://webaim.org/techniques/skipnav/) are another form of accessibility for keyboard users and can be especially helpful for those who require more effort to tab through the contents of a page.