Website: Update Button Organization pattern (bug bash) (#2676)

Co-authored-by: Jory Tindall <jory.tindall@hashicorp.com>

Author: shleewhite

website/docs/patterns/button-organization/partials/guidelines/alignment.md

@@ -6,41 +6,42 @@ Alignment refers to how buttons and actions are aligned relative to the containe
 
 When considering internationalization (i18n), **start** and **end** are suitable substitutes for **left** and **right** alignment to account for languages that are read right-to-left ([RTL](https://developer.mozilla.org/en-US/docs/Glossary/RTL)).
 
-![Button alignment options](/assets/patterns/button-organization/alignment-methods.png)
+![](/assets/patterns/button-organization/alignment-methods.png)
 !!!
 
 ### Left alignment
 
-Actions are aligned to the left of the container or page. A common example of this alignment method is in [Modals](/components/modal) and page-level forms.
+In most scenarios, align buttons to the **left side** of a container or page. The primary button should be leftmost, followed by secondary, then tertiary.
 
-![Left alignment example](/assets/patterns/button-organization/using-left-alignment.png)
+- This reinforces natural reading patterns and a conversational "dialog-like" messaging strategy.
+- When combined with a consistent ordering method, the primary button is prioritized in the reading direction.
+- When considering different contexts, opting for a single method helps to create consistency between constrained and unconstrained components and patterns.
+
+A common example of this alignment method is in [Modals](/components/modal) and page-level forms.
 
 !!! Do
 
-In most scenarios, align buttons to the **left side** of a container or page.
+Align buttons to the left side of the container.
 
-- This reinforces natural reading patterns and a conversational "dialog-like" messaging strategy.
-- When combined with a consistent ordering method, the primary button is prioritized in the reading direction.
-- When considering different contexts, opting for a single method helps to create consistency between constrained and unconstrained components and patterns.
+![Modal with buttons in the footer aligned to the left. The reading order goes from left to right, top to bottom.](/assets/patterns/button-organization/alignment-reading-pattern-comparison.png)
 
-![Button alignment reading pattern](/assets/patterns/button-organization/alignment-reading-pattern.png)
 !!!
 
 ### Right alignment
 
-Actions are aligned to the right of the container or page. This alignment method is commonly used for page-level functions or actions that create and manage elements within a page.
+In the case of page-level functions or actions that manage elements within the page, align buttons to the right of the page. The primary button should be the farthest right, then secondary, then tertiary.
 
-![Right alignment example](/assets/patterns/button-organization/using-right-alignment.png)
+![Peering connections heading with a "Create connection" button right aligned to the container. A table of peering connections below.](/assets/patterns/button-organization/using-right-alignment.png)
 
 ### Center alignment
 
-Actions are aligned in the middle of the container or page. This alignment method is _not_ recommended in the majority of scenarios.
+This alignment method is _not_ recommended in the majority of scenarios.
 
 - Can cause buttons to needlessly fill the horizontal space of the container
 - Can cause buttons to appear detached from the content they are paired with, especially if a user has increased zoom settings within their browser
 
 !!! Dont
 
-![Center alignment example](/assets/patterns/button-organization/using-center-alignment.png)
+![Align buttons in the center of a form container.](/assets/patterns/button-organization/using-center-alignment.png)
 !!!
 

website/docs/patterns/button-organization/partials/guidelines/grouping.md

@@ -2,7 +2,7 @@
 
 How actions are grouped can influence what the user perceives as the primary action. Actions grouped correctly can alleviate decision fatigue and help users better understand the outcome of their actions.
 
-- Group buttons together that perform similar, related, and inverse functions. This generally refers to functions like "yes/no" or "ok/cancel." 
+- Group buttons together that perform similar, related, and inverse functions. This generally refers to functions like "yes/no" or "ok/cancel". 
 - Inverse grouping generally helps users to make decisions quicker as their options are limited.
 - As a best practice, tertiary actions should only be used if they help the user make a decision (linking to a different area of the application or documentation).
     - Presenting the user with more than one action in this context can be confusing and force the user to question whether they are making the correct decision. Read more about [Hick's Law](https://www.interaction-design.org/literature/article/hick-s-law-making-the-choice-easier-for-users).

website/docs/patterns/button-organization/partials/guidelines/order.md

@@ -58,7 +58,7 @@ User edits the settings of a cluster:
 
 A possible exception to this ordering method is in multi-step and progressive flows in which buttons fulfill both a functional purpose (create or edit something) and a navigational purpose (proceed, go back).
 
-- The **directionality** and positive outcome of the overall flow are reinforced by the button order and grouping
+- The **directionality** and positive outcome of the overall flow are reinforced by the button order and grouping.
 - In a multi-step flow, this type of pattern would persist on the page; the repetitiveness acts as a form of consistency scoped to the feature the pattern is used in.
 
 ![Multi-step progressive flow](/assets/patterns/button-organization/multi-step-progressive-flow.png)
@@ -69,7 +69,7 @@ As the viewport size shrinks, buttons should stack vertically in accordance with
 
 - This naturally adheres to our ordering guidelines; button order remains the same, except the container is vertical rather than horizontal.
 - This reduces complexity in engineering.
-- This ensures our applications meet accessibility conformance in [making the DOM order match the visual order](https://www.w3.org/TR/WCAG20-TECHS/C27.html)
+- This ensures our applications meet accessibility conformance in [making the DOM order match the visual order](https://www.w3.org/TR/WCAG20-TECHS/C27.html).
 
 !!! Do