jpmorganchase · joshwooding · Oct 15, 2025 · Oct 15, 2025 · Nov 7, 2025
diff --git a/.changeset/dull-pears-rush.md b/.changeset/dull-pears-rush.md
@@ -0,0 +1,9 @@
+---
+"@salt-ds/embla-carousel": minor
+"@salt-ds/ag-grid-theme": minor
+"@salt-ds/theme": minor
+"@salt-ds/core": minor
+"@salt-ds/lab": minor
+---
+
+Added mobile density tokens.
diff --git a/.changeset/heavy-pandas-strive.md b/.changeset/heavy-pandas-strive.md
@@ -0,0 +1,5 @@
+---
+"@salt-ds/theme": minor
+---
+
+Added a new layout characteristic to the theme. This also adds `--salt-layout-page-margin` for the margin around the main content area and `--salt-layout-gap` for gutters.
diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
@@ -83,7 +83,7 @@ const preview: Preview = {
         // Storybook built in icons here - https://www.chromatic.com/component?appId=5a375b97f4b14f0020b0cda3&name=Basics%2FIcon&buildNumber=20654
         icon: "graphbar",
         // array of plain string values or MenuItem shape (see below)
-        items: ["touch", "low", "medium", "high"],
+        items: ["mobile", "touch", "low", "medium", "high"],
       },
     },
     responsive: {

diff --git a/cypress/support/commands.tsx b/cypress/support/commands.tsx
@@ -15,7 +15,7 @@ import { type PerformanceResult, PerformanceTester } from "./PerformanceTester";
 
 const SupportedThemeModeValues = ["light", "dark"] as const;
 type SupportedThemeMode = (typeof SupportedThemeModeValues)[number];
-const SupportedDensityValues = ["touch", "low", "medium", "high"];
+const SupportedDensityValues = ["mobile", "touch", "low", "medium", "high"];
 type SupportedDensity = (typeof SupportedDensityValues)[number];
 
 // Must be declared global to be detected by typescript (allows import/export)
@@ -132,7 +132,7 @@ Cypress.Commands.add(
       cy.state("announcement", announcement);
     };
 
-    const density: "touch" | "low" | "medium" | "high" | undefined =
+    const density: "mobile" | "touch" | "low" | "medium" | "high" | undefined =
       Cypress.env("density");
     const mode: "light" | "dark" | undefined = Cypress.env("mode");
     const dateAdapter: SaltDateAdapter<DateFrameworkType> | undefined =

diff --git a/packages/ag-grid-theme/src/dependencies/useAgGridHelpers.ts b/packages/ag-grid-theme/src/dependencies/useAgGridHelpers.ts
@@ -51,6 +51,8 @@ export function useAgGridHelpers({
         return [49, 48]; // 36 + 12 + [1 (border)]
       case "touch":
         return [61, 60]; // 44 + 16 + [1 (border)]
+      case "mobile":
+        return [61, 60]; // 44 + 16 + [1 (border)]
       default:
         return [25, 24];
     }

diff --git a/packages/core/src/salt-provider/SaltProvider.tsx b/packages/core/src/salt-provider/SaltProvider.tsx
@@ -179,7 +179,7 @@ interface SaltProviderBaseProps {
    */
   applyClassesTo?: TargetElement;
   /**
-   * Either "high", "medium", "low" or "touch".
+   * Either "high", "medium", "low", "touch" or "mobile".
    * Determines the amount of content that can fit on a screen based on the size and spacing of components.
    * Refer to [density](https://www.saltdesignsystem.com/salt/foundations/density) doc for more detail.
    *

diff --git a/packages/core/src/spinner/svgSpinners/SpinnerSVG.tsx b/packages/core/src/spinner/svgSpinners/SpinnerSVG.tsx
@@ -18,18 +18,21 @@ const sizeAndStrokeWidthMapping = {
     medium: { width: 12, strokeWidth: 2 },
     low: { width: 14, strokeWidth: 2 },
     touch: { width: 16, strokeWidth: 2 },
+    mobile: { width: 16, strokeWidth: 2 },
   },
   medium: {
     high: { width: 20, strokeWidth: 2 },
     medium: { width: 28, strokeWidth: 4 },
     low: { width: 36, strokeWidth: 6 },
     touch: { width: 44, strokeWidth: 8 },
+    mobile: { width: 44, strokeWidth: 8 },
   },
   large: {
     high: { width: 40, strokeWidth: 2 },
     medium: { width: 56, strokeWidth: 4 },
     low: { width: 72, strokeWidth: 6 },
     touch: { width: 88, strokeWidth: 8 },
+    mobile: { width: 88, strokeWidth: 8 },
   },
 };
 
@@ -64,8 +67,8 @@ export const SpinnerSVG = ({
         </linearGradient>
       </defs>
       <g fill="none">
-        {/* 
-          This first path draws the top half of the circle without a gradient. 
+        {/*
+          This first path draws the top half of the circle without a gradient.
           It starts from the right end, moves in a circular arc, and ends at the left end.
         */}
         <path
@@ -76,8 +79,8 @@ export const SpinnerSVG = ({
           strokeWidth="var(--spinner-strokeWidth)"
           fill="none"
         />
-        {/* 
-          This second path draws the left half of the circle with a gradient that transitions 
+        {/*
+          This second path draws the left half of the circle with a gradient that transitions
           from opaque on the left to transparent on the right.
           It starts from the top-center, moves in a circular arc, and ends at the bottom-center.
         */}

diff --git a/packages/core/src/theme/Density.ts b/packages/core/src/theme/Density.ts
@@ -1,3 +1,9 @@
-export const DensityValues = ["high", "medium", "low", "touch"] as const;
+export const DensityValues = [
+  "high",
+  "medium",
+  "low",
+  "touch",
+  "mobile",
+] as const;
 
 export type Density = (typeof DensityValues)[number];
diff --git a/packages/embla-carousel/src/CarouselAutoplayIndicator.tsx b/packages/embla-carousel/src/CarouselAutoplayIndicator.tsx
@@ -39,6 +39,7 @@ const sizeAndStrokeWidthMapping = {
   medium: { size: 12, strokeWidth: 2 },
   low: { size: 14, strokeWidth: 2 },
   touch: { size: 16, strokeWidth: 2 },
+  mobile: { size: 16, strokeWidth: 2 },
 };
 
 export const CarouselAutoplayIndicator = forwardRef<

diff --git a/packages/lab/src/tokenized-input/useTokenizedInput.tsx b/packages/lab/src/tokenized-input/useTokenizedInput.tsx
@@ -50,6 +50,7 @@ const BLUR_TIMEOUT = 200;
  */
 const SINGLE_LINE_HEIGHT_MAP = {
   touch: 45,
+  mobile: 45,
   low: 36,
   medium: 28,
   high: 23,

diff --git a/packages/lab/stories/list/list.stories.tsx b/packages/lab/stories/list/list.stories.tsx
@@ -458,6 +458,7 @@ export const VariableHeight: StoryFn<ListProps> = () => {
       medium: 32,
       low: 36,
       touch: 36,
+      mobile: 36,
     }),
     [],
   );

diff --git a/packages/theme/css/foundations/animation.css b/packages/theme/css/foundations/animation.css
@@ -1,7 +1,8 @@
 .salt-density-touch,
 .salt-density-low,
 .salt-density-medium,
-.salt-density-high {
+.salt-density-high,
+.salt-density-mobile {
   --salt-animation-opacity-start: 0;
   --salt-animation-opacity-end: 1;
   --salt-animation-scale-start: 0;

diff --git a/packages/theme/css/foundations/curve.css b/packages/theme/css/foundations/curve.css
@@ -28,6 +28,7 @@
   --salt-curve-999: 999px;
 }
 
+.salt-density-mobile,
 .salt-density-touch {
   --salt-curve-0: 0;
   --salt-curve-50: 4px;

diff --git a/packages/theme/css/foundations/size.css b/packages/theme/css/foundations/size.css
@@ -28,6 +28,7 @@
   --salt-size-bar-strong: 12px;
 }
 
+.salt-density-mobile,
 .salt-density-touch {
   --salt-size-adornment: 12px;
   --salt-size-bar: 8px;
@@ -41,7 +42,8 @@
 .salt-density-touch,
 .salt-density-low,
 .salt-density-medium,
-.salt-density-high {
+.salt-density-high,
+.salt-density-mobile {
   --salt-size-fixed-100: 1px;
   --salt-size-fixed-200: 2px;
   --salt-size-fixed-300: 3px;

diff --git a/packages/theme/css/foundations/spacing.css b/packages/theme/css/foundations/spacing.css
@@ -39,7 +39,37 @@
   --salt-spacing-850: calc(8.5 * var(--salt-spacing-100));
   --salt-spacing-900: calc(9 * var(--salt-spacing-100));
   --salt-spacing-950: calc(9.5 * var(--salt-spacing-100));
+}
+
+.salt-density-mobile {
+  --salt-spacing-25: 4px;
+  --salt-spacing-50: 8px;
+  --salt-spacing-75: 12px;
+  --salt-spacing-100: 16px;
+  --salt-spacing-150: 18px;
+  --salt-spacing-200: 20px;
+  --salt-spacing-250: 22px;
+  --salt-spacing-300: 24px;
+  --salt-spacing-350: 26px;
+  --salt-spacing-400: 28px;
+  --salt-spacing-450: 30px;
+  --salt-spacing-500: 32px;
+  --salt-spacing-550: 34px;
+  --salt-spacing-600: 36px;
+  --salt-spacing-650: 38px;
+  --salt-spacing-700: 40px;
+  --salt-spacing-750: 42px;
+  --salt-spacing-800: 44px;
+  --salt-spacing-850: 46px;
+  --salt-spacing-900: 48px;
+  --salt-spacing-950: 50px;
+}
 
+.salt-density-touch,
+.salt-density-low,
+.salt-density-medium,
+.salt-density-high,
+.salt-density-mobile {
   --salt-spacing-fixed-100: 1px;
   --salt-spacing-fixed-200: 2px;
   --salt-spacing-fixed-300: 3px;

diff --git a/packages/theme/css/foundations/zindex.css b/packages/theme/css/foundations/zindex.css
@@ -1,7 +1,8 @@
 .salt-density-touch,
 .salt-density-low,
 .salt-density-medium,
-.salt-density-high {
+.salt-density-high,
+.salt-density-mobile {
   --salt-zIndex-default: 1;
   --salt-zIndex-popout: 1000;
   --salt-zIndex-appHeader: 1100;

diff --git a/packages/theme/css/legacy/characteristics/layout.css b/packages/theme/css/legacy/characteristics/layout.css
@@ -0,0 +1,12 @@
+.salt-density-low,
+.salt-density-medium,
+.salt-density-high {
+  --salt-layout-page-margin: var(--salt-spacing-300);
+  --salt-layout-gap: var(--salt-spacing-300);
+}
+
+.salt-density-touch,
+.salt-density-mobile {
+  --salt-layout-page-margin: var(--salt-spacing-100);
+  --salt-layout-gap: var(--salt-spacing-100);
+}
diff --git a/packages/theme/css/legacy/characteristics/text.css b/packages/theme/css/legacy/characteristics/text.css
@@ -224,3 +224,39 @@
   --salt-text-notation-fontSize: 8px;
   --salt-text-notation-lineHeight: 10px;
 }
+
+.salt-density-mobile {
+  --salt-text-h1-fontSize: 42px;
+  --salt-text-h1-lineHeight: 54px;
+
+  --salt-text-h2-fontSize: 32px;
+  --salt-text-h2-lineHeight: 42px;
+
+  --salt-text-h3-fontSize: 24px;
+  --salt-text-h3-lineHeight: 32px;
+
+  --salt-text-h4-fontSize: 16px;
+  --salt-text-h4-lineHeight: 21px;
+
+  --salt-text-label-fontSize: 14px;
+  --salt-text-label-lineHeight: 18px;
+
+  --salt-text-fontSize: 16px;
+  --salt-text-lineHeight: 21px;
+  --salt-text-minHeight: 21px;
+
+  --salt-text-display1-fontSize: 84px;
+  --salt-text-display1-lineHeight: 109px;
+
+  --salt-text-display2-fontSize: 58px;
+  --salt-text-display2-lineHeight: 76px;
+
+  --salt-text-display3-fontSize: 42px;
+  --salt-text-display3-lineHeight: 54px;
+
+  --salt-text-display4-fontSize: 42px;
+  --salt-text-display4-lineHeight: 54px;
+
+  --salt-text-notation-fontSize: 14px;
+  --salt-text-notation-lineHeight: 18px;
+}
diff --git a/packages/theme/css/next/characteristics/layout.css b/packages/theme/css/next/characteristics/layout.css
@@ -0,0 +1,12 @@
+.salt-density-low,
+.salt-density-medium,
+.salt-density-high {
+  --salt-layout-page-margin: var(--salt-spacing-300);
+  --salt-layout-gap: var(--salt-spacing-300);
+}
+
+.salt-density-touch,
+.salt-density-mobile {
+  --salt-layout-page-margin: var(--salt-spacing-100);
+  --salt-layout-gap: var(--salt-spacing-100);
+}
diff --git a/packages/theme/css/next/characteristics/text.css b/packages/theme/css/next/characteristics/text.css
@@ -224,3 +224,39 @@
   --salt-text-notation-fontSize: 8px;
   --salt-text-notation-lineHeight: 10px;
 }
+
+.salt-density-mobile {
+  --salt-text-h1-fontSize: 42px;
+  --salt-text-h1-lineHeight: 54px;
+
+  --salt-text-h2-fontSize: 32px;
+  --salt-text-h2-lineHeight: 42px;
+
+  --salt-text-h3-fontSize: 24px;
+  --salt-text-h3-lineHeight: 32px;
+
+  --salt-text-h4-fontSize: 16px;
+  --salt-text-h4-lineHeight: 21px;
+
+  --salt-text-label-fontSize: 14px;
+  --salt-text-label-lineHeight: 18px;
+
+  --salt-text-fontSize: 16px;
+  --salt-text-lineHeight: 21px;
+  --salt-text-minHeight: 21px;
+
+  --salt-text-display1-fontSize: 84px;
+  --salt-text-display1-lineHeight: 109px;
+
+  --salt-text-display2-fontSize: 58px;
+  --salt-text-display2-lineHeight: 76px;
+
+  --salt-text-display3-fontSize: 42px;
+  --salt-text-display3-lineHeight: 54px;
+
+  --salt-text-display4-fontSize: 42px;
+  --salt-text-display4-lineHeight: 54px;
+
+  --salt-text-notation-fontSize: 14px;
+  --salt-text-notation-lineHeight: 18px;
+}
diff --git a/packages/theme/css/theme-next.css b/packages/theme/css/theme-next.css
@@ -27,6 +27,7 @@
 @import url(next/characteristics/content.css);
 @import url(next/characteristics/editable.css);
 @import url(next/characteristics/focused.css);
+@import url(next/characteristics/layout.css);
 @import url(next/characteristics/navigable.css);
 @import url(next/characteristics/overlayable.css);
 @import url(next/characteristics/selectable.css);

diff --git a/packages/theme/css/theme.css b/packages/theme/css/theme.css
@@ -29,6 +29,7 @@
 @import url(legacy/characteristics/content.css);
 @import url(legacy/characteristics/editable.css);
 @import url(legacy/characteristics/focused.css);
+@import url(legacy/characteristics/layout.css);
 @import url(legacy/characteristics/navigable.css);
 @import url(legacy/characteristics/overlayable.css);
 @import url(legacy/characteristics/selectable.css);

diff --git a/site/src/ThemeProvider.tsx b/site/src/ThemeProvider.tsx
@@ -23,7 +23,7 @@ function DensitySetter({
 }) {
   const isMobileOrTablet = useIsMobileView();
 
-  const density = isMobileOrTablet ? "touch" : "low";
+  const density = isMobileOrTablet ? "mobile" : "low";
 
   useEffect(() => {
     setDensity(density);

diff --git a/site/src/components/components/ThemeControls.tsx b/site/src/components/components/ThemeControls.tsx
@@ -27,6 +27,7 @@ export function ThemeControls() {
           <ToggleButton value="medium">Medium</ToggleButton>
           <ToggleButton value="low">Low</ToggleButton>
           <ToggleButton value="touch">Touch</ToggleButton>
+          <ToggleButton value="mobile">Mobile</ToggleButton>
         </ToggleButtonGroup>
       </StackLayout>
       <StackLayout gap={0.75} align="baseline" padding={0}>