Update docs

jpmorganchase · Jul 26, 2024 · ed98080 · ed98080
1 parent 2ec05dd
commit ed98080
Show file tree

Hide file tree

Showing 9 changed files with 150 additions and 104 deletions.
diff --git a/site/docs/components/button/examples.mdx b/site/docs/components/button/examples.mdx
@@ -9,21 +9,33 @@ data:
 ---
 
 <LivePreviewControls>
-<LivePreview componentName="button" exampleName="Appearance">
+<LivePreview componentName="button" exampleName="Color">
 
-## Appearance
+## Color
 
-Button comes in three variants based on appearance—`"solid"`, `"transparent"`, and `"outline"`—with solid being the default. These visually differing styles provide multiple levels of affordance from greatest to least.
+Button has two colors: `accent` and `neutral`. Accent buttons will reflect the primary color of the design language.
+
+### Best practices
+
+- Use accent buttons for the main calls-to-action in your application workflows (button bars, card actions, promotional banners, etc.).
+- Use neutral buttons for secondary tasks or workflows, such as configuring settings in preferences, or actions embedded in form fields and forms. Neutral buttons can also be used to give greater prominence to alternative actions alongside accent buttons.
 
 </LivePreview>
 
-<LivePreview componentName="button" exampleName="Color">
+<LivePreview componentName="button" exampleName="Appearance">
 
-## Color
+## Appearance
+
+Button comes in three variants based on appearance—`solid`, `outline` and `transparent`—which give button more or less visual prominence on the page.
+
+### Best practices
 
-Color assigns a button's meaning and usage. It has a default color of `"neutral"` used for routine, non-urgent actions. Whereas you can use `"accent"` color for high-priority actions.
+- Solid buttons are typically used for the primary actions in your application.
+- Outline buttons pair well with solid buttons for alternative secondary tasks in a workflow.
+- Transparent buttons are typically used in groupings, like toggle buttons, or where other appearances would be too prominent. It is also commonly used where an icon needs to be interactive, providing focus management and interactive visual styles for the icon-only action.
 
 </LivePreview>
+
 <LivePreview componentName="button" exampleName="IconAndText">
 
 ## Icon and text
@@ -33,7 +45,7 @@ Add an icon before the text to reinforce the button text. Add an icon after the
 ### Best practices
 
 - 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 user activates the button, there's typically an immediate visual change.
+- Place an icon to the right of the text to suggest direction or movement, such as opening a menu overlay or expanding a panel. When the user activates the button, there's typically an immediate visual change.
 
 </LivePreview>
 
@@ -46,7 +58,7 @@ Display an icon-only button with no text when you have limited on-screen space,
 ### Best practices
 
 - An icon-only button should be self-explanatory, ideally using well-known symbols. If the button's purpose 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”.
+- Use [`Tooltip`](../tooltip) on an icon-only button to describe the action, such as “Send comment”, “Search documents”, or “Open settings”.
 
 </LivePreview>
 
@@ -55,16 +67,16 @@ Display an icon-only button with no text when you have limited on-screen space,
 ## Disabled
 
 Use the disabled state for a button that the user can’t press.
-
-A button with the prop `disabled={true}` will suppress all functionality.
+  
+To set the button as disabled pass the prop `disabled={true}`.
 
 </LivePreview>
 
 <LivePreview componentName="button" exampleName="FocusableWhenDisabled" >
 
 ## Focusable when disabled
 
-If you need to allow the user to place focus on a disabled button, you also need to pass `focusableWhenDisabled={true}`.
+If a disabled element can be enabled (either by the user or by the system), it should be focusable. To allows this you can pass `focusableWhenDisabled={true}`.
 
 This is useful when you want to show a tooltip or a popover when the user hovers over the button.
 
@@ -80,7 +92,7 @@ Use full width buttons on mobile devices or smaller viewports, the button will t
 
 <LivePreview componentName="button" exampleName="CTA" displayName="CTA - Deprecated" >
 
-## CTA
+## CTA - Deprecated
 
 _Note:_ The `variant` prop is deprecated. Use `appearance="solid"` and `color="accent"` instead.
 
@@ -94,7 +106,7 @@ Use CTA buttons sparingly. They represent the default or expected action on the
 
 <LivePreview componentName="button" exampleName="Primary" displayName="Primary - Deprecated" >
 
-## Primary
+## Primary - Deprecated
 
 _Note:_ The `variant` prop is deprecated. Use `appearance="solid"` and `color="neutral"` instead.
 
@@ -104,7 +116,7 @@ This is the default variant. Use the primary button for routine, nonurgent actio
 
 <LivePreview componentName="button" exampleName="Secondary" displayName="Secondary - Deprecated" >
 
-## Secondary
+## Secondary - Deprecated
 
 _Note:_ The `variant` prop is deprecated. Use `appearance="transparent"` and `color="neutral"` instead.
 

diff --git a/site/docs/components/button/index.mdx b/site/docs/components/button/index.mdx
@@ -1,7 +1,7 @@
 ---
 title: Button
 data:
-  description: "`Button` is an interactive component that allows the user to execute an action. You can display a button with or without a text description or icon, and in various states."
+  description: "`Button` is an interactive component that allows the user to execute an action. You can display a button with or without a text description or icon."
 
   # Fill in the info from the content template's "Metadata" table below.
   # To omit optional items, comment them out with #
@@ -14,9 +14,7 @@ data:
       # related component here (separated by commas).
       # Permitted values for relationship are: "similarTo" or
       # "contains".
-      { name: "Link", relationship: "similarTo" },
-      { name: "Icon", relationship: "contains" },
-      { name: "Status indicator", relationship: "contains" },
+      { name: "Link", relationship: "similarTo" }
     ]
   relatedPatterns: ["Button bar", "Split button"]
 

diff --git a/site/src/examples/button/Appearance.tsx b/site/src/examples/button/Appearance.tsx
@@ -3,8 +3,14 @@ import type { ReactElement } from "react";
 
 export const Appearance = (): ReactElement => (
   <>
-    <Button appearance="solid">Solid</Button>
-    <Button appearance="outline">Outline</Button>
-    <Button appearance="transparent">Transparent</Button>
+    <Button appearance="solid" color="accent">
+      Solid
+    </Button>
+    <Button appearance="outline" color="accent">
+      Outline
+    </Button>
+    <Button appearance="transparent" color="accent">
+      Transparent
+    </Button>
   </>
 );
diff --git a/site/src/examples/button/Color.tsx b/site/src/examples/button/Color.tsx
@@ -1,25 +1,35 @@
-import { Button, GridLayout } from "@salt-ds/core";
+import { Button, FlowLayout, H3, StackLayout } from "@salt-ds/core";
 import type { ReactElement } from "react";
 
 export const Color = (): ReactElement => (
-  <GridLayout columns={3}>
-    <Button appearance="solid" color="neutral">
-      Solid
-    </Button>
-    <Button appearance="outline" color="neutral">
-      Outline
-    </Button>
-    <Button appearance="transparent" color="neutral">
-      Transparent
-    </Button>
-    <Button appearance="solid" color="accent">
-      Solid
-    </Button>
-    <Button appearance="outline" color="accent">
-      Outline
-    </Button>
-    <Button appearance="transparent" color="accent">
-      Transparent
-    </Button>
-  </GridLayout>
+  <StackLayout gap={6}>
+    <StackLayout>
+      <H3>Accent</H3>
+      <FlowLayout>
+        <Button appearance="solid" color="accent">
+          Solid
+        </Button>
+        <Button appearance="outline" color="accent">
+          Outline
+        </Button>
+        <Button appearance="transparent" color="accent">
+          Transparent
+        </Button>
+      </FlowLayout>
+    </StackLayout>
+    <StackLayout>
+      <H3>Neutral</H3>
+      <FlowLayout>
+        <Button appearance="solid" color="neutral">
+          Solid
+        </Button>
+        <Button appearance="outline" color="neutral">
+          Outline
+        </Button>
+        <Button appearance="transparent" color="neutral">
+          Transparent
+        </Button>
+      </FlowLayout>
+    </StackLayout>
+  </StackLayout>
 );
diff --git a/site/src/examples/button/Disabled.tsx b/site/src/examples/button/Disabled.tsx
@@ -4,22 +4,22 @@ import type { ReactElement } from "react";
 
 export const Disabled = (): ReactElement => (
   <GridLayout columns={3}>
-    <Button appearance="solid" color="neutral" disabled>
+    <Button appearance="solid" color="accent" disabled>
       Solid
     </Button>
-    <Button appearance="outline" color="neutral" disabled>
+    <Button appearance="outline" color="accent" disabled>
       Outline
     </Button>
-    <Button appearance="transparent" color="neutral" disabled>
+    <Button appearance="transparent" color="accent" disabled>
       Transparent
     </Button>
-    <Button appearance="solid" color="accent" disabled>
+    <Button appearance="solid" color="neutral" disabled>
       Solid
     </Button>
-    <Button appearance="outline" color="accent" disabled>
+    <Button appearance="outline" color="neutral" disabled>
       Outline
     </Button>
-    <Button appearance="transparent" color="accent" disabled>
+    <Button appearance="transparent" color="neutral" disabled>
       Transparent
     </Button>
   </GridLayout>

diff --git a/site/src/examples/button/FocusableWhenDisabled.tsx b/site/src/examples/button/FocusableWhenDisabled.tsx
@@ -4,29 +4,29 @@ import type { ReactElement } from "react";
 
 export const FocusableWhenDisabled = (): ReactElement => (
   <GridLayout columns={3}>
-    <Button appearance="solid" color="neutral" disabled focusableWhenDisabled>
+    <Button appearance="solid" color="accent" disabled focusableWhenDisabled>
       Solid
     </Button>
-    <Button appearance="outline" color="neutral" disabled focusableWhenDisabled>
+    <Button appearance="outline" color="accent" disabled focusableWhenDisabled>
       Outline
     </Button>
     <Button
       appearance="transparent"
-      color="neutral"
+      color="accent"
       disabled
       focusableWhenDisabled
     >
       Transparent
     </Button>
-    <Button appearance="solid" color="accent" disabled focusableWhenDisabled>
+    <Button appearance="solid" color="neutral" disabled focusableWhenDisabled>
       Solid
     </Button>
-    <Button appearance="outline" color="accent" disabled focusableWhenDisabled>
+    <Button appearance="outline" color="neutral" disabled focusableWhenDisabled>
       Outline
     </Button>
     <Button
       appearance="transparent"
-      color="accent"
+      color="neutral"
       disabled
       focusableWhenDisabled
     >

diff --git a/site/src/examples/button/FullWidth.tsx b/site/src/examples/button/FullWidth.tsx
@@ -2,24 +2,28 @@ import { Button, StackLayout } from "@salt-ds/core";
 import type { ReactElement } from "react";
 
 export const FullWidth = (): ReactElement => (
-  <StackLayout style={{ width: "400px" }}>
-    <Button color="neutral" appearance="solid">
-      Solid neutral full width Button
-    </Button>
-    <Button color="neutral" appearance="outline">
-      Outline neutral full width Button
-    </Button>
-    <Button color="neutral" appearance="transparent">
-      Transparent neutral full width Button
-    </Button>
-    <Button color="accent" appearance="solid">
-      Solid accent full width Button
-    </Button>
-    <Button color="accent" appearance="outline">
-      Outline accent full width Button
-    </Button>
-    <Button color="accent" appearance="transparent">
-      Transparent accent full width Button
-    </Button>
+  <StackLayout gap={6} style={{ width: "400px" }}>
+    <StackLayout>
+      <Button color="accent" appearance="solid">
+        Solid accent
+      </Button>
+      <Button color="accent" appearance="outline">
+        Outline accent
+      </Button>
+      <Button color="accent" appearance="transparent">
+        Transparent accent
+      </Button>
+    </StackLayout>
+    <StackLayout>
+      <Button color="neutral" appearance="solid">
+        Solid neutral
+      </Button>
+      <Button color="neutral" appearance="outline">
+        Outline neutral
+      </Button>
+      <Button color="neutral" appearance="transparent">
+        Transparent neutral
+      </Button>
+    </StackLayout>
   </StackLayout>
 );
diff --git a/site/src/examples/button/IconAndText.tsx b/site/src/examples/button/IconAndText.tsx
@@ -1,26 +1,30 @@
 import { Button, GridLayout } from "@salt-ds/core";
-import { RefreshIcon, SearchIcon, SendIcon } from "@salt-ds/icons";
+import {
+  DoubleChevronRightIcon,
+  DownloadIcon,
+  SearchIcon,
+} from "@salt-ds/icons";
 import type { ReactElement } from "react";
 
 export const IconAndText = (): ReactElement => (
   <GridLayout columns={3}>
-    <Button appearance="solid" color="neutral">
+    <Button appearance="solid" color="accent">
       <SearchIcon /> Search
     </Button>
-    <Button appearance="outline" color="neutral">
-      Send <SendIcon />
+    <Button appearance="outline" color="accent">
+      <DownloadIcon /> Download
     </Button>
-    <Button appearance="transparent" color="neutral">
-      Refresh <RefreshIcon />
+    <Button appearance="transparent" color="accent">
+      Expand <DoubleChevronRightIcon />
     </Button>
-    <Button appearance="solid" color="accent">
+    <Button appearance="solid" color="neutral">
       <SearchIcon /> Search
     </Button>
-    <Button appearance="outline" color="accent">
-      Send <SendIcon />
+    <Button appearance="outline" color="neutral">
+      <DownloadIcon /> Download
     </Button>
-    <Button appearance="transparent" color="accent">
-      Refresh <RefreshIcon />
+    <Button appearance="transparent" color="neutral">
+      Expand <DoubleChevronRightIcon />
     </Button>
   </GridLayout>
 );