Various improvements to guides

Author: RoyalIcing

apps/components_guide_web/assets/css/app.css

@@ -102,7 +102,8 @@ blockquote {
 }
 hr {
   margin: var(--separator-spacing);
-  color: var(--separator-color);
+  border-color: var(--separator-color);
+  opacity: var(--separator-opacity);
 }
 
 input {
@@ -136,6 +137,7 @@ pre {
   --blockquote-background: rgba(255, 255, 255, 0.1);
   --separator-spacing: var(--size-5xl) 0;
   --separator-color: currentColor;
+  --separator-opacity: 0.333;
 }
 
 .row {

apps/components_guide_web/lib/components_guide_web/templates/accessibility_first/_nav.html.eex

@@ -2,10 +2,10 @@
   <ul y-y x-x=md class="text-lg font-bold text-shadow" style="--link-padding: 0.75em">
     <li><%= link("Why?", to: '/accessibility-first') %>
     <li><%= link("Navigation", to: '/accessibility-first/navigation') %>
-    <li><%= link("Roles", to: '/accessibility-first/roles') %>
-    <li><%= link("Accessible Name", to: '/accessibility-first/accessible-name') %>
+    <li><%= link("Content", to: '/accessibility-first/content') %>
     <li><%= link("Forms", to: '/accessibility-first/forms') %>
+    <li><%= link("All Roles", to: '/accessibility-first/roles') %>
+    <li><%= link("Accessible Name", to: '/accessibility-first/accessible-name') %>
     <li><%= link("Properties", to: '/accessibility-first/properties-cheatsheet') %>
-    <li><%= link("Content", to: '/accessibility-first/content') %>
   </ul>
 </nav>

apps/components_guide_web/lib/components_guide_web/templates/accessibility_first/content.html.md

@@ -1,13 +1,51 @@
-# Content
+# Semantic Content
 
-Coming soon…
+<table class="text-left table-fixed">
+  <caption class="text-3xl pb-4 text-left">Content roles cheatsheet</caption>
+  <thead>
+    <tr>
+      <th style="width: 12em">Role name</th>
+      <th>HTML element</th>
+    </tr>
+  </thead>
+  <tbody class="text-white bg-purple-900 border border-purple-700">
+    <%= table_rows([
+      ["**link**", "`<a href=…>`"],
+      ["_none!_", "`<a>`"],
+      ["**heading**", "`<h1>`, `<h2>`, `<h3>`, etc"],
+      ["**list**", "`<ul>`, `<ol>`"],
+      ["**listitem**", "`<li>`"],
+      ["**term**", "`<dt>`"],
+      ["**definition**", "`<dd>`"],
+      ["**img**", "`<img alt=\"Some description\">`"],
+      ["_none!_", "`<img alt=\"\">`"],
+      ["**figure**", "`<figure>`"],
+      ["**separator**", "`<hr>`, `<li role=separator>`"],
+      ["_none!_", "`<p>`"],
+      ["_none!_", "`<div>`"],
+      ["_none!_", "`<span>`"],
+      ["**group**", "`<details>`"],
+      ["**button**", "`<summary>`"],
+    ]) %>
+  </tbody>
+</table>
+
+## Search engines and other crawlers
+
+A crawler service that visits your website on behalf of a search engine like Google or social network like Instagram expects semantic content.
+
+Semantic HTML elements allow meaning and structure to be determined.
+
+More coming soon…
 
 ## Headings
 
 ## Lists
 
 ## Term & Definition
 
+## Images
+
 ## Figure
 
 ## Details & Summary

apps/components_guide_web/lib/components_guide_web/templates/accessibility_first/forms.html.md

@@ -1,3 +1,45 @@
+# Accessible Forms with Tests
+
+<table class="text-left table-fixed">
+  <caption class="text-3xl pb-4 text-left">Form roles cheatsheet</caption>
+  <thead>
+    <tr>
+      <th style="width: 12em">Role name</th>
+      <th>HTML snippet</th>
+    </tr>
+  </thead>
+  <tbody class="text-white bg-purple-900 border border-purple-700">
+    <%= table_rows([
+      ["**form**", "`<form>`"],
+      ["**search**", "`<form role=search>`"],
+      ["**group**", "`<fieldset>`"],
+      ["**button**", "`<button>`"],
+      ["**button**", "`<input type=button>`"],
+      ["**button**", "`<button type=submit>`, `<input type=submit>`"],
+      ["**textbox**", "`<textarea>`"],
+      ["**textbox**", "`<input type=text>`"],
+      ["**textbox**", "`<input type=email>`"],
+      ["**textbox**", "`<input type=tel>`"],
+      ["**textbox**", "`<input type=url>`"],
+      ["**searchbox**", "`<input type=search>` without `list` attribute"],
+      ["**radiogroup**", "`<fieldset role=radiogroup>`"],
+      ["**radio**", "`<input type=radio>`"],
+      ["**checkbox**", "`<input type=checkbox>`"],
+      ["**combobox**", "`<select>` without `multiple` attribute"],
+      ["**listbox**", "`<select>` with `multiple` attribute"],
+      ["**option**", "`<option>`"],
+      ["**slider**", "`<input type=range>`"],
+      ["_none_", "`<input type=password>`"],
+      ["**progressbar**", "`<progress>`"],
+      ["**status**", "`<output>`"],
+    ]) %>
+  </tbody>
+</table>
+
+_Note: The code examples here use [Testing Library](https://testing-library.com/), which works with React, Vue, Preact, Angular, Puppeteer, and more._
+
+----
+
 ## Form
 
 ```html
@@ -8,17 +50,19 @@
 ```
 
 ```js
-getByRole('form', { name: 'Sign up' });
+screen.getByRole('form', { name: 'Sign up' });
 ```
 
+----
+
 ## Button
 
 ```html
 <button>Save</button>
 ```
 
 ```js
-getByRole('button', { name: 'Save' });
+screen.getByRole('button', { name: 'Save' });
 ```
 
 ### Disabled
@@ -28,17 +72,19 @@ getByRole('button', { name: 'Save' });
 ```
 
 ```js
-expect(getByRole('button', { name: 'Save' })).toBeDisabled();
+expect(screen.getByRole('button', { name: 'Save' })).toBeDisabled();
 ```
 
+----
+
 ## Textbox
 
 ```html
 <label>Name <input type=text></label>
 ```
 
 ```js
-getByRole('textbox', { name: 'Name' });
+screen.getByRole('textbox', { name: 'Name' });
 ```
 
 ### Multilined
@@ -48,7 +94,7 @@ getByRole('textbox', { name: 'Name' });
 ```
 
 ```js
-getByRole('textbox', { name: 'Bio' });
+screen.getByRole('textbox', { name: 'Bio' });
 ```
 
 ### Specific types
@@ -60,9 +106,9 @@ getByRole('textbox', { name: 'Bio' });
 ```
 
 ```js
-const emailTextbox = getByRole('textbox', { name: 'Email' });
-const websiteTextbox = getByRole('textbox', { name: 'Website' });
-const phoneTextbox = getByRole('textbox', { name: 'Phone' });
+const emailTextbox = screen.getByRole('textbox', { name: 'Email' });
+const websiteTextbox = screen.getByRole('textbox', { name: 'Website' });
+const phoneTextbox = screen.getByRole('textbox', { name: 'Phone' });
 ```
 
 ### Expect value to match
@@ -73,28 +119,32 @@ const phoneTextbox = getByRole('textbox', { name: 'Phone' });
 
 ```js
 expect(
-  getByRole('textbox', { name: 'Bio' })
+  screen.getByRole('textbox', { name: 'Bio' })
 ).toHaveValue("Some bio");
 ```
 
+----
+
 ## Searchbox
 
 ```html
 <label>Search <input type=search></label>
 ```
 
 ```js
-getByRole('searchbox', { name: 'Search' });
+screen.getByRole('searchbox', { name: 'Search' });
 ```
 
+----
+
 ## Checkbox
 
 ```html
 <label><input type=checkbox> Receive email alerts</label>
 ```
 
 ```js
-getByRole('checkbox', { name: 'Receive email alerts' });
+screen.getByRole('checkbox', { name: 'Receive email alerts' });
 ```
 
 ### Expect to be checked
@@ -105,10 +155,11 @@ getByRole('checkbox', { name: 'Receive email alerts' });
 
 ```js
 expect(
-  getByRole('checkbox', { name: 'Receive email alerts' })
+  screen.getByRole('checkbox', { name: 'Receive email alerts' })
 ).toBeChecked();
 ```
 
+----
 
 ## Radio & Radiogroup
 
@@ -123,15 +174,15 @@ expect(
 ```
 
 ```js
-getByRole('radiogroup', { name: 'Favorite color' });
+screen.getByRole('radiogroup', { name: 'Favorite color' });
 ```
 
 ```js
-expect(getByRole('radio', { name: 'Red' })).toBeChecked();
+expect(screen.getByRole('radio', { name: 'Red' })).toBeChecked();
 ```
 
 ```js
 expect(
-  getByRole('radiogroup', { name: 'Favorite color' })
+  screen.getByRole('radiogroup', { name: 'Favorite color' })
 ).toHaveFormValues({ 'fave-color': 'red' });
 ```

apps/components_guide_web/lib/components_guide_web/templates/accessibility_first/intro.html.md

@@ -1,18 +1,19 @@
 # Why Consider Accessibility First?
 
-A mobile-first approach ensures that a phone experience, which many users now prefer and use regularly, is prioritised and is great. It helps combat the natural tendency for the mobile experience to be left behind.
+A mobile-first approach ensures that a phone experience, which many users now prefer and use regularly, is prioritised and is great. This approach helps combat the natural tendency for the mobile experience to be left behind.
 
-Similarly, an accessibility-first experience that the accessible experience, using screen readers and other assistive tech, is prioritised and is great.
+Similarly, an accessibility-first experience ensures that the experience using screen readers and other assistive tech is prioritised and is great.
 
-But the benefit goes further. Developers can use the accessibility affordances to write automated tests. And if they ensure it’s accessible right away, it provides predictable ways to write the tests upfront.
+But the benefit goes further, as developers can use the accessibility affordances to write automated tests. And if what they make is accessible immediately, it provides predictable ways to write the tests upfront. This leads to quicker development and greater reliability.
 
 ## Consider your HTML, no matter your framework
 
 HTML is not an after-thought, it’s not a ‘solved problem’, it’s not something you learn once and never have to study again. Especially in the world of web apps, it’s worth surveying the capabilities of today’s HTML and the affordances it can bring to every user.
 
 ## Accessibility Checklist for HTML
 
-1. **Landmarks:** provide familiar touch points that users can jump to
-2. **Semantics & Roles:** give every element semantic meaning
-3. **Widgets:** allow everyone to use your controls
-4. **Attributes:** sometimes sprinkling aria- attributes everywhere makes things less accessible
+1. **Links vs Buttons:** use links for navigating and buttons for actions.
+1. **Landmarks:** provide familiar touch points that users can jump to.
+2. **Semantics & Roles:** give every element semantic meaning.
+3. **Widgets:** allow everyone to use your controls.
+4. **Properties:** hide or mark elements using accessibility attributes.

apps/components_guide_web/lib/components_guide_web/templates/accessibility_first/landmarks.html.md

@@ -1,4 +1,4 @@
-# Navigation elements
+# Accessible Navigation
 
 ## Link vs Button
 

apps/components_guide_web/lib/components_guide_web/templates/accessibility_first/navigation.html.md

@@ -1,29 +1,5 @@
 ## Available Roles
 
-<table class="text-left table-fixed">
-  <thead>
-    <tr>
-      <th style="width: 12em">Role name</th>
-      <th>HTML element</th>
-    </tr>
-  </thead>
-  <tbody class="text-white bg-purple-900 border border-purple-700">
-    <%= table_rows([
-      ["**link**", "`<a href=…>`"],
-      ["_none_", "`<a>`"],
-      ["**button**", "`<button>`"],
-      ["**button**", "`<input type=button>`"],
-      ["**textbox**", "`<textarea>`"],
-      ["**textbox**", "`<input type=text>`"],
-      ["**radio**", "`<input type=radio>`"],
-      ["**heading**", "`<h1>`"],
-      ["**heading**", "`<h2>`"],
-      ["**heading**", "`<h3>`"],
-      ["**document**", "`<body>`"],
-    ]) %>
-  </tbody>
-</table>
-
 <table class="text-left table-fixed">
   <caption class="text-2xl">Landmarks</caption>
   <thead>