Add Link vs Button

Author: RoyalIcing

apps/components_guide_web/assets/css/app.css

@@ -9,50 +9,56 @@
 @import "../node_modules/nprogress/nprogress.css";
 
 :root {
-    @apply bg-gray-900;
+  @apply bg-gray-900;
 
-    --link-color: currentColor;
+  --link-color: currentColor;
 
-    --size-xs: .75rem;
-    --size-sm: .875rem;
-    --size-base: 1rem;
-    --size-lg: 1.125rem;
-    --size-xl: 1.25rem;
-    --size-2xl: 1.5rem;
-    --size-3xl: 1.875rem;
-    --size-4xl: 2.25rem;
-    --size-5xl: 3rem;
-    --size-6xl: 4rem;
+  --size-xs: 0.75rem;
+  --size-sm: 0.875rem;
+  --size-base: 1rem;
+  --size-lg: 1.125rem;
+  --size-xl: 1.25rem;
+  --size-2xl: 1.5rem;
+  --size-3xl: 1.875rem;
+  --size-4xl: 2.25rem;
+  --size-5xl: 3rem;
+  --size-6xl: 4rem;
 }
 
 [hidden] {
-    display: none !important;
+  display: none !important;
 }
 
 article a:not(nav *) {
-    text-decoration: underline;
+  text-decoration: underline;
 }
 article a:hover {
-    text-decoration: underline;
+  text-decoration: underline;
 }
 article figcaption {
   font-style: italic;
 }
 
 .a\{font-bold\} a {
-    font-weight: bold;
+  font-weight: bold;
 }
 
 a {
-    color: var(--link-color);
-    padding: var(--link-padding);
-    text-decoration: var(--link-decoration);
+  color: var(--link-color);
+  padding: var(--link-padding);
+  text-decoration: var(--link-decoration);
 }
 a:hover {
-    text-decoration: var(--hover\:links-decoration);
+  text-decoration: var(--hover\: links-decoration);
 }
 
-h1, h2, h3, p, li, table {
+h1,
+h2,
+h3,
+p,
+li,
+table,
+blockquote {
   margin-left: var(--item-spacing-left);
   margin-right: var(--item-spacing-right);
 }
@@ -87,6 +93,13 @@ table {
   padding: var(--code-spacing);
   border-radius: var(--code-radius);
 }
+blockquote {
+  --link-decoration: underline;
+  margin: var(--blockquote-spacing-outer);
+  padding: var(--blockquote-spacing-inner);
+  font-style: var(--blockquote-font-style);
+  background: var(--blockquote-background);
+}
 hr {
   margin: var(--separator-spacing);
   color: var(--separator-color);
@@ -96,7 +109,8 @@ input {
   outline: none;
 }
 
-:not(pre) > code, pre {
+:not(pre) > code,
+pre {
   color: white;
   background-color: #011627;
 }
@@ -116,6 +130,10 @@ input {
   --table-spacing: var(--size-xl) 0;
   --code-spacing: 0 0.1875em;
   --code-radius: 0.125em;
+  --blockquote-spacing-outer: 1rem 0rem;
+  --blockquote-spacing-inner: 1rem;
+  --blockquote-font-style: italic;
+  --blockquote-background: rgba(255, 255, 255, 0.1);
   --separator-spacing: var(--size-5xl) 0;
   --separator-color: currentColor;
 }
@@ -125,23 +143,23 @@ input {
 }
 
 .container {
-    @apply max-w-5xl mx-auto px-6;
+  @apply max-w-5xl mx-auto px-6;
 }
 
 .nums-tabular {
-    font-variant-numeric: tabular-nums;
+  font-variant-numeric: tabular-nums;
 }
 
 .text-shadow {
-    text-shadow: 0.0625em 0.0625em 0.125em rgba(0,0,0,0.25);
+  text-shadow: 0.0625em 0.0625em 0.125em rgba(0, 0, 0, 0.25);
 }
 
 ul:not([class]) {
-    list-style: disc;
-    padding-left: 1em;
+  list-style: disc;
+  padding-left: 1em;
 }
 ul:not([class]) > li > ul:not([class]) {
-    @apply pl-8;
+  @apply pl-8;
 }
 
 ol:not([class]) {
@@ -150,13 +168,13 @@ ol:not([class]) {
 }
 
 /* Navigation links */
-a[aria-current=page][class*="hover\:border-"] {
-    border-color: currentColor;
+a[aria-current="page"][class*="hover\:border-"] {
+  border-color: currentColor;
 }
 
-[phx-hook=SwatchInput] {
-   user-select: none;
-   cursor: default;
+[phx-hook="SwatchInput"] {
+  user-select: none;
+  cursor: default;
 }
 
 /* @import "./phoenix.css"; */

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

@@ -1,6 +1,6 @@
 <nav class="pt-6 pb-4">
   <ul y-y x-x=md class="text-lg font-bold text-shadow" style="--link-padding: 0.75em">
-    <li><%= link("Intro", to: '/accessibility-first') %>
+    <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') %>

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

@@ -1,5 +1,49 @@
 # Navigation elements
 
+## Link vs Button
+
+Links are the ‘secret ingredient’ of the web. They take web pages from being standalone documents to being part of a living, collaborative medium.
+
+As a web author, it’s easy to mix up links and buttons, especially when everything is styled to look like a rounded capsule. However, there are clear rules you can follow for when to use links and when to use buttons.
+
+Here’s what users like to do with links:
+
+- They can open a link in a new tab.
+- They can share that link with someone else so they can arrive at the same place.
+- They can bookmark that link for later.
+
+Let’s see how the specs describe links:
+
+> [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1/#link) — An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource.
+
+So how are buttons different?
+
+Clicking a button usually produces a change of some sort. For example, a Checkout action should be a button and not a link, because that action changes the state of the shopping cart. It makes little sense to be able to look at the shopping cart before it was checked out.
+
+In contrast to a link:
+
+- The user shouldn’t be able to open Checkout in a new tab.
+- The user can’t share Checkout with someone else.
+- The user can’t bookmark Checkout for later.
+
+> [WAI-ARIA Practices](https://www.w3.org/TR/wai-aria-practices/#button) — A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.
+
+Let’s look the example of an online store, and categorize things into links or buttons:
+
+- The Product Name _links_ to the page dedicated to this product.
+- The Add to Wishlist _button_ performs the add to wishlist action.
+- The Checkout _button_ changes the state of the shopping cart.
+- The Product Image _link_ opens the product photo gallery.
+- The More Details _button_ expands to show the full specifications of the product.
+
+----
+
+In short, buttons **perform actions** and links **navigate somewhere**. Links have URLs that can be shared or copied, and buttons cannot be shared.
+
+Every element of a UI mockup should be very clear which model they use. How these elements work is part of the design.
+
+----
+
 ## Link
 
 ```html
@@ -10,22 +54,20 @@
 const aboutLink = screen.getByRole('link', { name: 'About' });
 ```
 
-### Current link
+### When the link is the current page
 
 ```html
 <a href="/about" aria-current=page>About</a>
 ```
 
 ```ts
+const aboutLink = screen.getByRole('link', { name: 'About' });
 expect(aboutLink).toHaveAttribute('aria-current', 'page');
 ```
 
-## Navigation
+----
 
-```ts
-const primaryNav = screen.getByRole('navigation', { name: 'Primary' });
-const navLinks = getAllByRole(primaryNav, 'link');
-```
+## Navigation
 
 ```html
 <nav aria-label=Primary>
@@ -36,3 +78,10 @@ const navLinks = getAllByRole(primaryNav, 'link');
   </ul>
 </nav>
 ```
+
+```ts
+const primaryNav = screen.getByRole('navigation', { name: 'Primary' });
+const navLinks = getAllByRole(primaryNav, 'link');
+
+expect(navLinks).toHaveLength(3);
+```