feat(ui): remap Mosaic Button onto color, variant, and size (#9282)

Author: maxyinger

.changeset/mosaic-button-variants.md

@@ -0,0 +1,2 @@
+---
+---

.claude/skills/mosaic/references/stylex.md

@@ -78,11 +78,29 @@ export const colorVars = stylex.defineVars(colorDefaults);
 - **DO** name internal, non-contract vars with a `--_cl-*` prefix (e.g. a value a
   parent writes for a child to read). They still emit verbatim but the `_` marks
   them "not a contract, don't override."
+- **DO** name a radius by **what the surface is**, not by size, so the steps nest:
+  `--cl-radius-inner` for a mark inside a control, `--cl-radius-control` for the
+  control itself (button, avatar square), `--cl-radius-container` for anything
+  wrapping controls. A role name survives a value change; `--cl-radius-md` doesn't.
 - **DO** compute tints at the call site with `color-mix()`, not as their own
   tokens. `color-mix(in oklab, ${primary}, ${fg} 12%)` beats minting
   `--cl-color-primary-hover-12`.
 - **DON'T** mint a per-step derivative token for something a `calc()`/`color-mix()`
   can express from an existing token.
+- **DO** build a fill that sits _on top of_ an unknown backdrop — a hover or pressed
+  wash on a transparent `outline`/`ghost` control — as a **scrim**: an opacity of
+  black-on-light / white-on-dark over `transparent`, not a percentage of a gray token.
+
+  ```ts
+  const step = `color-mix(in oklab, light-dark(oklch(0 0 0), oklch(1 0 0)) 12%, transparent)`;
+  ```
+
+  A gray token like `--cl-color-neutral` is a 900, not black, so the same percentage of
+  it lands lighter than the percentage of black — and by an amount that shifts with
+  whatever the control sits on, so the step numbers stop describing what they render.
+  The scrim composites, so one ramp reads consistently on every surface. This applies
+  to overlay fills only: a fill with a color of its own (`filled-primary`) still blends
+  from that color toward its own on-fill.
 
 **Spacing is one exposed var plus a `defineConsts` scale.** Only `--cl-spacing`
 is a custom property; every step is inlined at build as `calc(var(--cl-spacing) *
@@ -166,23 +184,119 @@ objects and compose them at the call site.
 - A helper that assembles a slot may **return an array** of atoms
   (`[base, direction[x], gap[n]]`) for the caller to spread into `stylex.props`.
 
+### Multiplying axes: flatten, don't plumb vars
+
+When two visual axes multiply (`color` × `variant`), the tempting move is to have
+one axis write custom properties and the other read them — 3 + 4 declarations
+instead of 12, with each axis staying independent. **Don't.**
+
+- **DON'T** declare custom properties inside a component's `stylex.create` to
+  decouple that component's own axes. They emit into the stylesheet and appear on
+  every instance in devtools, which reads as public API nobody agreed to support.
+  A `--cl-*` name is worse still — that prefix is reserved for the overridable
+  contract (see "Tokens").
+- **DON'T** reach for `defineVars` + `createTheme` to dodge that. The names get
+  hashed instead of `--cl-*`, but they still land in the inspector on every element.
+- **DO** flatten the cross product into one variant map keyed `<axis-a>-<axis-b>`,
+  indexed directly. A template-literal key makes an unhandled pair a compile error,
+  with no lookup map to maintain:
+
+  ```ts
+  const variants = stylex.create({
+    'filled-primary': {
+      /*…*/
+    },
+    'filled-negative': {
+      /*…*/
+    },
+    'outline-primary': {
+      /*…*/
+    },
+    // …one entry per cell
+  });
+  // <comp>.tsx — TS resolves the template against the literal keys
+  variants[`${variant}-${color}`];
+  ```
+
+  Each entry is self-contained, so a cell can be read and tuned straight against a
+  design matrix — which is usually the form these specs arrive in.
+
+- **DO** hoist a value shared across cells to a **same-file** `const`. StyleX
+  inlines it at build, so the duplication leaves the source without emitting a var:
+
+  ```ts
+  const primaryHover = `color-mix(in oklab, ${colorVars['--cl-color-primary']}, ${colorVars['--cl-color-primary-foreground']} 12%)`;
+  ```
+
+  Same-file is required — an imported one fails static evaluation ("Atoms" above).
+
+**Where a var is still right.** This rule is about a component plumbing values to
+itself. A custom property remains the correct tool when a value must cross an
+element boundary (a parent computes, a descendant reads) or collapse an unbounded
+dynamic value into a single atom — the `--_cl-*` cases in "Tokens" and sub-pattern
+A in "Dynamic styles". Those have no var-free equivalent; decoupling one element's
+own axes does.
+
+Flattening does scale multiplicatively, so for a genuinely large product reach for
+role atoms instead — each color exports the same role names (`solid`, `ink`,
+`tint`) and the variant picks which to apply. Still var-free, at the cost of an
+indirection the flattened map doesn't have.
+
 ### Conditions & state
 
 Use StyleX's conditional-value objects (a `default` plus pseudo / at-rule keys).
 
 ```ts
 backgroundColor: {
   default: colorVars['--cl-color-primary'],
-  ':active': `color-mix(in oklab, ${colorVars['--cl-color-primary']}, ${colorVars['--cl-color-primary-foreground']} 24%)`,
+  ':active': primaryActive,
   '@media (hover: hover)': {
-    // only the top-level value needs `default`; the nested block just adds `:hover`
-    ':hover': `color-mix(in oklab, ${colorVars['--cl-color-primary']}, ${colorVars['--cl-color-primary-foreground']} 12%)`,
+    // the media block contributes only the pseudo; the top-level `default` still
+    // paints the rest state. `:not(:active)` is load-bearing — see below.
+    default: null,
+    ':hover:not(:active)': primaryHover,
   },
 },
 ```
 
 - **DO** guard `:hover` behind `@media (hover: hover)` so it never sticks on touch;
   leave `:active`, `:focus-visible`, `:disabled` unguarded.
+
+#### A media-wrapped `:hover` outranks a bare `:active`
+
+StyleX encodes precedence by **repeating the class name**, and an at-rule adds
+priority. So a `@media (hover: hover)` `:hover` compiles to a doubled selector while
+a bare `:active` stays single — and the hover wins while the button is pressed:
+
+```css
+.x1ozrsgg:active {
+} /* 0,1,1 — loses */
+@media (hover: hover) {
+  .x1f1bnkq.x1f1bnkq:hover {
+  } /* 0,3,0 — wins during the press */
+}
+```
+
+The symptom is a hovered button that never shows its pressed colour on a mouse
+device, while touch devices look correct.
+
+- **DO** write the hover branch as `':hover:not(:active)'`. It stops the hover rule
+  **matching** during a press, so the fix rests on selector semantics rather than on
+  how StyleX happens to order equal-specificity rules.
+- **DO** keep the bare `':active'` outside the media query. It is the only pressed
+  state a no-hover device ever sees, since such a device never matches
+  `(hover: hover)`.
+- **DON'T** fix it by re-declaring `':active'` _inside_ the `@media` block. It does
+  work — both selectors end up doubled and StyleX emits `:active` after `:hover` —
+  but it depends on StyleX's emission order for the tiebreak and duplicates the
+  value in every cell.
+- Applies to any state pair where one side is inside an at-rule and the other is
+  not. Confirm the output rather than trusting it: `pnpm build:mosaic --filter @clerk/ui`,
+  then grep `dist-mosaic/styles.css` for the two selectors and compare their
+  specificity.
+
+Worked example: `packages/ui/src/mosaic/components/button/button.styles.ts`.
+
 - **DO** use `:focus-visible` for focus rings (never bare `:focus`). For a
   **container** that should ring when a child is focused, use
   `:has(:focus-visible)` — **not** `:focus-within`. `:focus-within` matches any
@@ -208,15 +322,59 @@ backgroundColor: {
   outlineOffset: { default: null, ':focus-visible': space['0.5'] },
   ```
 
-- **DO** gate every transition/animation on reduced motion, in the same object:
+- **DO** take durations from `durationVars` (`--cl-duration-instant` / `-fast` /
+  `-base` / `-slow` / `-slower`) rather than a literal, and vary them by state
+  where the feedback should read as more or less direct:
 
   ```ts
   transitionDuration: {
     default: durationVars['--cl-duration-fast'],
+    ':active': durationVars['--cl-duration-instant'],
+  },
+  ```
+
+- **DO** pick the timing function by **what the property does**, not by how long
+  it runs. Properties that move — `transform`, `translate`, `scale`, `rotate`,
+  insets — take `easingVars['--cl-ease-default']`, whose slight overshoot is what
+  sells the motion. Color and opacity take plain `linear`: their interpolation is
+  already perceptually non-uniform, so an ease on top only makes the midpoint
+  drag, and an overshoot extrapolates past the target color for nothing. A
+  transform at `--cl-duration-fast` still wants the curve.
+
+- **DO** gate transitions/animations of **motion-bearing** properties on reduced
+  motion — `transform`, `translate`, `scale`, `rotate`, positional insets — in the
+  same object. `prefers-reduced-motion` is a vestibular-safety signal, so color
+  and opacity transitions do **not** need it:
+
+  ```ts
+  transitionDuration: {
+    default: durationVars['--cl-duration-base'],
     '@media (prefers-reduced-motion: reduce)': '0.01ms',
   },
   ```
 
+- **DO** floor an interactive control's hit area at `targetVars['--cl-target-coarse']`
+  under `@media (pointer: coarse)`. Use `minHeight`/`minWidth` so the size axis stays
+  in charge otherwise, and give it its own atom rather than writing it into every
+  size — the floor is one physical constant, and a part that isn't really a control
+  (a `link` variant, which reads as text) opts out by not receiving the atom:
+
+  ```ts
+  touchTarget: {
+    minHeight: { default: null, '@media (pointer: coarse)': targetVars['--cl-target-coarse'] },
+  },
+  ```
+
+  Square controls need the floor on **both** axes, or the target grows tall and narrow.
+  `--cl-target-coarse` is deliberately off the `--cl-spacing` scale: a consumer
+  rescaling density must not shrink a touch target with it.
+
+- **DON'T** suppress interaction with `pointer-events: none` on a disabled control.
+  An element that isn't hit-tested supplies no cursor, so `cursor: not-allowed` never
+  renders, and a wrapping tooltip never gets the pointer to explain the disabled
+  state. Gate the interactive states on `:enabled` instead — `:hover`/`:active` still
+  match a disabled element, so every one of them needs the gate.
+
 - **DO** reflect runtime conditions the component owns (disabled, selected,
   invalid) as `data-<axis>` attrs via `themeProps`, in addition to the atom, so
   the state stays overridable in plain consumer CSS.
@@ -364,6 +522,7 @@ token colors aren't down-leveled into an invalid polyfill.
 
 - YES: `var()`, `calc()`, `color-mix()`, `light-dark()`, nested `@media`+pseudo,
   `:hover`/`:active`/`:focus-visible`/`:focus-within`/`:disabled`, `:has()`,
+  `:not()` and compound pseudo keys (`':hover:not(:active)'` compiles and lints),
   `::before`/`::after`/`::backdrop`, `@starting-style` (enter animations),
   `stylex.keyframes(...)`, `anchor-size(width|height)` (popover/menu matching its
   trigger), CSS counters, `@media (hover: hover)` / `(prefers-reduced-motion)` /

packages/swingset/src/stories/button.mdx

@@ -35,16 +35,90 @@ Button is the primary action element in Mosaic, used for form submissions and di
   storyModule={ButtonStories}
 />
 
+`size` sets the height, and under a coarse pointer every size floors at 44px instead — a
+fingertip is the same width whatever density the surrounding UI runs at, so the floor is a fixed
+`--cl-target-coarse` rather than a step on the spacing scale a consumer can rescale. Icon buttons
+take the floor on both axes, so a square button stays square rather than growing tall and narrow.
+`link` opts out entirely: it reads as text, not a control. None of this is visible on a mouse —
+it applies at `@media (pointer: coarse)`.
+
+### Variants
+
+<Story
+  name='Variants'
+  storyModule={ButtonStories}
+/>
+
+### Colors
+
+`color` and `variant` are independent: `color` picks the palette, `variant` decides how much of
+it to show. Every combination below is the same two props.
+
+Hover and focus are part of the matrix — hover a cell, or tab through it, to see them. `filled`
+shifts its fill and `link` underlines. `outline` and `ghost` share the same neutral hover fill,
+except `ghost` under `negative`, which is the one cell that tints by color. The focus ring is
+the same for every cell.
+
+<Story
+  name='Colors'
+  storyModule={ButtonStories}
+/>
+
 ### Shapes
 
 <Story
   name='Shapes'
   storyModule={ButtonStories}
 />
 
+### Icons
+
+An icon is a child, not a prop. Give it a `placement` and `Icon` reflects that as `data-icon`,
+which the button selects on to tighten the padding on that edge — pass icons on either side, or
+both, with nothing to declare on the button itself.
+
+<Story
+  name='Icons'
+  storyModule={ButtonStories}
+/>
+
+The tightened value isn't chosen by eye. An icon is centered in the button, so it already has
+`(height − icon size) / 2` of space above and below it; matching the inline side to that puts it
+in a square cell — 8px at every size, against 12px of text padding at `md` and `lg`, 10px at `sm`.
+The text side keeps the larger inset, since a run of text ends in a stem where an icon trails off.
+The middle button in each row below carries no icon, for comparison.
+
+<Story
+  name='IconSizes'
+  storyModule={ButtonStories}
+/>
+
+### Truncation
+
+A button sizes to its own content and doesn't shrink, so most of the time there's nothing to
+truncate. When its width _is_ constrained — `fullWidth` in a narrow container, or an explicit
+width — the label can't wrap to cope, because `size` fixes the height and a second line would
+grow out of the button. It stays on one line and ends in an ellipsis instead.
+
+Only text children truncate. Button wraps a text child in a span of its own to run the ellipsis
+against, since a bare text node is laid out in an anonymous box no selector can reach. Element
+children pass through as direct flex items, so an icon keeps its size and its padding while the
+label gives way around it.
+
+<Story
+  name='Truncation'
+  storyModule={ButtonStories}
+/>
+
 ### Disabled
 
 <Story
   name='Disabled'
   storyModule={ButtonStories}
 />
+
+A disabled button keeps its resting fill and dims — it doesn't fall back to a gray of its own, so
+which color and variant it is stays legible while it's unavailable. Hover and press are suppressed
+by the styles, not by `pointer-events`: the button stays hit-testable, which is what makes
+`cursor: not-allowed` render at all and what lets a wrapping tooltip explain _why_ it's disabled.
+That tooltip is worth adding — a disabled control with no explanation is a dead end.