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

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: prestonwebdev

.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,
   },
 });