Toolbar: elevation + density as orthogonal axes

Replace the placement-named `variant` (floater/topbar/bottom-bar) with two
axes named for what they actually express:

- `elevation`: `raised` draws its own card (border + shadow) so it hovers over
  content; `flat` draws no surface and sits flush in a host bar. topbar and
  bottom-bar rendered identically, so they fold into one `flat`.
- `density`: `compact` (24px hit targets) vs `comfortable` (28px).

Both are required props, so the variant->density derivation table and the
`density ?? ...` fallback are gone. "Fixed + compact" stops being a special
case — it's just `elevation="flat" density="compact"`. Placement is the
consumer's job, not the primitive's, so it no longer lives on the component.

Also drop the now-dead `defaultVariants` on the internal item/dropdown
recipes: density always arrives through context.

Breaking: `variant` is removed. floater -> elevation="raised" density="compact";
topbar/bottom-bar -> elevation="flat" density="comfortable".

Author: lifeiscontent

packages/propel/src/components/toolbar/index.tsx

@@ -17,65 +17,53 @@ import {
   type DropdownSeparatorProps,
 } from "../dropdown/index";
 
-// The Figma "Toolbar" component has a single `variant` axis describing where the
-// toolbar is placed (Figma: Floater / Pages - Topbar / Comments bottom bar). The
-// variants differ in two ways: their *surface* and their *density*. Only the
-// floater is a self-contained surface — a white `surface-1` card with a subtle
-// border, `radius/lg` corners and an `Overlay-100` shadow — so it can hover over
-// content. Topbar and bottom-bar sit flush inside an existing bar, so they're flat
-// (no surface, no shadow) and are therefore visually identical to each other.
+// A toolbar is described by two orthogonal axes — `elevation` and `density` — named
+// for what they actually express rather than where the toolbar is placed (placement
+// is the consumer's job, not a primitive's). The Figma "Toolbar" component models
+// these as placements (Floater / Pages - Topbar / Comments bottom bar), but those
+// collapse to combinations of the two axes here.
 //
-// Density differs too: the floater packs controls tighter (24px hit targets, a
-// 14px chevron) while the topbar/bottom-bar are roomier (28px hit targets, a 16px
-// chevron). Every placement shares the root `p-1.5` (6px) padding and `gap-2` (8px)
-// item gap; clusters inside `ToolbarGroup`/`ToolbarToggleGroup` keep a tight
-// `gap-0.5` (2px).
+// `elevation`: whether the toolbar draws its own surface. `raised` is a
+// self-contained card — a white `surface-1` fill with a subtle border, `radius/lg`
+// corners and an `Overlay-100` shadow — so it can hover over content (the Figma
+// floater). `flat` draws no surface and sits flush inside an existing bar (the Figma
+// topbar / bottom-bar, which were visually identical).
 const toolbarVariants = cva("flex w-fit items-center gap-2 p-1.5 text-secondary", {
   variants: {
-    variant: {
-      floater: surfaceVariants({ elevation: "raised", radius: "lg" }),
-      topbar: "",
-      "bottom-bar": "",
+    elevation: {
+      raised: surfaceVariants({ elevation: "raised", radius: "lg" }),
+      flat: "",
     },
   },
 });
 
-export type ToolbarVariant = NonNullable<VariantProps<typeof toolbarVariants>["variant"]>;
+export type ToolbarElevation = NonNullable<VariantProps<typeof toolbarVariants>["elevation"]>;
 
-// The density of a toolbar defaults from its placement: the `floater` is compact
-// (24px hit targets), while `topbar`/`bottom-bar` are comfortable (28px). The
-// resolved density is shared with the child controls (buttons, toggles, dropdown
-// trigger) through context so they size themselves to match the root. Callers can
-// pass `density` on the root to override the placement default — e.g. Figma's flat
-// "fixed + compact" bar is a `topbar` forced to `compact`.
+// `density`: how tightly the controls pack. `compact` is 24px hit targets (a 14px
+// chevron), `comfortable` is 28px (a 16px chevron). It's shared with the child
+// controls (buttons, toggles, dropdown trigger) through context so they size
+// themselves to match the root. Both axes share the root `p-1.5` (6px) padding and
+// `gap-2` (8px) item gap; clusters inside `ToolbarGroup`/`ToolbarToggleGroup` keep a
+// tight `gap-0.5` (2px).
 type ToolbarDensity = "compact" | "comfortable";
 
-const DENSITY_BY_VARIANT: Record<ToolbarVariant, ToolbarDensity> = {
-  floater: "compact",
-  topbar: "comfortable",
-  "bottom-bar": "comfortable",
-};
-
 const ToolbarDensityContext = React.createContext<ToolbarDensity>("compact");
 
 export type ToolbarProps = Omit<
   React.ComponentProps<typeof BaseToolbar.Root>,
   "className" | "render" | "style"
 > & {
   /**
-   * Where the toolbar is placed, which controls its surface and the default density.
-   * `floater` is a self-contained card with a border + shadow that hovers over content
-   * and packs its controls tightly (24px). `topbar` and `bottom-bar` are flat, sit flush
-   * inside an existing bar, and default to the roomier 28px density.
+   * Whether the toolbar draws its own surface. `raised` is a self-contained card
+   * with a border + shadow that hovers over content; `flat` draws no surface and
+   * sits flush inside an existing bar. Independent of `density`.
    */
-  variant: ToolbarVariant;
+  elevation: ToolbarElevation;
   /**
-   * Hit-target density of the toolbar's controls. Defaults to the placement default
-   * (`floater` -> `compact`, `topbar`/`bottom-bar` -> `comfortable`); pass it to override
-   * the default and decouple density from `variant` — e.g. a flat `topbar` forced to
-   * `compact` for Figma's "fixed + compact" bar.
+   * How tightly the controls pack. `compact` is 24px hit targets, `comfortable` is
+   * 28px. Independent of `elevation`, so a flat bar can still be compact.
    */
-  density?: ToolbarDensity;
+  density: ToolbarDensity;
 };
 
 /**
@@ -85,10 +73,10 @@ export type ToolbarProps = Omit<
  * carries `role="toolbar"`. Compose it from `ToolbarGroup`, `ToolbarButton`,
  * `ToolbarToggle`, `ToolbarSeparator` and `ToolbarDropdown`.
  */
-export function Toolbar({ variant, density, ...props }: ToolbarProps) {
+export function Toolbar({ elevation, density, ...props }: ToolbarProps) {
   return (
-    <ToolbarDensityContext.Provider value={density ?? DENSITY_BY_VARIANT[variant]}>
-      <BaseToolbar.Root className={toolbarVariants({ variant })} {...props} />
+    <ToolbarDensityContext.Provider value={density}>
+      <BaseToolbar.Root className={toolbarVariants({ elevation })} {...props} />
     </ToolbarDensityContext.Provider>
   );
 }
@@ -130,9 +118,6 @@ const itemVariants = cva(
         comfortable: "size-7 [&_svg]:size-4",
       },
     },
-    defaultVariants: {
-      density: "compact",
-    },
   },
 );
 
@@ -235,9 +220,6 @@ const dropdownTriggerVariants = cva(
         comfortable: "h-7",
       },
     },
-    defaultVariants: {
-      density: "compact",
-    },
   },
 );
 
@@ -248,9 +230,6 @@ const dropdownChevronVariants = cva("shrink-0 text-icon-secondary", {
       comfortable: "size-4",
     },
   },
-  defaultVariants: {
-    density: "compact",
-  },
 });
 
 /**

packages/propel/src/components/toolbar/toolbar.stories.tsx

@@ -143,7 +143,7 @@ const meta = {
     ToolbarDropdownItem,
     ToolbarDropdownSeparator,
   },
-  args: { variant: "floater" },
+  args: { elevation: "raised", density: "compact" },
   render: (args) => <FormattingToolbar {...args} />,
   parameters: {
     design: {
@@ -156,33 +156,46 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-/** The default `floater`: a self-contained card with a border + shadow. */
+/** The default: a `raised`, `compact` floater — a self-contained card with a border + shadow. */
 export const Default: Story = {};
 
 /**
- * Each placement at its default density: the floating card is `compact` (24px), the
- * flat topbar and bottom bar are `comfortable` (28px). Density follows `variant`
- * unless overridden (see `FixedCompact`).
+ * The `elevation` axis: `raised` draws its own card (border + shadow) so it can hover
+ * over content; `flat` draws no surface and sits flush inside an existing bar.
+ * Independent of `density` — both rows keep the story's current density.
  */
-export const Variants: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
+export const Elevations: Story = {
+  argTypes: { elevation: { control: false } },
+  render: (args) => (
+    <div className="flex flex-col gap-6">
+      <FormattingToolbar {...args} elevation="raised" />
+      <FormattingToolbar {...args} elevation="flat" />
+    </div>
+  ),
+};
+
+/**
+ * The `density` axis: `compact` packs the controls to 24px hit targets, `comfortable`
+ * gives them 28px. Independent of `elevation` — both rows keep the story's current
+ * elevation.
+ */
+export const Densities: Story = {
+  argTypes: { density: { control: false } },
+  render: (args) => (
     <div className="flex flex-col gap-6">
-      <FormattingToolbar variant="floater" />
-      <FormattingToolbar variant="topbar" />
-      <FormattingToolbar variant="bottom-bar" />
+      <FormattingToolbar {...args} density="compact" />
+      <FormattingToolbar {...args} density="comfortable" />
     </div>
   ),
 };
 
 /**
- * Density is its own axis: pass `density` to decouple it from `variant`. Here a flat
- * `topbar` is forced to `compact` (24px) for Figma's "fixed + compact" bar — a
- * non-floating surface at the tight floater density. Without the override a `topbar`
- * would default to `comfortable` (28px).
+ * `elevation` and `density` are orthogonal: a `flat` bar can still be `compact`. This
+ * is Figma's "fixed + compact" bar — a non-floating surface at the tight 24px density
+ * the raised floater also uses.
  */
-export const FixedCompact: Story = {
-  args: { variant: "topbar", density: "compact" },
+export const FlatCompact: Story = {
+  args: { elevation: "flat", density: "compact" },
   parameters: {
     design: {
       type: "figma",
@@ -192,23 +205,22 @@ export const FixedCompact: Story = {
 };
 
 /**
- * Density override check that runs in the browser: a flat `topbar` defaults to
- * `comfortable` (28px), but passing `density="compact"` decouples density from
- * `variant` and shrinks its controls to 24px. Tagged out of the sidebar/docs/manifest
- * — it's a test, not a designer- or agent-facing example — but still runs under the
- * default `test` tag.
+ * Density wiring check that runs in the browser: `density` drives the child controls'
+ * size through context, independent of `elevation`, so a `flat` + `compact` toolbar
+ * renders 24px controls. Tagged out of the sidebar/docs/manifest — it's a test, not a
+ * designer- or agent-facing example — but still runs under the default `test` tag.
  */
-export const DensityOverride: Story = {
+export const DensityDrivesControlSize: Story = {
   tags: ["!dev", "!autodocs", "!manifest"],
   render: () => (
-    <Toolbar variant="topbar" density="compact">
+    <Toolbar elevation="flat" density="compact">
       <ToolbarToggle aria-label="Bold">
         <Bold aria-hidden />
       </ToolbarToggle>
     </Toolbar>
   ),
   play: async ({ canvas }) => {
-    // A flat topbar would default to comfortable (28px); the compact override wins.
+    // density="compact" sizes the controls to 24px regardless of the flat elevation.
     const bold = canvas.getByRole("button", { name: "Bold" });
     await expect(bold).toHaveClass("size-6");
     await expect(getComputedStyle(bold).height).toBe("24px");
@@ -284,7 +296,7 @@ export const Behavior: Story = {
 export const KeyboardRovingFocus: Story = {
   tags: ["!dev", "!autodocs", "!manifest"],
   render: () => (
-    <Toolbar variant="floater">
+    <Toolbar elevation="raised" density="compact">
       <ToolbarToggle aria-label="Bold">
         <Bold aria-hidden />
       </ToolbarToggle>

packages/propel/src/patterns/comment.stories.tsx

@@ -70,7 +70,7 @@ const bodyVariants = cva(
 // editor; here they just compose propel's Toolbar parts.
 function FormattingToolbar() {
   return (
-    <Toolbar variant="bottom-bar" aria-label="Comment formatting">
+    <Toolbar elevation="flat" density="comfortable" aria-label="Comment formatting">
       <ToolbarGroup aria-label="Insert">
         <ToolbarButton aria-label="Mention someone">
           <AtSign aria-hidden />
@@ -248,7 +248,7 @@ const RECIPE_SOURCE = `function CommentComposer() {
         className="min-h-10 w-full resize-none bg-transparent p-3 text-14 leading-snug text-primary outline-none placeholder:text-placeholder"
       />
       <div className="flex min-h-9 items-center justify-between gap-2 py-1 pe-1.5 ps-1">
-        <Toolbar variant="bottom-bar" aria-label="Comment formatting">
+        <Toolbar elevation="flat" density="comfortable" aria-label="Comment formatting">
           <ToolbarGroup aria-label="Insert">
             <ToolbarButton aria-label="Mention someone">
               <AtSign aria-hidden />