feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexcarpenter merged 12 commits into from
Jul 28, 2026
Merged

feat(ui): add Mosaic Avatar component #9230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
58416c5
feat(ui): add Mosaic Avatar component
alexcarpenter Jul 23, 2026
a24694c
refactor(ui): make Mosaic Avatar a compound component
alexcarpenter Jul 23, 2026
7982f48
docs(ui): update Avatar changeset for compound API
alexcarpenter Jul 23, 2026
414c00d
fix(ui): restore Avatar compound imports in swingset story
alexcarpenter Jul 23, 2026
9c2d3d7
docs(swingset): use Clerk logo in Avatar examples; document import-st…
alexcarpenter Jul 23, 2026
e06d744
refactor(ui): use Avatar.Root/.Image/.Fallback namespace API
alexcarpenter Jul 23, 2026
fe6cc36
refactor(ui): adopt mergeStyleProps rename in Avatar
alexcarpenter Jul 23, 2026
d46bd1c
fix(ui): use neutral tokens for Avatar fallback after muted removal
alexcarpenter Jul 28, 2026
96985cb
fix border radius
alexcarpenter Jul 28, 2026
0601742
extract variants
alexcarpenter Jul 28, 2026
f81aa94
refactor(ui): drive Avatar image status straight to context
alexcarpenter Jul 28, 2026
168ae35
Merge branch 'main' into carp/mosaic-avatar
alexcarpenter Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/mosaic-avatar.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.
27 changes: 14 additions & 13 deletions .claude/skills/clerk-monorepo/references/setup-and-footguns.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down
1 change: 1 addition & 0 deletions packages/swingset/CLAUDE.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
- ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down
1 change: 1 addition & 0 deletions packages/swingset/src/components/DocsViewer.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
destructive: dynamic(() => import('../stories/destructive.mdx')),
},
components: {
avatar: dynamic(() => import('../stories/avatar.mdx')),
badge: dynamic(() => import('../stories/badge.mdx')),
button: dynamic(() => import('../stories/button.mdx')),
card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down
16 changes: 16 additions & 0 deletions packages/swingset/src/lib/registry.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
Fallback as AvatarFallbackStory,
meta as avatarMeta,
Primary as AvatarPrimary,
Shapes as AvatarShapes,
Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
Colors as BadgeColors,
meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
meta: avatarMeta,
Primary: AvatarPrimary,
Fallback: AvatarFallbackStory,
Sizes: AvatarSizes,
Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
meta: badgeMeta,
Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
// Blocks
destructiveModule,
// Components
avatarModule,
badgeModule,
buttonModule,
cardComponentModule,
Expand Down
67 changes: 67 additions & 0 deletions packages/swingset/src/stories/avatar.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
name='Primary'
storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
<Avatar.Image
src='https://github.com/clerk.png'
alt='@clerk'
/>
<Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
name='Fallback'
storyModule={AvatarStories}
/>

### Sizes

<Story
name='Sizes'
storyModule={AvatarStories}
/>

### Shapes

<Story
name='Shapes'
storyModule={AvatarStories}
/>
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

alexcarpenter
merged 12 commits into

from

Jul 28, 2026
 Merged


feat(ui): add Mosaic Avatar component
#9230
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
58416c5

feat(ui): add Mosaic Avatar component


alexcarpenter Jul 23, 2026
a24694c

refactor(ui): make Mosaic Avatar a compound component


alexcarpenter Jul 23, 2026
7982f48

docs(ui): update Avatar changeset for compound API


alexcarpenter Jul 23, 2026
414c00d

fix(ui): restore Avatar compound imports in swingset story


alexcarpenter Jul 23, 2026
9c2d3d7

docs(swingset): use Clerk logo in Avatar examples; document import-st…


alexcarpenter Jul 23, 2026
e06d744

refactor(ui): use Avatar.Root/.Image/.Fallback namespace API


alexcarpenter Jul 23, 2026
fe6cc36

refactor(ui): adopt mergeStyleProps rename in Avatar


alexcarpenter Jul 23, 2026
d46bd1c

fix(ui): use neutral tokens for Avatar fallback after muted removal


alexcarpenter Jul 28, 2026
96985cb

fix border radius


alexcarpenter Jul 28, 2026
0601742

extract variants


alexcarpenter Jul 28, 2026
f81aa94

refactor(ui): drive Avatar image status straight to context


alexcarpenter Jul 28, 2026
168ae35

Merge branch 'main' into carp/mosaic-avatar


alexcarpenter Jul 28, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/mosaic-avatar.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.

27 changes: 14 additions & 13 deletions
.claude/skills/clerk-monorepo/references/setup-and-footguns.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
 - ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/src/components/DocsViewer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 destructive: dynamic(() => import('../stories/destructive.mdx')),
 },
 components: {
 avatar: dynamic(() => import('../stories/avatar.mdx')),
 badge: dynamic(() => import('../stories/badge.mdx')),
 button: dynamic(() => import('../stories/button.mdx')),
 card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down

16 changes: 16 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
 Fallback as AvatarFallbackStory,
 meta as avatarMeta,
 Primary as AvatarPrimary,
 Shapes as AvatarShapes,
 Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
 Colors as BadgeColors,
 meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
 meta: avatarMeta,
 Primary: AvatarPrimary,
 Fallback: AvatarFallbackStory,
 Sizes: AvatarSizes,
 Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
 meta: badgeMeta,
 Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
 // Blocks
 destructiveModule,
 // Components
 avatarModule,
 badgeModule,
 buttonModule,
 cardComponentModule,
Expand Down

67 changes: 67 additions & 0 deletions
packages/swingset/src/stories/avatar.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
 name='Primary'
 storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
 <Avatar.Image
 src='https://github.com/clerk.png'
 alt='@clerk'
 />
 <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
 name='Fallback'
 storyModule={AvatarStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={AvatarStories}
/>

### Shapes

<Story
 name='Shapes'
 storyModule={AvatarStories}
/>
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

alexcarpenter
merged 12 commits into

from

Jul 28, 2026
 Merged


feat(ui): add Mosaic Avatar component
#9230
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
58416c5

feat(ui): add Mosaic Avatar component


alexcarpenter Jul 23, 2026
a24694c

refactor(ui): make Mosaic Avatar a compound component


alexcarpenter Jul 23, 2026
7982f48

docs(ui): update Avatar changeset for compound API


alexcarpenter Jul 23, 2026
414c00d

fix(ui): restore Avatar compound imports in swingset story


alexcarpenter Jul 23, 2026
9c2d3d7

docs(swingset): use Clerk logo in Avatar examples; document import-st…


alexcarpenter Jul 23, 2026
e06d744

refactor(ui): use Avatar.Root/.Image/.Fallback namespace API


alexcarpenter Jul 23, 2026
fe6cc36

refactor(ui): adopt mergeStyleProps rename in Avatar


alexcarpenter Jul 23, 2026
d46bd1c

fix(ui): use neutral tokens for Avatar fallback after muted removal


alexcarpenter Jul 28, 2026
96985cb

fix border radius


alexcarpenter Jul 28, 2026
0601742

extract variants


alexcarpenter Jul 28, 2026
f81aa94

refactor(ui): drive Avatar image status straight to context


alexcarpenter Jul 28, 2026
168ae35

Merge branch 'main' into carp/mosaic-avatar


alexcarpenter Jul 28, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/mosaic-avatar.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.

27 changes: 14 additions & 13 deletions
.claude/skills/clerk-monorepo/references/setup-and-footguns.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
 - ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/src/components/DocsViewer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 destructive: dynamic(() => import('../stories/destructive.mdx')),
 },
 components: {
 avatar: dynamic(() => import('../stories/avatar.mdx')),
 badge: dynamic(() => import('../stories/badge.mdx')),
 button: dynamic(() => import('../stories/button.mdx')),
 card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down

16 changes: 16 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
 Fallback as AvatarFallbackStory,
 meta as avatarMeta,
 Primary as AvatarPrimary,
 Shapes as AvatarShapes,
 Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
 Colors as BadgeColors,
 meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
 meta: avatarMeta,
 Primary: AvatarPrimary,
 Fallback: AvatarFallbackStory,
 Sizes: AvatarSizes,
 Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
 meta: badgeMeta,
 Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
 // Blocks
 destructiveModule,
 // Components
 avatarModule,
 badgeModule,
 buttonModule,
 cardComponentModule,
Expand Down

67 changes: 67 additions & 0 deletions
packages/swingset/src/stories/avatar.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
 name='Primary'
 storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
 <Avatar.Image
 src='https://github.com/clerk.png'
 alt='@clerk'
 />
 <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
 name='Fallback'
 storyModule={AvatarStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={AvatarStories}
/>

### Shapes

<Story
 name='Shapes'
 storyModule={AvatarStories}
/>
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

alexcarpenter
merged 12 commits into

from

Jul 28, 2026
 Merged


feat(ui): add Mosaic Avatar component
#9230
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
58416c5

feat(ui): add Mosaic Avatar component


alexcarpenter Jul 23, 2026
a24694c

refactor(ui): make Mosaic Avatar a compound component


alexcarpenter Jul 23, 2026
7982f48

docs(ui): update Avatar changeset for compound API


alexcarpenter Jul 23, 2026
414c00d

fix(ui): restore Avatar compound imports in swingset story


alexcarpenter Jul 23, 2026
9c2d3d7

docs(swingset): use Clerk logo in Avatar examples; document import-st…


alexcarpenter Jul 23, 2026
e06d744

refactor(ui): use Avatar.Root/.Image/.Fallback namespace API


alexcarpenter Jul 23, 2026
fe6cc36

refactor(ui): adopt mergeStyleProps rename in Avatar


alexcarpenter Jul 23, 2026
d46bd1c

fix(ui): use neutral tokens for Avatar fallback after muted removal


alexcarpenter Jul 28, 2026
96985cb

fix border radius


alexcarpenter Jul 28, 2026
0601742

extract variants


alexcarpenter Jul 28, 2026
f81aa94

refactor(ui): drive Avatar image status straight to context


alexcarpenter Jul 28, 2026
168ae35

Merge branch 'main' into carp/mosaic-avatar


alexcarpenter Jul 28, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/mosaic-avatar.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.

27 changes: 14 additions & 13 deletions
.claude/skills/clerk-monorepo/references/setup-and-footguns.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
 - ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/src/components/DocsViewer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 destructive: dynamic(() => import('../stories/destructive.mdx')),
 },
 components: {
 avatar: dynamic(() => import('../stories/avatar.mdx')),
 badge: dynamic(() => import('../stories/badge.mdx')),
 button: dynamic(() => import('../stories/button.mdx')),
 card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down

16 changes: 16 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
 Fallback as AvatarFallbackStory,
 meta as avatarMeta,
 Primary as AvatarPrimary,
 Shapes as AvatarShapes,
 Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
 Colors as BadgeColors,
 meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
 meta: avatarMeta,
 Primary: AvatarPrimary,
 Fallback: AvatarFallbackStory,
 Sizes: AvatarSizes,
 Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
 meta: badgeMeta,
 Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
 // Blocks
 destructiveModule,
 // Components
 avatarModule,
 badgeModule,
 buttonModule,
 cardComponentModule,
Expand Down

67 changes: 67 additions & 0 deletions
packages/swingset/src/stories/avatar.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
 name='Primary'
 storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
 <Avatar.Image
 src='https://github.com/clerk.png'
 alt='@clerk'
 />
 <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
 name='Fallback'
 storyModule={AvatarStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={AvatarStories}
/>

### Shapes

<Story
 name='Shapes'
 storyModule={AvatarStories}
/>
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

alexcarpenter
merged 12 commits into

from

Jul 28, 2026
 Merged


feat(ui): add Mosaic Avatar component
#9230
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
58416c5

feat(ui): add Mosaic Avatar component


alexcarpenter Jul 23, 2026
a24694c

refactor(ui): make Mosaic Avatar a compound component


alexcarpenter Jul 23, 2026
7982f48

docs(ui): update Avatar changeset for compound API


alexcarpenter Jul 23, 2026
414c00d

fix(ui): restore Avatar compound imports in swingset story


alexcarpenter Jul 23, 2026
9c2d3d7

docs(swingset): use Clerk logo in Avatar examples; document import-st…


alexcarpenter Jul 23, 2026
e06d744

refactor(ui): use Avatar.Root/.Image/.Fallback namespace API


alexcarpenter Jul 23, 2026
fe6cc36

refactor(ui): adopt mergeStyleProps rename in Avatar


alexcarpenter Jul 23, 2026
d46bd1c

fix(ui): use neutral tokens for Avatar fallback after muted removal


alexcarpenter Jul 28, 2026
96985cb

fix border radius


alexcarpenter Jul 28, 2026
0601742

extract variants


alexcarpenter Jul 28, 2026
f81aa94

refactor(ui): drive Avatar image status straight to context


alexcarpenter Jul 28, 2026
168ae35

Merge branch 'main' into carp/mosaic-avatar


alexcarpenter Jul 28, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/mosaic-avatar.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.

27 changes: 14 additions & 13 deletions
.claude/skills/clerk-monorepo/references/setup-and-footguns.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
 - ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/src/components/DocsViewer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 destructive: dynamic(() => import('../stories/destructive.mdx')),
 },
 components: {
 avatar: dynamic(() => import('../stories/avatar.mdx')),
 badge: dynamic(() => import('../stories/badge.mdx')),
 button: dynamic(() => import('../stories/button.mdx')),
 card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down

16 changes: 16 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
 Fallback as AvatarFallbackStory,
 meta as avatarMeta,
 Primary as AvatarPrimary,
 Shapes as AvatarShapes,
 Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
 Colors as BadgeColors,
 meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
 meta: avatarMeta,
 Primary: AvatarPrimary,
 Fallback: AvatarFallbackStory,
 Sizes: AvatarSizes,
 Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
 meta: badgeMeta,
 Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
 // Blocks
 destructiveModule,
 // Components
 avatarModule,
 badgeModule,
 buttonModule,
 cardComponentModule,
Expand Down

67 changes: 67 additions & 0 deletions
packages/swingset/src/stories/avatar.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
 name='Primary'
 storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
 <Avatar.Image
 src='https://github.com/clerk.png'
 alt='@clerk'
 />
 <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
 name='Fallback'
 storyModule={AvatarStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={AvatarStories}
/>

### Shapes

<Story
 name='Shapes'
 storyModule={AvatarStories}
/>
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

alexcarpenter
merged 12 commits into

from

Jul 28, 2026
 Merged


feat(ui): add Mosaic Avatar component
#9230
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
58416c5

feat(ui): add Mosaic Avatar component


alexcarpenter Jul 23, 2026
a24694c

refactor(ui): make Mosaic Avatar a compound component


alexcarpenter Jul 23, 2026
7982f48

docs(ui): update Avatar changeset for compound API


alexcarpenter Jul 23, 2026
414c00d

fix(ui): restore Avatar compound imports in swingset story


alexcarpenter Jul 23, 2026
9c2d3d7

docs(swingset): use Clerk logo in Avatar examples; document import-st…


alexcarpenter Jul 23, 2026
e06d744

refactor(ui): use Avatar.Root/.Image/.Fallback namespace API


alexcarpenter Jul 23, 2026
fe6cc36

refactor(ui): adopt mergeStyleProps rename in Avatar


alexcarpenter Jul 23, 2026
d46bd1c

fix(ui): use neutral tokens for Avatar fallback after muted removal


alexcarpenter Jul 28, 2026
96985cb

fix border radius


alexcarpenter Jul 28, 2026
0601742

extract variants


alexcarpenter Jul 28, 2026
f81aa94

refactor(ui): drive Avatar image status straight to context


alexcarpenter Jul 28, 2026
168ae35

Merge branch 'main' into carp/mosaic-avatar


alexcarpenter Jul 28, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/mosaic-avatar.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.

27 changes: 14 additions & 13 deletions
.claude/skills/clerk-monorepo/references/setup-and-footguns.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
 - ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/src/components/DocsViewer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 destructive: dynamic(() => import('../stories/destructive.mdx')),
 },
 components: {
 avatar: dynamic(() => import('../stories/avatar.mdx')),
 badge: dynamic(() => import('../stories/badge.mdx')),
 button: dynamic(() => import('../stories/button.mdx')),
 card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down

16 changes: 16 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
 Fallback as AvatarFallbackStory,
 meta as avatarMeta,
 Primary as AvatarPrimary,
 Shapes as AvatarShapes,
 Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
 Colors as BadgeColors,
 meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
 meta: avatarMeta,
 Primary: AvatarPrimary,
 Fallback: AvatarFallbackStory,
 Sizes: AvatarSizes,
 Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
 meta: badgeMeta,
 Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
 // Blocks
 destructiveModule,
 // Components
 avatarModule,
 badgeModule,
 buttonModule,
 cardComponentModule,
Expand Down

67 changes: 67 additions & 0 deletions
packages/swingset/src/stories/avatar.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
 name='Primary'
 storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
 <Avatar.Image
 src='https://github.com/clerk.png'
 alt='@clerk'
 />
 <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
 name='Fallback'
 storyModule={AvatarStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={AvatarStories}
/>

### Shapes

<Story
 name='Shapes'
 storyModule={AvatarStories}
/>
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

alexcarpenter
merged 12 commits into

from

Jul 28, 2026
 Merged


feat(ui): add Mosaic Avatar component
#9230
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
58416c5

feat(ui): add Mosaic Avatar component


alexcarpenter Jul 23, 2026
a24694c

refactor(ui): make Mosaic Avatar a compound component


alexcarpenter Jul 23, 2026
7982f48

docs(ui): update Avatar changeset for compound API


alexcarpenter Jul 23, 2026
414c00d

fix(ui): restore Avatar compound imports in swingset story


alexcarpenter Jul 23, 2026
9c2d3d7

docs(swingset): use Clerk logo in Avatar examples; document import-st…


alexcarpenter Jul 23, 2026
e06d744

refactor(ui): use Avatar.Root/.Image/.Fallback namespace API


alexcarpenter Jul 23, 2026
fe6cc36

refactor(ui): adopt mergeStyleProps rename in Avatar


alexcarpenter Jul 23, 2026
d46bd1c

fix(ui): use neutral tokens for Avatar fallback after muted removal


alexcarpenter Jul 28, 2026
96985cb

fix border radius


alexcarpenter Jul 28, 2026
0601742

extract variants


alexcarpenter Jul 28, 2026
f81aa94

refactor(ui): drive Avatar image status straight to context


alexcarpenter Jul 28, 2026
168ae35

Merge branch 'main' into carp/mosaic-avatar


alexcarpenter Jul 28, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/mosaic-avatar.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.

27 changes: 14 additions & 13 deletions
.claude/skills/clerk-monorepo/references/setup-and-footguns.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
 - ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/src/components/DocsViewer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 destructive: dynamic(() => import('../stories/destructive.mdx')),
 },
 components: {
 avatar: dynamic(() => import('../stories/avatar.mdx')),
 badge: dynamic(() => import('../stories/badge.mdx')),
 button: dynamic(() => import('../stories/button.mdx')),
 card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down

16 changes: 16 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
 Fallback as AvatarFallbackStory,
 meta as avatarMeta,
 Primary as AvatarPrimary,
 Shapes as AvatarShapes,
 Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
 Colors as BadgeColors,
 meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
 meta: avatarMeta,
 Primary: AvatarPrimary,
 Fallback: AvatarFallbackStory,
 Sizes: AvatarSizes,
 Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
 meta: badgeMeta,
 Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
 // Blocks
 destructiveModule,
 // Components
 avatarModule,
 badgeModule,
 buttonModule,
 cardComponentModule,
Expand Down

67 changes: 67 additions & 0 deletions
packages/swingset/src/stories/avatar.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
 name='Primary'
 storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
 <Avatar.Image
 src='https://github.com/clerk.png'
 alt='@clerk'
 />
 <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
 name='Fallback'
 storyModule={AvatarStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={AvatarStories}
/>

### Shapes

<Story
 name='Shapes'
 storyModule={AvatarStories}
/>
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat(ui): add Mosaic Avatar component#9230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

alexcarpenter
merged 12 commits into

from

Jul 28, 2026
 Merged


feat(ui): add Mosaic Avatar component
#9230
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
58416c5

feat(ui): add Mosaic Avatar component


alexcarpenter Jul 23, 2026
a24694c

refactor(ui): make Mosaic Avatar a compound component


alexcarpenter Jul 23, 2026
7982f48

docs(ui): update Avatar changeset for compound API


alexcarpenter Jul 23, 2026
414c00d

fix(ui): restore Avatar compound imports in swingset story


alexcarpenter Jul 23, 2026
9c2d3d7

docs(swingset): use Clerk logo in Avatar examples; document import-st…


alexcarpenter Jul 23, 2026
e06d744

refactor(ui): use Avatar.Root/.Image/.Fallback namespace API


alexcarpenter Jul 23, 2026
fe6cc36

refactor(ui): adopt mergeStyleProps rename in Avatar


alexcarpenter Jul 23, 2026
d46bd1c

fix(ui): use neutral tokens for Avatar fallback after muted removal


alexcarpenter Jul 28, 2026
96985cb

fix border radius


alexcarpenter Jul 28, 2026
0601742

extract variants


alexcarpenter Jul 28, 2026
f81aa94

refactor(ui): drive Avatar image status straight to context


alexcarpenter Jul 28, 2026
168ae35

Merge branch 'main' into carp/mosaic-avatar


alexcarpenter Jul 28, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/mosaic-avatar.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.

27 changes: 14 additions & 13 deletions
.claude/skills/clerk-monorepo/references/setup-and-footguns.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
 - ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down

1 change: 1 addition & 0 deletions
packages/swingset/src/components/DocsViewer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 destructive: dynamic(() => import('../stories/destructive.mdx')),
 },
 components: {
 avatar: dynamic(() => import('../stories/avatar.mdx')),
 badge: dynamic(() => import('../stories/badge.mdx')),
 button: dynamic(() => import('../stories/button.mdx')),
 card: dynamic(() => import('../stories/card.component.mdx')),
Expand Down

16 changes: 16 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
// 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 {
 Fallback as AvatarFallbackStory,
 meta as avatarMeta,
 Primary as AvatarPrimary,
 Shapes as AvatarShapes,
 Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import {
 Colors as BadgeColors,
 meta as badgeMeta,
Expand DownExpand Up@@ -121,6 +128,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
 meta: avatarMeta,
 Primary: AvatarPrimary,
 Fallback: AvatarFallbackStory,
 Sizes: AvatarSizes,
 Shapes: AvatarShapes,
};

const badgeModule: StoryModule = {
 meta: badgeMeta,
 Primary: BadgePrimary,
Expand DownExpand Up@@ -184,6 +199,7 @@ export const registry: StoryModule[] = [
 // Blocks
 destructiveModule,
 // Components
 avatarModule,
 badgeModule,
 buttonModule,
 cardComponentModule,
Expand Down

67 changes: 67 additions & 0 deletions
packages/swingset/src/stories/avatar.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
 name='Primary'
 storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
 <Avatar.Image
 src='https://github.com/clerk.png'
 alt='@clerk'
 />
 <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
 name='Fallback'
 storyModule={AvatarStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={AvatarStories}
/>

### Shapes

<Story
 name='Shapes'
 storyModule={AvatarStories}
/>
Loading
Loading