@@ -1,41 +1,27 @@
 ---
 name: Links as buttons
-description: Any button variant renders as an anchor when href is set, so buttons that navigate elsewhere still look and behave like the intended variant.
+description: Buttons that link to another resource may take the form of primary, secondary, tertiary, or link variants. Set the href attribute to designate the button's target link.
 ---
 
 <section>
-  <pf-v6-button href="https://www.w3.org/TR/WCAG20-TECHS/ARIA8.html#ARIA8-examples"
-    >Primary link to W3.org</pf-v6-button
+  <pf-v6-button href="https://www.patternfly.org/" target="_blank"
+    >Link to PatternFly home</pf-v6-button
   >
   <pf-v6-button
     variant="secondary"
-    href="#overview"
-    accessible-label="Read more about button documentation"
-    >Secondary link to anchor</pf-v6-button
-  >
-  <pf-v6-button
-    variant="secondary"
-    danger
-    href="#overview"
-    accessible-label="Read more about button documentation"
-    >Secondary danger link to anchor</pf-v6-button
+    href="https://www.patternfly.org/"
+    target="_blank"
+    >Secondary link to PatternFly home</pf-v6-button
   >
   <pf-v6-button
     variant="tertiary"
-    href="https://www.w3.org/TR/WCAG20-TECHS/ARIA8.html#ARIA8-examples"
-    disabled-focusable
-    >Tertiary link to W3.org</pf-v6-button
+    href="https://www.patternfly.org/"
+    target="_blank"
+    disabled
+    >Tertiary link to PatternFly home</pf-v6-button
   >
-  <pf-v6-button
-    variant="link"
-    href="https://www.w3.org/TR/WCAG20-TECHS/ARIA8.html#ARIA8-examples"
-    >Link to W3.org</pf-v6-button
-  >
-  <pf-v6-button
-    variant="link"
-    danger
-    href="https://www.w3.org/TR/WCAG20-TECHS/ARIA8.html#ARIA8-examples"
-    >Link danger to W3.org</pf-v6-button
+  <pf-v6-button variant="link" href="https://www.patternfly.org/"
+    >Jump to PatternFly home</pf-v6-button
   >
 </section>
 
 
@@ -1,10 +1,10 @@
 ---
 name: Plain with no padding
-description: Use no-padding with variant="plain" for when a plain/icon button is placed inline with text.
+description: To display a plain/icon button inline with text, use the no-padding attribute in addition to variant="plain".
 ---
 
 <p>
-  For when a plain/icon button is placed inline with text
+  This is an example of a button
   <pf-v6-button variant="plain" no-padding accessible-label="More info">
     <svg
       slot="icon"
@@ -15,10 +15,11 @@
       aria-hidden="true"
     >
       <path
-        d="M16 1C7.729 1 1 7.729 1 16s6.729 15 15 15 15-6.729 15-15S24.271 1 16 1Zm0 28C8.832 29 3 23.168 3 16S8.832 3 16 3s13 5.832 13 13-5.832 13-13 13Zm5-17a5.008 5.008 0 0 1-4 4.899V19a1 1 0 0 1-2 0v-3a1 1 0 0 1 1-1c1.654 0 3-1.346 3-3s-1.346-3-3-3-3 1.346-3 3a1 1 0 0 1-2 0c0-2.757 2.243-5 5-5s5 2.243 5 5Zm-3.25 12a1.75 1.75 0 1 1-3.501-.001A1.75 1.75 0 0 1 17.75 24Z"
+        d="M16 1C7.729 1 1 7.729 1 16s6.729 15 15 15 15-6.729 15-15S24.271 1 16 1Zm0 26.014a2 2 0 1 1-.001-3.999A2 2 0 0 1 16 27.014Zm1.25-9.914V19a1.25 1.25 0 0 1-2.5 0v-3c0-.69.56-1.25 1.25-1.25 1.517 0 2.75-1.233 2.75-2.75S17.517 9.25 16 9.25s-2.75 1.233-2.75 2.75a1.25 1.25 0 0 1-2.5 0c0-2.895 2.355-5.25 5.25-5.25s5.25 2.355 5.25 5.25a5.26 5.26 0 0 1-4 5.1Z"
       ></path>
     </svg>
-  </pf-v6-button>.
+  </pf-v6-button>
+  which is placed inline with text
 </p>
 
 <script type="module">
 
@@ -1,29 +1,20 @@
 ---
 name: Progress
-description: Set loading="false" to reserve progress padding without a spinner, and loading (or loading="true") to show the spinner and in-progress styling.
+description: Progress indicators can be added to buttons to identify that an action is in progress after a click.
 ---
 
-<pf-v6-button loading="false">Primary loader</pf-v6-button>
-<pf-v6-button loading>Primary loading</pf-v6-button>
+<pf-v6-button id="primary-loading-button" loading
+  >Click to stop loading</pf-v6-button
+>
+<pf-v6-button
+  id="secondary-loading-button"
+  variant="secondary"
+  loading
+  loading-label="Content being loaded"
+  >Click to stop loading</pf-v6-button
+>
 <br />
-<pf-v6-button variant="secondary" loading="false">Secondary loader</pf-v6-button>
-<pf-v6-button variant="secondary" loading>Secondary loading</pf-v6-button>
-<br />
-<pf-v6-button variant="plain" accessible-label="Upload">
-  <svg
-    slot="icon"
-    fill="currentColor"
-    height="1em"
-    width="1em"
-    viewBox="0 0 512 512"
-    aria-hidden="true"
-  >
-    <path
-      d="M296 384h-80c-13.3 0-24-10.7-24-24V192h-87.7c-17.8 0-26.7-21.5-14.1-34.1L242.3 5.7c7.5-7.5 19.8-7.5 27.3 0l152.2 152.2c12.6 12.6 3.7 34.1-14.1 34.1H320v168c0 13.3-10.7 24-24 24zm216-8v112c0 13.3-10.7 24-24 24H24c-13.3 0-24-10.7-24-24V376c0-13.3 10.7-24 24-24h136v8c0 30.9 25.1 56 56 56h80c30.9 0 56-25.1 56-56v-8h136c13.3 0 24 10.7 24 24zm-124 88c0-11-9-20-20-20s-20 9-20 20 9 20 20 20 20-9 20-20zm64 0c0-11-9-20-20-20s-20 9-20 20 9 20 20 20 20-9 20-20z"
-    ></path>
-  </svg>
-</pf-v6-button>
-<pf-v6-button variant="plain" loading loading-label="Uploading...">
+<pf-v6-button id="upload-button" variant="plain" accessible-label="Upload" loading-label="Uploading data">
   <svg
     slot="icon"
     fill="currentColor"
@@ -38,9 +29,35 @@
   </svg>
 </pf-v6-button>
 <br />
-<pf-v6-button variant="link" inline loading="false">Inline loader</pf-v6-button>
-<pf-v6-button variant="link" inline loading>Inline loading</pf-v6-button>
+<br />
+<pf-v6-button
+  id="inline-loading-button"
+  variant="link"
+  inline
+  loading
+  loading-label="Content being loaded"
+  >Pause loading logs</pf-v6-button
+>
 
 <script type="module">
   import '@patternfly/elements/pf-v6-button/pf-v6-button.js';
+
+  function wireTextToggle(id, onText, offText) {
+    const button = document.getElementById(id);
+    button.addEventListener('click', () => {
+      button.loading = !button.loading;
+      button.textContent = button.loading ? onText : offText;
+    });
+  }
+
+  wireTextToggle('primary-loading-button', 'Click to stop loading', 'Click to start loading');
+  wireTextToggle('secondary-loading-button', 'Click to stop loading', 'Click to start loading');
+  wireTextToggle('inline-loading-button', 'Pause loading logs', 'Resume loading logs');
+
+  const uploadButton = document.getElementById('upload-button');
+  uploadButton.loading = false;
+  uploadButton.addEventListener('click', () => {
+    uploadButton.loading = !uploadButton.loading;
+    uploadButton.accessibleLabel = uploadButton.loading ? '' : 'Upload';
+  });
 </script>
@@ -1,6 +1,6 @@
 ---
 name: Settings
-description: Settings buttons use the settings attribute with variant="plain" and animate the gear icon on hover and focus.
+description: For a settings button with animations on hover and focus, use the settings attribute with either variant="plain" or variant="control".
 ---
 
 <section>
@@ -9,6 +9,7 @@
     settings
     accessible-label="Settings"
   ></pf-v6-button>
+  <pf-v6-button variant="control" settings>Settings</pf-v6-button>
 </section>
 
 <script type="module">
 
@@ -1,70 +1,16 @@
 ---
 name: Small buttons
-description: Every button variant can use size="sm" to fit tight spaces.
+description: To fit into tight spaces, primary, secondary, tertiary, danger, and warning button variations can be made smaller using the sm value for the size attribute.
 ---
 
 <section>
   <pf-v6-button size="sm">Primary</pf-v6-button>
   <pf-v6-button size="sm" variant="secondary">Secondary</pf-v6-button>
-  <pf-v6-button size="sm" variant="secondary" danger>Secondary danger</pf-v6-button>
   <pf-v6-button size="sm" variant="tertiary">Tertiary</pf-v6-button>
   <pf-v6-button size="sm" variant="danger">Danger</pf-v6-button>
   <pf-v6-button size="sm" variant="warning">Warning</pf-v6-button>
 </section>
 
-<section>
-  <pf-v6-button size="sm" variant="link">Link</pf-v6-button>
-  <pf-v6-button size="sm" variant="link" danger>Link danger</pf-v6-button>
-  <pf-v6-button size="sm" variant="link" inline>Inline link</pf-v6-button>
-  <pf-v6-button size="sm" variant="plain" accessible-label="Remove">
-    <svg
-      slot="icon"
-      fill="currentColor"
-      height="1em"
-      width="1em"
-      viewBox="0 0 20 20"
-      aria-hidden="true"
-    >
-      <path
-        d="M17.8 16.2 11.59 10l6.21-6.21c.42-.46.39-1.17-.07-1.59-.43-.4-1.09-.4-1.52 0l-6.2 6.2-6.22-6.19c-.44-.44-1.15-.44-1.59 0-.44.44-.44 1.15 0 1.59l6.2 6.21-6.2 6.2c-.42.46-.39 1.17.07 1.59.43.4 1.09.4 1.52 0L10 11.59l6.2 6.2c.44.44 1.15.44 1.59 0 .44-.45.44-1.16 0-1.6Z"
-      ></path>
-    </svg>
-  </pf-v6-button>
-  <pf-v6-button size="sm" variant="plain">
-    <svg
-      slot="icon"
-      fill="currentColor"
-      height="1em"
-      width="1em"
-      viewBox="0 0 20 20"
-      aria-hidden="true"
-    >
-      <path
-        d="M17.8 16.2 11.59 10l6.21-6.21c.42-.46.39-1.17-.07-1.59-.43-.4-1.09-.4-1.52 0l-6.2 6.2-6.22-6.19c-.44-.44-1.15-.44-1.59 0-.44.44-.44 1.15 0 1.59l6.2 6.21-6.2 6.2c-.42.46-.39 1.17.07 1.59.43.4 1.09.4 1.52 0L10 11.59l6.2 6.2c.44.44 1.15.44 1.59 0 .44-.45.44-1.16 0-1.6Z"
-      ></path>
-    </svg>
-    Plain with text
-  </pf-v6-button>
-</section>
-
-<section>
-  <pf-v6-button size="sm" variant="control">Control</pf-v6-button>
-  <pf-v6-button size="sm" variant="control" accessible-label="Copy input">
-    <svg
-      slot="icon"
-      fill="currentColor"
-      height="1em"
-      width="1em"
-      viewBox="0 0 32 32"
-      aria-hidden="true"
-    >
-      <path
-        d="M28 7v22.607c0 .768-.622 1.393-1.387 1.393H10a1 1 0 1 1 0-2h16V7a1 1 0 1 1 2 0Zm-6.5 19h-16c-.827 0-1.5-.673-1.5-1.5V8a1.001 1.001 0 0 1 .294-.708l5.998-5.998A1.001 1.001 0 0 1 11 1h10.5c.827 0 1.5.673 1.5 1.5v22c0 .827-.673 1.5-1.5 1.5ZM7.414 7H10V4.414L7.414 7ZM21 3h-9v4.614C12 8.378 11.378 9 10.613 9H6v15h15V3Z"
-      ></path>
-    </svg>
-  </pf-v6-button>
-</section>
-
 <script type="module">
   import '@patternfly/elements/pf-v6-button/pf-v6-button.js';
 </script>
@@ -75,6 +21,5 @@
     flex-wrap: wrap;
     gap: 0.5rem;
     align-items: center;
-    margin-block-end: 1rem;
   }
 </style>
@@ -1,62 +1,54 @@
 ---
 name: Stateful
-description: Stateful buttons communicate notification state with variant="stateful" and state set to read, unread, or attention. Set clicked to force the clicked/active styling.
+description: Stateful buttons communicate notification state with variant="stateful" and state set to read, unread (default), or attention.
 ---
 
-<strong>Read</strong>
-<br />
-<pf-v6-button variant="stateful" state="read">
-  <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
-    <path d="M28.75 22v3.5c0 .689-.561 1.25-1.25 1.25h-7.521c.005.084.021.166.021.25 0 2.206-1.794 4-4 4s-4-1.794-4-4c0-.084.016-.166.021-.25H4.5c-.689 0-1.25-.561-1.25-1.25V22a.75.75 0 0 1 .75-.75c1.24 0 2.25-1.009 2.25-2.25v-4c0-4.826 3.528-8.833 8.138-9.605A2.482 2.482 0 0 1 13.5 3.5C13.5 2.122 14.621 1 16 1s2.5 1.122 2.5 2.5c0 .761-.349 1.436-.888 1.895 4.61.772 8.138 4.779 8.138 9.605v4c0 1.241 1.01 2.25 2.25 2.25a.75.75 0 0 1 .75.75Z"></path>
-  </svg>
-  10<span class="pf-v6-screen-reader">items</span>
-</pf-v6-button>
-<pf-v6-button variant="stateful" state="read" clicked>
-  <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
-    <path d="M28.75 22v3.5c0 .689-.561 1.25-1.25 1.25h-7.521c.005.084.021.166.021.25 0 2.206-1.794 4-4 4s-4-1.794-4-4c0-.084.016-.166.021-.25H4.5c-.689 0-1.25-.561-1.25-1.25V22a.75.75 0 0 1 .75-.75c1.24 0 2.25-1.009 2.25-2.25v-4c0-4.826 3.528-8.833 8.138-9.605A2.482 2.482 0 0 1 13.5 3.5C13.5 2.122 14.621 1 16 1s2.5 1.122 2.5 2.5c0 .761-.349 1.436-.888 1.895 4.61.772 8.138 4.779 8.138 9.605v4c0 1.241 1.01 2.25 2.25 2.25a.75.75 0 0 1 .75.75Z"></path>
-  </svg>
-  10<span class="pf-v6-screen-reader">items</span>
-</pf-v6-button>
-
-<br /><br />
-
-<strong>Unread</strong>
-<br />
-<pf-v6-button variant="stateful" state="unread">
-  <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
-    <path d="M28.75 22v3.5c0 .689-.561 1.25-1.25 1.25h-7.521c.005.084.021.166.021.25 0 2.206-1.794 4-4 4s-4-1.794-4-4c0-.084.016-.166.021-.25H4.5c-.689 0-1.25-.561-1.25-1.25V22a.75.75 0 0 1 .75-.75c1.24 0 2.25-1.009 2.25-2.25v-4c0-4.826 3.528-8.833 8.138-9.605A2.482 2.482 0 0 1 13.5 3.5C13.5 2.122 14.621 1 16 1s2.5 1.122 2.5 2.5c0 .761-.349 1.436-.888 1.895 4.61.772 8.138 4.779 8.138 9.605v4c0 1.241 1.01 2.25 2.25 2.25a.75.75 0 0 1 .75.75Z"></path>
-  </svg>
-  10<span class="pf-v6-screen-reader">unread items</span>
-</pf-v6-button>
-<pf-v6-button variant="stateful" state="unread" clicked>
-  <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
-    <path d="M28.75 22v3.5c0 .689-.561 1.25-1.25 1.25h-7.521c.005.084.021.166.021.25 0 2.206-1.794 4-4 4s-4-1.794-4-4c0-.084.016-.166.021-.25H4.5c-.689 0-1.25-.561-1.25-1.25V22a.75.75 0 0 1 .75-.75c1.24 0 2.25-1.009 2.25-2.25v-4c0-4.826 3.528-8.833 8.138-9.605A2.482 2.482 0 0 1 13.5 3.5C13.5 2.122 14.621 1 16 1s2.5 1.122 2.5 2.5c0 .761-.349 1.436-.888 1.895 4.61.772 8.138 4.779 8.138 9.605v4c0 1.241 1.01 2.25 2.25 2.25a.75.75 0 0 1 .75.75Z"></path>
-  </svg>
-  10<span class="pf-v6-screen-reader">unread items</span>
-</pf-v6-button>
-
-<br /><br />
-
-<strong>Attention</strong>
-<br />
-<pf-v6-button variant="stateful" state="attention">
-  <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
-    <path d="M28 21c-1.103 0-2-.897-2-2v-4c0-4.884-3.523-8.955-8.159-9.823.405-.444.659-1.03.659-1.677C18.5 2.121 17.379 1 16 1s-2.5 1.121-2.5 2.5c0 .648.254 1.233.659 1.677C9.523 6.045 6 10.116 6 15v4c0 1.103-.897 2-2 2a1 1 0 0 0-1 1v3.5c0 .827.673 1.5 1.5 1.5H12c0 2.206 1.794 4 4 4s4-1.794 4-4h7.5c.827 0 1.5-.673 1.5-1.5V22a1 1 0 0 0-1-1ZM14.5 11a1.5 1.5 0 0 1 3 0v5a1.5 1.5 0 0 1-3 0v-5ZM16 24.014a2 2 0 1 1-.001-3.999A2 2 0 0 1 16 24.014Z"></path>
-  </svg>
-  10<span class="pf-v6-screen-reader">unread items, needs attention</span>
-</pf-v6-button>
-<pf-v6-button variant="stateful" state="attention" clicked>
-  <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
-    <path d="M28 21c-1.103 0-2-.897-2-2v-4c0-4.884-3.523-8.955-8.159-9.823.405-.444.659-1.03.659-1.677C18.5 2.121 17.379 1 16 1s-2.5 1.121-2.5 2.5c0 .648.254 1.233.659 1.677C9.523 6.045 6 10.116 6 15v4c0 1.103-.897 2-2 2a1 1 0 0 0-1 1v3.5c0 .827.673 1.5 1.5 1.5H12c0 2.206 1.794 4 4 4s4-1.794 4-4h7.5c.827 0 1.5-.673 1.5-1.5V22a1 1 0 0 0-1-1ZM14.5 11a1.5 1.5 0 0 1 3 0v5a1.5 1.5 0 0 1-3 0v-5ZM16 24.014a2 2 0 1 1-.001-3.999A2 2 0 0 1 16 24.014Z"></path>
-  </svg>
-  10<span class="pf-v6-screen-reader">unread items, needs attention</span>
-</pf-v6-button>
+<div class="stateful-demo">
+  <div>
+    <div><strong>Read</strong></div>
+    <pf-v6-button variant="stateful" state="read">
+      <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
+        <path d="M28.75 22v3.5c0 .689-.561 1.25-1.25 1.25h-7.521c.005.084.021.166.021.25 0 2.206-1.794 4-4 4s-4-1.794-4-4c0-.084.016-.166.021-.25H4.5c-.689 0-1.25-.561-1.25-1.25V22a.75.75 0 0 1 .75-.75c1.24 0 2.25-1.009 2.25-2.25v-4c0-4.826 3.528-8.833 8.138-9.605A2.482 2.482 0 0 1 13.5 3.5C13.5 2.122 14.621 1 16 1s2.5 1.122 2.5 2.5c0 .761-.349 1.436-.888 1.895 4.61.772 8.138 4.779 8.138 9.605v4c0 1.241 1.01 2.25 2.25 2.25a.75.75 0 0 1 .75.75Z"></path>
+      </svg>
+      10<span class="pf-v6-screen-reader">items</span>
+    </pf-v6-button>
+  </div>
+  <div>
+    <div><strong>Unread</strong></div>
+    <pf-v6-button variant="stateful" state="unread">
+      <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
+        <path d="M28.75 22v3.5c0 .689-.561 1.25-1.25 1.25h-7.521c.005.084.021.166.021.25 0 2.206-1.794 4-4 4s-4-1.794-4-4c0-.084.016-.166.021-.25H4.5c-.689 0-1.25-.561-1.25-1.25V22a.75.75 0 0 1 .75-.75c1.24 0 2.25-1.009 2.25-2.25v-4c0-4.826 3.528-8.833 8.138-9.605A2.482 2.482 0 0 1 13.5 3.5C13.5 2.122 14.621 1 16 1s2.5 1.122 2.5 2.5c0 .761-.349 1.436-.888 1.895 4.61.772 8.138 4.779 8.138 9.605v4c0 1.241 1.01 2.25 2.25 2.25a.75.75 0 0 1 .75.75Z"></path>
+      </svg>
+      10<span class="pf-v6-screen-reader">unread items</span>
+    </pf-v6-button>
+  </div>
+  <div>
+    <div><strong>Attention</strong></div>
+    <pf-v6-button variant="stateful" state="attention">
+      <svg slot="icon" fill="currentColor" height="1em" width="1em" viewBox="0 0 32 32" aria-hidden="true">
+        <path d="M28.75 22v3.5c0 .689-.561 1.25-1.25 1.25h-7.521c.005.084.021.166.021.25 0 2.206-1.794 4-4 4s-4-1.794-4-4c0-.084.016-.166.021-.25H4.5c-.689 0-1.25-.561-1.25-1.25V22a.75.75 0 0 1 .75-.75c1.24 0 2.25-1.009 2.25-2.25v-4c0-4.826 3.528-8.833 8.138-9.605A2.482 2.482 0 0 1 13.5 3.5C13.5 2.122 14.621 1 16 1s2.5 1.122 2.5 2.5c0 .761-.349 1.436-.888 1.895 4.61.772 8.138 4.779 8.138 9.605v4c0 1.241 1.01 2.25 2.25 2.25a.75.75 0 0 1 .75.75Z"></path>
+      </svg>
+      10<span class="pf-v6-screen-reader">unread items, needs attention</span>
+    </pf-v6-button>
+  </div>
+</div>
 
 <script type="module">
   import '@patternfly/elements/pf-v6-button/pf-v6-button.js';
 </script>
 
 <style>
+  .stateful-demo {
+    display: flex;
+    gap: 1rem;
+    align-items: flex-start;
+  }
+
+  .stateful-demo strong {
+    font-family: var(--pf-t--global--font--family--body, "Red Hat Text", RedHatText, Helvetica, Arial, sans-serif);
+    font-size: 0.875rem;
+  }
+
   .pf-v6-screen-reader {
     position: absolute;
     width: 1px;