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'],
+  },
+});