Add landmarks

Author: RoyalIcing

apps/components_guide_web/lib/components_guide_web/controllers/accessibility_first_controller.ex

@@ -6,10 +6,6 @@ defmodule ComponentsGuideWeb.AccessibilityFirstController do
     render(conn, "index.html", article: "intro")
   end
 
-  def show(conn, %{"id" => "landmarks"}) do
-    render(conn, "landmarks.html")
-  end
-
   def show(conn, %{"id" => "widgets-cheatsheet"}) do
     render(conn, "widgets-cheatsheet.html")
   end
@@ -18,7 +14,7 @@ defmodule ComponentsGuideWeb.AccessibilityFirstController do
     render(conn, "properties-cheatsheet.html")
   end
 
-  @articles ["navigation", "roles", "accessible-name", "forms", "content"]
+  @articles ["navigation", "landmarks", "roles", "accessible-name", "forms", "content"]
 
   def show(conn, %{"id" => article}) when article in @articles do
     render(conn, "index.html", article: article)

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

@@ -2,6 +2,7 @@
   <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("Landmarks", to: '/accessibility-first/landmarks') %>
     <li><%= link("Content", to: '/accessibility-first/content') %>
     <li><%= link("Forms", to: '/accessibility-first/forms') %>
     <li><%= link("All Roles", to: '/accessibility-first/roles') %>

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

@@ -14,6 +14,13 @@ HTML is not an after-thought, it’s not a ‘solved problem’, it’s not some
 
 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.
+2. **Semantic Content:** add meaningful structure to your content.
+3. **Usable Forms:** ensure form controls are labelled and have the correct roles.
+4. **Widgets:** allow everyone to use your controls.
+5. **Properties:** hide or mark elements using accessibility attributes.
+
+```ts
+getByRole('link', { name: 'About' });
+
+getByRole('button', { name: 'Sign up to newsletter' });
+```

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

@@ -0,0 +1,28 @@
+# Landmarks
+
+When you visit a new city, one thing you expect to see are landmarks. Statues, botanical gardens, theaters, skyscrapers, markets. These landmarks help us navigate around unfamiliar areas by being reference points we can see on the horizon or on a map.
+
+As makers of the web, we can also provide landmarks to people. These aren’t arbitrary — there are eight landmarks that are part of the HTML standard:
+
+- Navigation
+- Main
+- Banner
+- Search
+- Form
+- Content info
+- Region
+- Complementary
+
+Some of these seem obvious, but some are odd — what on earth does “contentinfo” mean? Let’s walk through what they are, why they are important to provide, and finally how we can really easily use them.
+
+## Navigation
+
+Nearly all websites have a primary navigation. It’s often presented as a row of links at the top of the page, or under a hamburger menu.
+
+![Stripe’s navigation bar at the top of its homepage][stripe-nav]
+
+Stripe’s navigation provides links to the primary pages people want to visit. It’s clear, and follows common practices of showing only a handful of links, and placing the link to sign in up on the far right.
+
+Most visual users would identify this as the primary navigation of the site, and so you should denote it as such in your HTML markup. Here’s what you might write for Stripe’s navigation:
+
+[stripe-nav]: https://icing.space/wp-content/uploads/2020/03/DraggedImage.77e7cbde60df4e08a4eac02d9ce73454-2048x134.png