Update Button docs to site (#2285)

Co-authored-by: lilyvc <[email protected]>
Co-authored-by: Joana Moreira <[email protected]>

site/docs/components/button/accessibility.mdx

@@ -1,35 +1,45 @@
 ---
-title: Button
+# Leave the frontmatter as is
+title:
+  $ref: ./#/title
 layout: DetailComponent
 sidebar:
   exclude: true
 data:
   $ref: ./#/data
 ---
 
-### Best practises
+### Best practices
 
-#### When a Button has both an icon and a label
+- When a Button has both an icon and text, pass `aria-hidden=”true”` to the icon so that its text is not announced by screen readers.
+- When a Button has an icon only and no text, pass an `aria-label` to Button that describes its purpose.
 
-- Pass `aria-hidden=”true”` to the icon so that its label is not announced by screen readers.
+#### Focusable disabled button
 
-#### When a Button has an icon only and no label
+- By default, a disabled button is not focusable. However, in certain scenarios it may be preferable for a disabled button to receive focus. To determine if this is necessary, the following rule of thumb can be followed: "If a disabled element can be enabled (either by the user or by the system) it should be made focusable.” For further information, view the W3C guidance on the [`aria-disabled` attribute](https://www.w3.org/TR/wai-aria/#aria-disabled).
 
-- Pass an `aria-label` to Button that describes its purpose.
+#### Screen reader behavior:
+
+On focus, the screen reader should:
+
+- Identify the button
+- Read out the text,
+- Express the state
+  - In certain situations, the screen reader may need to indicate if the button has a popup for lists or menus.
 
 ### Keyboard interactions
 
 <KeyboardControls>
 <KeyboardControl keyOrCombos="Tab">
 
-- If focus is above the button, Tab key press moves focus onto the button.
-- If the button is disabled and is set to receive focus, receives focus.
-- If the button has focus, Tab moves focus out of the button, to next focusable component in the tab order.
+- Tab moves focus onto the button.
+- If the button is disabled and not set to receive focus, Tab moves focus to the next focusable component.
+- If the button has focus, Tab moves focus to the next focusable component in the tab order.
 
 </KeyboardControl>
-<KeyboardControl keyOrCombos="Tab + Shift">
+<KeyboardControl keyOrCombos="Shift + Tab">
 
-- If focused, Tab+Shift combo moves focus out of the component to the previous component in the tab order.
+- Shift + Tab moves focus out of the component to the previous component in the tab order.
 
 </KeyboardControl>
 <KeyboardControl keyOrCombos="Enter / Space">

site/docs/components/button/examples.mdx

@@ -1,5 +1,7 @@
 ---
-title: Button
+# Leave the frontmatter as is
+title:
+  $ref: ./#/title
 layout: DetailComponent
 sidebar:
   exclude: true
@@ -12,47 +14,63 @@ data:
 
 ### CTA
 
-Use the CTA button for high priority actions.
+Use the CTA button for high priority actions. For example, a CTA button may prompt a user to register, sign up, submit or buy.
+
+Guidance:
+
+We recommend that you use CTA buttons sparingly. They represent the default or expected action on the page.
 
 </LivePreview>
 
 <LivePreview componentName="button" exampleName="Primary" >
 
 ### Primary
 
-Use the primary button for routine, non-urgent actions.
+This is the default variant. Use the primary button for routine, non-urgent actions. For example, a primary button should be used for moving to the next page or completing a task.
 
 </LivePreview>
 
 <LivePreview componentName="button" exampleName="Secondary" >
 
 ### Secondary
 
-Use the secondary button for non-critical actions that support the user but do not impact a flow.
+Use the secondary button for non-critical actions that support the user but do not impact a flow. They are typically the alternative option available alongside a primary action. For example, a primary “next” button may be supported by a secondary “back” button.
 
 </LivePreview>
 
-<LivePreview componentName="button" exampleName="IconAndLabel" displayName="Icon and label">
+<LivePreview componentName="button" exampleName="IconAndText">
+
+### Icon and text
+
+Add an icon before the text to reinforce the button text. Add an icon after the button text to suggest movement or a direction.
 
-### Icon and label
+Guidance:
 
-Add an icon before the text to reinforce the button label, or add an icon after the button label to suggest movement or a direction.
+- Place an icon to the left of the text to further describe the action, such as “upload”, “submit”, “play” or “done”. Additional description can make it easier for users to locate actions.
+- Place an icon to the right of the text to suggest direction or movement, such as opening a menu overlay, expanding a panel or opening a document. When the button is activated, there is typically an immediate visual change.
 
 </LivePreview>
 
-<LivePreview componentName="button" exampleName="IconOnly" displayName="Icon only">
+<LivePreview componentName="button" exampleName="IconOnly">
 
 ### Icon only
 
-Display an icon-only button with no label when you have limited on-screen space and the icon is globally understood.
+Display an icon-only button with no text when you have limited on-screen space, and the icon is easily understood.
+
+Guidance:
+
+- An icon-only button should be self-explanatory, ideally using well known symbols. If the purpose of the button isn’t clear from the icon alone, add a text description.
+- Use [Tooltip](../tooltip) on an icon-only button to describe the action such as “Edit this form”, “Print this document”, or “Lock document state”.
 
 </LivePreview>
 
 <LivePreview componentName="button" exampleName="Disabled" >
 
 ### Disabled
 
-Indicates a button that the user can’t interact with.
+Use disabled state for a button that the user can’t press.
+
+A button with the prop `disabled={true}` will suppress all functionality. If you need a disabled button to be focusable, you also need to pass `focusableWhenDisabled={true}`.
 
 </LivePreview>
 </LivePreviewControls>

site/docs/components/button/index.mdx

@@ -1,17 +1,27 @@
 ---
 title: Button
 data:
-  description: Button is an interactive component that allows the user to execute an action. There are three Button variants—CTA (call to action), primary and secondary—that you can display with or without a label or icon, and in various states.
+  description: Button is an interactive component that allows the user to execute an action. There are three Button variants—CTA (call to action), primary (default) and secondary. You can display Button with or without a text description or icon, and in various states.
+
+  # Fill in the info from the content template's "Metadata" table below.
+  # To omit optional items, comment them out with #
   sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/button/Button.tsx"
   package:
     name: "@salt-ds/core"
-    initialVersion: "1.0.0"
   alsoKnownAs: ["Action", "UI action"]
-  relatedComponents:
-    [
+  relatedComponents: [
+      # Add a { name: "...", relationship: "..." } block for each
+      # related component here (separated by commas).
+      # Permitted values for relationship are: "similarTo" or
+      # "contains".
       { name: "Link", relationship: "similarTo" },
       { name: "Icon", relationship: "contains" },
+      { name: "StatusIndicator", relationship: "contains" },
     ]
-  stickerSheet: ""
+  # stickerSheet: "https://figma.com/..."
+
+# Leave this as is
 layout: DetailComponent
 ---
+
+{/* This area stays blank */}

site/docs/components/button/usage.mdx

@@ -1,5 +1,7 @@
 ---
-title: Button
+# Leave the frontmatter as is
+title:
+  $ref: ./#/title
 layout: DetailComponent
 sidebar:
   exclude: true
@@ -9,14 +11,21 @@ data:
 
 ### Using the Button component
 
-- Keep the text label short. Ideally one to three words and no more than five. If you’re including an icon in the label, use no more than three words.
+- Keep the text description short, ideally one to three words and no more than five. If you’re including an icon with the text, use no more than three words.
+- For icons, use the Salt Figma icon library. If the icon you need isn’t available, follow the steps in our [Creating Salt icons](<https://www.figma.com/file/ibGX0b0CxUcZU3pn6OrqX7/Salt%3A-Icons-(Community)?type=design&node-id=490-74&mode=design>) guide.
 
-- When including icons, use the Salt Figma icon library. If the icon you need isn’t available, follow the steps in our Creating Salt icons guide.
+#### When to use Button
 
-- Consider a Link instead of the Button component if the user is navigating to a new page or window rather than carrying out an action.
+- To allow the user to execute an action, such as “submit”, “merge” or “upload”. Buttons are typically placed in components and contexts such as [Dialog](../dialog), [Cards](../card) and [Forms](/salt/patterns/forms).
+
+#### When not to use Button
+
+- When the primary action is to navigate the user to another page or window, rather than triggering a function. Consider using a [Link](../link) component instead.
 
 ### Import
 
+{/* Update the text and code snippet below as needed: */}
+
 To import Button from the core Salt package, use:
 
 ```js
@@ -25,4 +34,16 @@ import { Button } from "@salt-ds/core";
 
 ### Props
 
-<PropsTable componentName="Button" />
+{/* Update packageName and componentName below as needed */}
+{/* packageName is optional and defaults to "core" if omitted */}
+
+<PropsTable packageName="core" componentName="Button" />
+
+### Content
+
+- Always style button text in all caps for prominence. This avoids confusion with body text or general writing.
+- Never use ampersand (&) in button text to save space.
+
+### References
+
+Button Pattern (https://www.w3.org/WAI/ARIA/apg/patterns/button/) W3C

site/src/examples/button/IconAndLabel.tsx → site/src/examples/button/IconAndText.tsx

@@ -2,7 +2,7 @@ import { ReactElement } from "react";
 import { Button } from "@salt-ds/core";
 import { SearchIcon, SendIcon } from "@salt-ds/icons";
 
-export const IconAndLabel = (): ReactElement => (
+export const IconAndText = (): ReactElement => (
   <>
     <Button variant="primary">
       <SearchIcon /> Search

site/src/examples/button/index.ts

@@ -1,6 +1,6 @@
 export * from "./CTA";
 export * from "./Disabled";
-export * from "./IconAndLabel";
+export * from "./IconAndText";
 export * from "./IconOnly";
 export * from "./Primary";
 export * from "./Secondary";