clerk · alexcarpenter · Aug 12, 2026 · Aug 12, 2026
diff --git a/.changeset/mosaic-item-title-to-label.md b/.changeset/mosaic-item-title-to-label.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/swingset/src/stories/item.mdx b/packages/swingset/src/stories/item.mdx
@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';
 
 # Item
 
-Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
+Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
 
 Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.
 
@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
       </Avatar.Root>
     </Item.Media>
     <Item.Content>
-      <Item.Title>Test Organization</Item.Title>
+      <Item.Label>Test Organization</Item.Label>
       <Item.Description>Member</Item.Description>
     </Item.Content>
     <Item.Actions>
@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Item.Group>;
 ```
 
-Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
+Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:
 
 ```tsx
 <Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
   <Item.Media>
     <Icon name='log-out' size='sm' />
   </Item.Media>
   <Item.Content>
-    <Item.Label>Sign out of all accounts</Item.Label>
+    <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
   </Item.Content>
 </Item.Root>;
 ```
 
 ## Parts
 
-| Part               | Class                 | Description                                                                      |
-| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
-| `Item.Root`        | `cl-item`             | Root row. Renders a `<div>`, or a custom element via `render`.                   |
-| `Item.Media`       | `cl-item-media`       | Square leading column: icon, image, or avatar. Sized by the root's `size`.       |
-| `Item.Content`     | `cl-item-content`     | Vertical stack that grows to fill the row between media and actions.             |
-| `Item.Title`       | `cl-item-title`       | Primary label. Truncates to a single line.                                       |
-| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line.                    |
-| `Item.Label`       | `cl-item-label`       | Sole label on an action row, in place of a title. Inherits the row's text color. |
-| `Item.Actions`     | `cl-item-actions`     | Trailing controls (buttons, badges).                                             |
-| `Item.Group`       | `cl-item-group`       | Vertical wrapper around a set of rows (layout only, no role).                    |
-| `Item.Separator`   | `cl-item-separator`   | Thin divider (`<hr>`) between rows.                                              |
+| Part               | Class                 | Description                                                                |
+| ------------------ | --------------------- | -------------------------------------------------------------------------- |
+| `Item.Root`        | `cl-item`             | Root row. Renders a `<div>`, or a custom element via `render`.             |
+| `Item.Media`       | `cl-item-media`       | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
+| `Item.Content`     | `cl-item-content`     | Vertical stack that grows to fill the row between media and actions.       |
+| `Item.Label`       | `cl-item-label`       | The row's label. Truncates to a single line.                               |
+| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line.              |
+| `Item.Actions`     | `cl-item-actions`     | Trailing controls (buttons, badges).                                       |
+| `Item.Group`       | `cl-item-group`       | Vertical wrapper around a set of rows (layout only, no role).              |
+| `Item.Separator`   | `cl-item-separator`   | Thin divider (`<hr>`) between rows.                                        |
 
 Every part accepts a `render` prop for element polymorphism and forwards a ref.
 
 ## Styling
 
-The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
+The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
+
+`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:
+
+| Prop      | Attribute      | Values                   | Default   |
+| --------- | -------------- | ------------------------ | --------- |
+| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |
 
 The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:
 

diff --git a/packages/swingset/src/stories/item.stories.tsx b/packages/swingset/src/stories/item.stories.tsx
@@ -32,7 +32,7 @@ export function Default() {
         </Avatar.Root>
       </Item.Media>
       <Item.Content>
-        <Item.Title>Test Organization</Item.Title>
+        <Item.Label>Test Organization</Item.Label>
         <Item.Description>Member</Item.Description>
       </Item.Content>
       <Item.Actions>
@@ -68,7 +68,7 @@ export function Interactive() {
         </Avatar.Root>
       </Item.Media>
       <Item.Content>
-        <Item.Title>Test Organization</Item.Title>
+        <Item.Label>Test Organization</Item.Label>
         <Item.Description>Member</Item.Description>
       </Item.Content>
     </Item.Root>
@@ -92,7 +92,7 @@ export function Sizes() {
             </Avatar.Root>
           </Item.Media>
           <Item.Content>
-            <Item.Title>Test Organization</Item.Title>
+            <Item.Label>Test Organization</Item.Label>
           </Item.Content>
         </Item.Root>
       ))}
@@ -114,7 +114,7 @@ export function Group() {
             </Avatar.Root>
           </Item.Media>
           <Item.Content>
-            <Item.Title>Cameron Walker</Item.Title>
+            <Item.Label>Cameron Walker</Item.Label>
             <Item.Description>cameron@clerk.com</Item.Description>
           </Item.Content>
           <Item.Actions>
@@ -158,7 +158,7 @@ export function Group() {
             </Avatar.Root>
           </Item.Media>
           <Item.Content>
-            <Item.Title>Clerk</Item.Title>
+            <Item.Label>Clerk</Item.Label>
           </Item.Content>
           <Icon
             name='check'
@@ -189,7 +189,7 @@ export function Group() {
             </Avatar.Root>
           </Item.Media>
           <Item.Content>
-            <Item.Title>Clerk</Item.Title>
+            <Item.Label>Clerk</Item.Label>
           </Item.Content>
         </Item.Root>
       </Item.Group>
@@ -215,7 +215,7 @@ export function Group() {
             </Avatar.Root>
           </Item.Media>
           <Item.Content>
-            <Item.Title>DesignCloud</Item.Title>
+            <Item.Label>DesignCloud</Item.Label>
           </Item.Content>
         </Item.Root>
       </Item.Group>
@@ -239,7 +239,7 @@ export function Group() {
             />
           </Item.Media>
           <Item.Content>
-            <Item.Label>Add account</Item.Label>
+            <Item.Label variant='secondary'>Add account</Item.Label>
           </Item.Content>
         </Item.Root>
         <Item.Root
@@ -260,7 +260,7 @@ export function Group() {
             />
           </Item.Media>
           <Item.Content>
-            <Item.Label>Sign out of all accounts</Item.Label>
+            <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
           </Item.Content>
         </Item.Root>
       </Item.Group>
@@ -324,7 +324,7 @@ export function Scrolling() {
               </Avatar.Root>
             </Item.Media>
             <Item.Content>
-              <Item.Title>{name}</Item.Title>
+              <Item.Label>{name}</Item.Label>
             </Item.Content>
           </Item.Root>
         ))}

diff --git a/packages/swingset/src/stories/scroll-area.stories.tsx b/packages/swingset/src/stories/scroll-area.stories.tsx
@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
         </Avatar.Root>
       </Item.Media>
       <Item.Content>
-        <Item.Title>{name}</Item.Title>
+        <Item.Label>{name}</Item.Label>
       </Item.Content>
     </Item.Root>
   );
@@ -166,7 +166,7 @@ export function Gutter() {
                       </Avatar.Root>
                     </Item.Media>
                     <Item.Content>
-                      <Item.Title>{name}</Item.Title>
+                      <Item.Label>{name}</Item.Label>
                     </Item.Content>
                     {/* The shift is only legible against something reaching the content's right edge. */}
                     <div className='bg-border h-4 w-8 rounded-full' />

diff --git a/packages/ui/src/mosaic/components/item/item.styles.ts b/packages/ui/src/mosaic/components/item/item.styles.ts
@@ -95,28 +95,31 @@ export const content = stylex.create({
   },
 });
 
-export const title = stylex.create({
+export const label = stylex.create({
   base: {
+    fontWeight: fontWeightVars['--cl-font-medium'],
+  },
+
+  primary: {
     color: colorVars['--cl-color-neutral'],
     fontSize: typeScaleVars['--cl-text-sm-size'],
-    fontWeight: fontWeightVars['--cl-font-medium'],
     lineHeight: typeScaleVars['--cl-text-sm-leading'],
   },
-});
-
-export const description = stylex.create({
-  base: {
-    color: colorVars['--cl-color-neutral-faded'],
+  // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
+  // what carries it through the hover promotion on an interactive row, which a fixed color would
+  // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
+  // last style that declares it, so `base` cannot hold a color either.
+  secondary: {
     fontSize: typeScaleVars['--cl-text-xs-size'],
-    fontWeight: fontWeightVars['--cl-font-normal'],
     lineHeight: typeScaleVars['--cl-text-xs-leading'],
   },
 });
 
-export const label = stylex.create({
+export const description = stylex.create({
   base: {
+    color: colorVars['--cl-color-neutral-faded'],
     fontSize: typeScaleVars['--cl-text-xs-size'],
-    fontWeight: fontWeightVars['--cl-font-medium'],
+    fontWeight: fontWeightVars['--cl-font-normal'],
     lineHeight: typeScaleVars['--cl-text-xs-leading'],
   },
 });

diff --git a/packages/ui/src/mosaic/components/item/item.test.tsx b/packages/ui/src/mosaic/components/item/item.test.tsx
@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
     expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
   });
 
+  it('reflects the label variant as a data attribute, defaulting to primary', () => {
+    const { rerender } = render(<Item.Label>Clerk</Item.Label>);
+    expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
+    rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
+    expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
+  });
+
+  // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
+  // survives on the variant that declares no color of its own. That is what puts the secondary
+  // label on the row's color and carries it through the row's hover promotion. `Item.Content`
+  // declares no color either, so it stands in for the untouched reset.
+  it('lets the row color the secondary label, and not the primary one', () => {
+    render(
+      <Item.Content data-testid='reset-only'>
+        <Item.Label>Primary</Item.Label>
+        <Item.Label variant='secondary'>Secondary</Item.Label>
+      </Item.Content>,
+    );
+
+    const atoms = (element: HTMLElement) => element.className.split(' ');
+    const resetAtoms = atoms(screen.getByTestId('reset-only'));
+    const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));
+
+    expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
+  });
+
   it('wires consumer className/style through to the element', () => {
     render(
       <Item.Root
@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
         )}
       >
         <Item.Content>
-          <Item.Title>Settings</Item.Title>
+          <Item.Label>Settings</Item.Label>
         </Item.Content>
       </Item.Root>,
     );
@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
     render(
       <Item.Root>
         <Item.Content>
-          <Item.Title>Test Organization</Item.Title>
+          <Item.Label>Test Organization</Item.Label>
           <Item.Description>Member</Item.Description>
         </Item.Content>
         <Item.Actions>
           <button type='button'>Manage</button>
         </Item.Actions>
       </Item.Root>,
     );
-    expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
+    expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
     expect(screen.getByText('Member')).toHaveClass('cl-item-description');
     expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
   });