feat(mosaic): split control and container borders and use washes for states

.changeset/mosaic-color-adoption.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Controls such as inputs, selects, checkboxes, radios and outline buttons keep the stronger `--cl-color-border`, while containers and dividers (cards, sections, tables, menus, the profile nav) use `--cl-color-border-subtle`. Outline buttons fill with the surface color and lay their hover and pressed tint over it, so the tint works on the page, the surface or a faded fill. Banners, badges, toasts and the tag-input error use the `-subtle` and `-border` tokens, and the neutral badge and banner use `--cl-color-neutral-subtle`. The negative color is slightly deeper in light mode for contrast.

packages/mosaic/src/components/action-bar/action-bar.styles.ts

@@ -76,7 +76,7 @@ export const styles = stylex.create({
     marginBlock: space['1'],
     marginInline: space['0.5'],
     alignSelf: 'stretch',
-    backgroundColor: colorVars['--cl-color-border'],
+    backgroundColor: colorVars['--cl-color-border-subtle'],
     width: '1px',
   },
 });

packages/mosaic/src/components/avatar/avatar.styles.ts

@@ -67,7 +67,7 @@ export const styles = stylex.create({
   },
 
   icon: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderRadius: radiusVars['--cl-radius-full'],
     borderStyle: 'solid',
     borderWidth: '1px',

packages/mosaic/src/components/badge/badge.styles.ts

@@ -2,12 +2,9 @@ import * as stylex from '@stylexjs/stylex';
 
 import { colorVars, fontFamilyVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
 
-// warning/negative/positive fill with the subtle surface and use the saturated token as text;
-// primary fills with the solid token and uses its `-foreground` for text.
-//
-// Neutral has no subtle surface to fill — `--cl-color-foreground-secondary` is a text gray, and its
-// `-foreground` is a text color rather than an on-fill one, so it is unreadable against the solid
-// 900. It rides the same neutral scrim the button's neutral fill does.
+// Every color but primary fills with its `-subtle` token and uses the saturated token as text;
+// primary fills with the solid token and uses its `-foreground` for text. Every `-subtle` is a
+// wash, so the chip stays visible on the page, the surface and the faded surface alike.
 export const styles = stylex.create({
   base: {
     borderRadius: radiusVars['--cl-radius-full'],
@@ -33,7 +30,7 @@ export const colors = stylex.create({
     color: colorVars['--cl-color-brand-foreground'],
   },
   neutral: {
-    backgroundColor: colorVars['--cl-color-neutral-alpha-100'],
+    backgroundColor: colorVars['--cl-color-neutral-subtle'],
     color: colorVars['--cl-color-foreground'],
   },
   warning: {

packages/mosaic/src/components/banner/banner.styles.ts

@@ -39,7 +39,7 @@ export const styles = stylex.create({
 export const rootColors = stylex.create({
   neutral: {
     borderColor: colorVars['--cl-color-border'],
-    backgroundColor: colorVars['--cl-color-neutral-alpha-100'],
+    backgroundColor: colorVars['--cl-color-neutral-subtle'],
   },
   warning: {
     borderColor: colorVars['--cl-color-warning-border'],

packages/mosaic/src/components/button/button.styles.ts

@@ -13,14 +13,20 @@ import {
 import { iconScope } from '../icon/icon.markers.stylex';
 
 // Neutral fills are the three neutral alpha steps, shared across variants:
-//   100 — `filled-neutral` rest, `outline-*`/`ghost-*` hover
-//   200 — `filled-neutral` hover, `outline-*`/`ghost-*` pressed
+//   100 — `filled-neutral` rest, `ghost-*` hover
+//   200 — `filled-neutral` hover, `ghost-*` pressed
 //   300 — `filled-neutral` pressed
 
 // Opaque fills blend toward their own on-fill at the same 12%/18%. Neutral has no fill
 // to blend from, so it rides the opacity ramp above.
+// Outline variants keep the surface as their fill and lay the hover and pressed wash over it as an
+// inset shadow, so the state tint works on any backdrop and still transitions.
 const primaryHover = `color-mix(in oklab, ${colorVars['--cl-color-brand']}, ${colorVars['--cl-color-brand-foreground']} 12%)`;
 const primaryActive = `color-mix(in oklab, ${colorVars['--cl-color-brand']}, ${colorVars['--cl-color-brand-foreground']} 18%)`;
+const neutralHoverWash = `inset 0 0 0 100vmax ${colorVars['--cl-color-neutral-alpha-100']}`;
+const neutralPressedWash = `inset 0 0 0 100vmax ${colorVars['--cl-color-neutral-alpha-200']}`;
+const negativeHoverWash = `inset 0 0 0 100vmax ${colorVars['--cl-color-negative-alpha-200']}`;
+const negativePressedWash = `inset 0 0 0 100vmax ${colorVars['--cl-color-negative-alpha-300']}`;
 const negativeHover = `color-mix(in oklab, ${colorVars['--cl-color-negative']}, ${colorVars['--cl-color-negative-foreground']} 12%)`;
 const negativeActive = `color-mix(in oklab, ${colorVars['--cl-color-negative']}, ${colorVars['--cl-color-negative-foreground']} 18%)`;
 
@@ -75,7 +81,7 @@ export const styles = stylex.create({
       ':not([data-disabled]):active': durationVars['--cl-duration-instant'],
       ':not([data-disabled]):hover': durationVars['--cl-duration-instant'],
     },
-    transitionProperty: 'background-color, border-color, color, opacity, text-decoration-color',
+    transitionProperty: 'background-color, border-color, box-shadow, color, opacity, text-decoration-color',
     // Linear, not `--cl-ease-default`: nothing here moves. An ease on already non-uniform
     // color interpolation just drags the midpoint, and the house curve's overshoot would
     // extrapolate past the target color.
@@ -181,39 +187,42 @@ export const variants = stylex.create({
   // fill, and leaves it independently themeable.
   'outline-primary': {
     borderColor: colorVars['--cl-color-border'],
-    backgroundColor: {
-      default: 'transparent',
-      ':not([data-disabled]):active': colorVars['--cl-color-neutral-alpha-200'],
-      ':not([data-disabled])[data-open]': colorVars['--cl-color-neutral-alpha-200'],
+    backgroundColor: colorVars['--cl-color-surface'],
+    boxShadow: {
+      default: null,
+      ':not([data-disabled]):active': neutralPressedWash,
+      ':not([data-disabled])[data-open]': neutralPressedWash,
       '@media (hover: hover)': {
         default: null,
-        ':not([data-disabled]):hover:not(:active):not([data-open])': colorVars['--cl-color-neutral-alpha-100'],
+        ':not([data-disabled]):hover:not(:active):not([data-open])': neutralHoverWash,
       },
     },
     color: colorVars['--cl-color-brand'],
   },
   'outline-neutral': {
     borderColor: colorVars['--cl-color-border'],
-    backgroundColor: {
-      default: 'transparent',
-      ':not([data-disabled]):active': colorVars['--cl-color-neutral-alpha-200'],
-      ':not([data-disabled])[data-open]': colorVars['--cl-color-neutral-alpha-200'],
+    backgroundColor: colorVars['--cl-color-surface'],
+    boxShadow: {
+      default: null,
+      ':not([data-disabled]):active': neutralPressedWash,
+      ':not([data-disabled])[data-open]': neutralPressedWash,
       '@media (hover: hover)': {
         default: null,
-        ':not([data-disabled]):hover:not(:active):not([data-open])': colorVars['--cl-color-neutral-alpha-100'],
+        ':not([data-disabled]):hover:not(:active):not([data-open])': neutralHoverWash,
       },
     },
     color: colorVars['--cl-color-foreground'],
   },
   'outline-negative': {
     borderColor: colorVars['--cl-color-border'],
-    backgroundColor: {
-      default: 'transparent',
-      ':not([data-disabled]):active': colorVars['--cl-color-neutral-alpha-200'],
-      ':not([data-disabled])[data-open]': colorVars['--cl-color-neutral-alpha-200'],
+    backgroundColor: colorVars['--cl-color-surface'],
+    boxShadow: {
+      default: null,
+      ':not([data-disabled]):active': negativePressedWash,
+      ':not([data-disabled])[data-open]': negativePressedWash,
       '@media (hover: hover)': {
         default: null,
-        ':not([data-disabled]):hover:not(:active):not([data-open])': colorVars['--cl-color-neutral-alpha-100'],
+        ':not([data-disabled]):hover:not(:active):not([data-open])': negativeHoverWash,
       },
     },
     color: colorVars['--cl-color-negative'],
@@ -248,11 +257,11 @@ export const variants = stylex.create({
   'ghost-negative': {
     backgroundColor: {
       default: 'transparent',
-      ':not([data-disabled]):active': `color-mix(in oklab, ${colorVars['--cl-color-negative-subtle']}, ${colorVars['--cl-color-negative']} 8%)`,
-      ':not([data-disabled])[data-open]': `color-mix(in oklab, ${colorVars['--cl-color-negative-subtle']}, ${colorVars['--cl-color-negative']} 8%)`,
+      ':not([data-disabled]):active': colorVars['--cl-color-negative-alpha-300'],
+      ':not([data-disabled])[data-open]': colorVars['--cl-color-negative-alpha-300'],
       '@media (hover: hover)': {
         default: null,
-        ':not([data-disabled]):hover:not(:active):not([data-open])': colorVars['--cl-color-negative-subtle'],
+        ':not([data-disabled]):hover:not(:active):not([data-open])': colorVars['--cl-color-negative-alpha-200'],
       },
     },
     color: colorVars['--cl-color-negative'],

packages/mosaic/src/components/card/card.styles.ts

@@ -187,7 +187,7 @@ export const footer = stylex.create({
     flexShrink: 0,
     gridTemplateColumns: { [compactCard]: 'minmax(0, 1fr)', default: null },
     justifyContent: 'space-between',
-    borderTopColor: colorVars['--cl-color-border'],
+    borderTopColor: colorVars['--cl-color-border-subtle'],
     borderTopStyle: 'solid',
     borderTopWidth: {
       default: '0px',
@@ -202,7 +202,7 @@ export const branding = stylex.create({
   base: {
     paddingBlock: space['3'],
     paddingInline: space['6'],
-    borderBlockStartColor: colorVars['--cl-color-border'],
+    borderBlockStartColor: colorVars['--cl-color-border-subtle'],
     borderBlockStartStyle: 'solid',
     borderBlockStartWidth: '1px',
     display: 'flex',

packages/mosaic/src/components/data-list/data-list.styles.ts

@@ -4,7 +4,7 @@ import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../
 
 export const list = stylex.create({
   base: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderRadius: radiusVars['--cl-radius-lg'],
     borderStyle: 'solid',
     borderWidth: '1px',
@@ -25,7 +25,7 @@ export const item = stylex.create({
     justifyContent: 'space-between',
   },
   divided: {
-    borderBlockEndColor: colorVars['--cl-color-border'],
+    borderBlockEndColor: colorVars['--cl-color-border-subtle'],
     borderBlockEndStyle: 'solid',
     borderBlockEndWidth: {
       default: '1px',

packages/mosaic/src/components/drawer/drawer.styles.ts

@@ -140,8 +140,8 @@ export const styles = stylex.create({
     // the pointer is captured on it, so `:active` survives the drag. A press elsewhere in the sheet
     // is not a press on the handle, and leaves it alone.
     '--_cl-grip-color': {
-      default: colorVars['--cl-color-border'],
-      ':active': `color-mix(in oklab, ${colorVars['--cl-color-border']}, ${colorVars['--cl-color-foreground-secondary']} 35%)`,
+      default: colorVars['--cl-color-border-subtle'],
+      ':active': `color-mix(in oklab, ${colorVars['--cl-color-border-subtle']}, ${colorVars['--cl-color-foreground-secondary']} 35%)`,
     },
     placeItems: 'center',
     display: 'grid',

packages/mosaic/src/components/icon/icon-frame.styles.ts

@@ -2,6 +2,8 @@ import * as stylex from '@stylexjs/stylex';
 
 import { colorVars, radiusVars, space } from '../../tokens.stylex';
 
+const filledWash = `light-dark(color-mix(in oklab, ${colorVars['--cl-color-neutral']} 3.5%, transparent), color-mix(in oklab, ${colorVars['--cl-color-neutral']} 4.5%, transparent))`;
+
 export const styles = stylex.create({
   base: {
     borderColor: 'transparent',
@@ -17,10 +19,10 @@ export const styles = stylex.create({
     justifyContent: 'center',
   },
   bordered: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
   },
   filled: {
-    backgroundColor: colorVars['--cl-color-neutral-alpha-100'],
+    backgroundColor: filledWash,
   },
 });
 

packages/mosaic/src/components/item/item.styles.ts

@@ -58,7 +58,7 @@ export const item = stylex.create({
   },
 
   outline: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderStyle: 'solid',
     borderWidth: '1px',
   },

packages/mosaic/src/components/menu/menu.styles.ts

@@ -176,7 +176,7 @@ export const separator = stylex.create({
     // Full-bleed across the popup: cancel the viewport's inline padding.
     marginBlock: space['0.5'],
     marginInline: `calc(-1 * ${space['0.5']})`,
-    backgroundColor: colorVars['--cl-color-border'],
+    backgroundColor: colorVars['--cl-color-border-subtle'],
     blockSize: '1px',
     flexShrink: 0,
   },

packages/mosaic/src/components/pagination/pagination.styles.ts

@@ -33,7 +33,7 @@ export const styles = stylex.create({
   controls: {
     gap: space['1'],
     alignItems: 'center',
-    borderBlockStartColor: colorVars['--cl-color-border'],
+    borderBlockStartColor: colorVars['--cl-color-border-subtle'],
     borderBlockStartStyle: 'solid',
     borderBlockStartWidth: { [compact]: '1px', default: 0 },
     display: { [compact]: 'grid', default: 'flex' },
@@ -55,7 +55,7 @@ export const styles = stylex.create({
     whiteSpace: 'nowrap',
   },
   divider: {
-    backgroundColor: colorVars['--cl-color-border'],
+    backgroundColor: colorVars['--cl-color-border-subtle'],
     display: { [compact]: 'none', default: 'block' },
     height: '1.25rem',
     width: '1px',

packages/mosaic/src/components/phone-input/phone-input.styles.ts

@@ -47,7 +47,7 @@ export const styles = stylex.create({
     width: space['4'],
   },
   divider: {
-    backgroundColor: colorVars['--cl-color-border'],
+    backgroundColor: colorVars['--cl-color-border-subtle'],
     flexShrink: 0,
     height: space['3.5'],
     width: '1px',
@@ -73,7 +73,7 @@ export const styles = stylex.create({
   countrySearchRow: {
     gap: space['1'],
     alignItems: 'center',
-    borderBlockEndColor: colorVars['--cl-color-border'],
+    borderBlockEndColor: colorVars['--cl-color-border-subtle'],
     borderBlockEndStyle: 'solid',
     borderBlockEndWidth: '1px',
     display: 'flex',

packages/mosaic/src/components/profile/profile.styles.ts

@@ -60,7 +60,7 @@ export const styles = stylex.create({
 
   // A fixed height so switching pages never resizes the surface.
   layout: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderRadius: {
       [compact]: 0,
       default: radiusVars['--cl-radius-xl'],
@@ -129,7 +129,7 @@ export const styles = stylex.create({
 
   nav: {
     padding: space['4'],
-    borderInlineEndColor: colorVars['--cl-color-border'],
+    borderInlineEndColor: colorVars['--cl-color-border-subtle'],
     borderInlineEndStyle: 'solid',
     borderInlineEndWidth: '1px',
     // Hidden in CSS too, so the column never shows on a phone before measuring.

packages/mosaic/src/components/section/section.styles.ts

@@ -44,7 +44,7 @@ export const styles = stylex.create({
     maxWidth: 'none',
   },
   body: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderRadius: radiusVars['--cl-radius-xl'],
     borderStyle: 'solid',
     borderWidth: '1px',
@@ -56,7 +56,7 @@ export const styles = stylex.create({
   },
   row: {
     paddingBlock: space['4'],
-    borderBlockStartColor: colorVars['--cl-color-border'],
+    borderBlockStartColor: colorVars['--cl-color-border-subtle'],
     borderBlockStartStyle: 'solid',
     borderBlockStartWidth: {
       default: '1px',
@@ -89,7 +89,7 @@ export const styles = stylex.create({
   },
   nestedItem: {
     paddingBlock: space['4'],
-    borderBlockStartColor: colorVars['--cl-color-border'],
+    borderBlockStartColor: colorVars['--cl-color-border-subtle'],
     borderBlockStartStyle: 'solid',
     borderBlockStartWidth: {
       default: '0px',

packages/mosaic/src/components/table/table.styles.ts

@@ -29,7 +29,7 @@ export const styles = stylex.create({
   search: { maxWidth: '100%', width: '17rem' },
   noWrap: { whiteSpace: 'nowrap' },
   shell: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderRadius: radiusVars['--cl-radius-xl'],
     borderStyle: 'solid',
     borderWidth: '1px',
@@ -72,7 +72,7 @@ export const styles = stylex.create({
         ':where([data-actionable]:not([data-selected]):hover)': colorVars['--cl-color-surface-subtle'],
       },
     },
-    borderBlockStartColor: colorVars['--cl-color-border'],
+    borderBlockStartColor: colorVars['--cl-color-border-subtle'],
     borderBlockStartStyle: 'solid',
     borderBlockStartWidth: '1px',
     cursor: { default: null, ':where([data-actionable])': 'pointer' },

packages/mosaic/src/components/tag-input/tag-input.styles.ts

@@ -60,7 +60,7 @@ export const styles = stylex.create({
     minWidth: 0,
   },
   tagInvalid: {
-    backgroundColor: colorVars['--cl-color-negative-alpha-100'],
+    backgroundColor: colorVars['--cl-color-negative-subtle'],
     color: colorVars['--cl-color-negative'],
   },
   tagLabel: {

packages/mosaic/src/components/toast/toast.styles.ts

@@ -162,11 +162,11 @@ export const styles = stylex.create({
 
 export const iconColors = stylex.create({
   success: {
-    backgroundColor: colorVars['--cl-color-positive-alpha-200'],
+    backgroundColor: colorVars['--cl-color-positive-subtle'],
     color: colorVars['--cl-color-positive'],
   },
   error: {
-    backgroundColor: colorVars['--cl-color-negative-alpha-200'],
+    backgroundColor: colorVars['--cl-color-negative-subtle'],
     color: colorVars['--cl-color-negative'],
   },
   loading: {

packages/mosaic/src/features/user-profile/user-profile-billing-history-section/user-profile-billing-history-section.styles.ts

@@ -66,7 +66,7 @@ export const styles = stylex.create({
     lineHeight: typeScaleVars['--cl-text-xs-leading'],
   },
   pageSizeSelect: {
-    borderColor: colorVars['--cl-color-border'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderRadius: radiusVars['--cl-radius-md'],
     borderStyle: 'solid',
     borderWidth: '1px',
@@ -82,7 +82,7 @@ export const styles = stylex.create({
     paddingBlock: space['2'],
     paddingInline: space['3'],
     alignItems: 'center',
-    borderBlockStartColor: colorVars['--cl-color-border'],
+    borderBlockStartColor: colorVars['--cl-color-border-subtle'],
     borderBlockStartStyle: 'solid',
     borderBlockStartWidth: '1px',
     display: 'flex',
@@ -94,7 +94,7 @@ export const styles = stylex.create({
     display: 'flex',
   },
   row: {
-    borderBlockStartColor: colorVars['--cl-color-border'],
+    borderBlockStartColor: colorVars['--cl-color-border-subtle'],
     borderBlockStartStyle: 'solid',
     borderBlockStartWidth: '1px',
   },