From c00f6eb784e0da41df14e0a7187bd22b7bfa0f00 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 14:05:21 +0530
Subject: [PATCH 01/31] fix(badge): update badge variant to use rounded-sm for
 improved styling

---
 packages/propel/src/elements/badge/variants.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/propel/src/elements/badge/variants.ts b/packages/propel/src/elements/badge/variants.ts
index 8acb90b9..bfab9f1e 100644
--- a/packages/propel/src/elements/badge/variants.ts
+++ b/packages/propel/src/elements/badge/variants.ts
@@ -16,7 +16,7 @@ import { type StrictVariantProps } from "../../internal/variant-props";
 //   - magnitude: S / Base / Large (height, horizontal padding, text size, node size)
 //   - tone: color/sentiment (neutral, grey, brand, info, …)
 export const badgeVariants = cva(
-  "inline-flex w-fit shrink-0 items-center justify-center gap-1 rounded-full leading-none font-medium whitespace-nowrap",
+  "inline-flex w-fit shrink-0 items-center justify-center gap-1 rounded-sm leading-none font-medium whitespace-nowrap",
   {
     variants: {
       // Figma Size axis. Each step sets height, horizontal padding, text size, and the

From 232b256cce4e50e993af5d210410730e5be9a3e3 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 14:27:11 +0530
Subject: [PATCH 02/31] refactor: wrap checkbox, radio, and switch controls in
 FieldItemControlGroup for consistent layout

- Added FieldItemControlGroup to CheckboxField, CheckboxGroupFieldOption, RadioGroupFieldOption, and SwitchField components to enhance layout consistency.
- Updated field item content variants to align control heights with label text for improved visual alignment.
---
 .../checkbox-field/checkbox-field.tsx         |  5 ++++-
 .../checkbox-group-field-option.tsx           |  5 ++++-
 .../radio-group-field-option.tsx              |  5 ++++-
 .../components/switch-field/switch-field.tsx  |  5 ++++-
 .../field/field-item-control-group.tsx        | 21 +++++++++++++++++++
 packages/propel/src/elements/field/index.tsx  |  1 +
 .../propel/src/elements/field/variants.ts     | 11 ++++++++--
 7 files changed, 47 insertions(+), 6 deletions(-)
 create mode 100644 packages/propel/src/elements/field/field-item-control-group.tsx

diff --git a/packages/propel/src/components/checkbox-field/checkbox-field.tsx b/packages/propel/src/components/checkbox-field/checkbox-field.tsx
index 2e4428b1..3e5c11e4 100644
--- a/packages/propel/src/components/checkbox-field/checkbox-field.tsx
+++ b/packages/propel/src/components/checkbox-field/checkbox-field.tsx
@@ -1,5 +1,6 @@
 import type * as React from "react";
 
+import { FieldItemControlGroup } from "../../elements/field/field-item-control-group";
 import type { FieldMagnitude } from "../../elements/field/variants";
 import {
   CheckboxFieldControl,
@@ -40,7 +41,9 @@ export function CheckboxField({
   return (
     <Field name={name} disabled={disabled} invalid={error != null || undefined}>
       <FieldItem disabled={disabled}>
-        <CheckboxFieldControl disabled={disabled} {...controlProps} />
+        <FieldItemControlGroup>
+          <CheckboxFieldControl disabled={disabled} {...controlProps} />
+        </FieldItemControlGroup>
         <FieldItemContent magnitude={magnitude} description={description}>
           {label}
         </FieldItemContent>
diff --git a/packages/propel/src/components/checkbox-group-field/checkbox-group-field-option.tsx b/packages/propel/src/components/checkbox-group-field/checkbox-group-field-option.tsx
index 73d7c847..4096edec 100644
--- a/packages/propel/src/components/checkbox-group-field/checkbox-group-field-option.tsx
+++ b/packages/propel/src/components/checkbox-group-field/checkbox-group-field-option.tsx
@@ -1,5 +1,6 @@
 import type * as React from "react";
 
+import { FieldItemControlGroup } from "../../elements/field/field-item-control-group";
 import type { FieldMagnitude } from "../../elements/field/variants";
 import {
   CheckboxFieldControl,
@@ -31,7 +32,9 @@ export function CheckboxGroupFieldOption({
 
   return (
     <FieldItem disabled={props.disabled}>
-      <CheckboxFieldControl {...props} />
+      <FieldItemControlGroup>
+        <CheckboxFieldControl {...props} />
+      </FieldItemControlGroup>
       <FieldItemContent magnitude={magnitude} description={description}>
         {label}
       </FieldItemContent>
diff --git a/packages/propel/src/components/radio-group-field/radio-group-field-option.tsx b/packages/propel/src/components/radio-group-field/radio-group-field-option.tsx
index 88e8dd82..37c8d595 100644
--- a/packages/propel/src/components/radio-group-field/radio-group-field-option.tsx
+++ b/packages/propel/src/components/radio-group-field/radio-group-field-option.tsx
@@ -1,5 +1,6 @@
 import type * as React from "react";
 
+import { FieldItemControlGroup } from "../../elements/field/field-item-control-group";
 import type { FieldMagnitude } from "../../elements/field/variants";
 import { useFieldOptionMagnitude } from "../../internal/field-option-magnitude";
 import { FieldItem, FieldItemContent } from "../field";
@@ -25,7 +26,9 @@ export function RadioGroupFieldOption({
 
   return (
     <FieldItem disabled={props.disabled}>
-      <Radio {...props} />
+      <FieldItemControlGroup>
+        <Radio {...props} />
+      </FieldItemControlGroup>
       <FieldItemContent magnitude={magnitude} description={description}>
         {label}
       </FieldItemContent>
diff --git a/packages/propel/src/components/switch-field/switch-field.tsx b/packages/propel/src/components/switch-field/switch-field.tsx
index 9ebaa026..cc245362 100644
--- a/packages/propel/src/components/switch-field/switch-field.tsx
+++ b/packages/propel/src/components/switch-field/switch-field.tsx
@@ -1,5 +1,6 @@
 import type * as React from "react";
 
+import { FieldItemControlGroup } from "../../elements/field/field-item-control-group";
 import type { FieldMagnitude } from "../../elements/field/variants";
 import { Field, FieldItem, FieldItemContent } from "../field";
 import { FieldHelperText } from "../field/field-helper-text";
@@ -38,7 +39,9 @@ export function SwitchField({
   return (
     <Field name={name} disabled={disabled} invalid={error != null || undefined}>
       <FieldItem disabled={disabled}>
-        <Switch magnitude={magnitude} disabled={disabled} {...controlProps} />
+        <FieldItemControlGroup>
+          <Switch magnitude={magnitude} disabled={disabled} {...controlProps} />
+        </FieldItemControlGroup>
         <FieldItemContent magnitude={textMagnitude} description={description}>
           {label}
         </FieldItemContent>
diff --git a/packages/propel/src/elements/field/field-item-control-group.tsx b/packages/propel/src/elements/field/field-item-control-group.tsx
new file mode 100644
index 00000000..62dcd5e9
--- /dev/null
+++ b/packages/propel/src/elements/field/field-item-control-group.tsx
@@ -0,0 +1,21 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+
+import { fieldItemControlGroupVariants } from "./variants";
+
+export type FieldItemControlGroupProps = Omit<
+  useRender.ComponentProps<"div">,
+  "className" | "style"
+>;
+
+/**
+ * The control slot of a choice option row (checkbox/radio/switch): a 20px-tall box matching the
+ * label's first line box, so the wrapped control centers on that line even when the label wraps or
+ * a description follows.
+ */
+export function FieldItemControlGroup({ render, ...props }: FieldItemControlGroupProps) {
+  const defaultProps: useRender.ElementProps<"div"> = {
+    className: fieldItemControlGroupVariants(),
+  };
+  return useRender({ defaultTagName: "div", render, props: mergeProps(defaultProps, props) });
+}
diff --git a/packages/propel/src/elements/field/index.tsx b/packages/propel/src/elements/field/index.tsx
index 1e75e31d..6444e674 100644
--- a/packages/propel/src/elements/field/index.tsx
+++ b/packages/propel/src/elements/field/index.tsx
@@ -3,6 +3,7 @@ export * from "./field-control-content";
 export * from "./field-description";
 export * from "./field-error";
 export * from "./field-item";
+export * from "./field-item-control-group";
 export * from "./field-item-content";
 export * from "./field-label";
 export * from "./field-label-group";
diff --git a/packages/propel/src/elements/field/variants.ts b/packages/propel/src/elements/field/variants.ts
index c8c01cf0..7811b9f8 100644
--- a/packages/propel/src/elements/field/variants.ts
+++ b/packages/propel/src/elements/field/variants.ts
@@ -38,8 +38,15 @@ export type FieldLabelVariantProps = StrictVariantProps<typeof fieldLabelVariant
 // `required` carries the semantics), tinted danger per the Figma spec.
 export const fieldLabelRequiredMarkerVariants = cva("text-danger-primary");
 
-// The label + description column for a single choice option (checkbox/radio/switch row).
-export const fieldItemContentVariants = cva("flex min-w-0 flex-col gap-1");
+// The label + description column for a single choice option (checkbox/radio/switch row). The
+// explicit 20px line box (`leading-5`) pairs with the 20px control slot
+// (`fieldItemControlGroupVariants`) so the control centers on the label's first line.
+export const fieldItemContentVariants = cva("flex min-w-0 flex-col gap-1 leading-5");
+
+// The control slot of a choice option row: a 20px-tall box matching the label's first line box
+// (`fieldItemContentVariants`' `leading-5`), centering any control height (radio/checkbox 16px,
+// switch 14–18px) against that line — even when the label wraps or a description follows.
+export const fieldItemControlGroupVariants = cva("flex h-5 shrink-0 items-center");
 
 export const fieldDescriptionVariants = cva("text-tertiary", {
   variants: {

From 56f419b9c82a37807bb664760bbfca98feee5b9f Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 14:39:45 +0530
Subject: [PATCH 03/31] refactor(autocomplete, combobox, select): update
 description prop behavior to handle error state

- Modified the description prop in AutocompleteField, ComboboxField, and SelectField components to clarify that it is replaced by the error prop when an error is set.
- Adjusted rendering logic to ensure description is only displayed when there is no error present.
---
 .../src/components/autocomplete-field/autocomplete-field.tsx  | 4 ++--
 .../propel/src/components/combobox-field/combobox-field.tsx   | 4 ++--
 packages/propel/src/components/select-field/select-field.tsx  | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/propel/src/components/autocomplete-field/autocomplete-field.tsx b/packages/propel/src/components/autocomplete-field/autocomplete-field.tsx
index 4824bd41..722030c5 100644
--- a/packages/propel/src/components/autocomplete-field/autocomplete-field.tsx
+++ b/packages/propel/src/components/autocomplete-field/autocomplete-field.tsx
@@ -20,7 +20,7 @@ export type AutocompleteFieldProps<Value = string> = Omit<
   AutocompleteProps<Value>,
   "children" | "items"
 > & {
-  /** Supporting text shown below the input. */
+  /** Supporting text shown below the input. Replaced by `error` when an error is set. */
   description?: React.ReactNode;
   /** The clear control (e.g. an `IconButton`) carrying its own localizable `aria-label`. */
   clear: React.ReactElement;
@@ -76,7 +76,7 @@ export function AutocompleteField<Value = string>({
           <BaseAutocomplete.Clear render={clear} />
           <BaseAutocomplete.Trigger render={trigger} />
         </BaseAutocomplete.InputGroup>
-        {description != null ? (
+        {error == null && description != null ? (
           <FieldDescription magnitude={magnitude}>{description}</FieldDescription>
         ) : null}
         <BaseAutocomplete.Portal>
diff --git a/packages/propel/src/components/combobox-field/combobox-field.tsx b/packages/propel/src/components/combobox-field/combobox-field.tsx
index 5d87c46f..9bf73bd7 100644
--- a/packages/propel/src/components/combobox-field/combobox-field.tsx
+++ b/packages/propel/src/components/combobox-field/combobox-field.tsx
@@ -16,7 +16,7 @@ export type ComboboxFieldProps<Value = string> = Omit<
   ComboboxProps<Value>,
   "children" | "items"
 > & {
-  /** Supporting text shown below the input. */
+  /** Supporting text shown below the input. Replaced by `error` when an error is set. */
   description?: React.ReactNode;
   /**
    * The clear control (e.g. an `IconButton`), rendered as the combobox's clear button. It carries
@@ -74,7 +74,7 @@ export function ComboboxField<Value = string>({
           <BaseCombobox.Clear render={clear} />
           <BaseCombobox.Trigger render={trigger} />
         </BaseCombobox.InputGroup>
-        {description != null ? (
+        {error == null && description != null ? (
           <FieldDescription magnitude={magnitude}>{description}</FieldDescription>
         ) : null}
         <BaseCombobox.Portal>
diff --git a/packages/propel/src/components/select-field/select-field.tsx b/packages/propel/src/components/select-field/select-field.tsx
index 3276c471..902c54b0 100644
--- a/packages/propel/src/components/select-field/select-field.tsx
+++ b/packages/propel/src/components/select-field/select-field.tsx
@@ -31,7 +31,7 @@ export type SelectFieldOption = {
 };
 
 export type SelectFieldProps = Omit<SelectProps<string>, "children" | "items"> & {
-  /** Supporting text shown below the trigger. */
+  /** Supporting text shown below the trigger. Replaced by `error` when an error is set. */
   description?: React.ReactNode;
   /** Error text shown below the control. */
   error?: React.ReactNode;
@@ -63,7 +63,7 @@ export function SelectField({
       <Select disabled={disabled} items={options} {...selectProps}>
         <BaseSelect.Label render={<SelectLabel />}>{label}</BaseSelect.Label>
         <SelectTrigger magnitude={selectMagnitude} />
-        {description != null ? (
+        {error == null && description != null ? (
           <FieldDescription magnitude={magnitude}>{description}</FieldDescription>
         ) : null}
         <BaseSelect.Portal>

From 3c967ce7f509495ac3c4bbee649738e613ba935e Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 15:36:24 +0530
Subject: [PATCH 04/31] refactor(table): enhance editable cell behavior and
 improve table variant styles

- Updated the behavior of editable cells to ensure the selected tint is maintained only while the menu is open.
- Refined the table variant styles to incorporate directional shadows based on scroll state, improving visual feedback for pinned headers and cells.
- Adjusted the `onOpenChange` logic for better clarity and conciseness in handling selected email state.
---
 .../src/components/table/table.stories.tsx    |  8 ++--
 .../propel/src/elements/table/variants.ts     | 39 +++++++++++++++----
 2 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/packages/propel/src/components/table/table.stories.tsx b/packages/propel/src/components/table/table.stories.tsx
index 90913051..23ce21e2 100644
--- a/packages/propel/src/components/table/table.stories.tsx
+++ b/packages/propel/src/components/table/table.stories.tsx
@@ -235,8 +235,8 @@ const ROLES = ["Admin", "Member", "Guest"];
 /**
  * **Editable cells.** Each "Account type" cell is a `TableEditableCell`: clicking it opens a propel
  * `Menu` to pick a new value, which updates the row in place (Figma "Account type" editable cell).
- * The cell tints on hover and while its menu is open; the last-clicked cell keeps a stronger
- * `selected` tint to mark the active cell. Works in both table variants.
+ * The cell tints on hover and while its menu is open; the open cell also carries the stronger
+ * `selected` tint, which clears when the menu closes. Works in both table variants.
  */
 export const EditableCells: Story = {
   args: { mode: "table" },
@@ -273,9 +273,7 @@ export const EditableCells: Story = {
                 value={person.role}
                 selected={selectedEmail === person.email}
                 aria-label={`Account type for ${person.name}`}
-                onOpenChange={(next) => {
-                  if (next) setSelectedEmail(person.email);
-                }}
+                onOpenChange={(next) => setSelectedEmail(next ? person.email : null)}
               >
                 <MenuContent>
                   {ROLES.map((role) => (
diff --git a/packages/propel/src/elements/table/variants.ts b/packages/propel/src/elements/table/variants.ts
index ae417be2..8885ef89 100644
--- a/packages/propel/src/elements/table/variants.ts
+++ b/packages/propel/src/elements/table/variants.ts
@@ -15,10 +15,12 @@ export const tableScrollAreaVariants = cva(
   "relative flex max-h-full w-full flex-col overflow-hidden rounded-lg border border-subtle bg-surface-1",
 );
 
-// The scroll viewport that the `<table>` lives in.
+// The scroll viewport that the `<table>` lives in. The `group/table-viewport` marker lets pinned
+// heads/cells read Base UI's `data-overflow-x-start`/`data-overflow-x-end` scroll state to cast
+// their directional shadow only while content is scrolled behind them.
 export const tableScrollAreaViewportVariants = cva(
   cx(
-    "min-h-0 flex-1 overscroll-contain rounded-[inherit] outline-none",
+    "group/table-viewport min-h-0 flex-1 overscroll-contain rounded-[inherit] outline-none",
     "focus-visible:ring-2 focus-visible:ring-accent-strong focus-visible:ring-inset",
   ),
 );
@@ -51,11 +53,25 @@ export const tableHeadVariants = cva(
         table: "border-b border-subtle",
         spreadsheet: "border-e-[0.5px] border-b-[0.5px] border-subtle last:border-e-0",
       },
-      // Pin this header to an inline edge while the body scrolls sideways.
+      // Pin this header to an inline edge while the body scrolls sideways. The directional shadow
+      // appears only while content is scrolled behind the pinned edge (Base UI's overflow state on
+      // the viewport) and flips with the writing direction. It's cast from an `::after` box, not
+      // the cell itself: Chrome does not paint `box-shadow` on table cells under
+      // `border-collapse: collapse`.
       pinned: {
         none: "z-20",
-        start: "sticky inset-s-0 z-30 border-e-[0.5px] border-subtle",
-        end: "sticky inset-e-0 z-30 border-s-[0.5px] border-subtle",
+        start: cx(
+          "sticky inset-s-0 z-30 border-e-[0.5px] border-subtle",
+          "after:pointer-events-none after:absolute after:inset-0 after:[clip-path:inset(0_-80px)]",
+          "group-data-overflow-x-start/table-viewport:after:shadow-direction-right",
+          "rtl:group-data-overflow-x-start/table-viewport:after:shadow-direction-left",
+        ),
+        end: cx(
+          "sticky inset-e-0 z-30 border-s-[0.5px] border-subtle",
+          "after:pointer-events-none after:absolute after:inset-0 after:[clip-path:inset(0_-80px)]",
+          "group-data-overflow-x-end/table-viewport:after:shadow-direction-left",
+          "rtl:group-data-overflow-x-end/table-viewport:after:shadow-direction-right",
+        ),
       },
     },
   },
@@ -72,9 +88,18 @@ export const tableCellVariants = cva("h-11 align-middle", {
     },
     pinned: {
       none: "",
-      start:
+      start: cx(
         "sticky inset-s-0 z-10 border-e-[0.5px] border-subtle bg-layer-2 group-hover/body-row:bg-layer-2-hover",
-      end: "sticky inset-e-0 z-10 border-s-[0.5px] border-subtle bg-layer-2 group-hover/body-row:bg-layer-2-hover",
+        "after:pointer-events-none after:absolute after:inset-0 after:[clip-path:inset(0_-80px)]",
+        "group-data-overflow-x-start/table-viewport:after:shadow-direction-right",
+        "rtl:group-data-overflow-x-start/table-viewport:after:shadow-direction-left",
+      ),
+      end: cx(
+        "sticky inset-e-0 z-10 border-s-[0.5px] border-subtle bg-layer-2 group-hover/body-row:bg-layer-2-hover",
+        "after:pointer-events-none after:absolute after:inset-0 after:[clip-path:inset(0_-80px)]",
+        "group-data-overflow-x-end/table-viewport:after:shadow-direction-left",
+        "rtl:group-data-overflow-x-end/table-viewport:after:shadow-direction-right",
+      ),
     },
     // Cells that host a full-cell trigger (editable/action) drop their own padding so
     // the trigger fills the cell; plain cells keep the standard padding.

From 3924b3c36918d9b105f00d9b332fab70e052d5a7 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 15:45:37 +0530
Subject: [PATCH 05/31] refactor(pagination): unify corner radius for
 pagination items and arrows

- Updated the corner radius for pagination items and arrow buttons to `radius/sm` for consistency in design.
- Enhanced comments to clarify the design intent regarding the shared corner radius for selected numbers and arrows.
---
 packages/propel/src/elements/pagination/variants.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/propel/src/elements/pagination/variants.ts b/packages/propel/src/elements/pagination/variants.ts
index 9b3c8d1b..ba65ef1c 100644
--- a/packages/propel/src/elements/pagination/variants.ts
+++ b/packages/propel/src/elements/pagination/variants.ts
@@ -25,7 +25,8 @@ export const paginationItemVariants = cva("flex items-center");
 // 24px tall with a 24px minimum width so single digits stay square (per Figma),
 // but the slot grows for wider content — multi-digit page numbers like `100` get
 // their own width plus horizontal padding rather than clipping a fixed square.
-// `radius/sm` for page numbers, `radius/md` for the arrow buttons.
+// One `radius/sm` (4px, per Figma) across page numbers and arrows so the
+// selected-number fill and the arrow fill share a corner radius.
 const slotBase = cx(
   "inline-flex h-6 w-auto min-w-6 shrink-0 items-center justify-center px-1",
   "text-13 text-primary outline-none",
@@ -51,7 +52,7 @@ export const paginationPageButtonVariants = cva(
 export const paginationArrowButtonVariants = cva(
   cx(
     slotBase,
-    "rounded-md bg-layer-transparent text-icon-secondary",
+    "rounded-sm bg-layer-transparent text-icon-secondary",
     "hover:bg-layer-transparent-hover",
     "focus-visible:ring-2 focus-visible:ring-accent-strong",
     "disabled:pointer-events-none disabled:text-icon-disabled",

From 48f9517676b0c954dc48bf79fbe81f8221945879 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 15:54:36 +0530
Subject: [PATCH 06/31] refactor(tabs): enhance disabled tab styling and update
 comments for clarity

- Added assertions to verify that the disabled tab's label color differs from the resting state, ensuring proper visual feedback.
- Updated the tabUnderlineLabelVariants to reflect the disabled state correctly, ensuring the disabled tone is applied based on the parent tab's state.
- Improved comments to clarify the relationship between the tab's disabled state and its visual representation.
---
 packages/propel/src/elements/tabs/tabs.stories.tsx | 8 ++++++++
 packages/propel/src/elements/tabs/variants.ts      | 7 ++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/packages/propel/src/elements/tabs/tabs.stories.tsx b/packages/propel/src/elements/tabs/tabs.stories.tsx
index 9481097a..2f678cd4 100644
--- a/packages/propel/src/elements/tabs/tabs.stories.tsx
+++ b/packages/propel/src/elements/tabs/tabs.stories.tsx
@@ -251,6 +251,14 @@ export const StatesCanary: Story = {
         .backgroundColor,
     );
 
+    // The disabled tab dims its label through `group-disabled/tab` — the label owns the text color,
+    // so the tab button's own `disabled:` tone can't reach it; assert it differs from resting.
+    await expect(
+      getComputedStyle(labelOf(underlineList.getByRole("tab", { name: "Disabled" }))).color,
+    ).not.toBe(
+      getComputedStyle(labelOf(underlineList.getByRole("tab", { name: "Resting" }))).color,
+    );
+
     // The pinned `--active-tab-left` (2px) resolves through the indicator's compiled
     // `left: calc(var(--active-tab-left) + 0.5rem)` to 10px.
     const indicator = underlineListEl.querySelector(":scope > [aria-hidden]");
diff --git a/packages/propel/src/elements/tabs/variants.ts b/packages/propel/src/elements/tabs/variants.ts
index e714543b..033f0ea6 100644
--- a/packages/propel/src/elements/tabs/variants.ts
+++ b/packages/propel/src/elements/tabs/variants.ts
@@ -51,8 +51,13 @@ export const tabVariants = cva(
 
 export type TabVariantProps = StrictVariantProps<typeof tabVariants>;
 
+// The label owns the underline tab's visible text color, so the disabled tone has to key off the
+// parent tab's `disabled` here — the tab button's own `disabled:text-disabled` can't reach text a
+// child colors explicitly. The disabled/hover/active state tones are mutually exclusive in practice
+// (a tab is never both disabled and active/hovered), so their equal specificity never collides;
+// the hover background is also suppressed while disabled.
 export const tabUnderlineLabelVariants = cva(
-  "flex h-7 items-center justify-center gap-1.5 rounded-md px-2 py-0.5 text-tertiary transition-colors group-hover/tab:bg-layer-transparent-hover group-hover/tab:text-secondary group-data-active/tab:bg-layer-transparent-selected group-data-active/tab:text-primary",
+  "flex h-7 items-center justify-center gap-1.5 rounded-md px-2 py-0.5 text-tertiary transition-colors group-hover/tab:bg-layer-transparent-hover group-hover/tab:text-secondary group-disabled/tab:bg-transparent group-disabled/tab:text-disabled group-data-active/tab:bg-layer-transparent-selected group-data-active/tab:text-primary",
 );
 
 export const tabUnderlineBarTrackVariants = cva("flex px-2");

From a2df919f5b8cd39ed28bdedd6f07ec92f2a58a19 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 16:41:53 +0530
Subject: [PATCH 07/31] refactor(autocomplete): tighten right padding for input
 group with trailing control

- Adjusted the right padding of the autocomplete input group to ensure the trailing button appears flush with the input field, enhancing visual balance.
- Updated comments to clarify the impact of the `:has()` selector on padding behavior when a button is present.
---
 packages/propel/src/elements/autocomplete/variants.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/propel/src/elements/autocomplete/variants.ts b/packages/propel/src/elements/autocomplete/variants.ts
index 37ec2b30..5ad05a3c 100644
--- a/packages/propel/src/elements/autocomplete/variants.ts
+++ b/packages/propel/src/elements/autocomplete/variants.ts
@@ -10,6 +10,11 @@ export const autocompleteInputGroupVariants = cva(
     // Wraps a separate focusable input → the shared `focus: within` group chrome.
     controlGroupClass,
     "w-full items-center gap-2 rounded-lg px-3",
+    // A trailing control (clear/trigger renders a `<button>`; the leading icon is a `<span>`) sits
+    // flush inside the field, not in its own oversized button well: tighten the group's right
+    // padding so the chevron/clear glyph reads as part of the input, optically balanced with the
+    // text. The `:has()` selector outweighs the flat `px-3`, so it only applies when present.
+    "has-[button]:pr-1",
   ),
   {
     variants: {

From 144625c1cc0595774f6cdec57fcbac87b2eaf034 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 17:18:15 +0530
Subject: [PATCH 08/31] refactor(pill): update border-radius to medium and
 enhance comments for clarity

- Changed the border-radius of the pill component from fully rounded to medium (md) to align with design specifications.
- Updated comments to reflect the new border-radius and clarify the design intent.
---
 packages/propel/src/elements/pill/variants.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/propel/src/elements/pill/variants.ts b/packages/propel/src/elements/pill/variants.ts
index 2ac05288..a3b1f68f 100644
--- a/packages/propel/src/elements/pill/variants.ts
+++ b/packages/propel/src/elements/pill/variants.ts
@@ -3,7 +3,7 @@ import { cva, cx } from "class-variance-authority";
 import { type StrictVariantProps } from "../../internal/variant-props";
 
 // "Always the same" per Figma design spec (issue #142):
-// - Pill-shaped border-radius (fully rounded ends)
+// - Medium (md) border-radius
 // - Inline-flex layout with centered content
 // - Height, horizontal padding, font size per size step
 // - Font weight
@@ -18,7 +18,7 @@ import { type StrictVariantProps } from "../../internal/variant-props";
 
 // Shared structural base baked into every pill container cva below.
 const pillBase =
-  "inline-flex shrink-0 items-center justify-center rounded-full border-sm outline-none transition-colors focus-visible:ring-2 focus-visible:ring-accent-strong";
+  "inline-flex shrink-0 items-center justify-center rounded-md border-sm outline-none transition-colors focus-visible:ring-2 focus-visible:ring-accent-strong";
 
 // Shared label-pill base (PillButton + PillSwitch): a 14px node scale, capped width, and
 // per-magnitude height/padding/font.

From 1868f802e2814aaf2a459ba61a38ce260f6062c5 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 17:26:31 +0530
Subject: [PATCH 09/31] refactor(otp-field, control-group): adjust size
 specifications for consistency

- Updated the width for the xl variant of the otp-field input from 11 to 10 to align with design standards.
- Modified the control group comments to reflect the new height for the xl size, changing it from 44px to 40px for improved clarity and consistency across components.
---
 packages/propel/src/elements/otp-field/variants.ts | 2 +-
 packages/propel/src/internal/control-group.ts      | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/propel/src/elements/otp-field/variants.ts b/packages/propel/src/elements/otp-field/variants.ts
index d0f9feaf..f8934e6b 100644
--- a/packages/propel/src/elements/otp-field/variants.ts
+++ b/packages/propel/src/elements/otp-field/variants.ts
@@ -28,7 +28,7 @@ export const otpFieldInputVariants = cva(
       magnitude: {
         md: cx(controlMagnitude.md, "w-8"),
         lg: cx(controlMagnitude.lg, "w-9"),
-        xl: cx(controlMagnitude.xl, "w-11"),
+        xl: cx(controlMagnitude.xl, "w-10"),
       },
     },
   },
diff --git a/packages/propel/src/internal/control-group.ts b/packages/propel/src/internal/control-group.ts
index 41dd481f..72f17a56 100644
--- a/packages/propel/src/internal/control-group.ts
+++ b/packages/propel/src/internal/control-group.ts
@@ -34,7 +34,7 @@ export const controlGroupClass = cx(
  * scale one label off (32/36/40 as "sm/md/lg"), and combobox had no axis at all. A step now always
  * means: height, text size, and glyph `--node-size`.
  *
- * Sm 28px / text-13 / 14px glyphs · md 32px / text-14 / 16px · lg 36px / text-14 / 16px · xl 44px /
+ * Sm 28px / text-13 / 14px glyphs · md 32px / text-14 / 16px · lg 36px / text-14 / 16px · xl 40px /
  * text-16 / 20px. Families expose the steps their Figma spec defines and add only their own
  * geometry (padding, width, radius). Multiline (`text-area`) reuses the text sizes; the
  * number-field's scale stays coupled to its stepper `IconButton` squares.
@@ -43,7 +43,7 @@ export const controlMagnitude = {
   sm: "min-h-7 text-13 [--node-size:0.875rem]",
   md: "min-h-8 text-14 [--node-size:1rem]",
   lg: "min-h-9 text-14 [--node-size:1rem]",
-  xl: "min-h-11 text-16 [--node-size:1.25rem]",
+  xl: "min-h-10 text-16 [--node-size:1.25rem]",
 } as const;
 
 /** The visible label beside/above a bordered control — one type treatment for every picker. */

From ac489574e053295df8ac7939713be35ec72c8752 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 19:39:55 +0530
Subject: [PATCH 10/31] refactor(button, control-chrome, spinner): enhance
 animations and improve comments

- Updated button label variants to include transition effects for smoother loading states.
- Modified control chrome variants to apply a unified transition effect for better visual consistency.
- Enhanced spinner component with new animations for a smoother reveal and spin effect, improving user experience.
- Added detailed comments to clarify the purpose and behavior of the new animations.
---
 packages/propel/src/elements/button/variants.ts |  4 +++-
 packages/propel/src/internal/control-chrome.ts  |  2 +-
 packages/propel/src/internal/spinner.tsx        | 16 ++++++++++++----
 packages/propel/src/styles/animations.css       | 14 ++++++++++++++
 4 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/packages/propel/src/elements/button/variants.ts b/packages/propel/src/elements/button/variants.ts
index 96521ea5..67759af9 100644
--- a/packages/propel/src/elements/button/variants.ts
+++ b/packages/propel/src/elements/button/variants.ts
@@ -19,4 +19,6 @@ export type ButtonVariantProps = StrictVariantProps<typeof buttonVariants>;
 
 // The text label inside a Button. When the parent button is `aria-busy` (loading) it dims via the
 // `group-aria-busy:` sibling of the `group` class on the root.
-export const buttonLabelVariants = cva("group-aria-busy:opacity-50");
+export const buttonLabelVariants = cva(
+  "transition-opacity duration-200 ease-out group-aria-busy:opacity-50",
+);
diff --git a/packages/propel/src/internal/control-chrome.ts b/packages/propel/src/internal/control-chrome.ts
index 72162fa3..ef016677 100644
--- a/packages/propel/src/internal/control-chrome.ts
+++ b/packages/propel/src/internal/control-chrome.ts
@@ -10,7 +10,7 @@ import { cva, cx, type VariantProps } from "class-variance-authority";
 export const controlChromeVariants = cva(
   cx(
     "group relative inline-flex shrink-0 cursor-pointer items-center justify-center rounded-md",
-    "transition-colors outline-none",
+    "transition-all duration-200 ease-out outline-none",
     "focus-visible:ring-2 focus-visible:ring-accent-strong focus-visible:ring-offset-1",
     "disabled:pointer-events-none disabled:cursor-not-allowed",
     "aria-busy:cursor-default",
diff --git a/packages/propel/src/internal/spinner.tsx b/packages/propel/src/internal/spinner.tsx
index 303cc0ed..f6042f9a 100644
--- a/packages/propel/src/internal/spinner.tsx
+++ b/packages/propel/src/internal/spinner.tsx
@@ -5,11 +5,19 @@ import { cva, cx } from "class-variance-authority";
 import { nodeSlotClass } from "./node-slot";
 
 /**
- * The shared pending-state glyph slot (rule 4a): an `aria-hidden` spinning `<span>` sizing its
- * single svg child (pass a `LoaderCircle`) to the inherited `--node-size`. Replaces the
- * byte-identical Button/IconButton/Pill spinner parts.
+ * The shared pending-state glyph slot (rule 4a): an `aria-hidden` `<span>` sizing its single svg
+ * child (pass a `LoaderCircle`) to the inherited `--node-size`. Replaces the byte-identical
+ * Button/IconButton/Pill spinner parts.
+ *
+ * Two animations run on mount: the `--animate-spinner-reveal` one-shot grows the slot from zero
+ * width and fades it in (so a control entering its loading state widens smoothly instead of
+ * snapping), while the perpetual `spin` rotates the glyph. They live on separate elements because
+ * an element has a single `animation` slot: the reveal owns the span, the spin owns the svg child.
+ * `overflow-hidden` clips the glyph while the slot is still expanding.
  */
-export const spinnerVariants = cva(cx(nodeSlotClass, "animate-spin"));
+export const spinnerVariants = cva(
+  cx(nodeSlotClass, "animate-spinner-reveal overflow-hidden [&>svg]:animate-spin"),
+);
 
 export type SpinnerProps = Omit<useRender.ComponentProps<"span">, "className" | "style">;
 
diff --git a/packages/propel/src/styles/animations.css b/packages/propel/src/styles/animations.css
index 69346926..d0c602cf 100644
--- a/packages/propel/src/styles/animations.css
+++ b/packages/propel/src/styles/animations.css
@@ -86,6 +86,20 @@
     }
   }
 
+  /* spinner reveal: a loader slot growing from zero to its glyph width while fading in, so the
+     control it sits in (button, pill) widens smoothly into its loading state instead of snapping */
+  --animate-spinner-reveal: spinnerReveal 0.2s ease-out forwards;
+  @keyframes spinnerReveal {
+    0% {
+      opacity: 0;
+      width: 0;
+    }
+    100% {
+      opacity: 1;
+      width: var(--node-size);
+    }
+  }
+
   /* tour carousel animations */
   --animate-tour-carousel-slide-in-right: tourCarouselSlideInRight 0.4s
     cubic-bezier(0.25, 0.46, 0.45, 0.94) forwards;

From f3ba08f24173587d5219336654fafb3c83b7e057 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 19:53:24 +0530
Subject: [PATCH 11/31] refactor(link-chrome): update secondary link variant
 and adjust text size specifications

- Changed the secondary link variant from `text-secondary hover:text-primary` to `text-tertiary hover:text-primary` for clearer hover visibility.
- Adjusted text size specifications for the lg and xl variants to ensure distinct font sizes at each magnitude, enhancing visual hierarchy.
---
 packages/propel/src/internal/link-chrome.ts | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/packages/propel/src/internal/link-chrome.ts b/packages/propel/src/internal/link-chrome.ts
index 7384e613..7dbf281f 100644
--- a/packages/propel/src/internal/link-chrome.ts
+++ b/packages/propel/src/internal/link-chrome.ts
@@ -16,13 +16,19 @@ export const linkChromeVariants = cva(
     variants: {
       prominence: {
         primary: "text-link-primary hover:text-link-primary-hover",
-        secondary: "text-secondary hover:text-primary",
+        // The muted link rests at `tertiary` and darkens two steps to `primary` on hover — a wider
+        // default→hover gap than `secondary`→`primary` gave, so the hover reads clearly.
+        secondary: "text-tertiary hover:text-primary",
       },
+      // Inline text has no height/padding, so text size is the ONLY size cue — the scale must step
+      // the font itself at every magnitude (unlike `buttonGeometryVariants`, where the button
+      // height carries the step and `md`/`lg` can share a font size). One distinct token per step:
+      // 12·13·14·16.
       magnitude: {
         sm: "text-12 leading-snug [--node-size:0.75rem]",
         md: "text-13 [--node-size:0.875rem]",
-        lg: "text-13 [--node-size:0.875rem]",
-        xl: "text-14 [--node-size:1rem]",
+        lg: "text-14 [--node-size:1rem]",
+        xl: "text-16 [--node-size:1.25rem]",
       },
     },
   },

From d9f56cababb82e0a390b30b0b479c2c5674cbeec Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Mon, 6 Jul 2026 20:33:46 +0530
Subject: [PATCH 12/31] feat(drawer): introduce DrawerHeader component with
 built-in close functionality

- Added a new DrawerHeader component that includes a built-in corner close button for consistent user experience across drawers.
- Updated drawer stories to reflect the new DrawerHeader implementation, removing manual close button instances.
- Adjusted comments and exports in related files to accommodate the new component structure.
---
 .../src/components/drawer/drawer-header.tsx   | 36 +++++++++++++++++++
 .../propel/src/components/drawer/index.tsx    |  7 ++--
 .../propel/src/elements/drawer/variants.ts    |  5 ++-
 3 files changed, 44 insertions(+), 4 deletions(-)
 create mode 100644 packages/propel/src/components/drawer/drawer-header.tsx

diff --git a/packages/propel/src/components/drawer/drawer-header.tsx b/packages/propel/src/components/drawer/drawer-header.tsx
new file mode 100644
index 00000000..6e61ce56
--- /dev/null
+++ b/packages/propel/src/components/drawer/drawer-header.tsx
@@ -0,0 +1,36 @@
+import { Drawer as BaseDrawer } from "@base-ui/react/drawer";
+import { X } from "lucide-react";
+
+import {
+  DrawerHeader as DrawerHeaderElement,
+  type DrawerHeaderProps as DrawerHeaderElementProps,
+} from "../../elements/drawer";
+import { IconButton } from "../icon-button";
+
+export type DrawerHeaderProps = DrawerHeaderElementProps & {
+  /** Accessible label for the built-in corner close button. @default "Close" */
+  closeLabel?: string;
+};
+
+/**
+ * The drawer's top region with a built-in corner close: lays the consumer's heading block (a
+ * `DrawerHeaderContent`) at the inline-start and a ghost `IconButton` dismiss at the inline-end, so
+ * every drawer gets a consistent close without hand-wiring one. The close grafts Base UI's
+ * `Drawer.Close` behavior onto the `IconButton` (behavior part outer, styled part as render
+ * target). Pass `closeLabel` to localize its accessible name. For a header without the close,
+ * compose the `elements/drawer` `DrawerHeader` atom directly.
+ */
+export function DrawerHeader({ closeLabel = "Close", children, ...props }: DrawerHeaderProps) {
+  return (
+    <DrawerHeaderElement {...props}>
+      {children}
+      <BaseDrawer.Close
+        render={
+          <IconButton prominence="ghost" tone="neutral" magnitude="lg" aria-label={closeLabel}>
+            <X aria-hidden />
+          </IconButton>
+        }
+      />
+    </DrawerHeaderElement>
+  );
+}
diff --git a/packages/propel/src/components/drawer/index.tsx b/packages/propel/src/components/drawer/index.tsx
index e6ef9213..ad2ccd36 100644
--- a/packages/propel/src/components/drawer/index.tsx
+++ b/packages/propel/src/components/drawer/index.tsx
@@ -9,11 +9,14 @@ export * from "./drawer-backdrop";
 export * from "./drawer-title";
 export * from "./drawer-description";
 export * from "./drawer-panel";
+export * from "./drawer-header";
 export * from "./create-handle";
 // Re-export the styled `elements` parts so a full drawer can be assembled from one entry. The
 // behavior-only roles need no Base UI at the call site: `DrawerTrigger`/`DrawerClose` above are
 // the passthroughs, and `DrawerPanel` composes the `Portal`. The styled bare close control stays
-// in `elements/drawer` — the `DrawerClose` behavior part replaces its re-export here.
+// in `elements/drawer` — the `DrawerClose` behavior part replaces its re-export here. `DrawerHeader`
+// is NOT re-exported from `elements` here: the `./drawer-header` ready-made (with the built-in
+// corner close) shadows it; the close-less atom stays reachable at `@plane/propel/elements/drawer`.
 export {
   DrawerBody,
   type DrawerBodyProps,
@@ -21,8 +24,6 @@ export {
   type DrawerContentProps,
   DrawerFooter,
   type DrawerFooterProps,
-  DrawerHeader,
-  type DrawerHeaderProps,
   DrawerHeaderContent,
   type DrawerHeaderContentProps,
   DrawerPopup,
diff --git a/packages/propel/src/elements/drawer/variants.ts b/packages/propel/src/elements/drawer/variants.ts
index 181dd7b9..16efc674 100644
--- a/packages/propel/src/elements/drawer/variants.ts
+++ b/packages/propel/src/elements/drawer/variants.ts
@@ -22,7 +22,10 @@ export const drawerViewportVariants = cva("fixed inset-0 z-50");
 export const drawerPopupVariants = cva(
   cx(
     "fixed inset-y-0 z-50 flex h-full w-80 max-w-[90vw] flex-col",
-    "border-subtle bg-layer-1 shadow-overlay-100 outline-none",
+    // `surface-1` is the on-top-of-page panel surface every other overlay uses (the shared
+    // `internal/surface` recipe: menus, toast, calendar, toolbar). `layer-1` is an interactive
+    // control fill (it carries hover/active/selected variants), wrong for a static panel.
+    "border-subtle bg-surface-1 shadow-overlay-100 outline-none",
     "transition-transform duration-200",
   ),
   {

From db39f4cb22a90002db2ec7827b348be55378304c Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 10:13:41 +0530
Subject: [PATCH 13/31] refactor(popover): enhance panel row structure and
 improve alignment

- Refactored the PanelRow component to standardize the layout for various controls, ensuring consistent height across Radio and Checkbox elements.
- Updated the ToggleFooter to utilize the new PanelRow for better visual alignment and user interaction.
- Improved comments to clarify the purpose of alignment adjustments in the popover stories, ensuring panels extend inward to avoid overflow.
---
 .../components/popover/popover.stories.tsx    | 47 ++++++++++++++-----
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/packages/propel/src/components/popover/popover.stories.tsx b/packages/propel/src/components/popover/popover.stories.tsx
index 4345a3d8..73526c6a 100644
--- a/packages/propel/src/components/popover/popover.stories.tsx
+++ b/packages/propel/src/components/popover/popover.stories.tsx
@@ -38,21 +38,30 @@ function PanelSeparator() {
   return <div className="-mx-1 my-1 border-t border-subtle" />;
 }
 
-// A row whose leading control is a propel Radio, for single-select sort lists.
-// Sized to match a MenuItem (34px tall, `rounded-md`) so the panel reads like
-// the menu.
-function PanelRadioRow({ value, label }: { value: string; label: string }) {
+// One option row for the panels, sized to match a MenuItem (34px tall, `rounded-md`) so
+// every leading control — Radio, Checkbox, anything — lands on the SAME row height and the
+// panel reads like the menu. The whole row is the clickable `<label>`; a bare control goes
+// in `control` and the text as children (the wrapping label names the control, so the bare
+// box/circle needs no `aria-label`, mirroring a native labelled input).
+function PanelRow({ control, children }: { control: React.ReactNode; children: React.ReactNode }) {
   return (
     <label className="flex h-[34px] cursor-pointer items-center gap-2 rounded-md px-2 text-13 text-secondary hover:bg-layer-transparent-hover">
-      <Radio value={value} />
-      <span className="min-w-0 flex-1 truncate">{label}</span>
+      {control}
+      <span className="min-w-0 flex-1 truncate">{children}</span>
     </label>
   );
 }
 
-// The checkbox-toggle footer (show sub-work items / show empty groups) that closes
-// several of the display panels. Each panel gets an independent copy that owns its
-// own state; pass `defaultToggles` to start a key checked.
+// A single-select sort row: a propel Radio in the shared `PanelRow`.
+function PanelRadioRow({ value, label }: { value: string; label: string }) {
+  return <PanelRow control={<Radio value={value} />}>{label}</PanelRow>;
+}
+
+// The checkbox-toggle footer (show sub-work items / show empty groups) that closes several
+// of the display panels. Each toggle is a BARE Checkbox box in a `PanelRow` — not the propel
+// Checkbox's own shorter label row — so the checkbox rows match the radio rows' 34px height.
+// Each panel gets an independent copy that owns its own state; pass `defaultToggles` to start
+// a key checked.
 function ToggleFooter({ defaultToggles = {} }: { defaultToggles?: Record<string, boolean> }) {
   const [toggles, setToggles] = React.useState<Record<string, boolean>>(defaultToggles);
   return (
@@ -363,6 +372,10 @@ const displayPopoverHandle = createPopoverHandle();
  * **DetachedTrigger** — `createPopoverHandle()` links a `PopoverTrigger` that lives OUTSIDE the
  * `Popover` to it via the `handle` prop, so a toolbar button can open a panel that is declared
  * elsewhere in the tree (the panel still anchors to the trigger that opened it).
+ *
+ * This panel uses `align="end"` (the other stories use `align="start"`): the trigger sits at the
+ * inline-end of its row, so end-aligning keeps the panel extending inward instead of overflowing
+ * the right edge. Match `align` to where the trigger sits.
  */
 export const DetachedTrigger: Story = {
   render: () => (
@@ -381,6 +394,9 @@ export const DetachedTrigger: Story = {
       </div>
       {/* The popover: declared elsewhere, associated by `handle`. */}
       <Popover handle={displayPopoverHandle}>
+        {/* `align="end"` (vs the `start` the other panels use): the trigger sits at the row's
+            inline-end, so end-aligning the panel makes it extend inward/leftward and stay on-screen
+            rather than overflowing the right edge. */}
         <PopoverContent side="bottom" align="end" sizing="md" aria-label="Display options">
           <ToggleFooter defaultToggles={{ sub: true }} />
         </PopoverContent>
@@ -494,8 +510,13 @@ export const MultipleTriggersInteraction: Story = {
 /**
  * **Controlled** — external state drives the popover via `open` + `onOpenChange`, with `triggerId`
  * naming the active trigger among several (each `PopoverTrigger` gets an `id`; the change event's
- * `trigger` element reports which one fired). The panel content follows the active trigger, and a
- * plain button outside the popover reopens the Filter panel programmatically.
+ * `trigger` element reports which one fired). The panel content follows the active trigger.
+ *
+ * The "Reopen filters" button is a plain button OUTSIDE the popover: it sets `open` and points
+ * `triggerId` at the Filter trigger. Because the panel anchors to whatever `triggerId` names, it
+ * reopens **under the Filter button**, not under "Reopen filters" — that's how a toolbar action can
+ * reopen a panel at its original anchor. Set `triggerId` to control where a programmatic open
+ * lands.
  */
 export const Controlled: Story = {
   render: function Render() {
@@ -545,7 +566,9 @@ export const Controlled: Story = {
             )}
           </PopoverContent>
         </Popover>
-        {/* Programmatic opening: any control can set the state (and the target trigger). */}
+        {/* Programmatic opening: any control can set the state AND the target trigger. Because it
+            sets `triggerId` to the Filter trigger, the panel anchors to (opens under) THAT trigger,
+            not this button — clicking here reopens the Filter panel where the Filter button is. */}
         <Button
           sizing="hug"
           prominence="tertiary"

From 007e8ea3061a58388d5d91f7b0ed8ede98ab1b12 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 10:39:00 +0530
Subject: [PATCH 14/31] refactor(breadcrumb): update color variants and improve
 height consistency

- Changed icon and disclosure indicator tint from `tertiary` to `secondary` for better visual alignment.
- Updated breadcrumb link and page variants to ensure consistent height across elements, fixing the height to `h-6` (24px) for uniformity.
- Enhanced comments to clarify design specifications and behavior of breadcrumb components.
---
 .../breadcrumb/breadcrumb-menu-trigger.tsx    |  2 +-
 .../src/elements/breadcrumb/variants.ts       | 27 +++++++++++++------
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/packages/propel/src/components/breadcrumb/breadcrumb-menu-trigger.tsx b/packages/propel/src/components/breadcrumb/breadcrumb-menu-trigger.tsx
index 04317ade..755e5a72 100644
--- a/packages/propel/src/components/breadcrumb/breadcrumb-menu-trigger.tsx
+++ b/packages/propel/src/components/breadcrumb/breadcrumb-menu-trigger.tsx
@@ -21,7 +21,7 @@ export function BreadcrumbMenuTrigger({ icon, label, ...props }: BreadcrumbMenuT
     <BaseMenu.Trigger render={<BreadcrumbTrigger group />} {...props}>
       {icon}
       {label}
-      <DisclosureIndicator motion="disclose" tint="tertiary" magnitude="sm">
+      <DisclosureIndicator motion="disclose" tint="secondary" magnitude="sm">
         <ChevronDown />
       </DisclosureIndicator>
     </BaseMenu.Trigger>
diff --git a/packages/propel/src/elements/breadcrumb/variants.ts b/packages/propel/src/elements/breadcrumb/variants.ts
index f6bbb7aa..e2354dad 100644
--- a/packages/propel/src/elements/breadcrumb/variants.ts
+++ b/packages/propel/src/elements/breadcrumb/variants.ts
@@ -2,14 +2,22 @@ import { cva, cx } from "class-variance-authority";
 
 import { nodeSlotClass } from "../../internal/node-slot";
 
-/** Chrome for `BreadcrumbLink` — a navigable (hoverable) crumb anchor. */
+/**
+ * Chrome for `BreadcrumbLink` — a navigable (hoverable) crumb anchor. Resting text is `tertiary`;
+ * hover only adds the `transparent-hover` fill and does NOT recolor the text (the crumb goes
+ * `primary` only when it is the current page — `BreadcrumbPage`). Icons render one step darker than
+ * the text (`icon-secondary`), set on the icon slot, not inherited from `currentColor`.
+ *
+ * Fixed `h-6` (24px, per Figma): every crumb is the same height whether or not it has a leading
+ * icon — the 16px icon and 14px text center inside the 24px box — so a mixed trail stays flush.
+ */
 export const breadcrumbLinkVariants = cva(
-  "inline-flex items-center gap-1.5 rounded-md px-1 py-0.5 text-14 leading-none font-medium text-tertiary transition-colors hover:bg-layer-transparent-hover hover:text-primary",
+  "inline-flex h-6 items-center gap-1.5 rounded-md px-1 text-14 leading-none font-medium text-tertiary transition-colors hover:bg-layer-transparent-hover",
 );
 
-/** Chrome for `BreadcrumbPage` — the current page (non-interactive) crumb. */
+/** Chrome for `BreadcrumbPage` — the current page (non-interactive) crumb. Fixed `h-6` (24px). */
 export const breadcrumbPageVariants = cva(
-  "inline-flex items-center gap-1.5 rounded-md px-1 py-0.5 text-14 leading-none font-medium text-primary",
+  "inline-flex h-6 items-center gap-1.5 rounded-md px-1 text-14 leading-none font-medium text-primary",
 );
 
 /**
@@ -17,7 +25,9 @@ export const breadcrumbPageVariants = cva(
  * and an optional `group/trigger` marker so descendant chevrons can react to the popup open state.
  */
 export const breadcrumbTriggerVariants = cva(
-  "inline-flex cursor-default items-center gap-1.5 rounded-md px-1 py-0.5 text-14 leading-none font-medium text-tertiary transition-colors [--node-size:0.875rem] hover:bg-layer-transparent-hover hover:text-primary data-popup-open:bg-layer-transparent-hover data-popup-open:text-primary",
+  // Resting text `tertiary`; hover only adds the fill (no recolor, matching a link crumb). The
+  // OPEN menu is the crumb's active state, so `data-popup-open` shifts text to `primary`.
+  "inline-flex h-6 cursor-default items-center gap-1.5 rounded-md px-1 text-14 leading-none font-medium text-tertiary transition-colors [--node-size:0.875rem] hover:bg-layer-transparent-hover data-popup-open:bg-layer-transparent-hover data-popup-open:text-primary",
   {
     variants: {
       /** Adds `group/trigger` so descendant elements can use `group-data-popup-open/trigger:*`. */
@@ -35,11 +45,12 @@ export const breadcrumbItemVariants = cva("inline-flex items-center");
 /**
  * The visual divider between crumbs. Sizes any child icon to `--node-size` via the shared node-slot
  * class, so callers pass raw SVGs without extra wrappers. Chevron icons are RTL-mirrored via
- * `rtl:[&>svg]:-scale-x-100`.
+ * `rtl:[&>svg]:-scale-x-100`. Fixed `size-6` (24px, per Figma): the 14px chevron centers in a
+ * 24px-square box so the divider matches the crumbs' height.
  */
 export const breadcrumbSeparatorVariants = cva(
-  cx(nodeSlotClass, "px-1 text-icon-tertiary [--node-size:0.875rem] rtl:[&>svg]:-scale-x-100"),
+  cx(nodeSlotClass, "size-6 text-icon-secondary [--node-size:0.875rem] rtl:[&>svg]:-scale-x-100"),
 );
 
 /** The `<ol>` that carries the ordered trail of crumbs. */
-export const breadcrumbListVariants = cva("flex items-center gap-0.5");
+export const breadcrumbListVariants = cva("flex items-center");

From cff06d06c37e780bc0f054ecbcf0b13fd77508e6 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 10:46:29 +0530
Subject: [PATCH 15/31] refactor(select-field): replace SelectLabel with
 FieldLabel for consistent label sizing

- Updated the SelectField component to use FieldLabel instead of SelectLabel, ensuring the label size matches other form fields.
- Enhanced comments to explain the rationale behind the change, focusing on visual consistency across form elements.
---
 .../src/components/select-field/select-field.tsx      | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/propel/src/components/select-field/select-field.tsx b/packages/propel/src/components/select-field/select-field.tsx
index 902c54b0..f50555ab 100644
--- a/packages/propel/src/components/select-field/select-field.tsx
+++ b/packages/propel/src/components/select-field/select-field.tsx
@@ -5,13 +5,12 @@ import type * as React from "react";
 import type { FieldMagnitude } from "../../elements/field/variants";
 import {
   SelectItemIndicator,
-  SelectLabel,
   type SelectTriggerMagnitude,
 } from "../../elements/select/index";
 import { ListboxItem } from "../../internal/listbox-item";
 import { ListboxPopup } from "../../internal/listbox-popup";
 import { Positioner } from "../../internal/positioner";
-import { Field, FieldDescription } from "../field";
+import { Field, FieldDescription, FieldLabel } from "../field";
 import { FieldHelperText } from "../field/field-helper-text";
 import { Select, SelectTrigger, type SelectProps } from "../select";
 
@@ -61,7 +60,13 @@ export function SelectField({
   return (
     <Field name={name} disabled={disabled} invalid={error != null || undefined}>
       <Select disabled={disabled} items={options} {...selectProps}>
-        <BaseSelect.Label render={<SelectLabel />}>{label}</BaseSelect.Label>
+        {/* Use the shared `FieldLabel` (magnitude-scaled: md=text-13) so the select field's label
+            matches the other field labels — the picker's own fixed-`text-14` `SelectLabel` made it a
+            step too large next to Input/Radio/Checkbox in a form. `Field.Root` still associates it
+            with the trigger. */}
+        <FieldLabel magnitude={magnitude} inset={false}>
+          {label}
+        </FieldLabel>
         <SelectTrigger magnitude={selectMagnitude} />
         {error == null && description != null ? (
           <FieldDescription magnitude={magnitude}>{description}</FieldDescription>

From ed29335412a5b5df0957ec128f3cca118188a8e4 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 11:13:56 +0530
Subject: [PATCH 16/31] refactor(checkbox, radio, switch): unify transition
 durations and enhance comments

- Updated transition durations for Checkbox, Radio, and Switch components to a consistent 100ms for improved responsiveness.
- Enhanced comments to clarify the rationale behind the changes, ensuring a cohesive user experience across toggle controls.
- Added CheckboxField to the Checkbox stories for better integration and documentation of form behavior.
---
 .../components/checkbox/checkbox.stories.tsx  | 40 +++++++++++++------
 .../propel/src/elements/radio/variants.ts     |  4 +-
 .../propel/src/elements/switch/variants.ts    |  7 +++-
 packages/propel/src/internal/checkbox-box.ts  | 16 ++++++--
 4 files changed, 49 insertions(+), 18 deletions(-)

diff --git a/packages/propel/src/components/checkbox/checkbox.stories.tsx b/packages/propel/src/components/checkbox/checkbox.stories.tsx
index ca5d01a6..3fb3b202 100644
--- a/packages/propel/src/components/checkbox/checkbox.stories.tsx
+++ b/packages/propel/src/components/checkbox/checkbox.stories.tsx
@@ -4,6 +4,7 @@ import * as React from "react";
 import { expect, userEvent } from "storybook/test";
 
 import { Button } from "../button";
+import { CheckboxField } from "../checkbox-field";
 import { Field } from "../field";
 import { Form, FormActions, FormBody } from "../form";
 import { Icon } from "../icon";
@@ -17,10 +18,14 @@ import {
 const meta = {
   title: "Components/Checkbox",
   component: Checkbox,
+  // The ready-made Checkbox is the bare box (+ optional inline label); CheckboxField is the
+  // labeled-row composition that owns the Field name for form submission — add its tab to the
+  // args table and record the relationship in the manifest (mirrors Switch/RadioGroup).
   subcomponents: {
     CheckboxLabel,
     CheckboxIndicator,
     CheckboxIndeterminateIndicator,
+    CheckboxField,
   },
   args: {
     "aria-label": "Example",
@@ -164,9 +169,10 @@ export const Invalid: Story = {
 };
 
 /**
- * Interaction test: the invalid `Field` propagates `data-invalid` and the danger border, while the
- * checked box keeps the accent fill. Tagged out of the sidebar/docs/manifest while still running
- * under the default `test` tag.
+ * Interaction test: the invalid `Field` propagates `data-invalid` and the danger border on the
+ * RESTING box only — once checked, the danger border clears back to transparent (the accent fill
+ * alone communicates the value; a required-and-now-satisfied checkbox shouldn't still ring red).
+ * Tagged out of the sidebar/docs/manifest while still running under the default `test` tag.
  */
 export const InvalidInteraction: Story = {
   ...Invalid,
@@ -182,17 +188,29 @@ export const InvalidInteraction: Story = {
     await expect(getComputedStyle(unchecked).borderColor).not.toBe(
       getComputedStyle(resting).borderColor,
     );
-    // Checked invalid box: accent-blue fill, like every other state.
+    // Checked invalid box: accent-blue fill, like every other state...
     await expect(checked).toHaveAttribute("aria-checked", "true");
-    await expect(checked).toHaveClass("data-checked:bg-accent-primary");
+    await expect(checked).toHaveAttribute("data-invalid");
+    await expect(getComputedStyle(checked).backgroundColor).not.toBe(
+      getComputedStyle(resting).backgroundColor,
+    );
+    // ...and, despite still being `data-invalid`, the danger border does NOT persist through the
+    // checked fill: `data-checked:border-transparent` takes over, same as a checked box anywhere
+    // else — it must NOT still show the unchecked invalid box's red border.
+    await expect(getComputedStyle(checked).borderColor).not.toBe(
+      getComputedStyle(unchecked).borderColor,
+    );
   },
 };
 
 /**
- * Form integration: wrap the checkbox in a `Field` with a `name` and Base UI wires the rest — the
- * field name flows onto the box, a hidden input serializes it with the form, and `Form`'s
- * `onFormSubmit` receives the checked state as a boolean. The checkbox itself needs no extra
- * wiring. Submit to see the captured value.
+ * Form integration: a sign-in form where "Stay logged in" needs to submit alongside the rest of the
+ * fields — e.g. to extend the session server-side once the user authenticates. `CheckboxField` (the
+ * labeled-row ready-made) already owns the `Field` name, so inside a `Form` its checked state
+ * serializes with the submission — `onFormSubmit` receives it under the field's `name` as a
+ * boolean, with no extra wiring on the checkbox. Reach for the bare `Checkbox` + a hand-wired
+ * `Field` (as in the `Invalid` story above) only when you need a custom row layout `CheckboxField`
+ * doesn't offer. Submit to see the captured value.
  */
 export const FormIntegration: Story = {
   parameters: { controls: { disable: true } },
@@ -202,9 +220,7 @@ export const FormIntegration: Story = {
       <div className="flex w-80 flex-col gap-3">
         <Form<{ stayLoggedIn: boolean }> onFormSubmit={(values) => setSubmitted(values)}>
           <FormBody layout="single">
-            <Field name="stayLoggedIn">
-              <Checkbox label="Stay logged in for 7 days" />
-            </Field>
+            <CheckboxField name="stayLoggedIn" label="Stay logged in for 7 days" magnitude="md" />
           </FormBody>
           <FormActions layout="inline">
             <Button
diff --git a/packages/propel/src/elements/radio/variants.ts b/packages/propel/src/elements/radio/variants.ts
index 2bdd1339..27fd3ed1 100644
--- a/packages/propel/src/elements/radio/variants.ts
+++ b/packages/propel/src/elements/radio/variants.ts
@@ -6,7 +6,9 @@ import { type StrictVariantProps } from "../../internal/variant-props";
 export const radioVariants = cva(
   cx(
     "flex size-4 shrink-0 items-center justify-center rounded-full border-sm border-current bg-layer-1",
-    "text-icon-tertiary transition-colors outline-none",
+    // `duration-100`, matching Checkbox/Switch: one snappy fill speed across every small toggle
+    // control.
+    "text-icon-tertiary transition-colors duration-100 outline-none",
     "data-checked:text-icon-accent-primary",
     "focus-visible:ring-2 focus-visible:ring-accent-strong focus-visible:ring-offset-2",
     "data-disabled:cursor-not-allowed data-disabled:text-icon-disabled data-disabled:opacity-60",
diff --git a/packages/propel/src/elements/switch/variants.ts b/packages/propel/src/elements/switch/variants.ts
index 844367a1..f97c7ae7 100644
--- a/packages/propel/src/elements/switch/variants.ts
+++ b/packages/propel/src/elements/switch/variants.ts
@@ -14,7 +14,10 @@ import { type StrictVariantProps } from "../../internal/variant-props";
 // so the track stays the single source of the size axis.
 export const switchVariants = cva(
   cx(
-    "relative inline-flex shrink-0 items-center rounded-full p-px transition-colors",
+    // `duration-100`, matching Checkbox/Radio: one snappy fill speed across every small toggle
+    // control. The thumb's slide (`switchThumbVariants`) matches too, so the track's color change
+    // and the knob's travel finish together instead of the fill completing before the slide.
+    "relative inline-flex shrink-0 items-center rounded-full p-px transition-colors duration-100",
     // Off track = Figma icon/placeholder; on track = accent/primary.
     "bg-icon-placeholder data-checked:bg-accent-primary",
     // Unchangeable (disabled or readonly) dims the whole control to 40%,
@@ -41,7 +44,7 @@ export const switchVariants = cva(
 // `on-color` is the white-on-tone token, which holds across the theme flip.
 export const switchThumbVariants = cva(
   cx(
-    "size-(--switch-thumb-size) rounded-full bg-on-color shadow-raised-100 transition-transform",
+    "size-(--switch-thumb-size) rounded-full bg-on-color shadow-raised-100 transition-transform duration-100",
     "data-checked:translate-x-(--switch-thumb-travel)",
     "rtl:data-checked:-translate-x-(--switch-thumb-travel)",
   ),
diff --git a/packages/propel/src/internal/checkbox-box.ts b/packages/propel/src/internal/checkbox-box.ts
index 228f9ec6..25bf2fea 100644
--- a/packages/propel/src/internal/checkbox-box.ts
+++ b/packages/propel/src/internal/checkbox-box.ts
@@ -8,14 +8,24 @@ import { cva, cx } from "class-variance-authority";
  * (`data-checked`/`data-indeterminate`/`data-disabled`), so any host that sets them gets the look.
  * The error look isn't a prop: it rests at the neutral border and recolors to `danger` off
  * `data-invalid`, which Base UI's `Field.Root` propagates to the `Checkbox.Root` when the field is
- * invalid — so a single checkbox or a whole group tones danger purely from field validity.
+ * invalid — so a single checkbox or a whole group tones danger purely from field validity. The
+ * danger border is scoped to `not-data-checked:not-data-indeterminate` (rather than a bare
+ * `data-invalid:`) so it only ever shows on the RESTING (unchecked) box: without the exclusion, a
+ * checked+invalid box (e.g. a required checkbox the user has ticked) keeps the red border because
+ * Tailwind's generated stylesheet happens to emit `data-invalid` after `data-checked`, so equal
+ * (single-attribute) specificity lets it win the cascade even though the box is no longer invalid
+ * in the way that matters visually. Excluding checked/indeterminate makes the selector not match at
+ * all once filled, independent of generation order.
  */
 export const checkboxBoxVariants = cva(
   cx(
     "inline-flex size-4 shrink-0 items-center justify-center rounded-sm border-sm border-icon-tertiary align-top [--node-size:0.75rem]",
-    "transition-colors outline-none",
+    // `duration-100` (vs Tailwind's 150ms default): the box is a small, frequently-toggled target,
+    // so the resting-to-checked fill reads snappier at 100ms — the default read as a beat too slow
+    // for a click-and-move-on control.
+    "transition-colors duration-100 outline-none",
     "focus-visible:ring-2 focus-visible:ring-accent-strong focus-visible:ring-offset-1",
-    "data-invalid:border-danger-strong",
+    "data-invalid:not-data-checked:not-data-indeterminate:border-danger-strong",
     "data-checked:border-transparent data-checked:bg-accent-primary data-checked:text-icon-on-color",
     "data-indeterminate:border-transparent data-indeterminate:bg-accent-primary data-indeterminate:text-icon-on-color",
     "data-disabled:cursor-not-allowed data-disabled:border-disabled data-disabled:bg-transparent",

From a43755f97d4736d7dd188f470a4804c624b00ad0 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 11:30:51 +0530
Subject: [PATCH 17/31] refactor(context-menu): update selection indicators and
 improve item height consistency

- Replaced `Dot` with `Circle` for selection indicators in the context menu stories to enhance visual clarity.
- Adjusted item height from `h-8` to `h-[34px]` for better alignment with dropdown menu rows, ensuring a consistent user experience.
- Updated comments to clarify the rationale behind the height adjustments and styling changes.
---
 .../context-menu/context-menu.stories.tsx      |  8 ++++----
 .../src/elements/context-menu/variants.ts      | 18 +++++++++---------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/packages/propel/src/elements/context-menu/context-menu.stories.tsx b/packages/propel/src/elements/context-menu/context-menu.stories.tsx
index 392e2f1e..ca1a585f 100644
--- a/packages/propel/src/elements/context-menu/context-menu.stories.tsx
+++ b/packages/propel/src/elements/context-menu/context-menu.stories.tsx
@@ -2,9 +2,9 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import {
   Check,
   ChevronDown,
+  Circle,
   ClipboardPaste,
   Copy,
-  Dot,
   ExternalLink,
   FolderInput,
   Link2,
@@ -303,19 +303,19 @@ export const SelectionItems: Story = {
       <div role="group" aria-label="Order by">
         <ContextMenuRadioItem role="menuitemradio" aria-checked="true" tone="neutral">
           <ContextMenuRadioItemIndicator data-selected="">
-            <Dot />
+            <Circle aria-hidden />
           </ContextMenuRadioItemIndicator>
           <ContextMenuItemLabel>Manual</ContextMenuItemLabel>
         </ContextMenuRadioItem>
         <ContextMenuRadioItem role="menuitemradio" aria-checked="false" tone="neutral">
           <ContextMenuRadioItemIndicator>
-            <Dot />
+            <Circle aria-hidden />
           </ContextMenuRadioItemIndicator>
           <ContextMenuItemLabel>Created date</ContextMenuItemLabel>
         </ContextMenuRadioItem>
         <ContextMenuRadioItem role="menuitemradio" aria-checked="false" tone="neutral">
           <ContextMenuRadioItemIndicator>
-            <Dot />
+            <Circle aria-hidden />
           </ContextMenuRadioItemIndicator>
           <ContextMenuItemLabel>Priority</ContextMenuItemLabel>
         </ContextMenuRadioItem>
diff --git a/packages/propel/src/elements/context-menu/variants.ts b/packages/propel/src/elements/context-menu/variants.ts
index 1c615209..c6ba11da 100644
--- a/packages/propel/src/elements/context-menu/variants.ts
+++ b/packages/propel/src/elements/context-menu/variants.ts
@@ -11,11 +11,13 @@ export const contextMenuPopupVariants = cva(cx(popupSurfaceClass, "min-w-40 p-1"
 
 /**
  * Item rows: shared styling for Item, LinkItem, CheckboxItem and RadioItem. `--node-size` sizes the
- * row's icon regions (leading icon, selection indicator) to the 16px row glyph.
+ * row's icon regions (leading icon, selection indicator) to the 16px row glyph. `h-[34px]` (not the
+ * Tailwind `h-8`/32px step) and the highlighted state leaving `text-secondary` untouched (bg tint
+ * only) both match the dropdown `Menu`'s row exactly — the two surfaces share one row anatomy.
  */
 export const contextMenuItemVariants = cva(
   cx(
-    "flex h-8 cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
+    "flex h-[34px] cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
     "data-highlighted:bg-layer-transparent-hover",
     "data-disabled:pointer-events-none data-disabled:text-disabled",
   ),
@@ -23,9 +25,8 @@ export const contextMenuItemVariants = cva(
     variants: {
       /** Neutral rows use the standard text hierarchy; `danger` rows use the error palette. */
       tone: {
-        neutral: "text-secondary data-highlighted:text-primary",
-        danger:
-          "text-danger-primary data-disabled:text-disabled data-highlighted:text-danger-primary",
+        neutral: "text-secondary",
+        danger: "text-danger-primary data-disabled:text-disabled",
       },
     },
   },
@@ -37,7 +38,7 @@ export const contextMenuItemVariants = cva(
  */
 export const contextMenuSubmenuTriggerVariants = cva(
   cx(
-    "group/item flex h-8 cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
+    "group/item flex h-[34px] cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
     "data-highlighted:bg-layer-transparent-hover",
     "data-popup-open:bg-layer-transparent-hover",
     "data-disabled:pointer-events-none data-disabled:text-disabled",
@@ -46,9 +47,8 @@ export const contextMenuSubmenuTriggerVariants = cva(
     variants: {
       /** Neutral rows use the standard text hierarchy; `danger` rows use the error palette. */
       tone: {
-        neutral: "text-secondary data-highlighted:text-primary data-popup-open:text-primary",
-        danger:
-          "text-danger-primary data-disabled:text-disabled data-highlighted:text-danger-primary data-popup-open:text-danger-primary",
+        neutral: "text-secondary",
+        danger: "text-danger-primary data-disabled:text-disabled",
       },
     },
   },

From eb456ba86c64e3608fbdb5718435eccc0c2ca2d7 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 12:13:49 +0530
Subject: [PATCH 18/31] fix(checkbox-field, checkbox-group-field): update stale
 invalid-border test assertions

The checkbox danger-border selector gained a not-data-checked/not-data-indeterminate
guard in an earlier commit, changing its compiled class string. Two sibling
interaction tests still pinned the old literal class via toHaveClass, breaking CI.
Replaced with computed-style checks against the live --border-danger-strong token.
---
 .../checkbox-field/checkbox-field.stories.tsx    |  1 -
 .../checkbox-group-field.stories.tsx             | 16 +++++++++++++---
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/packages/propel/src/components/checkbox-field/checkbox-field.stories.tsx b/packages/propel/src/components/checkbox-field/checkbox-field.stories.tsx
index 63b5da66..d0c6a427 100644
--- a/packages/propel/src/components/checkbox-field/checkbox-field.stories.tsx
+++ b/packages/propel/src/components/checkbox-field/checkbox-field.stories.tsx
@@ -97,7 +97,6 @@ export const InvalidInteraction: Story = {
     await expect(resting).not.toHaveAttribute("data-invalid");
     // The invalid field propagates `data-invalid` onto the box (Base UI Field -> Checkbox.Root).
     await expect(invalid).toHaveAttribute("data-invalid");
-    await expect(invalid).toHaveClass("data-invalid:border-danger-strong");
     // ...and the danger border actually renders: its color differs from the resting box's border.
     await expect(getComputedStyle(invalid).borderColor).not.toBe(
       getComputedStyle(resting).borderColor,
diff --git a/packages/propel/src/components/checkbox-group-field/checkbox-group-field.stories.tsx b/packages/propel/src/components/checkbox-group-field/checkbox-group-field.stories.tsx
index cdebf142..fb65e1ee 100644
--- a/packages/propel/src/components/checkbox-group-field/checkbox-group-field.stories.tsx
+++ b/packages/propel/src/components/checkbox-group-field/checkbox-group-field.stories.tsx
@@ -92,16 +92,26 @@ export const Invalid: Story = {
 };
 
 /**
- * Interaction test: every option's box propagates `data-invalid` and the danger border class.
- * Tagged out of the sidebar/docs/manifest while still running under the default `test` tag.
+ * Interaction test: every option's box propagates `data-invalid`. The still-unchecked options show
+ * the danger border; "Email" starts `defaultValue`-checked, and a checked box keeps its transparent
+ * border (the accent fill alone communicates the value) even while the group is invalid. Tagged out
+ * of the sidebar/docs/manifest while still running under the default `test` tag.
  */
 export const InvalidInteraction: Story = {
   ...Invalid,
   tags: ["!dev", "!autodocs", "!manifest"],
   play: async ({ canvas }) => {
+    const dangerBorder = getComputedStyle(document.documentElement)
+      .getPropertyValue("--border-danger-strong")
+      .trim();
     for (const box of canvas.getAllByRole("checkbox")) {
       await expect(box).toHaveAttribute("data-invalid");
-      await expect(box).toHaveClass("data-invalid:border-danger-strong");
+      const borderColor = getComputedStyle(box).borderColor;
+      if (box.getAttribute("aria-checked") === "true") {
+        await expect(borderColor).not.toBe(dangerBorder);
+      } else {
+        await expect(borderColor).toBe(dangerBorder);
+      }
     }
   },
 };

From acbaca4f1d3f701268f96c19c5520f8189cd9688 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 14:19:45 +0530
Subject: [PATCH 19/31] refactor(menu-item): update check indicator positioning
 and improve comments

- Adjusted the `MenuItemIndicator` to render at the inline-start position, ahead of any leading icon, for better alignment with design specifications.
- Enhanced comments in the `MenuItem` and `MenuItemIndicator` components to clarify the rendering logic and selected state handling.
- Updated related stories to reflect the new positioning of the check indicator, ensuring consistency across menu items.
---
 .../src/elements/menu/menu-item-indicator.tsx |  6 ++--
 .../propel/src/elements/menu/menu.stories.tsx | 35 +++++++++++--------
 packages/propel/src/elements/menu/variants.ts | 13 ++++---
 .../src/internal/listbox-group-label.tsx      |  9 +++--
 4 files changed, 39 insertions(+), 24 deletions(-)

diff --git a/packages/propel/src/elements/menu/menu-item-indicator.tsx b/packages/propel/src/elements/menu/menu-item-indicator.tsx
index 1b196a71..7237d38c 100644
--- a/packages/propel/src/elements/menu/menu-item-indicator.tsx
+++ b/packages/propel/src/elements/menu/menu-item-indicator.tsx
@@ -6,9 +6,9 @@ import { menuItemIndicatorVariants } from "./variants";
 export type MenuItemIndicatorProps = Omit<useRender.ComponentProps<"span">, "className" | "style">;
 
 /**
- * The single-select check slot shown at a row's inline-end. Decorative (the row carries the
- * selected state), so it is `aria-hidden`. Renders and sizes its single child; pass the glyph as
- * `children`.
+ * The single-select check slot shown at a row's inline-start, before any leading icon (Figma:
+ * check, then icon, then label). Decorative (the row carries the selected state), so it is
+ * `aria-hidden`. Renders and sizes its single child; pass the glyph as `children`.
  */
 export function MenuItemIndicator({ render, ...props }: MenuItemIndicatorProps) {
   const defaultProps: useRender.ElementProps<"span"> = {
diff --git a/packages/propel/src/elements/menu/menu.stories.tsx b/packages/propel/src/elements/menu/menu.stories.tsx
index 2a06048a..146311b2 100644
--- a/packages/propel/src/elements/menu/menu.stories.tsx
+++ b/packages/propel/src/elements/menu/menu.stories.tsx
@@ -90,8 +90,9 @@ type Story = StoryObj<typeof meta>;
  * rows of internal `Icon` + `MenuItemContent` › `MenuItemTitleRow` › `MenuItemTitle`), an
  * inline-end `MenuItemEndContent` shortcut, a `MenuSubmenuTrigger` row whose caret is the internal
  * `DisclosureIndicator` (`motion="pointEnd"`), `MenuSeparator` dividers, and a single-select row
- * whose inline-end check (`MenuItemIndicator`) shows via the pinned `data-selected=""`. The
- * "Duplicate" row pins `data-highlighted=""` — the state Base UI sets on the active row.
+ * whose inline-start check (`MenuItemIndicator`, ahead of any icon) shows via the pinned
+ * `data-selected=""`. The "Duplicate" row pins `data-highlighted=""` — the state Base UI sets on
+ * the active row.
  */
 export const Default: Story = {
   render: ({ elevation }) => (
@@ -140,14 +141,14 @@ export const Default: Story = {
           </DisclosureIndicator>
         </MenuSubmenuTrigger>
         <MenuItem role="menuitem" layout="default">
+          <MenuItemIndicator data-selected="">
+            <Check />
+          </MenuItemIndicator>
           <MenuItemContent>
             <MenuItemTitleRow>
               <MenuItemTitle>Pinned</MenuItemTitle>
             </MenuItemTitleRow>
           </MenuItemContent>
-          <MenuItemIndicator data-selected="">
-            <Check />
-          </MenuItemIndicator>
         </MenuItem>
         <MenuSeparator role="separator" />
         <MenuItem role="menuitem" layout="default">
@@ -258,6 +259,9 @@ export const ItemLayouts: Story = {
         </MenuItem>
         <MenuSeparator role="separator" />
         <MenuItem role="menuitem" layout="with-description">
+          <MenuItemIndicator data-selected="">
+            <Check />
+          </MenuItemIndicator>
           <Icon tint="secondary">
             <Lock />
           </Icon>
@@ -267,11 +271,14 @@ export const ItemLayouts: Story = {
             </MenuItemTitleRow>
             <MenuItemDescription>Accessible only by invite</MenuItemDescription>
           </MenuItemContent>
-          <MenuItemIndicator data-selected="">
-            <Check />
-          </MenuItemIndicator>
         </MenuItem>
         <MenuItem role="menuitem" layout="with-description">
+          {/* Unselected, but still mounted: Private/Public form a single-select pair, so both rows
+              reserve the same leading gutter — Public's icon lines up with Private's rather than
+              sitting flush against the row's edge. */}
+          <MenuItemIndicator>
+            <Check />
+          </MenuItemIndicator>
           <Icon tint="secondary">
             <Globe />
           </Icon>
@@ -333,24 +340,24 @@ export const States: Story = {
             </MenuItemContent>
           </MenuItem>
           <MenuItem role="menuitem" layout="default">
+            <MenuItemIndicator data-selected="">
+              <Check />
+            </MenuItemIndicator>
             <MenuItemContent>
               <MenuItemTitleRow>
                 <MenuItemTitle>Selected</MenuItemTitle>
               </MenuItemTitleRow>
             </MenuItemContent>
-            <MenuItemIndicator data-selected="">
-              <Check />
-            </MenuItemIndicator>
           </MenuItem>
           <MenuItem role="menuitem" layout="default">
+            <MenuItemIndicator>
+              <Check />
+            </MenuItemIndicator>
             <MenuItemContent>
               <MenuItemTitleRow>
                 <MenuItemTitle>Unselected</MenuItemTitle>
               </MenuItemTitleRow>
             </MenuItemContent>
-            <MenuItemIndicator>
-              <Check />
-            </MenuItemIndicator>
           </MenuItem>
           <MenuSeparator role="separator" />
           <MenuSubmenuTrigger role="menuitem" aria-haspopup="menu" aria-expanded={false}>
diff --git a/packages/propel/src/elements/menu/variants.ts b/packages/propel/src/elements/menu/variants.ts
index 262c75d3..76fbca3f 100644
--- a/packages/propel/src/elements/menu/variants.ts
+++ b/packages/propel/src/elements/menu/variants.ts
@@ -126,8 +126,9 @@ export const menuItemDescriptionVariants = cva(
 export const menuItemEndContentVariants = cva(nodeSlotClass);
 
 /**
- * The single-select check shown at a row's inline-end. Sizes its single child to `--node-size` and
- * tints it with the accent. Decorative — the row carries the selected state.
+ * The single-select check shown at a row's inline-start, ahead of any leading icon. Sizes its
+ * single child to `--node-size` and tints it with the accent. Decorative — the row carries the
+ * selected state.
  */
 export const menuItemIndicatorVariants = cva(cx(itemIndicatorClass, "h-5 w-4"));
 
@@ -159,9 +160,13 @@ export const menuSeparatorVariants = cva(menuSeparatorClass);
 
 /**
  * Label: a non-interactive section heading row that can carry inline-end metadata. Lays out a
- * growing `MenuLabelTitle` and an optional `MenuLabelMeta`.
+ * growing `MenuLabelTitle` and an optional `MenuLabelMeta`. `text-caption-md-regular` (not the bare
+ * `text-12`) so it picks up the preset's `1.2` line-height, matching `MenuGroupLabel`'s height
+ * instead of falling back to the browser's taller default.
  */
-export const menuLabelVariants = cva("flex items-center gap-1.5 px-2 py-1.5 text-12 text-tertiary");
+export const menuLabelVariants = cva(
+  "flex items-center gap-1.5 px-2 py-1.5 text-caption-md-regular text-tertiary",
+);
 
 /** The growing title within a `MenuLabel`. */
 export const menuLabelTitleVariants = cva("min-w-0 flex-1 truncate");
diff --git a/packages/propel/src/internal/listbox-group-label.tsx b/packages/propel/src/internal/listbox-group-label.tsx
index d15e55c6..0556b0db 100644
--- a/packages/propel/src/internal/listbox-group-label.tsx
+++ b/packages/propel/src/internal/listbox-group-label.tsx
@@ -5,10 +5,13 @@ import { cva } from "class-variance-authority";
 /**
  * The muted heading naming a group of listbox options, grafted onto a Base UI `GroupLabel` in
  * `components` (`<BaseCombobox.GroupLabel render={<ListboxGroupLabel/>} />`). Matches the menu
- * group label's type treatment so grouped pickers and menus read the same.
+ * group label's type treatment so grouped pickers and menus read the same. `text-caption-md-medium`
+ * (not the bare `text-12 font-medium`) so the row picks up the preset's `1.2` line-height — the
+ * bare utility fell back to the browser's normal (~1.5×) line-height, rendering the heading taller
+ * than the Figma "caption/md" spec.
  */
-export const listboxGroupLabelVariants = cva("px-2 py-1.5 text-12 font-medium text-tertiary");
-export const groupLabelClass = "px-2 py-1.5 text-12 font-medium text-tertiary";
+export const listboxGroupLabelVariants = cva("px-2 py-1.5 text-caption-md-medium text-tertiary");
+export const groupLabelClass = "px-2 py-1.5 text-caption-md-medium text-tertiary";
 
 export type ListboxGroupLabelProps = Omit<useRender.ComponentProps<"div">, "className" | "style">;
 

From f188b6669b5f1513ac940c52d85a172abbcf1159 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 15:09:36 +0530
Subject: [PATCH 20/31] feat(preview-card): enhance component structure with
 new elements and improved documentation

- Introduced new components: `PreviewCardIcon`, `PreviewCardMeta`, `PreviewCardPropertyGroup`, and `PreviewCardTitleRow` to enrich the preview card's anatomy.
- Updated `PreviewCardContent` to remove the backdrop, clarifying its non-modal nature and enhancing the hover-triggered experience.
- Enhanced storybook examples to demonstrate the new components and their usage in various scenarios, including rich anatomy interactions.
- Improved comments across files to provide clearer explanations of component behavior and design rationale.
---
 .../src/components/preview-card/index.tsx     | 10 ++-
 .../preview-card/preview-card-content.tsx     | 15 ++--
 .../preview-card/preview-card.stories.tsx     | 75 ++++++++++++++++++-
 .../src/elements/preview-card/index.tsx       |  4 +
 .../preview-card/preview-card-icon.tsx        | 19 +++++
 .../preview-card/preview-card-meta.tsx        | 17 +++++
 .../preview-card-property-group.tsx           | 21 ++++++
 .../preview-card/preview-card-title-row.tsx   | 17 +++++
 .../preview-card/preview-card.stories.tsx     | 64 ++++++++++++++--
 .../src/elements/preview-card/variants.ts     | 50 +++++++++++--
 packages/propel/src/internal/backdrop.tsx     | 13 +++-
 11 files changed, 279 insertions(+), 26 deletions(-)
 create mode 100644 packages/propel/src/elements/preview-card/preview-card-icon.tsx
 create mode 100644 packages/propel/src/elements/preview-card/preview-card-meta.tsx
 create mode 100644 packages/propel/src/elements/preview-card/preview-card-property-group.tsx
 create mode 100644 packages/propel/src/elements/preview-card/preview-card-title-row.tsx

diff --git a/packages/propel/src/components/preview-card/index.tsx b/packages/propel/src/components/preview-card/index.tsx
index 9fa08ede..0ddb637a 100644
--- a/packages/propel/src/components/preview-card/index.tsx
+++ b/packages/propel/src/components/preview-card/index.tsx
@@ -6,11 +6,19 @@ export * from "./preview-card-title";
 export * from "./preview-card-trigger";
 export * from "./create-handle";
 // Re-export propel's STYLED preview-card parts so a full card can be assembled from one entry. The
-// remaining behavior/structural parts (`Portal`, `Backdrop`, `Positioner`) are composed inside
+// remaining behavior/structural parts (`Portal`, `Positioner`) are composed inside
 // `PreviewCardContent`, so consumers never wire Base UI directly.
 export {
   PreviewCardBody,
   type PreviewCardBodyProps,
+  PreviewCardIcon,
+  type PreviewCardIconProps,
   PreviewCardImage,
   type PreviewCardImageProps,
+  PreviewCardMeta,
+  type PreviewCardMetaProps,
+  PreviewCardPropertyGroup,
+  type PreviewCardPropertyGroupProps,
+  PreviewCardTitleRow,
+  type PreviewCardTitleRowProps,
 } from "../../elements/preview-card";
diff --git a/packages/propel/src/components/preview-card/preview-card-content.tsx b/packages/propel/src/components/preview-card/preview-card-content.tsx
index a8b2c710..8ffe7ea7 100644
--- a/packages/propel/src/components/preview-card/preview-card-content.tsx
+++ b/packages/propel/src/components/preview-card/preview-card-content.tsx
@@ -4,7 +4,6 @@ import {
   PreviewCardPopup,
   type PreviewCardPopupProps,
 } from "../../elements/preview-card/preview-card-popup";
-import { Backdrop } from "../../internal/backdrop";
 import { Positioner } from "../../internal/positioner";
 
 export type PreviewCardContentProps = PreviewCardPopupProps & {
@@ -17,9 +16,16 @@ export type PreviewCardContentProps = PreviewCardPopupProps & {
 };
 
 /**
- * Convenience that composes the anchored preview card boilerplate — Base UI portal, backdrop,
- * positioner, and popup grafted onto Propel's styled surfaces — so a consumer only writes the
- * trigger and the card body. Pass `side`/`sideOffset`/`align` through to the positioner.
+ * Convenience that composes the anchored preview card boilerplate — Base UI portal, positioner, and
+ * popup grafted onto Propel's styled surface — so a consumer only writes the trigger and the card
+ * body. Pass `side`/`sideOffset`/`align` through to the positioner.
+ *
+ * No backdrop: unlike Dialog/AlertDialog/Drawer, a preview card is a non-modal, hover-triggered
+ * rich tooltip (it opens on hover/focus and closes on pointer-leave/blur, with no focus trap) —
+ * dimming the page behind a hover preview reads as a modal takeover it isn't. Base UI ships a
+ * `PreviewCard.Backdrop` primitive, but it is purely optional/decorative for apps that want one; it
+ * has none of `Dialog.Backdrop`'s click-outside-to-dismiss semantics, so omitting it costs no
+ * behavior.
  */
 export function PreviewCardContent({
   side = "bottom",
@@ -29,7 +35,6 @@ export function PreviewCardContent({
 }: PreviewCardContentProps) {
   return (
     <BasePreviewCard.Portal>
-      <BasePreviewCard.Backdrop render={<Backdrop />} />
       <BasePreviewCard.Positioner
         side={side}
         sideOffset={sideOffset}
diff --git a/packages/propel/src/components/preview-card/preview-card.stories.tsx b/packages/propel/src/components/preview-card/preview-card.stories.tsx
index 059f66d3..56a63da3 100644
--- a/packages/propel/src/components/preview-card/preview-card.stories.tsx
+++ b/packages/propel/src/components/preview-card/preview-card.stories.tsx
@@ -1,7 +1,10 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { CircleDot } from "lucide-react";
 import * as React from "react";
 import { expect, userEvent, waitFor, within } from "storybook/test";
 
+import { Avatar } from "../avatar/index";
+import { Badge } from "../badge/index";
 import { Button } from "../button/index";
 import {
   createPreviewCardHandle,
@@ -10,15 +13,20 @@ import {
   PreviewCardBody,
   PreviewCardContent,
   PreviewCardDescription,
+  PreviewCardIcon,
   PreviewCardImage,
+  PreviewCardMeta,
+  PreviewCardPropertyGroup,
   PreviewCardTitle,
+  PreviewCardTitleRow,
   PreviewCardTrigger,
 } from "./index";
 
 // Components-tier story: uses the ready-made `PreviewCardContent`, which composes
-// the portal/backdrop/positioner/popup so a consumer only writes the trigger and
-// the card body (and may drop in the re-exported `PreviewCardArrow`). The trigger is
-// `PreviewCardTrigger` — propel's behavior passthrough of Base UI's `PreviewCard.Trigger`.
+// the portal/positioner/popup (no backdrop — a preview card is non-modal) so a consumer only
+// writes the trigger and the card body (and may drop in the re-exported `PreviewCardArrow`). The
+// trigger is `PreviewCardTrigger` — propel's behavior passthrough of Base UI's
+// `PreviewCard.Trigger`.
 
 const meta = {
   title: "Components/PreviewCard",
@@ -28,8 +36,12 @@ const meta = {
     PreviewCardContent,
     PreviewCardArrow,
     PreviewCardBody,
+    PreviewCardIcon,
     PreviewCardImage,
+    PreviewCardMeta,
+    PreviewCardPropertyGroup,
     PreviewCardTitle,
+    PreviewCardTitleRow,
     PreviewCardDescription,
   },
 } satisfies Meta<typeof PreviewCard>;
@@ -132,6 +144,63 @@ export const WithImageInteraction: Story = {
   },
 };
 
+/**
+ * A work-item-style link preview: `PreviewCardIcon` sits beside the title in a
+ * `PreviewCardTitleRow` (compose the row only when there's a leading icon),
+ * `PreviewCardPropertyGroup` holds a wrapping row of the consumer's own controls (here the
+ * ready-made `Badge` for status/priority and `Avatar` for the assignee — the part supplies only the
+ * row layout), and `PreviewCardMeta` closes the card with a muted caption. Every region is optional
+ * and independent — a card can add just one.
+ */
+export const WithRichAnatomy: Story = {
+  render: () => (
+    <p className="max-w-prose text-14 text-secondary">
+      See{" "}
+      <PreviewCard>
+        <PreviewCardTrigger render={triggerAnchor("https://app.plane.so/issues/WEB-142")}>
+          WEB-142
+        </PreviewCardTrigger>
+        <PreviewCardContent side="top">
+          <PreviewCardBody>
+            <PreviewCardTitleRow>
+              <PreviewCardIcon>
+                <CircleDot />
+              </PreviewCardIcon>
+              <PreviewCardTitle>Redesign the pricing page</PreviewCardTitle>
+            </PreviewCardTitleRow>
+            <PreviewCardDescription>
+              Rework the tiered layout to highlight the annual plan discount.
+            </PreviewCardDescription>
+            <PreviewCardPropertyGroup>
+              <Badge tone="warning" magnitude="sm" label="In Progress" />
+              <Badge tone="danger" magnitude="sm" label="High priority" />
+              <Avatar magnitude="xs" alt="Priya Sharma" fallback="P" />
+            </PreviewCardPropertyGroup>
+            <PreviewCardMeta>WEB-142 · Updated 2 days ago</PreviewCardMeta>
+          </PreviewCardBody>
+          <PreviewCardArrow />
+        </PreviewCardContent>
+      </PreviewCard>{" "}
+      for the current status before starting the follow-up task.
+    </p>
+  ),
+};
+
+export const WithRichAnatomyInteraction: Story = {
+  ...WithRichAnatomy,
+  tags: ["!dev", "!autodocs", "!manifest"],
+  play: async ({ canvas }) => {
+    await userEvent.hover(canvas.getByRole("link", { name: "WEB-142" }));
+    const body = within(document.body);
+    await waitFor(() => expect(body.getByText("Redesign the pricing page")).toBeInTheDocument());
+    // Properties and metadata render alongside the title/description.
+    await expect(body.getByText("In Progress")).toBeInTheDocument();
+    await expect(body.getByText("High priority")).toBeInTheDocument();
+    await expect(body.getByRole("img", { name: "Priya Sharma" })).toBeInTheDocument();
+    await expect(body.getByText("WEB-142 · Updated 2 days ago")).toBeInTheDocument();
+  },
+};
+
 // Per-trigger payload body: the card resolves its body from the string payload the
 // active trigger passed, so one card serves several launch points.
 const topics: Record<string, { title: string; description: string }> = {
diff --git a/packages/propel/src/elements/preview-card/index.tsx b/packages/propel/src/elements/preview-card/index.tsx
index 138f35e4..b5af72e7 100644
--- a/packages/propel/src/elements/preview-card/index.tsx
+++ b/packages/propel/src/elements/preview-card/index.tsx
@@ -1,3 +1,7 @@
 export * from "./preview-card-body";
+export * from "./preview-card-icon";
 export * from "./preview-card-image";
+export * from "./preview-card-meta";
 export * from "./preview-card-popup";
+export * from "./preview-card-property-group";
+export * from "./preview-card-title-row";
diff --git a/packages/propel/src/elements/preview-card/preview-card-icon.tsx b/packages/propel/src/elements/preview-card/preview-card-icon.tsx
new file mode 100644
index 00000000..e2ac8f2f
--- /dev/null
+++ b/packages/propel/src/elements/preview-card/preview-card-icon.tsx
@@ -0,0 +1,19 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+
+import { previewCardIconVariants } from "./variants";
+
+export type PreviewCardIconProps = Omit<useRender.ComponentProps<"span">, "className" | "style">;
+
+/**
+ * The decorative leading glyph shown beside the title (a favicon stand-in, an entity-type icon, …).
+ * Sizes its single child to `--node-size`, so the caller passes a bare icon. Decorative — the title
+ * carries the accessible name — so it is `aria-hidden`.
+ */
+export function PreviewCardIcon({ render, ...props }: PreviewCardIconProps) {
+  const defaultProps: useRender.ElementProps<"span"> = {
+    "aria-hidden": true,
+    className: previewCardIconVariants(),
+  };
+  return useRender({ defaultTagName: "span", render, props: mergeProps(defaultProps, props) });
+}
diff --git a/packages/propel/src/elements/preview-card/preview-card-meta.tsx b/packages/propel/src/elements/preview-card/preview-card-meta.tsx
new file mode 100644
index 00000000..9adcecb2
--- /dev/null
+++ b/packages/propel/src/elements/preview-card/preview-card-meta.tsx
@@ -0,0 +1,17 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+
+import { previewCardMetaVariants } from "./variants";
+
+export type PreviewCardMetaProps = Omit<useRender.ComponentProps<"div">, "className" | "style">;
+
+/**
+ * The muted footer caption closing out the card's text content (a source domain, a relative
+ * timestamp, …).
+ */
+export function PreviewCardMeta({ render, ...props }: PreviewCardMetaProps) {
+  const defaultProps: useRender.ElementProps<"div"> = {
+    className: previewCardMetaVariants(),
+  };
+  return useRender({ defaultTagName: "div", render, props: mergeProps(defaultProps, props) });
+}
diff --git a/packages/propel/src/elements/preview-card/preview-card-property-group.tsx b/packages/propel/src/elements/preview-card/preview-card-property-group.tsx
new file mode 100644
index 00000000..73c77ff3
--- /dev/null
+++ b/packages/propel/src/elements/preview-card/preview-card-property-group.tsx
@@ -0,0 +1,21 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+
+import { previewCardPropertyGroupVariants } from "./variants";
+
+export type PreviewCardPropertyGroupProps = Omit<
+  useRender.ComponentProps<"div">,
+  "className" | "style"
+>;
+
+/**
+ * The row of property chips (status, priority, assignee, labels, …) shown beneath the description.
+ * A bare flex-wrap row — the chips are the consumer's own components (`Pill`, `Avatar`, `Badge`,
+ * …); this part only supplies the row layout. Never `aria-hidden`: its content is meaningful.
+ */
+export function PreviewCardPropertyGroup({ render, ...props }: PreviewCardPropertyGroupProps) {
+  const defaultProps: useRender.ElementProps<"div"> = {
+    className: previewCardPropertyGroupVariants(),
+  };
+  return useRender({ defaultTagName: "div", render, props: mergeProps(defaultProps, props) });
+}
diff --git a/packages/propel/src/elements/preview-card/preview-card-title-row.tsx b/packages/propel/src/elements/preview-card/preview-card-title-row.tsx
new file mode 100644
index 00000000..90180507
--- /dev/null
+++ b/packages/propel/src/elements/preview-card/preview-card-title-row.tsx
@@ -0,0 +1,17 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+
+import { previewCardTitleRowVariants } from "./variants";
+
+export type PreviewCardTitleRowProps = Omit<useRender.ComponentProps<"div">, "className" | "style">;
+
+/**
+ * Lays an optional `PreviewCardIcon` beside `PreviewCardTitle`. Compose it only when the card has a
+ * leading icon; a card without one renders `PreviewCardTitle` directly inside `PreviewCardBody`.
+ */
+export function PreviewCardTitleRow({ render, ...props }: PreviewCardTitleRowProps) {
+  const defaultProps: useRender.ElementProps<"div"> = {
+    className: previewCardTitleRowVariants(),
+  };
+  return useRender({ defaultTagName: "div", render, props: mergeProps(defaultProps, props) });
+}
diff --git a/packages/propel/src/elements/preview-card/preview-card.stories.tsx b/packages/propel/src/elements/preview-card/preview-card.stories.tsx
index 4e2a1297..f76512d7 100644
--- a/packages/propel/src/elements/preview-card/preview-card.stories.tsx
+++ b/packages/propel/src/elements/preview-card/preview-card.stories.tsx
@@ -1,25 +1,41 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { CircleDot } from "lucide-react";
 import { expect } from "storybook/test";
 
 import { OverlayDescription } from "../../internal/overlay-description";
 import { OverlayTitle } from "../../internal/overlay-title";
-import { PreviewCardBody, PreviewCardImage, PreviewCardPopup } from "./index";
+import { Avatar, AvatarFallback } from "../avatar/index";
+import { Badge } from "../badge/index";
+import {
+  PreviewCardBody,
+  PreviewCardIcon,
+  PreviewCardImage,
+  PreviewCardMeta,
+  PreviewCardPopup,
+  PreviewCardPropertyGroup,
+  PreviewCardTitleRow,
+} from "./index";
 
 // elements-tier story (rule 2b): a pure UI-configuration showcase. The styled parts render
 // DIRECTLY — no Base UI grafts — with the popup laid out inline (it is just a styled div; Base UI
 // only positions it) and its transition poses pinned statically via the `data-starting-style`/
 // `data-ending-style` attributes Base UI's preview card would set. The Root, Trigger, and Portal
-// are behavior-only roles (they live in `components`); the positioner, backdrop, and arrow are
-// shared `internal/` chrome grafted there too. The title and description compose the shared
-// `internal/overlay-*` recipes at the preview card's `md` size. Hover-open, dismissal, and aria
-// behavior are demonstrated AND tested in the components-tier story (Components/PreviewCard).
+// are behavior-only roles (they live in `components`); the positioner and arrow are shared
+// `internal/` chrome grafted there too — no backdrop, since a preview card is non-modal (rule 4a's
+// shared `Backdrop` is for genuinely modal overlays only). The title and description compose the
+// shared `internal/overlay-*` recipes at the preview card's `md` size. Hover-open, dismissal, and
+// aria behavior are demonstrated AND tested in the components-tier story (Components/PreviewCard).
 
 const meta = {
   title: "Elements/PreviewCard",
   component: PreviewCardPopup,
   subcomponents: {
     PreviewCardBody,
+    PreviewCardIcon,
     PreviewCardImage,
+    PreviewCardMeta,
+    PreviewCardPropertyGroup,
+    PreviewCardTitleRow,
   },
 } satisfies Meta<typeof PreviewCardPopup>;
 
@@ -70,6 +86,44 @@ export const WithImage: Story = {
   ),
 };
 
+/**
+ * A work-item-style link preview: `PreviewCardIcon` sits beside the title in a
+ * `PreviewCardTitleRow` (compose the row only when there's a leading icon),
+ * `PreviewCardPropertyGroup` holds a wrapping row of the consumer's own chips (here `Badge` for
+ * status/priority and `Avatar` for the assignee — the part supplies only the row layout), and
+ * `PreviewCardMeta` closes the card with a muted caption. Every new region is optional and
+ * independent — a card can add just one.
+ */
+export const RichAnatomy: Story = {
+  render: () => (
+    <PreviewCardPopup>
+      <PreviewCardBody>
+        <PreviewCardTitleRow>
+          <PreviewCardIcon>
+            <CircleDot />
+          </PreviewCardIcon>
+          <OverlayTitle magnitude="md">Redesign the pricing page</OverlayTitle>
+        </PreviewCardTitleRow>
+        <OverlayDescription magnitude="md">
+          Rework the tiered layout to highlight the annual plan discount.
+        </OverlayDescription>
+        <PreviewCardPropertyGroup>
+          <Badge tone="warning" magnitude="sm">
+            In Progress
+          </Badge>
+          <Badge tone="danger" magnitude="sm">
+            High priority
+          </Badge>
+          <Avatar magnitude="xs" role="img" aria-label="Priya Sharma">
+            <AvatarFallback tone="indigo">P</AvatarFallback>
+          </Avatar>
+        </PreviewCardPropertyGroup>
+        <PreviewCardMeta>WEB-142 · Updated 2 days ago</PreviewCardMeta>
+      </PreviewCardBody>
+    </PreviewCardPopup>
+  ),
+};
+
 /**
  * The popup's transition poses, pinned statically:
  *
diff --git a/packages/propel/src/elements/preview-card/variants.ts b/packages/propel/src/elements/preview-card/variants.ts
index 73075ac9..89247d0c 100644
--- a/packages/propel/src/elements/preview-card/variants.ts
+++ b/packages/propel/src/elements/preview-card/variants.ts
@@ -1,17 +1,21 @@
 import { cva, cx } from "class-variance-authority";
 
+import { nodeSlotClass } from "../../internal/node-slot";
 import { popupSurfaceClass } from "../../internal/popup-surface";
 
 // Preview Card wraps Base UI's parts; Base UI drives all open state through `data-*`
 // attributes, so there are no styling axes (variant/tone/magnitude) to expose. The
 // cva pairings below hold the static chrome for the styled parts that are UNIQUE to
-// this family — Popup, Body, and Image. The shared overlay chrome (positioner,
-// backdrop, arrow, title, description) is adopted from `internal/` (rule 4a) and no
-// longer lives here.
+// this family — Popup, Body, Image, Icon, TitleRow, PropertyGroup, and Meta. The
+// shared overlay chrome (positioner, backdrop, arrow, title, description) is adopted
+// from `internal/` (rule 4a) and no longer lives here.
 //
-// Body and Image are propel extensions with no Base UI counterpart; their styles
-// encode the "always the same" items from the design spec: the text content area's
-// layout + padding (Body) and the image overflow/cover-fit (Image).
+// Body, Image, Icon, TitleRow, PropertyGroup, and Meta are propel extensions with no
+// Base UI counterpart; their styles encode the "always the same" items from the
+// design spec — the text content area's layout + padding (Body), the image
+// overflow/cover-fit (Image), the leading glyph beside the title (Icon), the
+// icon+title row (TitleRow), the row of property chips (PropertyGroup), and the
+// muted footer caption (Meta).
 
 // The card surface. Padding lives on `PreviewCardBody` (per the spec, padding is
 // "within the text content area") rather than here, so the popup is the bare
@@ -22,8 +26,9 @@ import { popupSurfaceClass } from "../../internal/popup-surface";
 export const previewCardPopupVariants = cva(cx(popupSurfaceClass, "max-w-80"));
 
 // Body: the text content area. Per the spec, the content layout (a column with the
-// title above the description) and the padding around it are "always the same", so
-// they live here rather than in the consumer's composition.
+// title row above the description, property row, and meta caption) and the padding
+// around it are "always the same", so they live here rather than in the consumer's
+// composition.
 export const previewCardBodyVariants = cva("flex flex-col gap-1 p-3");
 
 // Image: overflow-hidden + object-cover bake in the "always the same" thumbnail
@@ -31,3 +36,32 @@ export const previewCardBodyVariants = cva("flex flex-col gap-1 p-3");
 // can sit inside the popup without the popup needing overflow-hidden (which would
 // clip the arrow). Width/height are set by the consumer's layout.
 export const previewCardImageVariants = cva("overflow-hidden rounded-md object-cover");
+
+// Icon: the decorative glyph shown at the inline-start of the title (a favicon
+// stand-in, an entity-type glyph, …). Sizes its single child to `--node-size` via
+// the shared node-slot class; muted like every other decorative leading icon in the
+// system (Menu's leading icon, etc.) since it never carries the accessible name —
+// the title does.
+export const previewCardIconVariants = cva(
+  cx(nodeSlotClass, "text-icon-secondary [--node-size:1rem]"),
+);
+
+// TitleRow: lays the optional `PreviewCardIcon` beside `PreviewCardTitle` on one
+// baseline-free row (mirrors `MenuItemTitleRow`'s icon+label pairing, `items-center`
+// rather than `items-baseline` since a glyph — not a second text run — sits next to
+// the title).
+export const previewCardTitleRowVariants = cva("flex items-center gap-1.5");
+
+// PropertyGroup: the row of property chips (status, priority, assignee, labels, …)
+// a link-unfurl card shows beneath its description. A bare flex-wrap row — the
+// chips themselves are the consumer's own components (`Pill`, `Avatar`, `Badge`,
+// …), so this part supplies only the row layout, wrapping instead of overflowing
+// when there are many.
+export const previewCardPropertyGroupVariants = cva("flex flex-wrap items-center gap-1.5");
+
+// Meta: the muted footer caption (a source domain, a relative timestamp, …) closing
+// out the card's text content. Same muted caption treatment used elsewhere in the
+// system (`text-12 text-tertiary`), spelled out here rather than imported since
+// `internal/menu-row-parts`'s `rowMetaClass` bakes in `shrink-0` for an inline
+// trailing chip — this is a block-level line, not byte-identical (rule 4a).
+export const previewCardMetaVariants = cva("text-12 text-tertiary");
diff --git a/packages/propel/src/internal/backdrop.tsx b/packages/propel/src/internal/backdrop.tsx
index a5ecdc12..57226430 100644
--- a/packages/propel/src/internal/backdrop.tsx
+++ b/packages/propel/src/internal/backdrop.tsx
@@ -4,10 +4,15 @@ import { cva } from "class-variance-authority";
 
 /**
  * The shared overlay backdrop surface, grafted onto any Base UI `*.Backdrop` behavior in
- * `components` (`<BaseDialog.Backdrop render={<Backdrop />}>`). Dims the page behind a modal
- * overlay and fades with the overlay's open/close transition. Byte-identical across every overlay
- * family — alert-dialog, dialog, drawer, navigation-menu, popover, preview-card — so it lives here
- * rather than being copied per family (rule 4a). No styling axes.
+ * `components` (`<BaseDialog.Backdrop render={<Backdrop />}>`). Dims the page behind a MODAL
+ * overlay and fades with the overlay's open/close transition. Byte-identical across every modal
+ * family — alert-dialog, dialog, drawer — so it lives here rather than being copied per family
+ * (rule 4a). No styling axes.
+ *
+ * Reach for this only when the overlay is genuinely modal (traps focus, blocks the rest of the
+ * page). A non-modal, hover/focus-triggered surface — preview-card, popover, tooltip, menu,
+ * context-menu — has no business dimming the page just because it's open; it doesn't graft a
+ * `*.Backdrop` behavior at all, styled or not.
  */
 export const backdropVariants = cva(
   "fixed inset-0 bg-backdrop transition-opacity duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0",

From 31d5212c7927037226f50ce627e9aa542e5bdbfe Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 15:41:13 +0530
Subject: [PATCH 21/31] feat(combobox): enhance chip rendering with overflow
 management and contextual icons

- Introduced `maxVisible` prop to limit the number of visible chips, collapsing excess into a "+N more" count.
- Added `startIcon` and `endIcon` props for contextual icons on chips, improving visual representation.
- Created `ComboboxChipOverflow` component to display the overflow count when chips exceed the visible limit.
- Updated `ComboboxChips` to handle new layout options and improved rendering logic for better user experience.
- Enhanced storybook examples to demonstrate new features and interactions, including overflow behavior.
---
 .../components/combobox/combobox-chips.tsx    | 87 +++++++++++++------
 .../components/combobox/combobox.stories.tsx  | 81 ++++++++++++++++-
 .../combobox/combobox-chip-overflow.tsx       | 21 +++++
 .../src/elements/combobox/combobox-chips.tsx  |  9 +-
 .../elements/combobox/combobox.stories.tsx    | 42 ++++++++-
 .../propel/src/elements/combobox/index.tsx    |  1 +
 .../propel/src/elements/combobox/variants.ts  | 31 +++++--
 .../propel/src/internal/listbox-popup.tsx     |  6 +-
 8 files changed, 237 insertions(+), 41 deletions(-)
 create mode 100644 packages/propel/src/elements/combobox/combobox-chip-overflow.tsx

diff --git a/packages/propel/src/components/combobox/combobox-chips.tsx b/packages/propel/src/components/combobox/combobox-chips.tsx
index 982fc892..7c2f5bb8 100644
--- a/packages/propel/src/components/combobox/combobox-chips.tsx
+++ b/packages/propel/src/components/combobox/combobox-chips.tsx
@@ -1,13 +1,16 @@
 import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
 import { X } from "lucide-react";
+import type * as React from "react";
 
 import {
   type ComboboxMagnitude,
   ComboboxChip as ComboboxChipElement,
+  ComboboxChipOverflow as ComboboxChipOverflowElement,
   ComboboxChipRemove as ComboboxChipRemoveElement,
   ComboboxChips as ComboboxChipsElement,
   ComboboxInput as ComboboxInputElement,
 } from "../../elements/combobox";
+import { Icon } from "../../internal/icon";
 
 export type ComboboxChipsProps<Value = string> = {
   /** Visual size of the chips frame: height, text, and glyph sizing. Required. */
@@ -24,48 +27,80 @@ export type ComboboxChipsProps<Value = string> = {
    * same function you give the `Combobox` root; defaults to `String(item)`.
    */
   itemToStringLabel?: (item: Value) => string;
+  /**
+   * Cap on how many chips render inline. When more are selected, the frame collapses to a single
+   * row showing the first `maxVisible` chips followed by a "+N more" count (the rest stay managed
+   * from the popup). Omit for the default behavior — chips wrap onto new rows as the selection
+   * grows.
+   */
+  maxVisible?: number;
+  /**
+   * A contextual node rendered at the inline-start of each chip (e.g. an assignee `Avatar` or an
+   * entity-type glyph), sized to the chip's `--node-size`. Decorative — the chip's label carries
+   * its accessible name.
+   */
+  startIcon?: (item: Value) => React.ReactNode;
+  /**
+   * A contextual node rendered after each chip's label, before the remove control (e.g. a status
+   * glyph), sized to the chip's `--node-size`. Decorative — the chip's label carries its name.
+   */
+  endIcon?: (item: Value) => React.ReactNode;
 };
 
 /**
  * The ready-made multiselect input frame — it replaces `ComboboxInputGroup` in the `multiple`
  * anatomy. Grafts Base UI's `Chips` behavior onto the styled `elements/combobox` frame and maps
- * each selected value to a removable chip (label + X remove button) ahead of the inline input,
- * wrapping onto new rows as the selection grows. Arrow keys move focus across chips; Backspace
- * removes.
+ * each selected value to a removable chip (optional leading/trailing node + label + X remove) ahead
+ * of the inline input. Without `maxVisible` the chips wrap onto new rows; with it the frame
+ * collapses to one row of the first `maxVisible` chips plus a "+N more" count. Arrow keys move
+ * focus across chips; Backspace removes.
  */
 export function ComboboxChips<Value = string>({
   magnitude,
   placeholder,
   removeLabel,
   itemToStringLabel,
+  maxVisible,
+  startIcon,
+  endIcon,
 }: ComboboxChipsProps<Value>) {
   const label = (item: Value) => (itemToStringLabel ? itemToStringLabel(item) : String(item));
+  const layout = maxVisible != null ? "collapse" : "wrap";
   return (
-    <BaseCombobox.Chips render={<ComboboxChipsElement magnitude={magnitude} />}>
+    <BaseCombobox.Chips render={<ComboboxChipsElement magnitude={magnitude} layout={layout} />}>
       <BaseCombobox.Value>
-        {(values: Value[]) => (
-          <>
-            {values.map((value) => {
-              const chipLabel = label(value);
-              return (
-                <BaseCombobox.Chip
-                  key={chipLabel}
-                  render={<ComboboxChipElement />}
-                  aria-label={chipLabel}
-                >
-                  {chipLabel}
-                  <BaseCombobox.ChipRemove
-                    render={<ComboboxChipRemoveElement />}
-                    aria-label={removeLabel(value)}
+        {(values: Value[]) => {
+          const visible = maxVisible != null ? values.slice(0, maxVisible) : values;
+          const hiddenCount = values.length - visible.length;
+          return (
+            <>
+              {visible.map((value) => {
+                const chipLabel = label(value);
+                return (
+                  <BaseCombobox.Chip
+                    key={chipLabel}
+                    render={<ComboboxChipElement />}
+                    aria-label={chipLabel}
                   >
-                    <X aria-hidden />
-                  </BaseCombobox.ChipRemove>
-                </BaseCombobox.Chip>
-              );
-            })}
-            <BaseCombobox.Input render={<ComboboxInputElement />} placeholder={placeholder} />
-          </>
-        )}
+                    {startIcon ? <Icon>{startIcon(value)}</Icon> : null}
+                    {chipLabel}
+                    {endIcon ? <Icon>{endIcon(value)}</Icon> : null}
+                    <BaseCombobox.ChipRemove
+                      render={<ComboboxChipRemoveElement />}
+                      aria-label={removeLabel(value)}
+                    >
+                      <X aria-hidden />
+                    </BaseCombobox.ChipRemove>
+                  </BaseCombobox.Chip>
+                );
+              })}
+              {hiddenCount > 0 ? (
+                <ComboboxChipOverflowElement>+{hiddenCount} more</ComboboxChipOverflowElement>
+              ) : null}
+              <BaseCombobox.Input render={<ComboboxInputElement />} placeholder={placeholder} />
+            </>
+          );
+        }}
       </BaseCombobox.Value>
     </BaseCombobox.Chips>
   );
diff --git a/packages/propel/src/components/combobox/combobox.stories.tsx b/packages/propel/src/components/combobox/combobox.stories.tsx
index 349be0e2..4cb91ce5 100644
--- a/packages/propel/src/components/combobox/combobox.stories.tsx
+++ b/packages/propel/src/components/combobox/combobox.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { ChevronsUpDown, X } from "lucide-react";
+import { ChevronsUpDown, MapPin, X } from "lucide-react";
 import * as React from "react";
 import { expect, waitFor, within } from "storybook/test";
 
@@ -227,6 +227,69 @@ export const MultipleInteraction: Story = {
   },
 };
 
+const MANY_REGIONS = [
+  "us-central-1",
+  "us-east-1",
+  "eu-central-1",
+  "eu-west-1",
+  "ap-west-1",
+  "ap-southeast-2",
+  "sa-east-1",
+];
+
+/**
+ * `maxVisible` collapses a large selection to a single row: the first N chips plus a "+N more"
+ * count, instead of wrapping onto new rows. `startIcon`/`endIcon` add a contextual node to each
+ * chip (here a leading region glyph — an assignee `Avatar` works the same way). The hidden values
+ * stay managed from the popup: reopen it and deselect to remove one.
+ */
+export const MultipleOverflow: Story = {
+  render: () => (
+    <Field name="regions">
+      <Combobox multiple items={MANY_REGIONS} defaultValue={MANY_REGIONS}>
+        <FieldLabel magnitude="md" inset={false}>
+          Regions
+        </FieldLabel>
+        <ComboboxChips
+          magnitude="md"
+          placeholder=""
+          maxVisible={2}
+          removeLabel={(region) => `Remove ${region}`}
+          startIcon={() => <MapPin />}
+        />
+        <ComboboxContent>
+          <ComboboxEmpty>No matches</ComboboxEmpty>
+          <ComboboxList>
+            {(region: string) => (
+              <ComboboxItem key={region} value={region} magnitude="md">
+                {region}
+              </ComboboxItem>
+            )}
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  ),
+};
+
+/**
+ * Interaction test: with seven values selected and `maxVisible={2}`, only two chips render and the
+ * rest collapse into "+5 more". Tagged out of the sidebar/docs/manifest while still running under
+ * the default `test` tag.
+ */
+export const MultipleOverflowInteraction: Story = {
+  ...MultipleOverflow,
+  tags: ["!dev", "!autodocs", "!manifest"],
+  play: async ({ canvas }) => {
+    await expect(canvas.getByText("us-central-1")).toBeInTheDocument();
+    await expect(canvas.getByText("us-east-1")).toBeInTheDocument();
+    await expect(canvas.getByText("+5 more")).toBeInTheDocument();
+    // Only the first two values render as chips; the rest are represented by the overflow count.
+    await expect(canvas.queryByText("eu-central-1")).not.toBeInTheDocument();
+    await expect(canvas.getAllByRole("button", { name: /^Remove/ })).toHaveLength(2);
+  },
+};
+
 const GROUPED_REGIONS = [
   { label: "Americas", items: ["us-central-1", "us-east-1", "sa-east-1"] },
   { label: "Europe", items: ["eu-central-1", "eu-west-1"] },
@@ -412,7 +475,9 @@ const INITIAL_LABELS: ProjectLabel[] = [
 /**
  * Creating a new item when the query matches nothing: a synthetic `Create "…"` row is appended to
  * `items`, and picking it opens a creation `Dialog` (intercepted in the root's `onValueChange`)
- * instead of selecting. Confirming adds the new label to the list and selects it as a chip.
+ * instead of selecting. Confirming adds the new label to the list and selects it as a chip. The
+ * dialog follows the standard `Dialog` anatomy — a titled header with a corner close, a described
+ * body with the name field, and cancel/create actions.
  */
 export const Creatable: Story = {
   render: function Render() {
@@ -506,13 +571,23 @@ export const Creatable: Story = {
               <DialogHeading>
                 <DialogTitle>Create new label</DialogTitle>
               </DialogHeading>
+              <IconButton
+                prominence="ghost"
+                tone="neutral"
+                magnitude="lg"
+                aria-label="Close"
+                render={<DialogClose />}
+              >
+                <X />
+              </IconButton>
             </DialogHeader>
             <DialogBody>
-              <DialogDescription>Add a new label to select.</DialogDescription>
+              <DialogDescription>Name the label you want to add, then create it.</DialogDescription>
               <InputField
                 magnitude="md"
                 orientation="vertical"
                 label="Label name"
+                placeholder="e.g. triage"
                 value={draft ?? ""}
                 onValueChange={(value) => setDraft(value)}
               />
diff --git a/packages/propel/src/elements/combobox/combobox-chip-overflow.tsx b/packages/propel/src/elements/combobox/combobox-chip-overflow.tsx
new file mode 100644
index 00000000..d7688152
--- /dev/null
+++ b/packages/propel/src/elements/combobox/combobox-chip-overflow.tsx
@@ -0,0 +1,21 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+
+import { comboboxChipOverflowVariants } from "./variants";
+
+export type ComboboxChipOverflowProps = Omit<
+  useRender.ComponentProps<"span">,
+  "className" | "style"
+>;
+
+/**
+ * The "+N more" count shown after the visible chips when the multiselect frame collapses (its
+ * `layout="collapse"` and the selection exceeds the ready-made's `maxVisible`). A muted,
+ * non-interactive caption — the hidden values stay managed from the popup. Base-UI-agnostic.
+ */
+export function ComboboxChipOverflow({ render, ...props }: ComboboxChipOverflowProps) {
+  const defaultProps: useRender.ElementProps<"span"> = {
+    className: comboboxChipOverflowVariants(),
+  };
+  return useRender({ defaultTagName: "span", render, props: mergeProps(defaultProps, props) });
+}
diff --git a/packages/propel/src/elements/combobox/combobox-chips.tsx b/packages/propel/src/elements/combobox/combobox-chips.tsx
index f861e119..768d6ee6 100644
--- a/packages/propel/src/elements/combobox/combobox-chips.tsx
+++ b/packages/propel/src/elements/combobox/combobox-chips.tsx
@@ -7,13 +7,14 @@ export type ComboboxChipsProps = Omit<useRender.ComponentProps<"div">, "classNam
   ComboboxChipsVariantProps;
 
 /**
- * The multiselect input frame: a wrapping row of `ComboboxChip`s ahead of the inline
- * `ComboboxInput` (it replaces `ComboboxInputGroup` in the `multiple` anatomy). Base-UI-agnostic —
+ * The multiselect input frame holding the `ComboboxChip`s ahead of the inline `ComboboxInput` (it
+ * replaces `ComboboxInputGroup` in the `multiple` anatomy). `layout="wrap"` grows onto new rows;
+ * `layout="collapse"` keeps a single clipped row for the "+N more" overflow. Base-UI-agnostic —
  * graft in `components` via `<BaseCombobox.Chips render={<ComboboxChips/>} />`.
  */
-export function ComboboxChips({ magnitude, render, ...props }: ComboboxChipsProps) {
+export function ComboboxChips({ magnitude, layout, render, ...props }: ComboboxChipsProps) {
   const defaultProps: useRender.ElementProps<"div"> = {
-    className: comboboxChipsVariants({ magnitude }),
+    className: comboboxChipsVariants({ magnitude, layout }),
   };
   return useRender({ defaultTagName: "div", render, props: mergeProps(defaultProps, props) });
 }
diff --git a/packages/propel/src/elements/combobox/combobox.stories.tsx b/packages/propel/src/elements/combobox/combobox.stories.tsx
index 0fbb1c54..7700da8b 100644
--- a/packages/propel/src/elements/combobox/combobox.stories.tsx
+++ b/packages/propel/src/elements/combobox/combobox.stories.tsx
@@ -8,6 +8,7 @@ import { ListboxPopup } from "../../internal/listbox-popup";
 import { IconButton } from "../icon-button";
 import {
   ComboboxChip,
+  ComboboxChipOverflow,
   ComboboxChipRemove,
   ComboboxChips,
   ComboboxEmpty,
@@ -48,6 +49,7 @@ const meta = {
     ComboboxInput,
     ComboboxChips,
     ComboboxChip,
+    ComboboxChipOverflow,
     ComboboxChipRemove,
     ComboboxItemIndicator,
     ComboboxEmpty,
@@ -155,7 +157,7 @@ export const Magnitudes: Story = {
           <ComboboxInputGroup magnitude={magnitude}>
             <ComboboxInput aria-label={`Region (${magnitude})`} placeholder={magnitude} />
           </ComboboxInputGroup>
-          <ComboboxChips magnitude={magnitude}>
+          <ComboboxChips magnitude={magnitude} layout="wrap">
             <ComboboxChip>
               us-east-1
               <ComboboxChipRemove aria-label={`Remove us-east-1 (${magnitude})`}>
@@ -265,7 +267,7 @@ export const Chips: Story = {
   },
   render: () => (
     <div className="flex w-96 flex-col gap-1.5">
-      <ComboboxChips magnitude="md">
+      <ComboboxChips magnitude="md" layout="wrap">
         <ComboboxChip>
           us-east-1
           <ComboboxChipRemove id="combobox-chip-remove-hover" aria-label="Remove us-east-1">
@@ -290,6 +292,42 @@ export const Chips: Story = {
   ),
 };
 
+/**
+ * The `layout="collapse"` frame: a single clipped row that shows the visible chips (each here with
+ * a leading `Icon` slot standing in for a contextual glyph/avatar) followed by a
+ * `ComboboxChipOverflow` "+N more" count. The components-tier `ComboboxChips` derives this from its
+ * `maxVisible` prop; the hidden values stay managed from the popup.
+ */
+export const Collapsed: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-72 flex-col gap-1.5">
+      <ComboboxChips magnitude="md" layout="collapse">
+        <ComboboxChip>
+          <Icon>
+            <Check />
+          </Icon>
+          Priya Nair
+          <ComboboxChipRemove aria-label="Remove Priya Nair">
+            <X aria-hidden />
+          </ComboboxChipRemove>
+        </ComboboxChip>
+        <ComboboxChip>
+          <Icon>
+            <Check />
+          </Icon>
+          Marcus Chen
+          <ComboboxChipRemove aria-label="Remove Marcus Chen">
+            <X aria-hidden />
+          </ComboboxChipRemove>
+        </ComboboxChip>
+        <ComboboxChipOverflow>+5 more</ComboboxChipOverflow>
+        <ComboboxInput aria-label="Assignees" placeholder="" />
+      </ComboboxChips>
+    </div>
+  ),
+};
+
 /**
  * The no-matches popup: `ComboboxEmpty` is the live region Base UI keeps mounted inside the popup,
  * and its padding applies via `:not(:empty)` only once it holds the message — while there are
diff --git a/packages/propel/src/elements/combobox/index.tsx b/packages/propel/src/elements/combobox/index.tsx
index 9dfcc56b..fbf451b7 100644
--- a/packages/propel/src/elements/combobox/index.tsx
+++ b/packages/propel/src/elements/combobox/index.tsx
@@ -1,4 +1,5 @@
 export * from "./combobox-chip";
+export * from "./combobox-chip-overflow";
 export * from "./combobox-chip-remove";
 export * from "./combobox-chips";
 export * from "./combobox-empty";
diff --git a/packages/propel/src/elements/combobox/variants.ts b/packages/propel/src/elements/combobox/variants.ts
index 8ff827fa..23d13188 100644
--- a/packages/propel/src/elements/combobox/variants.ts
+++ b/packages/propel/src/elements/combobox/variants.ts
@@ -12,6 +12,12 @@ export const comboboxInputGroupVariants = cva(
     // Wraps a separate focusable input → the shared `focus: within` group chrome.
     controlGroupClass,
     "min-w-64 items-center gap-2 rounded-md px-3",
+    // A trailing control (clear/trigger renders a `<button>`; the leading icon is a `<span>`) sits
+    // flush inside the field, not in its own oversized button well: tighten the group's right
+    // padding so the chevron/clear glyph reads as part of the input. The `:has()` selector outweighs
+    // the flat `px-3`, so it only applies when a trailing control is present. Mirrors the same fix on
+    // `autocompleteInputGroupVariants`.
+    "has-[button]:pr-1",
   ),
   {
     variants: {
@@ -28,13 +34,13 @@ export const comboboxInputVariants = cva(cx(controlInputClass, "flex-1"));
 export const comboboxItemIndicatorVariants = cva(cx(itemIndicatorClass, "size-4"));
 export const comboboxEmptyVariants = cva(listboxEmptyClass);
 
-// The multiselect variant of the input frame: chips wrap onto new rows ahead of the inline input.
-// Tighter padding than `ComboboxInputGroup` so the h-6 chips sit inset like text would.
+// The multiselect variant of the input frame. Tighter padding than `ComboboxInputGroup` so the h-6
+// chips sit inset like text would.
 export const comboboxChipsVariants = cva(
   cx(
     // Wraps a separate focusable input → the shared `focus: within` group chrome.
     controlGroupClass,
-    "min-w-64 flex-wrap items-center gap-1 rounded-md px-1.5 py-1",
+    "min-w-64 items-center gap-1 rounded-md px-1.5 py-1",
   ),
   {
     variants: {
@@ -44,18 +50,33 @@ export const comboboxChipsVariants = cva(
         lg: controlMagnitude.lg,
         xl: controlMagnitude.xl,
       },
+      // How the frame handles more chips than fit: `wrap` grows onto new rows (the default
+      // multiselect), `collapse` keeps a single clipped row where the ready-made shows the first
+      // N chips plus a `ComboboxChipOverflow` "+N more" count. `components` resolves this from
+      // whether `maxVisible` was set (rule 13), so the primitive itself has no default.
+      layout: {
+        wrap: "flex-wrap",
+        collapse: "flex-nowrap overflow-hidden",
+      },
     },
   },
 );
 // One selected value, rendered as a removable tag (the neutral badge chrome). Arrow keys move
-// focus onto a chip, so it carries the standard focus ring.
+// focus onto a chip, so it carries the standard focus ring. `--node-size` sizes an optional
+// leading/trailing `Icon`/avatar slot (composed by the ready-made) to 14px, matching the chip text.
 export const comboboxChipVariants = cva(
   cx(
-    "flex h-6 shrink-0 cursor-default items-center gap-1 rounded-sm bg-layer-3 ps-1.5 pe-0.5 text-13 text-secondary",
+    "flex h-6 shrink-0 cursor-default items-center gap-1 rounded-sm bg-layer-3 ps-1.5 pe-0.5 text-13 text-secondary [--node-size:0.875rem]",
     "outline-none focus-visible:ring-2 focus-visible:ring-accent-strong",
     "data-disabled:cursor-not-allowed data-disabled:text-disabled",
   ),
 );
+// The "+N more" count shown after the visible chips when the frame is `layout="collapse"` and the
+// selection exceeds `maxVisible`. A muted, non-interactive caption sized to the chip text; the
+// hidden values are managed from the popup (deselect to remove).
+export const comboboxChipOverflowVariants = cva(
+  "shrink-0 px-0.5 text-13 text-secondary select-none",
+);
 // The chip's remove affordance; pass an X-style svg.
 export const comboboxChipRemoveVariants = cva(
   cx(
diff --git a/packages/propel/src/internal/listbox-popup.tsx b/packages/propel/src/internal/listbox-popup.tsx
index 16f339cd..3efefe94 100644
--- a/packages/propel/src/internal/listbox-popup.tsx
+++ b/packages/propel/src/internal/listbox-popup.tsx
@@ -10,9 +10,13 @@ import { cva } from "class-variance-authority";
  * it lives here rather than being copied per family (rule 4a). `origin-(--transform-origin)` is
  * included in the base so an animated family (select) shares the exact same class; it is harmless
  * when the surface is not animated.
+ *
+ * `bg-surface-1` (the white floating-card fill) matches the regular dropdown/menu surface — those
+ * float on `surface-1` via `internal/surface`, so a listbox on the page-depth `layer-1` grey read
+ * as a different, wrong color next to them.
  */
 export const listboxPopupVariants = cva(
-  "max-h-[min(var(--available-height),18rem)] min-w-(--anchor-width) origin-(--transform-origin) overflow-y-auto rounded-md border-sm border-subtle bg-layer-1 p-1 shadow-overlay-100",
+  "max-h-[min(var(--available-height),18rem)] min-w-(--anchor-width) origin-(--transform-origin) overflow-y-auto rounded-md border-sm border-subtle bg-surface-1 p-1 shadow-overlay-100",
 );
 
 export type ListboxPopupProps = Omit<useRender.ComponentProps<"div">, "className" | "style">;

From 6ccb982066d3463a879766ad4f7c3c085bad62bd Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 18:58:34 +0530
Subject: [PATCH 22/31] refactor(menu-item, select-field): improve layout and
 component structure

- Updated `MenuItem` to render a leading single-select check indicator conditionally, enhancing alignment with design specifications.
- Refined comments in `MenuItem` for clarity on rendering logic and selected state handling.
- Modified `SelectField` to use `FieldLabel` for better consistency in label sizing across field components, improving overall UI coherence.
---
 .../propel/src/components/menu/menu-item.tsx  | 20 ++++++++++++-------
 .../components/select-field/select-field.tsx  | 16 ++++++---------
 2 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/packages/propel/src/components/menu/menu-item.tsx b/packages/propel/src/components/menu/menu-item.tsx
index e1d87167..bdd0eb05 100644
--- a/packages/propel/src/components/menu/menu-item.tsx
+++ b/packages/propel/src/components/menu/menu-item.tsx
@@ -36,8 +36,8 @@ export type MenuItemProps = Omit<
 
 /**
  * The ready-made selectable menu row: grafts Base UI's `Menu.Item` behavior onto the styled
- * `MenuItem` and lays out an optional leading icon, label, secondary line, and inline-end content,
- * plus the single-select check indicator.
+ * `MenuItem` and lays out a leading single-select check, an optional leading icon, the label, a
+ * secondary line, and inline-end content.
  */
 export function MenuItem({
   tone,
@@ -53,6 +53,17 @@ export function MenuItem({
   const layout = description != null ? "with-description" : "default";
   return (
     <BaseMenu.Item {...props} render={<MenuItemElement layout={layout} tone={tone} />}>
+      {/* A single-select list passes a real `selected` boolean on EVERY row; a plain action row
+          passes none. Render the leading check gutter only for the former — and for every row, so
+          each row's icon/label lines up whether or not it is checked (keepMounted-equivalent, like
+          Select/Combobox's `ItemIndicator`). Base UI has no `Menu.ItemIndicator` to set the
+          attribute, so `data-selected` is set here from the boolean; `itemIndicatorClass` hides the
+          glyph via `not-data-selected:invisible` without collapsing the reserved column. */}
+      {selected !== undefined ? (
+        <MenuItemIndicator data-selected={selected ? "" : undefined}>
+          <Check />
+        </MenuItemIndicator>
+      ) : null}
       {icon}
       <MenuItemContent>
         <MenuItemTitleRow>
@@ -64,11 +75,6 @@ export function MenuItem({
         {description != null ? <MenuItemDescription>{description}</MenuItemDescription> : null}
       </MenuItemContent>
       {endContent != null ? <MenuItemEndContent>{endContent}</MenuItemEndContent> : null}
-      {selected ? (
-        <MenuItemIndicator>
-          <Check />
-        </MenuItemIndicator>
-      ) : null}
     </BaseMenu.Item>
   );
 }
diff --git a/packages/propel/src/components/select-field/select-field.tsx b/packages/propel/src/components/select-field/select-field.tsx
index f50555ab..5a1190d0 100644
--- a/packages/propel/src/components/select-field/select-field.tsx
+++ b/packages/propel/src/components/select-field/select-field.tsx
@@ -3,10 +3,7 @@ import { Check } from "lucide-react";
 import type * as React from "react";
 
 import type { FieldMagnitude } from "../../elements/field/variants";
-import {
-  SelectItemIndicator,
-  type SelectTriggerMagnitude,
-} from "../../elements/select/index";
+import { SelectItemIndicator, type SelectTriggerMagnitude } from "../../elements/select/index";
 import { ListboxItem } from "../../internal/listbox-item";
 import { ListboxPopup } from "../../internal/listbox-popup";
 import { Positioner } from "../../internal/positioner";
@@ -60,13 +57,12 @@ export function SelectField({
   return (
     <Field name={name} disabled={disabled} invalid={error != null || undefined}>
       <Select disabled={disabled} items={options} {...selectProps}>
-        {/* Use the shared `FieldLabel` (magnitude-scaled: md=text-13) so the select field's label
-            matches the other field labels — the picker's own fixed-`text-14` `SelectLabel` made it a
-            step too large next to Input/Radio/Checkbox in a form. `Field.Root` still associates it
-            with the trigger. */}
-        <FieldLabel magnitude={magnitude} inset={false}>
+        {/* Graft Base UI's select-label association onto the shared, magnitude-scaled `FieldLabel`
+            (md=text-13) so the label matches the other field wrappers (input/combobox/autocomplete)
+            — the picker's own fixed-`text-14` `SelectLabel` rendered it a step too large. */}
+        <BaseSelect.Label render={<FieldLabel magnitude={magnitude} inset={false} />}>
           {label}
-        </FieldLabel>
+        </BaseSelect.Label>
         <SelectTrigger magnitude={selectMagnitude} />
         {error == null && description != null ? (
           <FieldDescription magnitude={magnitude}>{description}</FieldDescription>

From 55bf0cd9bd7c3c3e821edb37123ac9ddef468290 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 19:29:49 +0530
Subject: [PATCH 23/31] refactor(checkbox-group): rename parent checkbox to
 select-all and enhance documentation

- Updated the `ParentCheckbox` story to `SelectAll`, reflecting its role as a select-all control.
- Improved comments for clarity on the select-all functionality and its interaction with child checkboxes.
- Adjusted interaction tests to align with the new naming and functionality, ensuring accurate behavior representation.
- Refined nested checkbox group documentation to clarify independent category management.
---
 .../checkbox-group/checkbox-group.stories.tsx | 202 ++++++++----------
 1 file changed, 94 insertions(+), 108 deletions(-)

diff --git a/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx b/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx
index 0bd58b03..1ad5375d 100644
--- a/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx
+++ b/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import * as React from "react";
 import { expect } from "storybook/test";
 
 import { Checkbox } from "../checkbox/index";
@@ -18,8 +17,8 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Every child value in the parent-checkbox stories; the group's `allValues` prop
-// is what lets a `parent` checkbox derive its checked/indeterminate state.
+// Every value in the select-all story; the group's `allValues` prop is what lets the `parent`
+// checkbox derive its checked/indeterminate state from the flat list of rows.
 const PROTOCOLS = ["http", "https", "ssh"];
 
 /** Labeled checkbox rows; the first is selected by default. */
@@ -50,16 +49,18 @@ export const DefaultInteraction: Story = {
 };
 
 /**
- * A `parent` checkbox controls the whole group: pass the group `allValues` and mark one row
- * `parent`. With only some values selected it shows the indeterminate dash; toggling it checks or
- * clears every row. Explicit child ids + `aria-controls` keep the parent's controls references
- * valid (propel rows always carry their own label id).
+ * A **select-all** control (Base UI's `parent` checkbox): pass the group `allValues` and mark one
+ * row `parent`. Base UI derives that row's state from the flat list — checked when every row is on,
+ * the indeterminate dash when only some are, unchecked when none — and toggling it checks or clears
+ * every row at once. The control is an affordance over the whole group, not a value of its own, so
+ * label it plainly ("Select all"). Explicit child ids + `aria-controls` keep the parent's controls
+ * reference valid (propel rows always carry their own label id).
  */
-export const ParentCheckbox: Story = {
+export const SelectAll: Story = {
   args: { density: "comfortable", defaultValue: ["https"], allValues: PROTOCOLS },
   render: (args) => (
     <CheckboxGroup {...args} aria-label="Allowed protocols">
-      <Checkbox parent label="All protocols" aria-controls={PROTOCOLS.join(" ")} />
+      <Checkbox parent label="Select all" aria-controls={PROTOCOLS.join(" ")} />
       <Checkbox id="http" value="http" label="HTTP" />
       <Checkbox id="https" value="https" label="HTTPS" />
       <Checkbox id="ssh" value="ssh" label="SSH" />
@@ -68,158 +69,143 @@ export const ParentCheckbox: Story = {
 };
 
 /**
- * Interaction test: the parent reads `mixed` for a partial selection, checks every row when
+ * Interaction test: the select-all row reads `mixed` for a partial selection, checks every row when
  * clicked, clears them on the next click, and returns to `mixed` when a single row is checked.
  * Tagged out of the sidebar/docs/manifest while still running under the default `test` tag.
  */
-export const ParentCheckboxInteraction: Story = {
-  ...ParentCheckbox,
+export const SelectAllInteraction: Story = {
+  ...SelectAll,
   tags: ["!dev", "!autodocs", "!manifest"],
   play: async ({ canvas, userEvent }) => {
-    const parent = canvas.getByRole("checkbox", { name: "All protocols" });
+    const selectAll = canvas.getByRole("checkbox", { name: "Select all" });
     const http = canvas.getByRole("checkbox", { name: "HTTP" });
     const https = canvas.getByRole("checkbox", { name: "HTTPS" });
     const ssh = canvas.getByRole("checkbox", { name: "SSH" });
 
-    // one of three values selected → the parent reports the indeterminate (mixed) state
-    await expect(parent).toHaveAttribute("aria-checked", "mixed");
+    // one of three values selected → the select-all reports the indeterminate (mixed) state
+    await expect(selectAll).toHaveAttribute("aria-checked", "mixed");
 
-    // clicking a mixed parent selects every value
-    await userEvent.click(parent);
-    await expect(parent).toHaveAttribute("aria-checked", "true");
+    // clicking a mixed select-all selects every value
+    await userEvent.click(selectAll);
+    await expect(selectAll).toHaveAttribute("aria-checked", "true");
     await expect(http).toHaveAttribute("aria-checked", "true");
     await expect(https).toHaveAttribute("aria-checked", "true");
     await expect(ssh).toHaveAttribute("aria-checked", "true");
 
-    // clicking a fully-checked parent clears the group
-    await userEvent.click(parent);
-    await expect(parent).toHaveAttribute("aria-checked", "false");
+    // clicking a fully-checked select-all clears the group
+    await userEvent.click(selectAll);
+    await expect(selectAll).toHaveAttribute("aria-checked", "false");
     await expect(http).toHaveAttribute("aria-checked", "false");
     await expect(https).toHaveAttribute("aria-checked", "false");
     await expect(ssh).toHaveAttribute("aria-checked", "false");
 
-    // checking a single row returns the parent to mixed
+    // checking a single row returns the select-all to mixed
     await userEvent.click(http);
-    await expect(parent).toHaveAttribute("aria-checked", "mixed");
+    await expect(selectAll).toHaveAttribute("aria-checked", "mixed");
   },
 };
 
-// Values for the nested-group stories: the outer group tracks the top-level permissions while
-// the nested group tracks the user-management subset behind the "manage-users" value.
-const MAIN_PERMISSIONS = ["view-dashboard", "manage-users", "access-reports"];
-const MANAGEMENT_PERMISSIONS = ["create-user", "edit-user", "delete-user", "assign-roles"];
+// The nested story models a real permission tree as two INDEPENDENT categories. Each category is its
+// own group whose `allValues` are exactly that category's children, so its `parent` rolls up only
+// its own children — never the sibling category.
+const MANAGE_USERS_PERMISSIONS = ["create-user", "edit-user", "delete-user", "assign-roles"];
+const MANAGE_CONTENT_PERMISSIONS = ["create-content", "edit-content", "publish-content"];
 
 /**
- * Groups nest: a nested `CheckboxGroup` (with its own `parent` row) manages a subset of values
- * while the outer group tracks the top level. The two controlled selections stay in sync through
- * `onValueChange` — completing the nested group checks its value into the outer one — and the outer
- * parent's explicit `indeterminate` shows the dash while the nested selection is partial.
+ * A genuine parent/child hierarchy — distinct from the flat `SelectAll` control above. Each
+ * category ("Manage users", "Manage content") is its OWN `CheckboxGroup` whose `allValues` are
+ * exactly that category's children, so its `parent` row rolls up ONLY its own children: it checks
+ * when all of them are on, shows the indeterminate dash when only some are, and toggling it checks
+ * or clears its own children. The categories are independent — a row under "Manage users" never
+ * affects "Manage content". Both groups are uncontrolled (`defaultValue`), so Base UI owns every
+ * parent/child state with no manual syncing. "User permissions" is a plain heading, not a control.
  */
 export const NestedParentCheckbox: Story = {
-  args: { density: "comfortable", allValues: MAIN_PERMISSIONS },
-  render: function Render(args) {
-    const [mainValue, setMainValue] = React.useState<string[]>([]);
-    const [managementValue, setManagementValue] = React.useState<string[]>([]);
-    return (
+  parameters: { controls: { disable: true } },
+  args: { density: "comfortable" },
+  render: (args) => (
+    <div className="flex flex-col gap-4">
+      <p className="text-13 font-semibold text-primary">User permissions</p>
+      <CheckboxGroup
+        density={args.density}
+        aria-label="Manage users"
+        allValues={MANAGE_USERS_PERMISSIONS}
+        defaultValue={[]}
+      >
+        <Checkbox parent label="Manage users" aria-controls={MANAGE_USERS_PERMISSIONS.join(" ")} />
+        <div className="flex flex-col gap-2 ps-6">
+          <Checkbox id="create-user" value="create-user" label="Create user" />
+          <Checkbox id="edit-user" value="edit-user" label="Edit user" />
+          <Checkbox id="delete-user" value="delete-user" label="Delete user" />
+          <Checkbox id="assign-roles" value="assign-roles" label="Assign roles" />
+        </div>
+      </CheckboxGroup>
       <CheckboxGroup
-        {...args}
-        aria-label="User permissions"
-        value={mainValue}
-        onValueChange={(value) => {
-          if (value.includes("manage-users")) {
-            setManagementValue(MANAGEMENT_PERMISSIONS);
-          } else if (managementValue.length === MANAGEMENT_PERMISSIONS.length) {
-            setManagementValue([]);
-          }
-          setMainValue(value);
-        }}
+        density={args.density}
+        aria-label="Manage content"
+        allValues={MANAGE_CONTENT_PERMISSIONS}
+        defaultValue={[]}
       >
         <Checkbox
           parent
-          label="User permissions"
-          aria-controls={MAIN_PERMISSIONS.join(" ")}
-          indeterminate={
-            managementValue.length > 0 && managementValue.length !== MANAGEMENT_PERMISSIONS.length
-          }
+          label="Manage content"
+          aria-controls={MANAGE_CONTENT_PERMISSIONS.join(" ")}
         />
-        <Checkbox id="view-dashboard" value="view-dashboard" label="View dashboard" />
-        <Checkbox id="access-reports" value="access-reports" label="Access reports" />
-        <div className="ps-6">
-          <CheckboxGroup
-            density={args.density}
-            aria-label="Manage users"
-            allValues={MANAGEMENT_PERMISSIONS}
-            value={managementValue}
-            onValueChange={(value) => {
-              if (value.length === MANAGEMENT_PERMISSIONS.length) {
-                setMainValue((prev) =>
-                  prev.includes("manage-users") ? prev : [...prev, "manage-users"],
-                );
-              } else {
-                setMainValue((prev) => prev.filter((v) => v !== "manage-users"));
-              }
-              setManagementValue(value);
-            }}
-          >
-            <Checkbox
-              parent
-              id="manage-users"
-              label="Manage users"
-              aria-controls={MANAGEMENT_PERMISSIONS.join(" ")}
-            />
-            <Checkbox id="create-user" value="create-user" label="Create user" />
-            <Checkbox id="edit-user" value="edit-user" label="Edit user" />
-            <Checkbox id="delete-user" value="delete-user" label="Delete user" />
-            <Checkbox id="assign-roles" value="assign-roles" label="Assign roles" />
-          </CheckboxGroup>
+        <div className="flex flex-col gap-2 ps-6">
+          <Checkbox id="create-content" value="create-content" label="Create content" />
+          <Checkbox id="edit-content" value="edit-content" label="Edit content" />
+          <Checkbox id="publish-content" value="publish-content" label="Publish content" />
         </div>
       </CheckboxGroup>
-    );
-  },
+    </div>
+  ),
 };
 
 /**
- * Interaction test: one nested row turns the nested parent `mixed` and puts the indeterminate dash
- * on the outer parent (its explicit `indeterminate` surfaces as `data-indeterminate`;
- * `aria-checked` stays group-derived). Completing the nested group checks "manage-users" into the
- * outer group, and the outer parent then selects and clears every value across both groups. Tagged
- * out of the sidebar/docs/manifest while still running under the default `test` tag.
+ * Interaction test for the parent/child hierarchy: selecting one child turns ONLY its own parent
+ * `mixed` (the sibling category is untouched), completing every child checks that parent, toggling
+ * a parent checks/clears only its own children, and toggling one category never leaks into the
+ * other. Tagged out of the sidebar/docs/manifest while still running under the default `test` tag.
  */
 export const NestedParentCheckboxInteraction: Story = {
   ...NestedParentCheckbox,
   tags: ["!dev", "!autodocs", "!manifest"],
   play: async ({ canvas, userEvent }) => {
-    const userPermissions = canvas.getByRole("checkbox", { name: "User permissions" });
     const manageUsers = canvas.getByRole("checkbox", { name: "Manage users" });
     const createUser = canvas.getByRole("checkbox", { name: "Create user" });
-    const viewDashboard = canvas.getByRole("checkbox", { name: "View dashboard" });
+    const editUser = canvas.getByRole("checkbox", { name: "Edit user" });
+    const deleteUser = canvas.getByRole("checkbox", { name: "Delete user" });
+    const assignRoles = canvas.getByRole("checkbox", { name: "Assign roles" });
+    const manageContent = canvas.getByRole("checkbox", { name: "Manage content" });
+    const createContent = canvas.getByRole("checkbox", { name: "Create content" });
 
     // nothing selected anywhere → both parents read clear
-    await expect(userPermissions).toHaveAttribute("aria-checked", "false");
     await expect(manageUsers).toHaveAttribute("aria-checked", "false");
+    await expect(manageContent).toHaveAttribute("aria-checked", "false");
 
-    // one nested row → the nested parent turns mixed and the outer parent shows the dash
-    // through its explicit `indeterminate` wiring
+    // selecting one child turns ONLY its own parent mixed; the sibling category is untouched
     await userEvent.click(createUser);
     await expect(manageUsers).toHaveAttribute("aria-checked", "mixed");
-    await expect(userPermissions).toHaveAttribute("data-indeterminate");
+    await expect(manageContent).toHaveAttribute("aria-checked", "false");
+    await expect(createContent).toHaveAttribute("aria-checked", "false");
 
-    // completing the nested group syncs "manage-users" into the outer group → outer parent mixed
-    await userEvent.click(manageUsers);
+    // completing every child of a category checks its parent — the sibling stays clear
+    await userEvent.click(editUser);
+    await userEvent.click(deleteUser);
+    await userEvent.click(assignRoles);
     await expect(manageUsers).toHaveAttribute("aria-checked", "true");
-    await expect(createUser).toHaveAttribute("aria-checked", "true");
-    await expect(userPermissions).toHaveAttribute("aria-checked", "mixed");
+    await expect(manageContent).toHaveAttribute("aria-checked", "false");
 
-    // checking the outer parent selects every value in both groups
-    await userEvent.click(userPermissions);
-    await expect(userPermissions).toHaveAttribute("aria-checked", "true");
-    await expect(viewDashboard).toHaveAttribute("aria-checked", "true");
-    await expect(manageUsers).toHaveAttribute("aria-checked", "true");
+    // toggling a checked parent clears only its own children
+    await userEvent.click(manageUsers);
+    await expect(manageUsers).toHaveAttribute("aria-checked", "false");
+    await expect(createUser).toHaveAttribute("aria-checked", "false");
+    await expect(assignRoles).toHaveAttribute("aria-checked", "false");
 
-    // clearing the outer parent empties both groups
-    await userEvent.click(userPermissions);
-    await expect(userPermissions).toHaveAttribute("aria-checked", "false");
-    await expect(viewDashboard).toHaveAttribute("aria-checked", "false");
+    // toggling the OTHER parent checks only its own children — no leak into the first category
+    await userEvent.click(manageContent);
+    await expect(manageContent).toHaveAttribute("aria-checked", "true");
+    await expect(createContent).toHaveAttribute("aria-checked", "true");
     await expect(manageUsers).toHaveAttribute("aria-checked", "false");
     await expect(createUser).toHaveAttribute("aria-checked", "false");
   },

From 5cdcdaebc99cd4d22dbb1af3a4861ab03ef2512b Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 19:46:29 +0530
Subject: [PATCH 24/31] refactor(popover): update PanelRow to use label prop
 for improved clarity

- Modified the `PanelRow` component to accept a `label` prop instead of `children`, enhancing the clarity of its intended use.
- Updated related components to align with the new `PanelRow` structure, ensuring consistent usage across the popover component.
---
 .../propel/src/components/popover/popover.stories.tsx | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/propel/src/components/popover/popover.stories.tsx b/packages/propel/src/components/popover/popover.stories.tsx
index 73526c6a..cc128038 100644
--- a/packages/propel/src/components/popover/popover.stories.tsx
+++ b/packages/propel/src/components/popover/popover.stories.tsx
@@ -41,20 +41,21 @@ function PanelSeparator() {
 // One option row for the panels, sized to match a MenuItem (34px tall, `rounded-md`) so
 // every leading control — Radio, Checkbox, anything — lands on the SAME row height and the
 // panel reads like the menu. The whole row is the clickable `<label>`; a bare control goes
-// in `control` and the text as children (the wrapping label names the control, so the bare
-// box/circle needs no `aria-label`, mirroring a native labelled input).
-function PanelRow({ control, children }: { control: React.ReactNode; children: React.ReactNode }) {
+// in `control` and the text in `label` (the wrapping label names the control, so the bare
+// box/circle needs no `aria-label`, mirroring a native labelled input). `label` is a plain
+// string because this slot is designed for a text label only.
+function PanelRow({ control, label }: { control: React.ReactNode; label: string }) {
   return (
     <label className="flex h-[34px] cursor-pointer items-center gap-2 rounded-md px-2 text-13 text-secondary hover:bg-layer-transparent-hover">
       {control}
-      <span className="min-w-0 flex-1 truncate">{children}</span>
+      <span className="min-w-0 flex-1 truncate">{label}</span>
     </label>
   );
 }
 
 // A single-select sort row: a propel Radio in the shared `PanelRow`.
 function PanelRadioRow({ value, label }: { value: string; label: string }) {
-  return <PanelRow control={<Radio value={value} />}>{label}</PanelRow>;
+  return <PanelRow control={<Radio value={value} />} label={label} />;
 }
 
 // The checkbox-toggle footer (show sub-work items / show empty groups) that closes several

From 05d50e6e13229df4204df197095cac174ae5cdb2 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 19:53:56 +0530
Subject: [PATCH 25/31] refactor(popover, context-menu, menu): standardize
 height across components

- Updated height from `h-[34px]` to `h-8.5` in `Popover`, `ContextMenu`, and `Menu` components for consistency.
- Ensured that all related styles align with the new height standard, improving visual coherence across the UI.
---
 .../propel/src/components/popover/popover.stories.tsx |  4 ++--
 packages/propel/src/elements/context-menu/variants.ts | 10 +++++-----
 packages/propel/src/elements/menu/variants.ts         | 11 ++++-------
 3 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/packages/propel/src/components/popover/popover.stories.tsx b/packages/propel/src/components/popover/popover.stories.tsx
index cc128038..42c1771b 100644
--- a/packages/propel/src/components/popover/popover.stories.tsx
+++ b/packages/propel/src/components/popover/popover.stories.tsx
@@ -46,7 +46,7 @@ function PanelSeparator() {
 // string because this slot is designed for a text label only.
 function PanelRow({ control, label }: { control: React.ReactNode; label: string }) {
   return (
-    <label className="flex h-[34px] cursor-pointer items-center gap-2 rounded-md px-2 text-13 text-secondary hover:bg-layer-transparent-hover">
+    <label className="flex h-8.5 cursor-pointer items-center gap-2 rounded-md px-2 text-13 text-secondary hover:bg-layer-transparent-hover">
       {control}
       <span className="min-w-0 flex-1 truncate">{label}</span>
     </label>
@@ -254,7 +254,7 @@ export const DisplayAccordion: Story = {
                   type="button"
                   aria-expanded={isOpen}
                   onClick={() => setOpen(isOpen ? null : key)}
-                  className="flex h-[34px] w-full items-center gap-2 rounded-md px-2 text-13 text-secondary outline-none hover:bg-layer-transparent-hover"
+                  className="flex h-8.5 w-full items-center gap-2 rounded-md px-2 text-13 text-secondary outline-none hover:bg-layer-transparent-hover"
                 >
                   <span className="min-w-0 flex-1 truncate text-left">{title}</span>
                   {isOpen ? (
diff --git a/packages/propel/src/elements/context-menu/variants.ts b/packages/propel/src/elements/context-menu/variants.ts
index c6ba11da..cac1651d 100644
--- a/packages/propel/src/elements/context-menu/variants.ts
+++ b/packages/propel/src/elements/context-menu/variants.ts
@@ -11,13 +11,13 @@ export const contextMenuPopupVariants = cva(cx(popupSurfaceClass, "min-w-40 p-1"
 
 /**
  * Item rows: shared styling for Item, LinkItem, CheckboxItem and RadioItem. `--node-size` sizes the
- * row's icon regions (leading icon, selection indicator) to the 16px row glyph. `h-[34px]` (not the
- * Tailwind `h-8`/32px step) and the highlighted state leaving `text-secondary` untouched (bg tint
- * only) both match the dropdown `Menu`'s row exactly — the two surfaces share one row anatomy.
+ * row's icon regions (leading icon, selection indicator) to the 16px row glyph. `h-8.5` (34px) and
+ * the highlighted state leaving `text-secondary` untouched (bg tint only) both match the dropdown
+ * `Menu`'s row exactly — the two surfaces share one row anatomy.
  */
 export const contextMenuItemVariants = cva(
   cx(
-    "flex h-[34px] cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
+    "flex h-8.5 cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
     "data-highlighted:bg-layer-transparent-hover",
     "data-disabled:pointer-events-none data-disabled:text-disabled",
   ),
@@ -38,7 +38,7 @@ export const contextMenuItemVariants = cva(
  */
 export const contextMenuSubmenuTriggerVariants = cva(
   cx(
-    "group/item flex h-[34px] cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
+    "group/item flex h-8.5 cursor-default items-center gap-2 rounded-md px-2 text-13 outline-none select-none [--node-size:1rem]",
     "data-highlighted:bg-layer-transparent-hover",
     "data-popup-open:bg-layer-transparent-hover",
     "data-disabled:pointer-events-none data-disabled:text-disabled",
diff --git a/packages/propel/src/elements/menu/variants.ts b/packages/propel/src/elements/menu/variants.ts
index 76fbca3f..5bdfa77e 100644
--- a/packages/propel/src/elements/menu/variants.ts
+++ b/packages/propel/src/elements/menu/variants.ts
@@ -48,8 +48,8 @@ const menuRowToneVariants = {
 export const menuRowVariants = cva(cx(menuRowBase, "data-highlighted:bg-layer-transparent-hover"), {
   variants: {
     layout: {
-      default: "h-[34px] items-center",
-      "with-description": "min-h-[34px] items-start py-1.5",
+      default: "h-8.5 items-center",
+      "with-description": "min-h-8.5 items-start py-1.5",
     },
     /** Row text palette. */
     tone: menuRowToneVariants,
@@ -62,10 +62,7 @@ export const menuRowVariants = cva(cx(menuRowBase, "data-highlighted:bg-layer-tr
  * checkbox row never carries a description).
  */
 export const menuCheckboxItemVariants = cva(
-  cx(
-    menuRowBase,
-    "h-[34px] cursor-default items-center data-highlighted:bg-layer-transparent-hover",
-  ),
+  cx(menuRowBase, "h-8.5 cursor-default items-center data-highlighted:bg-layer-transparent-hover"),
   {
     variants: {
       /** Row text palette. */
@@ -82,7 +79,7 @@ export const menuCheckboxItemVariants = cva(
 export const menuSubmenuTriggerVariants = cva(
   cx(
     menuRowBase,
-    "h-[34px] cursor-default items-center",
+    "h-8.5 cursor-default items-center",
     "data-highlighted:bg-layer-transparent-hover data-popup-open:bg-layer-transparent-hover",
   ),
   {

From 8cbf8a55d9137faca296e4132c093eedf60cafdc Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 20:26:47 +0530
Subject: [PATCH 26/31] refactor(spinner, animations): update animation naming
 conventions for consistency

- Renamed spinner animation from `--animate-spinner-reveal` to `--animate-spinner-expand` for clarity.
- Updated related CSS keyframes to follow a consistent naming pattern, changing `slideInFromBottom` to `slide-in-from-bottom`, `fadeIn` to `fade-in`, and others accordingly.
- Improved comments in the spinner and animations files to reflect the changes and enhance understanding of the animation behaviors.
---
 packages/propel/src/internal/spinner.tsx  |  6 +--
 packages/propel/src/styles/animations.css | 58 +++++++++++------------
 2 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/packages/propel/src/internal/spinner.tsx b/packages/propel/src/internal/spinner.tsx
index f6042f9a..69e86612 100644
--- a/packages/propel/src/internal/spinner.tsx
+++ b/packages/propel/src/internal/spinner.tsx
@@ -9,14 +9,14 @@ import { nodeSlotClass } from "./node-slot";
  * child (pass a `LoaderCircle`) to the inherited `--node-size`. Replaces the byte-identical
  * Button/IconButton/Pill spinner parts.
  *
- * Two animations run on mount: the `--animate-spinner-reveal` one-shot grows the slot from zero
+ * Two animations run on mount: the `--animate-spinner-expand` one-shot grows the slot from zero
  * width and fades it in (so a control entering its loading state widens smoothly instead of
  * snapping), while the perpetual `spin` rotates the glyph. They live on separate elements because
- * an element has a single `animation` slot: the reveal owns the span, the spin owns the svg child.
+ * an element has a single `animation` slot: the expand owns the span, the spin owns the svg child.
  * `overflow-hidden` clips the glyph while the slot is still expanding.
  */
 export const spinnerVariants = cva(
-  cx(nodeSlotClass, "animate-spinner-reveal overflow-hidden [&>svg]:animate-spin"),
+  cx(nodeSlotClass, "animate-spinner-expand overflow-hidden [&>svg]:animate-spin"),
 );
 
 export type SpinnerProps = Omit<useRender.ComponentProps<"span">, "className" | "style">;
diff --git a/packages/propel/src/styles/animations.css b/packages/propel/src/styles/animations.css
index d0c602cf..c20e102e 100644
--- a/packages/propel/src/styles/animations.css
+++ b/packages/propel/src/styles/animations.css
@@ -13,8 +13,8 @@
   }
 
   /* slide in from bottom */
-  --animate-slide-in-from-bottom: slideInFromBottom 0.25s ease-out forwards;
-  @keyframes slideInFromBottom {
+  --animate-slide-in-from-bottom: slide-in-from-bottom 0.25s ease-out forwards;
+  @keyframes slide-in-from-bottom {
     0% {
       transform: translateY(100%);
       opacity: 0;
@@ -26,8 +26,8 @@
   }
 
   /* slide in from top */
-  --animate-slide-in-from-top: slideInFromTop 0.25s ease-out forwards;
-  @keyframes slideInFromTop {
+  --animate-slide-in-from-top: slide-in-from-top 0.25s ease-out forwards;
+  @keyframes slide-in-from-top {
     0% {
       transform: translateY(-100%);
       opacity: 0;
@@ -39,8 +39,8 @@
   }
 
   /* slide out */
-  --animate-slide-out: slideOut 0.25s ease-out forwards;
-  @keyframes slideOut {
+  --animate-slide-out: slide-out 0.25s ease-out forwards;
+  @keyframes slide-out {
     0% {
       transform: translateY(0);
       opacity: 1;
@@ -52,8 +52,8 @@
   }
 
   /* slide out down */
-  --animate-slide-out-down: slideOutDown 0.25s ease-out forwards;
-  @keyframes slideOutDown {
+  --animate-slide-out-down: slide-out-down 0.25s ease-out forwards;
+  @keyframes slide-out-down {
     0% {
       transform: translateY(0);
       opacity: 1;
@@ -65,8 +65,8 @@
   }
 
   /* fade out */
-  --animate-fade-out: fadeOut 0.25s ease-out forwards;
-  @keyframes fadeOut {
+  --animate-fade-out: fade-out 0.25s ease-out forwards;
+  @keyframes fade-out {
     0% {
       opacity: 1;
     }
@@ -76,8 +76,8 @@
   }
 
   /* fade in */
-  --animate-fade-in: fadeIn 0.25s ease-out forwards;
-  @keyframes fadeIn {
+  --animate-fade-in: fade-in 0.25s ease-out forwards;
+  @keyframes fade-in {
     0% {
       opacity: 0;
     }
@@ -86,10 +86,10 @@
     }
   }
 
-  /* spinner reveal: a loader slot growing from zero to its glyph width while fading in, so the
+  /* spinner expand: a loader slot growing from zero to its glyph width while fading in, so the
      control it sits in (button, pill) widens smoothly into its loading state instead of snapping */
-  --animate-spinner-reveal: spinnerReveal 0.2s ease-out forwards;
-  @keyframes spinnerReveal {
+  --animate-spinner-expand: spinner-expand 0.2s ease-out forwards;
+  @keyframes spinner-expand {
     0% {
       opacity: 0;
       width: 0;
@@ -101,9 +101,9 @@
   }
 
   /* tour carousel animations */
-  --animate-tour-carousel-slide-in-right: tourCarouselSlideInRight 0.4s
+  --animate-tour-carousel-slide-in-right: tour-carousel-slide-in-right 0.4s
     cubic-bezier(0.25, 0.46, 0.45, 0.94) forwards;
-  @keyframes tourCarouselSlideInRight {
+  @keyframes tour-carousel-slide-in-right {
     0% {
       opacity: 0;
       transform: translateX(40px);
@@ -114,9 +114,9 @@
     }
   }
 
-  --animate-tour-carousel-slide-in-left: tourCarouselSlideInLeft 0.4s
+  --animate-tour-carousel-slide-in-left: tour-carousel-slide-in-left 0.4s
     cubic-bezier(0.25, 0.46, 0.45, 0.94) forwards;
-  @keyframes tourCarouselSlideInLeft {
+  @keyframes tour-carousel-slide-in-left {
     0% {
       opacity: 0;
       transform: translateX(-40px);
@@ -127,9 +127,9 @@
     }
   }
 
-  --animate-tour-carousel-slide-out-right: tourCarouselSlideOutRight 0.4s
+  --animate-tour-carousel-slide-out-right: tour-carousel-slide-out-right 0.4s
     cubic-bezier(0.25, 0.46, 0.45, 0.94) forwards;
-  @keyframes tourCarouselSlideOutRight {
+  @keyframes tour-carousel-slide-out-right {
     0% {
       opacity: 1;
       transform: translateX(0);
@@ -140,9 +140,9 @@
     }
   }
 
-  --animate-tour-carousel-slide-out-left: tourCarouselSlideOutLeft 0.4s
+  --animate-tour-carousel-slide-out-left: tour-carousel-slide-out-left 0.4s
     cubic-bezier(0.25, 0.46, 0.45, 0.94) forwards;
-  @keyframes tourCarouselSlideOutLeft {
+  @keyframes tour-carousel-slide-out-left {
     0% {
       opacity: 1;
       transform: translateX(0);
@@ -153,9 +153,9 @@
     }
   }
 
-  --animate-tour-carousel-fade-in: tourCarouselFadeIn 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94)
+  --animate-tour-carousel-fade-in: tour-carousel-fade-in 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94)
     forwards;
-  @keyframes tourCarouselFadeIn {
+  @keyframes tour-carousel-fade-in {
     0% {
       opacity: 0;
     }
@@ -164,8 +164,8 @@
     }
   }
 
-  --animate-tour-popover-enter: tourPopoverEnter 0.2s cubic-bezier(0.21, 1.02, 0.48, 1) forwards;
-  @keyframes tourPopoverEnter {
+  --animate-tour-popover-enter: tour-popover-enter 0.2s cubic-bezier(0.21, 1.02, 0.48, 1) forwards;
+  @keyframes tour-popover-enter {
     0% {
       opacity: 0;
       transform: translateY(8px) scale(0.95);
@@ -176,8 +176,8 @@
     }
   }
 
-  --animate-tour-popover-exit: tourPopoverExit 0.15s ease-in forwards;
-  @keyframes tourPopoverExit {
+  --animate-tour-popover-exit: tour-popover-exit 0.15s ease-in forwards;
+  @keyframes tour-popover-exit {
     0% {
       opacity: 1;
       transform: translateY(0) scale(1);

From 267cf8c4726ca16932cfcc5db4e516d1e85f3fdc Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Tue, 7 Jul 2026 20:33:49 +0530
Subject: [PATCH 27/31] refactor(checkbox-group): simplify checkbox structure
 and enhance documentation

- Removed explicit `id` attributes from child checkboxes, allowing the base UI to derive input IDs automatically.
- Updated the `SelectAll` and `NestedParentCheckbox` stories to reflect the new checkbox structure, improving clarity and consistency.
- Enhanced comments to better explain the relationship between parent and child checkboxes, ensuring accurate understanding of their functionality.
---
 .../checkbox-group/checkbox-group.stories.tsx | 35 +++++++++----------
 1 file changed, 16 insertions(+), 19 deletions(-)

diff --git a/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx b/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx
index 1ad5375d..5d03429e 100644
--- a/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx
+++ b/packages/propel/src/components/checkbox-group/checkbox-group.stories.tsx
@@ -53,17 +53,18 @@ export const DefaultInteraction: Story = {
  * row `parent`. Base UI derives that row's state from the flat list — checked when every row is on,
  * the indeterminate dash when only some are, unchecked when none — and toggling it checks or clears
  * every row at once. The control is an affordance over the whole group, not a value of its own, so
- * label it plainly ("Select all"). Explicit child ids + `aria-controls` keep the parent's controls
- * reference valid (propel rows always carry their own label id).
+ * label it plainly ("Select all"). Rows carry no explicit `id`: Base UI derives each child input id
+ * as `${groupId}-${value}` and auto-wires the parent's `aria-controls` to match (a custom `id` on a
+ * grouped child is ignored — base-ui#2691).
  */
 export const SelectAll: Story = {
   args: { density: "comfortable", defaultValue: ["https"], allValues: PROTOCOLS },
   render: (args) => (
     <CheckboxGroup {...args} aria-label="Allowed protocols">
-      <Checkbox parent label="Select all" aria-controls={PROTOCOLS.join(" ")} />
-      <Checkbox id="http" value="http" label="HTTP" />
-      <Checkbox id="https" value="https" label="HTTPS" />
-      <Checkbox id="ssh" value="ssh" label="SSH" />
+      <Checkbox parent label="Select all" />
+      <Checkbox value="http" label="HTTP" />
+      <Checkbox value="https" label="HTTPS" />
+      <Checkbox value="ssh" label="SSH" />
     </CheckboxGroup>
   ),
 };
@@ -132,12 +133,12 @@ export const NestedParentCheckbox: Story = {
         allValues={MANAGE_USERS_PERMISSIONS}
         defaultValue={[]}
       >
-        <Checkbox parent label="Manage users" aria-controls={MANAGE_USERS_PERMISSIONS.join(" ")} />
+        <Checkbox parent label="Manage users" />
         <div className="flex flex-col gap-2 ps-6">
-          <Checkbox id="create-user" value="create-user" label="Create user" />
-          <Checkbox id="edit-user" value="edit-user" label="Edit user" />
-          <Checkbox id="delete-user" value="delete-user" label="Delete user" />
-          <Checkbox id="assign-roles" value="assign-roles" label="Assign roles" />
+          <Checkbox value="create-user" label="Create user" />
+          <Checkbox value="edit-user" label="Edit user" />
+          <Checkbox value="delete-user" label="Delete user" />
+          <Checkbox value="assign-roles" label="Assign roles" />
         </div>
       </CheckboxGroup>
       <CheckboxGroup
@@ -146,15 +147,11 @@ export const NestedParentCheckbox: Story = {
         allValues={MANAGE_CONTENT_PERMISSIONS}
         defaultValue={[]}
       >
-        <Checkbox
-          parent
-          label="Manage content"
-          aria-controls={MANAGE_CONTENT_PERMISSIONS.join(" ")}
-        />
+        <Checkbox parent label="Manage content" />
         <div className="flex flex-col gap-2 ps-6">
-          <Checkbox id="create-content" value="create-content" label="Create content" />
-          <Checkbox id="edit-content" value="edit-content" label="Edit content" />
-          <Checkbox id="publish-content" value="publish-content" label="Publish content" />
+          <Checkbox value="create-content" label="Create content" />
+          <Checkbox value="edit-content" label="Edit content" />
+          <Checkbox value="publish-content" label="Publish content" />
         </div>
       </CheckboxGroup>
     </div>

From 3e60d0a24d0c16bc069e189a52274307ec5aaa14 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Wed, 8 Jul 2026 15:38:46 +0530
Subject: [PATCH 28/31] feat(combobox): introduce ComboboxChip and
 ComboboxChipRemove components

- Added `ComboboxChip` for rendering individual chips with customizable content and remove functionality.
- Implemented `ComboboxChipRemove` to provide a consistent remove action for chips, defaulting to an 'X' icon.
- Updated `ComboboxChips` to utilize the new `ComboboxChip` for rendering selected values, enhancing flexibility and customization.
- Modified stories to demonstrate the new chip components and their integration within the Combobox structure.
---
 .../combobox/combobox-chip-remove.tsx         | 25 +++++++
 .../src/components/combobox/combobox-chip.tsx | 42 ++++++++++++
 .../components/combobox/combobox-chips.tsx    | 65 ++++--------------
 .../components/combobox/combobox.stories.tsx  | 68 +++++++++++--------
 .../propel/src/components/combobox/index.tsx  |  2 +
 5 files changed, 119 insertions(+), 83 deletions(-)
 create mode 100644 packages/propel/src/components/combobox/combobox-chip-remove.tsx
 create mode 100644 packages/propel/src/components/combobox/combobox-chip.tsx

diff --git a/packages/propel/src/components/combobox/combobox-chip-remove.tsx b/packages/propel/src/components/combobox/combobox-chip-remove.tsx
new file mode 100644
index 00000000..5be9c7f1
--- /dev/null
+++ b/packages/propel/src/components/combobox/combobox-chip-remove.tsx
@@ -0,0 +1,25 @@
+import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
+import { X } from "lucide-react";
+import type * as React from "react";
+
+import { ComboboxChipRemove as ComboboxChipRemoveElement } from "../../elements/combobox";
+
+export type ComboboxChipRemoveProps = Omit<
+  BaseCombobox.ChipRemove.Props,
+  "children" | "className" | "style"
+> & {
+  /** The remove glyph. Defaults to an X (defaults are a `components` concern). */
+  icon?: React.ReactNode;
+};
+
+/**
+ * Ready-made chip-remove control: Base UI's remove behavior grafted onto the styled button. Give it
+ * an `aria-label` naming the value it removes.
+ */
+export function ComboboxChipRemove({ icon, ...props }: ComboboxChipRemoveProps) {
+  return (
+    <BaseCombobox.ChipRemove {...props} render={<ComboboxChipRemoveElement />}>
+      {icon ?? <X aria-hidden />}
+    </BaseCombobox.ChipRemove>
+  );
+}
diff --git a/packages/propel/src/components/combobox/combobox-chip.tsx b/packages/propel/src/components/combobox/combobox-chip.tsx
new file mode 100644
index 00000000..b841efab
--- /dev/null
+++ b/packages/propel/src/components/combobox/combobox-chip.tsx
@@ -0,0 +1,42 @@
+import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
+import type * as React from "react";
+
+import { ComboboxChip as ComboboxChipElement } from "../../elements/combobox";
+import { ComboboxChipRemove } from "./combobox-chip-remove";
+
+export type ComboboxChipProps = Omit<
+  BaseCombobox.Chip.Props,
+  "children" | "className" | "style"
+> & {
+  /** Leading element before the label — an `<Icon icon={...} />`, an assignee `Avatar`, or similar. */
+  startContent?: React.ReactNode;
+  /** Trailing element after the label, before the remove control, e.g. a status `<Icon .../>`. */
+  endContent?: React.ReactNode;
+  /** The chip's label. Also sets the chip's own accessible name. */
+  label: string;
+  /** Accessible name for the remove button (localizable), e.g. `` `Remove ${label}` ``. */
+  removeLabel: string;
+};
+
+/**
+ * Ready-made chip: Base UI's chip behavior (arrow-key focus, Backspace/Delete removal) grafted onto
+ * the styled tag, laying out an optional leading/trailing node around the label plus a
+ * `ComboboxChipRemove`. Base UI derives which selected value a chip represents from its position
+ * among its siblings — pass one per value from `ComboboxChips`' `children`.
+ */
+export function ComboboxChip({
+  startContent,
+  endContent,
+  label,
+  removeLabel,
+  ...props
+}: ComboboxChipProps) {
+  return (
+    <BaseCombobox.Chip {...props} aria-label={label} render={<ComboboxChipElement />}>
+      {startContent}
+      {label}
+      {endContent}
+      <ComboboxChipRemove aria-label={removeLabel} />
+    </BaseCombobox.Chip>
+  );
+}
diff --git a/packages/propel/src/components/combobox/combobox-chips.tsx b/packages/propel/src/components/combobox/combobox-chips.tsx
index 7c2f5bb8..b5543c1e 100644
--- a/packages/propel/src/components/combobox/combobox-chips.tsx
+++ b/packages/propel/src/components/combobox/combobox-chips.tsx
@@ -1,32 +1,18 @@
 import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
-import { X } from "lucide-react";
 import type * as React from "react";
 
 import {
   type ComboboxMagnitude,
-  ComboboxChip as ComboboxChipElement,
   ComboboxChipOverflow as ComboboxChipOverflowElement,
-  ComboboxChipRemove as ComboboxChipRemoveElement,
   ComboboxChips as ComboboxChipsElement,
   ComboboxInput as ComboboxInputElement,
 } from "../../elements/combobox";
-import { Icon } from "../../internal/icon";
 
 export type ComboboxChipsProps<Value = string> = {
   /** Visual size of the chips frame: height, text, and glyph sizing. Required. */
   magnitude: ComboboxMagnitude;
   /** Input placeholder shown while typing to add another value. */
   placeholder?: string;
-  /**
-   * Accessible name for a value's chip-remove button (e.g. `` (item) => `Remove ${item.label}` ``).
-   * Localizable, so it is required — the frame bakes no label text.
-   */
-  removeLabel: (item: Value) => string;
-  /**
-   * A selected item's display text — Base UI's `itemToStringLabel`. For object values, pass the
-   * same function you give the `Combobox` root; defaults to `String(item)`.
-   */
-  itemToStringLabel?: (item: Value) => string;
   /**
    * Cap on how many chips render inline. When more are selected, the frame collapses to a single
    * row showing the first `maxVisible` chips followed by a "+N more" count (the rest stay managed
@@ -35,36 +21,28 @@ export type ComboboxChipsProps<Value = string> = {
    */
   maxVisible?: number;
   /**
-   * A contextual node rendered at the inline-start of each chip (e.g. an assignee `Avatar` or an
-   * entity-type glyph), sized to the chip's `--node-size`. Decorative — the chip's label carries
-   * its accessible name.
-   */
-  startIcon?: (item: Value) => React.ReactNode;
-  /**
-   * A contextual node rendered after each chip's label, before the remove control (e.g. a status
-   * glyph), sized to the chip's `--node-size`. Decorative — the chip's label carries its name.
+   * Renders one selected value as a `ComboboxChip` — the `ComboboxChips` counterpart of
+   * `ComboboxList`'s item template. Set your own `key`, exactly like `ComboboxList`'s function
+   * child, e.g. ``(value) => <ComboboxChip key={value} label={value} removeLabel={`Remove
+   * ${value}`} />``.
    */
-  endIcon?: (item: Value) => React.ReactNode;
+  children: (value: Value) => React.ReactNode;
 };
 
 /**
  * The ready-made multiselect input frame — it replaces `ComboboxInputGroup` in the `multiple`
- * anatomy. Grafts Base UI's `Chips` behavior onto the styled `elements/combobox` frame and maps
- * each selected value to a removable chip (optional leading/trailing node + label + X remove) ahead
- * of the inline input. Without `maxVisible` the chips wrap onto new rows; with it the frame
- * collapses to one row of the first `maxVisible` chips plus a "+N more" count. Arrow keys move
- * focus across chips; Backspace removes.
+ * anatomy. Grafts Base UI's `Chips` behavior onto the styled `elements/combobox` frame, owning only
+ * the frame, the selected-values loop, and `maxVisible` overflow ahead of the inline input — each
+ * chip's template is the consumer's `children`, mirroring `ComboboxList`. Without `maxVisible` the
+ * chips wrap onto new rows; with it the frame collapses to one row of the first `maxVisible` chips
+ * plus a "+N more" count. Arrow keys move focus across chips; Backspace removes.
  */
 export function ComboboxChips<Value = string>({
   magnitude,
   placeholder,
-  removeLabel,
-  itemToStringLabel,
   maxVisible,
-  startIcon,
-  endIcon,
+  children,
 }: ComboboxChipsProps<Value>) {
-  const label = (item: Value) => (itemToStringLabel ? itemToStringLabel(item) : String(item));
   const layout = maxVisible != null ? "collapse" : "wrap";
   return (
     <BaseCombobox.Chips render={<ComboboxChipsElement magnitude={magnitude} layout={layout} />}>
@@ -74,26 +52,7 @@ export function ComboboxChips<Value = string>({
           const hiddenCount = values.length - visible.length;
           return (
             <>
-              {visible.map((value) => {
-                const chipLabel = label(value);
-                return (
-                  <BaseCombobox.Chip
-                    key={chipLabel}
-                    render={<ComboboxChipElement />}
-                    aria-label={chipLabel}
-                  >
-                    {startIcon ? <Icon>{startIcon(value)}</Icon> : null}
-                    {chipLabel}
-                    {endIcon ? <Icon>{endIcon(value)}</Icon> : null}
-                    <BaseCombobox.ChipRemove
-                      render={<ComboboxChipRemoveElement />}
-                      aria-label={removeLabel(value)}
-                    >
-                      <X aria-hidden />
-                    </BaseCombobox.ChipRemove>
-                  </BaseCombobox.Chip>
-                );
-              })}
+              {visible.map(children)}
               {hiddenCount > 0 ? (
                 <ComboboxChipOverflowElement>+{hiddenCount} more</ComboboxChipOverflowElement>
               ) : null}
diff --git a/packages/propel/src/components/combobox/combobox.stories.tsx b/packages/propel/src/components/combobox/combobox.stories.tsx
index 4cb91ce5..989355ea 100644
--- a/packages/propel/src/components/combobox/combobox.stories.tsx
+++ b/packages/propel/src/components/combobox/combobox.stories.tsx
@@ -21,6 +21,8 @@ import { IconButton } from "../icon-button";
 import { InputField } from "../input-field/index";
 import {
   Combobox,
+  ComboboxChip,
+  ComboboxChipRemove,
   ComboboxChips,
   ComboboxCollection,
   ComboboxContent,
@@ -47,6 +49,8 @@ const meta = {
   subcomponents: {
     ComboboxInputGroup,
     ComboboxChips,
+    ComboboxChip,
+    ComboboxChipRemove,
     ComboboxContent,
     ComboboxList,
     ComboboxItem,
@@ -176,9 +180,10 @@ export const InvalidInteraction: Story = {
 
 /**
  * `multiple` swaps the input frame for `ComboboxChips`: each selected value renders as a removable
- * chip ahead of the inline input, wrapping onto new rows as the selection grows. `removeLabel`
- * names each chip's remove button (localizable, required). Arrow keys move focus across chips;
- * Backspace removes.
+ * chip ahead of the inline input, wrapping onto new rows as the selection grows. `children` renders
+ * one value as a `ComboboxChip` — the `ComboboxChips` counterpart of `ComboboxList`'s item
+ * template. `removeLabel` names the chip's remove button (localizable, required). Arrow keys move
+ * focus across chips; Backspace removes.
  */
 export const Multiple: Story = {
   render: () => (
@@ -187,11 +192,11 @@ export const Multiple: Story = {
         <FieldLabel magnitude="md" inset={false}>
           Regions
         </FieldLabel>
-        <ComboboxChips
-          magnitude="md"
-          placeholder="Add a region"
-          removeLabel={(region) => `Remove ${region}`}
-        />
+        <ComboboxChips magnitude="md" placeholder="Add a region">
+          {(region: string) => (
+            <ComboboxChip key={region} label={region} removeLabel={`Remove ${region}`} />
+          )}
+        </ComboboxChips>
         <ComboboxContent>
           <ComboboxEmpty>No matches</ComboboxEmpty>
           <ComboboxList>
@@ -239,9 +244,9 @@ const MANY_REGIONS = [
 
 /**
  * `maxVisible` collapses a large selection to a single row: the first N chips plus a "+N more"
- * count, instead of wrapping onto new rows. `startIcon`/`endIcon` add a contextual node to each
- * chip (here a leading region glyph — an assignee `Avatar` works the same way). The hidden values
- * stay managed from the popup: reopen it and deselect to remove one.
+ * count, instead of wrapping onto new rows. `startContent` adds a contextual leading node to each
+ * chip (here a region glyph — an assignee `Avatar` works the same way). The hidden values stay
+ * managed from the popup: reopen it and deselect to remove one.
  */
 export const MultipleOverflow: Story = {
   render: () => (
@@ -250,20 +255,21 @@ export const MultipleOverflow: Story = {
         <FieldLabel magnitude="md" inset={false}>
           Regions
         </FieldLabel>
-        <ComboboxChips
-          magnitude="md"
-          placeholder=""
-          maxVisible={2}
-          removeLabel={(region) => `Remove ${region}`}
-          startIcon={() => <MapPin />}
-        />
+        <ComboboxChips magnitude="md" placeholder="" maxVisible={2}>
+          {(region: string) => (
+            <ComboboxChip
+              key={region}
+              label={region}
+              removeLabel={`Remove ${region}`}
+              startContent={<Icon icon={MapPin} />}
+            />
+          )}
+        </ComboboxChips>
         <ComboboxContent>
           <ComboboxEmpty>No matches</ComboboxEmpty>
           <ComboboxList>
             {(region: string) => (
-              <ComboboxItem key={region} value={region} magnitude="md">
-                {region}
-              </ComboboxItem>
+              <ComboboxItem key={region} value={region} magnitude="md" label={region} />
             )}
           </ComboboxList>
         </ComboboxContent>
@@ -541,12 +547,15 @@ export const Creatable: Story = {
             <FieldLabel magnitude="md" inset={false}>
               Labels
             </FieldLabel>
-            <ComboboxChips
-              magnitude="md"
-              placeholder="Add a label"
-              removeLabel={(label: ProjectLabel) => `Remove ${label.value}`}
-              itemToStringLabel={(label: ProjectLabel) => label.value}
-            />
+            <ComboboxChips magnitude="md" placeholder="Add a label">
+              {(label: ProjectLabel) => (
+                <ComboboxChip
+                  key={label.id}
+                  label={label.value}
+                  removeLabel={`Remove ${label.value}`}
+                />
+              )}
+            </ComboboxChips>
             <ComboboxContent>
               <ComboboxEmpty>No labels found</ComboboxEmpty>
               <ComboboxList>
@@ -577,9 +586,8 @@ export const Creatable: Story = {
                 magnitude="lg"
                 aria-label="Close"
                 render={<DialogClose />}
-              >
-                <X />
-              </IconButton>
+                icon={<Icon icon={X} />}
+              />
             </DialogHeader>
             <DialogBody>
               <DialogDescription>Name the label you want to add, then create it.</DialogDescription>
diff --git a/packages/propel/src/components/combobox/index.tsx b/packages/propel/src/components/combobox/index.tsx
index 07338e29..0c9a995b 100644
--- a/packages/propel/src/components/combobox/index.tsx
+++ b/packages/propel/src/components/combobox/index.tsx
@@ -1,4 +1,6 @@
 export * from "./combobox";
+export * from "./combobox-chip";
+export * from "./combobox-chip-remove";
 export * from "./combobox-chips";
 export * from "./combobox-collection";
 export * from "./combobox-content";

From 1d7871f1c701f04e5ae45a85cd4b92ffa17dfd02 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Wed, 8 Jul 2026 15:45:59 +0530
Subject: [PATCH 29/31] refactor(spinner, animations): update animation naming
 for clarity

- Renamed spinner animation from `--animate-spinner-expand` to `--animate-spinner-reveal` in both TypeScript and CSS files for improved clarity.
- Updated related CSS keyframes to reflect the new naming convention, ensuring consistency across the animation definitions.
- Enhanced comments to accurately describe the animation behavior and purpose, improving documentation quality.
---
 packages/propel/src/internal/spinner.tsx  | 6 +++---
 packages/propel/src/styles/animations.css | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/propel/src/internal/spinner.tsx b/packages/propel/src/internal/spinner.tsx
index 69e86612..f6042f9a 100644
--- a/packages/propel/src/internal/spinner.tsx
+++ b/packages/propel/src/internal/spinner.tsx
@@ -9,14 +9,14 @@ import { nodeSlotClass } from "./node-slot";
  * child (pass a `LoaderCircle`) to the inherited `--node-size`. Replaces the byte-identical
  * Button/IconButton/Pill spinner parts.
  *
- * Two animations run on mount: the `--animate-spinner-expand` one-shot grows the slot from zero
+ * Two animations run on mount: the `--animate-spinner-reveal` one-shot grows the slot from zero
  * width and fades it in (so a control entering its loading state widens smoothly instead of
  * snapping), while the perpetual `spin` rotates the glyph. They live on separate elements because
- * an element has a single `animation` slot: the expand owns the span, the spin owns the svg child.
+ * an element has a single `animation` slot: the reveal owns the span, the spin owns the svg child.
  * `overflow-hidden` clips the glyph while the slot is still expanding.
  */
 export const spinnerVariants = cva(
-  cx(nodeSlotClass, "animate-spinner-expand overflow-hidden [&>svg]:animate-spin"),
+  cx(nodeSlotClass, "animate-spinner-reveal overflow-hidden [&>svg]:animate-spin"),
 );
 
 export type SpinnerProps = Omit<useRender.ComponentProps<"span">, "className" | "style">;
diff --git a/packages/propel/src/styles/animations.css b/packages/propel/src/styles/animations.css
index c20e102e..e19f3fdd 100644
--- a/packages/propel/src/styles/animations.css
+++ b/packages/propel/src/styles/animations.css
@@ -86,10 +86,10 @@
     }
   }
 
-  /* spinner expand: a loader slot growing from zero to its glyph width while fading in, so the
+  /* spinner reveal: a loader slot growing from zero to its glyph width while fading in, so the
      control it sits in (button, pill) widens smoothly into its loading state instead of snapping */
-  --animate-spinner-expand: spinner-expand 0.2s ease-out forwards;
-  @keyframes spinner-expand {
+  --animate-spinner-reveal: spinner-reveal 0.2s ease-out forwards;
+  @keyframes spinner-reveal {
     0% {
       opacity: 0;
       width: 0;

From 4a7256f12e51032596eb6e480c7147981ed189d2 Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Wed, 8 Jul 2026 16:25:38 +0530
Subject: [PATCH 30/31] refactor(combobox): remove ComboboxChipRemove component
 and update usage

- Deleted the `ComboboxChipRemove` component to streamline the codebase and simplify the chip removal functionality.
- Updated `ComboboxChip` to accept a consumer-supplied `remove` control, enhancing flexibility in how removal actions are implemented.
- Adjusted related components and stories to reflect the new structure, ensuring consistent usage of the updated `remove` prop.
- Improved documentation to clarify the new approach for chip removal within the Combobox components.
---
 .../combobox/combobox-chip-remove.tsx         | 25 -----
 .../src/components/combobox/combobox-chip.tsx | 18 ++--
 .../components/combobox/combobox-chips.tsx    |  3 +-
 .../components/combobox/combobox.stories.tsx  | 39 ++++++--
 .../propel/src/components/combobox/index.tsx  |  1 -
 .../combobox/combobox-chip-remove.tsx         | 22 -----
 .../src/elements/combobox/combobox-chip.tsx   |  8 +-
 .../elements/combobox/combobox.stories.tsx    | 99 +++++++++++++------
 .../propel/src/elements/combobox/index.tsx    |  1 -
 .../propel/src/elements/combobox/variants.ts  | 10 --
 10 files changed, 117 insertions(+), 109 deletions(-)
 delete mode 100644 packages/propel/src/components/combobox/combobox-chip-remove.tsx
 delete mode 100644 packages/propel/src/elements/combobox/combobox-chip-remove.tsx

diff --git a/packages/propel/src/components/combobox/combobox-chip-remove.tsx b/packages/propel/src/components/combobox/combobox-chip-remove.tsx
deleted file mode 100644
index 5be9c7f1..00000000
--- a/packages/propel/src/components/combobox/combobox-chip-remove.tsx
+++ /dev/null
@@ -1,25 +0,0 @@
-import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
-import { X } from "lucide-react";
-import type * as React from "react";
-
-import { ComboboxChipRemove as ComboboxChipRemoveElement } from "../../elements/combobox";
-
-export type ComboboxChipRemoveProps = Omit<
-  BaseCombobox.ChipRemove.Props,
-  "children" | "className" | "style"
-> & {
-  /** The remove glyph. Defaults to an X (defaults are a `components` concern). */
-  icon?: React.ReactNode;
-};
-
-/**
- * Ready-made chip-remove control: Base UI's remove behavior grafted onto the styled button. Give it
- * an `aria-label` naming the value it removes.
- */
-export function ComboboxChipRemove({ icon, ...props }: ComboboxChipRemoveProps) {
-  return (
-    <BaseCombobox.ChipRemove {...props} render={<ComboboxChipRemoveElement />}>
-      {icon ?? <X aria-hidden />}
-    </BaseCombobox.ChipRemove>
-  );
-}
diff --git a/packages/propel/src/components/combobox/combobox-chip.tsx b/packages/propel/src/components/combobox/combobox-chip.tsx
index b841efab..972514ad 100644
--- a/packages/propel/src/components/combobox/combobox-chip.tsx
+++ b/packages/propel/src/components/combobox/combobox-chip.tsx
@@ -2,7 +2,6 @@ import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
 import type * as React from "react";
 
 import { ComboboxChip as ComboboxChipElement } from "../../elements/combobox";
-import { ComboboxChipRemove } from "./combobox-chip-remove";
 
 export type ComboboxChipProps = Omit<
   BaseCombobox.Chip.Props,
@@ -14,21 +13,24 @@ export type ComboboxChipProps = Omit<
   endContent?: React.ReactNode;
   /** The chip's label. Also sets the chip's own accessible name. */
   label: string;
-  /** Accessible name for the remove button (localizable), e.g. `` `Remove ${label}` ``. */
-  removeLabel: string;
+  /**
+   * The remove control, grafted onto Base UI's `ChipRemove` behavior. It carries its own —
+   * localizable — `aria-label`; the chip bakes no label or glyph.
+   */
+  remove: React.ReactElement;
 };
 
 /**
  * Ready-made chip: Base UI's chip behavior (arrow-key focus, Backspace/Delete removal) grafted onto
- * the styled tag, laying out an optional leading/trailing node around the label plus a
- * `ComboboxChipRemove`. Base UI derives which selected value a chip represents from its position
- * among its siblings — pass one per value from `ComboboxChips`' `children`.
+ * the styled tag, laying out an optional leading/trailing node around the label plus the
+ * consumer-provided `remove` control. Base UI derives which selected value a chip represents from
+ * its position among its siblings — pass one per value from `ComboboxChips`' `children`.
  */
 export function ComboboxChip({
   startContent,
   endContent,
   label,
-  removeLabel,
+  remove,
   ...props
 }: ComboboxChipProps) {
   return (
@@ -36,7 +38,7 @@ export function ComboboxChip({
       {startContent}
       {label}
       {endContent}
-      <ComboboxChipRemove aria-label={removeLabel} />
+      <BaseCombobox.ChipRemove render={remove} />
     </BaseCombobox.Chip>
   );
 }
diff --git a/packages/propel/src/components/combobox/combobox-chips.tsx b/packages/propel/src/components/combobox/combobox-chips.tsx
index b5543c1e..118c8010 100644
--- a/packages/propel/src/components/combobox/combobox-chips.tsx
+++ b/packages/propel/src/components/combobox/combobox-chips.tsx
@@ -23,8 +23,7 @@ export type ComboboxChipsProps<Value = string> = {
   /**
    * Renders one selected value as a `ComboboxChip` — the `ComboboxChips` counterpart of
    * `ComboboxList`'s item template. Set your own `key`, exactly like `ComboboxList`'s function
-   * child, e.g. ``(value) => <ComboboxChip key={value} label={value} removeLabel={`Remove
-   * ${value}`} />``.
+   * child, e.g. `(value) => <ComboboxChip key={value} label={value} remove={<... />} />`.
    */
   children: (value: Value) => React.ReactNode;
 };
diff --git a/packages/propel/src/components/combobox/combobox.stories.tsx b/packages/propel/src/components/combobox/combobox.stories.tsx
index 989355ea..eada4fbe 100644
--- a/packages/propel/src/components/combobox/combobox.stories.tsx
+++ b/packages/propel/src/components/combobox/combobox.stories.tsx
@@ -22,7 +22,6 @@ import { InputField } from "../input-field/index";
 import {
   Combobox,
   ComboboxChip,
-  ComboboxChipRemove,
   ComboboxChips,
   ComboboxCollection,
   ComboboxContent,
@@ -50,7 +49,6 @@ const meta = {
     ComboboxInputGroup,
     ComboboxChips,
     ComboboxChip,
-    ComboboxChipRemove,
     ComboboxContent,
     ComboboxList,
     ComboboxItem,
@@ -182,7 +180,8 @@ export const InvalidInteraction: Story = {
  * `multiple` swaps the input frame for `ComboboxChips`: each selected value renders as a removable
  * chip ahead of the inline input, wrapping onto new rows as the selection grows. `children` renders
  * one value as a `ComboboxChip` — the `ComboboxChips` counterpart of `ComboboxList`'s item
- * template. `removeLabel` names the chip's remove button (localizable, required). Arrow keys move
+ * template. `remove` is a consumer-supplied control (its own — localizable — `aria-label`) grafted
+ * onto Base UI's remove behavior, same as `ComboboxInputGroup`'s `clear`/`trigger`. Arrow keys move
  * focus across chips; Backspace removes.
  */
 export const Multiple: Story = {
@@ -194,7 +193,19 @@ export const Multiple: Story = {
         </FieldLabel>
         <ComboboxChips magnitude="md" placeholder="Add a region">
           {(region: string) => (
-            <ComboboxChip key={region} label={region} removeLabel={`Remove ${region}`} />
+            <ComboboxChip
+              key={region}
+              label={region}
+              remove={
+                <IconButton
+                  prominence="ghost"
+                  tone="neutral"
+                  magnitude="sm"
+                  aria-label={`Remove ${region}`}
+                  icon={<Icon icon={X} />}
+                />
+              }
+            />
           )}
         </ComboboxChips>
         <ComboboxContent>
@@ -260,8 +271,16 @@ export const MultipleOverflow: Story = {
             <ComboboxChip
               key={region}
               label={region}
-              removeLabel={`Remove ${region}`}
               startContent={<Icon icon={MapPin} />}
+              remove={
+                <IconButton
+                  prominence="ghost"
+                  tone="neutral"
+                  magnitude="sm"
+                  aria-label={`Remove ${region}`}
+                  icon={<Icon icon={X} />}
+                />
+              }
             />
           )}
         </ComboboxChips>
@@ -552,7 +571,15 @@ export const Creatable: Story = {
                 <ComboboxChip
                   key={label.id}
                   label={label.value}
-                  removeLabel={`Remove ${label.value}`}
+                  remove={
+                    <IconButton
+                      prominence="ghost"
+                      tone="neutral"
+                      magnitude="sm"
+                      aria-label={`Remove ${label.value}`}
+                      icon={<Icon icon={X} />}
+                    />
+                  }
                 />
               )}
             </ComboboxChips>
diff --git a/packages/propel/src/components/combobox/index.tsx b/packages/propel/src/components/combobox/index.tsx
index 0c9a995b..2cd7d21c 100644
--- a/packages/propel/src/components/combobox/index.tsx
+++ b/packages/propel/src/components/combobox/index.tsx
@@ -1,6 +1,5 @@
 export * from "./combobox";
 export * from "./combobox-chip";
-export * from "./combobox-chip-remove";
 export * from "./combobox-chips";
 export * from "./combobox-collection";
 export * from "./combobox-content";
diff --git a/packages/propel/src/elements/combobox/combobox-chip-remove.tsx b/packages/propel/src/elements/combobox/combobox-chip-remove.tsx
deleted file mode 100644
index d66f7330..00000000
--- a/packages/propel/src/elements/combobox/combobox-chip-remove.tsx
+++ /dev/null
@@ -1,22 +0,0 @@
-import { mergeProps } from "@base-ui/react/merge-props";
-import { useRender } from "@base-ui/react/use-render";
-
-import { comboboxChipRemoveVariants } from "./variants";
-
-export type ComboboxChipRemoveProps = Omit<
-  useRender.ComponentProps<"button">,
-  "className" | "style"
->;
-
-/**
- * The remove affordance inside a `ComboboxChip`. Renders whatever X-style svg you pass, sized to
- * the chip's scale. Give it an `aria-label` naming the value it removes. Base-UI-agnostic — graft
- * in `components` via `<BaseCombobox.ChipRemove render={<ComboboxChipRemove/>} />`.
- */
-export function ComboboxChipRemove({ render, ...props }: ComboboxChipRemoveProps) {
-  const defaultProps: useRender.ElementProps<"button"> = {
-    type: "button",
-    className: comboboxChipRemoveVariants(),
-  };
-  return useRender({ defaultTagName: "button", render, props: mergeProps(defaultProps, props) });
-}
diff --git a/packages/propel/src/elements/combobox/combobox-chip.tsx b/packages/propel/src/elements/combobox/combobox-chip.tsx
index be4067c7..7719ed55 100644
--- a/packages/propel/src/elements/combobox/combobox-chip.tsx
+++ b/packages/propel/src/elements/combobox/combobox-chip.tsx
@@ -6,10 +6,10 @@ import { comboboxChipVariants } from "./variants";
 export type ComboboxChipProps = Omit<useRender.ComponentProps<"div">, "className" | "style">;
 
 /**
- * One selected value in the multiselect frame, shown as a removable tag: its label plus a
- * `ComboboxChipRemove`. Arrow keys move focus across chips (Base UI's behavior), so it carries the
- * standard focus ring. Base-UI-agnostic — graft in `components` via `<BaseCombobox.Chip
- * render={<ComboboxChip/>} />`.
+ * One selected value in the multiselect frame, shown as a removable tag: its label plus a remove
+ * control (an `IconButton` grafted onto Base UI's `ChipRemove` by the `components` ready-made).
+ * Arrow keys move focus across chips (Base UI's behavior), so it carries the standard focus ring.
+ * Base-UI-agnostic — graft in `components` via `<BaseCombobox.Chip render={<ComboboxChip/>} />`.
  */
 export function ComboboxChip({ render, ...props }: ComboboxChipProps) {
   const defaultProps: useRender.ElementProps<"div"> = { className: comboboxChipVariants() };
diff --git a/packages/propel/src/elements/combobox/combobox.stories.tsx b/packages/propel/src/elements/combobox/combobox.stories.tsx
index 7700da8b..4a4a0fb1 100644
--- a/packages/propel/src/elements/combobox/combobox.stories.tsx
+++ b/packages/propel/src/elements/combobox/combobox.stories.tsx
@@ -9,7 +9,6 @@ import { IconButton } from "../icon-button";
 import {
   ComboboxChip,
   ComboboxChipOverflow,
-  ComboboxChipRemove,
   ComboboxChips,
   ComboboxEmpty,
   ComboboxInput,
@@ -50,7 +49,6 @@ const meta = {
     ComboboxChips,
     ComboboxChip,
     ComboboxChipOverflow,
-    ComboboxChipRemove,
     ComboboxItemIndicator,
     ComboboxEmpty,
     ListboxPopup,
@@ -160,9 +158,16 @@ export const Magnitudes: Story = {
           <ComboboxChips magnitude={magnitude} layout="wrap">
             <ComboboxChip>
               us-east-1
-              <ComboboxChipRemove aria-label={`Remove us-east-1 (${magnitude})`}>
-                <X aria-hidden />
-              </ComboboxChipRemove>
+              <IconButton
+                prominence="ghost"
+                tone="neutral"
+                magnitude="sm"
+                aria-label={`Remove us-east-1 (${magnitude})`}
+              >
+                <Icon>
+                  <X />
+                </Icon>
+              </IconButton>
             </ComboboxChip>
             <ComboboxInput aria-label={`Regions (${magnitude})`} placeholder="Add a region" />
           </ComboboxChips>
@@ -248,20 +253,18 @@ export const StatesCanary: Story = {
 
 /**
  * The multiselect anatomy: `ComboboxChips` replaces the input frame, wrapping one `ComboboxChip`
- * per selected value (its label plus a `ComboboxChipRemove` — pass an X-style svg and an
- * `aria-label` naming the value) ahead of the inline `ComboboxInput`. Chip states pinned: the
- * second chip wears the focus ring arrow-key navigation would give it (forced by the pseudo-states
- * addon, as is the first chip's remove hover), and the third pins the `data-disabled` a disabled
- * root would mirror onto it, with its remove natively disabled.
+ * per selected value (its label plus the remove control — an `IconButton` the components ready-made
+ * grafts onto Base UI's remove behavior) ahead of the inline `ComboboxInput`. Chip states pinned:
+ * the third pins the `data-disabled` a disabled root would mirror onto the chip, with its remove
+ * natively disabled.
  */
 export const Chips: Story = {
   parameters: {
     controls: { disable: true },
     a11y: {
-      // Pinning hover/disabled state attributes makes axe evaluate visuals it never sees live
-      // (it does not test :hover, and WCAG 1.4.3 exempts disabled controls). The tertiary-text-
-      // on-hover-fill contrast is a design-token question flagged for the design pass, not a
-      // story bug.
+      // Pinning the disabled state attribute makes axe evaluate visuals it never sees live (WCAG
+      // 1.4.3 exempts disabled controls). The tertiary-text-on-hover-fill contrast is a design-token
+      // question flagged for the design pass, not a story bug.
       config: { rules: [{ id: "color-contrast", enabled: false }] },
     },
   },
@@ -270,21 +273,43 @@ export const Chips: Story = {
       <ComboboxChips magnitude="md" layout="wrap">
         <ComboboxChip>
           us-east-1
-          <ComboboxChipRemove id="combobox-chip-remove-hover" aria-label="Remove us-east-1">
-            <X aria-hidden />
-          </ComboboxChipRemove>
+          <IconButton
+            prominence="ghost"
+            tone="neutral"
+            magnitude="sm"
+            aria-label="Remove us-east-1"
+          >
+            <Icon>
+              <X />
+            </Icon>
+          </IconButton>
         </ComboboxChip>
-        <ComboboxChip id="combobox-chip-focus">
+        <ComboboxChip>
           eu-central-1
-          <ComboboxChipRemove aria-label="Remove eu-central-1">
-            <X aria-hidden />
-          </ComboboxChipRemove>
+          <IconButton
+            prominence="ghost"
+            tone="neutral"
+            magnitude="sm"
+            aria-label="Remove eu-central-1"
+          >
+            <Icon>
+              <X />
+            </Icon>
+          </IconButton>
         </ComboboxChip>
         <ComboboxChip data-disabled="">
           ap-west-1
-          <ComboboxChipRemove aria-label="Remove ap-west-1" disabled>
-            <X aria-hidden />
-          </ComboboxChipRemove>
+          <IconButton
+            prominence="ghost"
+            tone="neutral"
+            magnitude="sm"
+            aria-label="Remove ap-west-1"
+            disabled
+          >
+            <Icon>
+              <X />
+            </Icon>
+          </IconButton>
         </ComboboxChip>
         <ComboboxInput aria-label="Regions" placeholder="Add a region" />
       </ComboboxChips>
@@ -308,18 +333,32 @@ export const Collapsed: Story = {
             <Check />
           </Icon>
           Priya Nair
-          <ComboboxChipRemove aria-label="Remove Priya Nair">
-            <X aria-hidden />
-          </ComboboxChipRemove>
+          <IconButton
+            prominence="ghost"
+            tone="neutral"
+            magnitude="sm"
+            aria-label="Remove Priya Nair"
+          >
+            <Icon>
+              <X />
+            </Icon>
+          </IconButton>
         </ComboboxChip>
         <ComboboxChip>
           <Icon>
             <Check />
           </Icon>
           Marcus Chen
-          <ComboboxChipRemove aria-label="Remove Marcus Chen">
-            <X aria-hidden />
-          </ComboboxChipRemove>
+          <IconButton
+            prominence="ghost"
+            tone="neutral"
+            magnitude="sm"
+            aria-label="Remove Marcus Chen"
+          >
+            <Icon>
+              <X />
+            </Icon>
+          </IconButton>
         </ComboboxChip>
         <ComboboxChipOverflow>+5 more</ComboboxChipOverflow>
         <ComboboxInput aria-label="Assignees" placeholder="" />
diff --git a/packages/propel/src/elements/combobox/index.tsx b/packages/propel/src/elements/combobox/index.tsx
index fbf451b7..9c061e93 100644
--- a/packages/propel/src/elements/combobox/index.tsx
+++ b/packages/propel/src/elements/combobox/index.tsx
@@ -1,6 +1,5 @@
 export * from "./combobox-chip";
 export * from "./combobox-chip-overflow";
-export * from "./combobox-chip-remove";
 export * from "./combobox-chips";
 export * from "./combobox-empty";
 export * from "./combobox-input";
diff --git a/packages/propel/src/elements/combobox/variants.ts b/packages/propel/src/elements/combobox/variants.ts
index 23d13188..a27e9ab2 100644
--- a/packages/propel/src/elements/combobox/variants.ts
+++ b/packages/propel/src/elements/combobox/variants.ts
@@ -4,7 +4,6 @@ import { controlGroupClass, controlMagnitude } from "../../internal/control-grou
 import { controlInputClass } from "../../internal/control-input";
 import { itemIndicatorClass } from "../../internal/item-indicator";
 import { listboxEmptyClass } from "../../internal/listbox-empty";
-import { nodeSlotClass } from "../../internal/node-slot";
 import { type StrictVariantProps } from "../../internal/variant-props";
 
 export const comboboxInputGroupVariants = cva(
@@ -77,15 +76,6 @@ export const comboboxChipVariants = cva(
 export const comboboxChipOverflowVariants = cva(
   "shrink-0 px-0.5 text-13 text-secondary select-none",
 );
-// The chip's remove affordance; pass an X-style svg.
-export const comboboxChipRemoveVariants = cva(
-  cx(
-    nodeSlotClass,
-    "size-4 cursor-pointer rounded-sm text-icon-secondary [--node-size:0.75rem]",
-    "outline-none hover:bg-layer-transparent-hover focus-visible:ring-2 focus-visible:ring-accent-strong",
-    "disabled:cursor-not-allowed disabled:text-icon-disabled",
-  ),
-);
 
 export type ComboboxInputGroupVariantProps = StrictVariantProps<typeof comboboxInputGroupVariants>;
 export type ComboboxChipsVariantProps = StrictVariantProps<typeof comboboxChipsVariants>;

From 37a3bf313800edcb80a6b0944029fe643b05de3f Mon Sep 17 00:00:00 2001
From: Atul Tameshwari <atameshwari9@gmail.com>
Date: Wed, 8 Jul 2026 16:55:04 +0530
Subject: [PATCH 31/31] fix(rebase): reconcile drawer + select-field with
 approved review state

Rebasing onto the merge-base dropped two merge commits whose reconciliations
had removed the components-tier DrawerHeader ready-made (reverting to the
elements DrawerHeader re-export) and dropped the transient select-field
description guard. Restore the approved-review state for those files.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/components/drawer/drawer-header.tsx   | 36 -------------------
 .../propel/src/components/drawer/index.tsx    |  7 ++--
 .../components/select-field/select-field.tsx  |  2 +-
 3 files changed, 4 insertions(+), 41 deletions(-)
 delete mode 100644 packages/propel/src/components/drawer/drawer-header.tsx

diff --git a/packages/propel/src/components/drawer/drawer-header.tsx b/packages/propel/src/components/drawer/drawer-header.tsx
deleted file mode 100644
index 6e61ce56..00000000
--- a/packages/propel/src/components/drawer/drawer-header.tsx
+++ /dev/null
@@ -1,36 +0,0 @@
-import { Drawer as BaseDrawer } from "@base-ui/react/drawer";
-import { X } from "lucide-react";
-
-import {
-  DrawerHeader as DrawerHeaderElement,
-  type DrawerHeaderProps as DrawerHeaderElementProps,
-} from "../../elements/drawer";
-import { IconButton } from "../icon-button";
-
-export type DrawerHeaderProps = DrawerHeaderElementProps & {
-  /** Accessible label for the built-in corner close button. @default "Close" */
-  closeLabel?: string;
-};
-
-/**
- * The drawer's top region with a built-in corner close: lays the consumer's heading block (a
- * `DrawerHeaderContent`) at the inline-start and a ghost `IconButton` dismiss at the inline-end, so
- * every drawer gets a consistent close without hand-wiring one. The close grafts Base UI's
- * `Drawer.Close` behavior onto the `IconButton` (behavior part outer, styled part as render
- * target). Pass `closeLabel` to localize its accessible name. For a header without the close,
- * compose the `elements/drawer` `DrawerHeader` atom directly.
- */
-export function DrawerHeader({ closeLabel = "Close", children, ...props }: DrawerHeaderProps) {
-  return (
-    <DrawerHeaderElement {...props}>
-      {children}
-      <BaseDrawer.Close
-        render={
-          <IconButton prominence="ghost" tone="neutral" magnitude="lg" aria-label={closeLabel}>
-            <X aria-hidden />
-          </IconButton>
-        }
-      />
-    </DrawerHeaderElement>
-  );
-}
diff --git a/packages/propel/src/components/drawer/index.tsx b/packages/propel/src/components/drawer/index.tsx
index ad2ccd36..e6ef9213 100644
--- a/packages/propel/src/components/drawer/index.tsx
+++ b/packages/propel/src/components/drawer/index.tsx
@@ -9,14 +9,11 @@ export * from "./drawer-backdrop";
 export * from "./drawer-title";
 export * from "./drawer-description";
 export * from "./drawer-panel";
-export * from "./drawer-header";
 export * from "./create-handle";
 // Re-export the styled `elements` parts so a full drawer can be assembled from one entry. The
 // behavior-only roles need no Base UI at the call site: `DrawerTrigger`/`DrawerClose` above are
 // the passthroughs, and `DrawerPanel` composes the `Portal`. The styled bare close control stays
-// in `elements/drawer` — the `DrawerClose` behavior part replaces its re-export here. `DrawerHeader`
-// is NOT re-exported from `elements` here: the `./drawer-header` ready-made (with the built-in
-// corner close) shadows it; the close-less atom stays reachable at `@plane/propel/elements/drawer`.
+// in `elements/drawer` — the `DrawerClose` behavior part replaces its re-export here.
 export {
   DrawerBody,
   type DrawerBodyProps,
@@ -24,6 +21,8 @@ export {
   type DrawerContentProps,
   DrawerFooter,
   type DrawerFooterProps,
+  DrawerHeader,
+  type DrawerHeaderProps,
   DrawerHeaderContent,
   type DrawerHeaderContentProps,
   DrawerPopup,
diff --git a/packages/propel/src/components/select-field/select-field.tsx b/packages/propel/src/components/select-field/select-field.tsx
index 5a1190d0..0cd8dd28 100644
--- a/packages/propel/src/components/select-field/select-field.tsx
+++ b/packages/propel/src/components/select-field/select-field.tsx
@@ -64,7 +64,7 @@ export function SelectField({
           {label}
         </BaseSelect.Label>
         <SelectTrigger magnitude={selectMagnitude} />
-        {error == null && description != null ? (
+        {description != null ? (
           <FieldDescription magnitude={magnitude}>{description}</FieldDescription>
         ) : null}
         <BaseSelect.Portal>