Salt Design System

https://www.saltdesignsystem.com
Admin
Salt is J.P. Morgan's open-source design system, providing accessible components and extensive...
Tokens:4,759
Snippets:23
Trust Score:7.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Salt Design System Packages with npm

Source: https://www.saltdesignsystem.com/getting-started/developing

This command installs the core, theme, and icons packages required for Salt Design System components in a React project.

```npm
npm install @salt-ds/core @salt-ds/theme @salt-ds/icons
```

--------------------------------

### Install Fontsource Packages for Salt Design System

Source: https://www.saltdesignsystem.com/getting-started/developing

Install the necessary Fontsource npm packages to self-host Open Sans and PT Mono web fonts required by Salt's default theme.

```npm
npm install @fontsource/open-sans @fontsource/pt-mono
```

--------------------------------

### Salt DS Figma Libraries Reference

Source: https://www.saltdesignsystem.com/getting-started/designing

A comprehensive reference of the Salt Design System Figma libraries, detailing their contents and intended use for designers.

```APIDOC
Salt DS Libraries:
  - Salt DS Components and Patterns:
      Description: This library includes all Salt DS components and patterns that are represented in code and are documented on the site. To use Salt components and patterns directly, please install this library.
  - Salt DS Themes:
      Description: This library includes all typography and effect styles as well as all color, size, and spacing variables needed for the themes available within the components and patterns library. All variables are reflective of the design tokens in code.
  - Salt DS Assets:
      Description: This library offers Salt icons and country symbols.
  - Salt DS JPM Brand Colors:
      Description: This library provides variables for each foundational color needed for the Salt DS JPM Brand theme.
  - Salt DS Legacy (UITK) Colors:
      Description: This library provides variables for each foundational color needed for the Salt DS Legacy (UITK) theme.
  - Salt DS Logos:
      Description: This library contains logo variations, including J.P. Morgan, Chase, and dual brand logos. This library is for internal JPMC use only.
```

--------------------------------

### Salt Design System Header Spacing Guidelines

Source: https://www.saltdesignsystem.com/foundations/spacing

Specifies the recommended `--salt-spacing-XXX` tokens to apply above and below heading elements (H1-H4) to establish visual hierarchy and rhythm.

```APIDOC
Heading | Space above | Space below
--- | --- | ---
H1 | --salt-spacing-200 | --salt-spacing-300
H2 | --salt-spacing-200 | --salt-spacing-200
H3 | --salt-spacing-200 | --salt-spacing-100
H4 | --salt-spacing-200 | None
```

--------------------------------

### Salt Design System Responsive Web Breakpoint Specifications

Source: https://www.saltdesignsystem.com/foundations/responsiveness/small-viewports

Details the recommended breakpoints for responsive web design within the Salt Design System, including device types, pixel widths, column counts, spacing, fixed grid width, and density for each breakpoint. It also notes the relevance of Touch Density for smaller screens.

```APIDOC
Breakpoint Specifications:
- Extra large:
  - Device: Desktop
  - Width: >1920px
  - Columns: Density dependent
  - Spacing: --salt-spacing-300, -200, -100
  - Fixed grid width: 1280px, centered
  - Density: HD,MD,LD
- Large:
  - Device: Desktop
  - Width: 1280-1919px
  - Columns: Density dependent
  - Spacing: --salt-spacing-300, -200, -100
  - Fixed grid width: 1280px, centered
  - Density: HD,MD,LD
- Medium:
  - Device: Desktop
  - Width: 960-1279px
  - Columns: Density dependent
  - Spacing: --salt-spacing-300, -200, -100
  - Fixed grid width: 100%
  - Density: HD,MD,LD
- Small:
  - Device: Tablet, mobile landscape
  - Width: 600-959px
  - Columns: 2
  - Spacing: --salt-spacing-300, -200, -100
  - Fixed grid width: 100%
  - Density: TD
- Extra small:
  - Device: Mobile
  - Width: 0-599px
  - Columns: 1
  - Spacing: --salt-spacing-300, -200, -100
  - Fixed grid width: 100%
  - Density: TD

Notes:
- Density dependent: The number of columns in a layout changes based on the chosen breakpoint and its density. For each combination, the margin and gutter size remains constant, whereas the width of each column will vary as a percentage of the overall width.
- Small and XS breakpoints are only relevant if using Touch Density on smaller screens.
- Touch Density is recommended for mobile and tablet devices to achieve the best mobile experience and ensure secure touch targets. It is not recommended to mix densities within a single product, except for using Touch Density in mobile and tablet views.
- When breakpoint changes to Small or Extra Small, spacing becomes smaller.
```

--------------------------------

### Salt Design System Container Padding Guidelines

Source: https://www.saltdesignsystem.com/foundations/spacing

Outlines the recommended `--salt-spacing-XXX` tokens for internal padding within containers based on their size (Large, Medium, Small), controlling the distance between content and boundaries.

```APIDOC
Container size | Padding size
--- | ---
Large | --salt-spacing-300
Medium | --salt-spacing-200
Small | --salt-spacing-100
```

--------------------------------

### Integrate Google Fonts for Salt Design System

Source: https://www.saltdesignsystem.com/getting-started/developing

Add these <link> tags to your application's index.html file to load Open Sans and PT Mono fonts directly from Google Fonts, which are required by Salt's default theme.

```HTML
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&family=PT+Mono&display=swap" rel="stylesheet">
```

--------------------------------

### Integrate Salt Design System Provider in React App

Source: https://www.saltdesignsystem.com/getting-started/developing

Wrap your React application with the SaltProvider component and import the Salt theme CSS to apply the default Salt Design System styling.

```JavaScript
import { SaltProvider } from "@salt-ds/core";
import "@salt-ds/theme/salt-theme.css";

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <React.StrictMode>
    <SaltProvider>
      <App />
    </SaltProvider>
  </React.StrictMode>
);
```

--------------------------------

### Salt Design System Horizontal Spacing Guidelines

Source: https://www.saltdesignsystem.com/foundations/spacing

Provides recommended `--salt-spacing-XXX` tokens for horizontal spacing between common UI elements such as buttons and components, ensuring consistent alignment and visual rhythm.

```APIDOC
Horizontal spacing | Space between
--- | ---
Buttons | --salt-spacing-100
Components | --salt-spacing-300
```

--------------------------------

### Salt Design System Spacing Ramp Tokens

Source: https://www.saltdesignsystem.com/foundations/spacing

Defines the `--salt-spacing-XXX` design tokens, their proportional formulas, and corresponding pixel values across High, Medium, Low, and Touch densities. These tokens form the foundation of consistent spacing within the Salt Design System.

```APIDOC
Token | Formula | High Density (HD) (px) | Medium Density (MD) (px) | Low Density (LD) (px) | Touch Density (TD) (px)
--- | --- | --- | --- | --- | ---
--salt-spacing-25 | 0.25x | 1 | 2 | 3 | 4
--salt-spacing-50 | 0.50x | 2 | 4 | 6 | 8
--salt-spacing-75 | 0.75x | 3 | 6 | 9 | 12
--salt-spacing-100 | 1.00x | 4 | 8 | 12 | 16
--salt-spacing-150 | 1.50x | 6 | 12 | 18 | 24
--salt-spacing-200 | 2.00x | 8 | 16 | 24 | 32
--salt-spacing-250 | 2.50x | 10 | 20 | 30 | 40
--salt-spacing-300 | 3.00x | 12 | 24 | 36 | 48
--salt-spacing-350 | 3.50x | 14 | 28 | 42 | 56
--salt-spacing-400 | 4.00x | 16 | 32 | 48 | 64
--salt-spacing-450 | 4.50x | 18 | 36 | 54 | 72
--salt-spacing-500 | 5.00x | 20 | 40 | 60 | 80
--salt-spacing-550 | 5.50x | 22 | 44 | 66 | 88
--salt-spacing-600 | 6.00x | 24 | 48 | 72 | 96
--salt-spacing-650 | 6.50x | 26 | 52 | 78 | 104
--salt-spacing-700 | 7.00x | 28 | 56 | 84 | 112
--salt-spacing-750 | 7.50x | 30 | 60 | 90 | 120
--salt-spacing-800 | 8.00x | 32 | 64 | 96 | 128
--salt-spacing-850 | 8.50x | 34 | 68 | 102 | 136
--salt-spacing-900 | 9.00x | 36 | 72 | 108 | 144
--salt-spacing-950 | 9.50x | 38 | 76 | 114 | 152
```

--------------------------------

### Import Fontsource CSS for Salt Design System

Source: https://www.saltdesignsystem.com/getting-started/developing

Import the required Open Sans and PT Mono font styles and weights into your src/index.js file when using Fontsource for self-hosting Salt Design System fonts.

```JavaScript
import "@fontsource/open-sans/300.css";
import "@fontsource/open-sans/300-italic.css";
import "@fontsource/open-sans/400.css";
import "@fontsource/open-sans/400-italic.css";
import "@fontsource/open-sans/500.css";
import "@fontsource/open-sans/500-italic.css";
import "@fontsource/open-sans/600.css";
import "@fontsource/open-sans/600-italic.css";
import "@fontsource/open-sans/700.css";
import "@fontsource/open-sans/700-italic.css";
import "@fontsource/open-sans/800.css";
import "@fontsource/open-sans/800-italic.css";
import "@fontsource/pt-mono/400.css";
```

--------------------------------

### Salt Design System Size Tokens Reference

Source: https://www.saltdesignsystem.com/foundations/size

This table provides a comprehensive reference for the Salt Design System's size tokens, detailing their dimensions across various density settings (High, Medium, Low, Touch). These tokens define restricted dimensions for elements like height and width, ensuring consistent sizing and alignment.

```CSS
--salt-size-base:
  Dimension: Height
  High Density (HD): 20px
  Medium Density (MD): 28px
  Low Density (LD): 36px
  Touch Density (TD): 44px

--salt-size-selectable:
  Dimension: Height and width
  High Density (HD): 12px
  Medium Density (MD): 14px
  Low Density (LD): 16px
  Touch Density (TD): 18px

--salt-size-icon:
  Dimension: Height and width
  High Density (HD): 12px
  Medium Density (MD): 12px
  Low Density (LD): 14px
  Touch Density (TD): 16px

--salt-size-adornment:
  Dimension: Height and width
  High Density (HD): 6px
  Medium Density (MD): 8px
  Low Density (LD): 10px
  Touch Density (TD): 12px

--salt-size-bar:
  Dimension: Height or width
  High Density (HD): 2px
  Medium Density (MD): 4px
  Low Density (LD): 6px
  Touch Density (TD): 8px

--salt-size-indicator:
  Dimension: Height or width
  High Density (HD): 1px
  Medium Density (MD): 2px
  Low Density (LD): 3px
  Touch Density (TD): 4px

--salt-size-border:
  Dimension: Height or width
  High Density (HD): 1px
  Medium Density (MD): 1px
  Low Density (LD): 1px
  Touch Density (TD): 1px
```

--------------------------------

### API Documentation for Salt Design System Progression Indication

Source: https://www.saltdesignsystem.com/patterns/indication

Defines the five main stages of progression in the Salt Design System, including their associated colors and icons, to represent a sequence of steps through which a piece of work passes from initiation to completion. Progression is sequential but does not escalate, and steps can be skipped or repeated.

```APIDOC
Progression:
  - Static:
    Color: Gray
    Icons: ProgressTodoIcon, ProgressDraftIcon
    Sub-statuses:
      - To do: An item ready to be picked up or assigned.
      - Draft: An item picked up/assigned, ready to be worked on.
  - In Progress:
    Color: Accent
    Icons: ProgressOnhold, ProgressInprogressIcon
    Sub-statuses:
      - On hold: Item temporarily paused.
      - In progress: Item actively being worked on, no blockers.
  - Alert:
    Color: Orange
    Icon: ProgressPending
    Sub-statuses:
      - Pending: Item being worked on but waiting for another process or input.
  - At Risk:
    Color: Red
    Icons: ProgressCancelledIcon, ProgressRejectedIcon
    Sub-statuses:
      - Canceled: Item deliberately closed or removed due to negative circumstance.
      - Rejected: Item dismissed or failed, requires further action.
  - Complete:
    Color: Green
    Icons: ProgressCompleteIcon, ProgressClosedIcon
    Sub-statuses:
      - Completed: Item finished or ready, no further action required.
      - Closed: Item not actively worked on, no further action required.
```

--------------------------------

### Salt Design System Token Naming Convention

Source: https://www.saltdesignsystem.com/themes

Illustrates the naming convention for Salt Design System tokens in code, where all tokens are prefixed with `--salt-` to ensure consistency and avoid naming conflicts. This allows Figma variables to map directly to corresponding CSS custom properties.

```CSS
:root {
  --salt-spacing-100: 0.25rem; /* Example value */
  --salt-color-blue-500: #007bff; /* Example color token */
  /* ... other Salt Design System tokens */
}
```

--------------------------------

### APIDOC: Touch Density Breakpoint Specifications

Source: https://www.saltdesignsystem.com/foundations/responsiveness/breakpoints

Defines the breakpoint specifications for touch-density layouts, including width ranges, column counts, and spacing for margins and gutters across different screen sizes (Extra Small to Extra Large). This density is recommended for mobile and tablet devices to ensure optimal touch targets.

```APIDOC
Breakpoint | Width (px) | Columns | Margin size | Gutter size
--- | --- | --- | --- | ---
Extra Small | 0 - 599 | 1 | --salt-spacing-300 | --salt-spacing-300
Small | 600 - 959 | 2 | --salt-spacing-300 | --salt-spacing-300
Medium | 960 - 1279 | 4 | --salt-spacing-300 | --salt-spacing-300
Large | 1280-1919 | 6 | --salt-spacing-300 | --salt-spacing-300
Extra Large | >1920 | 8 | --salt-spacing-300 | --salt-spacing-300
```

--------------------------------

### APIDOC: Medium Density Breakpoint Specifications

Source: https://www.saltdesignsystem.com/foundations/responsiveness/breakpoints

Defines the breakpoint specifications for medium-density layouts, including width ranges, column counts, and spacing for margins and gutters across different screen sizes (Extra Small to Extra Large). This density offers a balanced approach for various content types.

```APIDOC
Breakpoint | Width (px) | Columns | Margin size | Gutter size
--- | --- | --- | --- | ---
Extra Small | 0 - 599 | 2 | --salt-spacing-300 | --salt-spacing-300
Small | 600 - 959 | 4 | --salt-spacing-300 | --salt-spacing-300
Medium | 960 - 1279 | 6 | --salt-spacing-300 | --salt-spacing-300
Large | 1280-1919 | 8 | --salt-spacing-300 | --salt-spacing-300
Extra Large | >1920 | 12 | --salt-spacing-300 | --salt-spacing-300
```

--------------------------------

### Import and Use Salt Design System Components in React

Source: https://www.saltdesignsystem.com/getting-started/developing

Import individual UI components from the @salt-ds/core package and use them directly within your React JSX code.

```JavaScript
import { Button } from "@salt-ds/core";

function MyComponent() {
  return <Button>Hello World</Button>;
}
```

--------------------------------

### APIDOC: Low Density Breakpoint Specifications

Source: https://www.saltdesignsystem.com/foundations/responsiveness/breakpoints

Defines the breakpoint specifications for low-density layouts, including width ranges, column counts, and spacing for margins and gutters across different screen sizes (Extra Small to Extra Large). This density is suitable for content-light applications or specific design requirements.

```APIDOC
Breakpoint | Width (px) | Columns | Margin size | Gutter size
--- | --- | --- | --- | ---
Extra Small | 0 - 599 | 1 | --salt-spacing-300 | --salt-spacing-300
Small | 600 - 959 | 2 | --salt-spacing-300 | --salt-spacing-300
Medium | 960 - 1279 | 4 | --salt-spacing-300 | --salt-spacing-300
Large | 1280-1919 | 6 | --salt-spacing-300 | --salt-spacing-300
Extra Large | >1920 | 8 | --salt-spacing-300 | --salt-spacing-300
```

--------------------------------

### APIDOC: High Density Breakpoint Specifications

Source: https://www.saltdesignsystem.com/foundations/responsiveness/breakpoints

Defines the breakpoint specifications for high-density layouts, including width ranges, column counts, and spacing for margins and gutters across different screen sizes (Extra Small to Extra Large). This density is typically applied on desktop devices based on content needs.

```APIDOC
Breakpoint | Width (px) | Columns | Margin size | Gutter size
--- | --- | --- | --- | ---
Extra Small | 0 - 599 | 2 | --salt-spacing-300 | --salt-spacing-300
Small | 600 - 959 | 4 | --salt-spacing-300 | --salt-spacing-300
Medium | 960 - 1279 | 6 | --salt-spacing-300 | --salt-spacing-300
Large | 1280-1919 | 8 | --salt-spacing-300 | --salt-spacing-300
Extra Large | >1920 | 12 | --salt-spacing-300 | --salt-spacing-300
```

--------------------------------

### API Documentation for Salt Design System Status Indication

Source: https://www.saltdesignsystem.com/patterns/indication

Defines the four status types used in the Salt Design System, including their associated colors and icons, to indicate the state or condition of a system or process. Each status helps users understand what’s happening, what actions are needed, and whether any issues need to be addressed.

```APIDOC
Status:
  - Info:
    Color: Blue
    Icon: InfoIcon
  - Warning:
    Color: Orange
    Icon: WarningIcon
  - Error:
    Color: Red
    Icon: ErrorIcon
  - Success:
    Color: Green
    Icon: SuccessCircleIcon
```

--------------------------------

### API Documentation for Salt Design System Urgency Indication

Source: https://www.saltdesignsystem.com/patterns/indication

Defines the five levels of urgency in the Salt Design System, including their associated colors and icons, to communicate the level of risk associated with an item, process, or entity. Urgency levels escalate but do not have to be followed in sequence, and can jump between levels.

```APIDOC
Urgency:
  - None:
    Color: Gray
    Icon: UrgencyNoneIcon
    Description: No urgency or priority level, neutral item with no action required.
  - Low:
    Color: Accent
    Icon: UrgencyLowIcon
    Description: Non-priority item with low threat to threshold/deadline, doesn’t require immediate acknowledgement.
  - Medium:
    Color: Orange
    Icon: UrgencyMediumIcon
    Description: Moderate level of priority nearing threshold/deadline, item can be addressed later.
  - High:
    Color: Red
    Icon: UrgencyHighIcon
    Description: Nearing threshold/deadline, item to be addressed to prevent serious outcome.
  - On Time:
    Color: Green
    Icon: Icon TBD
    Description: Process has begun, but not enough time elapsed to increase urgency to 'low'.
```

--------------------------------

### API Documentation for Salt Design System Sentiment Indication

Source: https://www.saltdesignsystem.com/patterns/indication

Defines the five sentiment types used in the Salt Design System, including their associated colors and feelings, to provide visual cues about potential outcomes. Each sentiment evokes specific feelings such as negativity, carefulness, comfort, trust or positivity.

```APIDOC
Sentiment:
  - Neutral:
    Color: Gray
    Feeling: Comfort
  - Accented:
    Color: Accent
    Feeling: Trust
  - Caution:
    Color: Orange
    Feeling: Carefulness
  - Negative:
    Color: Red
    Feeling: Negativity
  - Positive:
    Color: Green
    Feeling: Positivity
```

--------------------------------

### Salt Design System Shadow Token Properties

Source: https://www.saltdesignsystem.com/foundations/elevation

Defines the properties for the five levels of shadow tokens provided by the Salt Design System, including their horizontal offset (X-Axis), vertical offset (Y-Axis), and blur radius (Blur). These tokens are used to create graduated shadow effects.

```APIDOC
--salt-shadow-100:
  X-Axis: 0px
  Y-Axis: 1px
  Blur: 3px
--salt-shadow-200:
  X-Axis: 0px
  Y-Axis: 2px
  Blur: 4px
--salt-shadow-300:
  X-Axis: 0px
  Y-Axis: 4px
  Blur: 8px
--salt-shadow-400:
  X-Axis: 0px
  Y-Axis: 6px
  Blur: 10px
--salt-shadow-500:
  X-Axis: 0px
  Y-Axis: 12px
  Blur: 40px
```
Tokens:
Raw