feat(mosaic): rework Section into cards with titled headers by maxyinger · Pull Request #9991 · clerk/javascript

maxyinger · 2026-09-29T23:00:34Z

Description

Reworks Section to the card model in #9925 and moves every user profile and organization profile section onto it. Supersedes #9911, whose commit this branch carries.

Section.Group is the card: border, background, and radius move onto it, and it is a role='group' named by the Section.Title in its Section.Header. Section.Surface and the contained variant are gone.
Section.Header is a two-column grid: title and optional description on the left, optional actions on the right, centered on the title block. Card titles use the base type size at medium weight.
New Section.Body wraps the rows or list under the header and draws the divider between them; Section.Items renders a real ul/li list.
Section.Root has no title and is not a landmark unless given aria-label. Cards sit space-8 apart, panel titles sit space-6 above their first card.
Views: Profile, Email, and Phone are cards in one Account section; Password, Passkeys, and 2-step verification are cards in one Authentication section; Active devices is a single card with the sign-out-all action in its header; every other section is one card with its title in the header. The asGroup and sectionTitle props are removed.
The public --cl-section-row-min-height token is dropped in favor of a plain value.
Swingset: the Section page documents the card model and keeps one Flat example that restyles the cards from external CSS.

The changeset is empty because Section is not exported from @clerk/mosaic's public entry.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

🤖 Generated with Claude Code

vercel · 2026-09-29T23:00:37Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 30, 2026 11:27pm UTC
swingset	Ready	Preview	Sep 30, 2026 11:27pm UTC

changeset-bot · 2026-09-29T23:00:43Z

🦋 Changeset detected

Latest commit: dd32ae0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-09-29T23:01:03Z

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Repository guideline files applied to this review (3)

references/mosaic-architecture.md — configured
packages/swingset/CLAUDE.md — auto-discovered
.cursor/rules/typescript.mdc — auto-discovered

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: 404007b9-7b67-410b-ab51-97ea98cdf8a8

📥 Commits

Reviewing files that changed from the base of the PR and between 41eba8d and dd32ae0.

📒 Files selected for processing (7)

packages/mosaic/src/components/section/index.ts
packages/mosaic/src/components/section/section.styles.ts
packages/mosaic/src/components/section/section.tsx
packages/mosaic/src/features/user-profile/user-profile-delete-section/user-profile-delete-section.view.tsx
packages/mosaic/src/features/user-profile/user-profile-password-section/user-profile-password-section.types.ts
packages/swingset/src/stories/section.mdx
packages/swingset/src/stories/section.stories.tsx

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/cli (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/clerk-android (auto-detected)

💤 Files with no reviewable changes (1)

packages/mosaic/src/features/user-profile/user-profile-password-section/user-profile-password-section.types.ts

Included review availability: This review used your included allowance. 5 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

📝 Walkthrough

Walkthrough

The Section component adds grouped headers and bodies, group-level accessible naming, and list semantics for nested items. User and organization profile sections adopt the updated composition. Tests, stories, and documentation reflect the new structure. The example snippet formatter now handles the final semicolon and aligns continuation lines.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: alexcarpenter

Merge Risk: ⚪ Minimal · up to dd32a

The card composition and profile migrations show no established merge-blocking issue. The change is mergeable subject to normal test and build checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.70% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 37 functions across 42 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: reworking `Section` into cards with titled headers.
Description check	✅ Passed	The description directly explains the `Section` card model, related component changes, profile migrations, and documentation updates.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 2.70% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 37 functions across 42 files. (1 skipped: 1 unsupported.)

Fix all pre-merge checks with AI

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-09-29T23:03:46Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9991

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9991

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9991

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9991

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9991

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9991

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9991

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9991

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9991

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9991

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9991

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9991

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9991

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9991

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@9991

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9991

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9991

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9991

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9991

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9991

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9991

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9991

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9991

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9991

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9991

commit: dd32ae0

Section.Group pairs an optional Section.Title with a new Section.Surface that draws the card. Groups take variant='contained' for nested lists, rendered as Section.Header + Section.Items inside the surface, and --cl-section-row-min-height exposes the row height. The account, active devices, and authentication sections render one <section> with contained groups instead of sibling sections. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Every Section.Group is now the card: border, background, and radius move onto it, Section.Surface and the contained variant go away, and the group is named by the Section.Title inside its Section.Header. A new Section.Body wraps the rows or list under the header and draws the divider between them. Section.Items renders a real list. Root loses its title and the gap between cards is a uniform space-8. The public --cl-section-row-min-height token is dropped in favor of a plain value. Every user profile and organization profile section composes the card model; the password, passkeys, and MFA views render a group and let the security panel own the shared root, so asGroup and sectionTitle go. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Title and description stack in the first column, actions sit in the second on the title row, so a header with a description keeps its action on the right and a header without one stays vertically centered. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…itles at base Actions span both header rows when a description follows the title, so they center on the whole block; without one they stay on the title row. Card titles use the base type size at medium weight. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…flat section example Active devices renders one card: the sign-out-all action sits in the header as a ghost button and every device is a list item, current first. The password card gets a "Password" heading and keeps its action in the row. The Section page shows a flat variant restyled from external CSS. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

The password card shows its value as a single list item instead of a full-height row, a row's content centers within its minimum height, and the sign-out-all action uses the outline variant like other header actions. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…pace-6 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions Bot added the mosaic label Sep 29, 2026

vercel Bot deployed to Preview – clerk-js-sandbox September 29, 2026 23:01 View deployment

vercel Bot deployed to Preview – swingset September 29, 2026 23:03 View deployment

maxyinger mentioned this pull request Sep 30, 2026

feat(mosaic): contained section groups and Section.Surface #9911

Closed

2 of 9 tasks

maxyinger requested a review from austincalvelage September 30, 2026 17:32

maxyinger force-pushed the section-cards branch from 69b7dc5 to 41eba8d Compare September 30, 2026 17:34

vercel Bot deployed to Preview – clerk-js-sandbox September 30, 2026 17:35 View deployment

vercel Bot deployed to Preview – swingset September 30, 2026 17:37 View deployment

maxyinger requested review from alexcarpenter and austincalvelage and removed request for alexcarpenter and austincalvelage September 30, 2026 22:56

alexcarpenter approved these changes Sep 30, 2026

View reviewed changes

maxyinger and others added 7 commits September 30, 2026 17:21

fix(mosaic): open the gap between a panel title and its sections to s…

dd32ae0

…pace-6 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

maxyinger force-pushed the section-cards branch from 41eba8d to dd32ae0 Compare September 30, 2026 23:24

vercel Bot deployed to Preview – clerk-js-sandbox September 30, 2026 23:25 View deployment

vercel Bot deployed to Preview – swingset September 30, 2026 23:27 View deployment

maxyinger merged commit 2eae624 into main Oct 1, 2026
51 checks passed

maxyinger deleted the section-cards branch October 1, 2026 00:01

Navigation Menu

feat(mosaic): rework Section into cards with titled headers - #9991

feat(mosaic): rework Section into cards with titled headers#9991
maxyinger merged 7 commits into
mainfrom
section-cards

maxyinger commented Sep 29, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 29, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Sep 29, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 29, 2026 •

edited

Loading

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

pkg-pr-new Bot commented Sep 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

maxyinger commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

vercel Bot commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

pkg-pr-new Bot commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

maxyinger commented Sep 29, 2026 •

edited

Loading

vercel Bot commented Sep 29, 2026 •

edited

Loading

changeset-bot Bot commented Sep 29, 2026 •

edited

Loading

coderabbitai Bot commented Sep 29, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 29, 2026 •

edited

Loading