diff --git a/site/docs/components/accordion/accessibility.mdx b/site/docs/components/accordion/accessibility.mdx index 6f6888c5f10..f901299ed1c 100644 --- a/site/docs/components/accordion/accessibility.mdx +++ b/site/docs/components/accordion/accessibility.mdx @@ -12,17 +12,17 @@ data: -- If focus is above the Accordion group, Tab moves focus to the first Accordion item in the group. Then each next Accordion item is a tab stop. +- If focus is above the accordion group, Tab moves focus to the first accordion item in the group. Then, each press moves to the next accordion item. -If focus is below the Accordion Group, Shift + Tab moves focus to the last Accordion item in the group. Then each Shift + Tab moves focus to the previous Accordion item in the group. +- If focus is below the accordion group, this action moves focus to the last accordion item in the group. Then, each press moves focus to the previous accordion item in the group. -- Accordions are collapsed by default. Enter or Space expands, or collapses, Accordions. +- Accordions are in the collapsed state by default. This action expands, or collapses, accordions. diff --git a/site/docs/components/accordion/examples.mdx b/site/docs/components/accordion/examples.mdx index fa9a18e7d42..afcaa868a23 100644 --- a/site/docs/components/accordion/examples.mdx +++ b/site/docs/components/accordion/examples.mdx @@ -12,35 +12,35 @@ data: ### Default -Accordion is a single element by default that can be expanded or collapsed to show or hide content within a panel. +By default, `Accordion` is a single element the user can expand or collapse to show or hide content within a panel. -### Accordion Groups +### Accordion groups -You can place Accordions in an Accordion Group which allows multiple accordions to be open at the same time. +You can place accordions in an accordion group, which allows multiple accordions to be open at the same time. ### Disabled -Use the `disabled` prop to disable an Accordion. A disabled Accordion cannot be expanded, collapsed or focused. +Use the `disabled` prop to disable an accordion. The user can't expand, collapse or focus a disabled accordion. ### Status -You can set a status of either "error", "warning" or "success" for an Accordion. This should be used to indicate the status of the content within the Accordion. +You can set a status of "error", "warning" or "success" for an accordion to indicate the type of content it contains. -### Inline Badge +### Inline badge -You can use an inline [Badge](../badge) to indicate a change, or number of changes, to the content within the Accordion. +You can use an inline [badge](../badge) to indicate a change, or several changes, to the content within the accordion. diff --git a/site/docs/components/accordion/index.mdx b/site/docs/components/accordion/index.mdx index cfaca63a923..a4845dd5ced 100644 --- a/site/docs/components/accordion/index.mdx +++ b/site/docs/components/accordion/index.mdx @@ -1,16 +1,16 @@ --- title: Accordion data: - description: Accordion displays a panel which can be expanded or collapsed to allow the user to show or hide content and control the complexity of a given view. + description: "`Accordion` displays a panel that the user can expand or collapse to show or hide content and control the complexity of a given view." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/accordion/Accordion.tsx" package: name: "@salt-ds/core" initialVersion: "1.0.0" - alsoKnownAs: ["Collapsible Panel", "Concertina", "Expansion Panel"] + alsoKnownAs: ["Collapsible panel", "Concertina", "Expansion panel"] relatedComponents: [ { name: "Icon", relationship: "contains" }, - { name: "Status Indicator", relationship: "contains" }, + { name: "Status indicator", relationship: "contains" }, ] stickerSheet: "" layout: DetailComponent diff --git a/site/docs/components/accordion/usage.mdx b/site/docs/components/accordion/usage.mdx index b41bcc1d703..5fdfa2f25ee 100644 --- a/site/docs/components/accordion/usage.mdx +++ b/site/docs/components/accordion/usage.mdx @@ -7,21 +7,23 @@ data: $ref: ./#/data --- -### When to use Accordion +### Using the component + +#### When to use - To organize related content within expandable groups/categories/sections. -- To reduce scrolling or overall page length when it is not critical that content is displayed in full. +- To reduce scrolling or overall page length when displaying content in full isn't critical. -- When content cannot be displayed all at once due to restricted screen real estate. +- When you can't display all the content at once due to restricted screen space. -### When not to use Accordion +#### When not to use -- This component is not intended for use with grids to replace grouped rows. +- To replace grouped rows with grids. ### Import -To import Accordion and Accordion Group from the core Salt package, use: +To import `Accordion` and related components from the core Salt package, use: ```js import { @@ -34,18 +36,18 @@ import { ### Props -#### Accordion +#### `Accordion` -#### Accordion Group +#### `AccordionGroup` -#### Accordion Header +#### `AccordionHeader` -#### Accordion Panel +#### `AccordionPanel` diff --git a/site/docs/components/ag-grid-theme/examples.mdx b/site/docs/components/ag-grid-theme/examples.mdx index f0072fe5cdb..74d2e0d55ad 100644 --- a/site/docs/components/ag-grid-theme/examples.mdx +++ b/site/docs/components/ag-grid-theme/examples.mdx @@ -13,7 +13,20 @@ data: ### Default -Applies the default look when applying Salt theme +Applies the default look when applying the Salt theme. + + + + + +### Variants + +There are three variants of the Salt AG Grid theme: primary (default), secondary and zebra. To use one of the non-default variants, add an additional class name to the container element above ``. + +The class names are: + +- `ag-theme-salt-variant-secondary` +- `ag-theme-salt-variant-zebra` @@ -105,7 +118,7 @@ Users can reveal a child grid when a row in the master grid is expanded. -### No data overlay +### "No data" overlay This overlay tells the user that there is no information to display. @@ -119,7 +132,7 @@ Users can move between pages using the controls in the lower right. -### Parent child rows +### Parent-child rows These rows group items under headers and sub-headers. @@ -151,18 +164,6 @@ Row groups display in the above panel. The section below the table displays a status bar. - - - -### Variants - -There are three variants of the Salt AG Grid theme: primary (default), secondary and zebra. To use one of the non-default variants, add an additional class name to the container element above ``. - -The class names are: - -- `ag-theme-salt-variant-secondary` -- `ag-theme-salt-variant-zebra` - diff --git a/site/docs/components/ag-grid-theme/index.mdx b/site/docs/components/ag-grid-theme/index.mdx index 99894c35fed..b7761727643 100644 --- a/site/docs/components/ag-grid-theme/index.mdx +++ b/site/docs/components/ag-grid-theme/index.mdx @@ -1,7 +1,7 @@ --- -title: AG Grid Theme +title: AG Grid theme data: - description: AG Grid Theme is a package that adds Salt theme styles to AG Grid. The package contains CSS files only, and works with AG Grid versions 25 - 28. + description: "AG Grid theme is a package that adds Salt theme styles to AG Grid. The package contains CSS files only, and works with AG Grid versions 25-28." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/ag-grid-theme" package: name: "@salt-ds/ag-grid-theme" diff --git a/site/docs/components/ag-grid-theme/usage.mdx b/site/docs/components/ag-grid-theme/usage.mdx index c5cad570747..1adfb93cd19 100644 --- a/site/docs/components/ag-grid-theme/usage.mdx +++ b/site/docs/components/ag-grid-theme/usage.mdx @@ -9,13 +9,13 @@ data: $ref: ./#/data --- -### Using AG Grid Theme +### Using the package -#### When to use AG Grid Theme +#### When to use When you want to use the Salt theme with AG Grid. -#### When not to use AG Grid Theme +#### When not to use When you want to use a component that is not related to AG Grid. Instead, use Grid. diff --git a/site/docs/components/avatar/accessibility.mdx b/site/docs/components/avatar/accessibility.mdx index 293adcad919..7af5d430b19 100644 --- a/site/docs/components/avatar/accessibility.mdx +++ b/site/docs/components/avatar/accessibility.mdx @@ -9,6 +9,6 @@ data: ### Best practices -Decorative Avatars (Avatars that repeat the information already expressed by the accompanying text) should be hidden from the screen reader to avoid repetition. If you are adding an Avatar for decorative purposes, use `aria-hidden` to hide its label from the screen reader. +You should exclude decorative avatars (avatars that repeat the information already expressed by the accompanying text) from screen reader access to avoid repetition. If you're adding an avatar for decorative purposes, use `aria-hidden` to exclude its label from the screen reader. -If an alternative icon is used inside an Avatar, the icon's `aria-label` should be descriptive in relation to the Avatar context, not the icon context. For example, when using `` to represent a company `aria-label` should read "Company profile" rather than the Icon's default label "building solid". +If you're using an alternative icon inside an avatar, the icon's `aria-label` should be descriptive in relation to the avatar context, not the icon context. For example, when using `` to represent a company, `aria-label` should read "Company profile" rather than the icon's default label "building solid." diff --git a/site/docs/components/avatar/examples.mdx b/site/docs/components/avatar/examples.mdx index 5e32a799beb..79156db2bad 100644 --- a/site/docs/components/avatar/examples.mdx +++ b/site/docs/components/avatar/examples.mdx @@ -12,34 +12,34 @@ data: ### Image -You can pass an image using the `src` property to be used as the Avatar image. +You can pass an image as the avatar image using the `src` prop. -A custom image or SVG can also be passed as the child of the component. Note that for images passed as children, you will also need to handle the fallback logic. +You can also pass a custom image or SVG as the child of the component. Note that for images passed as children, you'll also need to handle the fallback logic. ### Initials -If a photo is not available, the Avatar will fall back to initials or an icon: +If a photo is not available, the avatar will fall back to initials or an icon: -- Initials can be used when a photo is unavailable, but profile information is. +- You can use initials when a photo is unavailable, but profile information is. -- Icon can be used when neither a photo nor profile information are available. +- Use an icon when neither a photo nor profile information is available. ### Sizes -The Avatar size can be increased by modifying the size property. Each Avatar variant has a default size across all four densities, equal to the [Size Foundation](/salt/foundations/size) `size-base`; 20px (HD), 28px (MD), 36px (LD), and 44px (TD). The size property acts as a multiplier of the base size. +You can use the `size` prop to modify the avatar size. Each avatar variant has a default size across all four densities, equal to the [size foundation](/salt/foundations/size) `size-base`: 20px (HD), 28px (MD), 36px (LD), and 44px (TD). The size property acts as a multiplier of the base size. -### Custom Fallback Icon +### Custom fallback icon -Avatar renders with an icon defined by `UserSolidIcon` but an alternative icon can be passed as `fallbackIcon`. +`Avatar` renders with an icon defined by `UserSolidIcon`, but you can pass an alternative icon as `fallbackIcon`. diff --git a/site/docs/components/avatar/index.mdx b/site/docs/components/avatar/index.mdx index 3808f58c09a..e96addc8b98 100644 --- a/site/docs/components/avatar/index.mdx +++ b/site/docs/components/avatar/index.mdx @@ -1,7 +1,7 @@ --- title: Avatar data: - description: The Avatar component is a graphical element which can be used to represent a person, group, entity, or communication channel. + description: "`Avatar` is a graphical element which you can use to represent a person, group, entity or communication channel." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/avatar/Avatar.tsx" package: name: "@salt-ds/core" diff --git a/site/docs/components/avatar/usage.mdx b/site/docs/components/avatar/usage.mdx index 5463f937538..006a81f7728 100644 --- a/site/docs/components/avatar/usage.mdx +++ b/site/docs/components/avatar/usage.mdx @@ -7,17 +7,19 @@ data: $ref: ./#/data --- -### When to use Avatar +### Using the component -Use Avatar to visually represent a person, group, entity or communication channel. The same image, initials, or placeholder image should appear for a given object instance throughout the experience. +#### When to use -### When not to use Avatar +To visually represent a person, group, entity or communication channel. The same image, initials, or placeholder image should appear for a given object instance throughout the experience. -Do not use when a large, full-size image is required. +#### When not to use + +When a large, full-size image is necessary. ### Import -To import Avatar from the core Salt package, use: +To import `Avatar` from the core Salt package, use: ``` import { Avatar } from "@salt-ds/core"; diff --git a/site/docs/components/badge/accessibility.mdx b/site/docs/components/badge/accessibility.mdx index 7045146bc05..91319f340c7 100644 --- a/site/docs/components/badge/accessibility.mdx +++ b/site/docs/components/badge/accessibility.mdx @@ -7,4 +7,6 @@ data: $ref: ./#/data --- -We recommend only using the accent color for Badge. Align to the minimum contrast guidance outlined in [WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) for any color overrides. +### Best practices + +We recommend only using the accent color for `Badge`. Align to the minimum contrast guidance outlined in [WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) for any color overrides. diff --git a/site/docs/components/badge/examples.mdx b/site/docs/components/badge/examples.mdx index cb1099f6f05..bead9a15b8a 100644 --- a/site/docs/components/badge/examples.mdx +++ b/site/docs/components/badge/examples.mdx @@ -9,44 +9,40 @@ data: - ### Default (top-right) + ### Default (top-right) - Badge is positioned in the top-right corner when attached to a child component such as an icon. +By default, `Badge` is in the top-right corner when attached to a child component such as an icon. Badges visually anchor to the attached component. As the number of alphanumeric characters increases, the badge width expands, but stays in the same place. +#### Best practices - #### Guidance - - - Badge is visually anchored to the attached component. As the number of alphanumeric characters increases, the Badge width expands, but stays in the same place. - - Use badge in the top-right corner if you want to provide a summary of the overall state of the content the badge is anchored to. For example, you may want to provide a quick overview of how many new or unread items there are, using numeric values. +Use a badge in the top-right corner to summarize the overall state of the content the badge is anchored to. For example, you may want to provide a quick overview of the number of new or unread items, using numeric values. - ### Inline Badge +### Inline badge - To place a badge inline, instead of in the top-right corner of an element simply do not pass `children` to Badge. +To place a badge inline instead of in the top-right corner of an element, don't pass `children` to the badge. - #### Guidance +#### Best practices - Using Badge inline with text makes clear which part of the content the badge relates to and allows specific details to be highlighted within the content to draw the user’s attention. For example, you may use Badge within Tab, inline to the text. +Using a badge inline with text clarifies which part of the content the badge relates to and allows specific details to be highlighted within the content to draw the user’s attention. For example, you may use a badge within `TabNext`, inline with the text. - ### Badge with maximum digits - - Specify the maximum number to be displayed with the `max` property. If `value` exceeds `max`, the value will be clamped and a (`+`) suffix will be appended. +### Badge with maximum digits - #### Guidance +Specify the maximum displayed number with the `max` prop. If `value` exceeds `max`, it will clamp the value and append a (`+`) suffix. - - In the case that no max value is passed to the component, the value will be limited to 3 digits by default and therefore display 999+ for any values over 999. +When you don't pass a max value to the component, the value will have a limitation of three digits by default, displaying 999+ for any values over 999. - ### Badge with string + ### Badge with string - The `value` property can accept both a `number` and a `string`. +The `value` property can accept both a `number` and a `string`. diff --git a/site/docs/components/badge/index.mdx b/site/docs/components/badge/index.mdx index ba37fb4de25..d54abfde542 100644 --- a/site/docs/components/badge/index.mdx +++ b/site/docs/components/badge/index.mdx @@ -1,7 +1,7 @@ --- title: Badge data: - description: Badge is a numeric or alpha character annotation that represents a number of items. It appears either on the top-right of an element, or inline. + description: "`Badge` is a numeric or alpha character annotation. It appears either in the top-right corner of an element, or inline." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/badge/Badge.tsx" package: name: "@salt-ds/core" diff --git a/site/docs/components/badge/usage.mdx b/site/docs/components/badge/usage.mdx index 81d6eb58778..bfbcacafb12 100644 --- a/site/docs/components/badge/usage.mdx +++ b/site/docs/components/badge/usage.mdx @@ -7,32 +7,32 @@ data: $ref: ./#/data --- -### Using the Badge component +### Using the component -If a numeric annotation exceeds the max value passed as a prop, a plus (`+`) sign will be displayed after the max value stated. In the case that no max value is passed to the component, the value will truncate after 3 digits and therefore display 999+ for any values over 999. +If a numeric annotation exceeds the max value passed as a prop, there will be a plus (`+`) after the max value stated. If you don't pass a max value to the component, it will truncate the value after three digits displaying 999+ for any values over 999. -#### When to use Badge +We recommend that you avoid using a badge with more than four to six characters. If needed, truncate strings exceeding this count with an ellipsis (…). + +#### When to use -- To communicate a non-interactive, system driven change to the underlying component it is anchored to. For example, in tabs, pages and containers. +- To communicate a non-interactive, system-driven change to the underlying component it anchors to, such as in tabs, pages and containers. -- Typically, if a badge is used to indicate an unread notification, the badge is hidden once the notification is addressed. However, badges can remain persistent depending on context. +- Typically, if you use a badge to indicate an unread notification, you'd hide the badge once the user addresses the notification. However, badges can remain persistent depending on the context. -#### When not to use Badge +#### When not to use -- To organize content within categories, trigger an immediate action, or enable an action that may change depending on context. Instead, use [Pill](../pill). +- To organize content within categories, trigger an immediate action, or enable an action that may change depending on context. Instead, use [`Pill`](../pill). -- To communicate status through color, such as RAG statuses. Instead, use Pill. Badges are independent of user action and therefore should not be used to communicate something the user can directly influence through a task. +- To communicate status through color, such as red/amber/green statuses. Instead, use `Pill`. Badges are independent of user action, so avoid using them to communicate something the user can directly influence through a task. ### Import -To import Badge from the core Salt package, use: +To import `Badge` from the core Salt package, use: -``` +```js import { Badge } from "@salt-ds/core"; ``` ### Props - -We recommend that you avoid using a badge with more than four to six characters. If needed, truncate strings exceeding this count with an ellipsis (…). diff --git a/site/docs/components/banner/accessibility.mdx b/site/docs/components/banner/accessibility.mdx index 6362eaa3d47..38adae5f226 100644 --- a/site/docs/components/banner/accessibility.mdx +++ b/site/docs/components/banner/accessibility.mdx @@ -8,18 +8,18 @@ data: $ref: ./#/data --- -Any focusable elements included in the Banner content will need to be checked and tested accordingly. +### Best practices -### Guidance +Check and test any focusable elements included in the banner content. -When using Banner to alert the user, apply `role="alert"`. When using Banner to notify the user, apply `role="status"`. +When using a banner to alert the user, apply `role="alert"`. When using a banner to notify the user, apply `role="status"`. ### Keyboard interactions -Use Tab key to navigate through the interactive elements added. +Tab moves focus through the interactive elements. diff --git a/site/docs/components/banner/examples.mdx b/site/docs/components/banner/examples.mdx index e41bbcc51c2..55ccc024792 100644 --- a/site/docs/components/banner/examples.mdx +++ b/site/docs/components/banner/examples.mdx @@ -13,7 +13,7 @@ data: ### Static - The static Banner displays information to the user, has no interactive elements, and is non-functional. + The static banner displays information to the user, has no interactive elements, and is nonfunctional. A status icon displays alongside a supporting message. @@ -23,9 +23,9 @@ data: ### Interactive - The interactive Banner displays information to the user, has at least one function allowing users to dismiss or resolve it, and can include additional interactive elements as needed (i.e., links, buttons, etc). + The interactive banner displays information to the user, has at least one function allowing users to dismiss or resolve it, and can include additional interactive elements as needed (i.e., links, buttons). - Use `BannerActions` to add actions like close, refresh, etc. + Use `BannerActions` to add actions such as close and refresh. A status icon displays alongside a supporting message. @@ -35,7 +35,7 @@ data: ### Info - Use the info Banner when you need to display general information your user was unaware of, for example, a link to updated terms and condition. + Use the info banner when you need to display general information the user is unaware of, such as a link to updated terms and conditions. An info icon displays alongside a supporting message. @@ -45,7 +45,7 @@ data: ### Error - Use the error Banner to communicate a critical issue that prevents the user from completing a task, such as a system error or technical failure. The messaging should tell them how to resolve it. + Use the error banner to communicate a critical issue preventing the user from completing a task, such as a system error or technical failure. The messaging should tell the user how to resolve it. An error icon displays alongside a supporting message. @@ -55,7 +55,7 @@ data: ### Warning - Use the warning Banner to inform users of an issue or potential issue related to their current task that will not prevent them from continuing the task, but may cause errors if it is not addressed, such as a restriction due to entitlements or current system status. + Use the warning banner to inform users of an issue or potential issue related to their current task that won't prevent them from continuing the task, but may cause errors if they don't address it, such as a restriction due to entitlements or current system status. A warning icon displays alongside a supporting message. @@ -65,7 +65,7 @@ data: ### Success - Use the success Banner to confirm that a user's action related to their current task has been completed successfully. + Use the success banner to confirm that a user's action related to their current task was succesful. A success icon displays alongside a supporting message. diff --git a/site/docs/components/banner/index.mdx b/site/docs/components/banner/index.mdx index 22b2b5c390c..c20210e2266 100644 --- a/site/docs/components/banner/index.mdx +++ b/site/docs/components/banner/index.mdx @@ -1,7 +1,7 @@ --- title: Banner data: - description: Banner is a type of notification that displays a message or provides feedback related to the user’s current workflow and spans the page or container horizontally. It can communicate new information, errors, warnings, or successful completion of a process or task. + description: "`Banner` is a type of notification that displays a message or provides feedback related to the user’s current workflow, spanning the page or container horizontally. It can communicate new information, errors, warnings, or successful completion of a process or task." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/banner" package: name: "@salt-ds/core" @@ -10,14 +10,14 @@ data: ["Alert", "Application Message", "Notification", "Strip", "System Message"] relatedComponents: [ - { name: "Content Status", relationship: "similarTo" }, + { name: "Content status", relationship: "similarTo" }, { name: "Dialog", relationship: "similarTo" }, { name: "Toast", relationship: "similarTo" }, { name: "Tooltip", relationship: "similarTo" }, { name: "Button", relationship: "contains" }, { name: "Icon", relationship: "contains" }, { name: "Link", relationship: "contains" }, - { name: "Status Indicator", relationship: "contains" }, + { name: "Status indicator", relationship: "contains" }, ] stickerSheet: "" layout: DetailComponent diff --git a/site/docs/components/banner/usage.mdx b/site/docs/components/banner/usage.mdx index 90b26990b15..4f89c76162f 100644 --- a/site/docs/components/banner/usage.mdx +++ b/site/docs/components/banner/usage.mdx @@ -8,33 +8,35 @@ data: $ref: ./#/data --- -You should always position the Banner component in the main content area or in the related container component. It should sit directly below the navigation and span the page or container horizontally. +### Using the component + +Always position the banner component in the main content area or in the related container component. It should sit directly below the navigation and span the page or container horizontally. You should configure it to close when: -- The user performs an action that fixes an issue. For example, they correct a validation error. +- The user performs an action that fixes an issue, such as correcting a validation error. -- The system status that triggered the notification is resolved. For example, a server connection is restored. +- The system status that triggered the notification is resolved, such as restoring a server connection. -### When to use Banner +#### When to use - To show a notification that applies to the user’s current task or workflow. -### When not to use Banner +#### When not to use -- To notify users of an event that has occurred in a peripheral application or workflow. Instead, use [Toast](../toast). +- To notify users of an event that has occurred in a peripheral application or workflow. Instead, use [`Toast`](../toast). -- When the notification is caused by a low priority event not requiring user feedback. Instead, use [Toast](../toast). +- When a low priority event not requiring user feedback causes the notification. Instead, use [`Toast`](../toast). ### Content -A Banner is typically used with one or two lines of text. Content should be short, clear, and concise, allowing users to quickly scan the notification and understand the situation and/or next steps. +A banner typically has one or two lines of text. Make content short, clear, and concise, allowing users to quickly scan the notification and understand the situation and/or next steps. -The content is set to Body Default, however, if titles are needed, they should be configured to display the Body Strong typography style across densities. +Body Default applies to the content, however, if titles are necessary, you should configure them to display the Body Strong typography style across densities. See the [typography foundation](/salt/foundations/typography/) for more information. ### Import -To import Banner from the core Salt package, use: +To import `Banner` and related components from the core Salt package, use: ``` import { Banner, BannerContent, BannerActions } from "@salt-ds/core"; @@ -42,14 +44,14 @@ import { Banner, BannerContent, BannerActions } from "@salt-ds/core"; ### Props -#### Banner +#### `Banner` -#### BannerContent +#### `BannerContent` -#### BannerActions +#### `BannerActions` diff --git a/site/docs/components/border-layout/accessibility.mdx b/site/docs/components/border-layout/accessibility.mdx index a52cbf8c716..0cfa2ba6f0c 100644 --- a/site/docs/components/border-layout/accessibility.mdx +++ b/site/docs/components/border-layout/accessibility.mdx @@ -12,7 +12,7 @@ data: When building a page layout, it is important to make sure we use semantic HTML. This means using the correct HTML elements for their intended purpose as much as possible. -The Border Layout and Border Item components support this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. +The `BorderLayout` and `BorderItem` components support this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. ```tsx diff --git a/site/docs/components/border-layout/examples.mdx b/site/docs/components/border-layout/examples.mdx index 86dec9bb74a..eea931c27ab 100644 --- a/site/docs/components/border-layout/examples.mdx +++ b/site/docs/components/border-layout/examples.mdx @@ -13,7 +13,7 @@ data: ### Default -Border Layout can be set to display five regions: North, East, South, West and Center. At least one region but must be displayed alongside the Center region in the layout. +You can set `BorderLayout` to display five regions: North, East, South, West and Center. You must display at least one region alongside the Center region in the layout. By default, there are no gaps between regions. @@ -25,7 +25,7 @@ By default, there are no gaps between regions. You can manually define the size of regions. This example shows how to set the West and East regions to a fixed width, with a responsive Center region. -This layout would work well where a fixed-width side navigation is required, alongside responsive page content. +This layout would work well where a fixed-width side navigation is necessary, alongside responsive page content. @@ -33,7 +33,7 @@ This layout would work well where a fixed-width side navigation is required, alo ### Gap between regions -A gap can be added between each region. The `gap` property is a multiplier that aligns to the [Salt spacing system](/salt/foundations/spacing). +You can add a gap between each region. The `gap` prop is a multiplier that aligns to the [Salt spacing system](/salt/foundations/spacing). - The standard gap between column and row elements in Salt is 3 times the base unit. @@ -45,23 +45,23 @@ A gap can be added between each region. The `gap` property is a multiplier that ### Hide regions -Border Layout can display any combination of Border Items. This example demonstrates a layout with North, East and Center regions. +`BorderLayout` can display any combination of border items. This example demonstrates a layout with North, West and Center regions. -### Border Item position +### Border item position -Set the `position` property of the Border Item wrapper to define where content should be displayed in the layout: North, East, South, West, Center. +Set the `position` property of the border item wrapper to define where content should be displayed in the layout: North, East, South, West or Center. -### Border Item alignment +### Border item alignment -Use the `verticalAlignment` and `horizontalAlignment` properties of the Border Item wrapper to determine how content should be aligned in the region. +Use the `verticalAlignment` and `horizontalAlignment` properties of the border item wrapper to determine how content should align in the region. @@ -69,9 +69,9 @@ Use the `verticalAlignment` and `horizontalAlignment` properties of the Border I ### Sticky positioning -Use the `sticky` property of the Border Item wrapper to define a region as sticky. When set to `true`, content in surrounding regions will scroll beneath a `sticky` Border Item. +Use the `sticky` prop of the border item wrapper to define a region as sticky. When you set it to `true`, content in surrounding regions will scroll beneath a `sticky` Border Item. -This is particularly useful if you require a header, (in the North region) or side navigation (in the West) to remain visible at all times. +This is particularly useful if you require a header, (in the North region) or side navigation (in the West region) to remain visible at all times. diff --git a/site/docs/components/border-layout/index.mdx b/site/docs/components/border-layout/index.mdx index 9b7325106c6..b6446ea28df 100644 --- a/site/docs/components/border-layout/index.mdx +++ b/site/docs/components/border-layout/index.mdx @@ -1,15 +1,15 @@ --- -title: Border Layout +title: Border layout data: - description: Border Layout manages the top-level layout of your application, website, or widget. It defines five distinct regions. Four of these regions surround a main content region and are used for elements such as a footer, header or side navigation. Border Layout is built on top of Grid Layout and is specifically intended for entire website pages or application screens, where there is at least one additional region alongside the main area. + description: "`BorderLayout` manages the top-level layout of your application, website, or widget. It defines five distinct regions, with four surrounding a main content region. You can use them for elements such as a footer, header or side navigation. `BorderLayout` builds on top of `GridLayout`, and it's best to use it for entire website pages or application screens, where there's at least one additional region alongside the main area." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/border-layout/BorderLayout.tsx" package: name: "@salt-ds/core" alsoKnownAs: ["Grid", "Side panel", "Header", "Main"] relatedComponents: [ - { name: "Grid Layout", relationship: "similarTo" }, - { name: "Grid Layout", relationship: "contains" }, + { name: "Grid layout", relationship: "similarTo" }, + { name: "Grid layout", relationship: "contains" }, ] stickerSheet: "" layout: DetailComponent diff --git a/site/docs/components/border-layout/usage.mdx b/site/docs/components/border-layout/usage.mdx index dec7f857a2f..19b9658dac5 100644 --- a/site/docs/components/border-layout/usage.mdx +++ b/site/docs/components/border-layout/usage.mdx @@ -8,21 +8,23 @@ data: $ref: ./#/data --- -### When to use Border Layout +### Using the component + +#### When to use - To manage the top-level layout of your application, or page, with at least one additional region alongside the main content area (e.g., for navigation or a footer). -### When not to use Border Layout +#### When not to use -- You’re not managing the top-level layout of your application, but the layout inside one of the five Border Layout regions. +- When you're not managing the top-level layout of your application, but the layout inside one of the five border layout regions. -- For a customized layout that you can control in both row and column dimensions (for example, a Dashboard). Instead, use Grid Layout. +- For a customized layout that you can control in both row and column dimensions (for example, a dashboard). Instead, use [`GridLayout`](../grid-layout). -- For a side panel that temporarily reveals relevant content, consider using a Drawer component instead of a border layout region. +- For a side panel that temporarily reveals relevant content. Instead, use [`Drawer`](../drawer). ### Import -To import Border Layout from the core Salt package, use: +To import `BorderLayout` and `BorderItem` from the core Salt package, use: ``` import { BorderItem, BorderLayout } from "@salt-ds/core"; @@ -30,10 +32,10 @@ import { BorderItem, BorderLayout } from "@salt-ds/core"; ### Props -#### Border Layout +#### `BorderLayout` -#### Border Item +#### `BorderItem` diff --git a/site/docs/components/button/accessibility.mdx b/site/docs/components/button/accessibility.mdx index f865dc01f55..9a025258576 100644 --- a/site/docs/components/button/accessibility.mdx +++ b/site/docs/components/button/accessibility.mdx @@ -11,41 +11,32 @@ data: ### Best practices -- When a Button has both an icon and text, use`aria-hidden` on the icon so that screen readers do not announce its text. -- When a Button has an icon only and no text, pass an `aria-label` to Button that describes its purpose. +- When a button has both an icon and text, use `aria-hidden` on the icon so that screen readers don't announce its text. +- When a button has an icon only and no text, pass an `aria-label` to the button that describes its purpose. #### Focusable disabled button -- 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). - -#### 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. +- By default, a user can't place focus on a disabled button. However in certain scenarios, it may be preferable for a disabled button to receive focus. To determine if this is necessary, you can apply the following rule of thumb: "If the user or the system can enable a disabled element, it should be focusable." For further information, view the W3C guidance on the [`aria-disabled` attribute](https://www.w3.org/TR/wai-aria/#aria-disabled). ### Keyboard interactions -- 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. +- Tab moves focus to the button. +- If the button is disabled and cannot 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. -- Shift + Tab moves focus out of the component to the previous component in the tab order. +- This action moves focus out of the component to the previous component in the tab order. -- If the button has focus, Enter or Space key press activates the button. -- If the button is disabled and can receive focus, does nothing. +- If the button has focus, this action activates it. +- If the button is disabled and can receive focus, this action does nothing. diff --git a/site/docs/components/button/examples.mdx b/site/docs/components/button/examples.mdx index 9ab4a7c30a2..ca46afd7aec 100644 --- a/site/docs/components/button/examples.mdx +++ b/site/docs/components/button/examples.mdx @@ -14,9 +14,9 @@ data: ### CTA -Use the CTA button for high priority actions. For example, a CTA button may prompt a user to register, sign up, submit or buy. +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: +#### Best practices We recommend that you use CTA buttons sparingly. They represent the default or expected action on the page. @@ -26,7 +26,7 @@ We recommend that you use CTA buttons sparingly. They represent the default or e ### Primary -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. +This is the default variant. Use the primary button for routine, nonurgent actions. For example, you should use a primary button to move to the next page or complete a task. @@ -34,7 +34,7 @@ This is the default variant. Use the primary button for routine, non-urgent acti ### Secondary -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. +Use the secondary button for noncritical actions that support the user but don't impact a flow. They're typically the alternative option available alongside a primary action. For example, a secondary “back” button may support a primary “next” button. @@ -44,10 +44,10 @@ Use the secondary button for non-critical actions that support the user but do n Add an icon before the text to reinforce the button text. Add an icon after the button text to suggest movement or a direction. -Guidance: +#### 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 button is activated, there is 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, expanding a panel or opening a document. When the user activates the button, there's typically an immediate visual change. @@ -55,12 +55,12 @@ Guidance: ### Icon only -Display an icon-only button with no text when you have limited on-screen space, and the icon is easily understood. +Display an icon-only button with no text when you have limited on-screen space, and users can easily understand the icon. -Guidance: +#### Best practices -- 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”. +- 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”. @@ -68,9 +68,9 @@ Guidance: ### Disabled -Use disabled state for a button that the user can’t press. +Use the 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}`. +A button with the prop `disabled={true}` will suppress all functionality. If you need to allow the user to place focus on a disabled button, you also need to pass `focusableWhenDisabled={true}`. diff --git a/site/docs/components/button/index.mdx b/site/docs/components/button/index.mdx index 93401542556..f6f86f34dad 100644 --- 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. 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. + description: "`Button` is an interactive component that allows the user to execute an action. There are three button variants—call to action (CTA), primary (default) and secondary. You can display a 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 # @@ -16,7 +16,7 @@ data: # "contains". { name: "Link", relationship: "similarTo" }, { name: "Icon", relationship: "contains" }, - { name: "StatusIndicator", relationship: "contains" }, + { name: "Status indicator", relationship: "contains" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/button/usage.mdx b/site/docs/components/button/usage.mdx index 239ce4c8ec9..ef613d5ac9a 100644 --- a/site/docs/components/button/usage.mdx +++ b/site/docs/components/button/usage.mdx @@ -9,24 +9,24 @@ data: $ref: ./#/data --- -### Using the Button component +### Using the component - 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]() guide. -#### When to use Button +#### When to use -- 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). +To allow the user to execute an action, such as “submit”, “merge” or “upload”. Buttons are typically placed in components and contexts such as [dialogs](../dialog), [cards](../card) and [forms](/salt/patterns/forms). -#### When not to use Button +#### When not to use -- 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. +When the primary action is to take the user to another page or window rather than to trigger a function. Instead, use [`Link`](../link). ### Import {/* Update the text and code snippet below as needed: */} -To import Button from the core Salt package, use: +To import `Button` from the core Salt package, use: ```js import { Button } from "@salt-ds/core"; @@ -46,4 +46,4 @@ import { Button } from "@salt-ds/core"; ### References -Button Pattern (https://www.w3.org/WAI/ARIA/apg/patterns/button/) W3C +- Button Pattern (https://www.w3.org/WAI/ARIA/apg/patterns/button/) W3C diff --git a/site/docs/components/card/accessibility.mdx b/site/docs/components/card/accessibility.mdx index 2276a055803..0f20658daff 100644 --- a/site/docs/components/card/accessibility.mdx +++ b/site/docs/components/card/accessibility.mdx @@ -18,12 +18,12 @@ Tab moves focus to a target element in the correct tabbing order on a page. -When focus is on a target element, moves focus to the previous interactive element within the tab order. +When focus is on a target element, this action moves focus to the previous interactive element within the tab order. -If the target element has focus, Enter performs an action. +If the target element has focus, Enter activates the target element. diff --git a/site/docs/components/card/examples.mdx b/site/docs/components/card/examples.mdx index 8e2d8515700..72bc8f71c13 100644 --- a/site/docs/components/card/examples.mdx +++ b/site/docs/components/card/examples.mdx @@ -21,15 +21,15 @@ data: ### Adding actions - If you intend to add any links or buttons within your Card, use a default Card, not an Interactable Card, to ensure the component is accessible. + If you intend to add any links or buttons within your card, use a default card rather than interactable card to ensure the component is accessible. - ### Interactable Card + ### Interactable card - - Use the Interactable Card component to make the entire Card interactable. Do not use any focusable elements within Interactable Card. - - To use as a link, wrap Card in a [Link](../link) component. - - Avoid adding too much content to Interactable Cards. They should be easily readable by all users, and not take too long for a screen reader tool to read out the contents. + - Use the `InteractableCard` component to make the entire card interactable. Don't use any focusable elements within interactable cards. + - To use as a link, wrap `Card` in [`Link`](../link). + - Avoid adding too much content to interactable cards. All users should be able to read them easily, and it shouldn't take too long for a screen reader tool to read out the content. @@ -37,19 +37,19 @@ data: - ### Disabled Interactable Card - - Set `disabled={true}` to apply disabled styling to Interactable Cards. - - Make sure to also apply `disabled={true}` to any nested components, such as Text, to ensure disabled styling is also applied to the inner content. + ### Disabled interactable card + - Set `disabled={true}` to apply disabled styling to interactable cards. + - Make sure to also apply `disabled={true}` to any nested components, such as `Text`, to ensure disabled styling also applies to the content. ### Accent variations - Use the `accentPlacement` prop to position the accent bar left, right, top, or bottom of an Interactable Card. + Use the `accentPlacement` prop to position the accent bar to the left, right, top or bottom of an interactable card. - ### Multiple Cards - Layout components can be used for grouping Card components together. + ### Multiple cards + You can use layout components to group card components together. diff --git a/site/docs/components/card/index.mdx b/site/docs/components/card/index.mdx index 43bbb7f1f7d..d323d3c4740 100644 --- a/site/docs/components/card/index.mdx +++ b/site/docs/components/card/index.mdx @@ -1,7 +1,7 @@ --- title: Card data: - description: Card and Interactable Card are visually distinct content containers that displays a snapshot of information about a single subject and acts as an entry point to more detailed information. + description: "`Card` and `InteractableCard` are visually distinct content containers that display a snapshot of information about a single subject and act as an entry point for more detailed information." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/core/src/card" package: name: "@salt-ds/core" diff --git a/site/docs/components/card/usage.mdx b/site/docs/components/card/usage.mdx index 97ff74e41a5..629bf9d6903 100644 --- a/site/docs/components/card/usage.mdx +++ b/site/docs/components/card/usage.mdx @@ -8,44 +8,46 @@ data: $ref: ./#/data --- -### When to use Card +### Using the components + +#### When to use - To group related information with the same visual hierarchy. - To present a summary of a larger idea. - To link to more detailed information. -### When not to use Card +#### When not to use -- To display sequential information or emphasize ranking. Consider [List](../list) instead. -- As a stand-alone call to action. Consider [Button](../button) instead. +- To display sequential information or emphasize ranking. Instead, use [`List`](../list). +- As a stand-alone call to action. Instead, use [`Button`](../button). - For decoration purposes only. ### Card groups -- Group cards together in a layout using similar size and content length. If the content and size differs among Cards, consider layout customisation such as a Mosaic grid. -- Avoid repeating images or content in a group of Cards. +- Group cards together in a layout using similar size and content length. If the content and size differs among cards, consider layout customization such as a Mosaic grid. +- Avoid repeating images or content in a group of cards. - Use the same accent placement in a group if interactable. ### Interactable elements -A default Card can contain any UI elements, such as actionable components like [Buttons](../button) or [Links](../link). You can use these, for example, to link to more detailed information. +A default card can contain any UI elements, including actionable components such as [buttons](../button) or [links](../link). You can use these, for example, to link to more detailed information. -Interactable Cards should not contain actionable components ([Buttons](../button) or [Links](../link)) because the card itself is the interactive element. +Interactable cards shouldn't contain actionable components (like [Buttons](../button) or [Links](../link)), as the card itself is the interactive element. ### Import -To import Card from the core Salt package, use: +To import `Card` and `InteractableCard` from the core Salt package, use: -``` +```js import { Card, InteractableCard } from "@salt-ds/core"; ``` ### Props -#### Card Props +#### `Card` -#### Interactable Card Props +#### `InteractableCard` diff --git a/site/docs/components/checkbox/accessibility.mdx b/site/docs/components/checkbox/accessibility.mdx index 0dcabfa8530..592ec55034f 100644 --- a/site/docs/components/checkbox/accessibility.mdx +++ b/site/docs/components/checkbox/accessibility.mdx @@ -12,28 +12,24 @@ data: ### Best practices - If you are using a checkbox without a text description, pass an `aria-label` to the checkbox that describes its purpose. -- On focus, the screen reader should: - - Identify the checkbox - - Read out the text - - Express the state -- Moves focus to the checkbox. -- If tabbing into a checkbox group, moves focus to the first checkbox in the group. -- Press tab to move focus between all available checkbox options. +- Tab moves focus to the checkbox. +- If moving focus into a checkbox group, Tab moves focus to the first checkbox in the group. +- If focus is in a checkbox group, Tab moves focus to the next checkbox in the group. -- Press Space to change the state of the checkbox, select or deselect. +- Space changes the state of the checkbox, select or deselect. -- Move focus to outside of the checkbox component and to the previous element in the tabbing order. -- If focus is inside a checkbox group, moves focus to the previous checkbox option within the tabbing order. +- This action moves focus to outside of the checkbox component and to the previous element in the tabbing order. +- If focus is inside a checkbox group, this action moves focus to the previous checkbox option within the tab order. diff --git a/site/docs/components/checkbox/examples.mdx b/site/docs/components/checkbox/examples.mdx index f58bd8faddb..5ad9d032a5c 100644 --- a/site/docs/components/checkbox/examples.mdx +++ b/site/docs/components/checkbox/examples.mdx @@ -22,9 +22,9 @@ A single checkbox can be either selected or deselected. ### Checkbox Group: vertical (default) -Checkbox Group allows selection of one or more values from a given set of choices. They can be aligned horizontally or vertically. By default, the group is aligned vertically. +`CheckboxGroup` allows selection of one or more values from a given set of choices. They can be aligned horizontally or vertically. By default, the group is aligned vertically. -Guidance: +#### Best practices - Do not truncate checkbox text descriptions as this can hide important content relevant to the user’s workflow. Consider shortening or rewording the label if space is limited. - The checkbox should always be placed left aligned to the text. @@ -33,11 +33,11 @@ Guidance: -### Chekcbox Group: horizontal +### Checkbox Group: horizontal By default, a checkbox group is aligned vertically. To align horizontally, set `direction="horizontal"`. -Guidance: +#### Best practices Keep text as clear and concise as possible in the horizontal orientation. @@ -45,7 +45,7 @@ Keep text as clear and concise as possible in the horizontal orientation. -### Wrapping Checkbox Group +### Wrapping checkbox group By default, a checkbox group in a horizontal alignment wraps onto the next line as the viewport size changes if they don’t fit within a container. @@ -75,11 +75,11 @@ A checkbox with the prop `indeterminate={true}` will display an indeterminate ic A disabled checkbox is not interactive or focusable. -A checkbox can be disabled by setting `disabled={true}`. +You can disable a checkbox by setting `disabled={true}`. -Guidance: +#### Best practices -Use a disabled state for checkboxes that have permissions, dependencies or pre-requisites. For example, a checkbox in a [Form](/salt/patterns/forms) may be disabled because the user has not yet completed an earlier section of the form. +Use a disabled state for checkboxes that have permissions, dependencies or pre-requisites. For example, a checkbox in a [form](/salt/patterns/forms) may be disabled because the user has not yet completed an earlier section of the form. If a disabled checkbox's text description contains information that is valuable to the user, consider using a read-only checkbox instead. @@ -93,7 +93,7 @@ A read-only checkbox permits the user to only read or copy the text description, A checkbox with the prop `readOnly={true}` will suppress all functionality along with displaying read-only styling. -Guidance: +#### Best practices Read-only checkboxes are navigable using keyboard shortcuts. This means that, unlike disabled checkboxes, users can interact with the text description. Use a read-only checkbox instead of a disabled checkbox when the text description contains information that is valuable to the user. @@ -113,7 +113,7 @@ Indicate an error state by setting the `validationStatus` prop to "error". Use w Indicate a warning state by setting the `validationStatus` prop to "warning". Use when you want to alert the user to a non-critical issue related to the checkbox. -Guidance: +#### Best practices - When used in a group, use `validationStatus` on the group rather than the individual controls. Any status provided to the group will take precedence over the statuses applied directly to the nested controls. - Avoid using `validationStatus` when a checkbox is disabled. If provided, disabled functionality and styling will take precedence over any validation status styling. @@ -130,11 +130,11 @@ Checkbox supports long text descriptions. If text wraps to multiple lines, it al -### Form Field compatibility +### Form field compatibility -Checkbox group can be wrapped in a Form Field when it’s displayed within a Form context. This provides functionality built into Form Field for increased accessibility. +You can wrap checkbox groups in a form field when it’s displayed within a form. This provides functionality built into `FormField` for increased accessibility. -For more information, refer to the [Form Field](/salt/patterns/forms) guidance. +For more information, refer to the [form pattern](/salt/patterns/forms). diff --git a/site/docs/components/checkbox/index.mdx b/site/docs/components/checkbox/index.mdx index d1f38408d63..1a5f8845f2a 100644 --- a/site/docs/components/checkbox/index.mdx +++ b/site/docs/components/checkbox/index.mdx @@ -1,20 +1,20 @@ --- title: Checkbox data: - description: Checkbox and Checkbox Group allow the user to select or deselect a specific option. It can stand alone to toggle a single option, or form part of a checkbox group to toggle multiple options. + description: "`Checkbox` and `CheckboxGroup` allow users to select or deselect a specific option. A checkbox can stand alone to control a single option, or form part of a checkbox group to control multiple options." # 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/checkbox/Checkbox.tsx" package: name: "@salt-ds/core" - alsoKnownAs: ["Check Box", "Tick Box", "Tickbox"] + alsoKnownAs: ["Check box", "Tick box", "Tickbox"] relatedComponents: [ # Add a { name: "...", relationship: "..." } block for each # related component here (separated by commas). # Permitted values for relationship are: "similarTo" or # "contains". - { name: "Radio Button", relationship: "similarTo" }, + { name: "Radio button", relationship: "similarTo" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/checkbox/usage.mdx b/site/docs/components/checkbox/usage.mdx index 1a24c2104be..c62bce05bb9 100644 --- a/site/docs/components/checkbox/usage.mdx +++ b/site/docs/components/checkbox/usage.mdx @@ -9,23 +9,23 @@ data: $ref: ./#/data --- -### Using the Checkbox component +### Using the components -#### When to use Checkbox +#### When to use - To present an independent choice that the user can select or deselect. - To present a list of independent options where the user can select any number of choices. -#### When not to use Checkbox +#### When not to use -- When the checkbox displays a mutually exclusive choice between two or more options. Instead, use [Radio Button](../radio-button). -- To display a single option but trigger a state change directly and immediately. Instead, use [Switch](../switch). +- When the checkbox displays a mutually exclusive choice between two or more options. Instead, use [`RadioButton`](../radio-button). +- To display a single option but trigger a state change directly and immediately. Instead, use [`Switch`](../switch). ### Import {/* Update the text and code snippet below as needed: */} -To import Checkbox from the core Salt package, use: +To import `Checkbox` and `CheckboxGroup` from the core Salt package, use: ```js import { Checkbox, CheckboxGroup } from "@salt-ds/core"; @@ -36,11 +36,11 @@ import { Checkbox, CheckboxGroup } from "@salt-ds/core"; {/* Update packageName and componentName below as needed */} {/* packageName is optional and defaults to "core" if omitted */} -#### Checkbox +#### `Checkbox` -#### Checkbox Group +#### `CheckboxGroup` diff --git a/site/docs/components/combo-box/accessibility.mdx b/site/docs/components/combo-box/accessibility.mdx index d558fcea0f8..a4bb8cfed66 100644 --- a/site/docs/components/combo-box/accessibility.mdx +++ b/site/docs/components/combo-box/accessibility.mdx @@ -20,8 +20,8 @@ data: -- If focus is below the combo box, Shift + Tab sets focus on the component. -- If focus is on combo box, Shift + Tab moves focus to the previous focusable element in the tab order. +- If focus is below the combo box, this action sets focus on the component. +- If focus is on combo box, this action moves focus to the previous focusable element in the tab order. @@ -32,7 +32,7 @@ data: -Types a space character into the input field. +- Space types a space character into the input field. @@ -41,24 +41,24 @@ Types a space character into the input field. - If the list is closed, does nothing. Focus remains on combo box. - + -Moves visual focus to the previous item in the list. Focus does not wrap. +- Up arrow moves visual focus to the previous item in the list. Focus does not wrap. - + -Moves visual focus to the next item in the list. Focus does not wrap. +- Down arrow moves visual focus to the next item in the list. Focus does not wrap. -When focus is within the combo box, Home moves focus to the first list item. +- When focus is within the combo box, Home moves focus to the first list item. -When focus is within the combo box, End moves focus to the last list item. +- When focus is within the combo box, End moves focus to the last list item. diff --git a/site/docs/components/combo-box/examples.mdx b/site/docs/components/combo-box/examples.mdx index 9fd531c4672..12cc3428c48 100644 --- a/site/docs/components/combo-box/examples.mdx +++ b/site/docs/components/combo-box/examples.mdx @@ -16,7 +16,7 @@ data: A single item can be selected from the combo box options. -Combo Box contains an input field that opens a list. As users' type, the list displays all filtered options based on the user’s input. +Combo Box contains an input field that opens a list. As users type, the list displays all filtered options based on their input. diff --git a/site/docs/components/combo-box/index.mdx b/site/docs/components/combo-box/index.mdx index 32c45c63645..044d3ad7311 100644 --- a/site/docs/components/combo-box/index.mdx +++ b/site/docs/components/combo-box/index.mdx @@ -1,7 +1,7 @@ --- -title: Combo Box +title: Combo box data: - description: Combo Box helps users to select an item from a large list of options without scrolling. The typeahead functionality makes this selection process quicker, easier and reduces errors. Users can see a list of available options when they click on the component and then filter the list as they type. Once they’ve made their selection, it populates the field and the overlay list closes. + description: "`ComboBoxNext` helps users to select an item from a large list of options without scrolling. The typeahead functionality makes this selection process quicker, easier and reduces errors. Users can see a list of available options when they click on the component and then filter the list as they type. Once they’ve made their selection, it populates the field and the overlay list closes." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # @@ -21,10 +21,10 @@ data: # related component here (separated by commas). # Permitted values for relationship are: "similarTo" or # "contains". - { name: "List", relationship: "similarTo" }, { name: "Dropdown", relationship: "similarTo" }, - { name: "List", relationship: "contains" }, + { name: "List", relationship: "similarTo" }, { name: "Input", relationship: "contains" }, + { name: "List", relationship: "contains" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/combo-box/usage.mdx b/site/docs/components/combo-box/usage.mdx index 8fd4e386e29..05433527d2c 100644 --- a/site/docs/components/combo-box/usage.mdx +++ b/site/docs/components/combo-box/usage.mdx @@ -9,27 +9,27 @@ data: $ref: ./#/data --- -### Using the Combo Box component +### Using the component -#### When to use Combo Box +#### When to use - To display and select from a list of 10 or more options that don't need to be permanently visible to the user without selecting from a dropdown menu. - When only the selected value from a set of options needs to be visible once the selection is made. - If a workflow benefits from having a filter to quickly narrow down the available options. - If there are more than 100 options and you would like to prevent performance issues without virtualization. -#### When not to use Combo Box +#### When not to use -- To choose one value from a set of five to ten options that does not require filtering. Instead, use [Dropdown](../dropdown). -- To select a single option from fewer than five. Instead, use [Radio Button Group](../radio-button). -- To select multiple options from fewer than five. Instead, use [Checkbox Group](../checkbox). -- To make an instantaneous selection between two binary choices, for example “on” and “off”. Instead, use [Switch](../switch). +- To choose one value from a set of five to ten options that does not require filtering. Instead, use [`Dropdown`](../dropdown). +- To select a single option from fewer than five. Instead, use [`RadioButtonGroup`](../radio-button). +- To select multiple options from fewer than five. Instead, use [`CheckboxGroup`](../checkbox). +- To make an instantaneous selection between two binary choices, for example “on” and “off”. Instead, use [`Switch`](../switch). ### Import {/* Update the text and code snippet below as needed: */} -To import Combo Box from the lab Salt package, use: +To import `ComboBoxNext` from the lab Salt package, use: ```js import { ComboBoxNext } from "@salt-ds/lab"; diff --git a/site/docs/components/country-symbol/accessibility.mdx b/site/docs/components/country-symbol/accessibility.mdx index 14e9c8b9198..29785b2bb16 100644 --- a/site/docs/components/country-symbol/accessibility.mdx +++ b/site/docs/components/country-symbol/accessibility.mdx @@ -9,4 +9,4 @@ data: ### Best practices -If you're using Country Symbol for decorative purposes, and the country is named in accompanying text, you should hide its label from screen readers to avoid repetition. To hide the label, pass `aria-hidden=”true”`. +If you're using a country symbol for decorative purposes, and the country is named in accompanying text, you should hide its label from screen readers to avoid repetition. To hide the label, pass `aria-hidden=”true”`. diff --git a/site/docs/components/country-symbol/examples.mdx b/site/docs/components/country-symbol/examples.mdx index dac4a4841bf..310338e1074 100644 --- a/site/docs/components/country-symbol/examples.mdx +++ b/site/docs/components/country-symbol/examples.mdx @@ -12,23 +12,23 @@ data: ### Basic usage - Each country symbol should be imported and used individually. + You should import and use each country symbol individually. ### Size - You can change the size of each country symbol using the `size` property which acts as a multiplier for the base size, as described in the [Scale Foundation](/salt/foundations/scale). The base size of Country Symbol is based on the active density as described in the [Size Foundation](/salt/foundations/size). + You can change the size of each country symbol using the `size` property which acts as a multiplier for the base size, as described in the [scale foundation](/salt/foundations/scale). The base size of the country symbol is based on the active density as described in the [size foundation](/salt/foundations/size). - ### All Country Symbols + ### All country symbols - The following example shows all the available country symbols. Each component can be imported individually and is named via its country code. + The following example shows all the available country symbols. You can import each component individually using its respective country code. - For example the country symbol for Belgium has the code BE and can be imported as follows: + For example, the country symbol for Belgium has the code BE, which you can import as follows: ```jsx import { BE } from '@salt-ds/countries'; @@ -39,7 +39,7 @@ data: ### Lazy loading - When importing many country symbol components at once, such as with List, you may not want all the components in your initial bundle size. Instead, you can lazily load the Country Symbol components using [React Suspense](https://react.dev/reference/react/Suspense), alongside the `LazyCountrySymbol` component. `LazyCountrySymbol` takes a `code` prop to load the appropriate Country Symbol component. + When importing many country symbol components at once, such as with a list, you may not want all the components in your initial bundle size. Instead, you can lazily load the country symbol components using [React Suspense](https://react.dev/reference/react/Suspense), alongside the `LazyCountrySymbol` component. `LazyCountrySymbol` takes a `code` prop to load the appropriate country symbol component. diff --git a/site/docs/components/country-symbol/index.mdx b/site/docs/components/country-symbol/index.mdx index 45f61e5d610..58ad5489a26 100644 --- a/site/docs/components/country-symbol/index.mdx +++ b/site/docs/components/country-symbol/index.mdx @@ -1,7 +1,7 @@ --- -title: Country Symbol +title: Country symbol data: - description: Country Symbol displays an icon that represents the flag of a country or intergovernmental organization. You can use Country Symbols individually or as a complete package. The Country Symbols are stylized and representative, so users are more likely to recognize them at smaller sizes, and they maintain their character within the circular form. + description: "Country symbols display an icon that represents the flag of a country or intergovernmental organization. You can use country symbols individually or as a complete package. The country symbols are stylized and representative, so users are more likely to recognize them at smaller sizes, and they maintain their character within the circular form." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/countries/src/index.ts" package: name: "@salt-ds/countries" diff --git a/site/docs/components/country-symbol/usage.mdx b/site/docs/components/country-symbol/usage.mdx index 57eac517be0..65ea15a7f4d 100644 --- a/site/docs/components/country-symbol/usage.mdx +++ b/site/docs/components/country-symbol/usage.mdx @@ -7,19 +7,25 @@ data: $ref: ./#/data --- -#### How to use Country Symbol +### Using the components + +To reduce the core package's bundle size, country symbols are in a separate package that you should first install using: + +`npm install @salt-ds/countries` or `yarn add @salt-ds/countries` + +#### When to use When you need to display an icon that represents the flag of a country or intergovernmental organization. ### Import -To import an individual Country Symbol from the `countries` Salt package, use its country code: +To import an individual country symbol from the `countries` Salt package, use its country code: ``` import { AD, GB_ENG } from "@salt-ds/countries"; ``` -To import the Lazy Country Symbol from the `countries` Salt package, use: +To import `LazyCountrySymbol` from the `countries` Salt package, use: ``` import { LazyCountrySymbol } from "@salt-ds/countries"; @@ -27,16 +33,10 @@ import { LazyCountrySymbol } from "@salt-ds/countries"; ### Props -#### Country Symbol +#### `CountrySymbol` -#### Lazy Country Symbol +#### `LazyCountrySymbol` - -### Using the Country Symbol component - -To reduce bundle size, Country Symbols are in a separate package that you should first install using: - -`npm install @salt-ds/countries` or `yarn add @salt-ds/countries` diff --git a/site/docs/components/dialog/accessibility.mdx b/site/docs/components/dialog/accessibility.mdx index e2f38c3d3c3..dbaf179a7cf 100644 --- a/site/docs/components/dialog/accessibility.mdx +++ b/site/docs/components/dialog/accessibility.mdx @@ -12,44 +12,44 @@ data: #### Focus -The Dialog component will trap focus within the Dialog when open. This means that the user will not be able to tab out of the Dialog and focus will be set to the first focusable element within the Dialog. When the Dialog is closed, focus will be returned to the element that was focused before the Dialog was opened. +The dialog component will trap focus within the dialog when open. This means that the user will not be able to tab out of the dialog and focus will be set to the first focusable element within the dialog. When the dialog is closed, focus will be returned to the element that was focused before the dialog was opened. #### Initial focus -You can control which element receives focus when the Dialog is opened by passing an `initialFocus` prop to the Dialog component. This prop accepts a number, which indicates the index of the tabbable element within the Dialog that should receive focus. If no element is found, focus will be set to the first focusable element within the Dialog. The `initialFocus` can also be a ref to an element within the Dialog. +You can control which element receives focus when the dialog is opened by passing an `initialFocus` prop to the dialog component. This prop accepts a number, which indicates the index of the tabbable element within the dialog that should receive focus. If no element is found, focus will be set to the first focusable element within the Dialog. The `initialFocus` can also be a ref to an element within the dialog. #### Focus sequence -- For Dialogs that prompt for user confirmation, the CTA button takes focus first. +- For dialogs that prompt for user confirmation, the CTA button takes focus first. -- For Dialogs with destructive interactions, the CANCEL button takes focus first. +- For dialogs with destructive interactions, the cancel button takes focus first. ### Keyboard interactions -- When the Dialog is opened, sets focus to the first focusable component in the Dialog. -- If focus is in the Dialog, sets focus to the next focusable component in the tab order. -- If the last element in the Dialog has focus, wraps to the first focusable element in the Dialog. +- When the dialog is opened, Tab sets focus to the first focusable component in the dialog. +- If focus is in the dialog, Tab sets focus to the next focusable component in the tab order. +- If the last element in the dialog has focus, Tab wraps to the first focusable element in the dialog. -- If focus is in the Dialog, sets focus to the previous focusable component in the tab order. +- If focus is in the dialog, this action sets focus to the previous focusable component in the tab order. -- If the first element in the Dialog has focus, wraps to the last focusable element in the Dialog. +- If the first element in the dialog has focus, this action wraps to the last focusable element in the dialog. -- If focus is in the Dialog, closes the Dialog and returns focus to the triggering element. +- If focus is in the dialog, Escape closes the dialog and returns focus to the triggering element. -- If focus is on a button in the Dialog button bar, activates the button. -- If focus is on the close button, activates the close button, closes the Dialog and returns focus to the triggering element. +- If focus is on a button in the dialog button bar, this action activates the button. +- If focus is on the close button, this action activates the close button, closes the dialog and returns focus to the triggering element. diff --git a/site/docs/components/dialog/examples.mdx b/site/docs/components/dialog/examples.mdx index e5919d273d7..153dab6f8af 100644 --- a/site/docs/components/dialog/examples.mdx +++ b/site/docs/components/dialog/examples.mdx @@ -24,7 +24,7 @@ data: - ### Close Button + ### Close button You can also render the `DialogCloseButton` as a child of the `Dialog` component to render a close button in the top right corner of the dialog. You can pass the `onClick` prop like with any `Button` component to handle the close button click. diff --git a/site/docs/components/dialog/index.mdx b/site/docs/components/dialog/index.mdx index ced267b582c..c086346616c 100644 --- a/site/docs/components/dialog/index.mdx +++ b/site/docs/components/dialog/index.mdx @@ -1,15 +1,15 @@ --- title: Dialog data: - description: Dialog is a window that opens over the application content, focusing the user’s attention on a particular task or piece of information. It can communicate new information, errors, warnings, or successful completion of a process or task. + description: "`Dialog` is a window that opens over the application content, focusing the user’s attention on a particular task or piece of information. It can communicate new information, errors, warnings, or successful completion of a process or task." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/lab/src/dialog" package: name: "@salt-ds/lab" - alsoKnownAs: ["Modal", "Modal Dialog", "Overlay", "Popup"] + alsoKnownAs: ["Modal", "Modal dialog", "Overlay", "Popup"] relatedComponents: [ { name: "Banner", relationship: "similarTo" }, - { name: "Content Status", relationship: "similarTo" }, + { name: "Content status", relationship: "similarTo" }, { name: "Toast", relationship: "similarTo" }, ] layout: DetailComponent diff --git a/site/docs/components/dialog/usage.mdx b/site/docs/components/dialog/usage.mdx index 5fe227d18bb..ed752e50183 100644 --- a/site/docs/components/dialog/usage.mdx +++ b/site/docs/components/dialog/usage.mdx @@ -8,13 +8,15 @@ data: $ref: ./#/data --- -Dialogs are interruptive by nature and should be used sparingly. Use Dialog to present or gather critical information that requires immediate action, whether it’s directly or indirectly part of the user’s current task. For example, a warning dialog that appears when a document is closed without being saved—and asks how the user wishes to proceed—is indirectly related to the user’s task. +### Using the component + +Dialogs are interruptive by nature and should be used sparingly. Use dialogs to present or gather critical information that requires immediate action, whether it’s directly or indirectly part of the user’s current task. For example, a warning dialog that appears when a document is closed without being saved—and asks how the user wishes to proceed—is indirectly related to the user’s task. ### Status For status dialogs you can set the `status` prop to `error`, `warning`, `success`, or `info` to render a status icon in the title and change the border color of the Dialog. For accessibility reasons, you should pass a `role="alertdialog"` to the Dialog component when rendering an alert dialog. You should rely on users' acknowledgment of the message by clicking the action button. -### When to use Dialog +### When to use - To notify critical information that requires immediate action. @@ -22,15 +24,15 @@ For status dialogs you can set the `status` prop to `error`, `warning`, `success - To interrupt user's flow. -### When not to use Dialog +### When not to use -- When non-disruptive feedback will suffice. If the information you’re displaying is part of an event that’s occurred in a peripheral application or workflow, use [Toast](../toast) instead. If the information you're displaying is related to the current workflow, use [Banner](../banner) instead. +- When non-disruptive feedback will suffice. If the information you’re displaying is part of an event that’s occurred in a peripheral application or workflow, use [`Toast`](../toast) instead. If the information you're displaying is related to the current workflow, use [`Banner`](../banner) instead. - To launch a dialog from another dialog. Users may struggle to dismiss the two dialogs and may not understand which dialog is higher priority. Consider an alternative solution, such as progressively disclosing information in the first dialog. ### Import -To import Dialog from the lab Salt package, use: +To import `Dialog` and related components from the lab Salt package, use: ``` import { @@ -44,22 +46,22 @@ import { ### Props -#### Dialog +#### `Dialog` -#### Dialog Title +#### `DialogTitle` -#### Dialog Actions +#### `DialogActions` -#### Dialog Content +#### `DialogContent` -#### Dialog Close Button +#### `DialogCloseButton` diff --git a/site/docs/components/drawer/accessibility.mdx b/site/docs/components/drawer/accessibility.mdx index 7e238f40c5c..dbd418f43ba 100644 --- a/site/docs/components/drawer/accessibility.mdx +++ b/site/docs/components/drawer/accessibility.mdx @@ -16,24 +16,24 @@ You can customize or disable the animations using the `prefers-reduced-motion` C -- Activates the trigger/disclosure button if it is in focus, controlling the visibility of the Drawer. +- This action activates the trigger/disclosure button if it is in focus, controlling the visibility of the drawer. - In closed state: The trigger is a user-defined content element. Drawer opens and focus is set to first focusable element in the Drawer. - In open state: The trigger is the Drawer's 'X' button. Drawer closes and focus returns to content element trigger. -- Moves focus on to the next focusable element in the Drawer. When focus is on the last element in the Drawer, it moves focus to first focusable element in the Drawer. +- Tab moves focus on to the next focusable element in the drawer. When focus is on the last element in the drawer, it moves focus to first focusable element in the drawer. -- Moves focus to the previous focusable element in the Drawer. When focus is on the first element in a Drawer, it moves focus to last focusable element in the Drawer. +- This action moves focus to the previous focusable element in the drawer. When focus is on the first element in a drawer, it moves focus to last focusable element in the drawer. -- Closes the Drawer and returns focus to the trigger button. +- Escape closes the drawer and returns focus to the trigger button. diff --git a/site/docs/components/drawer/examples.mdx b/site/docs/components/drawer/examples.mdx index c729987ab2c..bd7d8694928 100644 --- a/site/docs/components/drawer/examples.mdx +++ b/site/docs/components/drawer/examples.mdx @@ -10,33 +10,33 @@ data: -### Top Positioned +### Top positioned -Set `position="top"` to display the Drawer component at the top. +Set `position="top"` to display the drawer component at the top. -### Right Positioned +### Right positioned -Set `position="right"` to display the Drawer component on the right. +Set `position="right"` to display the drawer component on the right. -### Left Positioned +### Left positioned -By default, the Drawer is displayed on the left if the `position` prop is not set. +By default, the drawer is displayed on the left if the `position` prop is not set. -### Bottom Positioned +### Bottom positioned -Set `position="bottom"` to display the Drawer component at the bottom. +Set `position="bottom"` to display the drawer component at the bottom. diff --git a/site/docs/components/drawer/index.mdx b/site/docs/components/drawer/index.mdx index 8ae2629195c..ae7279c9648 100644 --- a/site/docs/components/drawer/index.mdx +++ b/site/docs/components/drawer/index.mdx @@ -1,12 +1,12 @@ --- title: Drawer data: - description: A Drawer is an expandable panel that users can open and close with a sliding animation. Use this component to display content as an overlay within the application layout. With Drawer, the user can view additional content without navigating away from the current screen. + description: "`Drawer` is an expandable panel that users can open and close with a sliding animation. Use this component to display content as an overlay within the application layout. With a drawer, the user can view additional content without navigating away from the current screen." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/lab/src/drawer/Drawer.tsx" package: name: "@salt-ds/lab" initialVersion: "1.0.0" - alsoKnownAs: ["Flyout", "Sheet", "Sidebar", "Side Panel", "Split View"] + alsoKnownAs: ["Flyout", "Sheet", "Sidebar", "Side panel", "Split view"] relatedComponents: [ { name: "Overlay", relationship: "similarTo" }, diff --git a/site/docs/components/drawer/usage.mdx b/site/docs/components/drawer/usage.mdx index 87a862ef293..9cde329f9bb 100644 --- a/site/docs/components/drawer/usage.mdx +++ b/site/docs/components/drawer/usage.mdx @@ -7,23 +7,25 @@ data: $ref: ./#/data --- -Use the Drawer component by wrapping it around your content and setting the desired position. Provide a mechanism, such as [Button](../button), for users to open and close it. +### Using the component -When open, the Drawer displays a visual overlay, also known as a scrim, over the underlying content. It also plays relevant animations when opening and closing that can be visually customized via CSS. +Use the component by wrapping it around your content and setting the desired position. Provide a mechanism, such as [`Button`](../button), for users to open and close it. -Use the `useDrawer` hook to handle interactions with the Drawer, such as opening and closing it. +When open, the drawer displays a visual overlay, also known as a scrim, over the underlying content. It also plays relevant animations when opening and closing that can be visually customized via CSS. -### When to use Drawer +Use the `useDrawer` hook to handle interactions with the drawer, such as opening and closing it. -- Use Drawer when you need additional content, such as a form or sidebar navigation, to be displayed in a specific area of the screen. +### When to use -### When not to use Drawer +- When you need additional content, such as a form or sidebar navigation, to be displayed in a specific area of the screen. -- If you want your content split between pages or tabs, consider [Deck Layout](../deck-layout) instead. +### When not to use + +- If you want your content split between pages or tabs. Instead, use [`DeckLayout`](../deck-layout). ### Import -To import Drawer from the lab Salt package, use: +To import `Drawer` and `useDrawer` from the lab Salt package, use: ```js import { Drawer, useDrawer } from "@salt-ds/lab"; diff --git a/site/docs/components/dropdown/accessibility.mdx b/site/docs/components/dropdown/accessibility.mdx index 14a3c1daca0..959dd96320d 100644 --- a/site/docs/components/dropdown/accessibility.mdx +++ b/site/docs/components/dropdown/accessibility.mdx @@ -9,7 +9,7 @@ data: $ref: ./#/data --- -The following keyboard interactions are provided: +### Keyboard interactions @@ -19,41 +19,41 @@ The following keyboard interactions are provided: -- If focus is below the dropdown, sets focus on the component. +- If focus is below the dropdown, this action sets focus on the component. -- If the dropdown list is closed, opens the list. Focus is set to the first item. -- If the list is open, selects the list item that has focus and closes the list. +- If the dropdown list is closed, this action opens the list. Focus is set to the first item. +- If the list is open, this action selects the list item that has focus and closes the list. -- If the dropdown list is open and has focus, closes the list without making a selection. Focus remains on the dropdown button. +- If the dropdown list is open and has focus, Escape closes the list without making a selection. Focus remains on the dropdown button. - + -- If the dropdown list is closed, opens it and moves visual focus to the next item in the list. Focus does not wrap. +- If the dropdown list is closed, Down arrow opens it and moves visual focus to the next item in the list. Focus does not wrap. - + -- If the dropdown is open, moves visual focus to the previous item in the list. Focus does not wrap. +- If the dropdown list is open, Up arrow moves visual focus to the previous item in the list. Focus does not wrap. -- When focus is within the dropdown, Home moves focus to the first List item. +- When focus is within the dropdown, Home moves focus to the first list item. -- When focus is within the dropdown, End moves focus to the last List item. +- When focus is within the dropdown, End moves focus to the last list item. diff --git a/site/docs/components/dropdown/examples.mdx b/site/docs/components/dropdown/examples.mdx index 77273b688c6..8d36d72f8bf 100644 --- a/site/docs/components/dropdown/examples.mdx +++ b/site/docs/components/dropdown/examples.mdx @@ -14,7 +14,7 @@ data: ### Dropdown -Dropdown contains a button that opens a list on mouse or keyboard interaction. +Dropdowns contain a button that opens a list on mouse or keyboard interaction. @@ -22,13 +22,13 @@ Dropdown contains a button that opens a list on mouse or keyboard interaction. ### Variants -Dropdown has two variants: `primary` and `secondary`. The primary variant is set by default. Set to secondary with `variant=”secondary”`. +The component has two variants: `primary` and `secondary`. The primary variant is set by default. Set to secondary with `variant=”secondary”`. Choose secondary when used in a data-dense or compact interface, or for a form with multiple columns or sections. The choice between primary and secondary variants should be considered alongside the background color it sits upon. -Tip: The [Forms pattern](/salt/patterns/forms) provides further guidance on primary versus secondary control selection. +Tip: The [forms pattern](/salt/patterns/forms) provides further guidance on primary versus secondary control selection. @@ -44,7 +44,7 @@ By default, the dropdown’s field is empty. When the `defaultSelected` prop is ### Read-only -Set Dropdown to read-only to allow values to be displayed that are predefined and not editable, for instance when a user does not have the appropriate permissions to select an option within the dropdown. +Set the dropdown to read-only to allow values to be displayed that are predefined and not editable, for instance when a user does not have the appropriate permissions to select an option within the dropdown. When `readOnly={true}` users will not be able to interact with dropdown apart from focusing on it. Use to indicate that the pre-selected value is valid but changes are not permitted. @@ -55,11 +55,11 @@ Use to indicate that the pre-selected value is valid but changes are not permitt ### Disabled -Dropdown can be disabled if required, for instance if the access to the options needs to be restricted based on the current context. +You can disable the dropdown if required, for instance if the access to the options needs to be restricted based on the current context. Unlike read-only, the disabled state can change for the current user depending on context. Showing it in a disabled state allows the user to be aware of the presence of the control, without enabling access to its functionality temporarily. -When `disabled={true}`, user will not be able to interact with dropdown, it does not receive focus on any interaction. +When `disabled={true}`, user will not be able to interact with dropdown. It does not receive focus on any interaction. diff --git a/site/docs/components/dropdown/index.mdx b/site/docs/components/dropdown/index.mdx index 31e3c8d6e6c..365816c25db 100644 --- a/site/docs/components/dropdown/index.mdx +++ b/site/docs/components/dropdown/index.mdx @@ -1,24 +1,24 @@ --- title: Dropdown data: - description: Dropdown allows the user to select from an overlayed vertical list of options. A selected value is displayed in the dropdown field. Dropdown provides a screen space-efficient way of interacting with a list of selectable options. + description: "`DropdownNext` allows the user to select from an overlayed vertical list of options. A selected value is displayed in the dropdown field. Dropdowns provide a screen space-efficient way of interacting with a list of selectable options." # 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/lab/src/dropdown-next/DropdownNext.tsx" package: name: "@salt-ds/lab" - alsoKnownAs: ["Select", "Picklist", "Menu Button", "Form Field"] + alsoKnownAs: ["Select", "Picklist", "Menu button", "Form field"] relatedComponents: [ # Add a { name: "...", relationship: "..." } block for each # related component here (separated by commas). # Permitted values for relationship are: "similarTo" or # "contains". { name: "Checkbox", relationship: "similarTo" }, - { name: "Combo Box", relationship: "similarTo" }, + { name: "Combo box", relationship: "similarTo" }, { name: "List", relationship: "similarTo" }, { name: "List", relationship: "contains" }, - { name: "List Items", relationship: "contains" }, + { name: "List items", relationship: "contains" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/dropdown/usage.mdx b/site/docs/components/dropdown/usage.mdx index 577ac0dfee6..260e0f51162 100644 --- a/site/docs/components/dropdown/usage.mdx +++ b/site/docs/components/dropdown/usage.mdx @@ -9,26 +9,26 @@ data: $ref: ./#/data --- -### Using the Dropdown component +### Using the component -#### When to use Dropdown +#### When to use - When a user needs the ability to choose one value from a set of five to 10 options. - When only the selected value from a set of options needs to be visible once the selection is made. -#### When not to use Dropdown +#### When not to use -- When you have more than 10 options and users would benefit from filtering to narrow down the available options. Instead, use [Combo Box](../combo-box). -- When you have fewer than five options and need to one option to be selected. Instead, use [Radio Button Group](../button). -- When you have fewer than five options and multiple selections are required, or possible. Instead, use [Checkbox Group](../checkbox). -- If you have a Boolean selection, for instance “on” or “off”. Instead, use [Switch](../switch). -- When you have large number (>100) of list items, to prevent performance issues without virtualization, we strongly recommend adding a filter e.g. use a [Combo Box](../combo-box) instead of Dropdown +- When you have more than 10 options and users would benefit from filtering to narrow down the available options. Instead, use [`ComboBoxNext`](../combo-box). +- When you have fewer than five options and need to one option to be selected. Instead, use [`RadioButtonGroup`](../button). +- When you have fewer than five options and multiple selections are required, or possible. Instead, use [`CheckboxGroup`](../checkbox). +- If you have a Boolean selection, for instance “on” or “off”. Instead, use [`Switch`](../switch). +- When you have large number (>100) of list items, to prevent performance issues without virtualization, we strongly recommend adding a filter e.g. use a [`ComboBox`](../combo-box) instead. ### Import {/* Update the text and code snippet below as needed: */} -To import Dropdown from the lab Salt package, use: +To import `DropdownNext` from the lab Salt package, use: ```js import { DropdownNext } from "@salt-ds/lab"; diff --git a/site/docs/components/flex-layout/accessibility.mdx b/site/docs/components/flex-layout/accessibility.mdx index bcc80c6786c..b084af1def1 100644 --- a/site/docs/components/flex-layout/accessibility.mdx +++ b/site/docs/components/flex-layout/accessibility.mdx @@ -9,9 +9,11 @@ data: $ref: ./#/data --- -When building a layout for part of a page using Flex Layout, it is important to make sure you use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. +### Best practices -Flex Layout and Flex Item components support this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `“div”`. +When building a layout for part of a page using `FlexLayout`, it is important to make sure you use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. + +`FlexLayout` and `FlexItem` components support this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `“div”`. ```tsx diff --git a/site/docs/components/flex-layout/examples.mdx b/site/docs/components/flex-layout/examples.mdx index d9f25739789..761b2f8b1e5 100644 --- a/site/docs/components/flex-layout/examples.mdx +++ b/site/docs/components/flex-layout/examples.mdx @@ -15,9 +15,9 @@ data: ### Default -By default, Flex Layout displays items along the horizontal axis in a row, aligned to the start of the container. The spacing between items is driven by the property `gap`, which is a multiple of the [Salt base unit](/salt/foundations/spacing) and is set to 3. The dimensions of the layout (height or width) are driven by the items contained within it. +By default, `FlexLayout` displays items along the horizontal axis in a row, aligned to the start of the container. The spacing between items is driven by the property `gap`, which is a multiple of the [Salt base unit](/salt/foundations/spacing) and is set to 3. The dimensions of the layout (height or width) are driven by the items contained within it. -#### Guidance +#### Best practices Set `wrap={true}` to overflow items onto subsequent rows when they no longer fit in the container. @@ -27,7 +27,7 @@ Set `wrap={true}` to overflow items onto subsequent rows when they no longer fit ### Column direction -The Flex Layout `direction` prop defines the main axis that items are displayed along. Set `direction` to `column` to display items in a vertical direction. +The flex layout `direction` prop defines the main axis that items are displayed along. Set `direction` to `column` to display items in a vertical direction. @@ -35,9 +35,9 @@ The Flex Layout `direction` prop defines the main axis that items are displayed ### Layout position -Control the position of Flex Layout and its items using the `align` and `justify` props. +Control the position of the flex layout and its items using the `align` and `justify` props. -Use `justify` to define how to distribute any remaining space between or around all of the items along the main-axis of Flex Layout (i.e., along the row or column). +Use `justify` to define how to distribute any remaining space between or around all of the items along the main-axis of the flex layout (i.e., along the row or column). If there is additional space available in the cross-axis of the layout (i.e., beside a row, or above/below a column), the `align` prop defines how items should be positioned within that space. @@ -47,9 +47,7 @@ If there is additional space available in the cross-axis of the layout (i.e., be ### Responsive layout -Flex Layout supports responsive props, so you can define different behaviors based on viewport size (e.g., switching `direction` with screen size). You can use the default [Salt breakpoints](/salt/foundations/responsiveness#breakpoints) or pass in your own using `SaltProvider`. - -#### What are responsive props? +Flex layouts support responsive props, so you can define different behaviors based on viewport size (e.g., switching `direction` with screen size). You can use the default [Salt breakpoints](/salt/foundations/responsiveness#breakpoints) or pass in your own using `SaltProvider`. A responsive prop is a prop that takes either multiple values (one value per breakpoint), or a single value that would take effect across all different screen sizes. For example, a layout that will responsively change direction from row to column at specific breakpoints or viewport sizes: @@ -63,7 +61,7 @@ direction={{ xs: "row", sm: "column", lg: "row", md: "column", xl: "row" }} ### Flex item position -Use the Flex Item `align` prop to set an alignment for a specific item in the layout. Use the `align` prop to set the item’s position along the cross-axis of the layout (i.e., perpendicular to the `direction`–`row` or `column`). +Use the flex item's `align` prop to set an alignment for a specific item in the layout. Use the `align` prop to set the item’s position along the cross-axis of the layout (i.e., perpendicular to the `direction`–`row` or `column`). @@ -71,15 +69,13 @@ Use the Flex Item `align` prop to set an alignment for a specific item in the la ### Flex item size -The Flex Item `grow` prop enables specific items in the layout to grow and fill any remaining space that is available in the layout: +The flex item's `grow` prop enables specific items in the layout to grow and fill any remaining space that is available in the layout: - By default, `grow` is set to 0 and items will be displayed in their ‘normal’ size. - If an item is set to `1` it will fill the available space. - If an item is set to `2` it will fill twice as much space as other items that have `grow` set to `1`. -#### Guidance - -- In contrast to the `grow` prop, the `shrink` prop makes a specific item as small as possible within the layout. By default, `shrink` is set to `1`. If an item is set to `2`, that item would attempt to take half as much space. +In contrast to the `grow` prop, the `shrink` prop makes a specific item as small as possible within the layout. By default, `shrink` is set to `1`. If an item is set to `2`, that item would attempt to take half as much space. diff --git a/site/docs/components/flex-layout/index.mdx b/site/docs/components/flex-layout/index.mdx index 38b601e1e3c..024a13a596e 100644 --- a/site/docs/components/flex-layout/index.mdx +++ b/site/docs/components/flex-layout/index.mdx @@ -1,16 +1,16 @@ --- -title: Flex Layout +title: Flex layout data: - description: Flex Layout controls the direction, size and position of items displayed in a UI container. Use when the direction needs complex customization that can't be achieved by Stack, Flow or Split Layout. For additional control of the size and position of content, use Flex Item for each content item inside Flex Layout. + description: "`FlexLayout` controls the direction, size and position of items displayed in a UI container. Use when the direction needs complex customization that can't be achieved by `StackLayout`, `FlowLayout` or `SplitLayout`. For additional control of the size and position of content, use `FlexItem` for each content item inside `FlexLayout`." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/flex-layout/FlexLayout.tsx" package: name: "@salt-ds/core" - alsoKnownAs: ["CSS Flexbox", "Flexible Box", "Responsive Layout"] + alsoKnownAs: ["CSS flexbox", "Flexible box", "Responsive layout"] relatedComponents: [ - { name: "Split Layout", relationship: "similarTo" }, - { name: "Flow Layout", relationship: "similarTo" }, - { name: "Stack Layout", relationship: "similarTo" }, + { name: "Flow layout", relationship: "similarTo" }, + { name: "Split layout", relationship: "similarTo" }, + { name: "Stack layout", relationship: "similarTo" }, ] layout: DetailComponent diff --git a/site/docs/components/flex-layout/usage.mdx b/site/docs/components/flex-layout/usage.mdx index 75f969b4897..8000819bcb8 100644 --- a/site/docs/components/flex-layout/usage.mdx +++ b/site/docs/components/flex-layout/usage.mdx @@ -9,25 +9,25 @@ data: $ref: ./#/data --- -### When to use Flex Layout +### Using the components -- When a complex layout cannot first be achieved using the Flow, Stack and Split layouts. However, if you are very familiar with [CSS Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/), you may choose to use Flex Layout from the start. +#### When to use + +- When a complex layout cannot first be achieved using flow, stack and split layouts. However, if you are very familiar with [CSS Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/), you may choose to use a flex layout from the start. - You want a layout that flows in a single dimension, where the dimension may change depending on other factors, such as viewport size. For example, in layouts where the direction and overflow behavior need to change depending on the viewport size or device. - For small-scale layout of components within a container or region within an application or webpage. -### When not to use Flex Layout - -- When Flow, Stack or Split Layout can achieve your desired layout. These components are optimized for specific use cases in a constant direction. - -- When you need to present content over both rows and columns at the same time, such as a Dashboard or multi-column Form, use the Grid Layout. +#### When not to use -- For large-scale, page-level layout. Instead, use Grid or Border Layouts. +- When a flow, stack or split layout can achieve your desired layout. These components are optimized for specific use cases in a constant direction. +- When you need to present content over both rows and columns at the same time, such as a dashboard or multi-column Form, use [`GridLayout`](../grid-layout/). +- For large-scale, page-level layout. Instead, use [`GridLayout`](../grid-layout/) or [`BorderLayout`](../border-layout/). ### Import -To import Flex Layout from the core Salt package, use: +To import `FlexLayout` and `FlexItem` from the core Salt package, use: ```js import { FlexLayout, FlexItem } from "@salt-ds/core"; @@ -35,10 +35,10 @@ import { FlexLayout, FlexItem } from "@salt-ds/core"; ### Props -#### Flex Layout +#### `FlexLayout` -#### Flex Item +#### `FlexItem` diff --git a/site/docs/components/flow-layout/accessibility.mdx b/site/docs/components/flow-layout/accessibility.mdx index 72a7067cb43..4daa1e25923 100644 --- a/site/docs/components/flow-layout/accessibility.mdx +++ b/site/docs/components/flow-layout/accessibility.mdx @@ -9,9 +9,11 @@ data: $ref: ./#/data --- -When building a sub-section of a page using Flow Layout, it is important to make sure you use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. +### Best practices -Flow Layout supports this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. +When building a sub-section of a page using a flow layout, it's important to use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. + +Flow layouts support this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. ```tsx diff --git a/site/docs/components/flow-layout/examples.mdx b/site/docs/components/flow-layout/examples.mdx index 4bf30185c7e..ec57f619ec2 100644 --- a/site/docs/components/flow-layout/examples.mdx +++ b/site/docs/components/flow-layout/examples.mdx @@ -15,11 +15,11 @@ data: ### Default -Flow Layout displays items in a row which will responsively wrap onto a new line. +Flow Layout displays items in a row that will responsively wrap onto a new line. By default, items will stretch across the layout, with a `gap` between items of 3, which is a multiple of the [Salt base unit](/salt/foundations/spacing). -The height and width of the layout area are driven by the items contained within it. +The height and width of the layout area depend on the items contained within it. @@ -27,39 +27,37 @@ The height and width of the layout area are driven by the items contained within ### Layout position -Control the position of Flow Layout and its items using `align` and `justify` props. +Control the position of the flow layout and its items using `align` and `justify` props. Use `justify` to define how to distribute any remaining space between or at the ends of items in the row. -If there is additional space available above or below the row, use the `align` property to define how items should be positioned within that space. +If there's additional space available above or below the row, use the `align` property to define the position of items within that space. -### Flex Item position +### Flex item position -Use the Flex Item `align` prop to set an alignment for a specific item in the layout. +Use the flex item `align` prop to set an alignment for a specific item in the layout. -Set the item’s position along the cross-axis of the layout (i.e., perpendicular to the row). +Set the item’s position along the cross axis of the layout (i.e., perpendicular to the row). -### Flex Item size +### Flex item size -The Flex Item `grow` prop enables specific items in the layout to grow and fill any remaining space in the row: +The flex item `grow` prop enables specific items in the layout to grow and fill any remaining space in the row: -- By default, `grow` is set to 0 and items will be displayed in their ‘normal’ size. +- By default, `grow` is 0 and items will be in their "normal" size. -- If an item is set to ‘1’ it will fill the available space. +- If you set an item to 1, it will fill the available space. -- If an item is set to ‘2’ it will fill twice as much space as other items that have `grow` set to ‘1’. +- If you set an item to 2, it will fill twice as much space as other items that have `grow` set to 1. -#### Guidance - -- In contrast to `grow`, `shrink` makes a specific item as small as possible within the row. By default, `shrink` is set to `1`. If an item is set to `2`, that item will attempt to take half as much space. +In contrast to `grow`, `shrink` makes a specific item as small as possible within the row. By default, `shrink` is 1. If you set an item to 2, it will attempt to take half as much space. diff --git a/site/docs/components/flow-layout/index.mdx b/site/docs/components/flow-layout/index.mdx index 355ed22eaf1..d9315d1b418 100644 --- a/site/docs/components/flow-layout/index.mdx +++ b/site/docs/components/flow-layout/index.mdx @@ -1,7 +1,7 @@ --- -title: Flow Layout +title: Flow layout data: - description: Flow Layout displays items in a horizontal order and wraps them onto a subsequent row if they don’t fit within the defined width. It is built on top of the Flex Layout component and is specifically intended for small-scale layouts where components need to be displayed in a responsive row, such as a row of metrics or a filter bar where fields can wrap over multiple lines. For additional control of the size and position of content, use Flex Item for each content item inside Flow Layout. + description: "`FlowLayout` displays items in a horizontal order and wraps them onto a subsequent row if they don’t fit within the defined width. It builds on top of the `FlexLayout` component and is best for small-scale layouts where you need to display components in a responsive row, such as a row of metrics or a filter bar where fields can wrap over multiple lines. For additional control of the size and position of content, use `FlexItem` for each content item inside a flow layout." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # @@ -14,10 +14,10 @@ data: # related component here (separated by commas). # Permitted values for relationship are: "similarTo" or # "contains". - { name: "Split Layout", relationship: "similarTo" }, - { name: "Stack Layout", relationship: "similarTo" }, - { name: "Flex Layout", relationship: "similarTo" }, - { name: "Flex Layout", relationship: "contains" }, + { name: "Flex layout", relationship: "similarTo" }, + { name: "Split layout", relationship: "similarTo" }, + { name: "Stack layout", relationship: "similarTo" }, + { name: "Flex layout", relationship: "contains" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/flow-layout/usage.mdx b/site/docs/components/flow-layout/usage.mdx index 4c191d640a8..00b50a6e95f 100644 --- a/site/docs/components/flow-layout/usage.mdx +++ b/site/docs/components/flow-layout/usage.mdx @@ -9,21 +9,23 @@ data: $ref: ./#/data --- -### When to use Flow Layout +### Using the component -- When you want to build responsive layouts that will wrap across multiple rows as soon as there is not enough space on the viewport. +### When to use -- For small-scale layouts within the application, such as a card in a Dashboard displaying metrics or a header bar containing filter controls. +- To build responsive layouts that wrap across multiple rows when there isn't enough space in the viewport. -### When not to use Flow Layout +- For small-scale layouts within the application, such as a card in a dashboard displaying metrics or a header bar containing filter controls. -- Flow Layout will always wrap. If you want to create a layout in a row that doesn’t wrap, use [Stack Layout](/salt/components/stack-layout). +### When not to use -- You want the layout to have more complex customization. In this case we recommend you having a look at [Flex Layout](/salt/components/flex-layout). +- A flow layout will always wrap. If you want to create a layout in a row that doesn’t wrap, use [`StackLayout`](/salt/components/stack-layout). + +- If you want the layout to have more complex customization. In this case, we recommend [`FlexLayout`](/salt/components/flex-layout). ### Import -To import Flow Layout from the core Salt package, use: +To import `FlowLayout` from the core Salt package, use: ```js import { FlowLayout } from "@salt-ds/core"; diff --git a/site/docs/components/form-field/accessibility.mdx b/site/docs/components/form-field/accessibility.mdx index fed854a895a..24f0a828c54 100644 --- a/site/docs/components/form-field/accessibility.mdx +++ b/site/docs/components/form-field/accessibility.mdx @@ -9,4 +9,4 @@ data: ### Keyboard interactions -All keyboard interactions are supplied by the underlying wrapped components, rather than the Form Field component. +All keyboard interactions are supplied by the underlying wrapped components, rather than the `FormField` component. diff --git a/site/docs/components/form-field/examples.mdx b/site/docs/components/form-field/examples.mdx index 9f69d4832d9..f52a439c5c1 100644 --- a/site/docs/components/form-field/examples.mdx +++ b/site/docs/components/form-field/examples.mdx @@ -7,56 +7,56 @@ data: $ref: ./#/data --- -All examples demonstrate Salt form controls inside the Form Field, including [Input](../input), [Checkbox](../checkbox) and [Radio Button](../radio-button). These components are available as part of the Salt component library in addition to Form Field. +All examples demonstrate Salt form controls inside the form field, including [`Input`](../input), [`Checkbox`](../checkbox) and [`RadioButton`](../radio-button). These components are available as part of the Salt component library in addition to `FormField`. ### Default -Form Field is a wrapper for UI controls that are typically found in a form (for example, [Input](../input), [Combobox](../combo-box) or [Radio Button](../radio-button)). Form Field makes these controls accessible by providing them with a visible label, validation control, states and descriptive text elements. +A form field is a wrapper for UI controls typically found in a form (for example, [`Input`](../input), [`Combobox`](../combo-box) or [`RadioButton`](../radio-button)). Form fields make these controls accessible by providing them with a visible label, validation control, states and descriptive text elements. ### Disabled -Form Field can be disabled via the prop `disabled`. +You can disable a form field via the prop `disabled`. -- The prop should be applied to the field, not the control it contains, for expected results. +- You should apply the prop to the field, not the control it contains, for expected results. -- Fields are typically disabled if the context or required permissions prevent the user from interacting with a field. +- You'd typically disable a form field if the context or required permissions prevent the user from interacting with a field. -- Text contrast is not WCAG AA compliant; an editable field is only disabled if the field is not relevant at the current time. +- Text contrast isn't WCAG AA compliant; an editable field is only in the disabled state if the field isn't relevant at the time. ### Helper text -Form Field can display helper text using the `FormFieldHelperText` component. +Form Field can display helper text using the `FormFieldHelperText` component: -- Use helper text to provide additional guidance to users, such as an instruction (when it’s not obvious what action the user must take), or if you need to show an example of acceptable formats to increase the likelihood of successful entry. +- Use helper text to provide additional guidance to users, such as an instruction (when it’s not obvious what action the user must take) or if you need to show an example of acceptable formats to increase the likelihood of successful entry. - Keep your form label short by moving guidance to the helper text. -### Helper text as Tooltip +### Helper text as tooltip -Display the helper text in a [Tooltip](../tooltip) when you are low on screen real-estate. +Display the helper text in a [tooltip](../tooltip) when you're low on screen real estate. ### Label -Form field provides a visible label which should be used to describe the form control in the field. The label is placed above the form control by default. Display the label via the `FormFieldLabel` component. +Form fields provides a visible label which you should use to describe the form control in the field. The label is above the form control by default. Display the label via the `FormFieldLabel` component: -- The label should be easy to scan and be no more than three words long. +- Users should be able to easily scan the label, which should be no more than three words long. -- Use the label to describe the information/data the field is collecting (e.g., Name, Location, Currency). +- Use the label to describe the information or data the field is collecting (e.g., Name, Location, Currency). - Use `FormFieldHelperText` to provide additional information and context to help the user complete the field. @@ -65,89 +65,89 @@ Form field provides a visible label which should be used to describe the form co ### Label placement left -The form field label can be positioned to the left of the form control via the prop `labelPlacement`. +You can position the form field label to the left of the form control via the prop `labelPlacement`: -- Place your label to the left of the control if your application is limited in vertical real estate or if you have a very data heavy, dense form where it’s preferable to have as many fields visible as possible without scrolling. +- Place your label to the left of the control if your application has limitations in vertical real estate or you have a very data-heavy, dense form that should show as many fields visible as possible without scrolling. -### Label as Question +### Label as question -Form Field labels can be styled with a different intent by setting the `intent` prop. Use “sentence” intent for sentences and questions. See more about [displaying labels](/salt/patterns/forms#label-vs-question). +You can style form field labels with a different intent by setting the `intent` prop. Use “sentence” intent for sentences and questions. See more about [displaying labels](/salt/patterns/forms#label-vs-question). -### Multiple Children +### Multiple children -You can display multiple controls within a single Form Field. Wrap the controls in a Stack Layout for the correct styling. +You can display multiple controls within a single form field. Wrap the controls in `StackLayout` for the correct styling. -### Necessity Label +### Necessity label -If a field is required, it can be marked with a "Required”, “Optional”, or “\*” indicator using the `necessity` prop. +If a field is necessary, you can mark it with a "Required”, “Optional” or “\*” indicator using the `necessity` prop. -### Readonly +### Read-only -Form Field can be set as read-only via the prop `readOnly`. +You can set a form field as read-only via the prop `readOnly`: -- The prop should be applied to the field, not the control it contains, for expected results. +- You should apply the prop to the field, not the control it contains, for expected results. -- Set the field to read-only if you’re displaying values that are predefined and not editable, e.g., entry that’s populated and fixed by template selection. +- Set the field to read-only if you’re displaying predefined, noneditable values, e.g., entry populated and fixed by template selection. -- Adheres to WCAG AA text contrast for legibility; read-only field content is always relevant to the form, but cannot be changed. +- Test must adhere to WCAG AA text contrast for legibility; read-only field content is always relevant to the form, but users cannot change it. ### Validation -Form Fields can show validation states (warning, success, error) with the prop `validationStatus`. +Form fields can show validation states (warning, success, error) with the prop `validationStatus`: -- The prop should be applied to the field,not the control it contains, for expected results. +- You should apply the prop to the field, not the control it contains, for expected results. -- Use the error state to alert the user of a critical issue that’s related to the field entry. This issue, which may jeopardize completion of the task, usually requires action from the user to resolve the error. +- Use the error state to alert the user of a critical issue related to the field entry. This issue, which may jeopardize completion of the task, usually requires action from the user to resolve it. -- Display the warning state when you need to alert the user of a potential issue that won’t prevent the user from continuing with the task, but may cause errors if it’s not addressed. +- Display the warning state when you need to alert the user of a potential issue that won’t prevent them from continuing with the task, but may cause errors if they don't address it. -### With Checkbox and Radio Button +### With checkbox and radio button -Form Field can wrap any Salt UI control that is typically found in a form, such as [Input](../input), [Checkbox](../checkbox) and [Combo Box](../combo-box) components. This example shows Radio Button and Checkbox controls used within a Form Field. +Form fields can wrap any Salt UI control typically found in a form, such as [`Input`](../input), [`Checkbox`](../checkbox) and [`ComboBox`](../combo-box) components. This example shows radio buttons and checkbox controls used within a form field. -- Form Field doesn’t have primary and secondary variants. Any variants apply to the field controls contained within Form Field and can be displayed via the components `variant` prop if supported. +- Form fields don't have primary and secondary variants. Any variants apply to the field controls contained within the form field, and you can display them via the component's `variant` prop if supported. -### Grouped With Left Aligned Label Placement +### Grouped with left aligned label placement -Wrap multiple Form Fields in a [Stack Layout](../stack-layout) to form a group. +Wrap multiple form fields in [`StackLayout`](../stack-layout) to form a group: - Use the same label placement on each field. -- Spread grouped props on the Form Fields to reduce code repetition. -- Set `role="group"` or `as="fieldset"` on the layout component for accessibility. If using a fieldset, browser fieldset styling should be overridden. +- Spread grouped props on the form fields to reduce code repetition. +- Set `role="group"` or `as="fieldset"` on the layout component for accessibility. If using a fieldset, you should override browser fieldset styling. -This example shows a group with the fields `labelPlacement` props set to "left". +This example shows a group with the fields `labelPlacement` props set to "left": -### Grouped With Top Aligned Label Placement +### Grouped with top aligned label placement -Wrap multiple Form Fields in a [Stack Layout](../stack-layout) to form a group. +Wrap multiple form fields in [`StackLayout`](../stack-layout) to form a group. - Use the same label placement on each field. - Spread grouped props on the Form Fields to reduce code repetition. -- Set `role="group"` or `as="fieldset"` on the layout component for accessibility. If using a fieldset, browser fieldset styling should be overridden. +- Set `role="group"` or `as="fieldset"` on the layout component for accessibility. If using a fieldset, you should override browser fieldset styling. This example shows a group with the fields `labelPlacement` props set to "top". @@ -156,34 +156,34 @@ This example shows a group with the fields `labelPlacement` props set to "top". ### Grouped With Right Aligned Label Placement -Wrap multiple Form Fields in a [Stack Layout](../stack-layout) to form a group. +Wrap multiple form fields in [`StackLayout`](../stack-layout) to form a group. - Use the same label placement on each field. -- Spread grouped props on the Form Fields to reduce code repetition. -- Set `role="group"` or `as="fieldset"` on the layout component for accessibility. If using a fieldset, browser fieldset styling should be overridden. +- Spread grouped props on the form fields to reduce code repetition. +- Set `role="group"` or `as="fieldset"` on the layout component for accessibility. If using a fieldset, you should override browser fieldset styling. This example shows a group with the fields `labelPlacement` props set to "right". -### Grouped With Multiple Columns +### Grouped with multiple columns -Use multiple [Stack Layouts](../stack-layout) inside a group to create a multiple column layout. +Use multiple [stack layouts](../stack-layout) inside a group to create a multiple column layout. -### Grouped With Empty Slot +### Grouped with empty slot -Use [Grid Layout](../grid-layout) within a group to create multiple columns where empty slots may be present. +Use [`GridLayout`](../grid-layout) within a group to create multiple columns where empty slots may be present. ### Grouped With Variant -Grouped Form Fields should all have the same variant. Set the `variant` prop on each field to the same. To avoid code repetition, spread the props onto the fields. +Grouped form fields should all have the same variant. Set the same `variant` prop on each field. To avoid code repetition, spread the props onto the fields. diff --git a/site/docs/components/form-field/index.mdx b/site/docs/components/form-field/index.mdx index 979f7479a78..d3b57866ecc 100644 --- a/site/docs/components/form-field/index.mdx +++ b/site/docs/components/form-field/index.mdx @@ -1,12 +1,12 @@ --- -title: Form Field +title: Form field data: - description: Form Field is a wrapper for UI controls that are typically found in a form (for example, Input, Combobox or Radio Button). It is required to make these controls accessible by providing them with a visible label, validation control and states and descriptive text elements. + description: "`FormField` is a wrapper for user interface controls that are typically found in a form (for example, `Input`, `ComboBox` or `RadioButton`). You must make these controls accessible by providing them with a visible label, validation control, states and descriptive text elements." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/form-field/FormField.tsx" package: name: "@salt-ds/core" initialVersion: "1.8.0-rc.0" - alsoKnownAs: ["Form Input", "Input Control", "Form Element"] + alsoKnownAs: ["Form input", "Input control", "Form element"] stickerSheet: "" layout: DetailComponent --- diff --git a/site/docs/components/form-field/usage.mdx b/site/docs/components/form-field/usage.mdx index 3f389e55848..e0114309803 100644 --- a/site/docs/components/form-field/usage.mdx +++ b/site/docs/components/form-field/usage.mdx @@ -7,21 +7,21 @@ data: $ref: ./#/data --- -### Using the Form Field component +### Using the component -- We highly recommend using the `FormFieldLabel` and `FormFieldHelperText` components within Form Field to provide your form elements with the descriptive label and validation feedback required to ensure ADA compliance. +- We highly recommend using the `FormFieldLabel` and `FormFieldHelperText` components within the form field to provide your form elements with the descriptive label and validation feedback required to ensure ADA compliance. -- Align the Form Field to the correct Salt layout grid for your density and viewport size. Set the width of the form control to the number of columns that best reflects the length of the control’s expected value. The form control width can be set independently of the Form Field Label and Form Field Helper Text if required. +- Align the form field to the correct Salt layout grid for your density and viewport size. Set the width of the form control to the number of columns that best reflects the length of the control’s expected value. You can set the form control width independently of the form field label and form field helper text if required. -- Use Form Field as a wrapper for editable components in a form layout—such as a simple form, filter panel or cash ticket. +- Use a form field as a wrapper for editable components in a form layout—such as a simple form, filter panel or cash ticket. -#### Form Pattern +#### Form pattern -Follow the Salt [Forms pattern](/salt/patterns/forms), for guidance using Form Fields in forms. +Follow the Salt [forms pattern](/salt/patterns/forms) for guidance using form fields in forms. ### Import -To import Form Field from the core Salt package, use: +To import `FormField` and related components from the core Salt package, use: ```js import { FormField, FormFieldHelperText, FormFieldLabel } from "@salt-ds/core"; @@ -29,14 +29,14 @@ import { FormField, FormFieldHelperText, FormFieldLabel } from "@salt-ds/core"; ### Props -#### Form Field +#### `FormField` -#### Form Field Label +#### `FormFieldLabel` -#### Form Field Helper Text +#### `FormFieldHelperText` diff --git a/site/docs/components/grid-layout/accessibility.mdx b/site/docs/components/grid-layout/accessibility.mdx index be4b42a20d0..9ec34fe1f02 100644 --- a/site/docs/components/grid-layout/accessibility.mdx +++ b/site/docs/components/grid-layout/accessibility.mdx @@ -11,9 +11,9 @@ data: ### Best practices -When building a page layout, it is important to make sure you use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. +When building a page layout, it's important to make sure you apply semantic HTML by using the correct HTML elements for their intended purpose as much as possible. -The Grid Layout and Grid Item components support this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. +The `GridLayout` and `GridItem` components support this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. ```tsx diff --git a/site/docs/components/grid-layout/examples.mdx b/site/docs/components/grid-layout/examples.mdx index ba904f0451a..e5ef0911226 100644 --- a/site/docs/components/grid-layout/examples.mdx +++ b/site/docs/components/grid-layout/examples.mdx @@ -15,13 +15,13 @@ data: ### Default -Grid Layout defaults to a 12 column grid with one row. The spacing between rows and columns is driven by the prop `gap` and is set to 3. +`GridLayout` defaults to a 12-column grid with one row. The spacing between rows and columns depends on the prop `gap`, which is 3 by default. -Content in the Grid Layout is displayed inside Grid Item components. This helps control the size and position of content. +Content in `GridLayout` is inside `GridItem` components. This helps control the size and position of content. -#### Guidance +#### Best practices -- Grid Item components are recommended for displaying content in the layout. If the layout is very simple (i.e., does not span multiple columns or rows) content (e.g., components, text, divs, etc) can be placed directly into the Grid Layout component. +- We recommend `GridItem` components for displaying content in the layout. If the layout is very simple (i.e., doesn't span multiple columns or rows), you can place content (e.g., components, text, divs, etc) directly into the `GridLayout` component. - Any items displayed beyond 12 columns (or the number of defined columns) will wrap to a subsequent row. - Use `columnGap` and `rowGap` properties to set a specific gap in a particular dimension or `gap` to update both values simultaneously. @@ -31,7 +31,7 @@ Content in the Grid Layout is displayed inside Grid Item components. This helps ### Columns and rows -Use Grid Layout `column` and `row` properties to control the number of columns and rows in the layout. +Use grid layout `column` and `row` properties to control the number of columns and rows in the layout. @@ -39,23 +39,21 @@ Use Grid Layout `column` and `row` properties to control the number of columns a ### Responsive layout -The Grid Layout’s responsive properties allow you to customize specific properties of the grid (such as the number of columns and rows) per breakpoint. +The grid layout’s responsive properties allow you to customize specific properties of the grid (such as the number of columns and rows) per breakpoint. -You can use the default [Salt breakpoints](/salt/foundations/responsiveness#breakpoints) or pass in your own using [SaltProvider](/salt/components/salt-provider). +You can use the default [Salt breakpoints](/salt/foundations/responsiveness#breakpoints) or pass in your own using [`SaltProvider`](/salt/components/salt-provider). -#### What are responsive properties? - -A responsive property is a property that takes either multiple values (one value per breakpoint), or a single value that would take effect across all different screen sizes. For example, a layout that will responsively change from 12 columns to two and then to one as the space decreases: +A responsive property is a property that takes either multiple values (one value per breakpoint) or a single value that would take effect across all different screen sizes. An example is a layout that will responsively change from 12 columns to two and then to one as the space decreases: ```js columns={{ xs: 1, sm: 2, lg: 12, md: 12, xl: 12 }} ``` -#### Guidance +#### Best practices -- Use Grid Layout’s responsive properties when the flow of the grid is dependent on the viewport size, such as when a user typically resizes their application or webpage and content needs to remain visible. +- Use the grid layout’s responsive properties when the flow of the grid is dependent on the viewport size, such as when a user typically resizes their application or webpage and content needs to remain visible. -- Define specific layout behaviours per breakpoint to optimize the content display across different device sizes. +- Define specific layout behaviors per breakpoint to optimize the content display across different device sizes. @@ -63,11 +61,11 @@ columns={{ xs: 1, sm: 2, lg: 12, md: 12, xl: 12 }} ### Spanning columns and rows -We strongly recommend that you display content in Grid Layout inside Grid Items. Using a Grid Item you can control the size and position of content in the grid. By default, a Grid Item will span one column and one row. Use the `colSpan` and `rowSpan` props to increase the size of individual items to span multiple rows and columns. +Although it is possible to use `GridLayout` without using `GridItem`, we strongly recommend that you wrap items with the `GridItem` component. Using a grid item, you can control the size and position of content in the grid. By default, a grid item will span one column and one row. Use the `colSpan` and `rowSpan` props to increase the size of individual items to span multiple rows and columns. -#### Guidance +#### Best practices -- Spanning multiple columns and rows is an effective way to drive visual hierarchy in the layout. For example, Grid Items at the top of an analytical dashboard are typically larger in size to emphasize data visualisations, such as charts or metrics. +Spanning multiple columns and rows is an effective way to drive visual hierarchy in the layout. For example, grid items at the top of an analytical dashboard are typically larger in size to emphasize data visualizations, such as charts or metrics. @@ -75,7 +73,7 @@ We strongly recommend that you display content in Grid Layout inside Grid Items. ### Expanding and collapsing items -Use the `colSpan` and `rowSpan` props to dynamically control the size of an item in the grid to show more or less content to the user. This example shows how to expand a Grid Item in the layout and reposition surrounding Grid Items at the same time. +Use the `colSpan` and `rowSpan` props to dynamically control the size of an item in the grid to show more or less content to the user. This example shows how to expand a grid item in the layout and reposition surrounding grid items at the same time. @@ -83,7 +81,7 @@ Use the `colSpan` and `rowSpan` props to dynamically control the size of an item ### Positioning items -Use the `verticalAlignment` and `horizontalAlignment` props to control the position of content in the Grid Layout. +Use the `verticalAlignment` and `horizontalAlignment` props to control the position of content in the grid layout. diff --git a/site/docs/components/grid-layout/index.mdx b/site/docs/components/grid-layout/index.mdx index 8d7e600a44b..86d2eca1847 100644 --- a/site/docs/components/grid-layout/index.mdx +++ b/site/docs/components/grid-layout/index.mdx @@ -1,14 +1,14 @@ --- -title: Grid Layout +title: Grid layout data: - description: "Grid Layout manages the layout of the main content area in your application screen or webpage. It aligns content to a system of equally distributed columns and rows to create a cohesive and organized UI. When used with responsive breakpoints, Grid Layout can be used to determine how the same content is displayed across different viewport sizes or device screen sizes." + description: "`GridLayout` and `GridItem` manage the layout of the main content area in your application screen or webpage. It aligns content to a system of equally distributed columns and rows to create a cohesive and organized user interface. When combined with responsive breakpoints, You can configure `GridLayout` to determine the display of specific content across different viewport sizes or device screen sizes." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/grid-layout/GridLayout.tsx" package: name: "@salt-ds/core" alsoKnownAs: ["Column layout", "Responsive grid"] relatedComponents: [ - { name: "Border Layout", relationship: "similarTo" }, + { name: "Border layout", relationship: "similarTo" }, ] diff --git a/site/docs/components/grid-layout/usage.mdx b/site/docs/components/grid-layout/usage.mdx index 30a33810917..db5936a8a4b 100644 --- a/site/docs/components/grid-layout/usage.mdx +++ b/site/docs/components/grid-layout/usage.mdx @@ -8,23 +8,25 @@ data: $ref: ./#/data --- -### When to use Grid Layout +### Using the components -- Your content is best displayed using a configurable number of columns and rows, such as a [Form](/salt/patterns/forms) or a Dashboard. +### When to use -- For content regions where blocks, or groups, of content are displayed alongside each other, such as the main content area of the application, a [Dialog](/salt/components/dialog), or a [Drawer](/salt/components/drawer). +- When it's best to display your content using a configurable number of columns and rows, such as a [form](/salt/patterns/forms) or a dashboard. -- The application or webpage will be displayed across different viewport, screen, or device sizes. Grid Layout provides control over how the content is displayed and responsively organized across the different spaces, and ensures a reliable, usable experience. +- For content regions where you display blocks or groups of content alongside each other, such as the main content area of the application, [`Dialog`](/salt/components/dialog), or [`Drawer`](/salt/components/drawer). -### When not to use Grid Layout +- When users will access the application or webpage across different viewport, screen or device sizes. `GridLayout` controls how to display the content and responsively organize across the different spaces, ensuring a reliable, usable experience. -- To define the high-level layout of your application surrounding the content area (i.e., header, footer, navigation areas. Instead, use the [Border Layout](/salt/components/border-layout) component. +### When not to use -- To lay out your content in a single dimension only, for example a horizontal summary bar containing a row of metric components, or a vertical stack of Accordion components. Instead, use [Stack Layout](/salt/components/stack-layout), [Flow Layout](/salt/components/flow-layout) or [Flex Layout](/salt/components/flex-layout). +- To define the high-level layout of your application surrounding the content area (i.e., header, footer, navigation areas. Instead, use [`BorderLayout`](/salt/components/border-layout). + +- To lay out your content in a single dimension only, for example a horizontal summary bar containing a row of metric components, or a vertical stack of `Accordion` components. Instead, use [`StackLayout`](/salt/components/stack-layout), [`FlowLayout`](/salt/components/flow-layout) or [`FlexLayout`](/salt/components/flex-layout). ### Import -To import Grid Layout from the core Salt package, use: +To import `GridLayout` and `GridItem` from the core Salt package, use: ```js import { GridLayout, GridItem } from "@salt-ds/core"; @@ -32,14 +34,14 @@ import { GridLayout, GridItem } from "@salt-ds/core"; ### Props -#### Grid Layout +#### `GridLayout` -#### Grid Item +#### `GridItem` ### References -Grid Layout has a complementary Layout grid style library for Figma. J.P. Morgan employees can enable the Salt Layout Grid library from the Assets panel. External designers can install the library from the [Salt community page](https://www.figma.com/community/file/1184561028332139679/Salt%3A-Layout-Grid). +`GridLayout` has a complementary layout grid style library for Figma. J.P. Morgan employees can enable the Salt Layout Grid library from the Assets panel. External designers can install the library from the [Salt community page](https://www.figma.com/community/file/1184561028332139679/Salt%3A-Layout-Grid). diff --git a/site/docs/components/icon/accessibility.mdx b/site/docs/components/icon/accessibility.mdx index ee96925b311..38ea6de2cdf 100644 --- a/site/docs/components/icon/accessibility.mdx +++ b/site/docs/components/icon/accessibility.mdx @@ -9,4 +9,4 @@ data: ### Best practices -Decorative icons (icons that repeat the information already expressed by the accompanied text) should be hidden from the screen reader to avoid repetition. If you are adding an icon for decorative purposes, pass `aria-hidden=”true”` to hide its label from the screen reader. +You should exclude decorative icons (icons that repeat the information already expressed by the accompanied text) from screen reader access to avoid repetition. If you're adding an icon for decorative purposes, pass `aria-hidden=”true”` to exclude its label from the screen reader. diff --git a/site/docs/components/icon/examples.mdx b/site/docs/components/icon/examples.mdx index a0878d0ed51..0b9ded07615 100644 --- a/site/docs/components/icon/examples.mdx +++ b/site/docs/components/icon/examples.mdx @@ -9,26 +9,26 @@ data: - ### Basic Icon + ### Basic icon - Icons should be individually imported and used from the `@salt-ds/icons` - package + You should individually import and use from the `@salt-ds/icons` + package. - ### Icon Size + ### Icon size - You can change the size of each icon using the `size` property which acts as a multiplier for the base icon’s size, as described in the [Scale Foundation](/salt/foundations/scale). The base size of Icon is based on the active density as described in the [Size Foundation](/salt/foundations/size). + You can change the size of each icon using the `size` property, which acts as a multiplier for the base icon’s size, as described in the [scale foundation](/salt/foundations/scale). The base size of the icon depends on the active density as described in the [size foundation](/salt/foundations/size). - ### Icon Types + ### Icon types - We provide two types of icons: default and solid. Most icons will have both versions, with some exceptions as described in the [Iconography Foundation](/salt/foundations/iconography). The outline style is the default icon type. Use the solid icon for additional emphasis or to represent a toggled 'on' state. + We provide two icon types: default and solid. Most icons will have both versions, with some exceptions as described in the [iconography foundation](/salt/foundations/iconography). The outline style is the default icon type. Use the solid icon for additional emphasis or to represent a toggled "on" state. - ### Icon Color + ### Icon color To override the default color of the icon, use the `color` prop. This allows you to set the color to `primary`, `secondary` or `inherit`. @@ -36,7 +36,7 @@ data: ### Custom Icons - If you need a custom SVG icon, use the Icon component. Icon has the same API as the native `` element. Whenever you add a custom icon, pass an `aria-label` to Icon. + If you need a custom SVG icon, use the `Icon` component. `Icon` has the same API as the native `` element. Whenever you add a custom icon, pass an `aria-label` to `Icon`. @@ -45,9 +45,9 @@ data: - ### All Icons + ### All icons - A searchable list of all the Icons included in the `@salt-ds/icons` package. + This is a searchable list of all the icons included in the `@salt-ds/icons` package. diff --git a/site/docs/components/icon/index.mdx b/site/docs/components/icon/index.mdx index ff7d0de9e56..3b8033023ec 100644 --- a/site/docs/components/icon/index.mdx +++ b/site/docs/components/icon/index.mdx @@ -1,7 +1,7 @@ --- title: Icon data: - description: Icon is a visual representation of an application, a capability, a concept or a specific entity with meaning on an interface (e.g. a floppy disk to represent a save action). Icons help users to recognize and understand a concept or an action regardless of linguistic or cultural boundaries. + description: "Icons are a visual representation of an application, a capability, a concept or a specific entity with meaning on an interface (e.g., a floppy disk to represent a save action). Icons help users to recognize and understand a concept or an action regardless of linguistic or cultural boundaries." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/icons/src/icon/Icon.tsx" package: name: "@salt-ds/icons" @@ -9,8 +9,8 @@ data: alsoKnownAs: ["Glyph", "Symbol"] relatedComponents: [ - { name: "StatusIndicator", relationship: "similarTo" }, - { name: "CountrySymbol", relationship: "similarTo" }, + { name: "Country symbol", relationship: "similarTo" }, + { name: "Status indicator", relationship: "similarTo" }, ] stickerSheet: "https://www.figma.com/file/9laF7Zn75aUMNsqSqRgAuX/Salt-Icons?type=design&node-id=2%3A2&mode=design&t=6K6VsqXrQdjSfZjk-1 " layout: DetailComponent diff --git a/site/docs/components/icon/usage.mdx b/site/docs/components/icon/usage.mdx index 200ef18fd64..cc3794acfa3 100644 --- a/site/docs/components/icon/usage.mdx +++ b/site/docs/components/icon/usage.mdx @@ -7,25 +7,25 @@ data: $ref: ./#/data --- -### Using the Icon components +### Using icons -#### When to use Icons +#### When to use icons -- Use an icon to aid recognition and to help users make choices by providing context (e.g. an office phone number vs mobile phone number in contact information). +- Use an icon to aid recognition and help users make choices by providing context (e.g., an office phone number vs cell phone number in contact information). -#### When not to use Icons +#### When not to use icons -- When you need an interactive icon. Instead, use [Button](/salt/components/Button) (CTA, Primary or Secondary variant). +- When you need an interactive icon. Instead, use [`Button`](/salt/components/Button) (call to action, primary or secondary variant). ### Import -To import an individual Icon from the icons package use: +To import an individual icon from the icons package, use: ```js import { AddDocumentIcon } from "@salt-ds/icons"; ``` -To import Icon from the icons package for creating custom SVG Icons use: +To import the `Icon` component from the icons package for creating custom SVG icons, use: ```js import { Icon } from "@salt-ds/icons"; @@ -37,4 +37,4 @@ import { Icon } from "@salt-ds/icons"; ### References -Icon has a complementary Icon style library for Figma including Icon design principles and creation guidelines. J.P. Morgan employees can enable the Salt Icons library from the Assets panel. External designers can install the library from the [Salt community page](https://www.figma.com/community/file/1184561977727107234/Salt%3A-Icons) +Icons have a complementary icon style library for Figma, including icon design principles and creation guidelines. J.P. Morgan employees can enable the Salt Icons library from the Assets panel. External designers can install the library from the [Salt community page](https://www.figma.com/community/file/1184561977727107234/Salt%3A-Icons). diff --git a/site/docs/components/index.mdx b/site/docs/components/index.mdx index 294728615d4..9cfb7a00a18 100644 --- a/site/docs/components/index.mdx +++ b/site/docs/components/index.mdx @@ -16,7 +16,7 @@ in Figma when logged in to the JPMC network. They include accessibility and design specifications for each component, with designs for light and dark modes in all four densities. -## Lab components ({meta.labsIcon}) +## Lab components Stable components do not feature an accompanying symbol in their navigation link titles. You can find them in the `@salt-ds/core` package. diff --git a/site/docs/components/input/accessibility.mdx b/site/docs/components/input/accessibility.mdx index ba4db6b50cd..cd2c9cfc381 100644 --- a/site/docs/components/input/accessibility.mdx +++ b/site/docs/components/input/accessibility.mdx @@ -7,16 +7,18 @@ data: $ref: ./#/data --- -- Wrap Input in a [Form Field](/salt/components/form-field) to make it accessible within a form. This will provide the field with a visible label, help text and a status message for validation feedback. More information can be found [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/). +### Best practices -- Text that extends beyond the visible area of Input is clipped. This behavior is common to all states, i.e., default, read-only and disabled—whether or not the input has focus. To view the text in its entirety, the user can traverse the characters using the cursor. +- Wrap `Input` in [`FormField`](/salt/components/form-field) to provide the field with a visible label, help text and a status message for validation feedback. This will ensure it complies with accessibility guidelines. You can find more information [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/). + +- The component clips text that extends beyond its visible area. All states have the same behavior—default, read-only and disabled—whether or not the input has focus. To view the text in its entirety, the user can traverse the characters using the cursor. -### Empty Read-only Marker +#### Empty read-only marker -For accessibility purposes, we recommend you use the `emptyReadOnlyMarker` prop to add a marker for empty read-only fields. This ensures it’s clear that for the current selection or configuration a value is not necessary. +For accessibility purposes, we recommend you use the `emptyReadOnlyMarker` prop to add a marker for empty read-only fields. This ensures it’s clear that a value is not necessary for the current selection or configuration. @@ -26,8 +28,8 @@ For accessibility purposes, we recommend you use the `emptyReadOnlyMarker` prop -- If focus is above the Input, Tab key press moves focus onto the input. The text will be highlighted. If the input area is empty, the text cursor is displayed. -- If the input is disabled, Tab key press will skip the input. +- If focus is above the input, Tab moves focus onto the input and highlights the text. If the input area is empty, Tab displays a text cursor in the input area. +- If the input is disabled, Tab skips the input. - If the input has focus, Tab moves focus out of the input, to next focusable component in the tab order. @@ -38,18 +40,18 @@ If focused, Shift + Tab moves focus out of the component to the previous compone -If an interactive adornment, e.g., a button, has focus, the element is activated. +If an interactive adornment, e.g., a button, has focus, Tab activates the element. -- When the Input area has focus, a space character is inserted at the point where the text cursor is positioned. -- If an interactive adornment, e.g., a button, has focus, the element is activated. +- When the input area has focus, Space inserts a character at the position of the text cursor. +- If an interactive adornment, e.g., a button, has focus, Space activates the element. -When the Input area has focus: +When the input area has focus: - If text is highlighted, the highlight is removed and the text cursor is positioned at the right edge of the highlight. - If the text cursor is displayed, it is positioned on the alternative side of the following character. If is there is no following character, there is no effect. @@ -57,32 +59,32 @@ When the Input area has focus: -When the Input area has focus: +When the input area has focus: -- If text is highlighted, the highlight is removed and the text cursor is positioned at the left edge of the highlight. -- If the text cursor is displayed, it is positioned on the alternative side of the following character. If is there is no preceding character, there is no effect. +- If text is in a highlighted state, Left Arrow removes the highlight and positions the text cursor at the left edge of the highlight. +- If the text cursor is visible, Left Arrow positions it on the alternative side of the following character. If there's no preceding character, there's no effect. - + Drags selection over text characters, one at a time. -When Input area has focus and: -- Text is highlighted, all highlighted characters are removed. -- The text cursor is positioned to the right of text, the preceding character is removed. +When the input area has focus and: +- Text is highlighted, this action removes all highlighted characters. +- The text cursor is positioned to the right of text, this action removes the preceding character. -When the Input area has focus, the relevant character is inserted at the point where the text cursor is positioned. +When the input area has focus, this action inserts the relevant character at the position of the text cursor. - + -Highlights all strings within the field. +This action highlights all strings within the field. diff --git a/site/docs/components/input/examples.mdx b/site/docs/components/input/examples.mdx index ada0f0c50a1..10debe938f4 100644 --- a/site/docs/components/input/examples.mdx +++ b/site/docs/components/input/examples.mdx @@ -12,54 +12,56 @@ data: ### Primary -Input comprises value text and a focus ring. The component is initially empty and then, once it has focus, it accepts text on a single line only. +`Input` comprises value text and a focus ring. The component is initially empty; once it has focus, it accepts text on a single line only. -The default variant for Input is "primary". +The default variant for Input is "primary." ### Secondary -Input has a "secondary" variant. +`Input` has a "secondary" variant. -For recommendations on variant choice, see the [Forms pattern](salt/patterns/forms). +For recommendations on variant choice, see the [forms pattern](salt/patterns/forms). ### Disabled -You can disable Input, with no resultant action when the user interacts with it. +You can disable the input, resulting in no action when the user interacts with it. ### Read-only -You can set Input to a read-only state. The value text can’t be edited in this state, but it can be highlighted and copied. +You can set `Input` to a read-only state. The user can't edit the value text in this state, but they can highlight and copy it. -By default, the marker is set to an em dash. If your application requires a different marker it can be set via the `emptyReadOnlyMarker` prop. +By default, the marker is an em dash. If your application requires a different marker, you can set it via the `emptyReadOnlyMarker` prop. -- Use the read-only state when the value is necessary for the users flow or current task but cannot be edited, for example, because of user permissions. +- Use the read-only state when the user needs the value for their flow or current task but cannot edit it, for example, because of user permissions. ### Placeholder -You can use a placeholder to prompt user input if no default value is provided. +You can use a placeholder to prompt user input if there's no default value. -- Placeholder text should never be used to provide the user with contextual help since it will be removed when the user starts typing and does not meet minimum contrast requirements. Doing so is a WCAG failure. Instead, use helper text beneath the field to provide instructions or directions which are necessary to complete the field, and reserve the placeholder text to support the help message, or provide an example of the suggested content. +#### Best practices -More information can be found [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/). +You should never use placeholder text to provide the user with contextual help since it will disappear when the user starts typing and doesn't meet minimum contrast requirements. Doing so is a WCAG failure. Instead, use helper text beneath the field to provide instructions or directions necessary to complete the field, and reserve the placeholder text to support the help message, or provide an example of the suggested content. + +You can find more information [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/). ### Spellcheck -Turn automatic spellchecking on using `inputProps`. +Turn on automatic spellchecking using `inputProps`. @@ -68,40 +70,42 @@ Turn automatic spellchecking on using `inputProps`. You can add custom adornments at the beginning or end of the Input field using the `startAdornment` and `endAdornment` props. -Start adornments are typically used to describe the purpose of the field (e.g., a phone number input, or a currency), whereas end adornments are typically used to indicate a reveal of more information (e.g., using an arrow icon) or to trigger a new UI (such as a date picker). +Start adornments typically describe the purpose of the field (e.g., a phone number input, or a currency), while end adornments typically indicate a reveal of more information (e.g., using an arrow icon) or to trigger a new user interface (such as a date picker). -Salt [Text](/salt/components/text) and [Icons](/salt/foundations/iconography) can be used to add Salt styled alphanumeric text or symbols as adornments. Multiple start or end adornments should be wrapped in a parent container and passed to the respective prop as a single fragment. Adornments can be dynamic, with their value depending on the current state. +You can use [text](/salt/components/text) and [icons](/salt/foundations/iconography) to add Salt styled alphanumeric text or symbols as adornments. You should wrap multiple start or end adornments in a parent container and pass them to the respective prop as a single fragment. Adornments can be dynamic, with their value depending on the current state. ### Button adornments -You can use [Button](/salt/components/button) at the beginning or end of the Input field with the `startAdornment` and `endAdornment` props. Buttons can allow for custom interactivity within the Input field itself, or elsewhere in the app via the Input field. +You can use [`Button`](/salt/components/button) at the beginning or end of the input field with the `startAdornment` and `endAdornment` props. Buttons can allow for custom interactivity within the input field itself or elsewhere in the app via the input field. -Ensure to make your interactive Buttons disabled or read-only should it match the state of the containing Input field. +Disable your interactive buttons or make them read-only should they match the state of the containing input field. ### Validation -Input can show validation states (warning, success, error) with the prop `validationStatus`. +Input can show validation states (warning, success and error) with the prop `validationStatus`. + +#### Best practices -- Use the error state to alert the user of a critical issue that’s related to the input. This issue, which may jeopardize completion of the task, usually requires action from the user to resolve the error. +- Use the error state to alert the user of a critical issue related to the input. This issue, which may jeopardize completion of the task, usually requires action from the user to resolve the error. -- Display the warning state when you need to alert the user of a potential issue—that won’t prevent the user from continuing with the task, but may cause errors if it’s not addressed. +- Display the warning state when you need to alert the user of a potential issue that won’t prevent them from continuing with a task but may cause errors if they don't address it. -### Text Alignment +### Text alignment -Text is left-aligned by default. Use the `textAlign` prop to change the alignment to “center” or “right”. +Text has left alignment by default. Use the `textAlign` prop to change the alignment to “center” or “right.” -- Numeric values are often displayed right aligned to make them easier to compare. However, sometimes number fields are unrelated or are mixed with text fields in a form, so left-alignment may promote better visual flow. Consider your use case when deciding on Input field alignment. +Numeric values often have right alignment to make comparing them easier. However, sometimes number fields don't relate to each other or mix with text fields in a form, so left alignment may promote better visual flow. Consider your use case when deciding on input field alignment. -You may choose to center-align an input field to bring emphasis to a value. However, this should be the exception and used sparingly. +You may choose to center-align an input field to bring emphasis to a value. However, this should be the exception, and you should use it sparingly. diff --git a/site/docs/components/input/index.mdx b/site/docs/components/input/index.mdx index 5f10d0f16c0..5bd54b864b7 100644 --- a/site/docs/components/input/index.mdx +++ b/site/docs/components/input/index.mdx @@ -1,7 +1,7 @@ --- title: Input data: - description: Input provides an editable field in which users can enter text and numeric values. It is best used for short freeform content and data entry. + description: "`Input` provides an editable field where users can enter text and numeric values. It works best for short, freeform content and data entry." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/input/Input.tsx" package: name: "@salt-ds/core" diff --git a/site/docs/components/input/usage.mdx b/site/docs/components/input/usage.mdx index 09e3fa63db6..47e10e45455 100644 --- a/site/docs/components/input/usage.mdx +++ b/site/docs/components/input/usage.mdx @@ -7,18 +7,21 @@ data: $ref: ./#/data --- -### When to use Input +### Using the component + +To avoid misleading users, set the width to correlate to the length of the answer you’re expecting. For example, an input for a three-digit value shouldn't be wide enough to accommodate a sentence worth of characters. See [forms pattern](/salt/patterns/forms) for more information on layout. + +### When to use - To ask a user a subjective question to which user responses will vary and the length of their answer is likely to be less than a single line. -- To avoid misleading users, set the width to correlates to the length of the answer you’re expecting. For example, an input for a three-digit value should not be wide enough to accommodate a sentence worth of characters. See [Forms pattern](/salt/patterns/forms) for more information on layout. -#### When not to use Input +#### When not to use -When the content is likely to exceed a single line. Instead, use a [Multiline Input](/salt/components/multiline-input). Input field width and height should always reflect the amount of content expected in the field. +- When the content is likely to exceed a single line. Instead, use [`MultilineInput`](/salt/components/multiline-input). Input field width and height should always reflect the amount of content expected in the field. ### Import -To import Input from the core Salt package, use: +To import `Input` from the core Salt package, use: ```js import { Input } from "@salt-ds/core"; diff --git a/site/docs/components/link/accessibility.mdx b/site/docs/components/link/accessibility.mdx index 4044d0fe754..cbd6b6230ce 100644 --- a/site/docs/components/link/accessibility.mdx +++ b/site/docs/components/link/accessibility.mdx @@ -8,14 +8,18 @@ data: $ref: ./#/data --- +### Best practices + - Screen reader users will use the Tab key to jump from link to link or pull up a list of links on a page. Avoid using the same link text to link to different content and ensure that links make sense out of context. -- When a link contains an icon and text, pass `aria-hidden=”true"` to the icon so that its label is not announced by screen readers -- When a link has an icon and no text, pass an `aria-label` to Link to describe the content the link leads to. +- When a link contains an icon and text, pass `aria-hidden=”true"` to the icon so that its label is not announced by screen readers. +- When a link has an icon and no text, pass an `aria-label` to the link to describe the content that the link leads to. + +### Keyboard interactions -If the link has an href, the Enter key press navigates the user. +If the link has an href, navigates the user. diff --git a/site/docs/components/link/index.mdx b/site/docs/components/link/index.mdx index df66a5ae357..acaa8069be7 100644 --- a/site/docs/components/link/index.mdx +++ b/site/docs/components/link/index.mdx @@ -1,7 +1,7 @@ --- title: Link data: - description: Link allows users to navigate to a different site or other pages within the current site. It can be inline within a sentence, or standalone on its own or after a sentence. + description: "`Link` allows users to navigate to a different site or other pages within the current site. You can use it inline in a sentence, standalone on its own, or after a sentence." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/core/src/link" package: name: "@salt-ds/core" diff --git a/site/docs/components/link/usage.mdx b/site/docs/components/link/usage.mdx index cf0b4b5796d..66523508f70 100644 --- a/site/docs/components/link/usage.mdx +++ b/site/docs/components/link/usage.mdx @@ -8,26 +8,26 @@ data: $ref: ./#/data --- -### Using the Link component +### Using the component A standalone link is typically displayed in a body text style in the primary variant. If you want to display the link with less prominence, such as when linking to secondary information, you can display it in the secondary variant. An inline link should always use the same text formatting as the text that it is displayed with. -#### When to use Link +#### When to use - To provide navigation to a page on the same or different site. - To link to documents, email addresses or phone numbers. - To send users to a specific section on the same page. - To provide users with more detailed information or assistance e.g., terms and conditions, help sections or contact information. -#### When not to use Link +#### When not to use -To trigger an action, such as submitting a form or opening a dialog. Instead, use [Button](../button). +- To trigger an action, such as submitting a form or opening a dialog. Instead, use [Button](../button). ### Import -To import Link from the core Salt package, use: +To import `Link` from the core Salt package, use: ```js import { Link } from "@salt-ds/core"; @@ -42,9 +42,9 @@ import { Link } from "@salt-ds/core"; - Link text should be concise, no longer than a single sentence. This helps to keep the user interface clean, minimize distractions and maintain a clear visual hierarchy. - Do not overload sentences or pages with links. - Consider writing standalone links as calls-to-action and begin with a verb e.g., “Visit the help page”. -- Inline links should be written as if they were part of the sentence. +- You should write inline links as if they were part of the sentence. - Do not include the word “link” in the link text. Most screen readers say “link” before each link. -- Link text should accurately describe the content the link leads to. When a link is not labelled correctly to reflect the destination or purpose, it can confuse or frustrate the user. +- Link text should accurately describe the linked content. Link text that does not correctly reflect the destination or purpose can confuse or frustrate the user. ### References diff --git a/site/docs/components/list/accessibility.mdx b/site/docs/components/list/accessibility.mdx index 46735afa53f..ee258a55e8f 100644 --- a/site/docs/components/list/accessibility.mdx +++ b/site/docs/components/list/accessibility.mdx @@ -10,12 +10,12 @@ data: $ref: ./#/data --- -The following keyboard interactions are provided: +### Keyboard interactions -If focus is above the List, Tab moves focus to one of the following items depending on previous user interaction: +If focus is above the list, Tab moves focus to one of the following items depending on previous user interaction: - The last selected item - The last item with focus @@ -24,32 +24,32 @@ If focus is above the List, Tab moves focus to one of the following items depend -If focus is below the List, Shift + Tab moves focus into the list item which last had focus or the first item in the List. +If focus is below the list, this action moves focus to the list item that last had focus or the first item in the list. -When focus is on a List item, Enter or Space selects the item and deselects the previously selected item, if any. +When focus is on a list item, this action selects the item and deselects the previously selected item, if any. - + -Moves focus to the previous item in the List. If focus is on the first item, the next Arrow-up key press retains focus on the first item, it does not wrap focus to the last item in the List. +Up arrow moves focus to the previous item in the list. If focus is on the first item, the next key press retains focus on the first item. It doesn't wrap focus to the last item in the list. - + -Moves focus to the next item in the List. If focus is on the last item, the next Arrow-down key press retains focus on the last item, it does not wrap focus back to the first item in the List. +Down arrow moves focus to the next item in the list. If focus is on the last item, the next key press retains focus on the last item. It does not wrap focus back to the first item in the list. -When focus is within the List, Home moves focus to the first List item. +When focus is within the list, Home moves focus to the first list item. -When focus is within the List, End moves focus to the last List item. +When focus is within the list, End moves focus to the last list item. diff --git a/site/docs/components/list/examples.mdx b/site/docs/components/list/examples.mdx index b2f3fbe4f53..3fa54799dc1 100644 --- a/site/docs/components/list/examples.mdx +++ b/site/docs/components/list/examples.mdx @@ -13,19 +13,19 @@ data: -### Single-select List +### Single-select list -The default List allows a user to make a single selection from the options available. +The default list allows a user to make a single selection from the options available. -### Disabled List +### Disabled list -If the options within the List are not applicable or relevant to the current user, the List can be presented as disabled. +If the options within the list aren't applicable or relevant to the current user, you can present the list as disabled. -The user retains the ability to scroll through the List items but can’t make a selection. If a List item has already been selected, for instance as a default selection, it will be displayed as such, the user can view it but can’t change the state. +The user retains the ability to scroll through the list items but can’t make a selection. If a list already has an item selected, for instance, as a default selection, it will display as such; the user can view it but can’t change the state. diff --git a/site/docs/components/list/index.mdx b/site/docs/components/list/index.mdx index 61e3df757f6..0adf07887be 100644 --- a/site/docs/components/list/index.mdx +++ b/site/docs/components/list/index.mdx @@ -1,7 +1,7 @@ --- title: List data: - description: List allows the user to select an item from an array of options. Selected items are visually distinct from non-selected items. To ensure space is used efficiently, long lists of items are displayed within a scrolling pane that can provide access to options that are not immediately visible to the user. + description: "`ListNext` and `ListItemNext` allow the user to select an item from an array of options. Selected items are visually distinct from nonselected items. To ensure efficient space usage, long lists of items are in a scrolling pane that can provide access to options not immediately visible to the user." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # diff --git a/site/docs/components/list/usage.mdx b/site/docs/components/list/usage.mdx index ff98f780902..71dad18fa48 100644 --- a/site/docs/components/list/usage.mdx +++ b/site/docs/components/list/usage.mdx @@ -10,24 +10,24 @@ data: $ref: ./#/data --- -### Using the List component +### Using the components -#### When to use List +#### When to use -- To present a set of selectable options that allow users to make a choice for an onward action, such as filtering a data grid, selecting a country, or assigning a task. +- To present a set of selectable options that allow users to make a choice for an onward action, such as filtering a data grid, selecting a country or assigning a task. -#### When not to use List +#### When not to use -- If the List items are intended to provide navigation, consider using stacked [Navigation Items](../navigation-item) to form a vertical navigation pattern. -- If the List is likely to contain five items or fewer, consider using a [Radio Button Group](../radio-button). -- If the List is likely to contain between five and 10 items and does not need to be visible at all times, consider placing the list of items within a [Dropdown](../dropdown). -- If the List contains more than 10 items and screen space is limited, consider using a [Combo Box](../combo-box). +- If the list items provide navigation, consider using stacked [`NavigationItem`s](../navigation-item) to form a vertical navigation pattern. +- If the list is likely to contain five items or fewer, consider using [`RadioButtonGroup`](../radio-button). +- If the list is likely to contain between five and 10 items and doesn't need to be visible at all times, consider placing the list of items within [`Dropdown`](../dropdown). +- If the List contains more than 10 items and you have limited screen space, consider using a [`ComboBox`](../combo-box). ### Import {/* Update the text and code snippet below as needed: */} -To import List from the lab Salt package, use: +To import `ListNext` and `ListItemNext` from the lab Salt package, use: ```js import { ListNext, ListItemNext } from “@salt-ds/lab”; @@ -38,11 +38,11 @@ import { ListNext, ListItemNext } from “@salt-ds/lab”; {/* Update packageName and componentName below as needed */} {/* packageName is optional and defaults to "core" if omitted */} -#### List Next +#### `ListNext` -#### List Item Next +#### `ListItemNext` diff --git a/site/docs/components/multiline-input/accessibility.mdx b/site/docs/components/multiline-input/accessibility.mdx index 12c3262dcea..5927e185d1f 100644 --- a/site/docs/components/multiline-input/accessibility.mdx +++ b/site/docs/components/multiline-input/accessibility.mdx @@ -8,73 +8,75 @@ data: $ref: ./#/data --- -- Wrap Multiline Input in a [Form Field](/salt/components/form-field) to make it accessible within a form. This will provide the field with a visible label, help text and a status message for validation feedback. More information can be found [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/). +### Best practices -- Text that extends beyond the visible area of Multiline Input is clipped. This behavior is common to all states, i.e., default, read-only and disabled—whether or not the input has focus. To view the text in its entirety, the user can traverse the characters using the cursor. +- Wrap `MultilineInput` in [`FormField`](/salt/components/form-field) to provide the field with a visible label, help text and a status message for validation feedback. This will ensure it complies with accessibility guidelines. You can find more information [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/). + +- A multiline input will clip text that extends beyond its visible area. This behavior is common to all states, i.e., default, read-only and disabled—whether or not the input has focus. To view the text in its entirety, the user can traverse the characters using the cursor. ### Keyboard interactions -- If focus is above the Multiline Input, Tab key press moves focus onto the Multiline Input. The text will be highlighted. If the Multiline Input area is empty, the text cursor is displayed. -- If the Multiline Input is disabled, tabbing will skip the Multiline Input. -- If the Multiline Input has focus, Tab moves focus out of the Multiline Input, to next focusable component in the tab order. +- If focus is above the multiline input, Tab moves focus onto the multiline input and highlights the text. If the multiline input area is empty, it will display the text cursor. +- If the multiline input is disabled, Tab skips the multiline input. +- If the multiline input has focus, Tab moves focus out of the multiline input to next focusable component in the tab order. -- If focused, Shift + Tab combo moves focus out of the component to the previous component in the tab order. +- If focused, this action moves focus out of the component to the previous component in the tab order. -- If an interactive adornment, e.g., a button, has focus, the element is actioned. +- If an interactive adornment, e.g., a button, has focus, Enter actions the element. -- When the Multiline Input area has focus, a space character is inserted at the point where the text cursor is positioned. -- If an interactive adornment, e.g., a button, has focus, the element is actioned. +- When the multiline input area has focus, Space inserts a space character at the positon of the text cursor. +- If an interactive adornment, e.g., a button, has focus, actions the element. - + -When the Multiline Input area has focus: +When the multiline input area has focus: -- If text is highlighted, the highlight is removed and the text cursor is positioned at the right edge of the highlight. -- If the text cursor is displayed, it is positioned on the alternative side of the following character. If there is no following character, there is no effect. +- If text is in a highlighted state, Right arrow removes the highlight and positions the text cursor at the right edge of the highlight. +- If the text cursor is visible, Right arrow positions it on the alternative side of the following character. If there's no following character, there's no effect. - + -When the Multiline Input area has focus: +When the multiline input area has focus: -- If text is highlighted, the highlight is removed and the text cursor is positioned at the left edge of the highlight. -- If the text cursor is displayed, it is positioned on the alternative side of the following character. If there is no preceding character, there is no effect. +- If text is in a highlighted state, Left arrow removes the highlight and positions the text cursor at the left edge of the highlight. +- If the text cursor is visible, Left arrow positions it on the alternative side of the following character. If there's no preceding character, there's no effect. - + -Drags selection over text characters, one at a time. +This action drags selection over text characters, one at a time. -When Multiline Input area has focus and: +When the multiline input area has focus and: -- Text is highlighted, all highlighted characters are removed. -- The text cursor is positioned to the right of text, the preceding character is removed. +- Text is highlighted, Backspace removes all highlighted characters. +- The text cursor is to the right of text, Backspace removes the preceding character. -When the Multiline Input area has focus, the relevant character is inserted at the point where the text cursor is positioned. +When the multiline input area has focus, this action inserts the relevant character at the point where the text cursor is positioned. - + -Highlights all strings within the field. +This action highlights all strings within the field. diff --git a/site/docs/components/multiline-input/examples.mdx b/site/docs/components/multiline-input/examples.mdx index 2d7f69e9fce..a4be18ebec8 100644 --- a/site/docs/components/multiline-input/examples.mdx +++ b/site/docs/components/multiline-input/examples.mdx @@ -13,11 +13,11 @@ data: ### Primary -Values entered into the Multiline Input are set to wrap based on the width of the component. Initially, the component is empty. Once it has focus it accepts text across multiple lines. By default, the component presents three rows of text at a time. +Values entered into the multiline input wrap based on the width of the component. Initially, the component is empty. Once it has focus, it accepts text across multiple lines. By default, the component presents three rows of text at a time. If entering more than three rows of text, the user can review the entered value using keyboard controls. -- Multiline Input has two variants: "primary" and "secondary". The primary variant is default. The choice between primary and secondary variants should be considered alongside the background color it sits upon. For recommendations on variant choice, see the [Forms pattern](/salt/patterns/forms). +`MultilineInput` has two variants: primary and secondary. The primary variant is the default. You should consider the choice between primary and secondary variants alongside the background color it sits upon. For recommendations on variant choice, see the [forms pattern](/salt/patterns/forms). @@ -25,98 +25,98 @@ If entering more than three rows of text, the user can review the entered value ### Secondary -Secondary variant is an effective option if included as part of a data-dense or compact interface, or within a form with multiple columns or sections. +Secondary variant is an effective option if included as part of a data-dense or compact interface or within a form with multiple columns or sections. -The choice between primary and secondary variants should be considered in the context of the background color it sits upon. +You should consider the choice between primary and secondary variants in the context of the background color it sits upon. -- For recommendations on variant choice, see the [Forms pattern](/salt/patterns/forms). +For recommendations on variant choice, see the [forms pattern](/salt/patterns/forms). ### Disabled -Multiline Input can be set to a disabled state, with no resultant action when the user interacts with it. Showing it in a disabled state means the user is aware of its presence or an entered value but is not able to edit it. +You can set `MultilineInput` to a disabled state, with no resultant action when the user interacts with it. Showing it in a disabled state means the user is aware of its presence or an entered value but is unable to edit it. ### Read-only -Multiline Input can be set to a read-only state. The entered text cannot be edited in this state, but it can be highlighted and copied. +You can set `MultilineInput` to a read-only state. The user cannot edit entered text in this state, but they can highlight and copy it. -Use the read-only state when the value is necessary for the user’s flow or current task but cannot be edited, for instance when a user's permissions are restricted. +Use the read-only state when the value is necessary for the user’s flow or current task, but you want to restrict editing, for instance, when a user has restricted permissions. -When setting Multiline Input to a read-only state, ensure to also disable any nested interactive adornments, such as buttons. +When setting `MultilineInput` to a read-only state, ensure to also disable any nested interactive adornments, such as buttons. ### Bordered -To style Multiline Input with a full border set `bordered={true}`. +To style `MultilineInput` with a full border, set `bordered={true}`. -- We recommend this styling when the field uses the same fill color as the background (i.e., a primary fill color on a primary background). +We recommend this styling when the field uses the same fill color as the background (i.e., a primary fill color on a primary background). -### Number Of Rows +### Number of rows -The Multiline Input shows three rows of text by default. This can be adjusted, using the `rows` prop, to provide a larger input allowing the user to review more of the entered text without the need for further interactions. This example demonstrates a Multiline Input customized to show four rows. +The multiline input shows three rows of text by default. You can adjust this using the `rows` prop to provide a larger input, allowing the user to review more of the entered text without the need for further interactions. This example demonstrates a multiline input customized to show four rows. -Set the number of rows to best reflect the context that your Multiline Input is being displayed, and how much user input would be expected in that context. +Set the number of rows to best reflect the context of your multiline input and how much user input you expect in that context. -### Character Count +### Character count -You can add a character count as a label using `endAdornment` props. The example demonstrates the expected behaviour when the count is exceeded, with the field dynamically displaying an error state and the count continuing to display the number of characters over the limit. +You can add a character count as a label using `endAdornment` props. The example demonstrates the expected behavior when the user exceeds the character count, with the field dynamically displaying an error state, and the count continuing to display the number of characters over the limit. -If the user goes over the character count limit, display an error state and change the Label to `primary` variant with a weight of ‘strong’. +If the user goes over the character count limit, display an error state and change the Label to `primary` variant with a weight of `"strong"`. ### Validation Status -Indicate validation state by setting the `validationStatus` prop. +Indicate a validation state by setting the `validationStatus` prop. -- Use the “error” state when you want to alert the user to a critical issue related to the input. This issue, which will jeopardize completion of the task, usually requires action from the user to resolve the error. +- Use the error state when you want to alert the user to a critical issue related to the input. This issue, which will jeopardize completion of the task, usually requires action from the user to resolve the error. -- Display the “warning” state when you need to alert the user of a non-critical issue—that won’t prevent the user from continuing with the task, but may cause errors if it’s not addressed. +- Use the warning state when you need to alert the user of a noncritical issue that won’t prevent them from continuing with the task but may cause errors if they don't address it. ### Placeholder -A placeholder can be used to prompt user input if no default value is provided. +You can use a placeholder to prompt user input if there's no default value. -Placeholder text should never be used to provide the user with contextual help since it will be removed when the user starts typing and does not meet minimum contrast requirements. Doing so is a WCAG failure. Instead, use helper text beneath the input to provide instructions, and reserve the placeholder text to support the help message, or provide an example of the input. +You should never use placeholder text to provide the user with contextual help since it will disappear when the user starts typing and doesn't meet minimum contrast requirements. Doing so is a WCAG failure. Instead, use helper text beneath the input to provide instructions and reserve the placeholder text to support the help message or provide an example of the input. -More information can be found [here](https://www.w3.org/WAI/tutorials/forms/instructions/) +You can find more information [in this W3 tutorial](https://www.w3.org/WAI/tutorials/forms/instructions/). -### Static Adornments +### Static adornments -You can add custom adornments at the beginning or end of the Multiline Input area using the `startAdornment` and `endAdornment` props. +You can add custom adornments at the beginning or end of the multiline input area using the `startAdornment` and `endAdornment` props. -Start adornments are typically used to describe the purpose of the field (eg., a phone number input, or a currency), whereas end adornments are typically used to indicate a reveal of more information (eg., using an arrow icon) or to trigger a new UI (such as a date picker). +Start adornments typically describe the purpose of the field (e.g., a phone number input, or a currency), whereas end adornments typically indicate a reveal of more information (e.g., using an arrow icon) or trigger a new user interface, such as a date picker. -Salt [Text](../text) and [Icons](/salt/foundations/iconography) can be used to add Salt styled alphanumeric text or symbols as adornments. Multiple start or end adornments should be wrapped in a parent container and passed to the respective prop as a single fragment. Adornments can be dynamic, with their value depending on the current state. +You can use Salt [text](../text) and [icons](/salt/foundations/iconography) to add Salt styled alphanumeric text or symbols as adornments. You sould wrap multiple start or end adornments in a parent container and pass them to the respective prop as a single fragment. Adornments can be dynamic, with their value depending on the current state. -### Button Adornments +### Button adornments -You can use a [Button](../button) at the beginning or end of the Multiline Input using the `startAdornment` and `endAdornment` props. Buttons can allow for custom interactivity within the Multiline Input area itself, or elsewhere in the app via the Multiline Input. +You can use a [button](../button) at the beginning or end of the multiline input using the `startAdornment` and `endAdornment` props. Buttons can allow for custom interactivity within the multiline input area itself, or elsewhere in the app via the multiline input. -If the containing Multiline Input is disabled or read-only, ensure your interactive buttons match that state. +If you've disabled the containing multiline input or set it to a read-only state, ensure your interactive buttons match that state. diff --git a/site/docs/components/multiline-input/index.mdx b/site/docs/components/multiline-input/index.mdx index 1016bc54455..6c8d18c5f7d 100644 --- a/site/docs/components/multiline-input/index.mdx +++ b/site/docs/components/multiline-input/index.mdx @@ -1,7 +1,7 @@ --- -title: Multiline Input +title: Multiline input data: - description: Multiline Input provides an editable text area in which users can enter multiple lines of text and numeric values whilst retaining visibility of the text they have entered. + description: "`MultilineInput` provides an editable text area where users can enter multiple lines of text and numeric values while retaining the visibility of the text they've entered." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/multiline-input/MultilineInput.tsx" package: name: "@salt-ds/core" diff --git a/site/docs/components/multiline-input/usage.mdx b/site/docs/components/multiline-input/usage.mdx index e83f6da6db9..d3796cc9879 100644 --- a/site/docs/components/multiline-input/usage.mdx +++ b/site/docs/components/multiline-input/usage.mdx @@ -8,17 +8,19 @@ data: $ref: ./#/data --- -### When to use Multiline Input +### Using the component -A Multiline Input is recommended when a user is asked a subjective question and the length of their answer is unknown. The input can give them plenty of space to answer the question and review the answer. Set the height accordingly if you can take an educated guess at the possible length of their answer – see the Number of Rows example. +#### When to use -### When not to use Multiline Input +Use a multiline input when asking a user a subjective question and the length of their answer is unknown. The input can give them plenty of space to answer the question and review the answer. If you can take an educated guess at the possible length of their answer, set the height accordingly—see the "Number of rows" example. -Multiline Input field width and height should always reflect the amount of content expected in the field. If the content is unlikely to exceed a single line, always use an [Input component](../input), rather than a Multiline. +#### When not to use + +Multiline input field width and height should always reflect the amount of content expected in the field. If the content is unlikely to exceed a single line, always use [`Input`](../input). ### Import -To import Multiline Input from the core Salt package, use: +To import `MultilineInput` from the core Salt package, use: ```js import { MultilineInput } from "@salt-ds/core"; diff --git a/site/docs/components/navigation-item/accessibility.mdx b/site/docs/components/navigation-item/accessibility.mdx index 7632bf8309b..a9a4a94bdc8 100644 --- a/site/docs/components/navigation-item/accessibility.mdx +++ b/site/docs/components/navigation-item/accessibility.mdx @@ -10,56 +10,28 @@ data: ### Keyboard interactions -#### Horizontal Navigation - - - - - - Moves focus into the first Navigation Item in the group. Focus is set to the entire component. - - - When the Navigation Item has children, tab again, to move focus on to the arrow icon. - - - When Navigation Item has focus, moves focus out of Navigation Item to next component in tab order. - - - - - - When Navigation Item has focus, moves focus out of Navigation Item to previous component in tab order. - - - - - - Selects the focused Navigation Item. - - - Triggers Navigation Item to reveal expanded list or mega-menu. - - - Trigger a Nav item with children, or just ‘Enter’ to trigger a Navigation Item without children. - - -#### Vertical Navigation - - - Moves focus into the first Navigation Item in the vertical group. Focus is set to the entire component. + - Tab moves focus into the first navigation item in the vertical group. Sets focus to the entire component. - - If a Navigation Item is selected before the Navigation Item receives focus, focus is set on the selected item. + - If a navigation item is selected before the navigation item receives focus, Tab sets focus on the selected item. - - When the Navigation Item has children, tab again, to move focus on to the arrow icon. + - When the navigation item has children, second key press moves focus on to the arrow icon. - - When Navigation Item has focus, moves focus out of Navigation Item to next component in tab order. + - When the navigation item has focus, Tab moves focus out of the navigation item to the next component in tab order. - - If focus is below the Navigation Item, moves focus to the currently selected Navigation Item in the Navigation Item component. + - If focus is below the navigation item, this action moves focus to the currently selected navigation item in the navigation item component. - - If focus is on an item inside the Nav group, moves focus out of the navigation to the previous focusable element in the tab order. + - If focus is on an item inside the navigation group, this action moves focus out of the navigation to the previous focusable element in the tab order. - - Selects the focused Navigation Item. + - This action selects the focused navigation item. - - Triggers Navigation Item to reveal nested levels within the navigation. + - For vertical navigation, this action triggers the navigation item to reveal nested levels within the navigation. For horizontal navigation, this action triggers the navigation item to reveal expanded list or mega-menu. diff --git a/site/docs/components/navigation-item/examples.mdx b/site/docs/components/navigation-item/examples.mdx index f099617cdae..dd824ee1a47 100644 --- a/site/docs/components/navigation-item/examples.mdx +++ b/site/docs/components/navigation-item/examples.mdx @@ -14,58 +14,58 @@ data: ### Default (Horizontal) -By default the Navigation Item is oriented horizontally. +By default the navigation item is oriented horizontally. -#### Guidance +#### Best practices -A Navigation Item hugs its content by default, but is customisable so that its container can be adjusted to fit any preferred width. +A navigation item hugs its content by default, but you can customize it and adjust its container to fit any preferred width. ### Vertical -To change the orientation of the Navigation Item you can use the vertical orientation prop. +To change the orientation of the navigation item, you can use the vertical orientation prop. - ### With Icon + ### With icon -Use an icon to effectively signify the Navigation Item’s purpose, whether it’s related to a product’s identity, a specific tool, function, or a configuration setting. +Use an icon to effectively signify the navigation item’s purpose, whether it’s related to a product’s identity, a specific tool, function, or a configuration setting. -#### Guidance +#### Best practices -Ensure that icon descriptors are used consistently across all items within the same hierarchy level. This helps keep them equally weighted. +Ensure that you use icon descriptors consistently across all items within the same hierarchy level. This helps keep them equally weighted. - ### With Badge + ### With badge -You can add a [Badge](../badge) to a Navigation Item to serve as a visual cue. A badge can inform users of additional context, notifications, signpost new content or indicate a status. +You can add a [badge](../badge) to a navigation item to serve as a visual cue. A badge can inform users of additional context, notifications, signpost new content or indicate a status. -#### Guidance +#### Best practices -A badge should only be placed in a Navigation Item that does not include nested items, i.e., it will not have a chevron. +You should only place a badge in a navigation item that does not include nested items, i.e., it will not have a chevron. ### With nested items -You can use a Navigation Item as a parent which nests other Navigation Items inside it. Parent Navigation Items are displayed with a chevron on the right-hand side. To set a Navigation Item as a parent use the `Parent` prop. +You can use a navigation item as a parent which nests other navigation items inside it. Parent navigation items are displayed with a chevron on the right-hand side. To set a navigation item as a parent, use the `parent` prop. ### Horizontal group -Use horizontal Navigation Items within a horizontal group to establish a consistent and easily accessible pathway for users, while conserving valuable screen estate. Users will be able to easily scan and identify navigation options in a seamless user experience. +Use horizontal navigation items within a horizontal group to establish a consistent and easily accessible pathway for users, while conserving valuable screen estate. This will allow users to easily scan and identify navigation options in a seamless user experience. -#### Guidance +#### Best practices -Use a horizontal group of Navigation Items when you have fewer than eight items, otherwise consider a vertical group of items. +Use a horizontal group of navigation items when you have fewer than eight items, otherwise consider a vertical group of items. @@ -79,13 +79,13 @@ A vertical navigation group provides a simple, single-level list of links that u ### Vertical group nested -Use vertical navigation when handling a hierarchical structure of nested pages. This configuration allows users to reveal nested items when selecting a parent item, facilitating an intuitive exploration of the content hierarchy. +Use vertical navigation when handling a hierarchical structure of nested pages. This configuration allows users to reveal nested items when selecting a parent item, making it easy to explore the content hierarchy. When the user collapses a vertical nested group, and there is an active nested item within it, the parent item will obtain a blur-active state. The indicator will stay on the parent item in the blur-active state. This tells the user which item is currently selected. -#### Guidance +#### Best practices -If a Navigation Item has nested items within it, it will act as a trigger to show and hide the nested items. A parent item cannot act as a link and navigate to an overview page. If you require an overview page, use the first nested item to achieve this. +If a navigation item has nested items within it, it will act as a trigger to show and hide the nested items. A parent item cannot act as a link and navigate to an overview page. If you require an overview page, use the first nested item to achieve this. diff --git a/site/docs/components/navigation-item/index.mdx b/site/docs/components/navigation-item/index.mdx index 6ff7c5fd935..455433543f5 100644 --- a/site/docs/components/navigation-item/index.mdx +++ b/site/docs/components/navigation-item/index.mdx @@ -1,9 +1,9 @@ --- -title: Navigation Item +title: Navigation item sidebar: - label: Navigation Item 🚧 + label: Navigation item data: - description: Navigation Item allows users to navigate between distinct applications and website pages. + description: "`NavigationItem` allows users to navigate between distinct applications and website pages." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/lab/src/navigation-item/NavigationItem.tsx" package: name: "@salt-ds/lab" diff --git a/site/docs/components/navigation-item/usage.mdx b/site/docs/components/navigation-item/usage.mdx index b1b9045335f..19f478a6c3f 100644 --- a/site/docs/components/navigation-item/usage.mdx +++ b/site/docs/components/navigation-item/usage.mdx @@ -8,25 +8,25 @@ data: $ref: ./#/data --- -### How to use +### Using the component -#### When to use Navigation Item +#### When to use -- Use Navigation Item when you have multiple levels of navigation in your application or website. +- When you have multiple levels of navigation in your application or website. -- We suggest first considering a horizontal group of Navigation Items for distinct webpages or applications. If you have multiple (more than eight) services to navigate to at a platform level, or have navigation across distinct apps, consider using a vertical group instead. +- We suggest first considering a horizontal group of navigation items for distinct webpages or applications. If you have multiple (more than eight) services to navigate to at a platform level, or have navigation across distinct apps, consider using a vertical group instead. -- If you need your items to remain visible on scroll, we recommend displaying Navigation Items in a fixed App Header (or header area) +- If you need your items to remain visible on scroll, we recommend displaying navigation items in a fixed app header (or header area). -#### When not to use Navigation Item +#### When not to use -- When you need to show different views of content within the same page, consider using [Tabs](https://storybook.saltdesignsystem.com/?path=/docs/documentation-lab-tabs--docs) instead. +- When you need to show different views of content within the same page. Instead, use [`Tabs`](/salt/components/tabs/). -- When your content is very specific. In this case, a minimalistic or single-page design may be more appropriate than a complex navigation structure. Consider using the [Interactable Card](../card), or a [Link](../link) component within the body of the page. +- When your content is very specific. In this case, a minimalistic or single-page design may be more appropriate than a complex navigation structure. Instead, use [`InteractableCard`](../card), or [`Link`](../link) within the body of the page. ### Import -To import Navigation Item from the lab Salt package, use: +To import `NavigationItem` from the lab Salt package, use: ``` import { NavigationItem } from "@salt-ds/lab"; @@ -36,13 +36,13 @@ import { NavigationItem } from "@salt-ds/lab"; - To make the most of screen real estate, our recommendation is that all description text should be clear and concise. -- Always write descriptions in sentence case in a Navigation Item. +- Always write descriptions in sentence case in a navigation item. -- When using a Navigation Item component within a Navigation Item, we recommend using sentence case. +- When using a navigation item component within a navigation item, we recommend using sentence case. -- In a Horizontal Navigation Item, do not wrap descriptions, use truncation with Tooltip if necessary. +- In a horizontal navigation item, do not wrap descriptions, use truncation with `Tooltip` if necessary. -- In a Vertical Navigation Item, descriptions can wrap onto multiple lines if necessary, and is preferred over truncation. +- In a vertical navigation item, descriptions can wrap onto multiple lines if necessary, and is preferred over truncation. ### Props diff --git a/site/docs/components/panel/index.mdx b/site/docs/components/panel/index.mdx index c08ee5deb48..e3f13ae58f0 100644 --- a/site/docs/components/panel/index.mdx +++ b/site/docs/components/panel/index.mdx @@ -1,7 +1,7 @@ --- title: Panel data: - description: Panel is a background that organizes content in an application. It uses color to reflect the level of importance of content and drive visual hierarchy. + description: "`Panel` is a background that organizes content in an application. It uses color to reflect the level of importance of content and drive visual hierarchy." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/panel/Panel.tsx" package: name: "@salt-ds/core" diff --git a/site/docs/components/panel/usage.mdx b/site/docs/components/panel/usage.mdx index 60666a4880f..c36af372311 100644 --- a/site/docs/components/panel/usage.mdx +++ b/site/docs/components/panel/usage.mdx @@ -7,19 +7,19 @@ data: $ref: ./#/data --- -### Using the Panel component +### Using the component -Pick the background that reflects the level of importance for the content (primary or secondary) and that will drive the types of components that are therefore displayed in the Panel. +Pick the background that reflects the level of importance of the content (primary or secondary), which will drive the types of components displayed in the panel. -### When to use Panel +### When to use - To organize and divide the application into clear content areas. - To create visual hierarchy within the application layout. -- With the Border Layout component to define the main content regions of your app with responsive behaviour. +- With the [`BorderLayout`](/salt/components/border-layout/) component to define the main content regions of your application with responsive behavior. ### Import -To import Panel from the core Salt package, use: +To import `Panel` from the core Salt package, use: ```js import { Panel } from "@salt-ds/core"; diff --git a/site/docs/components/pill/accessibility.mdx b/site/docs/components/pill/accessibility.mdx index 1e89479b8f9..12fdbc4431b 100644 --- a/site/docs/components/pill/accessibility.mdx +++ b/site/docs/components/pill/accessibility.mdx @@ -10,21 +10,20 @@ data: ### Keyboard interactions - - - When focus is on Pill, it is activated. - - When focus is on the close button, close the pill. + + - When focus is on the pill, this action activates it. + - When focus is on the close button, this action closes the pill. - - Moves focus into Pill. Focus is set to the entire Pill. - - - When Pill has focus, move focus out of Pill to next component in tab order. - - When a closable pill has focus, move focus into the close button. + - Tab sets focus on the entire pill. + - When the pill has focus, Tab moves focus out of the pill to next component in tab order. + - When a closable pill has focus, Tab moves focus into the close button. - - When Pill has focus, move focus out of Pill to previous component in tab + - When the pill has focus, this action moves focus out of the pill to the previous component in the tab order. - - When the close button has focus, move focus back to the pill. + - When the close button has focus, this action moves focus back to the pill. diff --git a/site/docs/components/pill/examples.mdx b/site/docs/components/pill/examples.mdx index dab71fbf1ae..397bb61f2f7 100644 --- a/site/docs/components/pill/examples.mdx +++ b/site/docs/components/pill/examples.mdx @@ -12,21 +12,28 @@ data: ### Default - The default Pill is often used for tagging purposes, or to filter or change the page view. You can also use Pill to trigger an action that is subject to change as a result of user input or a change in context, such as an auto-generated quick response to a message. + You'll typically use the default pill for tagging purposes or to filter or change the page view. You can also use pills to trigger an action subject to change as a result of user input or a change in context, such as an autogenerated quick response to a message. - ### With Icon + ### With icon - Display icons on the left of a default Pill label using the `icon` prop, to visually reinforce the theme or grouping of that pill, and for quick recognition. + Display icons on the left of a default pill label using the `icon` prop to visually reinforce the theme or grouping of that pill and for quick recognition. ### Disabled - Pill can be set to a disabled state, with no resultant action when the user interacts with it. + You can set a pill to a disabled state, with no resultant action when the user interacts with it. + + + + + ### Closable + + The closable pill represents a value selected via another mechanism, and which the user can remove within the pill. It can appear on its own, such as alongside a complex filter panel, or within an input control such as [`ComboBox`](../combo-box). diff --git a/site/docs/components/pill/index.mdx b/site/docs/components/pill/index.mdx index 644b4ce7ada..ad7ed03194b 100644 --- a/site/docs/components/pill/index.mdx +++ b/site/docs/components/pill/index.mdx @@ -1,15 +1,15 @@ --- title: Pill data: - description: Pill is a small visual element that can contain descriptive text and an icon. You can use Pill to label, tag or categorize content. With Pill, users can trigger actions, make selections or filter results. + description: "`PillNext` is a small visual element that can contain descriptive text and an icon. You can use pills to label, tag or categorize content. With pills, users can trigger actions, make selections or filter results." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/lab/src/pill-next/PillNext.tsx" package: name: "@salt-ds/lab" alsoKnownAs: ["Tag", "Chip", "Badge"] relatedComponents: [ - { name: "ToggleButton", relationship: "similarTo" }, { name: "Button", relationship: "similarTo" }, + { name: "Toggle button", relationship: "similarTo" }, { name: "Icon", relationship: "contains" }, ] stickerSheet: "" diff --git a/site/docs/components/pill/usage.mdx b/site/docs/components/pill/usage.mdx index 08db279ee0f..698fd9e3de1 100644 --- a/site/docs/components/pill/usage.mdx +++ b/site/docs/components/pill/usage.mdx @@ -7,23 +7,28 @@ data: $ref: ./#/data --- -#### When to use Pill +### Using the component -- To organize content that may be mapped to more than one category. This provides users with a way of distinguishing different types of content and categories. +Use title or sentence case when labelling pills. This maintains a visual distinction between `Pill` and `Button`, which always has uppercase labels. -- To trigger an immediate action—such as changing the view of content that’s currently on display or navigating to a new page that is contextually related to the pill. +Position any pill you’re using to tag content below or on the right of the related content, so that it’s not the primary focus. -- To enable an action that may change depending on the context. In a messaging application, you could use pills to display predefined replies that change depending on the received message. +Never apply red/amber/green status colors to pills to differentiate between categories. Use [icons](/salt/components/icon) or text instead. -#### When not to use Pill +#### When to use -- For actions that may change depending on the context, and are not fixed, are better represented by Button than Pill. +- To organize content mapped to more than one category, providing users with a way of distinguishing different content types and categories. +- To trigger an immediate action—such as changing the view of currently displayed content or going to a new page contextually related to the pill. +- To enable an action that could change depending on the context. In a messaging application, you could use pills to display predefined replies that change depending on the received message. -- When the content is a system message and does not support interaction. Instead, use [Badge](/salt/components/badge). +#### When not to use + +- For nonfixed actions that may change depending on the context. Instead, use [`Button`](/salt/components/button). +- When the content is a system message that doesn't support interaction. Instead, use [`Badge`](/salt/components/badge). ### Import -To import Pill from the lab Salt package, use: +To import `PillNext` from the lab Salt package, use: ``` import { PillNext } from “@salt-ds/lab”; @@ -32,11 +37,3 @@ import { PillNext } from “@salt-ds/lab”; ### Props - -### Using the Pill component - -Use title or sentence case when labelling Pill. This maintains a visual distinction between Pill and Button, which always has uppercase labels. - -Position any Pill you’re using to tag content below or on the right of the related content, so that it’s not the primary focus. - -Never apply RAG (status) colors to Pill to differentiate between categories. Use [Icons](/salt/components/icon) or text instead. diff --git a/site/docs/components/progress/accessibility.mdx b/site/docs/components/progress/accessibility.mdx index b8fc017bf79..416e54a70ec 100644 --- a/site/docs/components/progress/accessibility.mdx +++ b/site/docs/components/progress/accessibility.mdx @@ -9,6 +9,8 @@ data: $ref: ./#/data --- +### Best practices + Improve accessibility by customizing the `aria-label` prop to provide additional context about what is loading. For example: ```jsx diff --git a/site/docs/components/progress/examples.mdx b/site/docs/components/progress/examples.mdx index 817e1684d68..b9c20eef967 100644 --- a/site/docs/components/progress/examples.mdx +++ b/site/docs/components/progress/examples.mdx @@ -31,7 +31,7 @@ Use linear or circular depending on the context, layout and functionality of an ### With maximum value -Specify the maximum value of the progress indicator. The percentage progress will be calculated using this value. Default value is 100. +Specify the maximum value of the progress indicator. The percentage progress will be calculated using this value. The default value is 100. diff --git a/site/docs/components/progress/index.mdx b/site/docs/components/progress/index.mdx index a4524e1e88e..27a0bbb92bb 100644 --- a/site/docs/components/progress/index.mdx +++ b/site/docs/components/progress/index.mdx @@ -1,16 +1,16 @@ --- title: Progress sidebar: - label: Progress 🚧 + label: Progress data: - description: "Circular Progress and Linear Progress communicate the status of an ongoing operation, such as file downloads or data uploads. The two components accommodate different layout constraints." + description: "A progress indicator gives the user an understanding of how long a system operation will take. You should use it when the operation will take more than a second to complete. Two components are available to accommodate different layout constraints: `CircularProgress` and `LinearProgress`." # 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/tree/main/packages/lab/src/progress" package: name: "@salt-ds/lab" - alsoKnownAs: [Progress Bar, Progress Indicator] + alsoKnownAs: [Progress bar, Progress indicator] relatedComponents: [] # stickerSheet: "https://figma.com/..." status: Lab component diff --git a/site/docs/components/progress/usage.mdx b/site/docs/components/progress/usage.mdx index c42d7a3a7ad..17c0f9a1837 100644 --- a/site/docs/components/progress/usage.mdx +++ b/site/docs/components/progress/usage.mdx @@ -9,14 +9,15 @@ data: $ref: ./#/data --- -### Using the Progress components +### Using the components -#### When to use Progress +#### When to use - When it’s possible to determine the length of time remaining for a task or operation to complete. This will reassure the user that it is being processed. - To provide users with a visual indication of the status of an operation, or how much of a process is completed. +- When the operation will take more than a second to complete, to reassure users that the operation is in progress. -#### When not to use Progress +#### When not to use - When a task or operation will take an indeterminate length of time to complete. Instead, use [`Spinner`](/salt/components/spinner). - To indicate the loading of content on navigation. Instead, use [`Spinner`](/salt/components/spinner). diff --git a/site/docs/components/radio-button/accessibility.mdx b/site/docs/components/radio-button/accessibility.mdx index 5b06fed673b..55a8abeaab5 100644 --- a/site/docs/components/radio-button/accessibility.mdx +++ b/site/docs/components/radio-button/accessibility.mdx @@ -11,29 +11,23 @@ data: ### Best practices -- On focus, the screen reader should: - - - Identify the radio button - - Read out the text - - Express the state - ### Keyboard interactions -- Moves focus to the checked radio button in the radio button group. -- If a radio button is not checked, focus moves to the first radio button in the group. +- Tab moves focus to the checked radio button in the radio button group. +- If the user hasn't checked a radio button, Tab moves focus to the first radio button in the group. -- If the radio button with focus is not checked, changes the state to checked. +- If the focused radio button isn't checked, Space changes the state to checked. - + -- Moves focus between the available radio button options, and simultaneously selects an option. +- This action moves focus between the available radio button options, and simultaneously selects an option. diff --git a/site/docs/components/radio-button/examples.mdx b/site/docs/components/radio-button/examples.mdx index 9fffa029a92..965af6b3c4b 100644 --- a/site/docs/components/radio-button/examples.mdx +++ b/site/docs/components/radio-button/examples.mdx @@ -12,13 +12,13 @@ data: -### Radio Button Group (vertical) +### Radio button group (vertical) -Radio Button Groups allows users to select one or more values from a given set of choices. They can be aligned horizontally or vertically. +Radio button groups allow users to select one or more values from a given set of choices. You can align them horizontally or vertically. When `direction="vertical"` -Guidance: +#### Best practices - Keep text short and as concise as possible in the horizontal orientation. - Do not truncate text descriptions as this can hide important content relevant to the user’s workflow. Consider shortening or rewording the label if space is limited. @@ -29,7 +29,7 @@ Guidance: -### Radio Button Group (horizontal) +### Radio button group (horizontal) When `direction="horizontal"` @@ -37,7 +37,7 @@ When `direction="horizontal"` -### Wrapping Radio Button group +### Wrapping radio button group The default behaviour for Radio Button Group in a horizontal alignment allows radio button options to wrap onto the next line as the viewport size changes if they don’t fit within a container. @@ -55,13 +55,13 @@ You can configure radio button groups to maintain a horizontal alignment but all ### Disabled Radio Button -A disabled radio button is not interactive or focusable. +A disabled radio button isn't interactive or focusable. -A radio button can be disabled by setting `disabled={true}`. +You can disable a radio button by setting `disabled={true}`. -Guidance: +#### Best practices -Use a disabled state for radio buttons that have permissions, dependencies or pre-requisites. For example, a radio button in a [Form](/salt/patterns/forms) may be disabled because the user has not yet completed an earlier section of the form. +Use a disabled state for radio buttons that have permissions, dependencies or pre-requisites. For example, a radio button in a [form](/salt/patterns/forms) may be disabled because the user hasn't yet completed an earlier section of the form. If a disabled radio button's text description contains information that is valuable to the user, consider using a read-only radio button instead. @@ -69,15 +69,15 @@ If a disabled radio button's text description contains information that is valua -### Read-only Radio Button +### Read-only radio button A read-only radio button permits the user to only read or copy the value, but not edit the value or change the state of the radio. A radio button with the prop `readOnly={true}` will suppress all functionality along with displaying read-only styling. -Guidance: +#### Best practices -Read-only radio buttons are navigable using keyboard shortcuts. This means that, unlike disabled radio buttons, users can interact with the text description. Use a read-only radio button instead of a disabled radio button when the text description contains information that is valuable to the user. +Users can interact with read-only radio buttons using keyboard shortcuts. This means that, unlike disabled radio buttons, users can interact with the text description. Use a read-only radio button instead of a disabled radio button when the text description contains information valuable to the user. @@ -85,7 +85,7 @@ Read-only radio buttons are navigable using keyboard shortcuts. This means that, ### Validation states: error -You can indicate an error state stylistically by setting the `validationStatus` prop to "error". +You can indicate an error state stylistically by setting the `validationStatus` prop to `"error"`. @@ -93,10 +93,10 @@ You can indicate an error state stylistically by setting the `validationStatus` ### Validation states: warning -You can indicate a warning state stylistically by setting the `validationStatus` prop to "warning". +You can indicate a warning state stylistically by setting the `validationStatus` prop to `"warning"`. -- When used in a group, use `validationStatus` on the group rather than the individual controls. Any status provided to the group will take precedence over the statuses applied directly to the nested controls. -- Avoid using `validationStatus` when a Radio Button is disabled. If provided, disabled functionality and styling will take precedence over any validation status styling. +- In a group, use `validationStatus` rather than the individual controls. Any status provided to the group will take precedence over the statuses applied directly to the nested controls. +- Avoid using `validationStatus` with a disabled radio button. If provided, disabled functionality and styling will take precedence over any validation status styling. @@ -110,11 +110,11 @@ Radio Button supports long text descriptions. If text wraps to multiple lines, a -### Form Field compatibility +### Form field compatibility -Radio Button group can be wrapped in a Form Field when it’s displayed within a Form context. This provides functionality built into Form Field for increased accessibility. +You can wrap `RadioButtonGroup` in a form field when it’s within a form context. -For more information, refer to the [Form Field](/salt/patterns/forms) guidance. +For more information, refer to the [form field](/salt/patterns/forms) guidance. diff --git a/site/docs/components/radio-button/index.mdx b/site/docs/components/radio-button/index.mdx index 9429445303b..a84278a3a3d 100644 --- a/site/docs/components/radio-button/index.mdx +++ b/site/docs/components/radio-button/index.mdx @@ -1,7 +1,7 @@ --- -title: Radio Button +title: Radio button data: - description: Radio Button and Radio Button Group represent a set of mutually exclusive, but related options. Only one radio button can be selected at a time. When a user selects a new option, the previously selected option is automatically deselected. Radio Button should therefore be used to display a choice between two or more options, as it’s impossible to deselect a single radio button once it’s been selected. + description: "`RadioButton` and `RadioButtonGroup` represent a set of mutually exclusive but related options. The user can only select one radio button at a time. When a user selects a new option, the previously selected option automatically clears. Therefore, you should use radio buttons should therefore be used to display a choice between two or more options, as it’s impossible to clear a single radio button after selecting it." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # diff --git a/site/docs/components/radio-button/usage.mdx b/site/docs/components/radio-button/usage.mdx index 475cb3ded16..55fe25ae807 100644 --- a/site/docs/components/radio-button/usage.mdx +++ b/site/docs/components/radio-button/usage.mdx @@ -9,23 +9,24 @@ data: $ref: ./#/data --- -### Using the Radio Button component +### Using the components -#### When to use Radio Button +#### When to use -- When you have fewer than five options and only single selection is required +- When you have fewer than five options and only single selection is necessary. -#### When not to use Radio Button +#### When not to use -- When you have a Boolean selection (on/off). Instead, use [Switch](../switch). -- When you have fewer than five options and multiple selection is required. Instead, use [Checkbox Group](../checkbox). -- When you have more than five and fewer than 10 options. Instead, use [Dropdown](../dropdown). +- When you have a Boolean selection (on/off). Instead, use [`Switch`](../switch). +- When you have fewer than five options and multiple selection is necessary. Instead, use [`CheckboxGroup`](../checkbox). +- When you have more than five and fewer than 10 options. Instead, use [`Dropdown`](../dropdown). +- When you have more than 10 options. Instead, use [`ComboBox`](../combo-box). ### Import {/* Update the text and code snippet below as needed: */} -To import Radio Button from the core Salt package, use: +To import `RadioButton` and `RadioButtonGroup` from the core Salt package, use: ```js import { RadioButton, RadioButtonGroup } from "@salt-ds/core"; @@ -36,11 +37,11 @@ import { RadioButton, RadioButtonGroup } from "@salt-ds/core"; {/* Update packageName and componentName below as needed */} {/* packageName is optional and defaults to "core" if omitted */} -#### Radio Button +#### `RadioButton` -#### Radio Button Group +#### `RadioButtonGroup` diff --git a/site/docs/components/salt-provider/examples.mdx b/site/docs/components/salt-provider/examples.mdx index 2dd1bfbc8af..3f5c8336d9d 100644 --- a/site/docs/components/salt-provider/examples.mdx +++ b/site/docs/components/salt-provider/examples.mdx @@ -14,9 +14,9 @@ data: ### Theme - Use Salt Provider to change the theme of your application with the `theme` prop. By default, this is set to `salt-theme`. + Use `SaltProvider` to change the theme of your application with the `theme` prop. The default setting is `salt-theme`. - Use the `useTheme` hook to access the current active theme. + Use the `useTheme` hook to access the currently active theme. @@ -24,9 +24,9 @@ data: ### Modes - Use the `mode` prop to change the mode for all nested components. Modes enable the color palette to change from light to dark. You can read more about it on the [Modes Foundation](/salt/foundations/modes) page. The default mode is `light` mode. + Use the `mode` prop to change the mode for all nested components. Modes enable the color palette to change from light to dark. You can read more about it on the [modes foundation](/salt/foundations/modes) page. The default mode is `light` mode. - You can use the mode toggle at the top of this page to change the mode in the example. Note how the Card background and text changes. + You can use the mode toggle at the top of this page to change the mode in the example. Note how the card background and text change. Use the `useTheme` hook to access the current mode. @@ -36,9 +36,9 @@ data: ### Density - Use the `density` prop to change the density for all nested components. Density controls the amount of content that can fit on a screen based on the size and spacing of components. You can read more about it on the [Density Foundation](/salt/foundations/density) page. The default density is `medium` density. + Use the `density` prop to change the density for all nested components. Density controls the amount of content that can fit on a screen based on the size and spacing of components. You can read more about it on the [density foundation](/salt/foundations/density) page. The default density is `medium`. - You can use the density toggle at the top of this page to change the density in the example. See how the spacing changes between the squares. + You can use the density toggle at the top of this page to change the density and see how the spacing changes between the squares. Use the `useDensity` hook to access the current density. @@ -48,17 +48,17 @@ data: ### Breakpoints - Use the `breakpoints` prop to customize the CSS media queries that hooks like `useBreakpoints` and `useCurrentBreakpoint` use internally. These hooks are used for the responsive props, when you can pass multiple values (one per breakpoint) or a single value that would take affect across all screen sizes. You can read the [Responsiveness Foundation page](/salt/foundations/responsiveness) for more information about Salt's default breakpoints. + Use the `breakpoints` prop to customize the CSS media queries that hooks such as `useBreakpoints` and `useCurrentBreakpoint` use internally. You can use these hooks for the responsive props to pass multiple values (one per breakpoint) or a single value that would take affect across all screen sizes. You can read the [responsiveness foundation page](/salt/foundations/responsiveness) for more information about Salt's default breakpoints. - Use the `useBreakpoints` hook to access the current breakpoints defined via the Salt Provider. This is a low-level hook that is used internally in other hooks. + Use the `useBreakpoints` hook to access the current breakpoints defined via the Salt Provider. This is a low-level hook used internally in other hooks. - ### Nested Providers + ### Nested providers - You can used Salt Provider to create scoped themes, allowing you to mix themes, modes, densities and breakpoints in your application. Familiarize yourself with the guidance on our [Foundations](/salt/foundations/index) pages, where we recommend that you use this sparingly. Nested providers will inherit values from parent providers. + You can use `SaltProvider` to create scoped themes, allowing you to mix themes, modes, densities and breakpoints in your application. Familiarize yourself with the guidance on our [foundations](/salt/foundations/index) pages, where we recommend that you use this sparingly. Nested providers will inherit values from parent providers. diff --git a/site/docs/components/salt-provider/index.mdx b/site/docs/components/salt-provider/index.mdx index 5750c29b77e..36a3451c7c6 100644 --- a/site/docs/components/salt-provider/index.mdx +++ b/site/docs/components/salt-provider/index.mdx @@ -1,7 +1,7 @@ --- -title: Salt Provider +title: Salt provider data: - description: Salt Provider is a required component that is used to change the theme, mode, density and breakpoints of your application. + description: "`SaltProvider` is a required component used to change the theme, mode, density and breakpoints of your application." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # diff --git a/site/docs/components/salt-provider/usage.mdx b/site/docs/components/salt-provider/usage.mdx index 58cc1a9bc61..660646fb9a1 100644 --- a/site/docs/components/salt-provider/usage.mdx +++ b/site/docs/components/salt-provider/usage.mdx @@ -10,7 +10,7 @@ data: ### Import -To import Salt Provider from the core Salt package, use: +To import `SaltProvider` from the core Salt package, use: ``` import { SaltProvider } from "@salt-ds/core"; diff --git a/site/docs/components/spinner/accessibility.mdx b/site/docs/components/spinner/accessibility.mdx index 05cd1886d18..a58750a19e2 100644 --- a/site/docs/components/spinner/accessibility.mdx +++ b/site/docs/components/spinner/accessibility.mdx @@ -12,8 +12,8 @@ data: - Improve accessibility by customizing the `aria-label` to provide additional context about what is loading, for example, `aria-label="loading settings panel"`. -- The `aria-label` will be announced to screen-reader users at a regular interval which can be customised using the `announcerInterval` property. +- Screen-reader users will hear the `aria-label` at a regular interval, which you can customize using the `announcerInterval` property. -- After a set timeout the component will stop announcing the `aria-label`, this can be customised using the `announcerTimeout` property +- After a set timeout, the component will stop announcing the `aria-label`, which you can customize using the `announcerTimeout` property. -- A completion message will be announced to screen reader users when the spinner is unmounted to indicate that loading had completed. This can be customised using the `completionAnnouncement` prop or disabled by setting `completionAnnouncement={null}` +- Screen-reader users will hear a completion message when the spinner unmounts to indicate that loading has finished. You can customize this using the `completionAnnouncement` prop or disable it by setting `completionAnnouncement={null}`. diff --git a/site/docs/components/spinner/examples.mdx b/site/docs/components/spinner/examples.mdx index 763fde54b7c..423a343b4a8 100644 --- a/site/docs/components/spinner/examples.mdx +++ b/site/docs/components/spinner/examples.mdx @@ -21,7 +21,7 @@ data: ### Medium (default) - The medium spinner is typically used for widget loading experiences. + You would typically use the medium spinner is typically used for widget loading experiences. For the medium size, set the `size` prop to `”medium”` or leave it as `undefined`. @@ -31,21 +31,21 @@ data: ### Large - The large spinner is useful for full screen loading experiences. + The large spinner is useful for full-screen loading experiences. - For the large size set the `size` prop to `”large”`. + For the large size, set the `size` prop to `”large”`. ### Loading - Center spinner in the middle of a page or content that is loading. + Center the spinner in the middle of a page or content that's loading. - ### Partial Loading + ### Partial loading When updating only a portion of a page, position the spinner within that specific area. diff --git a/site/docs/components/spinner/index.mdx b/site/docs/components/spinner/index.mdx index 120225d8776..7617a984fd6 100644 --- a/site/docs/components/spinner/index.mdx +++ b/site/docs/components/spinner/index.mdx @@ -1,7 +1,7 @@ --- title: Spinner data: - description: Spinner is a visual representation of a process that is taking an indeterminate time to complete. This can be triggered by automated system processes, a user action, or to indicate that content is loading. This reassures the user that the system is still working, especially when the operation is taking longer than one second. + description: "`Spinner` is a visual representation of a process taking an indeterminate time to complete. Triggers include automated system processes, a user action or an indicator of content loading. Displaying a spinner reassures the user that the system is still working, especially when the operation takes longer than one second." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/spinner/Spinner.tsx" package: name: "@salt-ds/core" diff --git a/site/docs/components/spinner/usage.mdx b/site/docs/components/spinner/usage.mdx index 5c9fcf40a28..3a42d96aa8b 100644 --- a/site/docs/components/spinner/usage.mdx +++ b/site/docs/components/spinner/usage.mdx @@ -7,23 +7,22 @@ data: $ref: ./#/data --- -### How to use Spinner +### Using the component -#### When to use Spinner +#### When to use - To indicate that content is loading and reassure the user that the system is still working. +- For actions that you expect will take 1–9 seconds to load or for processes that will take an indeterminate amount of time to complete. -- For actions that you expect will take either between 1-9 seconds to load, or for processes that are taking an indeterminate amount of time to complete. +#### When not to use -#### When not to use Spinner +- For actions that will run for a determinable length of time. Instead, use [`Progress`](/salt/components/progress). -- For actions that will run for a determinable length of time. Instead, use [Progress](/salt/components/progress). - -- For a process that is taking longer than 10 seconds to complete, as this is the point at which any attempt for a system to respond should finish, and a status message should be displayed instead. For further guidance, view the [Salt Duration Foundation](/salt/foundations/duration). +- For a process that is taking longer than 10 seconds to complete, as this is the point at which any attempt for a system to respond should finish, and a status message should display instead. For further guidance, view the [Salt duration foundation](/salt/foundations/duration). ### Import -To import Spinner from the core Salt package, use: +To import `Spinner` from the core Salt package, use: ```js import { Spinner } from "@salt-ds/core"; diff --git a/site/docs/components/split-layout/accessibility.mdx b/site/docs/components/split-layout/accessibility.mdx index de6f777c94f..5aa45ae3296 100644 --- a/site/docs/components/split-layout/accessibility.mdx +++ b/site/docs/components/split-layout/accessibility.mdx @@ -9,9 +9,11 @@ data: $ref: ./#/data --- -When building a sub-section of a page using Split Layout, you should use semantic HTML. This means using the correct HTML elements for their intended purpose as much as possible. +### Best practices -Split Layout supports semantic HTML with the `as` prop. This renders the appropriate HTML instead of a plain `div`. +When building a sub-section of a page using a split layout, it's important to use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. + +`SplitLayout` supports semantic HTML with the `as` prop. This renders the appropriate HTML instead of a plain `div`. ```tsx @@ -25,7 +25,7 @@ Its items align centrally within the layout, with a `gap` between items of 3, wh ### Column direction -The Split Layout `direction` prop defines the main axis that items are displayed along. Set `direction` to `column` to display items in a vertical direction along a single line. +The split layout `direction` prop defines the main axis that items are displayed along. Set `direction` to `column` to display items in a vertical direction along a single line. @@ -33,7 +33,7 @@ The Split Layout `direction` prop defines the main axis that items are displayed ### Button bar -This example shows two groups of buttons inside a Split Layout, such as within an App Header. Here, Split Layout is in its default configuration. +This example shows two groups of buttons inside a split layout, such as within an app header. Here, the split layout is in its default configuration. @@ -41,7 +41,7 @@ This example shows two groups of buttons inside a Split Layout, such as within a ### Responsive layout -Split Layout supports responsive props, so you can define different behaviors based on viewport size. You can use the default [Salt breakpoints](https://www.saltdesignsystem.com/salt/foundations/responsiveness) or pass in your own using `SaltProvider`. +The split layout component supports responsive props, so you can define different behaviors based on viewport size. You can use the default [Salt breakpoints](https://www.saltdesignsystem.com/salt/foundations/responsiveness) or pass in your own using `SaltProvider`. #### Responsive props @@ -57,7 +57,7 @@ direction={{ xs: "column", sm: "column", lg: "row", md: "row ", xl: "row" }} ### Layout alignment -Control the position of Split Layout and its items using the `align` prop. +Control the position of the split layout and its items using the `align` prop. If there is additional space available around the layout (i.e., above or below the row, or beside the column) use the `align` prop to position items within that space. @@ -67,7 +67,7 @@ If there is additional space available around the layout (i.e., above or below t ### Flex item position -Use the Flex Item `align` prop to set an alignment for a specific item in the layout. Use the `align` prop to change the item’s position along the cross-axis of the layout (i.e., perpendicular to the `direction`–`row` or `column`). +Use the flex item component's `align` prop to set an alignment for a specific item in the layout. Use the `align` prop to change the item’s position along the cross-axis of the layout (i.e., perpendicular to the `direction`–`row` or `column`). @@ -75,15 +75,13 @@ Use the Flex Item `align` prop to set an alignment for a specific item in the la ### Flex item size -The Flex Item `grow` prop enables specific items in the layout to grow and fill any remaining space that is available in the layout: +The flex item component's `grow` prop enables specific items in the layout to grow and fill any remaining space that is available in the layout: -- By default, `grow` is set to `0` and items will be displayed in their normal size. -- If an item is set to `1` it will fill the available space. -- If an item is set to `2` it will fill twice as much space as other items that have `grow` set to `1`. +- By default, `grow` is set to 0 and items will display in their normal size. +- If you set an item to 1, it will fill the available space. +- If you set an item to 2, it will fill twice as much space as items that have `grow` set to 1. -#### Guidance - -In contrast to the `grow` prop, the `shrink` prop shrinks specific items as small as possible within the layout. By default, `shrink` is set to `1`. If an item is set to `2`, that item would attempt to take half as much space. +In contrast to the `grow` prop, the `shrink` prop shrinks specific items as small as possible within the layout. By default, `shrink` is set to 1. If an item is set to 2, that item would attempt to take half as much space. diff --git a/site/docs/components/split-layout/index.mdx b/site/docs/components/split-layout/index.mdx index ae0721f0e5f..260bbb07540 100644 --- a/site/docs/components/split-layout/index.mdx +++ b/site/docs/components/split-layout/index.mdx @@ -1,7 +1,7 @@ --- -title: Split Layout +title: Split layout data: - description: Split Layout displays items in two separate areas at opposite ends of a container. You can define the container in a vertical or horizontal orientation. + description: "`SplitLayout` displays items in two separate areas at opposite ends of a container. You can define the container in a vertical or horizontal orientation." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # @@ -14,8 +14,8 @@ data: # related component here (separated by commas). # Permitted values for relationship are: "similarTo" or # "contains". - { name: "Flex Layout", relationship: "similarTo" }, - { name: "Flex Layout", relationship: "contains" }, + { name: "Flex layout", relationship: "similarTo" }, + { name: "Flex layout", relationship: "contains" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/split-layout/usage.mdx b/site/docs/components/split-layout/usage.mdx index 41ce407a130..f674192b5f2 100644 --- a/site/docs/components/split-layout/usage.mdx +++ b/site/docs/components/split-layout/usage.mdx @@ -9,22 +9,22 @@ data: $ref: ./#/data --- -### How to use the Split Layout component +### Using the component -#### When to use Split Layout +#### When to use -- If you need two defined areas at the opposite horizontal ends of a container, for example if you need two Button Bar components in a header. +- If you need two defined areas at the opposite horizontal ends of a container, for example, if you need two button bar components in a header. -#### When not to use Split Layout +#### When not to use -- If your layout requires more than two regions. Instead, use [Flow Layout](/salt/components/flow-layout). -- If you want more complex customization in your layout, consider [Flex Layout](/salt/components/flex-layout). +- If your layout requires more than two regions. Instead, use [`FlowLayout`](/salt/components/flow-layout). +- If you want more complex customization in your layout, consider [`FlexLayout`](/salt/components/flex-layout). ### Import {/* Update the text and code snippet below as needed: */} -To import Split Layout from the core Salt package, use: +To import `SplitLayout` from the core Salt package, use: ```js import { SplitLayout } from "@salt-ds/core"; diff --git a/site/docs/components/stack-layout/accessibility.mdx b/site/docs/components/stack-layout/accessibility.mdx index 639a89df67c..9f6f4e7be40 100644 --- a/site/docs/components/stack-layout/accessibility.mdx +++ b/site/docs/components/stack-layout/accessibility.mdx @@ -9,9 +9,11 @@ data: $ref: ./#/data --- -When building a sub-section of a page using Stack Layout, it is important to make sure you use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. +### Best practices -Stack Layout supports this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. +When building a subsection of a page using `StackLayout`, it's important to use semantic HTML, which means using the correct HTML elements for their intended purpose as much as possible. + +`StackLayout` supports this behavior by allowing access to a prop called `as` that allows you to render the appropriate HTML instead of a plain `div`. ```tsx diff --git a/site/docs/components/stack-layout/examples.mdx b/site/docs/components/stack-layout/examples.mdx index b8a46d68caa..4f38e066e5d 100644 --- a/site/docs/components/stack-layout/examples.mdx +++ b/site/docs/components/stack-layout/examples.mdx @@ -15,9 +15,9 @@ data: ### Default -By default, Stack Layout displays items in a single column. +By default, `StackLayout` displays items in a single column. -Its items align to the start of the layout, with a `gap` between items of 3, which is a multiple of the [Salt base unit](/salt/foundations/spacing). The height and width of the layout are driven by the items contained within it. +Its items align to the start of the layout, with a `gap` between items of 3, which is a multiple of the [Salt base unit](/salt/foundations/spacing). The items contained within the layout determine its height and width. @@ -25,7 +25,7 @@ Its items align to the start of the layout, with a `gap` between items of 3, whi ### Row direction -The Stack Layout `direction` prop defines the main axis that items are displayed along. Set `direction` to `row` to display items in a horizontal direction along a single line. +The `direction` prop defines the main axis to display items along. Set `direction` to `row` to display items in a horizontal direction along a single line. @@ -33,9 +33,9 @@ The Stack Layout `direction` prop defines the main axis that items are displayed ### Layout separators -Stack Layout allows for `separators` to be displayed between items. By default, the separators are centered when `separators={true}` but can be customized to sit on the left or right of items. +The component allows for `separators` between items. By default, the separators have a cnetered alignment when `separators={true}` but you can customize them to sit on the left or right of items. -The separator will span across the layout component if the `direction` is `column`, or span the height if the `direction` is `row`. The Stack Layout `gap` is applied to both sides of the separator. +The separator will span across the layout component if the `direction` is `column` or span the height if the `direction` is `row`. The Stack Layout `gap` applies to both sides of the separator. @@ -43,11 +43,11 @@ The separator will span across the layout component if the `direction` is `colum ### Responsive layout -Stack Layout supports responsive props, so you can define different behaviors based on viewport size (e.g., switching `direction` of a card stack with separators across screen size). You can use the default [Salt breakpoints](/salt/foundations/responsiveness#breakpoints) or pass in your own using `SaltProvider`. +`StackLayout` supports responsive props, so you can define different behaviors based on viewport size (e.g., switching `direction` of a card stack with separators across screen size). You can use the default [Salt breakpoints](/salt/foundations/responsiveness#breakpoints) or pass in your own using [`SaltProvider`](/salt/components/salt-provider/). #### What are responsive props? -A responsive prop is a prop that takes either multiple values (one value per breakpoint), or a single value that would take effect across all different screen sizes. For example, a layout that will responsively change direction from row to column at specific breakpoints or viewport sizes: +A responsive prop takes either multiple values (one value per breakpoint) or a single value that would take effect across all different screen sizes. For example, this is a layout that will responsively change direction from row to column at specific breakpoints or viewport sizes: ```js direction={{ xs: "column", sm: "column", lg: "row", md: "row ", xl: "row" }} @@ -59,33 +59,31 @@ direction={{ xs: "column", sm: "column", lg: "row", md: "row ", xl: "row" }} ### Layout alignment -Control the position of Stack Layout and its items using the `align` prop. +Control the position of `StackLayout` and its items using the `align` prop. -If there is additional space available around the layout (i.e., above or below the row, or beside the column) use the `align` prop to define how items should be positioned within that space. +If there's additional space available around the layout (i.e., above or below the row or beside the column), use the `align` prop to define the position of items within that space. -### Flex Item position +### `FlexItem` position -Use the Flex Item `align` prop to set an alignment for a specific item in the layout. Use the `align` prop to change the item’s position along the cross-axis of the layout (i.e., perpendicular to the `direction`–`row` or `column`). +Use the `FlexItem` `align` prop to set an alignment for a specific item in the layout. Use the `align` prop to change the item’s position along the cross axis of the layout (i.e., perpendicular to the `direction`–`row` or `column`). -### Flex Item size +### `FlexItem` size -The Flex Item `grow` prop enables specific items in the layout to grow and fill any remaining space that is available in the layout: +The `FlexItem` `grow` prop enables specific items in the layout to grow and fill any remaining space in the layout: -- By default, `grow` is set to 0 and items will be displayed in their ‘normal’ size. -- If an item is set to `1` it will fill the available space. -- If an item is set to `2` it will fill twice as much space as other items that have `grow` set to `1`. +- By default, `grow` is set to `0`, and items will be in their "normal" size. +- If you set an item to `1`, it will fill the available space. +- If you set an item to `2`, it will fill twice as much space as other items where `grow` is `1`. -#### Guidance - -- In contrast to the `grow` prop, the `shrink` prop makes a specific item as small as possible within the layout. By default, `shrink` is set to `1`. If an item is set to `2`, that item would attempt to take half as much space. +In contrast to the `grow` prop, the `shrink` prop makes a specific item as small as possible within the layout. By default, `shrink` is `1`. If you set an item to `2`, that item would attempt to take half as much space. diff --git a/site/docs/components/stack-layout/index.mdx b/site/docs/components/stack-layout/index.mdx index 44259368e3d..1d6260bd40c 100644 --- a/site/docs/components/stack-layout/index.mdx +++ b/site/docs/components/stack-layout/index.mdx @@ -1,22 +1,22 @@ --- -title: Stack Layout +title: Stack layout data: - description: Stack Layout displays items in either a horizontal or vertical order on a single line. It is built on top of the Flex Layout component and is specifically intended for small-scale layouts where components need to be displayed in a single row or column, and may benefit from the supported visual separators, for example, a row of charts or a scrolling side panel comprising of multiple sections. For additional control of the size and position of content, use Flex Item for each content item inside Stack Layout. + description: "`StackLayout` displays items in horizontal or vertical order on a single line. It builds on the `FlexLayout` component and is best for small-scale layouts where displaying components in a single row or column is necessary. It may benefit from supported visual separators, such as a row of charts or a scrolling side panel comprising multiple sections. For additional control of the size and position of content, use `FlexItem` for each content item inside `StackLayout`." # 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/stack-layout/StackLayout.tsx" package: name: "@salt-ds/core" - alsoKnownAs: ["Inline Layout", "Flex Layout", "Column Layout"] + alsoKnownAs: ["Inline layout", "Flex layout", "Column layout"] relatedComponents: [ # Add a { name: "...", relationship: "..." } block for each # related component here (separated by commas). # Permitted values for relationship are: "similarTo" or # "contains". - { name: "Split Layout", relationship: "similarTo" }, - { name: "Flow Layout", relationship: "similarTo" }, - { name: "Flex Layout", relationship: "contains" }, + { name: "Flow layout", relationship: "similarTo" }, + { name: "Split layout", relationship: "similarTo" }, + { name: "Flex layout", relationship: "contains" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/stack-layout/usage.mdx b/site/docs/components/stack-layout/usage.mdx index d69eadfed60..b188eeb25d9 100644 --- a/site/docs/components/stack-layout/usage.mdx +++ b/site/docs/components/stack-layout/usage.mdx @@ -9,23 +9,23 @@ data: $ref: ./#/data --- -### When to use Stack Layout +### Using the component -- When you need a layout that is consistently horizontal or vertical. If there is not enough space in the main-axis, scrolling the content is acceptable. +#### When to use +- When you need a layout that's consistently horizontal or vertical. If there isn't enough space in the main axis, scrolling the content is acceptable. - For small-scale layouts within the application, such as a stack of cards or charts or a vertical side panel with visually distinct sections. +- To change the layout’s direction depending on breakpoints or add visual separation using the stack layout separators. -- To change the layout’s direction depending on breakpoints, and if visual separation using the Stack Layout separators is desirable. +#### When not to use -### When not to use Stack Layout +- Stack layouts will never wrap. If you want to create a layout in a row that responsively wraps over multiple lines, use [`FlowLayout`](/salt/components/flow-layout) instead. -- Stack Layout will never wrap. If you want to create a layout in a row that responsively wraps over multiple lines, use [Flow Layout](/salt/components/flow-layout) instead. - -- You want the layout to have more complex customization. In this case we recommend you having a look at [Flex Layout](/salt/components/flex-layout). +- If you want the layout to have more complex customization. In this case, consider [`FlexLayout`](/salt/components/flex-layout). ### Import -To import Stack Layout from the core Salt package, use: +To import `StackLayout` from the core Salt package, use: ```js import { StackLayout } from "@salt-ds/core"; diff --git a/site/docs/components/status-indicator/accessibility.mdx b/site/docs/components/status-indicator/accessibility.mdx index b9db6571a26..4f31117bc3d 100644 --- a/site/docs/components/status-indicator/accessibility.mdx +++ b/site/docs/components/status-indicator/accessibility.mdx @@ -9,4 +9,4 @@ data: ### Best practices -Decorative status indicators (status indicators that repeat the information already expressed by the accompanied text) should be hidden from the screen reader to avoid repetition. If you are adding a status indicator for decorative purposes, pass `aria-hidden=”true”` to hide its label from the screen reader. +You should exclude decorative status indicators (status indicators that repeat the information already expressed by the accompanied text) from the screen reader to avoid repetition. If you're adding a status indicator for decorative purposes, pass `aria-hidden=”true”` to exclude its label from the screen reader. diff --git a/site/docs/components/status-indicator/examples.mdx b/site/docs/components/status-indicator/examples.mdx index f86df393579..a64e4f8bbdc 100644 --- a/site/docs/components/status-indicator/examples.mdx +++ b/site/docs/components/status-indicator/examples.mdx @@ -12,8 +12,8 @@ data: ### Status - Use the `status` prop to change the status displayed. This will affect both - the icon and the color of the `StatusIndicator`. The status indicator offers + Use the `status` prop to change the displayed status. This will affect both + the icon and the color of `StatusIndicator`. The status indicator offers four severity levels that set a distinctive indicator and color. @@ -22,17 +22,17 @@ data: ### Size You can control the size of the Status Indicator with the `size` prop. This - number will be used as a multiplier of the base size as described in the + number will multiply the base size as described in the [scale](/salt/foundations/scale) and [size](/salt/foundations/size) foundations. - ### Labelling + ### Labeling We recommend that you add a self-explanatory header/label next to the status - indicator to help end-users to understand the type of status indicated. + indicator to help end users to understand the type of status indicated. diff --git a/site/docs/components/status-indicator/index.mdx b/site/docs/components/status-indicator/index.mdx index cedaa5873ff..7447c9ab5ab 100644 --- a/site/docs/components/status-indicator/index.mdx +++ b/site/docs/components/status-indicator/index.mdx @@ -1,7 +1,7 @@ --- -title: Status Indicator +title: Status indicator data: - description: A status indicator is a specialised icon which can be used to indicate a particular status (info, warning, error or success). It can be used on its own or within another component (e.g. Tooltip) to help convey a message. + description: "`StatusIndicator` is a specialized icon that you can use to indicate a particular status (info, warning, error or success). You can use it on its own or within another component (e.g. `Tooltip`) to help convey a message." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/status-indicator/StatusIndicator.tsx" package: name: "@salt-ds/core" @@ -9,11 +9,11 @@ data: alsoKnownAs: ["StatusIcon", "Status"] relatedComponents: [ + { name: "Banner", relationship: "similarTo" }, + { name: "Dialog", relationship: "similarTo" }, { name: "Icon", relationship: "similarTo" }, { name: "Toast", relationship: "similarTo" }, - { name: "Banner", relationship: "similarTo" }, { name: "Tooltip", relationship: "similarTo" }, - { name: "Dialog", relationship: "similarTo" }, { name: "Icon", relationship: "contains" }, ] stickerSheet: "" diff --git a/site/docs/components/status-indicator/usage.mdx b/site/docs/components/status-indicator/usage.mdx index 2f49755db25..b3ac25c9d10 100644 --- a/site/docs/components/status-indicator/usage.mdx +++ b/site/docs/components/status-indicator/usage.mdx @@ -7,21 +7,20 @@ data: $ref: ./#/data --- -#### When to use Status Indicator +### Using the component -- Use the info indicator when you need to highlight general information. - -- Use the error indicator when communicating a critical issue that prevents the user from continuing or completing it. +Where possible, we recommend using a Salt component that uses `StatusIndicator`, such as [`Banner`](/salt/components/banner), [`Toast`](/salt/components/toast) or [`Tooltip`](/salt/components/tooltip), instead of using `StatusIndicator` directly. -- Use the warning indicator to inform users of an issue or potential issue related to their current task. Use this for issues that do not prevent the user from continuing or completing their task. +#### When to use -- Use the success indicator to confirm that a user's action has been completed successfully. - -- When you need to indicate a status to the user. Where possible, we recommend using a Salt component that uses Status Indicator, such as [Banner](/salt/components/banner), [Toast](/salt/components/toast) or [Tooltip](/salt/components/tooltip), instead of using Status Indicator directly. +- Use the info indicator when you need to highlight general information. +- Use the error indicator when communicating a critical issue preventing the user from continuing or completing an action. +- Use the warning indicator to inform users of an issue or potential issue related to their current task. Use this for issues that don't prevent the user from continuing or completing their task. +- Use the success indicator to confirm that a user's action is successful. ### Import -To import Status Indicator from the core Salt package, use: +To import `StatusIndicator` from the core Salt package, use: ``` import { StatusIndicator } from "@salt-ds/core"; diff --git a/site/docs/components/stepped-tracker/accessibility.mdx b/site/docs/components/stepped-tracker/accessibility.mdx index 410d10f2b82..c3d732734d1 100644 --- a/site/docs/components/stepped-tracker/accessibility.mdx +++ b/site/docs/components/stepped-tracker/accessibility.mdx @@ -8,4 +8,4 @@ data: $ref: ./#/data --- -Stepped Tracker uses `aria-step` to indicate which is the current active step. +Stepped trackers use `aria-current="step"` to indicate the current active step. diff --git a/site/docs/components/stepped-tracker/examples.mdx b/site/docs/components/stepped-tracker/examples.mdx index 10056df24d6..8bbdc369b57 100644 --- a/site/docs/components/stepped-tracker/examples.mdx +++ b/site/docs/components/stepped-tracker/examples.mdx @@ -14,25 +14,25 @@ data: ### Basic - Stepped Tracker contains multiple `TrackerStep` child components. Each `TrackerStep` indicates its current status through its icon and color. In addition, the connectors indicate the current active step and the user’s progress through the process. + `SteppedTracker` contains multiple `TrackerStep` child components. Each `TrackerStep` indicates its current status through its icon and color. In addition, the connectors indicate the current active step and the user’s progress through the process. - A label can be added to the `TrackerStep` using the `StepLabel` component. + You can add a label to the `TrackerStep` using the `StepLabel` component. - ### Step Progression + ### Step progression - In normal circumstances, once a step is completed you should both advance the active step, and change the status of the current active step in unison. + In normal circumstances, once the user completes a step, you should advance the active step, and change the status of the current active step in unison. - ### Non-Sequential Progress + ### Nonsequential progress - It may not be appropriate in some circumstances, but it is possible to control the state of steps and the active step independently if users are able to revisit previous steps or complete steps non-sequentially. + It may not be appropriate in some circumstances, but it's possible to control the state of steps and the active step independently if users can revisit previous steps or complete steps nonsequentially. diff --git a/site/docs/components/stepped-tracker/index.mdx b/site/docs/components/stepped-tracker/index.mdx index b221a551ae0..0940d80c61d 100644 --- a/site/docs/components/stepped-tracker/index.mdx +++ b/site/docs/components/stepped-tracker/index.mdx @@ -1,19 +1,19 @@ --- -title: Stepped Tracker +title: Stepped tracker data: - description: Stepped Tracker visually communicates a user’s progress through a linear process. It gives the user context about where they are in the process, as well as an indication of remaining steps and the state of all steps. It can communicate new information, errors, warnings, or successful completion of a process or task. + description: "`SteppedTracker` visually communicates a user’s progress through a linear process. It gives the user context about where they are in the process, indicating the remaining steps and the state of all steps. It can communicate new information, errors, warnings or successful completion of a process or task." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/lab/src/stepped-tracker" package: name: "@salt-ds/lab" alsoKnownAs: [ + "Discrete progress indicator", + "Progress indicator", + "Progress stepper", + "Progress steps", + "Screen flow", + "Status tracker", "Stepper", - "Status Tracker", - "Progress Indicator", - "Progress Stepper", - "Discrete Progress Indicator", - "Progress Steps", - "Screen Flow", ] relatedComponents: [ @@ -21,7 +21,7 @@ data: { name: "Pagination", relationship: "similarTo" }, { name: "Progress", relationship: "similarTo" }, { name: "Icon", relationship: "contains" }, - { name: "Status Indicator", relationship: "contains" }, + { name: "Status indicator", relationship: "contains" }, ] # Leave this as is diff --git a/site/docs/components/stepped-tracker/usage.mdx b/site/docs/components/stepped-tracker/usage.mdx index 612fc918abb..ebd470078cc 100644 --- a/site/docs/components/stepped-tracker/usage.mdx +++ b/site/docs/components/stepped-tracker/usage.mdx @@ -8,25 +8,25 @@ data: $ref: ./#/data --- -### When to use Stepped Tracker +### Using the components -- When there are separate steps within a process, such as a wizard or a multi-step form. +#### When to use -- When you can break a process into distinct, bite-sized sections that are less daunting than lengthy forms. +- When there are separate steps within a process, such as a wizard or a multistep form. +- When you want to split a process into distinct, bite-sized sections that are less daunting than lengthy forms. -### When not to use Stepped Tracker +#### When not to use - When there are fewer than three steps in a process. - -- As navigation; the steps are not interactable. +- As navigation; users cannot interact with the steps. ### Content -Stepped Tracker labels never truncate, only wrap. Therefore, ensure they are short and self-explanatory. +Stepped tracker labels never truncate, only wrap. Therefore, ensure they're short and self-explanatory. ### Import -To import Stepped Tracker from the lab Salt package, use: +To import `SteppedTracker` and related components from the lab Salt package, use: ``` import { SteppedTracker, TrackerStep, StepLabel } from "@salt-ds/lab"; @@ -34,14 +34,14 @@ import { SteppedTracker, TrackerStep, StepLabel } from "@salt-ds/lab"; ### Props -#### Stepped Tracker +#### `SteppedTracker` -#### Tracker Step +#### `TrackerStep` -#### Step Label +#### `StepLabel` diff --git a/site/docs/components/switch/accessibility.mdx b/site/docs/components/switch/accessibility.mdx index 8341d5838d0..1819f708d42 100644 --- a/site/docs/components/switch/accessibility.mdx +++ b/site/docs/components/switch/accessibility.mdx @@ -9,31 +9,24 @@ data: $ref: ./#/data --- -### Best practices - -- On focus, the screen reader should: - - Identify the switch - - Read out the text - - Express the state - ### Keyboard interactions -- If focus is on the previous element in the tab order, move focus onto Switch. -- If focus is on Switch, moves focus to the next focusable element in the tab order. +- If focus is on the previous element in the tab order, Tab moves focus to the switch. +- If focus is on switch, Tab moves focus to the next focusable element in the tab order. -- Activate Switch to change state. +- Space activates switch to change between checked and unchecked state. -- If focus is on Switch, moves focus out of the component. Focus is set to the previous component in the tab order. -- If focus is below Switch, move focus to Switch. +- If focus is on the switch, this action moves focus out of the component and sets the focus to the previous component in the tab order. +- If focus is below the switch, this action moves focus to the switch. diff --git a/site/docs/components/switch/examples.mdx b/site/docs/components/switch/examples.mdx index c2325d336ab..49ac43b4fbf 100644 --- a/site/docs/components/switch/examples.mdx +++ b/site/docs/components/switch/examples.mdx @@ -16,10 +16,10 @@ data: By default, the switch thumb sits to the left side of the track and is in an unchecked state. -- The switch state can be set using the optional `defaultChecked` prop. -- The `onChange` event can be used to read the value using the second parameter. +- You can set the switch state using the optional `defaultChecked` prop. +- You can use the `onChange` event to read the value using the second parameter. -Guidance: +#### Best practices - Only use the `checked` prop for a controlled switch that requires some logic for validating value. - We recommend that you always use a text description for a switch. @@ -30,7 +30,7 @@ Guidance: ### Checked -When `defaultChecked={true}`, switch is in a `checked` state and the switch thumb sits to the right side of the track. +When `defaultChecked={true}`, switch is in a `checked` state, and the switch thumb sits to the right side of the track. @@ -38,11 +38,11 @@ When `defaultChecked={true}`, switch is in a `checked` state and the switch thum ### Disabled -You can set Switch to a disabled state. When `disabled`, it is not interactive or focusable. +You can set a switch to a disabled state. When `disabled`, it's not interactive or focusable. -Guidance: +#### Best practices -Use a disabled state for switches that have permissions, dependencies or pre-requisites. For example, a switch in a [Form](/salt/patterns/forms) may be disabled because the user has not yet completed an earlier section of the form. +Use a disabled state for switches that have permissions, dependencies or prerequisites. For example, you can disable a switch in a [form](/salt/patterns/forms) because the user hasn't yet completed an earlier section of the form. @@ -50,11 +50,11 @@ Use a disabled state for switches that have permissions, dependencies or pre-req ### Disabled checked -You can set a `checked` switch to a disabled state. When `disabled`, it is not interactive or focusable. This shows an option has been toggled to be “checked” but cannot be changed. +You can set a `checked` switch to a disabled state. When `disabled`, it's not interactive or focusable. This shows an option has been “checked” but the user cannot change it. -Guidance: +#### Best practices -Use a disabled checked state for switches that have permissions, dependencies or pre-requisites. For example, a switch in a [Form](/salt/patterns/forms) may be checked but disabled as the user does not have permissions to edit their selection during a later stage in a form. +Use a disabled checked state for switches that have permissions, dependencies or pre-requisites. For example, a switch in a [form](/salt/patterns/forms) may be in a checked state but disabled as the user doesn't have permissions to edit their selection during a later stage in a form. diff --git a/site/docs/components/switch/index.mdx b/site/docs/components/switch/index.mdx index 05ec3b8780c..eaa89303ba8 100644 --- a/site/docs/components/switch/index.mdx +++ b/site/docs/components/switch/index.mdx @@ -1,7 +1,7 @@ --- title: Switch data: - description: Switch is a binary control used to toggle between two different states. When interacted with, the thumb of the switch travels along the track to indicate state. Switch is used to control settings, preferences, or actions within an application or system. + description: "`Switch` is a binary control used to switch between two different states. When interacted with, the thumb of the switch travels along the track to indicate state. You can use a switch to control settings, preferences, or actions within an application or system." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # @@ -15,11 +15,11 @@ data: # Permitted values for relationship are: "similarTo" or # "contains". { name: "Icon", relationship: "contains" }, - { name: "Toggle Button", relationship: "similarTo" }, - { name: "Toggle Button Group", relationship: "similarTo" }, { name: "Checkbox", relationship: "similarTo" }, - { name: "Radio Button", relationship: "similarTo" }, { name: "Pill", relationship: "similarTo" }, + { name: "Radio button", relationship: "similarTo" }, + { name: "Toggle button", relationship: "similarTo" }, + { name: "Toggle button group", relationship: "similarTo" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/switch/usage.mdx b/site/docs/components/switch/usage.mdx index 6688246b891..0624694a81e 100644 --- a/site/docs/components/switch/usage.mdx +++ b/site/docs/components/switch/usage.mdx @@ -9,25 +9,25 @@ data: $ref: ./#/data --- -### Using the Switch component +### Using the component -#### When to use Switch +#### When to use -- To present an instantaneous, binary choice between two options that doesn’t require the action to be submitted or confirmed. The corresponding action takes effect immediately. -- To control a critical action that may require confirmation from the user before applying the action. This delay is usually intentional, ensuring that users do not accidentally make unwanted changes. +- To present an instantaneous, binary choice between two options that doesn’t require the user to submit or confirm the action. The corresponding action takes effect immediately. +- To control a critical action that may require confirmation from the user before applying it. This delay is usually intentional, ensuring that users don't accidentally make unwanted changes. -#### When not to use Switch +#### When not to use -- To present a list of independent options where the user can select any number of choices. Instead, use [Checkbox](../checkbox). -- To make a single selection between mutually exclusive choices between two or more options. Instead, use [Radio Button](../radio-button). -- To toggle between two (or more) opposing yet mutually exclusive states or options with visual priority. Instead, use [Toggle Button](../toggle-button). -- To present multiple options in a group within a compact UI, or if they’re subject to change depending on context. Instead, use [Selectable Pill](../pill). +- To present a list of independent options where the user can select any number of choices. Instead, use [`Checkbox`](../checkbox). +- To make a single selection between mutually exclusive choices between two or more options. Instead, use [`RadioButton`](../radio-button). +- To toggle between two (or more) opposing yet mutually exclusive states or options with visual priority. Instead, use [`ToggleButton`](../toggle-button). +- To present multiple options in a group within a compact UI, or if they’re subject to change depending on context. Instead, use selectable [`Pill`](../pill). ### Import {/* Update the text and code snippet below as needed: */} -To import Switch from the core Salt package, use: +To import `Switch` from the core Salt package, use: ```js import { Switch } from "@salt-ds/core"; @@ -35,7 +35,7 @@ import { Switch } from "@salt-ds/core"; ### Content -- The option that that switch controls should be made clear in the text inline to the switch. +- You should clarify the option that switch controls in the text inline to the switch. - Text should always sit to the right of the switch. - Keep the text description as clear and concise as possible, and ensure it accurately describes the action the switch will perform upon interaction. diff --git a/site/docs/components/tabs/accessibility.mdx b/site/docs/components/tabs/accessibility.mdx index 94473330c11..da7ca3b1435 100644 --- a/site/docs/components/tabs/accessibility.mdx +++ b/site/docs/components/tabs/accessibility.mdx @@ -8,39 +8,40 @@ data: $ref: ./#/data --- -Any focusable elements included in the Tab content will need to be checked and tested accordingly. +### Best practices + +Any focusable elements included in the tab content will need to be checked and tested accordingly. ### Keyboard interactions -- If focus is on outside of tabs, enters focus into tabs. -- If focus is on a tab item, exits the tab component and place focus onto the next element within the tabbing order. +- If focus is on outside of tabs, Tab enters focus into tabs. +- If focus is on a tab item, Tab exits the tab component and place focus onto the next element within the tabbing order. - - If focus is inside a tab component, moves focus to the previous element in - the tabbing order. + - If focus is inside a tab component, this action moves focus to the previous + element in the tabbing order. - - - If focus is on tab hover state, selects a tab item. + + - If focus is on tab hover state, this action selects a tab item. - - - Moves focus between tab items in tab bar. + + - This action moves focus between tab items in tab bar. - - - Moves focus between tab items in an overflow menu list. + + - This action moves focus between tab items in an overflow menu list. - - If focus is on a tab, moves focus to the first tab. + - If focus is on a tab, Home moves focus to the first tab. - - If focus is on a tab, moves focus to the last tab. +- If focus is on a tab, End moves focus to the last tab. - diff --git a/site/docs/components/tabs/index.mdx b/site/docs/components/tabs/index.mdx index 328c6ca1aac..bad937b4269 100644 --- a/site/docs/components/tabs/index.mdx +++ b/site/docs/components/tabs/index.mdx @@ -1,9 +1,7 @@ --- title: Tabs data: - description: - Tabs switch between different but related content. Users can move between different views without the need to leave the current page. - A tabstrip comprises a minimum of two tabs, with one tab actively engaged at any given moment. The active tab is differentiated from an inactive tab by a colored indicator either on the top or bottom edge of the tab, depending on the variant in use. These tabstrips can expand the full width of the page or be used within content areas, or within components such as dialogs, cards, and drawers. + description: "`TabNext` and `TabstripNext` switch between different but related content. Users can move between different views without the need to leave the current page. A tabstrip comprises a minimum of two tabs, with one tab actively engaged at any given moment. The active tab is differentiated from an inactive tab by a colored indicator either on the top or bottom edge of the tab, depending on the variant in use. These tabstrips can expand the full width of the page or be used within content areas, or within components such as dialogs, cards, and drawers." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/lab/src/tabs-next/TabNext.tsx" package: name: "@salt-ds/lab" diff --git a/site/docs/components/tabs/usage.mdx b/site/docs/components/tabs/usage.mdx index c733032afb5..d0bfde70a9c 100644 --- a/site/docs/components/tabs/usage.mdx +++ b/site/docs/components/tabs/usage.mdx @@ -8,14 +8,14 @@ data: $ref: ./#/data --- -### Using the Tabs component +### Using the components -#### When to use Tabs +#### When to use - Use tabs to organize logically related but mutually exclusive content on a single page. - Use tabstrips to prevent users from navigating to another page to complete a task. -#### When not to use Tabs +#### When not to use - Don’t use tabstrips when users need to compare information between views. - Don’t use tabstrips to communicate progress. Instead, use [`Stepped Tracker`](/salt/components/stepped-tracker). @@ -32,7 +32,7 @@ data: ### Import -To import Tabs from the lab Salt package, use: +To import `TabNext` and `TapstripNext` from the lab Salt package, use: ```js import { TabNext, TabstripNext } from "@salt-ds/lab"; @@ -40,10 +40,10 @@ import { TabNext, TabstripNext } from "@salt-ds/lab"; ### Props -#### TabNext +#### `TabNext` -#### TabstripNext +#### `TabstripNext` diff --git a/site/docs/components/text/accessibility.mdx b/site/docs/components/text/accessibility.mdx index 7c03180c045..bf3638a9c31 100644 --- a/site/docs/components/text/accessibility.mdx +++ b/site/docs/components/text/accessibility.mdx @@ -8,8 +8,10 @@ data: $ref: ./#/data --- -We are letting you decide on the user experience you would like to implement for text. However, you need to remain ADA compliant and provide the correct visual and auditory experience for text truncation. Truncated text must comply to [WCAG SC 1.4.4](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html). +### Best practices -The requirement states any visually rendered text must be accessible and displayed in full. You must ensure that users can view truncated strings in full if they want to. Consider using tooltips as a mechanism for expanding the text, or a link to open the full content on a new page. +We're letting you decide on the user experience you'd like to implement for text. However, you need to remain ADA compliant and provide the correct visual and auditory experience for text truncation. Truncated text must comply with [WCAG SC 1.4.4](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html). + +The requirement states you must make any visually rendered text accessible and display it in full. You must ensure that users can view truncated strings in full if they wish. Consider using tooltips as a mechanism for expanding the text or a link to open the full content on a new page. If you use truncated text, you must ensure that a screen reader can read the full value. diff --git a/site/docs/components/text/examples.mdx b/site/docs/components/text/examples.mdx index 95b4fdce947..e59e6308330 100644 --- a/site/docs/components/text/examples.mdx +++ b/site/docs/components/text/examples.mdx @@ -14,25 +14,25 @@ data: ### Styles -The Text component supports these sets of styles: +`Text` supports these sets of styles: - Display - Headings - Body - Label -These alternative components display text in commonly used styles. Where relevant, use them instead of Text to simplify syntax: +These alternative components display text in commonly used styles. Where relevant, use them instead of `Text` to simplify syntax: -- Display1 -- Display2 -- Display3 -- H1 -- H2 -- H3 -- H4 -- Label -- TextNotation -- TextAction +- `Display1` +- `Display2` +- `Display3` +- `H1` +- `H2` +- `H3` +- `H4` +- `Label` +- `TextNotation` +- `TextAction` @@ -40,11 +40,11 @@ These alternative components display text in commonly used styles. Where relevan ### Truncation -The component wraps by default, but you can use the `maxRows` prop to force truncation. Truncation will occur when `maxRows` is greater than 0. If a value is not provided, the text content will wrap. +The component wraps by default, but you can use the `maxRows` prop to force truncation. Truncation will occur when `maxRows` is greater than 0. If you don't provide a value, the text content will wrap. -#### Guidance +#### Best practices -Truncated text must comply to WCAG SC 1.4.4. If you use truncated text, you must ensure that a screen reader can read the full value. Read the Accessibility section for further guidance. +Truncated text must comply with [WCAG SC 1.4.4](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html). If you use truncated text, you must ensure that a screen reader can read the full value. Read the Accessibility section for further guidance. @@ -52,9 +52,9 @@ Truncated text must comply to WCAG SC 1.4.4. If you use truncated text, you must ### Styling -Although we do not encourage it, you may find it necessary to need to change an element’s mapped styling to another from our typography set. In this case you would use the `styleAs` prop. +Although we don't encourage it, you may find it necessary to change an element’s mapped styling to another from our typography set. In this case, you'd use the `styleAs` prop. -Using the `styleAs` prop you can maintain the correct HTML hierarchy as well as the appropriate visual priority. You can style headings to visually appear as different heading levels, irrespective of the underlying DOM element of a heading on the page. +Using the `styleAs` prop, you can maintain the correct HTML hierarchy and the appropriate visual priority. You can style headings to visually appear as different heading levels, irrespective of the underlying DOM element of a heading on the page. @@ -62,7 +62,7 @@ Using the `styleAs` prop you can maintain the correct HTML hierarchy as well as ### Variant -Use the `variant` prop to adjust the foreground color of any nested text. Use the `primary` variant most of the time, and the `secondary` variant for supporting text or to create visual hierarchy. +Use the `variant` prop to adjust the foreground color of any nested text. Use the `primary` variant most often, and the `secondary` variant for supporting text or creating a visual hierarchy. Read our [guidance on how to use text color](/salt/foundations/typography#color). diff --git a/site/docs/components/text/index.mdx b/site/docs/components/text/index.mdx index 579798fbc4b..53ea86af245 100644 --- a/site/docs/components/text/index.mdx +++ b/site/docs/components/text/index.mdx @@ -1,7 +1,7 @@ --- title: Text data: - description: Text is a component that makes it easy to use our typography styles throughout a product or application, ensuring consistency and a unified look and feel. It includes attributes such as font size, weight, letter spacing, line height and decoration. + description: "`Text` is a component that makes it easy to use our typography styles throughout a product or application, ensuring consistency and a unified look and feel. It includes attributes such as font size, weight, letter spacing, line height and decoration." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/core/src/text" package: name: "@salt-ds/core" diff --git a/site/docs/components/text/usage.mdx b/site/docs/components/text/usage.mdx index 2b2df5bb431..26e0e99b693 100644 --- a/site/docs/components/text/usage.mdx +++ b/site/docs/components/text/usage.mdx @@ -8,11 +8,11 @@ data: $ref: ./#/data --- -Read more on our [Typography Foundation](/salt/foundations/typography) page. +Read more on our [typography foundation](/salt/foundations/typography) page. ### Import -To import Text from the core Salt package, use: +To import `Text` and related components from the core Salt package, use: ```js import { diff --git a/site/docs/components/toast/accessibility.mdx b/site/docs/components/toast/accessibility.mdx index 4493604d748..1ed337dc218 100644 --- a/site/docs/components/toast/accessibility.mdx +++ b/site/docs/components/toast/accessibility.mdx @@ -8,14 +8,16 @@ data: $ref: ./#/data --- -Any focusable elements included in the Toast content will need to be checked and tested accordingly. +### Best practices + +You'll need to check and test any focusable elements included in the toast content accordingly. ### Keyboard interactions - + -Use `Tab` or `Tab + Shift` keys to navigate through the interactive elements added within the Toast. +Use this action to navigate through the interactive elements within the toast. diff --git a/site/docs/components/toast/examples.mdx b/site/docs/components/toast/examples.mdx index 4611bb456ba..98b4acee320 100644 --- a/site/docs/components/toast/examples.mdx +++ b/site/docs/components/toast/examples.mdx @@ -12,53 +12,53 @@ data: - ### Info Toast + ### Info toast - Use the info Toast notification when you need to display general information. An info icon displays alongside a title and supporting message. + Use the info toast notification when you need to display general information. An info icon displays alongside a title and supporting message. - ### Error Toast + ### Error toast - Use the error Toast notification to communicate a critical issue. An error icon displays alongside a title and supporting message. + Use the error toast notification to communicate a critical issue. An error icon displays alongside a title and supporting message. - ### Warning Toast + ### Warning toast - Use the warning Toast notification to inform users of an issue or potential issue. A warning icon displays alongside a title and supporting message. + Use the warning toast notification to inform users of an issue or potential issue. A warning icon displays alongside a title and supporting message. - ### Success Toast + ### Success toast - Use the success Toast notification to communicate that an action has been completed successfully. A success icon displays alongside a title and supporting message. + Use the success toast notification to communicate the successful completion of an action. A success icon displays alongside a title and supporting message. - ### Toast Group positioned top-right + ### Toast group positioned top-right - Toast Group is a wrapper container for multiple Toasts. + `ToastGroup` is a wrapper container for multiple toasts. - Use `ToastGroup` component to position stacked toasts. + Use `ToastGroup` to position stacked toasts. - ### Toast Group positioned bottom-right + ### Toast group positioned bottom-right - Toast Group is a wrapper container for multiple Toasts. + `ToastGroup` is a wrapper container for multiple Toasts. - Use `ToastGroup` component to position stacked toasts. + Use `ToastGroup` to position stacked toasts. diff --git a/site/docs/components/toast/index.mdx b/site/docs/components/toast/index.mdx index c500523b1fd..2c5aead72fe 100644 --- a/site/docs/components/toast/index.mdx +++ b/site/docs/components/toast/index.mdx @@ -1,7 +1,7 @@ --- title: Toast data: - description: Toast displays a small pop-up notification that provides short feedback and is displayed in response to a user action or system event that relates to a workflow or application outside the user’s current focus. It can communicate new information, errors, warnings, or successful completion of a process or task. + description: "`Toast` displays a small pop-up notification that provides short feedback in response to a user action or system event related to a workflow or application outside the user’s current focus. It can communicate new information, errors, warnings or successful completion of a process or task." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/toast" package: name: "@salt-ds/core" @@ -10,7 +10,7 @@ data: relatedComponents: [ { name: "Banner", relationship: "similarTo" }, - { name: "Content Status", relationship: "similarTo" }, + { name: "Content status", relationship: "similarTo" }, { name: "Dialog", relationship: "similarTo" }, { name: "Button", relationship: "contains" }, { name: "Icon", relationship: "contains" }, diff --git a/site/docs/components/toast/usage.mdx b/site/docs/components/toast/usage.mdx index bf6aed21f5b..479990ff0e0 100644 --- a/site/docs/components/toast/usage.mdx +++ b/site/docs/components/toast/usage.mdx @@ -8,49 +8,43 @@ data: $ref: ./#/data --- -### Positioning +### Using the components -Position Toast where it won’t interfere with navigation or important content in the user interface, for example in the lower right corner of the screen or application viewport. +#### Positioning -### Stacking +Position the toast where it won’t interfere with navigation or important content in the user interface, for example, in the lower-right corner of the screen or application viewport. -Stack toasts in chronological order if multiple toasts need to appear on screen at the same time. - -When toasts are stacked from the top, the newest one should be on top. When they’re stacked from the bottom, the newest toast should be at the bottom. - -### When to use Toast +#### Stacking -- To notify users of an event that’s occurred in a peripheral application or workflow. A toast should be noticeable without disrupting the user’s experience or requiring immediate action. - -- To communicate low priority information caused by events. Toasts usually don’t require feedback from the user. +Stack toasts in chronological order if multiple toasts need to appear on screen at the same time. -- To communicate information from a workflow external to the user’s current task or view. Toasts are located in an unintrusive location on an interface. +When you stack toasts from the top, the newest one should be first. When you stack them from the bottom, the newest toast should be at the bottom. -- To show system generated alerts, independent of the user’s actions. These toasts are persistent and must allow the user to either take action or dismiss it. Toasts can contain customizable content such as actionable buttons. +#### When to use -### When not to use Toast +- To notify users of an event that’s occurred in a peripheral application or workflow. The user should notice the toasts without disrupting their experience or requiring immediate action. -- To show a notification that applies to the user’s current task. Instead, use Banner. Banner sits either on the top of a page or component, or inline, and usually addresses issues inside the user’s current content area. +- To communicate low-priority information caused by events. Toasts usually don’t require feedback from the user. -- When the notification requires immediate action and is related to the user’s current task. Instead, use Dialog to interrupt the user's workflow. +- To communicate information from a workflow external to the user’s current task or view. Toasts are in an unintrusive location on an interface. -### Content +- To show system-generated alerts, independent of the user’s actions. These toasts are persistent and must allow the user to either take action or dismiss them. Toasts can contain customizable content, such as actionable buttons. -A Toast notification is typically limited in space, so content should be clear, concise, and short, allowing users to quickly scan the notification and understand the situation and/or next steps. +#### When not to use -Titles should be configured to display the Body Strong typography style and the messaging Body Default typography style, across densities. +- To show a notification that applies to the user’s current task. Instead, use [`Banner`](../banner). `Banner` sits either on the top of a page or component or inline and usually addresses issues inside the user’s current content area. -In addition to text content, Toast can contain any UI elements, such as actionable components, like Buttons. This allows the user to act on the message without interrupting their current workflow. For example, users can approve or respond to an update without opening a new window. Users should always be able to close or dismiss a Toast. +- When the notification requires immediate action and relates to the user’s current task. Instead, use [`Dialog`](../dialog) to interrupt the user's workflow. ### Import -To import Toast from the core Salt package, use: +To import `Toast` and `ToastContent` from the core Salt package, use: ```js import { Toast, ToastContent } from "@salt-ds/core"; ``` -To import ToastGroup from the lab Salt package, use: +To import `ToastGroup` from the lab Salt package, use: ```js import { ToastGroup } from "@salt-ds/lab"; @@ -58,14 +52,22 @@ import { ToastGroup } from "@salt-ds/lab"; ### Props -#### Toast +#### `Toast` -#### Toast Group +#### `ToastGroup` -#### Toast Content +#### `ToastContent` + +### Content + +A toast notification is typically limited in space, so content should be clear, concise, and short, allowing users to quickly scan the notification and understand the situation and/or next steps. + +You should configure titles to display the Body Strong typography style and the messaging Body Default typography style across densities. + +In addition to text content, toasts can contain any UI elements such as actionable components, like buttons. This allows the user to act on the message without interrupting their current workflow. For example, users can approve or respond to an update without opening a new window. Users should always be able to close or dismiss a toast. diff --git a/site/docs/components/toggle-button/accessibility.mdx b/site/docs/components/toggle-button/accessibility.mdx index 26cdc31b489..984c97b2351 100644 --- a/site/docs/components/toggle-button/accessibility.mdx +++ b/site/docs/components/toggle-button/accessibility.mdx @@ -11,41 +11,44 @@ data: ### Best practices -- On focus, the screen reader should: - - Identify the toggle button - - Read out the text - - Expresses the state - - Read the position of the option within the total number of buttons available +On focus, the screen reader should: + +- Identify the toggle button. +- Read out the text. +- Expresses the state. +- Read the position of the option within the total number of buttons available. + +### Keyboard interactions -- Moves focus into the toggle button group. Focus is set to the active button. -- If focus is inside the toggle button group, moves focus out of the toggle button group. Focus is set to the next component in the tab order. +- Tab moves focus into the toggle button group. Focus is set to the active button. +- If focus is inside the toggle button group, Tab moves focus out of the toggle button group. Focus is set to the next component in the tab order. -- When focus is on the toggle button and the button is inactive, it activates the button. -- If focus is on an active button, the button remains active. +- When focus is on the toggle button and the button is inactive, this action activates the button. +- If focus is on an active button, this actions keeps the button active. -- If focus is inside the toggle button group, moves focus out of the component. Focus is set to the previous component in the tab order. -- If focus is below the toggle button group, move focus into the toggle button group. Focus is set to the active button. +- If focus is inside the toggle button group, this action moves focus out of the component. Focus is set to the previous component in the tab order. +- If focus is below the toggle button group, this action move focus into the toggle button group. Focus is set to the active button. - + -- Moves focus to the next toggle button in the toggle button group. -- If focus is on the last toggle button, wrap focus to the first toggle button. +- This action moves focus to the next toggle button in the toggle button group. +- If focus is on the last toggle button, this action wraps focus to the first toggle button. - + -- Moves focus to the previous toggle button in the toggle button group. -- If focus is on the first toggle button, wrap focus to the last toggle button. +- This action moves focus to the previous toggle button in the toggle button group. +- If focus is on the first toggle button, this action wraps focus to the last toggle button. diff --git a/site/docs/components/toggle-button/examples.mdx b/site/docs/components/toggle-button/examples.mdx index 862044626a9..6d2a7bef0bb 100644 --- a/site/docs/components/toggle-button/examples.mdx +++ b/site/docs/components/toggle-button/examples.mdx @@ -12,15 +12,15 @@ data: -### Toggle Button +### Toggle button -The basic toggle button component allows users to switch between two states. +The basic `ToggleButton` allows users to switch between two states. -Use icons and text in toggle buttons if it's important to visually reinforce the theme of the options. Or if providing additional context may help decision-making (for example, selecting a document type or a text style). +Use icons and text in toggle buttons if it's important to visually reinforce the theme of the options or if providing additional context may help decision making (for example, selecting a document type or a text style). -Pass `aria-hidden={true}` to the icon so its text description is not announced by the screen reader. +Pass `aria-hidden={true}` to the icon so the screen reader doesn't announce its text description. -Guidance: +#### Best practices - To reduce visual noise and mitigate alignment issues, use icons in toggle button labels consistently across all options in a toggle button group. - Icons are placed to the left of the text only to describe the button. @@ -29,11 +29,11 @@ Guidance: -### Toggle Button Group +### Toggle button group -Toggle Button Group allows users to make a mutually exclusive selection from a set of related commands—with only one option selected at a time. +`ToggleButtonGroup` allows users to make a mutually exclusive selection from a set of related commands—with only one option selected at a time. -Guidance: +#### Best practices - A toggle button group should always contain two or more options related by function or context. Examples include text alignment (left, center, right) or speed selection (slow, medium, fast). - Use text description in addition to or instead of an icon if the options in the toggle button group are high priority. Users will be less likely to overlook the options. @@ -44,13 +44,13 @@ Guidance: ### Icon only -Toggle buttons can be used with icons only. +You can use toggle buttons with icons only. -Guidance: +#### Best practices -- An icon only toggle button should be self-explanatory, ideally using well known symbols. If the purpose of the button isn’t clear from the icon along, add a label. -- An accessible label should be provided for each toggle button. -- A [Tooltip](../tooltip) should be used to provide additional context for each toggle button. +- An icon-only toggle 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 label. +- You should provide an accessible label for each toggle button. +- Use [`Tooltip`](../tooltip) to provide additional context for each toggle button. @@ -58,7 +58,7 @@ Guidance: ### Text only -You can configure toggle buttons to display text only if you can’t identify a suitable or intuitive icon. +You can configure toggle buttons to only display text if you can’t identify a suitable or intuitive icon. @@ -66,15 +66,15 @@ You can configure toggle buttons to display text only if you can’t identify a ### Disabled -Toggle buttons can be disabled if required by context or user permissions. Disabling a toggle button will suppress all functionality. +You can disable toggle buttons if required by context or user permissions. Disabling a toggle button will suppress all functionality. -### Toggle Button Group Orientation +### Toggle button group orientation -By default, a toggle button group is aligned horizontally. If the options are better presented in a stacked layout, orientate the group vertically using the `orientation=”vertical”` prop. +By default, a toggle button group has horizontal alignment. If you can present the options in a stacked layout, orientate the group vertically using the `orientation=”vertical”` prop. diff --git a/site/docs/components/toggle-button/index.mdx b/site/docs/components/toggle-button/index.mdx index 0d2b5947364..afbf07776b0 100644 --- a/site/docs/components/toggle-button/index.mdx +++ b/site/docs/components/toggle-button/index.mdx @@ -1,7 +1,7 @@ --- -title: Toggle Button +title: Toggle button data: - description: Toggle Button is a two-state button that the user can toggle. The corresponding action takes effect immediately. With Toggle Button Group, users can make a mutually exclusive selection from a set of related commands—with only one option selected at a time. + description: "`ToggleButton` is a two-state button that the user can turn on or off. The corresponding action takes effect immediately. With `ToggleButtonGroup`, users can make a mutually exclusive selection from a set of related commands—with only one option selected at a time." # Fill in the info from the content template's "Metadata" table below. # To omit optional items, comment them out with # @@ -9,15 +9,15 @@ data: package: name: "@salt-ds/core" alsoKnownAs: - ["Button Group", "Toggle Button Group", "Toggle Group", "Segmented control"] + ["Button group", "Toggle button group", "Toggle group", "Segmented control"] relatedComponents: [ # Add a { name: "...", relationship: "..." } block for each # related component here (separated by commas). # Permitted values for relationship are: "similarTo" or # "contains". { name: "Checkbox", relationship: "similarTo" }, + { name: "Radio button", relationship: "similarTo" }, { name: "Switch", relationship: "similarTo" }, - { name: "Radio Button", relationship: "similarTo" }, ] # stickerSheet: "https://figma.com/..." diff --git a/site/docs/components/toggle-button/usage.mdx b/site/docs/components/toggle-button/usage.mdx index 1617f9c9c3e..9fd983d38fc 100644 --- a/site/docs/components/toggle-button/usage.mdx +++ b/site/docs/components/toggle-button/usage.mdx @@ -9,25 +9,25 @@ data: $ref: ./#/data --- -### Using the Toggle Button component +### Using the components -#### When to use Toggle Button +#### When to use - To make a single selection when switching between opposing yet mutually exclusive options. -- To visually prioritize options higher than [Radio Button](../radio-button) or [Switch](../switch). +- To visually prioritize options higher than [`RadioButton`](../radio-button) or [`Switch`](../switch). -#### When not to use Toggle Button +#### When not to use -- To present an instantaneous or binary choice between two options. Instead, use [Switch](../switch) -- When the options in the group are not high priority and high affordance is not required. Instead, use [Radio Button Group](../radio-button). -- When all options in the group don’t need to be visible at once, consider using [Dropdown](../dropdown). -- To present options in a Toggle Button Group within a compact UI, or they’re subject to change depending on context. Instead, use [Selectable Pill](../pill). +- To present an instantaneous or binary choice between two options. Instead, use [`Switch`](../switch). +- When the options in the group are not high priority and high affordance is not necessary. Instead, use [`RadioButtonGroup`](../radio-button). +- When all options in the group don’t need to be visible at once. Consider using [`Dropdown`](../dropdown). +- To present options in a toggle button group within a compact UI, or if they’re subject to change depending on context. Instead, use [`Pill`](../pill). ### Import {/* Update the text and code snippet below as needed: */} -To import Toggle Button and Toggle Button Group from the core Salt package, use: +To import `ToggleButton` and `ToggleButtonGroup` from the core Salt package, use: ```js import { ToggleButton, ToggleButtonGroup } from "@salt-ds/core"; @@ -38,11 +38,11 @@ import { ToggleButton, ToggleButtonGroup } from "@salt-ds/core"; {/* Update packageName and componentName below as needed */} {/* packageName is optional and defaults to "core" if omitted */} -#### Toggle Button +#### `ToggleButton` -#### Toggle Button Group +#### `ToggleButtonGroup` @@ -54,4 +54,4 @@ import { ToggleButton, ToggleButtonGroup } from "@salt-ds/core"; ### References -- Button Pattern (https://www.w3.org/WAI/ARIA/apg/patterns/button/) W3C +- [Button Pattern W3C](https://www.w3.org/WAI/ARIA/apg/patterns/button/) diff --git a/site/docs/components/tooltip/accessibility.mdx b/site/docs/components/tooltip/accessibility.mdx index 2342f0da995..6949f3b700c 100644 --- a/site/docs/components/tooltip/accessibility.mdx +++ b/site/docs/components/tooltip/accessibility.mdx @@ -9,6 +9,6 @@ data: $ref: ./#/data --- -The Tooltip does not receive focus, so we recommend that you do not include interactive elements as they will not be accessible. +### Best practices -If you need to display focusable content such as buttons or links, consider using [Overlay](../overlay) instead. +The tooltip doesn't receive focus, so we recommend that you don't include interactive elements as the user can't access them. diff --git a/site/docs/components/tooltip/examples.mdx b/site/docs/components/tooltip/examples.mdx index 256baf01927..a4073d7d3a4 100644 --- a/site/docs/components/tooltip/examples.mdx +++ b/site/docs/components/tooltip/examples.mdx @@ -13,9 +13,9 @@ data: - ### Default Tooltip + ### Default tooltip - By default, Tooltip displays a status icon alongside a supporting message and an arrow pointing to the relevant UI element. Its default placement is ‘right’ and appears after 300 milliseconds. + By default, `Tooltip` displays a status icon alongside a supporting message and an arrow pointing to the relevant UI element. Its default placement is "right," and appears after 300 milliseconds. @@ -23,31 +23,31 @@ data: ### Status - Use the `status` prop to define Tooltip’s icon and border color. You can choose between the following statuses: + Use the `status` prop to define the tooltip’s icon and border color. You can choose between the following statuses: - **Info**: Use this status when you need to display general information. - - **Error**: Use this status to communicate a critical issue that prevents the user from continuing. + - **Error**: Use this status to communicate a critical issue preventing the user from continuing. - - **Warning**: Use this status to inform users of an issue or potential issue related to their current task. Use this for issues that do not prevent the user from continuing or completing their task. + - **Warning**: Use this status to inform users of an issue or potential issue related to their current task. Use this for issues that don't prevent the user from continuing or completing their task. - - **Success**: Use this status to confirm that a user's action has been completed successfully. + - **Success**: Use this status to confirm the successful completion of a user's action. - ### Hide Arrow + ### Hide arrow - Use the `hideArrow` prop if you would like to display the Tooltip without the arrow. + Use the `hideArrow` prop to display the tooltip without the arrow. - ### Hide Icon + ### Hide icon - Use the `hideIcon` prop to display the Tooltip with text only, and no status icon. + Use the `hideIcon` prop to display the tooltip with text only and no status icon. @@ -55,7 +55,7 @@ data: ### Content - Use the `content` prop to pass either a simple string or a React component that is displayed inside the Tooltip. + Use the `content` prop to pass a simple string or a React component displayed inside the tooltip. @@ -63,15 +63,15 @@ data: ### Placement - Use the `placement` prop to position the Tooltip on its targeted UI element. + Use the `placement` prop to position the tooltip on its targeted UI element. - ### Delay Options + ### Delay options - Use the `enterDelay` or `leaveDelay` props to change the milliseconds before the Tooltip appears or disappears. + Use the `enterDelay` or `leaveDelay` props to change the milliseconds before the tooltip appears or disappears. diff --git a/site/docs/components/tooltip/index.mdx b/site/docs/components/tooltip/index.mdx index 112b31e1072..385354aea7f 100644 --- a/site/docs/components/tooltip/index.mdx +++ b/site/docs/components/tooltip/index.mdx @@ -1,7 +1,7 @@ --- title: Tooltip data: - description: Tooltip displays a brief message to the user that provides additional information about a UI element. The Tooltip appears after the user’s mouse pointer hovers over the target element for a certain amount of time. It can communicate new information, errors, warnings, or successful completion of a process or task. + description: "`Tooltip` displays a brief message to the user that provides additional information about a UI element. The tooltip appears after the user’s mouse pointer hovers over the target element for a certain time. It can communicate new information, errors, warnings or successful completion of a process or task." sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/core/src/tooltip" package: name: "@salt-ds/core" @@ -9,10 +9,10 @@ data: relatedComponents: [ { name: "Banner", relationship: "similarTo" }, + { name: "Content status", relationship: "similarTo" }, { name: "Overlay", relationship: "similarTo" }, - { name: "Content Status", relationship: "similarTo" }, { name: "Icon", relationship: "contains" }, - { name: "Status Indicator", relationship: "contains" }, + { name: "Status indicator", relationship: "contains" }, ] # stickerSheet: "" diff --git a/site/docs/components/tooltip/usage.mdx b/site/docs/components/tooltip/usage.mdx index a24e26f4ebf..d62b6da55eb 100644 --- a/site/docs/components/tooltip/usage.mdx +++ b/site/docs/components/tooltip/usage.mdx @@ -9,26 +9,30 @@ data: $ref: ./#/data --- -### When to use Tooltip +### Using the component + +#### When to use - When you want to display a brief message to the user that provides additional information about a UI element. -### When not to use Tooltip +### When not to use -- When the content contains interactive elements, like a link, input, or button. Consider always making this content visible or use an [Overlay](../overlay) or a [Dialog](../dialog) instead. +- When the content contains interactive elements, such as a link, input or button. Consider always making this content visible or using [`Overlay`](../overlay) or [`Dialog`](../dialog) instead. -- When there is information that the user needs to know to complete a task. Important help text should always be visible and not hidden from the user. +- When there's information that the user needs to know to complete a task. Important help text should always be visible to the user. - When the message always needs to be visible. Instead, place the message directly on the page. -- When the message is not about a UI element. Consider adding the message directly on the page or use an [Overlay](../overlay), a [Dialog](../dialog), or a [Banner](../banner) instead. +- When the message isn't about a UI element. Consider adding the message directly on the page or using [`Overlay`](../overlay), [`Dialog`](../dialog), or [`Banner`](../banner) instead. ### Content -The Tooltip content will never truncate. It should be short and self-explanatory. If a longer message is needed, consider adding it to the page so it is always visible. +Tooltip content will never truncate. It should be short and self-explanatory. If a longer message is necessary, consider adding it to the page so it's always visible. ### Import +To import `Tooltip` from the core Salt package, use: + ```js import { Tooltip } from "@salt-ds/core"; ```