prestonwebdev · Oct 29, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 29, 2026 · Oct 29, 2026
diff --git a/.changeset/mosaic-color-tokens.md b/.changeset/mosaic-color-tokens.md
@@ -0,0 +1,9 @@
+---
+'@clerk/mosaic': minor
+---
+
+Dark mode gives the profile its own shell color. `--cl-color-background` is replaced by `--cl-color-page`, the base layer (near-black in dark mode, white in light), which backs the profile shell. A new `--cl-color-surface` backs everything raised on it, such as cards, sections, menus, popovers and controls, and the gray ramp mixes into it. The surface is derived from the page (neutral mixed 5 percent into it in dark mode, white mixed 60 percent into it in light mode), so retinting `--cl-color-page` retints the shell, the surface and the ramp together, and with the default white page the shell, surface and borders look the same in light mode. `--cl-color-background-subtle` is renamed `--cl-color-surface-subtle`.
+
+Brand and the negative, positive and warning colors now share one set of derived tokens: `-foreground`, `-subtle`, `-border` and `-alpha-100|200|300`, so overriding a seed retints its companions. `-foreground` flips to dark text in dark mode for brand, positive and warning, where white would fail, while negative keeps white text. `--cl-color-brand-secondary` is removed. `--cl-color-neutral-subtle` is new. `--cl-color-border` and `--cl-color-border-subtle` are now neutral washes (7 and 4 percent in light mode, 12 and 8 in dark mode), so they stay visible on the surface and faded fills.
+
+In light mode the negative, positive and warning colors are slightly darker so their text passes contrast on their own `-subtle` fill, `--cl-color-foreground-secondary` is a little darker, and `--cl-color-input-placeholder` has its own value that now passes contrast on the field.
diff --git a/packages/mosaic/ARCHITECTURE.md b/packages/mosaic/ARCHITECTURE.md
@@ -18,14 +18,18 @@ Tokens are CSS custom properties declared through `stylex.defineVars` in `tokens
 // packages/mosaic/src/tokens.stylex.ts
 export const colorVars = stylex.defineVars({
   '--cl-color-brand': 'light-dark(oklch(0.2046 0 0), oklch(0.9851 0 0))',
-  '--cl-color-brand-foreground': 'light-dark(oklch(1 0 0), oklch(0.2046 0 0))',
+  '--cl-color-brand-foreground': 'light-dark(oklch(1 0 0), var(--cl-color-surface))',
   // …
 });
 ```
 
 Each exported `*Vars` const in that file is one group (`colorVars`, `radiusVars`, …); the file is the list. `space` is also declared with `defineVars`, but its keys are not `--cl-*` names, so its steps compile to hashed custom properties that are internal, not part of the contract.
 
-There is no gray scale. Every achromatic token (`--cl-color-foreground`, `-border`, `-background-subtle`, …) is `--cl-color-neutral` (black on light, white on dark) mixed into `--cl-color-background` at a fixed percentage per mode, so overriding neutral to a warm gray retints the whole ramp; in dark mode override `--cl-color-background` too, since the ramp mixes toward it. The `--cl-<color>-alpha-100|200|300` tokens in `colorVars` are washes (6, 8, and 12 percent of `--cl-color-neutral`, `-negative`, `-positive`, and `-warning` over `transparent`); overriding the solid color retints its washes.
+There is no gray scale. Every achromatic token (`--cl-color-foreground`, `-border`, `-surface-subtle`, …) is `--cl-color-neutral` (black on light, white on dark) mixed into `--cl-color-surface` at a fixed percentage per mode, so overriding neutral to a warm gray retints the whole ramp. The exception is the borders: `--cl-color-border` (controls) and `--cl-color-border-subtle` (containers and dividers) are neutral washes, 7 and 4 percent in light mode and 12 and 8 percent in dark mode, so they keep the same step over the surface and the faded surface alike. The `--cl-<color>-alpha-100|200|300` tokens in `colorVars` are washes (6, 8, and 12 percent of `--cl-color-neutral`, `-negative`, `-positive`, and `-warning` over `transparent`); overriding the solid color retints its washes.
+
+The seeds are `--cl-color-page`, `--cl-color-neutral`, `--cl-color-brand`, `--cl-color-negative`, `--cl-color-positive` and `--cl-color-warning`. Brand and the three statuses share one shape: the seed, `-foreground` (white in light mode; in dark mode the surface color for brand, positive and warning, where the fills are light, and white for negative), `-subtle` (the 8 percent wash, 12 in dark mode) and `-border` (the 12 percent wash), so both work over the page, the surface or a faded fill and `-alpha-100|200|300` washes. Neutral has the same slots under its own names: `--cl-color-surface-subtle`, `--cl-color-neutral-subtle` (the same wash as the accent `-subtle`, for chips such as the neutral badge) and `--cl-color-border`. Only the seeds and the `-foreground` pairs are set by hand, so retinting a seed retints its companions.
+
+Three tiers carry the layering. `--cl-color-page` is the base: the shell of a settings surface such as the profile, and the darkest layer (`oklch(0.16 0 0)` in dark mode, white in light mode). `--cl-color-surface` is everything raised on it (cards, sections, menus, popovers, dialogs, controls) and the base the gray ramp mixes into. `--cl-color-surface-subtle` is the faded step on a surface, for footers, tiles and striped rows. The surface is derived, not set: in dark mode it is `--cl-color-neutral` mixed 5 percent into `--cl-color-page`, and in light mode it is white mixed 60 percent into `--cl-color-page`, so it is exactly white over a white page and still reads as near white over a gray one. So retinting `--cl-color-page` retints the shell, the surface and the whole ramp together; override `--cl-color-surface` directly only to change how far cards sit above the shell. All three are solid, never alpha, so they look the same over any backdrop.
 
 Light and dark come from CSS `light-dark()` on the default values, so there is no theme object and no re-render on theme change — the browser resolves it.
 
@@ -51,7 +55,7 @@ A theme styles a part from CSS, against that class and its attributes:
   border-radius: 4px;
 }
 .cl-item[data-interactive] {
-  background-color: var(--cl-color-background);
+  background-color: var(--cl-color-surface);
 }
 ```
 

diff --git a/packages/mosaic/src/components/action-bar/action-bar.styles.ts b/packages/mosaic/src/components/action-bar/action-bar.styles.ts
@@ -30,7 +30,7 @@ export const styles = stylex.create({
     paddingBlock: space['1'],
     paddingInline: space['1'],
     alignItems: 'center',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     blockSize: space['10'],
     boxShadow: shadowVars['--cl-shadow-lg'],
     display: 'flex',

diff --git a/packages/mosaic/src/components/avatar/avatar.styles.ts b/packages/mosaic/src/components/avatar/avatar.styles.ts
@@ -73,7 +73,7 @@ export const styles = stylex.create({
     borderWidth: '1px',
     overflow: 'hidden',
     alignItems: 'center',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxSizing: 'border-box',
     display: 'flex',
     insetBlockEnd: `calc(${space['2']} * -1)`,

diff --git a/packages/mosaic/src/components/card/card.styles.ts b/packages/mosaic/src/components/card/card.styles.ts
@@ -26,7 +26,7 @@ export const root = stylex.create({
   card: {
     borderRadius: radiusVars['--cl-radius-xl'],
     overflow: 'hidden',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxShadow: shadowVars['--cl-shadow-lg'],
   },
   flush: {
@@ -38,7 +38,7 @@ export const root = stylex.create({
   overlay: {
     borderRadius: radiusVars['--cl-radius-xl'],
     overflow: 'hidden',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxShadow: shadowVars['--cl-shadow-lg'],
   },
 });

diff --git a/packages/mosaic/src/components/checkbox/checkbox.styles.ts b/packages/mosaic/src/components/checkbox/checkbox.styles.ts
@@ -26,7 +26,7 @@ export const styles = stylex.create({
     borderWidth: '1px',
     appearance: 'none',
     backgroundColor: {
-      default: colorVars['--cl-color-background'],
+      default: colorVars['--cl-color-surface'],
       ':checked': colorVars['--cl-color-brand'],
       ':indeterminate': colorVars['--cl-color-brand'],
     },

diff --git a/packages/mosaic/src/components/combobox/combobox.styles.ts b/packages/mosaic/src/components/combobox/combobox.styles.ts
@@ -20,7 +20,7 @@ export const styles = stylex.create({
     borderRadius: radiusVars['--cl-radius-lg'],
     outline: 'none',
     overflow: 'hidden',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxShadow: shadowVars['--cl-shadow-md'],
     color: colorVars['--cl-color-foreground'],
     opacity: {

diff --git a/packages/mosaic/src/components/copy-button/copy-button.styles.ts b/packages/mosaic/src/components/copy-button/copy-button.styles.ts
@@ -10,7 +10,7 @@ export const styles = stylex.create({
     paddingInline: space['1.5'],
     alignItems: 'center',
     backgroundColor: colorVars['--cl-color-foreground'],
-    color: colorVars['--cl-color-background'],
+    color: colorVars['--cl-color-surface'],
     // A copy while one is still showing queues behind the `limit`; only the newest is wanted.
     display: { default: 'flex', ':where([data-limited])': 'none' },
     fontSize: typeScaleVars['--cl-text-sm-size'],

diff --git a/packages/mosaic/src/components/data-list/data-list.styles.ts b/packages/mosaic/src/components/data-list/data-list.styles.ts
@@ -9,7 +9,7 @@ export const list = stylex.create({
     borderStyle: 'solid',
     borderWidth: '1px',
     paddingInline: space['3'],
-    backgroundColor: colorVars['--cl-color-background-subtle'],
+    backgroundColor: colorVars['--cl-color-surface-subtle'],
     display: 'flex',
     flexDirection: 'column',
     width: '100%',

diff --git a/packages/mosaic/src/components/dialog/__tests__/dialog.test.tsx b/packages/mosaic/src/components/dialog/__tests__/dialog.test.tsx
@@ -584,7 +584,7 @@ describe('popup surface', () => {
   // an atom from its property and value, so a probe with the popup's own values yields the very
   // atoms `styles.popup` declares.
   const probe = stylex.create({
-    background: { backgroundColor: colorVars['--cl-color-background'] },
+    background: { backgroundColor: colorVars['--cl-color-page'] },
     radius: { borderRadius: radiusVars['--cl-radius-xl'] },
   });
 

diff --git a/packages/mosaic/src/components/dialog/dialog.styles.ts b/packages/mosaic/src/components/dialog/dialog.styles.ts
@@ -218,7 +218,7 @@ export const styles = stylex.create({
       inset: 0,
       // Follows the popup's own radius.
       borderRadius: 'inherit',
-      backgroundColor: colorVars['--cl-color-background'],
+      backgroundColor: colorVars['--cl-color-surface'],
       content: '""',
       opacity: 'var(--_cl-stack-veil, 0)',
       pointerEvents: 'none',
@@ -465,7 +465,7 @@ export const compactPlacements = stylex.create({
     // shared: bottom-aligning there would drag a centered dialog down with it.
     alignSelf: { [SHEET]: 'end', default: null },
     // The sheet's surface, so it runs on through the keyboard padding below; the card only fills it.
-    backgroundColor: { [SHEET]: colorVars['--cl-color-background'], default: null },
+    backgroundColor: { [SHEET]: colorVars['--cl-color-surface'], default: null },
     // No drop shadow on the screen edge, only the hairline ring, as on `Drawer`. The card inside
     // reads the two variables and drops its own shadow and fixed width.
     boxShadow: { [SHEET]: shadowVars['--cl-shadow-sm'], default: null },

diff --git a/packages/mosaic/src/components/drawer/drawer.styles.ts b/packages/mosaic/src/components/drawer/drawer.styles.ts
@@ -82,7 +82,7 @@ export const styles = stylex.create({
     borderWidth: { default: null, '@media (forced-colors: active)': '1px' },
     outline: 'none',
     overscrollBehavior: 'contain',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     borderStartEndRadius: radiusVars['--cl-radius-2xl'],
     borderStartStartRadius: radiusVars['--cl-radius-2xl'],
     // No drop shadow — the sheet sits on the screen edge, so there is nothing for it to float over.

diff --git a/packages/mosaic/src/components/menu/menu.styles.ts b/packages/mosaic/src/components/menu/menu.styles.ts
@@ -25,7 +25,7 @@ export const popup = stylex.create({
   base: {
     borderRadius: radiusVars['--cl-radius-lg'],
     outline: 'none',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxShadow: shadowVars['--cl-shadow-md'],
     color: colorVars['--cl-color-foreground'],
     opacity: {

diff --git a/packages/mosaic/src/components/phone-input/phone-input.styles.ts b/packages/mosaic/src/components/phone-input/phone-input.styles.ts
@@ -66,7 +66,7 @@ export const styles = stylex.create({
   popup: {
     borderRadius: radiusVars['--cl-radius-lg'],
     overflow: 'hidden',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxShadow: shadowVars['--cl-shadow-md'],
     color: colorVars['--cl-color-foreground'],
   },

diff --git a/packages/mosaic/src/components/profile/profile.styles.ts b/packages/mosaic/src/components/profile/profile.styles.ts
@@ -72,7 +72,7 @@ export const styles = stylex.create({
     },
     // `clip`, not `hidden`: a scroll container here would scroll the surface instead of the column.
     overflow: 'clip',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-page'],
     blockSize: {
       [compact]: '100dvh',
       default: '45rem',

diff --git a/packages/mosaic/src/components/radio/radio.styles.ts b/packages/mosaic/src/components/radio/radio.styles.ts
@@ -30,7 +30,7 @@ export const styles = stylex.create({
     borderWidth: '1px',
     appearance: 'none',
     backgroundColor: {
-      default: colorVars['--cl-color-background'],
+      default: colorVars['--cl-color-surface'],
       ':checked': colorVars['--cl-color-brand'],
     },
     cursor: { default: 'pointer', ':disabled': 'not-allowed' },

diff --git a/packages/mosaic/src/components/section/section.styles.ts b/packages/mosaic/src/components/section/section.styles.ts
@@ -49,7 +49,7 @@ export const styles = stylex.create({
     borderStyle: 'solid',
     borderWidth: '1px',
     paddingInline: space['4'],
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     display: 'flex',
     flexDirection: 'column',
     width: 'auto',

diff --git a/packages/mosaic/src/components/segmented-control/segmented-control.styles.ts b/packages/mosaic/src/components/segmented-control/segmented-control.styles.ts
@@ -32,7 +32,7 @@ const scaleIn = stylex.keyframes({
 
 const surface = {
   borderRadius: radiusVars['--cl-radius-md'],
-  backgroundColor: { default: colorVars['--cl-color-background'], [forcedColors]: 'Highlight' },
+  backgroundColor: { default: colorVars['--cl-color-surface'], [forcedColors]: 'Highlight' },
   boxShadow: shadowVars['--cl-shadow-sm'],
   forcedColorAdjust: 'none',
 } as const;
@@ -44,7 +44,7 @@ export const styles = stylex.create({
     padding: space['0.5'],
     borderRadius: `calc(${radiusVars['--cl-radius-md']} + ${space['0.5']})`,
     alignItems: 'center',
-    backgroundColor: colorVars['--cl-color-background-subtle'],
+    backgroundColor: colorVars['--cl-color-surface-subtle'],
     display: 'inline-flex',
     isolation: 'isolate',
     position: 'relative',

diff --git a/packages/mosaic/src/components/select/select.styles.ts b/packages/mosaic/src/components/select/select.styles.ts
@@ -40,7 +40,7 @@ export const popup = stylex.create({
     borderStyle: 'solid',
     borderWidth: '1px',
     outline: 'none',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxShadow: shadowVars['--cl-shadow-md'],
     color: colorVars['--cl-color-foreground'],
     opacity: {

diff --git a/packages/mosaic/src/components/switch/switch.styles.ts b/packages/mosaic/src/components/switch/switch.styles.ts
@@ -6,7 +6,7 @@ import { switchInputMarker } from './switch.markers.stylex';
 const thumbInset = '2px';
 const trackOffHover = `color-mix(in oklab, ${colorVars['--cl-color-neutral']} 24%, transparent)`;
 const trackOnHover = `color-mix(in oklab, ${colorVars['--cl-color-brand']}, ${colorVars['--cl-color-brand-foreground']} 12%)`;
-const thumbOff = `light-dark(${colorVars['--cl-color-background']}, ${colorVars['--cl-color-foreground']})`;
+const thumbOff = `light-dark(${colorVars['--cl-color-surface']}, ${colorVars['--cl-color-foreground']})`;
 
 export const styles = stylex.create({
   root: {

diff --git a/packages/mosaic/src/components/table/table.styles.ts b/packages/mosaic/src/components/table/table.styles.ts
@@ -34,7 +34,7 @@ export const styles = stylex.create({
     borderStyle: 'solid',
     borderWidth: '1px',
     overflow: 'hidden',
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     width: '100%',
   },
   viewport: {
@@ -44,32 +44,32 @@ export const styles = stylex.create({
   },
   table: {
     '--_cl-table-row-tint': 'transparent',
-    '--_cl-table-surface': colorVars['--cl-color-background'],
+    '--_cl-table-surface': colorVars['--cl-color-surface'],
     borderCollapse: 'collapse',
     borderSpacing: 0,
     isolation: 'isolate',
     textAlign: 'start',
     width: '100%',
   },
   header: {
-    '--_cl-table-surface': colorVars['--cl-color-background-subtle'],
-    backgroundColor: colorVars['--cl-color-background-subtle'],
+    '--_cl-table-surface': colorVars['--cl-color-surface-subtle'],
+    backgroundColor: colorVars['--cl-color-surface-subtle'],
   },
   row: {
     '--_cl-table-row-tint': {
       default: null,
       ':where([data-selected])': colorVars['--cl-color-neutral-alpha-100'],
       '@media (hover: hover)': {
         default: null,
-        ':where([data-actionable]:not([data-selected]):hover)': colorVars['--cl-color-background-subtle'],
+        ':where([data-actionable]:not([data-selected]):hover)': colorVars['--cl-color-surface-subtle'],
       },
     },
     backgroundColor: {
       default: null,
       ':where([data-selected])': colorVars['--cl-color-neutral-alpha-100'],
       '@media (hover: hover)': {
         default: null,
-        ':where([data-actionable]:not([data-selected]):hover)': colorVars['--cl-color-background-subtle'],
+        ':where([data-actionable]:not([data-selected]):hover)': colorVars['--cl-color-surface-subtle'],
       },
     },
     borderBlockStartColor: colorVars['--cl-color-border'],

diff --git a/packages/mosaic/src/components/toast/toast.styles.ts b/packages/mosaic/src/components/toast/toast.styles.ts
@@ -43,7 +43,7 @@ export const styles = stylex.create({
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
     animationTimingFunction: easingVars['--cl-ease-default'],
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     boxShadow: shadowVars['--cl-shadow-lg'],
     color: colorVars['--cl-color-foreground'],
     display: {

diff --git a/...ofile/user-profile-billing-history-section/user-profile-billing-history-section.styles.ts b/...ofile/user-profile-billing-history-section/user-profile-billing-history-section.styles.ts
@@ -72,7 +72,7 @@ export const styles = stylex.create({
     borderWidth: '1px',
     paddingBlock: space['1'],
     paddingInline: space['2'],
-    backgroundColor: colorVars['--cl-color-background'],
+    backgroundColor: colorVars['--cl-color-surface'],
     color: colorVars['--cl-color-foreground'],
     fontSize: typeScaleVars['--cl-text-xs-size'],
     lineHeight: typeScaleVars['--cl-text-xs-leading'],

diff --git a/...ic/src/features/user-profile/user-profile-mfa-section/user-profile-backup-codes.styles.ts b/...ic/src/features/user-profile/user-profile-mfa-section/user-profile-backup-codes.styles.ts
@@ -9,7 +9,7 @@ export const styles = stylex.create({
     borderStyle: 'solid',
     borderWidth: '1px',
     overflow: 'hidden',
-    backgroundColor: colorVars['--cl-color-background-subtle'],
+    backgroundColor: colorVars['--cl-color-surface-subtle'],
     display: 'grid',
     gridTemplateColumns: 'repeat(2, minmax(0, 1fr))',
     listStyleType: 'none',

diff --git a/packages/mosaic/src/styles/skeleton.styles.ts b/packages/mosaic/src/styles/skeleton.styles.ts
@@ -3,7 +3,7 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, radiusVars } from '../tokens.stylex';
 
 const highlight =
-  'light-dark(color-mix(in oklab, var(--cl-color-background) 62%, transparent), color-mix(in oklab, var(--cl-color-neutral) 7%, transparent))';
+  'light-dark(color-mix(in oklab, var(--cl-color-surface) 62%, transparent), color-mix(in oklab, var(--cl-color-neutral) 7%, transparent))';
 
 const translate = stylex.keyframes({
   from: { transform: 'translateX(-100%)' },

diff --git a/packages/mosaic/src/styles/tooltip-surface.styles.ts b/packages/mosaic/src/styles/tooltip-surface.styles.ts
@@ -10,7 +10,7 @@ export const tooltipSurface = stylex.create({
     paddingInline: space['1.5'],
     alignItems: 'center',
     backgroundColor: colorVars['--cl-color-foreground'],
-    color: colorVars['--cl-color-background'],
+    color: colorVars['--cl-color-surface'],
     display: 'flex',
     fontSize: typeScaleVars['--cl-text-sm-size'],
     lineHeight: typeScaleVars['--cl-text-sm-leading'],