From 7693a3f244a8972e738fa0efaba5d38bad878427 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 14:49:47 -0400
Subject: [PATCH 1/5] init

---
 .claude/skills/README.md                      |   9 +-
 .claude/skills/mosaic-stylex/SKILL.md         | 130 +++++++++
 .../mosaic-stylex/references/authoring.md     | 250 +++++++++++++++++
 .../skills/mosaic-stylex/references/build.md  | 116 ++++++++
 .../mosaic-stylex/references/migration.md     | 101 +++++++
 .../mosaic-stylex/references/organization.md  | 139 ++++++++++
 .../mosaic-stylex/references/overrides.md     | 150 +++++++++++
 .../references/relational-and-dynamic.md      | 138 ++++++++++
 .../references/tokens-and-theming.md          | 255 ++++++++++++++++++
 9 files changed, 1284 insertions(+), 4 deletions(-)
 create mode 100644 .claude/skills/mosaic-stylex/SKILL.md
 create mode 100644 .claude/skills/mosaic-stylex/references/authoring.md
 create mode 100644 .claude/skills/mosaic-stylex/references/build.md
 create mode 100644 .claude/skills/mosaic-stylex/references/migration.md
 create mode 100644 .claude/skills/mosaic-stylex/references/organization.md
 create mode 100644 .claude/skills/mosaic-stylex/references/overrides.md
 create mode 100644 .claude/skills/mosaic-stylex/references/relational-and-dynamic.md
 create mode 100644 .claude/skills/mosaic-stylex/references/tokens-and-theming.md

diff --git a/.claude/skills/README.md b/.claude/skills/README.md
index 0031ac9bc9c..dbebb0e3f54 100644
--- a/.claude/skills/README.md
+++ b/.claude/skills/README.md
@@ -41,7 +41,8 @@ Skills are Claude Code specific. Cursor does not read this directory; it uses `.
 
 ## Skills in this repo
 
-| Skill            | Use it for                                                                                                                              |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `clerk-monorepo` | Day-to-day work in the monorepo: setup, build/test loops, the package map, changesets, commits, PRs, breaking-change checks.            |
-| `mosaic`         | Mosaic flow UI: authoring machines, controllers, and views, and migrating a legacy component into the split (with parity verification). |
+| Skill            | Use it for                                                                                                                                                                        |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clerk-monorepo` | Day-to-day work in the monorepo: setup, build/test loops, the package map, changesets, commits, PRs, breaking-change checks.                                                      |
+| `mosaic`         | Mosaic flow UI: authoring machines, controllers, and views, and migrating a legacy component into the split (with parity verification).                                           |
+| `mosaic-stylex`  | Authoring StyleX for Mosaic: `stylex.create`/`props`, `--cl-*` tokens, the stable class + cascade-layer override contract, markers, build, and migrating off Emotion/`useRecipe`. |
diff --git a/.claude/skills/mosaic-stylex/SKILL.md b/.claude/skills/mosaic-stylex/SKILL.md
new file mode 100644
index 00000000000..5227c3ec3b6
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/SKILL.md
@@ -0,0 +1,130 @@
+---
+name: mosaic-stylex
+description: >-
+  Author and organize StyleX styles for Mosaic components. Use when writing a
+  component's styles with `stylex.create` / `stylex.props`, defining or consuming
+  design tokens (`defineVars` / `defineConsts` / `createTheme`), exposing the
+  stable public styling contract (stable `.cl-*` classes, `--cl-*` CSS variables,
+  `data-*` attributes, cascade layers), setting up relational/state styling
+  (markers + `stylex.when`), wiring the build (rollup/tsdown plugin, layers,
+  ESLint), or migrating a Mosaic component off Emotion/`useRecipe` onto StyleX.
+  The direction: compile-time atomic CSS, a shipped static stylesheet, and
+  consumer overrides through their own CSS instead of the `appearance` prop.
+---
+
+# StyleX for Mosaic
+
+Mosaic is pivoting its styling engine from **Emotion** (runtime CSS-in-JS,
+`useRecipe`/`appearance`) to **StyleX** (compile-time atomic CSS, a shipped
+static stylesheet). This skill is the how-to for authoring StyleX the Mosaic
+way. It is grounded in two sources:
+
+- The **astryx** design system (`../research/astryx`, ~350 `.stylex.ts` files) —
+  a mature, production StyleX design system. Its patterns are the reference.
+- The Clerk **mosaic-x POC** (`packages/ui/src/mosaic-x/`, PR #9189) and its
+  writeup `references/mosaic-stylex-migration.md` — the proven direction for
+  _this_ repo.
+
+## The contract we are building toward
+
+Four public-surface goals drive every decision. Consumers style Mosaic from
+**their own CSS**, never from an `appearance` prop:
+
+1. **Stable CSS variables** — `--cl-foreground`, `--cl-primary`, … default in
+   our sheet and a consumer overrides them with plain `:root { --cl-foreground: red }`.
+2. **Stable class names** — every button carries `.cl-button`; a consumer targets
+   `.cl-button { … }` in their CSS.
+3. **Stable data attributes** — variant/state reflected as `data-variant`,
+   `data-size`, etc. for scoped targeting (`.cl-button[data-variant='outline']`).
+4. **A shipped static stylesheet** (`mosaic.css`) imported once into a cascade
+   layer the consumer controls.
+
+StyleX gives us goals 1, 3, 4 natively. Goal 2 (stable classes) needs a specific
+technique — you attach your own plain `.cl-*` class alongside StyleX's atomic
+classes. See `references/overrides.md`.
+
+## The core authoring shape
+
+Every styled part follows the same three moves. Read this, then the references.
+
+```tsx
+import * as stylex from '@stylexjs/stylex';
+import { mergeProps, themeProps } from '../shared/naming'; // cl-* stable class + data-attr helpers
+import { colors, radius, space } from './tokens.stylex';
+
+// 1. stylex.create — base + each variant VALUE as its own style object.
+//    Variants are COMPOSED conditionally, not resolved by a recipe engine.
+const styles = stylex.create({
+  base: {
+    display: 'inline-flex',
+    borderRadius: radius['--cl-radius-md'],
+    // states live inside property values as { default, ':hover', … } — never as top-level keys
+    outline: { default: 'none', ':focus-visible': `2px solid ${colors['--cl-primary']}` },
+  },
+  filledPrimary: { backgroundColor: colors['--cl-primary'], color: colors['--cl-primary-foreground'] },
+  outline: { backgroundColor: 'transparent', borderColor: colors['--cl-border'] },
+  sizeSm: { paddingBlock: space['--cl-spacing'], fontSize: '0.75rem' },
+  disabled: { opacity: 0.5, cursor: 'not-allowed', pointerEvents: 'none' },
+});
+
+// 2. Infer props; provide variant defaults.
+export interface ButtonProps extends React.ComponentPropsWithRef<'button'> {
+  variant?: 'filled' | 'outline';
+  size?: 'sm' | 'md';
+}
+
+// 3. Compose in stylex.props(...); merge the stable class + data-attrs first,
+//    consumer className/style last (they win).
+export const Button = ({ variant = 'filled', size = 'md', disabled, className, style, ...rest }: ButtonProps) => (
+  <button
+    disabled={disabled}
+    {...mergeProps(
+      themeProps('button', { variant, size }), // → .cl-button + data-variant + data-size
+      stylex.props(
+        styles.base,
+        variant === 'filled' && styles.filledPrimary,
+        variant === 'outline' && styles.outline,
+        size === 'sm' && styles.sizeSm,
+        disabled && styles.disabled,
+      ),
+      className,
+      style,
+    )}
+    {...rest}
+  />
+);
+```
+
+Three ideas make this different from the Emotion/`useRecipe` model you may know:
+
+- **Variants are conditional composition, not a recipe engine.** There is no
+  `defineSlotRecipe`, no `variants` map resolved at runtime, no `compoundVariants`
+  DSL. You write `cond && styles.x` in `stylex.props(...)`. Last wins.
+- **State is `{ default, ':hover', … }` inside a property value**, compiled into
+  the sheet — not a `_hover` condition key resolved at runtime. (Consumers still
+  override state through their own `.cl-*` CSS.)
+- **The stable `.cl-*` class + `data-*` attrs are the public API**, emitted by
+  `themeProps` and fused with StyleX's atomic classes by `mergeProps`. Consumers
+  never see the atomic `x…` hashes.
+
+## Which reference to read
+
+| You are…                                                                          | Read                                   |
+| --------------------------------------------------------------------------------- | -------------------------------------- |
+| Writing a component's styles (create/props, variants, states, composition)        | `references/authoring.md`              |
+| Defining or consuming tokens (`--cl-*` vars, `defineVars`/`defineConsts`, themes) | `references/tokens-and-theming.md`     |
+| Exposing/overriding the public contract (stable classes, cascade layers)          | `references/overrides.md`              |
+| Naming files, splitting styles, exports, the `naming`/`mergeProps` helpers        | `references/organization.md`           |
+| Parent/sibling/state scoping (markers + `stylex.when`), dynamic, keyframes        | `references/relational-and-dynamic.md` |
+| Setting up the build, ESLint, and distribution                                    | `references/build.md`                  |
+| Migrating a component off Emotion/`useRecipe`                                     | `references/migration.md`              |
+
+## Hard rules (apply everywhere)
+
+- **Reference tokens, never hardcode** colors, spacing, radius, or type. `colors['--cl-foreground']`, not `'#000'`. Hardcoding breaks theming.
+- **No top-level pseudo-classes or media queries.** Nest them inside property values: `{ default, ':hover', '@media …' }`.
+- **No `style` or `className` alongside a raw `stylex.props()` spread on the same element** — route both through `mergeProps` so they merge correctly.
+- **`defineVars`/`defineConsts` live only in `*.stylex.ts` files**, named exports only, no other exports in the file.
+- **Longhand over shorthand** (`paddingBlock`/`paddingInline`, not `padding`); `null` unsets a property.
+- **StyleX styles the element they're on — no child/descendant selectors.** Style each part on its own element; drive cross-element state by composing style objects or using markers (`references/relational-and-dynamic.md`).
+- **Never document or let consumers target the atomic `x…` hashes** — they change every build. The stable surface is `.cl-*`, `--cl-*`, and `data-*` only.
diff --git a/.claude/skills/mosaic-stylex/references/authoring.md b/.claude/skills/mosaic-stylex/references/authoring.md
new file mode 100644
index 00000000000..fd5dc52ce5c
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/references/authoring.md
@@ -0,0 +1,250 @@
+# Authoring component styles with StyleX
+
+The StyleX authoring API is small. This file is the distilled version plus the
+patterns astryx uses at scale. Full upstream reference: the StyleX LLM authoring
+guide at https://stylexjs.com/docs/llm-resources.
+
+## `stylex.create` — define styles as named namespaces
+
+```tsx
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+  base: { display: 'inline-flex', alignItems: 'center', paddingBlock: 8 },
+  title: { fontSize: 24, fontWeight: 'bold' },
+});
+```
+
+- **Longhand + single-value shorthands only.** `paddingBlock`/`paddingInline`,
+  `marginInlineStart`, `borderColor` — not `padding`, `margin`, `border`. Multi-value
+  shorthands (`border: '1px solid red'` used as a single value where you'd also set
+  `borderColor` elsewhere) fight the atomic model. `borderWidth`/`borderStyle`/`borderColor`
+  as three keys is fine.
+- **Length values are pixels by default** (`paddingBlock: 8` → `8px`).
+- **`null` unsets a property** — useful in a "reset" namespace or a `default` branch.
+
+## `stylex.props` — turn namespaces into `{ className, style }`
+
+```tsx
+<div {...stylex.props(styles.base, styles.title)} />
+```
+
+Multiple namespaces merge; **last wins** on conflict. Falsy entries are ignored,
+which is the whole variant mechanism:
+
+```tsx
+stylex.props(
+  styles.base,
+  isActive && styles.active, // boolean && namespace
+  variant === 'primary' ? styles.primary : styles.secondary,
+  xstyle, // caller override, always last
+);
+```
+
+In Mosaic you rarely call `stylex.props` bare on a public element — wrap it with
+`mergeProps` so the stable `.cl-*` class, `data-*` attrs, and consumer
+`className`/`style` fuse in one place (see `organization.md`). `stylex.props`
+bare is fine on **internal** elements that carry no public contract.
+
+## Variants = conditional composition (no recipe engine)
+
+There is no `defineSlotRecipe`/`variants` map. A variant is one style namespace
+per value, selected by indexed lookup or a boolean condition. Two idioms, both
+from astryx:
+
+**Indexed lookup** — the variant prop is the key:
+
+```tsx
+const variants = stylex.create({
+  primary: { backgroundColor: colors['--cl-primary'], color: colors['--cl-primary-foreground'] },
+  secondary: { backgroundColor: colors['--cl-secondary'] },
+  ghost: { backgroundColor: 'transparent' },
+});
+
+const sizeStyles = stylex.create({
+  sm: { height: sizes['--cl-size-sm'], paddingInline: space['--cl-spacing'] },
+  md: { height: sizes['--cl-size-md'] },
+});
+
+// apply
+stylex.props(styles.base, variants[variant], sizeStyles[size], xstyle);
+```
+
+Type the axis from the map so props stay in sync:
+
+```tsx
+export type ButtonSize = keyof typeof sizeStyles; // 'sm' | 'md'
+```
+
+**Boolean / compound conditions** — for multi-axis and compound cases, just
+`&&`-compose. This replaces `compoundVariants`:
+
+```tsx
+stylex.props(
+  styles.base,
+  variant === 'filled' && intent === 'primary' && styles.filledPrimary,
+  variant === 'filled' && intent === 'destructive' && styles.filledDestructive,
+  variant === 'outline' && styles.outline,
+  disabled && styles.disabled,
+  xstyle,
+);
+```
+
+**Repeated indexed scales** (spacing/gap) — build the map once, key by the step:
+
+```tsx
+const gapStyles = stylex.create({
+  0: { columnGap: space['--cl-spacing-0'], rowGap: space['--cl-spacing-0'] },
+  1: { columnGap: space['--cl-spacing-1'], rowGap: space['--cl-spacing-1'] },
+  2: { columnGap: space['--cl-spacing-2'], rowGap: space['--cl-spacing-2'] },
+});
+export type SpacingStep = keyof typeof gapStyles;
+```
+
+## State styling: nest inside property values
+
+Pseudo-classes and media queries are **values keyed by their selector**, never
+top-level namespace keys. `default` is required when any conditional key is present.
+
+```tsx
+const styles = stylex.create({
+  button: {
+    backgroundColor: {
+      default: colors['--cl-primary'],
+      ':hover': `color-mix(in oklab, ${colors['--cl-primary']}, ${colors['--cl-primary-foreground']} 12%)`,
+      ':active': `color-mix(in oklab, ${colors['--cl-primary']}, ${colors['--cl-primary-foreground']} 24%)`,
+      ':disabled': colors['--cl-muted'],
+    },
+    cursor: { default: 'pointer', ':disabled': 'not-allowed' },
+    // media as a value; nest a media query under a pseudo when both apply
+    outline: {
+      default: 'none',
+      ':focus-visible': `2px solid ${colors['--cl-primary']}`,
+    },
+    transitionDuration: {
+      default: motion['--cl-duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+  },
+});
+```
+
+Common recommended states: `:hover`, `:active`, `:focus`, `:focus-visible`,
+`:focus-within`, `:disabled`. Gate `:hover` behind `@media (hover: hover)` when
+you don't want it firing on touch (astryx does this consistently):
+
+```tsx
+backgroundColor: {
+  default: colors['--cl-primary'],
+  ':hover': { '@media (hover: hover)': colors['--cl-primary-hover'] },
+},
+```
+
+That nested `':hover' → '@media (hover: hover)'` is the StyleX equivalent of
+Emotion Mosaic's `_hover: ['@media (hover: hover)', '&:hover']` condition
+(`packages/ui/src/mosaic/conditions.ts`). There is **no runtime condition map** in
+StyleX — you don't register `_hover` and expand it later; you write the gate
+inline per property. The compiled selector (`@media (hover: hover) { &:hover }`)
+is identical. Key order doesn't affect output, but pseudo-outer / media-inner is
+the convention. What you give up: the gate isn't applied automatically, and it's
+overridden through consumer CSS (`.cl-button:hover { … }`), not a merged `_hover`
+key.
+
+Keep the gate DRY by hoisting the media string to a `defineConsts` (its values
+are valid as **nested keys**, and it inlines at compile time — no runtime var):
+
+```tsx
+// media.stylex.ts
+export const media = stylex.defineConsts({ hover: '@media (hover: hover)' });
+```
+
+```tsx
+import { media } from './media.stylex';
+backgroundColor: {
+  default: colors['--cl-primary'],
+  ':hover': { [media.hover]: colors['--cl-primary-hover'] },
+},
+```
+
+You **cannot** wrap this in a runtime helper (`_hover(value)`) called inside
+`stylex.create` — the compiler statically evaluates the `create` argument, so the
+nested object literal (optionally with the `defineConsts` key) is the ceiling for
+reuse. The auto-applied, appearance-overridable `_hover` was the Emotion model;
+the StyleX trade is explicit, compiled gates.
+
+`color-mix(...)` and `calc(...)` work inside values (verified in the POC), which
+is how you derive hover/active shades without a runtime `theme.mix()` helper.
+
+**Prefer JS/prop changes over `:first-child`/`:nth-child`** and **prefer real
+elements over `::before`/`::after`** — both bloat the atomic sheet and hurt a11y.
+
+## Pseudo-elements
+
+Top-level keys within a namespace (unlike pseudo-classes, which are value-nested):
+
+```tsx
+const styles = stylex.create({
+  input: {
+    color: colors['--cl-foreground'],
+    '::placeholder': { color: colors['--cl-muted-foreground'] },
+    '::selection': { backgroundColor: colors['--cl-primary'] },
+  },
+});
+```
+
+## Accepting style overrides from a parent
+
+Type a passthrough prop as `StyleXStyles` and place it **last** so it overrides:
+
+```tsx
+import type { StyleXStyles } from '@stylexjs/stylex';
+
+type Props = { xstyle?: StyleXStyles };
+stylex.props(styles.base, variants[variant], xstyle); // xstyle wins
+```
+
+Constrain or exclude properties when a slot must not be re-laid-out:
+
+```tsx
+import type { StyleXStyles, StyleXStylesWithout } from '@stylexjs/stylex';
+type ColorOnly = StyleXStyles<{ color?: string; backgroundColor?: string }>;
+type NoLayout = StyleXStylesWithout<{ margin: unknown; padding: unknown; width: unknown }>;
+```
+
+Note: an `xstyle` typed as `StyleXStyles` accepts **StyleX styles only** — it is
+not the free-form `sx` object from Emotion Mosaic. Arbitrary runtime styles are
+gone; see `migration.md`.
+
+## Composition across parts
+
+Compound components layer styles per element. A layout helper returns an array of
+namespaces that the caller spreads — astryx's `stack()`/`container()` pattern:
+
+```tsx
+export function stack({ direction, gap }: StackOptions) {
+  return [baseStyles.stack, directionStyles[direction], gap != null && gapStyles[gap]] as const;
+}
+
+// caller
+stylex.props(...stack({ direction, gap }), xstyle);
+```
+
+Icon sizing and other sub-parts get their own indexed map, applied on the child
+element:
+
+```tsx
+const iconSizeStyles = stylex.create({ sm: { width: 16, height: 16 }, md: { width: 20, height: 20 } });
+<span {...stylex.props(styles.iconWrapper, iconSizeStyles[size])}>{icon}</span>;
+```
+
+## Antipatterns (StyleX will fight you or silently misbehave)
+
+- **Top-level pseudo/media keys** in a namespace — invalid. Nest inside a value.
+- **Importing non-StyleX constants** into a style value (`padding: MY_CONST`) —
+  use a token (`space['--cl-spacing']`) or a `defineConsts` value.
+- **`className`/`style` alongside a bare `stylex.props()` spread** — route through
+  `mergeProps`.
+- **Child/descendant/self-attribute selectors** (`& > div`, `&[data-selected]`) —
+  unsupported. Compose a variant style object driven by the prop instead, or use a
+  marker for genuine ancestor/sibling relationships (`relational-and-dynamic.md`).
+- **Multi-value shorthands** where atomic merging matters — prefer longhands.
diff --git a/.claude/skills/mosaic-stylex/references/build.md b/.claude/skills/mosaic-stylex/references/build.md
new file mode 100644
index 00000000000..c37283d4775
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/references/build.md
@@ -0,0 +1,116 @@
+# Build, ESLint & distribution
+
+StyleX is a compiler. It transforms `stylex.*` calls into atomic classes +
+`defineVars` into custom properties and extracts everything to one static `.css`.
+The only runtime is a tiny `stylex.props()` class-joiner.
+
+## Build wiring (the POC, verified)
+
+The Clerk POC compiles `src/mosaic-x` with the StyleX **rollup** plugin inside the
+existing `tsdown` (rolldown) build, isolated from the Emotion build so nothing
+else is touched:
+
+```ts
+// tsdown.mosaic-x.config.mts
+import stylexPlugin from '@stylexjs/rollup-plugin';
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['./src/mosaic-x/index.ts'],
+  outDir: './dist-mosaic-x',
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  platform: 'browser',
+  tsconfig: './tsconfig.mosaic-x.json', // jsxImportSource back to 'react' (Emotion-free)
+  external: ['react', 'react-dom', '@stylexjs/stylex'],
+  plugins: [stylexPlugin({ fileName: 'mosaic.css', useCSSLayers: true })],
+});
+```
+
+- The rollup plugin bundles its own TS/JSX Babel syntax plugins — no
+  `@babel/preset-*` needed on this path. The oxc/tsdown pass strips types and
+  lowers JSX; the StyleX plugin transforms the `stylex.*` calls.
+- Output: `dist-mosaic-x/{index.js, index.d.ts, mosaic.css}`.
+- Deps: `@stylexjs/stylex` (dependency), `@stylexjs/rollup-plugin` (devDependency).
+- **`jsxImportSource` matters** — the `@clerk/ui` package defaults JSX to
+  `@emotion/react`. mosaic-x overrides it back to `react` in its own tsconfig so
+  the output is genuinely Emotion-free.
+
+Run it: `cd packages/ui && pnpm build:mosaic-x`, then open
+`src/mosaic-x/demo.html` for the override proof.
+
+## Key StyleX compiler options (astryx's babel config)
+
+If a Babel-based pipeline is used instead of the rollup plugin, these are the
+options that matter (from astryx `packages/core/babel.config.json`):
+
+```jsonc
+[
+  "@stylexjs/babel-plugin",
+  {
+    "dev": false, // production: no dev runtime / readable-name overhead
+    "runtimeInjection": false, // styles extracted to CSS at build, not injected at runtime
+    "genConditionalClasses": true, // REQUIRED for stylex.when.* (markers / relational)
+    "treeshakeCompensation": true, // re-adds styles a tree-shake would wrongly drop
+    "unstable_moduleResolution": { "type": "commonJS", "rootDir": "." },
+  },
+]
+```
+
+- `genConditionalClasses: true` — without it, markers/`stylex.when` don't compile.
+- `treeshakeCompensation: true` — pair with `sideEffects` in package.json.
+- `dev: true` in local dev gives readable, debuggable class names.
+
+## Cascade layers
+
+Keep **`useCSSLayers: true`**. StyleX wraps its atomic rules in
+`@layer priority1, priority2, …` for correct intra-StyleX precedence. Those nest
+under whatever outer layer the consumer imports our sheet into — see
+`overrides.md`. We do **not** engineer consumer override precedence; layers make
+it the consumer's job (`@import '@clerk/ui/mosaic.css' layer(components)`).
+
+For a global reset, mirror astryx's layer order: `reset` → `<ns>-base` →
+`<ns>-theme`, with unlayered consumer styles always winning. Keep the reset in the
+lowest-priority layer.
+
+## ESLint — enforce tokens & valid styles
+
+Two layers of linting:
+
+1. **`@stylexjs/eslint-plugin`** — the official rules:
+   - `valid-styles` — catches invalid style objects (top-level pseudos, bad values).
+   - `no-unused` — flags dead style namespaces.
+   - `valid-shorthands` — warns on multi-value shorthands.
+   - `sort-keys` — deterministic key order.
+2. **A repo rule enforcing token usage** (astryx ships an internal
+   `no-hardcoded-styles` rule): reject literal `color`/`backgroundColor`,
+   `padding`/`margin`, `borderRadius`, `fontSize`/`fontWeight`/`lineHeight` values
+   and require the matching `--cl-*` token. Run as warnings locally, errors in CI.
+
+The POC also adds a lint rule keeping the stable class (`'cl-button'`) a literal —
+it's a public contract, not a derived identifier.
+
+## Distribution model
+
+**Precompiled (the model for Clerk).** We run StyleX at _our_ build and publish
+transformed JS + a static `mosaic.css`. Consumers import components normally and
+import the stylesheet once into a layer they control. **Zero StyleX config
+downstream.** This fits how `@clerk/ui` is consumed (framework SDKs + injected
+into clerk-js).
+
+Source distribution (shipping `.stylex.ts` and requiring every consumer to run the
+StyleX plugin) is **not viable** — consumers are arbitrary Next/Vite/etc. apps we
+don't control.
+
+### Open build questions (from the migration spike)
+
+- **clerk-js load path.** clerk-js is a runtime-injected rspack UMD bundle, not an
+  npm import. A static `mosaic.css` needs an explicit load/inject path there
+  (today Mosaic styles are runtime-injected by Emotion). Biggest unknown.
+- **Double atomization.** A consumer that also uses StyleX won't dedupe against our
+  precompiled atoms (two outputs). Harmless with layers, slightly larger CSS —
+  document it.
+- **Migration coexistence.** During the window, Emotion Mosaic and StyleX Mosaic
+  share the DOM; reconcile the reset (`:where([data-cl-slot])`) and layer order so
+  neither stomps the other.
diff --git a/.claude/skills/mosaic-stylex/references/migration.md b/.claude/skills/mosaic-stylex/references/migration.md
new file mode 100644
index 00000000000..285598fb9e9
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/references/migration.md
@@ -0,0 +1,101 @@
+# Migrating a component off Emotion/`useRecipe`
+
+Mosaic today authors styles with Emotion: `defineSlotRecipe` + `useRecipe`/
+`useSlot`, an `appearance` prop (`variables` + `elements`), `data-cl-*`
+attributes, and the `_hover`/`_disabled` condition vocabulary, all resolved at
+runtime inside `MosaicProvider`'s Emotion cache. The StyleX target replaces that
+whole engine with compile-time atomic CSS and a CSS-first override contract.
+
+This is a **model change, not a mechanical port.** Read
+`references/mosaic-architecture.md` (repo root) for the Emotion model you're
+leaving and `references/mosaic-stylex-migration.md` for the full spike writeup.
+
+## What goes away
+
+The entire runtime styling engine is removed or rebuilt:
+
+- `slot-recipe.ts` (`defineSlotRecipe`, `useRecipe`, `RecipeVariantProps`),
+  `useSlot.ts` / `slot()`, `resolveSlot.ts`, `conditions.ts`, `registry.ts`.
+- `appearance.ts` and the whole `appearance` prop (`variables` + `elements` +
+  per-flow `scope`). Public surface — coordinate as a breaking change.
+- The Emotion cache and SSR plumbing in `MosaicProvider` (insertion point,
+  `<Global>`, hydration dance) — StyleX ships static CSS, so these vanish.
+
+## The mapping
+
+| Concern           | Emotion Mosaic (today)                                     | StyleX Mosaic (target)                                             |
+| ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
+| Author variants   | `defineSlotRecipe({ variants, compoundVariants })`         | `stylex.create` + conditional composition in `stylex.props(...)`   |
+| Resolve + attach  | `useRecipe(recipe, { variants, state, sx })` → `{...root}` | `mergeProps(themeProps(...), stylex.props(...), className, style)` |
+| Token override    | `appearance.variables`                                     | `:root { --cl-*: … }` in consumer CSS                              |
+| Element override  | `appearance.elements[slot]`                                | `.cl-<slot> { … }` in consumer CSS                                 |
+| Variant targeting | `data-cl-<axis>` attrs                                     | `data-<axis>` attrs + stable `.cl-<slot>` class                    |
+| State targeting   | `_hover` / `_disabled` condition keys                      | value-nested `:hover`/`:disabled`; `.cl-*` for consumer override   |
+| Per-flow scoping  | `appearance.elements[scope][slot]`                         | consumer scopes with their own selectors                           |
+| `sx` escape hatch | free-form Emotion object                                   | `xstyle?: StyleXStyles` (StyleX styles only) or a token            |
+| Delivery          | runtime `<style>` via Emotion cache                        | static `mosaic.css` imported once                                  |
+
+## Step-by-step
+
+1. **Recipe → `stylex.create`.** Turn `base` into a `base` namespace. Turn each
+   variant **value** into its own namespace (`variants.intent.primary` →
+   `filledPrimary`). `compoundVariants` become `&&`-composed conditions in
+   `stylex.props(...)`.
+2. **Tokens.** Rewrite `theme.color.primary` → `colors['--cl-primary']`,
+   `theme.rounded.md` → `radius['--cl-radius-md']`, `theme.spacing(2)` →
+   `s(2)`/indexed scale. Runtime helpers (`theme.mix`, `theme.alpha`) become
+   `color-mix(...)`/`calc(...)` expressions inside values, or new tokens.
+3. **State.** `_hover: {...}` / `_disabled: {...}` condition blocks become
+   value-nested pseudos: `backgroundColor: { default, ':hover', ':disabled' }`.
+4. **`useRecipe` → compose + merge.** Replace `const { root } = useRecipe(...)`
+   and `{...root}` with a `stylex.props(...)` composition wrapped in
+   `mergeProps(themeProps('<slot>', { variant, size }), …, className, style)`.
+   Infer props from a plain interface (no `RecipeVariantProps`).
+5. **Multi-slot / child selectors.** If the recipe styled multiple slots or used
+   `& > x` / `&[data-cl-selected]`, split styling onto each element and drive
+   cross-element state by composing style objects from props, or a marker
+   (`relational-and-dynamic.md`). **No child/self-attribute selectors survive.**
+6. **Registry.** Delete the `declare module '../registry'` slot augmentation —
+   there is no runtime registry; the stable class literal in `themeProps('button', …)`
+   is the slot identity now.
+7. **Provider.** The component no longer needs `MosaicProvider` for styling.
+   Themes are `--cl-*` values delivered as plain CSS (or `createTheme` for
+   subtree-scoped runtime theming).
+
+## Things that require real restructuring (not a rename)
+
+- **Runtime-computed styles** — anything Mosaic computes per-render
+  (`theme.mix(a, b, n)`, arbitrary `sx` objects, JS-derived values). Each must
+  become a **token**, a **precompiled variant**, or a CSS `var()`/`color-mix()`
+  expression. There is no runtime style computation in StyleX beyond simple
+  `(param) => ({...})` dynamic styles.
+- **`appearance.elements` consumers** lose programmatic overrides and the `scope`
+  cascade — they move to CSS. This is intended, but it's a real ergonomics loss
+  for programmatic theming; call it out when migrating a flow that relied on it.
+- **Nested/attribute self-selectors** (`tabs.tsx`'s `&[data-cl-selected]`) — state
+  must become a composed variant (`isSelected && styles.selected`), not a selector.
+
+## Sequencing
+
+Mosaic is greenfield/unused, so the model can change freely. Two viable paths:
+
+1. **Component-by-component behind the isolated build** (`src/mosaic-x`, its own
+   tsdown config) while the Emotion engine still exists — lowest risk, lets you
+   validate the harder cases first.
+2. **Single cutover** once the engine is ported.
+
+The spike's recommended next proof points before committing: port a **multi-part**
+component (e.g. `tabs`) to exercise the no-child-selector / state-as-variant
+constraints, and resolve the **clerk-js stylesheet load path** (`build.md`, open
+questions). Those two retire the remaining real risk.
+
+## Verify a migration
+
+- Build the isolated target (`pnpm build:mosaic-x`) and confirm `mosaic.css`
+  contains the expected `--cl-*` defaults in `:root` and the component's atomic
+  rules under `@layer priorityN`.
+- Confirm the three override paths work from plain consumer CSS: a `--cl-*` token
+  override, a `.cl-<slot>` rule, and a `.cl-<slot>[data-<axis>='…']` scoped rule
+  (the POC's `demo.html` is the template).
+- Diff rendered output: the public element carries `class="cl-<slot> … <atoms>"`
+  plus `data-*` attrs, and consumer `className`/`style` are preserved and win.
diff --git a/.claude/skills/mosaic-stylex/references/organization.md b/.claude/skills/mosaic-stylex/references/organization.md
new file mode 100644
index 00000000000..d8e5cb9736f
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/references/organization.md
@@ -0,0 +1,139 @@
+# File organization, naming & exports
+
+How astryx keeps ~350 `.stylex.ts` files navigable. Adopt the same conventions.
+
+## File naming
+
+| File                       | Holds                                                                                                             |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `tokens.stylex.ts`         | `defineVars`/`defineConsts` — the token surface (see tokens ref)                                                  |
+| `<name>.stylex.ts`         | Shared/large style sets extracted from a component (`text.stylex.ts`, `inputStyles.stylex.ts`, `stack.stylex.ts`) |
+| `<name>.markers.stylex.ts` | `stylex.defineMarker()` scopes for relational styling (see relational ref)                                        |
+| `<Component>.tsx`          | The component; small/component-local styles inline via `stylex.create`                                            |
+| `index.ts`                 | Named re-exports (component + types), no default exports                                                          |
+
+- `.stylex.ts` is **required** for any file calling `defineVars`/`defineConsts`/
+  `defineMarker` — the compiler keys off the suffix.
+- kebab or camel basename, `.stylex.ts` suffix. Export const names are plural by
+  concern (`colors`, `spacingVars`) for token groups, `styles` for a component's
+  local `create` call.
+
+## Inline vs. extracted styles
+
+- **Inline in the `.tsx`** when styles are component-specific and roughly under
+  ~150 lines. A simple Button/Badge keeps its `stylex.create` at the top of the
+  file.
+- **Extract to `<name>.stylex.ts`** when:
+  - the styles are **shared** across components (input field styles used by
+    TextInput, Selector, Typeahead → `inputStyles.stylex.ts`), or
+  - a single component's styles grow large (`text.stylex.ts` at ~350 lines with
+    11 `create` calls), or
+  - they're a reusable **layout utility** returning an array of namespaces
+    (`stack()`, `container()`).
+
+Past ~1000 lines in any file, decompose. Keep each file focused.
+
+## The `naming` module (single source of truth)
+
+The `cl` namespace appears in class names, data attributes, and CSS variables. It
+must live in **one** place, imported by both the runtime and any build/CLI
+tooling. astryx centralizes this in `naming.ts`; do the same:
+
+```ts
+// naming.ts
+export const NAMESPACE = 'cl';
+export const stableClassName = (component: string) => `${NAMESPACE}-${component}`; // .cl-button
+export const dataAttr = (name: string) => `data-${name}` as const; // data-variant
+export const cssVar = (name: string) => `--${NAMESPACE}-${name}`; // --cl-*
+```
+
+Then `themeProps`/`mergeProps` (see `overrides.md`) build on it. Never scatter
+`'cl-'` literals across components — one exception is the **stable class literal
+passed to `themeProps('button', …)`**, which is intentionally a literal per
+component (it's the public contract for that part; astryx and the POC both keep it
+literal, optionally lint-enforced).
+
+## Exports & tree-shaking
+
+**Named exports only, no barrels that create cycles.** astryx exposes each
+component as its own subpath export and marks style files as side-effectful so
+they're never tree-shaken away:
+
+```jsonc
+// package.json
+{
+  "sideEffects": ["**/*.stylex.ts", "**/*.stylex.js", "**/*.css"],
+  "exports": {
+    ".": { "source": "./src/index.ts", "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./tokens.stylex": { "source": "./src/mosaic-x/tokens.stylex.ts", "default": "./dist/.../tokens.stylex.js" },
+    "./mosaic.css": { "default": "./dist-mosaic-x/mosaic.css" },
+  },
+}
+```
+
+`sideEffects` for `*.stylex.ts`/`*.css` is **not optional** — StyleX/CSS files
+register global styles; tree-shaking them drops styles from the sheet.
+
+Component `index.ts`:
+
+```ts
+export { Button } from './button';
+export type { ButtonProps } from './button';
+```
+
+## Directory shape (per component)
+
+Mirror astryx's per-component folder:
+
+```text
+Button/
+  Button.tsx                 // component + inline styles.create (if small)
+  buttonStyles.stylex.ts     // only if extracted
+  button.markers.stylex.ts   // only if it needs relational scoping
+  Button.test.tsx
+  index.ts                   // named re-exports
+```
+
+In the current Clerk POC everything sits flat in `packages/ui/src/mosaic-x/`
+(`button.tsx`, `tokens.stylex.ts`, `props.ts`, `index.ts`). As the surface grows,
+move to per-component folders like astryx.
+
+## Companion helpers worth porting from astryx
+
+Beyond `naming` / `themeProps` / `mergeProps` (see `overrides.md`), a handful of
+astryx utilities pay off in a StyleX component library. They aren't StyleX-specific
+but they're what makes StyleX components composable:
+
+- **`mergeRefs(...refs)`** — one callback ref that forwards to all inputs (and
+  honors React 19 ref-cleanup return values). Pairs with `mergeProps` whenever a
+  `forwardRef` component also needs an internal ref (tooltip trigger, measure, focus
+  management).
+- **`composeEventHandlers(a, b)`** — run a consumer handler and the component's own
+  handler for the same event, short-circuiting if one calls `preventDefault()`.
+  Consumer-first lets consumers opt out of built-in behavior; component-first makes
+  built-in behavior always run. Essential once components own interactions but also
+  spread `{...rest}`.
+- **`SizeContext` + `useSize(sizeProp, 'md')`** — cascade a default size from a
+  container (a Toolbar, ButtonGroup, Card header) to interactive children. Explicit
+  prop wins, then inherited context, then the default. This is the clean way to feed
+  the `size` variant that `stylex.props(sizeStyles[size])` selects — no prop drilling.
+- **Layout primitives that return a style array** — `stack()` / `container()` /
+  `stackItem()` return `[...namespaces] as const` that callers spread into
+  `stylex.props(...)`. Formalize these as shared helpers rather than re-deriving flex
+  layout in every component (see `authoring.md` → Composition).
+- **`cssVar(name)`** (from `naming`) — build a `--cl-*` string for the rare dynamic
+  case that sets or reads a var by name (e.g. a dynamic style writing
+  `--cl-container-max-height`).
+
+### Deliberately DON'T port (the CSS-first model makes them redundant)
+
+astryx also ships a runtime theming/appearance engine — `defineTheme`,
+`expandColorScale` / `expandTypeScale` / `expandRadiusScale` / `expandMotionScale`,
+`hct`, `derivedVarRegistry`, `parseStyleKey`. These generate a full token set from a
+small config and drive class-selector-based component overrides. **Skip them:** our
+model is CSS-first — consumers override `--cl-*` vars and `.cl-*` classes directly
+(`overrides.md`), so the derived-var indirection and appearance-class targeting add
+nothing. The one exception worth revisiting later: the `expand*` / `hct` **theme
+generation** (accent color → full perceptual color scale) is a real convenience _if_
+we ever want to author themes from a single seed rather than hand-writing every
+`light-dark()` pair. That's a future call, not part of the core adoption.
diff --git a/.claude/skills/mosaic-stylex/references/overrides.md b/.claude/skills/mosaic-stylex/references/overrides.md
new file mode 100644
index 00000000000..4a2f9c00713
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/references/overrides.md
@@ -0,0 +1,150 @@
+# The public override contract
+
+This is the crux of the pivot: consumers customize Mosaic **from their own CSS**,
+not from an `appearance` prop. Three stable hooks, one delivery mechanism.
+
+## The three stable hooks
+
+| Hook               | Emitted by                   | Consumer targets                           |
+| ------------------ | ---------------------------- | ------------------------------------------ |
+| `--cl-*` vars      | `defineVars` (verbatim keys) | `:root { --cl-primary: … }`                |
+| `.cl-<slot>` class | your stable-class helper     | `.cl-button { … }`                         |
+| `data-*` attrs     | your `themeProps` helper     | `.cl-button[data-variant='outline'] { … }` |
+
+**Never expose the atomic `x…` hashes.** They change every build. Only `--cl-*`,
+`.cl-*`, and `data-*` are the API.
+
+## Why a hand-attached stable class (and why it's safe)
+
+StyleX will **not** hand you a stable atomic class — atomic classes are hashed and
+per-property. So you attach your own plain class (`cl-button`) alongside StyleX's
+classes as a targeting hook.
+
+StyleX's maintainer calls mixing a non-StyleX class with atomic classes for
+_styling_ "unpredictable" ([discussion #442](https://github.com/facebook/stylex/discussions/442)) —
+**but that caveat assumes no cascade layers.** Cascade layers make the outcome
+deterministic: we ship our styles inside a layer the consumer controls, and their
+overrides sit in a **later** layer, so their rule always wins by layer order. That
+converts "unpredictable" into "reliable." (For non-styling markers — analytics,
+session-replay masking — the merge is uncontroversial regardless.)
+
+## Delivery: a static sheet imported into a consumer-owned layer
+
+We ship one `mosaic.css`. The consumer imports it into a cascade layer they
+control and overrides from a later layer:
+
+```css
+@layer components, overrides;
+@import '@clerk/ui/mosaic.css' layer(components);
+
+@layer overrides {
+  :root {
+    --cl-primary: rebeccapurple;
+  } /* token override */
+  .cl-button {
+    border-radius: 9999px;
+  } /* stable-class override */
+  .cl-button[data-variant='outline'] {
+    color: rebeccapurple;
+  } /* variant scope */
+}
+```
+
+`overrides` outranks `components` by layer order, so the consumer always wins. An
+unlayered consumer rule wins too (unlayered outranks any layer). We keep StyleX's
+`useCSSLayers: true`: its internal `@layer priorityN` handles intra-StyleX
+precedence and **nests cleanly under whatever layer the consumer imports into** —
+we do not engineer consumer precedence ourselves; placing our sheet in a layer is
+the consumer's job.
+
+> Document `@import … layer(components)` as the expected usage. If a consumer
+> imports the sheet with **no** layer wrapper, our rules live in low-priority
+> `priorityN` layers and become weak against the consumer's unlayered global CSS
+> (a bare `button {}` reset could clobber us). The `layer(components)` form is the
+> supported path.
+
+## Emitting the hooks: `themeProps` + `mergeProps`
+
+Two small helpers (adapted from astryx's `naming.ts` + `themeProps.ts` +
+`mergeProps.ts`) centralize the contract. Put them in a shared module so the `cl`
+prefix lives in exactly one place.
+
+```ts
+// naming.ts — single source of truth for the public namespace
+export const NAMESPACE = 'cl';
+export const stableClassName = (component: string) => `${NAMESPACE}-${component}`; // 'cl-button'
+export const dataAttr = (name: string) => `data-${name}` as const;
+```
+
+```ts
+// themeProps.ts — stable class + data-attribute reflection
+export function themeProps(component: string, props?: Record<string, string | number | null | undefined>) {
+  const classes = [stableClassName(component)];
+  const attrs: Record<string, string> = {};
+  for (const [k, v] of Object.entries(props ?? {})) {
+    if (v == null) continue;
+    // class token: CSS classes can't start with a digit — prefix with the prop name
+    classes.push(/^\d/.test(String(v)) ? `${k}-${v}` : String(v));
+    attrs[`data-${k.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`] = String(v);
+  }
+  return { className: classes.join(' '), ...attrs };
+}
+// themeProps('button', { variant: 'outline', size: 'sm' })
+// → { className: 'cl-button outline sm', 'data-variant': 'outline', 'data-size': 'sm' }
+```
+
+```ts
+// mergeProps.ts — fuse themeProps + stylex.props() + consumer className/style
+export function mergeProps(...parts: Array<Record<string, unknown> | string | undefined>) {
+  const out: Record<string, unknown> = {};
+  const classes: string[] = [];
+  let style: React.CSSProperties | undefined;
+  for (const p of parts) {
+    if (p == null) continue;
+    if (typeof p === 'string') {
+      classes.push(p);
+      continue;
+    }
+    const { className, style: s, ...rest } = p as { className?: string; style?: React.CSSProperties };
+    Object.assign(out, rest);
+    if (className) classes.push(className);
+    if (s) style = { ...style, ...s }; // later wins → consumer style overrides
+  }
+  if (classes.length) out.className = classes.join(' ');
+  if (style) out.style = style;
+  return out;
+}
+```
+
+Used on the public element (order matters — stable class + data-attrs first,
+StyleX atoms next, consumer `className`/`style` last so they win):
+
+```tsx
+<button
+  {...mergeProps(
+    themeProps('button', { variant, size }),
+    stylex.props(styles.base, variants[variant], sizeStyles[size]),
+    className,
+    style,
+  )}
+/>
+// → class="cl-button outline sm x3nfvp2 x6s0dn4 …" data-variant="outline" data-size="sm"
+```
+
+The simpler POC `cx(stable, className, ...styles)` helper (in
+`packages/ui/src/mosaic-x/props.ts`) is a subset of this — it emits only the
+stable class, not the `data-*` reflection. Prefer the `themeProps`/`mergeProps`
+pair once variant targeting matters.
+
+## Consumers also lose these (accept the trade)
+
+- **No `appearance.elements` JS-object overrides** and **no per-flow `scope`
+  cascade** — those move to CSS selectors the consumer writes.
+- **No arbitrary runtime `sx`** — overrides are CSS, or a token, or a precompiled
+  variant. See `migration.md`.
+
+## Caveat: consumer-side StyleX
+
+If a consumer app _also_ uses StyleX, our precompiled atomic classes and theirs
+won't dedupe across the package boundary (two separate StyleX outputs). With
+layers this is harmless — no visual bug, just slightly larger CSS. Document it.
diff --git a/.claude/skills/mosaic-stylex/references/relational-and-dynamic.md b/.claude/skills/mosaic-stylex/references/relational-and-dynamic.md
new file mode 100644
index 00000000000..66ebc3d69fd
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/references/relational-and-dynamic.md
@@ -0,0 +1,138 @@
+# Relational styling, dynamic styles, keyframes
+
+Covers the harder-than-a-single-element cases: styling based on an ancestor/
+sibling's state (markers), runtime values (dynamic styles), and animations.
+
+## The no-child-selector constraint (read first)
+
+StyleX styles **only the element the namespace is applied to**. There is no
+`& > div`, no descendant selector, and no self attribute-selector like
+`&[data-selected]`. This is the single biggest shift from Emotion Mosaic, where
+recipes occasionally styled a child or keyed off `&[data-cl-selected]`.
+
+Restructure using one of three moves:
+
+1. **Style each part on its own element**, composing that part's style object from
+   props passed down. A parent that "styled a child on selection" becomes: the
+   parent computes `selected` and the child applies `selected && styles.selected`.
+2. **Drive state as a composed variant** — `isSelected && styles.selected` in the
+   child's `stylex.props(...)`, not a `&[data-selected]` selector.
+3. **Use a marker** when the relationship is a genuine ancestor/sibling DOM state
+   that can't be threaded as a prop (see below).
+
+## Markers + `stylex.when` — scoped ancestor/sibling state
+
+Markers solve: "style this element when an **ancestor** (or sibling) is in some
+state, without that state leaking to unrelated descendants." Example: a radio
+row's `:hover` shading should apply to that row only, not every descendant.
+
+Define the marker in a `*.markers.stylex.ts` file, named `<component>Scope`:
+
+```ts
+// radio.markers.stylex.ts
+import * as stylex from '@stylexjs/stylex';
+export const radioScope: ReturnType<typeof stylex.defineMarker> = stylex.defineMarker();
+```
+
+Reference it inside a property value with `stylex.when.ancestor(selector, scope)`:
+
+```tsx
+// RadioListItem.tsx
+const styles = stylex.create({
+  radioUnchecked: {
+    borderColor: {
+      default: colors['--cl-border'],
+      [stylex.when.ancestor(':hover', radioScope)]: {
+        '@media (hover: hover)': `color-mix(in srgb, ${colors['--cl-border']}, ${colors['--cl-foreground']} 20%)`,
+      },
+    },
+  },
+});
+```
+
+Place the marker on the ancestor whose state you're observing:
+
+```tsx
+<li {...stylex.props(styles.container, !isDisabled && radioScope)}>
+  <span {...stylex.props(styles.radioUnchecked)} />
+</li>
+```
+
+The available relational selectors:
+
+| Function                                 | Observes                        |
+| ---------------------------------------- | ------------------------------- |
+| `stylex.when.ancestor(sel, scope?)`      | a marked ancestor matches `sel` |
+| `stylex.when.descendant(sel, scope?)`    | a marked descendant matches     |
+| `stylex.when.anySibling(sel, scope?)`    | any marked sibling matches      |
+| `stylex.when.siblingBefore(sel, scope?)` | a preceding marked sibling      |
+| `stylex.when.siblingAfter(sel, scope?)`  | a following marked sibling      |
+
+- `stylex.defineMarker()` creates a custom scope (isolates the relationship to a
+  specific element). `stylex.defaultMarker()` marks the element with the default
+  scope for simple cases.
+- Selectors can be compound: `stylex.when.ancestor(':has(:focus-visible)', switchScope)`
+  is how astryx scopes a focus ring to a switch's own track.
+
+**When to use a marker vs. plain nesting:** reach for a marker only when a
+parent/sibling DOM state must reach a specific element and can't be a prop. If the
+state is local to the element (its own `:hover`/`:focus`), use plain value-nested
+pseudo-classes (`authoring.md`) — markers are heavier machinery.
+
+Naming: file `<component>.markers.stylex.ts`; export `<component>Scope`. The
+markers file often also exports the component's container/base styles.
+
+## Dynamic styles — runtime values
+
+For a value only known at runtime, use an arrow-function namespace. The body must
+be a **plain object literal** — no logic, no destructuring, one or more params in,
+object out.
+
+```tsx
+const dynamic = stylex.create({
+  width: (w: number | string) => ({ width: w }),
+  offset: (x: number, y: number) => ({ transform: `translate(${x}px, ${y}px)` }),
+  maxHeight: (h: string) => ({ '--cl-container-max-height': h }), // set a var dynamically
+});
+
+stylex.props(width != null && dynamic.width(width), xstyle);
+```
+
+Keep dynamic styles rare — they're an escape hatch, not the variant mechanism.
+Anything expressible as a token or a precompiled variant should be.
+
+## Keyframes & animation
+
+Declare with `stylex.keyframes`, then reference the returned name in a style. Gate
+motion behind `prefers-reduced-motion`:
+
+```tsx
+const spin = stylex.keyframes({ '0%': { transform: 'rotate(0)' }, '100%': { transform: 'rotate(360deg)' } });
+
+const styles = stylex.create({
+  spinner: {
+    animationName: { default: spin, '@media (prefers-reduced-motion: reduce)': 'none' },
+    animationDuration: motion['--cl-duration-slow'],
+    animationTimingFunction: 'linear',
+    animationIterationCount: 'infinite',
+  },
+});
+```
+
+Use token variables for durations/easings, never hardcoded ms. For a set of
+entrance animations, put them in a dedicated `<name>Animations.stylex.ts` and
+share an `animationBase` object spread into each namespace (astryx's
+`layerAnimations.stylex.ts` pattern).
+
+## Fallbacks
+
+`stylex.firstThatWorks(...)` picks the first value the browser supports:
+
+```tsx
+const styles = stylex.create({
+  header: { position: stylex.firstThatWorks('sticky', '-webkit-sticky', 'fixed') },
+});
+```
+
+astryx prefers conditional media-query disabling over `firstThatWorks` in
+practice; use it when you genuinely need a progressive-enhancement fallback chain.
diff --git a/.claude/skills/mosaic-stylex/references/tokens-and-theming.md b/.claude/skills/mosaic-stylex/references/tokens-and-theming.md
new file mode 100644
index 00000000000..991dc46e693
--- /dev/null
+++ b/.claude/skills/mosaic-stylex/references/tokens-and-theming.md
@@ -0,0 +1,255 @@
+# Tokens & theming
+
+Tokens are the theming surface. The Mosaic goal is **stable, public `--cl-*` CSS
+variables** a consumer can override from plain CSS. This file covers how to
+define, organize, layer, and theme them.
+
+## Stable `--cl-*` variables via `defineVars`
+
+`stylex.defineVars` normally hashes variable names (`--x1a2b3c`), which consumers
+can't target. **Keys that begin with `--` are emitted verbatim.** That is the
+linchpin — it turns `defineVars` into a public, stable custom-property surface.
+
+```ts
+// tokens.stylex.ts
+import * as stylex from '@stylexjs/stylex';
+
+// Color tokens carry BOTH modes in one value via light-dark(light, dark).
+// One token, no prefers-color-scheme media query, no duplicated color rules.
+export const colors = stylex.defineVars({
+  '--cl-foreground': 'light-dark(oklch(0.15 0 0), oklch(0.95 0 0))',
+  '--cl-background': 'light-dark(white, oklch(0.15 0 0))',
+  '--cl-primary': 'light-dark(oklch(0.205 0 0), oklch(0.92 0 0))',
+  '--cl-primary-foreground': 'light-dark(oklch(0.985 0 0), oklch(0.2 0 0))',
+  '--cl-destructive': 'light-dark(oklch(0.577 0.245 27.325), oklch(0.7 0.19 25))',
+  '--cl-border': 'light-dark(oklch(0.922 0 0), oklch(0.3 0 0))',
+  '--cl-muted-foreground': 'light-dark(oklch(0.556 0 0), oklch(0.65 0 0))',
+});
+
+export const radius = stylex.defineVars({
+  '--cl-radius-md': '0.375rem',
+  '--cl-radius-full': 'calc(infinity * 1px)',
+});
+
+export const space = stylex.defineVars({
+  '--cl-spacing': '0.25rem',
+});
+```
+
+Referencing a var in a component compiles to `var(--cl-…)`:
+
+```ts
+import { colors } from './tokens.stylex';
+const styles = stylex.create({ base: { color: colors['--cl-foreground'] } });
+// → color: var(--cl-foreground)
+```
+
+The compiled sheet emits the defaults into `:root`, so a consumer overrides with
+nothing but CSS:
+
+```css
+:root {
+  --cl-foreground: red;
+} /* unlayered → beats the layered default */
+```
+
+> Compiler note (from the POC): lightningcss resolves `oklch()` **defaults** to
+> hex + `@supports (color: lab())` fallbacks in the emitted CSS. `color-mix()`
+> and `calc()` used _inside rules_ are preserved as-is. This only affects the
+> printed default values, not the override mechanism.
+
+### Rules for `.stylex.ts` token files
+
+- File must be named `*.stylex.ts` (or `.js`).
+- **Named exports only. No default export. No non-token exports** in the file.
+- Group by concern with plural names: `colors`, `radius`, `space`, `text`,
+  `motion`. Each is one `defineVars` call.
+
+## `defineConsts` vs `defineVars`
+
+| Use `defineVars`                                  | Use `defineConsts`                                            |
+| ------------------------------------------------- | ------------------------------------------------------------- |
+| Value must be themeable / consumer-overridable    | Value is fixed and never themed                               |
+| Emits CSS custom properties                       | Inlined at compile time; no runtime var                       |
+| Colors, radii, spacing, type — the public surface | Breakpoints/media-query strings, z-index scale, fixed easings |
+
+```ts
+export const zIndices = stylex.defineConsts({ modal: '1000', toast: '1200' });
+```
+
+`defineConsts` values are used as **keys** (media / container query strings)
+inside a style value — that's their main use for shareable breakpoints and
+interaction gates. Group them in a `media.stylex.ts`:
+
+```ts
+// media.stylex.ts
+export const media = stylex.defineConsts({
+  hover: '@media (hover: hover)', // gate hover paints so they don't stick on touch
+  finePointer: '@media (hover: hover) and (pointer: fine)',
+  motionReduce: '@media (prefers-reduced-motion: reduce)',
+  motionSafe: '@media (prefers-reduced-motion: no-preference)',
+  contrastMore: '@media (prefers-contrast: more)',
+  forcedColors: '@media (forced-colors: active)',
+});
+```
+
+### Responsive = container queries, not viewport media
+
+Mosaic components render **inside arbitrary consumer layouts**, so viewport width
+is the wrong axis — the width of the container the component sits in is right. Use
+`@container`, never `@media (min-width)`. (This matches where Mosaic already went:
+`@container (min-width: 600px)`.)
+
+```ts
+// media.stylex.ts (continued)
+export const container = stylex.defineConsts({
+  sm: '@container (min-width: 400px)',
+  md: '@container (min-width: 600px)',
+  lg: '@container (min-width: 900px)',
+});
+```
+
+```ts
+const styles = stylex.create({
+  layout: {
+    flexDirection: { default: 'column', [container.md]: 'row' },
+    padding: { default: s(3), [container.md]: s(6) },
+  },
+});
+```
+
+**Container queries need a `container-type` on an ancestor** or `@container` never
+matches. Declare it once on the Mosaic root — the same element that sets
+`color-scheme` for `light-dark()` (see "Light/dark" below):
+
+```ts
+const root = stylex.create({
+  base: { containerType: 'inline-size', colorScheme: scheme['--cl-color-scheme'] },
+});
+```
+
+Skip viewport `@media` breakpoints entirely unless a component genuinely responds
+to the page (rare for embeddable UI).
+
+## Token layering (primitive → semantic → component)
+
+astryx uses a three-tier model. Adopt the same discipline even if Mosaic starts
+smaller:
+
+1. **Primitive** — raw scale values (`--cl-font-size-lg: 1.0625rem`,
+   `--cl-blue-500`). No meaning.
+2. **Semantic** — intent-bound, reference primitives
+   (`--cl-foreground`, `--cl-primary`, `--cl-text-body-size: var(--cl-font-size-base)`).
+   **Components consume these.**
+3. **Component** — component-scoped private vars for overridable local values
+   (`--cl-button-radius`, read as `var(--cl-button-radius, <fallback>)`). Only
+   introduce when a component needs a theme-overridable knob distinct from the
+   semantic token.
+
+Author components against **semantic** tokens. Never reach past them to a
+primitive (`--cl-blue-500`) in a component — that bypasses theming.
+
+## The spacing helper
+
+The POC keeps spacing math readable with a tiny helper over the `--cl-spacing`
+base (mirrors astryx's spacing scale):
+
+```ts
+// space['--cl-spacing'] compiles to var(--cl-spacing)
+const s = (n: number) => `calc(${space['--cl-spacing']} * ${n})`;
+// s(2) → calc(var(--cl-spacing) * 2)
+```
+
+Prefer a precomputed indexed scale (`gapStyles[step]`, `paddingStyles[step]`) for
+repeated values; use `s(n)` for one-off math inside a namespace.
+
+## Light/dark via `light-dark()`
+
+Color tokens carry both modes in a single value: `light-dark(<light>, <dark>)`.
+This is how astryx does it, and it means **dark mode lives entirely in the token
+layer** — no `@media (prefers-color-scheme)` const, no gating every color property
+on a media query, no duplicated color rules. Which branch resolves is decided by
+the CSS `color-scheme` property in scope.
+
+**`light-dark()` only resolves when `color-scheme` is set on an ancestor.** This
+is the one gotcha — a token defined with `light-dark()` renders the _light_ branch
+(or nothing sensible) until some ancestor declares `color-scheme`. Set it once on
+the Mosaic root (and expose it as a token so it's overridable):
+
+```ts
+export const scheme = stylex.defineVars({
+  '--cl-color-scheme': 'light dark', // honor the OS preference by default
+});
+```
+
+```tsx
+// The Mosaic root — the same element that declares container-type (see Responsive).
+const root = stylex.create({
+  base: { colorScheme: scheme['--cl-color-scheme'], containerType: 'inline-size' },
+});
+<div {...stylex.props(root.base)}>{children}</div>;
+```
+
+- Default `light dark` → follows the user's OS preference automatically.
+- Consumers **force a mode** by setting the property, no per-token overrides:
+  ```css
+  .cl-root {
+    color-scheme: dark;
+  } /* or on :root, or any subtree */
+  ```
+- Consumers **retint a specific token** by overriding the whole `light-dark(...)`
+  value: `:root { --cl-primary: light-dark(rebeccapurple, plum); }`.
+
+Set `color-scheme` on **one** owning element, not per component — it inherits, and
+`light-dark()` reads the inherited value.
+
+## Theming: two delivery models
+
+A "theme" is a set of `--cl-*` values (or a `color-scheme` flip). Ways to ship one:
+
+**1. Plain CSS file (preferred for the "consumers own their CSS" goal).** A
+`.css` that sets the vars — or just flips the scheme — under a selector. Zero JS,
+trivially shippable next to `mosaic.css`, and consumers just import it.
+
+```css
+/* dark mode: with light-dark() tokens, flip the scheme — don't re-set every var */
+.cl-root[data-cl-theme='dark'] {
+  color-scheme: dark;
+}
+
+/* a full retheme still overrides tokens directly (each keeps its light-dark pair) */
+.cl-root[data-cl-theme='brand'] {
+  --cl-primary: light-dark(#5b21b6, #c4b5fd);
+  --cl-radius-md: 0.5rem;
+}
+```
+
+**2. `stylex.createTheme` object** applied via a wrapper element — when a theme
+must be swapped per-subtree at runtime:
+
+```ts
+import { colors } from './tokens.stylex';
+export const darkTheme = stylex.createTheme(colors, {
+  '--cl-foreground': 'white',
+  '--cl-background': '#0a0a0a',
+});
+```
+
+```tsx
+<div {...stylex.props(isDark && darkTheme)}>{children}</div> // descendants use theme values
+```
+
+`createTheme` can be created anywhere and passed across files (unlike
+`defineVars`, which is file-bound). Reach for it only when subtree-scoped runtime
+theming is required; otherwise the plain-CSS route fits Mosaic better.
+
+## The public token contract
+
+The `--cl-*` list is a **published API** — consumers pin to it. Treat it like any
+public surface:
+
+- Lock and document the token names; renaming/removing one is a breaking change.
+- Every component value that a consumer might reasonably want to retheme should
+  resolve to a `--cl-*` var, not a literal.
+- Don't proliferate categories. Need "success green"? Add/keep a semantic
+  `--cl-success`, don't invent per-component color tokens.

From e4639297124759d34e05c433cc2365597a2613f4 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 14:59:30 -0400
Subject: [PATCH 2/5] docs(repo): add CSS reset guidance to mosaic-stylex skill

---
 .../mosaic-stylex/references/authoring.md     | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/.claude/skills/mosaic-stylex/references/authoring.md b/.claude/skills/mosaic-stylex/references/authoring.md
index fd5dc52ce5c..cc4c4d97e82 100644
--- a/.claude/skills/mosaic-stylex/references/authoring.md
+++ b/.claude/skills/mosaic-stylex/references/authoring.md
@@ -192,6 +192,59 @@ const styles = stylex.create({
 });
 ```
 
+## CSS reset (box-sizing, margin/padding, borders)
+
+Mosaic is an **embedded widget**, not a whole-app framework, so it must **not**
+ship a global reset (`*`, `html`, `body`, `h1`, `button`, …) the way astryx's
+`reset.css` does — that would restyle the host app's entire DOM. Two scoped moves
+replace it:
+
+**1. Per-component base reset in StyleX (primary).** StyleX styles only the
+element it's on, and Mosaic components are self-contained, so put the reset in each
+component's `base`. Factor the repeated bits into one shared `reset` object and
+compose it:
+
+```tsx
+const reset = stylex.create({
+  box: { boxSizing: 'border-box', margin: 0, padding: 0 },
+});
+
+const styles = stylex.create({
+  base: { display: 'inline-flex', borderRadius: radius['--cl-radius-md'] /* … */ },
+});
+
+stylex.props(reset.box, styles.base /* variants */); // reset first, so real styles win
+```
+
+This is what the POC's `button.tsx` already does implicitly — it sets
+`borderWidth`/`borderStyle`/`borderColor` explicitly rather than leaning on a
+global reset.
+
+**2. A _scoped_ reset stylesheet for the genuinely universal bits.** `box-sizing`
+and the border reset are things you don't want to hand-repeat on every element.
+StyleX can't express a `*`/descendant selector, so ship this as **plain hand-written
+CSS**, scoped to the Mosaic subtree and zero-specificity via `:where()`:
+
+```css
+@layer cl-reset {
+  :where([data-cl-scope] *, [data-cl-scope] *::before, [data-cl-scope] *::after) {
+    box-sizing: border-box;
+    border-width: 0;
+    border-style: solid; /* now a component adds a border with just border-width + border-color */
+  }
+}
+```
+
+The Mosaic root carries `data-cl-scope` (the same root that sets `color-scheme` +
+`container-type`). `:where()` keeps specificity 0 so component `base` styles and
+consumer overrides always win; the `@layer` keeps it below everything else.
+
+Two notes carried from astryx: the **border reset** (`border-width: 0; border-style: solid`)
+is a real ergonomic win — borders become `borderWidth` + `borderColor` only. And
+for layout-critical components, **also** assert `boxSizing: 'border-box'` in the
+StyleX `base` (belt-and-suspenders) so they're correct even if a consumer strips
+the reset sheet. Never reach for a global `*`/`body` reset.
+
 ## Accepting style overrides from a parent
 
 Type a passthrough prop as `StyleXStyles` and place it **last** so it overrides:

From 0cdedbddaee6e6c69115d652c9f9c289b8df0635 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 15:01:12 -0400
Subject: [PATCH 3/5] docs(repo): document reset CSS bundling in mosaic-stylex
 skill

---
 .../skills/mosaic-stylex/references/build.md  | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/.claude/skills/mosaic-stylex/references/build.md b/.claude/skills/mosaic-stylex/references/build.md
index c37283d4775..fc25e47dd23 100644
--- a/.claude/skills/mosaic-stylex/references/build.md
+++ b/.claude/skills/mosaic-stylex/references/build.md
@@ -103,6 +103,40 @@ Source distribution (shipping `.stylex.ts` and requiring every consumer to run t
 StyleX plugin) is **not viable** — consumers are arbitrary Next/Vite/etc. apps we
 don't control.
 
+### Two CSS files, produced two different ways
+
+astryx ships the reset and the compiled component CSS as **separate files**, and
+this split is inherent (StyleX can't emit a `*`/`:where()` reset):
+
+| File              | How it's produced                                                                       | Exported as                     |
+| ----------------- | --------------------------------------------------------------------------------------- | ------------------------------- |
+| reset (plain CSS) | Hand-authored, **shipped verbatim from `src/`** — not compiled                          | `./reset.css` → `src/reset.css` |
+| component CSS     | Compiled: babel/rollup runs the StyleX plugin over all source, wraps output in `@layer` | `./mosaic.css` → `dist/…`       |
+
+- astryx's compiled sheet comes from a custom post-build script (`build-css.mjs`:
+  glob sources → `@babel/core` + `@stylexjs/babel-plugin` → concat rules → wrap in
+  `@layer astryx-base` → write `dist/astryx.css`). The Clerk POC does the equivalent
+  with `@stylexjs/rollup-plugin` inside tsdown emitting `mosaic.css`.
+- **Ship a `.css.d.ts` stub** (`export {};`) next to each CSS export so TypeScript
+  allows `import '@clerk/ui/mosaic.css'` without a "cannot find module" error — the
+  babel/rolldown JS build ignores `.css` files, so the stub provides the type.
+- **`sideEffects` must include `**/\*.css`\*\* so bundlers never drop the import.
+- **Layers come from each file wrapping its own `@layer`** plus import order:
+  reset (`@layer cl-reset`) → component (`@layer` from `useCSSLayers`) → consumer.
+
+### Bundling the reset for Clerk
+
+The reset is a **hand-authored, scoped, static CSS file** (`:where([data-cl-scope] *)`,
+see `authoring.md` → CSS reset) shipped verbatim — same mechanism as astryx, but
+scoped instead of global. Two delivery choices astryx doesn't need:
+
+1. **Separate file** the consumer imports (`import '@clerk/ui/mosaic-reset.css'`) —
+   cleanest for npm consumers, keeps the layer explicit.
+2. **Prepend the `@layer cl-reset {…}` block into `mosaic.css`** at build so there's
+   a single sheet — simpler for the **clerk-js runtime-injection** path (one blob to
+   inject, no second load). Prepending keeps it in the lowest layer regardless of
+   source order.
+
 ### Open build questions (from the migration spike)
 
 - **clerk-js load path.** clerk-js is a runtime-injected rspack UMD bundle, not an

From 8a9e04d0fe7e3507b19b4fd5bac80637233205d9 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 15:01:39 -0400
Subject: [PATCH 4/5] docs(repo): fix escaped glob in mosaic-stylex build
 reference

---
 .claude/skills/mosaic-stylex/references/build.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/skills/mosaic-stylex/references/build.md b/.claude/skills/mosaic-stylex/references/build.md
index fc25e47dd23..a0747b58620 100644
--- a/.claude/skills/mosaic-stylex/references/build.md
+++ b/.claude/skills/mosaic-stylex/references/build.md
@@ -120,7 +120,7 @@ this split is inherent (StyleX can't emit a `*`/`:where()` reset):
 - **Ship a `.css.d.ts` stub** (`export {};`) next to each CSS export so TypeScript
   allows `import '@clerk/ui/mosaic.css'` without a "cannot find module" error — the
   babel/rolldown JS build ignores `.css` files, so the stub provides the type.
-- **`sideEffects` must include `**/\*.css`\*\* so bundlers never drop the import.
+- `sideEffects` **must list the `.css` glob** so bundlers never drop the import.
 - **Layers come from each file wrapping its own `@layer`** plus import order:
   reset (`@layer cl-reset`) → component (`@layer` from `useCSSLayers`) → consumer.
 

From 54817f95dc791f3173b819a48a6816d763c059b1 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 15:03:29 -0400
Subject: [PATCH 5/5] docs(repo): clarify Clerk ships a single mosaic.css with
 reset prepended

---
 .../skills/mosaic-stylex/references/build.md  | 28 ++++++++++---------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/.claude/skills/mosaic-stylex/references/build.md b/.claude/skills/mosaic-stylex/references/build.md
index a0747b58620..c4129b305af 100644
--- a/.claude/skills/mosaic-stylex/references/build.md
+++ b/.claude/skills/mosaic-stylex/references/build.md
@@ -103,10 +103,11 @@ Source distribution (shipping `.stylex.ts` and requiring every consumer to run t
 StyleX plugin) is **not viable** — consumers are arbitrary Next/Vite/etc. apps we
 don't control.
 
-### Two CSS files, produced two different ways
+### How the CSS is produced (astryx reference)
 
-astryx ships the reset and the compiled component CSS as **separate files**, and
-this split is inherent (StyleX can't emit a `*`/`:where()` reset):
+astryx ships the reset and the compiled component CSS as **separate files** — the
+split is inherent (StyleX can't emit a `*`/`:where()` reset). Clerk collapses these
+into one sheet (next section); the production mechanism is the same either way:
 
 | File              | How it's produced                                                                       | Exported as                     |
 | ----------------- | --------------------------------------------------------------------------------------- | ------------------------------- |
@@ -124,18 +125,19 @@ this split is inherent (StyleX can't emit a `*`/`:where()` reset):
 - **Layers come from each file wrapping its own `@layer`** plus import order:
   reset (`@layer cl-reset`) → component (`@layer` from `useCSSLayers`) → consumer.
 
-### Bundling the reset for Clerk
+### Bundling the reset for Clerk (one sheet only)
 
-The reset is a **hand-authored, scoped, static CSS file** (`:where([data-cl-scope] *)`,
-see `authoring.md` → CSS reset) shipped verbatim — same mechanism as astryx, but
-scoped instead of global. Two delivery choices astryx doesn't need:
+Unlike astryx (which ships `reset.css` and `astryx.css` separately), **Clerk ships
+exactly one CSS file** — `mosaic.css`. So the reset is **prepended into that single
+sheet** at build, not shipped as its own import:
 
-1. **Separate file** the consumer imports (`import '@clerk/ui/mosaic-reset.css'`) —
-   cleanest for npm consumers, keeps the layer explicit.
-2. **Prepend the `@layer cl-reset {…}` block into `mosaic.css`** at build so there's
-   a single sheet — simpler for the **clerk-js runtime-injection** path (one blob to
-   inject, no second load). Prepending keeps it in the lowest layer regardless of
-   source order.
+- The reset stays hand-authored, scoped, static CSS (`:where([data-cl-scope] *)`,
+  see `authoring.md` → CSS reset) — StyleX can't emit it.
+- A build step prepends the `@layer cl-reset {…}` block ahead of the StyleX output
+  in `mosaic.css`. Because it's declared first (and lives in the lowest layer), it
+  sits under every component rule regardless of source order.
+- One sheet is what the **clerk-js runtime-injection** path needs — a single blob
+  to inject, no second load — and it's simplest for npm consumers too (one import).
 
 ### Open build questions (from the migration spike)