feat(swingset): Scaffold component documentation package

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}

.changeset/cyan-regions-slide.md

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

package.json

@@ -14,6 +14,7 @@
  "dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
  "dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
  "dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
+ "dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
  "format": "turbo format && node scripts/format-non-workspace.mjs",
  "format:check": "turbo format:check && node scripts/format-non-workspace.mjs --check",
  "preinstall": "npx only-allow pnpm",

packages/swingset/README.md

@@ -0,0 +1,104 @@
+# Swingset
+
+Component explorer for the Mosaic design system. Runs at http://localhost:6006.
+
+## Dev
+
+```
+pnpm dev --filter @clerk/swingset
+```
+
+## Adding a component
+
+**1. Create a story file** — `src/stories/my-component.stories.tsx`
+
+```tsx
+/** @jsxImportSource @emotion/react */
+import type { StoryMeta } from '@/lib/types';
+import { MyComponent, myComponentStyles } from '@clerk/ui/mosaic/components/my-component';
+
+export const meta: StoryMeta = {
+ group: 'Components',
+ title: 'My Component',
+ styles: myComponentStyles, // CVA style object — knobs auto-generated from _variants
+};
+
+export function Default(props: Record<string, unknown>) {
+ return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
+}
+```
+
+Knobs are generated automatically from the CVA `_variants` on the style object. Boolean variants (`true`/`false` keys) become toggles; all others become selects. Default values come from `defaultVariants`.
+
+**2. Register in `src/lib/registry.ts`**
+
+```ts
+import { meta as myMeta, Default } from '../stories/my-component.stories';
+
+const myModule: StoryModule = { meta: myMeta, Default };
+export const registry: StoryModule[] = [..., myModule];
+```
+
+Import stories explicitly (not `import *`) to control sidebar order.
+
+**3. Add docs** — `src/stories/my-component.mdx`
+
+```mdx
+import * as Stories from './my-component.stories';
+
+# My Component
+
+<Story
+ name='Default'
+ storyModule={Stories}
+/>
+
+## Props
+
+| Prop | Type | Default |
+| -------------------- | ---------------------- | ---------------------- |
+| <code>variant</code> | <code>'primary'</code> | <code>'primary'</code> |
+```
+
+Register in `src/components/DocsViewer.tsx`:
+
+```ts
+const docModules = {
+ 'my-component': () => import('../stories/my-component.mdx'),
+};
+```
+
+Also update the root redirect in `src/app/page.tsx` if this is now the first component.
+
+## PropTable
+
+In MDX, use `<PropTable>` to auto-generate the props table from the CVA style object:
+
+```mdx
+import * as Stories from './my-component.stories';
+
+<PropTable meta={Stories.meta} />
+```
+
+Variant props (type and default) are derived from `meta.styles._variants` and `meta.styles._defaultVariants`. The `sx` prop is always appended automatically. Pass `extra` for any other non-variant props.
+
+## Architecture
+
+```
+src/
+ app/ Next.js App Router
+ components/
+ app-sidebar.tsx Left nav (reads from registry)
+ ClientRoot.tsx SidebarProvider + breadcrumb header
+ DocsViewer.tsx Renders MDX docs for /components/[slug]
+ StoryCanvas.tsx Renders a story + knobs for /components/[slug]/[story]
+ KnobPanel.tsx Auto-generated knob controls
+ VariablesPanel.tsx Mosaic CSS variable overrides
+ CodeBlock.tsx Shiki syntax highlighter (css-variables theme)
+ lib/
+ registry.ts Story registry — add new stories here
+ generateKnobs.ts CVA _variants → knob definitions
+ types.ts StoryMeta, StoryModule, KnobDef etc.
+ slug.ts URL slug utilities
+ stories/ Story and MDX files
+```

packages/swingset/components.json

@@ -0,0 +1,25 @@
+{
+"$schema": "https://ui.shadcn.com/schema.json",
+"style": "base-nova",
+"rsc": true,
+"tsx": true,
+"tailwind": {
+"config": "",
+"css": "src/app/globals.css",
+"baseColor": "neutral",
+"cssVariables": true,
+"prefix": ""
+ },
+"iconLibrary": "lucide",
+"rtl": false,
+"aliases": {
+"components": "@/components",
+"utils": "@/lib/utils",
+"ui": "@/components/ui",
+"lib": "@/lib",
+"hooks": "@/hooks"
+ },
+"menuColor": "default",
+"menuAccent": "subtle",
+"registries": {}
+}

packages/swingset/mdx-components.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+import { CodeBlock } from './src/components/CodeBlock';
+import { PropTable } from './src/components/PropTable';
+import { StoryEmbed } from './src/components/StoryEmbed';
+
+function PreBlock({ children }: { children?: React.ReactNode }) {
+ if (React.isValidElement(children) && (children as React.ReactElement).type === 'code') {
+ const { className, children: code } = (children as React.ReactElement<{ className?: string; children: string }>)
+ .props;
+ return <CodeBlock className={className}>{code}</CodeBlock>;
+ }
+ return <pre>{children}</pre>;
+}
+
+type MDXComponents = Record<string, React.ElementType>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ ...components,
+ pre: PreBlock,
+ Story: StoryEmbed,
+ PropTable,
+ };
+}

packages/swingset/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/swingset/next.config.mjs

@@ -0,0 +1,36 @@
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+import rehypeRaw from 'rehype-raw';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const withMDX = createMDX({
+ options: {
+ remarkPlugins: [remarkGfm],
+ rehypePlugins: [
+ [
+ rehypeRaw,
+ {
+ passThrough: ['mdxjsEsm', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxFlowExpression', 'mdxTextExpression'],
+ },
+ ],
+ ],
+ allowDangerousHtml: true,
+ },
+});
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ pageExtensions: ['tsx', 'ts', 'mdx'],
+ compiler: {
+ emotion: true,
+ },
+ webpack(config) {
+ config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
+ return config;
+ },
+};
+
+export default withMDX(nextConfig);

packages/swingset/package.json

@@ -0,0 +1,42 @@
+{
+ "name": "@clerk/swingset",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "dev": "next dev --port 6006",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check"
+ },
+ "dependencies": {
+ "@base-ui/react": "^1.5.0",
+ "@clerk/ui": "workspace:*",
+ "@emotion/react": "^11.11.1",
+ "@tailwindcss/typography": "^0.5.19",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^1.17.0",
+ "next": "^15.0.0",
+ "next-themes": "^0.4.6",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "react-grab": "^0.1.44",
+ "rehype-raw": "^7.0.0",
+ "tailwind-merge": "^3.6.0",
+ "tw-animate-css": "^1.4.0"
+ },
+ "devDependencies": {
+ "@mdx-js/loader": "^3.1.1",
+ "@mdx-js/react": "^3.1.0",
+ "@next/mdx": "^15.0.0",
+ "@tailwindcss/postcss": "^4.0.0",
+ "@types/react": "catalog:react",
+ "@types/react-dom": "catalog:react",
+ "remark-gfm": "^4.0.0",
+ "shadcn": "^4.10.0",
+ "shiki": "^1.0.0",
+ "tailwindcss": "^4.0.0",
+ "typescript": "catalog:repo"
+ }
+}

packages/swingset/postcss.config.mjs

@@ -0,0 +1,5 @@
+exportdefault{
+plugins: {
+'@tailwindcss/postcss': {},
+},
+};

packages/swingset/src/app/components/[component]/[story]/page.tsx

@@ -0,0 +1,15 @@
+import { StoryCanvas } from '@/components/StoryCanvas';
+
+interface Props {
+ params: Promise<{ component: string; story: string }>;
+}
+
+export default async function StoryPage({ params }: Props) {
+ const { component, story } = await params;
+ return (
+ <StoryCanvas
+ componentSlug={component}
+ storySlug={story}
+ />
+ );
+}

packages/swingset/src/app/components/[component]/page.tsx

@@ -0,0 +1,10 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+ params: Promise<{ component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+ const { component } = await params;
+ return <DocsViewer slug={component} />;
+}