diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index fb53fcdbc3c..e1497c04292 100644 --- a/.markdownlint-cli2.jsonc +++ b/.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" ] } diff --git a/LAYOUT_STYLE_GUIDE.md b/LAYOUT_STYLE_GUIDE.md index 48731991ce9..ae5fd1d0ac7 100644 --- a/LAYOUT_STYLE_GUIDE.md +++ b/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. diff --git a/advanced_html_css/accessibility/accessibility_auditing.md b/advanced_html_css/accessibility/accessibility_auditing.md index 4a8a876c83a..9d561ccd8b2 100644 --- a/advanced_html_css/accessibility/accessibility_auditing.md +++ b/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 diff --git a/advanced_html_css/accessibility/accessible_colors.md b/advanced_html_css/accessibility/accessible_colors.md index 2990dfd31f1..b355ab0cb7e 100644 --- a/advanced_html_css/accessibility/accessible_colors.md +++ b/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 diff --git a/advanced_html_css/accessibility/introduction_to_web_accessibility.md b/advanced_html_css/accessibility/introduction_to_web_accessibility.md index 2106d6fdd44..2b78b1e921c 100644 --- a/advanced_html_css/accessibility/introduction_to_web_accessibility.md +++ b/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. diff --git a/advanced_html_css/accessibility/keyboard_navigation.md b/advanced_html_css/accessibility/keyboard_navigation.md index 7bf6a6a2fe0..0d0973ad5ab 100644 --- a/advanced_html_css/accessibility/keyboard_navigation.md +++ b/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 `
` and `` 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
Rock
Paper
Scissors
-~~~ -~~~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 `
### 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. diff --git a/advanced_html_css/accessibility/meaningful_text.md b/advanced_html_css/accessibility/meaningful_text.md index 70379b575a9..cf71aa213f0 100644 --- a/advanced_html_css/accessibility/meaningful_text.md +++ b/advanced_html_css/accessibility/meaningful_text.md @@ -2,41 +2,43 @@ Meaningful text is pretty straight forward: when a user reads text or has it announced to them, they should be able to immediately understand what it means even without any surrounding context. A lack of meaningful text can affect all users, but especially those who rely on assistive technologies. In this lesson we'll be going over a few instances where you should start making sure you provide meaningful text to users. -### Learning outcomes -By the end of this lesson, you should be able to: +### Lesson overview -* Know how to provide meaningful links. -* Know how to provide meaningful text in forms. -* Know how to provide meaningful `alt` attributes for images. +This section contains a general overview of topics that you will learn in this lesson. + +- Know how to provide meaningful links. +- Know how to provide meaningful text in forms. +- Know how to provide meaningful `alt` attributes for images. ### Links + Let's take a look at two different examples of a link: -~~~html +```html Click here to start your career in web development! Visit The Odin Project to start your career in web development! -~~~ +``` To a sighted user, the link in Example 1 makes perfect sense. However, in addition to being able to navigate a page via landmarks and headings (as mentioned in the Semantic HTML lesson), a screen reader may be able to navigate between each element of a specific type, such as links. If a user were to navigate between all of the links on a page, the only thing that would get announced in Example 1 is, "Click here, link." Where's "here" exactly? Without any surrounding context, the link is meaningless. Not only that, but if you have multiple links on a page with that same text content, then users will be told to "click here" many times. -The link in Example 2, however, not only makes sense in context for all users, but it also makes sense *out of context* for screen reader users when it gets announced: "The Odin Project, link." +The link in Example 2, however, not only makes sense in context for all users, but it also makes sense *out of context* for screen reader users when it gets announced: "The Odin Project, link." When you add links to a page, there are a few rules you should be following: 1. Make sure that the text content of the `` element somehow indicates where the link redirects to and that it's brief (around 100 characters). So avoid using phrases like "click here" or "this page". -2. If a link would open or download a file, include text that tells the user what kind of file it is as well as the file size. -3. If a link would automatically open in a new tab or window with the `target="_blank"` attribute, you should indicate this to the user in some way. +1. If a link would open or download a file, include text that tells the user what kind of file it is as well as the file size. +1. If a link would automatically open in a new tab or window with the `target="_blank"` attribute, you should indicate this to the user in some way. -~~~html +```html 2021 Sign Up Statistics (PDF, 1MB) GitHub (opens in new tab) -~~~ +``` The next time you need to use links, try saying the contents of the element out loud to yourself. Does it reasonably indicate where that link would take you, such as the title of the page, article, or video? Are you aware whether it'll open in a new tab automatically or not, or that it'll open a download dialog? If you've been testing out using a screen reader up to this point, then an even better way to test whether a link has meaningful text is with the screen reader itself! @@ -44,7 +46,7 @@ The next time you need to use links, try saying the contents of the element out Providing meaningful errors to users when they are filling out or submitting a form can turn the experience from frustrating to... well, maybe not fun, but at the very least just a bit less frustrating. Let's take a look at a few error examples, ranging from not helpful at all to very helpful: -~~~html +```html
Error: Invalid input.
@@ -53,7 +55,7 @@ Providing meaningful errors to users when they are filling out or submitting a f
Error: 'JohnSmith@@test.com' is not valid. Example of a valid email: example@yourdomain.com.
-~~~ +``` Even if you could tell what input caused the error in Example 1, which may not always be the case, the error doesn't provide any meaningful text. What input is invalid? Why is it invalid? How can you fix it? None of these questions are answered. Now imagine how meaningless this error must be to users of assistive technologies, who may not be able to see where an error is rendered on the page and may only have "invalid input" announced to them. @@ -67,28 +69,29 @@ Another way to provide meaningful text in forms is with instructions, such as wh At this point you should be pretty familiar with the `alt` attribute on `img` elements. Whether you are or not, let's see if you can tell which of the following examples is valid: -~~~html +```html Odin -~~~ +``` Believe it or not, both examples above are valid! While Example 1 doesn't actually have any meaningful text (perhaps a meaningful *lack of* text), you should still understand its importance. When you're using an image purely for decoration, or the image just isn't really important for the user to be aware of, you generally don't want users of assistive technologies to be made aware of it. In those cases, you should **always** use an empty string for the value of the `alt` attribute as seen in Example 1 (this is also known as a null value, not to be confused with the JavaScript data type). If you omitted the `alt` attribute, the presence of the image could still be announced, which may confuse the user (especially if the file name was a random string of letters and numbers). For Example 2, the screen reader would announce, "Odin, graphic", making the user aware that there's an image and what it's an image of. What the alternative text should be for an image will ultimately depend on various factors, though. Read [Alternative Text - WebAIM](https://webaim.org/techniques/alttext) to learn about when and how you should be adding alternative text for images based on the function of the image and the context surrounding it. ### 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 three rules you should follow in order to provide meaningful links?](#meaningful-links-rules) -* [What information should you inform users of in order to provide meaningful error messages in forms?](#meaningful-error-msg) -* [When should you use the empty string/null value for the `alt` attribute?](#empty-alt-attribute) +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 three rules you should follow in order to provide meaningful links?](#meaningful-links-rules) +- [What information should you inform users of in order to provide meaningful error messages in forms?](#meaningful-error-msg) +- [When should you use the empty string/null value for the `alt` attribute?](#empty-alt-attribute) ### 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. -* [Making Accessible Links: 15 Golden Rules For Developers](https://www.sitepoint.com/15-rules-making-accessible-links/) is a little old, but is still a great list of 15 rules for creating, well, accessible links. Some of the rules the article goes over were mentioned in this lesson, but there are some other rules that can help make sure you're creating a11y friendly links. -* [Usable and Accessible Form Validation and Error Recovery](https://webaim.org/techniques/formvalidation/) goes over a few different ways you can provide errors to users (using the `alert` in JavaScript, providing all errors at the top of the page, and using inline errors), as well as the pros and cons of each. +- [Making Accessible Links: 15 Golden Rules For Developers](https://www.sitepoint.com/15-rules-making-accessible-links/) is a little old, but is still a great list of 15 rules for creating, well, accessible links. Some of the rules the article goes over were mentioned in this lesson, but there are some other rules that can help make sure you're creating a11y friendly links. +- [Usable and Accessible Form Validation and Error Recovery](https://webaim.org/techniques/formvalidation/) goes over a few different ways you can provide errors to users (using the `alert` in JavaScript, providing all errors at the top of the page, and using inline errors), as well as the pros and cons of each. diff --git a/advanced_html_css/accessibility/semantic_html.md b/advanced_html_css/accessibility/semantic_html.md index 33342a22919..33ce100b94a 100644 --- a/advanced_html_css/accessibility/semantic_html.md +++ b/advanced_html_css/accessibility/semantic_html.md @@ -2,41 +2,42 @@ As useful as `
` and `` elements can be as generic containers, they're not always the most a11y friendly elements to use. While it may be tempting or easier to just use them for everything, from containers to interactive areas, you should not only check whether there is a more appropriate element to use in certain situations, but also whether you're using an element correctly. -### Learning outcomes -By the end of this lesson, you should be able to: +### Lesson overview -* Explain why semantic HTML is important for accessibility. -* Name the seven HTML elements that define landmarks on a page. +This section contains a general overview of topics that you will learn in this lesson. + +- Explain why semantic HTML is important for accessibility. +- Name the seven HTML elements that define landmarks on a page. ### The importance of semantics -In terms of web accessibility, using semantic HTML is important because it provides meaning and context. Some elements have a *semantic meaning*, but don't really provide any *context* when announced by assistive technologies, such as the `

` element. Then there are elements that have a semantic meaning *and* are announced with some sort of context to help users perceive or operate them, like a `

-~~~ +``` Because the `