feat(ui): add Mosaic Badge component

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});

.changeset/mosaic-badge.md

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

packages/swingset/next.config.mjs

@@ -61,15 +61,23 @@ const nextConfig = {
 
  // Swingset consumes Mosaic from source, so StyleX (`defineVars`/`create`/`props`) must be
  // compiled here — otherwise the calls hit the runtime and throw. The unplugin transforms the
- // StyleX *JS only* (calls → static atom references), keeping SWC intact so `next/font` and the
- // Emotion transform keep working. The CSS is emitted separately by `@stylexjs/postcss-plugin`
- // (`@stylex` in `globals.css`), so this runs in extraction mode (no `runtimeInjection`); both
- // share the same StyleX babel version/options so the atom hashes match, and the plugin's dev
- // "no CSS asset" warning is expected and harmless. `useCSSLayers: true` matches the published
- // build so atoms carry StyleX's `@layer priorityN` precedence.
+ // StyleX *JS only*, keeping SWC intact so `next/font` and the Emotion transform keep working.
+ //
+ // The `@stylexjs/postcss-plugin` (see `postcss.config.mjs`) is what extracts the CSS — the
+ // token `:root { --cl-* }` defaults and the atoms — in both dev and prod. This unplugin only
+ // transforms the StyleX *calls* in the JS. `runtimeInjection` forks by env:
+ // - Prod: `false`. Atoms are static class refs resolved against the extracted sheet.
+ // - Dev: `true`. On top of the extracted sheet, StyleX also injects each atom at runtime under
+ // its content hash, so editing a `.styles.ts` file hot-reloads a fresh atom (the extracted
+ // sheet goes stale because Next won't re-run the `globals.css` PostCSS pass on Mosaic-source
+ // edits). The `:root` token defaults come from the extraction and never change mid-session,
+ // so they stay correct — `runtimeInjection` can't emit them (`defineVars` is compile-only).
+ // Both passes share the same babel version/options so atom hashes match.
+ const isDev = process.env.NODE_ENV !== 'production';
  config.plugins.push(
  stylexPlugin({
- dev: process.env.NODE_ENV !== 'production',
+ dev: isDev,
+ runtimeInjection: isDev,
  unstable_moduleResolution: { type: 'commonJS', rootDir: resolve(__dirname, '../ui') },
  useCSSLayers: true,
  }),

packages/swingset/postcss.config.mjs

@@ -5,34 +5,47 @@ import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// StyleX CSS extraction. The `@stylexjs/postcss-plugin` scans the Mosaic source, runs the
-// StyleX babel transform itself, and replaces the `@stylex;` directive in `globals.css` with
-// the generated CSS (token `:root` defaults + atoms). This is the CSS half of the setup; the
-// JS half is the unplugin in `next.config.mjs`. Both must use the SAME StyleX babel version
-// and options (`dev`, `rootDir`) so the atom class hashes line up.
 const uiRoot = resolve(__dirname, '../ui');
+const isDev = process.env.NODE_ENV !== 'production';
 
-export default {
- plugins: {
- '@stylexjs/postcss-plugin': {
- useCSSLayers: true,
- babelConfig: {
- babelrc: false,
- configFile: false,
- presets: [require('@babel/preset-typescript')],
- plugins: [
- require('@babel/plugin-syntax-jsx'),
- [
- require('@stylexjs/babel-plugin'),
- {
- dev: process.env.NODE_ENV !== 'production',
- runtimeInjection: false,
- unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
- },
- ],
+// StyleX CSS. `@stylexjs/postcss-plugin` scans the Mosaic source, runs the StyleX babel
+// transform, and replaces the `@stylex;` directive in `globals.css` with the generated CSS:
+// the token `:root { --cl-* }` defaults *and* the atoms. This runs in BOTH dev and prod
+// because it is the only thing that emits the `:root` token defaults — StyleX's `defineVars`
+// is compile-time-only (its runtime export throws), so `runtimeInjection` alone leaves every
+// `var(--cl-*)` unresolved (unstyled). Its babel `dev`/`rootDir` must match the unplugin in
+// `next.config.mjs` so atom hashes line up.
+//
+// In dev this sheet goes stale on `.styles.ts` edits (Next won't re-run the `globals.css`
+// PostCSS pass for files outside the CSS import graph), but that's fine: the unplugin's
+// `runtimeInjection` (see `next.config.mjs`) injects the *fresh* atom at runtime under a new
+// content hash, which HMR tracks. The stale extracted atom is dead CSS; the `:root` token
+// defaults never change mid-session, so they stay correct.
+const stylexExtraction = {
+ '@stylexjs/postcss-plugin': {
+ useCSSLayers: true,
+ babelConfig: {
+ babelrc: false,
+ configFile: false,
+ presets: [require('@babel/preset-typescript')],
+ plugins: [
+ require('@babel/plugin-syntax-jsx'),
+ [
+ require('@stylexjs/babel-plugin'),
+ {
+ dev: isDev,
+ runtimeInjection: false,
+ unstable_moduleResolution: { type: 'commonJS', rootDir: uiRoot },
+ },
  ],
-},
+],
  },
+ },
+};
+
+export default {
+ plugins: {
+ ...stylexExtraction,
  '@tailwindcss/postcss': {},
  },
 };

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  destructive: dynamic(() => import('../stories/destructive.mdx')),
  },
  components: {
+ badge: dynamic(() => import('../stories/badge.mdx')),
  button: dynamic(() => import('../stories/button.mdx')),
  card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),

packages/swingset/src/components/PropTable.tsx

@@ -15,11 +15,13 @@ interface ExtraProp {
 interface PropTableProps {
  meta: StoryMeta;
  extra?: ExtraProp[];
+ /** Append the `sx` row. StyleX components (e.g. Badge) don't take `sx`, so pass `false`. */
+ sx?: boolean;
 }
 
 const SX_ROW: ExtraProp = { name: 'sx', type: 'StyleRule | (theme) => StyleRule' };
 
-export function PropTable({ meta, extra = [] }: PropTableProps) {
+export function PropTable({ meta, extra = [], sx = true }: PropTableProps) {
  const playground = usePlayground();
  const variants = meta.styles?._variants ?? {};
  const defaults = meta.styles?._defaultVariants ?? {};
@@ -35,7 +37,7 @@ export function PropTable({ meta, extra = [] }: PropTableProps) {
  return { name, type, default: defDisplay };
  }),
  ...extra,
- SX_ROW,
+...(sx ? [SX_ROW] : []),
  ];
 
  return (

packages/swingset/src/lib/registry.ts

@@ -1,6 +1,12 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
+import {
+ Colors as BadgeColors,
+ meta as badgeMeta,
+ Primary as BadgePrimary,
+ WithIcon as BadgeWithIcon,
+} from '../stories/badge.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
  Centered as CardCentered,
@@ -115,6 +121,13 @@ const organizationProfileMembersPanelModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
 
+const badgeModule: StoryModule = {
+ meta: badgeMeta,
+ Primary: BadgePrimary,
+ Colors: BadgeColors,
+ WithIcon: BadgeWithIcon,
+};
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -171,6 +184,7 @@ export const registry: StoryModule[] = [
  // Blocks
  destructiveModule,
  // Components
+ badgeModule,
  buttonModule,
  cardComponentModule,
  inputModule,

packages/swingset/src/stories/badge.mdx

@@ -0,0 +1,47 @@
+import * as BadgeStories from './badge.stories';
+
+# Badge
+
+Badge labels the status or category of the thing next to it. It renders a `span` by default and forwards a ref to the underlying element; use the `render` prop when the badge belongs in a different element, such as a link. Its `color` carries meaning, so keep the label itself self-describing for anyone who can't see it.
+
+## Playground
+
+<Preview
+ name='Primary'
+ storyModule={BadgeStories}
+/>
+
+## Props
+
+<PropTable
+ meta={BadgeStories.meta}
+ extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+ sx={false}
+/>
+
+## Usage
+
+<Usage
+ component='Badge'
+ module='@clerk/ui/mosaic/components/badge'
+>
+ Badge Label
+</Usage>
+
+---
+
+## Examples
+
+### Colors
+
+<Story
+ name='Colors'
+ storyModule={BadgeStories}
+/>
+
+### With an icon
+
+<Story
+ name='WithIcon'
+ storyModule={BadgeStories}
+/>

packages/swingset/src/stories/badge.stories.tsx

@@ -0,0 +1,95 @@
+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './badge.stories?raw';
+
+// StyleX has no runtime recipe to derive knobs from, so the variant surface is described
+// here to drive the playground + prop table. Keys mirror `BadgeProps`.
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'Badge',
+ source: 'packages/ui/src/mosaic/components/badge/badge.tsx',
+ styles: {
+ _variants: {
+ color: { primary: {}, neutral: {}, warning: {}, negative: {}, positive: {} },
+ },
+ _defaultVariants: {
+ color: 'primary',
+ },
+ },
+};
+
+// Story functions accept Record<string,unknown> (knob values) and cast to BadgeProps.
+// The cast is unavoidable: knobs are dynamically typed; Badge has a strict prop interface.
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as BadgeProps;
+}
+
+export function Primary(props: Record<string, unknown>) {
+ return <Badge {...knobsAsProps(props)}>Badge Label</Badge>;
+}
+
+export function Colors(props: Record<string, unknown>) {
+ return (
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <Badge
+ {...knobsAsProps(props)}
+ color='primary'
+ >
+ Primary
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='neutral'
+ >
+ Neutral
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='warning'
+ >
+ Warning
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='negative'
+ >
+ Negative
+ </Badge>
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ Positive
+ </Badge>
+ </div>
+ );
+}
+
+export function WithIcon(props: Record<string, unknown>) {
+ return (
+ <Badge
+ {...knobsAsProps(props)}
+ color='positive'
+ >
+ <svg
+ width='10'
+ height='10'
+ viewBox='0 0 24 24'
+ fill='none'
+ stroke='currentColor'
+ strokeWidth='3'
+ strokeLinecap='round'
+ strokeLinejoin='round'
+ style={{ flexShrink: 0 }}
+ >
+ <path d='M20 6 9 17l-5-5' />
+ </svg>
+ Verified
+ </Badge>
+ );
+}

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

@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+// warning/negative/positive tint a faded fill and use the saturated token as text;
+// primary/neutral fill with the solid token and use its `-foreground` for text.
+export const styles = stylex.create({
+ base: {
+ borderRadius: radiusVars['--cl-radius-full'],
+ gap: space['1'],
+ paddingInline: space['2'],
+ alignItems: 'center',
+ boxSizing: 'border-box',
+ display: 'inline-flex',
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--cl-text-label-sm-size'],
+ fontWeight: typeScaleVars['--cl-text-label-sm-weight'],
+ justifyContent: 'center',
+ lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+ whiteSpace: 'nowrap',
+ height: space['5'],
+ },
+});
+
+export const colors = stylex.create({
+ primary: {
+ backgroundColor: colorVars['--cl-color-primary'],
+ color: colorVars['--cl-color-primary-foreground'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--cl-color-neutral'],
+ color: colorVars['--cl-color-neutral-foreground'],
+ },
+ warning: {
+ backgroundColor: colorVars['--cl-color-warning-faded'],
+ color: colorVars['--cl-color-warning'],
+ },
+ negative: {
+ backgroundColor: colorVars['--cl-color-negative-faded'],
+ color: colorVars['--cl-color-negative'],
+ },
+ positive: {
+ backgroundColor: colorVars['--cl-color-positive-faded'],
+ color: colorVars['--cl-color-positive'],
+ },
+});