@12-apps/ui 1.12.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -194,7 +194,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@12-apps/forms-core": "^1.11.0",
+    "@12-apps/forms-core": "^1.12.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@monaco-editor/react": "^4.7.0",
@@ -209,8 +209,8 @@
     "recharts": "^3.5.1"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.12.1",
-    "@12-apps/typescript-config": "^1.12.1",
+    "@12-apps/eslint-config": "^1.13.0",
+    "@12-apps/typescript-config": "^1.13.0",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",

package/src/components/data-display/DataViews/base-card.tsx

@@ -14,6 +14,7 @@ import { Text } from "../../typography/Text";
 
 import { DragHandle, useDragItem } from "./data-views-drag";
 import {
+  CARD_RADIUS,
   cardSurfaceStyles,
   isActionable,
   isSelectable,
@@ -28,9 +29,11 @@ export interface BaseCardProps extends CardSurfaceProps {
   /** Tile proportion. Defaults to "4:3". */
   aspectRatio?: CardAspectRatio;
   /**
-   * Size multiplier from the zoom slider (1 = base). Scales the card's padding +
-   * typography in step with its width (the grid sizes the track to base × scale),
-   * so the whole card grows together — a card at scale 2 renders at ~twice the
+   * Size multiplier from the zoom slider (1 = base).
+   *
+   * Applied as `zoom`, so the whole card grows together — padding, typography,
+   * the checkbox, the menu and the media alike — in step with its width, which
+   * the grid sizes to base × scale. A card at scale 2 renders at ~twice the
    * size, its proportion preserved by `aspectRatio`. Default 1.
    */
   scale?: number;
@@ -58,16 +61,26 @@ export interface BaseCardProps extends CardSurfaceProps {
   checkboxTestId?: string;
 }
 
-/** The outlined-tile style: fixed ratio, scaled padding, selected/dimmed states. */
+/**
+ * The outlined-tile style: fixed ratio, scaled padding, selected/dimmed states.
+ *
+ * See the note on the row: `zoom` scales EVERY length in the subtree, including
+ * the MUI internals (checkbox, chip, icon button) that no prop of ours reaches.
+ * The grid still sizes the track to BASE_CARD_WIDTH x scale, so the tile fills
+ * its track physically and lays its contents out in the unscaled box behind it
+ * — which is what "the whole card grows together" was always meant to mean.
+ */
 function cardSx(opts: {
   aspectRatio: CardAspectRatio;
   pad: number;
+  scale: number;
   interactive: boolean;
   draggable: boolean;
 }): CardSx {
-  const { aspectRatio, pad, interactive, draggable } = opts;
+  const { aspectRatio, pad, scale, interactive, draggable } = opts;
   return {
     position: "relative",
+    zoom: scale,
     aspectRatio: String(CARD_ASPECT_RATIOS[aspectRatio]),
     display: "flex",
     flexDirection: "column",
@@ -78,6 +91,35 @@ function cardSx(opts: {
   };
 }
 
+/**
+ * How far the first block in flow must start below the tile's top edge to clear
+ * the absolute overlays: their 4px inset plus the checkbox's 38px hit area (20px
+ * glyph in MUI's 9px padding), which is the taller of the two corners.
+ */
+const OVERLAY_BAND_PX = 42;
+
+/**
+ * The top margin each stacked slot needs, in MUI spacing units.
+ *
+ * The overlays are absolute, so they cost the flow nothing — over MEDIA that is
+ * the whole point (a checkbox on a thumbnail reads as a checkbox on a
+ * thumbnail). Over TEXT it is a collision: a title-only tile started its first
+ * line at the padding edge, directly under the checkbox, and rendered
+ * `Selecionada` with the box sitting on the `Se`. So when nothing pictorial is
+ * there to absorb them, whichever block comes first clears the band instead.
+ */
+function contentGaps(opts: {
+  hasMedia: boolean;
+  hasBody: boolean;
+  overlays: boolean;
+  pad: number;
+}): { body: number; caption: number } {
+  const { hasMedia, hasBody, overlays, pad } = opts;
+  const gap = pad * 0.5;
+  const clear = !hasMedia && overlays ? Math.max(0, OVERLAY_BAND_PX / 8 - pad) : 0;
+  return { body: hasMedia ? gap : clear, caption: hasMedia || hasBody ? gap : clear };
+}
+
 /** The top-corner overlays: the select checkbox (left) and the menu slot (right). */
 function CardOverlays({
   selected,
@@ -141,12 +183,10 @@ function CardMedia({ image, imageFallback }: Pick<BaseCardProps, "image" | "imag
 function CardBodyContent({
   children,
   fill,
-  scale,
   topGap,
 }: {
   children: ReactNode;
   fill: boolean;
-  scale: number;
   topGap: number;
 }): React.JSX.Element {
   return (
@@ -158,7 +198,7 @@ function CardBodyContent({
         flexDirection: "column",
         alignItems: "center",
         justifyContent: "center",
-        gap: 0.75 * scale,
+        gap: 0.75,
         mt: topGap,
         overflow: "hidden",
       }}
@@ -172,12 +212,10 @@ function CardBodyContent({
 function CardCaption({
   title,
   subtitle,
-  scale,
   topGap,
 }: {
   title?: ReactNode;
   subtitle?: ReactNode;
-  scale: number;
   topGap: number;
 }): React.JSX.Element {
   return (
@@ -190,7 +228,7 @@ function CardCaption({
           as="p"
           style={{
             lineHeight: 1.15,
-            fontSize: `${0.95 * scale}rem`,
+            fontSize: "0.95rem",
             overflow: "hidden",
             textOverflow: "ellipsis",
             whiteSpace: "nowrap",
@@ -215,32 +253,25 @@ function CardContents({
   imageFallback,
   title,
   subtitle,
-  scale,
+  overlays,
   pad,
 }: Pick<BaseCardProps, "children" | "image" | "imageFallback" | "title" | "subtitle"> & {
-  scale: number;
+  overlays: boolean;
   pad: number;
 }): React.JSX.Element {
   const hasMedia = image != null || imageFallback != null;
   const hasBody = children != null;
   const hasCaption = title != null || subtitle != null;
-  const gap = pad * 0.5;
+  const top = contentGaps({ hasMedia, hasBody, overlays, pad });
   return (
     <>
       {hasMedia && <CardMedia image={image} imageFallback={imageFallback} />}
       {hasBody && (
-        <CardBodyContent fill={!hasMedia} scale={scale} topGap={hasMedia ? gap : 0}>
+        <CardBodyContent fill={!hasMedia} topGap={top.body}>
           {children}
         </CardBodyContent>
       )}
-      {hasCaption && (
-        <CardCaption
-          title={title}
-          subtitle={subtitle}
-          scale={scale}
-          topGap={hasMedia || hasBody ? gap : 0}
-        />
-      )}
+      {hasCaption && <CardCaption title={title} subtitle={subtitle} topGap={top.caption} />}
     </>
   );
 }
@@ -275,12 +306,11 @@ export function BaseCard(props: BaseCardProps): React.JSX.Element {
   const { selectable, actionable, theme, slot, scale, drag } = useCardShell(props);
   const dataTestId = props.testId;
   const checkboxTestId = slot("checkbox");
-  const pad = 1.5 * scale;
+  const pad = 1.5;
 
   return (
     <Card
       variant="outlined"
-      borderRadius="lg"
       onClick={onClick}
       dataTestId={dataTestId}
       className={props.className}
@@ -292,6 +322,10 @@ export function BaseCard(props: BaseCardProps): React.JSX.Element {
       // nothing at all — the styles vanish silently, which is exactly how the
       // first version of this shipped with no variants and no effects.
       sx={{
+        // The same corner the row uses: a Grade and a Lista of the same records
+        // sit beside each other, and a tile that rounds harder than the row
+        // reads as a different component.
+        borderRadius: CARD_RADIUS,
         // The shared half — variant, colour, selection, effects — identical to
         // the one BaseListCard uses, so a Grade and a Lista of the same records
         // are dressed by one set of rules.
@@ -308,8 +342,7 @@ export function BaseCard(props: BaseCardProps): React.JSX.Element {
         ),
         // …and the tile's own geometry on top.
         ...cardSx({
-          aspectRatio,
-          pad,
+          aspectRatio, pad, scale,
           interactive: onClick != null,
           draggable: drag.draggable && drag.handleProps === undefined,
         }),
@@ -338,7 +371,7 @@ export function BaseCard(props: BaseCardProps): React.JSX.Element {
         imageFallback={props.imageFallback}
         title={props.title}
         subtitle={props.subtitle}
-        scale={scale}
+        overlays={selectable || menu != null}
         pad={pad}
       >
         {props.children}

package/src/components/data-display/DataViews/base-list-card-gutters.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { Checkbox } from "../../form/Checkbox";
+import { Box } from "../../../mui/Box";
+
+import { DragHandle, useDragItem } from "./data-views-drag";
+
+/**
+ * THE TWO GUTTERS AT THE HEAD OF A ROW — the drag grip and the select checkbox.
+ *
+ * Split from `base-list-card` at the size gate. Both answer the same question in
+ * the same way: whether to occupy a rail, hold one open, or leave the template
+ * altogether. See `railsTemplateFor` for why the third option has to exist.
+ */
+
+/**
+ * MUI's Checkbox carries 9px of hit-area padding on every side.
+ *
+ * Left uncancelled, a row asking for 8px of padding puts the checkbox SQUARE 17px
+ * in — and with the empty drag gutter's gap ahead of it, 46px in, which is what
+ * made the left edge look like a mistake. The hit area is worth keeping; the
+ * optical inset is not, so the padding is cancelled with a negative margin and
+ * the glyph lands where the row's own padding says it should.
+ */
+const CHECKBOX_PAD = "-9px";
+
+/** The grip. Its gutter is reserved only when the list says to reserve it. */
+export function DragSlot({
+  drag,
+  reserve,
+  testId,
+}: {
+  drag: ReturnType<typeof useDragItem>;
+  reserve: boolean;
+  testId?: string;
+}): React.JSX.Element | null {
+  if (!drag.draggable) return reserve ? <Box data-slot="drag" /> : null;
+  return (
+    // display:flex, as on the checkbox below: the grip is an inline-grid, and in
+    // a block parent an inline box sits on the text baseline — the line box adds
+    // descender leading under it (21px glyph in a 31px slot) and drops the grip
+    // 5px below the row's centre. A flex parent has no baseline to sit on.
+    <Box
+      data-slot="drag"
+      sx={{ position: "relative", zIndex: 1, display: "flex", alignItems: "center" }}
+    >
+      <DragHandle
+        handleProps={drag.handleProps}
+        gated={drag.handleProps !== undefined}
+        testId={testId}
+      />
+    </Box>
+  );
+}
+
+/** The select checkbox. Its gutter is reserved only when the list says to. */
+export function SelectSlot({
+  selectable,
+  selected,
+  reserve,
+  onToggleSelect,
+  testId,
+}: {
+  selectable: boolean;
+  selected: boolean;
+  reserve: boolean;
+  onToggleSelect?: (event?: React.MouseEvent) => void;
+  testId?: string;
+}): React.JSX.Element | null {
+  if (!selectable) return reserve ? <Box data-slot="select" /> : null;
+  return (
+    // z-index 1: above the stretched link, or the anchor swallows the click.
+    <Box
+      data-slot="select"
+      sx={{ position: "relative", zIndex: 1, mx: CHECKBOX_PAD, display: "flex" }}
+    >
+      <Checkbox
+        checked={selected}
+        onChange={() => onToggleSelect?.()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleSelect?.(event);
+        }}
+        size="small"
+        data-testid={testId}
+        aria-label="Selecionar"
+      />
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/base-list-card-slots.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { type ReactNode } from "react";
+import { Fragment, type ReactNode } from "react";
 
 import { DescriptionItem, type DescriptionItemProps } from "../DescriptionItem";
+import { RAIL_GAP_PX } from "./list-card-rails";
 import { Box } from "../../../mui/Box";
 import { Text } from "../../typography/Text";
 
@@ -41,14 +42,12 @@ export function ListCardCaption({
   subtitle,
   href,
   target,
-  scale,
   testId,
 }: {
   title?: ReactNode;
   subtitle?: ReactNode;
   href?: string;
   target?: string;
-  scale: number;
   testId?: string;
 }): React.JSX.Element {
   return (
@@ -61,7 +60,7 @@ export function ListCardCaption({
             sx={{
               display: "block",
               lineHeight: 1.2,
-              fontSize: `${0.9 * scale}rem`,
+              fontSize: "0.9rem",
               color: "inherit",
               textDecoration: "none",
               ...CLAMP,
@@ -95,19 +94,56 @@ export function ListCardCaption({
   );
 }
 
+/** One rule between two columns. Shared, so every gap gets the same mark. */
+function MetaRule(): React.JSX.Element {
+  return (
+    <Box
+      aria-hidden
+      sx={{
+        flex: "0 0 auto",
+        color: "text.disabled",
+        opacity: 0.5,
+        userSelect: "none",
+        fontSize: "0.875rem",
+        // A cancelled row strikes the whole meta cluster, and a struck `|` is a
+        // dagger. The rule is punctuation, not data — nothing to void.
+        textDecoration: "none",
+      }}
+    >
+      |
+    </Box>
+  );
+}
+
 /**
  * The middle columns: stacked label-over-value pairs, separated by a rule.
  *
  * Stacked rather than side by side because `DATA 05/08/2026` inline spends the
  * horizontal room the value rail needs, and the separator is what stops two
  * adjacent pairs reading as one four-word phrase.
+ *
+ * EVEN GAPS, NOT EVEN BOXES. The rail takes a share of the row's spare width
+ * per pair (see `metaRail`), and the obvious way to spend it — give every pair
+ * an equal-width box and centre its content — puts the separator on the BOX
+ * boundary, which is only the visual midpoint when both pairs are the same
+ * width. They never are: `05/08/2026, 13:45` reaches almost to the edge of its
+ * box while `PIX` stops well short of its own, so the rule ends up crowded
+ * against the date and adrift from the method.
+ *
+ * So the pairs are sized to their content and the SPARE space is what gets
+ * divided evenly. `space-evenly` gives every gap — including the two either
+ * side of each separator — the same width, which puts each rule exactly halfway
+ * between the two labels it separates, whatever they happen to say.
  */
 export function ListCardMeta({
   meta,
   metaSlot,
+  trailingRule,
 }: {
   meta?: DescriptionItemProps[];
   metaSlot?: ReactNode;
+  /** Close the run with a rule, dividing the last pair from the value. */
+  trailingRule?: boolean;
 }): React.JSX.Element {
   const items = meta ?? [];
   return (
@@ -116,7 +152,11 @@ export function ListCardMeta({
       sx={{
         display: "flex",
         alignItems: "center",
-        gap: 2,
+        justifyContent: "space-evenly",
+        // A FLOOR, not the spacing itself: `space-evenly` supplies the rest, and
+        // this is only what keeps a rail with no room to spare from running the
+        // date straight into the rule.
+        gap: 1,
         whiteSpace: "nowrap",
         ...TABULAR,
         // Rung 1 of the ladder.
@@ -124,34 +164,62 @@ export function ListCardMeta({
       }}
     >
       {items.map((item, index) => (
-        <Box key={`${item.label}-${index}`} sx={{ display: "flex", alignItems: "center", gap: 2 }}>
-          {index > 0 && (
-            <Box
-              aria-hidden
-              sx={{ color: "text.disabled", opacity: 0.5, userSelect: "none", fontSize: "0.875rem" }}
-            >
-              |
-            </Box>
-          )}
+        <Fragment key={`${item.label}-${index}`}>
+          {/* ITS OWN ITEM, not the first child of the pair that follows it.
+              Nested inside, the rule travelled with that pair's centred content
+              and came to rest nearer one label than the other — a separator
+              visibly closer to MÉTODO than to DATA reads as belonging to it. */}
+          {index > 0 && <MetaRule />}
           {/* Centred: a stacked pair sitting in its own column reads as one
               unit only when the label is over the value rather than flush left
               of a value shorter than it — `MÉTODO` above `PIX` was visibly
               unhinged from it. Overridable per item. */}
-          <DescriptionItem orientation="vertical" align="center" {...item} />
-        </Box>
+          <Box
+            sx={{
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              minWidth: 0,
+              // Sized to the pair, so the gaps either side of it are free space
+              // that `space-evenly` can equalise.
+              flex: "0 0 auto",
+            }}
+          >
+            <DescriptionItem orientation="vertical" align="center" {...item} />
+          </Box>
+        </Fragment>
       ))}
       {metaSlot}
+      {trailingRule && items.length > 0 && <MetaRule />}
     </Box>
   );
 }
 
+/**
+ * The value sits flush against the meta rail, with no gap of its own.
+ *
+ * Its divider is now the LAST ITEM OF THE META CLUSTER, placed by the same
+ * `space-evenly` that places the rules between the pairs — so it is equidistant
+ * from `PIX` and from `R$ 13,90` for free, which a rule centred in the rail gap
+ * could never be: the cluster's content stops well short of the rail's right
+ * edge, leaving that rule 150px from the method and 12px from the money.
+ *
+ * Cancelling this one gap is what makes the two distances equal. Below
+ * `META_BREAK` the cluster (and its rule) are gone, so the gap comes back —
+ * otherwise the value would sit straight against the title.
+ */
+const VALUE_FLUSH = {
+  marginLeft: `-${RAIL_GAP_PX}px`,
+  [`@container (max-width: ${META_BREAK}px)`]: { marginLeft: 0 },
+} as const;
+
 /** The value, on its own rail, never truncated and never shunted by the chip. */
-function ListCardValue({ value, scale }: { value: ReactNode; scale: number }): React.JSX.Element {
+function ListCardValue({ value }: { value: ReactNode }): React.JSX.Element {
   return (
     <Text variant="body" size="sm" weight="medium" as="span">
       <Box
         component="span"
-        sx={{ fontSize: `${0.875 * scale}rem`, whiteSpace: "nowrap", ...TABULAR }}
+        sx={{ fontSize: "0.875rem", whiteSpace: "nowrap", ...TABULAR }}
       >
         {value}
       </Box>
@@ -218,25 +286,33 @@ function ListCardActions({
 /** Value, status and actions — three rails, not one flex run. */
 export function ListCardTail({
   value,
+  separated,
   status,
   actions,
   actionsAlwaysVisible,
   menu,
-  scale,
   testId,
 }: {
   value?: ReactNode;
+  /** Whether a meta cluster precedes the value and wants dividing from it. */
+  separated?: boolean;
   status?: ReactNode;
   actions?: ReactNode;
   actionsAlwaysVisible?: boolean;
   menu?: ReactNode;
-  scale: number;
   testId: (slot: string) => string | undefined;
 }): React.JSX.Element {
   return (
     <>
-      <Box data-slot="value" sx={{ textAlign: "right" }} data-testid={testId("value")}>
-        {value != null && <ListCardValue value={value} scale={scale} />}
+      <Box
+        data-slot="value"
+        sx={{
+          textAlign: "right",
+          ...(separated && value != null ? VALUE_FLUSH : {}),
+        }}
+        data-testid={testId("value")}
+      >
+        {value != null && <ListCardValue value={value} />}
       </Box>
       <Box
         data-slot="status"

package/src/components/data-display/DataViews/base-list-card.tsx

@@ -3,21 +3,22 @@
 import { useTheme } from "@mui/material/styles";
 import { type ReactNode } from "react";
 
-import { Checkbox } from "../../form/Checkbox";
 import { Card } from "../../layout/Card";
 import type { DescriptionItemProps } from "../DescriptionItem";
 import { Box } from "../../../mui/Box";
 
 import {
+  CARD_RADIUS,
   cardSurfaceStyles,
   isActionable,
   isSelectable,
   slotTestIds,
   type CardSurfaceProps,
 } from "./card-surface";
-import { DragHandle, useDragItem } from "./data-views-drag";
+import { useDragItem } from "./data-views-drag";
+import { DragSlot, SelectSlot } from "./base-list-card-gutters";
 import { DENSITY_ROW_PADDING, type DataViewsDensity } from "./data-views-layout-context";
-import { RAIL_COUNT, useListRails } from "./list-card-rails";
+import { RAIL_COUNT, RAIL_GAP, railsTemplateFor, useListRails } from "./list-card-rails";
 import {
   ListCardCaption,
   ListCardMeta,
@@ -89,7 +90,13 @@ export interface BaseListCardProps extends CardSurfaceProps {
   onToggleSelect?: (event?: React.MouseEvent) => void;
   /** How much air the row gets. Vertical only — a full-width row cannot narrow. */
   density?: DataViewsDensity;
-  /** Fine-grained size multiplier on top of `density`. */
+  /**
+   * Fine-grained size multiplier on top of `density` (1 = base).
+   *
+   * Applied as `zoom`, so it scales EVERYTHING the row draws — type, gutters,
+   * gaps, padding, the checkbox, the grip, the chip and the menu — not just the
+   * handful of font sizes it once multiplied.
+   */
   scale?: number;
   /** Flush style: a bottom rule instead of an outline. Row-only. */
   divider?: boolean;
@@ -97,9 +104,7 @@ export interface BaseListCardProps extends CardSurfaceProps {
   dragId?: string | number;
 }
 
-/** The rails, for a card with no group above it. */
-const STANDALONE_RAILS =
-  "auto auto auto minmax(0, 1fr) auto max-content max-content auto";
+
 
 /**
  * Whether a click was really a click, or the tail of a text selection.
@@ -120,70 +125,41 @@ function clickKeys(onClick: () => void) {
   };
 }
 
-/** The grip. Its gutter is reserved whether or not anything drags. */
-function DragSlot({
-  drag,
-  testId,
-}: {
-  drag: ReturnType<typeof useDragItem>;
-  testId?: string;
-}): React.JSX.Element {
-  if (!drag.draggable) return <Box data-slot="drag" />;
-  return (
-    <Box data-slot="drag" sx={{ position: "relative", zIndex: 1 }}>
-      <DragHandle
-        handleProps={drag.handleProps}
-        gated={drag.handleProps !== undefined}
-        testId={testId}
-      />
-    </Box>
-  );
-}
-
-/** The select checkbox. Its gutter is reserved whether or not it is here. */
-function SelectSlot({
-  selectable,
-  selected,
-  onToggleSelect,
-  testId,
-}: {
-  selectable: boolean;
-  selected: boolean;
-  onToggleSelect?: (event?: React.MouseEvent) => void;
-  testId?: string;
-}): React.JSX.Element {
-  if (!selectable) return <Box data-slot="select" />;
-  return (
-    // z-index 1: above the stretched link, or the anchor swallows the click.
-    <Box data-slot="select" sx={{ position: "relative", zIndex: 1 }}>
-      <Checkbox
-        checked={selected}
-        onChange={() => onToggleSelect?.()}
-        onClick={(event) => {
-          event.stopPropagation();
-          onToggleSelect?.(event);
-        }}
-        size="small"
-        data-testid={testId}
-        aria-label="Selecionar"
-      />
-    </Box>
-  );
-}
-
-/** Geometry: the rails, the density padding, the two-line collapse. */
+/**
+ * Geometry: the rails, the density padding, the two-line collapse.
+ *
+ * SCALE IS `zoom`, NOT A SET OF MULTIPLIED FONT SIZES.
+ *
+ * It used to be the latter, on exactly three values — title, value, row padding
+ * — so the slider left the subtitle, the meta labels, the rules, the checkbox,
+ * the grip, the chip and the menu at their fixed sizes, and the row came apart
+ * as you dragged it. Multiplying the rest is not a fix: the checkbox and the
+ * chip are MUI internals sized in their own px, and no prop we pass reaches
+ * them.
+ *
+ * `zoom` scales the used value of every length in the subtree — ours and theirs
+ * — and unlike `transform: scale` it REFLOWS, so the row still occupies the
+ * space it draws and the rails still resolve. Verified against the group: at
+ * 1.4 all four rows keep identical rail edges, because subgrid tracks and the
+ * zoom that reads them are the same for every row.
+ */
 function rowSx(opts: {
   inGroup: boolean;
+  gutters: { drag: boolean; select: boolean };
+  metaColumns: number;
   pad: number;
   padY: number;
+  scale: number;
   divider: boolean;
   interactive: boolean;
   draggable: boolean;
 }): Record<string, unknown> {
-  const { inGroup, pad, padY, divider, interactive, draggable } = opts;
+  const { inGroup, gutters, metaColumns, pad, padY, scale, divider, interactive, draggable } = opts;
   return {
     position: "relative",
+    borderRadius: CARD_RADIUS,
     display: "grid",
+    zoom: scale,
     // SUBGRID AND `container-type` CANNOT COEXIST on one element: containment
     // makes the box size independently of its parent, so the browser drops the
     // subgrid and every slot stacks into one column. (Observed exactly that —
@@ -193,12 +169,15 @@ function rowSx(opts: {
     // subgrid; standalone, the row is both the container and its own grid.
     ...(inGroup
       ? { gridColumn: `span ${RAIL_COUNT}`, gridTemplateColumns: "subgrid" }
-      : { containerType: "inline-size", gridTemplateColumns: STANDALONE_RAILS }),
+      : {
+          containerType: "inline-size",
+          gridTemplateColumns: railsTemplateFor(gutters, metaColumns),
+        }),
     alignItems: "center",
     // Wide enough that the meta cluster, the value and the status read as three
     // columns rather than one run of text — the complaint that started all this
     // was `MÉTODO PIX R$ 13,90` scanning as a single phrase.
-    columnGap: 3,
+    columnGap: RAIL_GAP,
     width: "100%",
     px: pad,
     py: padY,
@@ -248,6 +227,31 @@ function rowSx(opts: {
  *
  * A SHELL, like {@link BaseCard}. Domain rows live in the app and compose it.
  */
+/**
+ * The id this row drags under, or nothing.
+ *
+ * `undefined` is the inert answer: `useDragItem` treats a missing id as "no
+ * drag", which is how the card's own veto (`draggable={false}`) and an
+ * unactionable record both switch dragging off without the card knowing
+ * anything about the container above it.
+ */
+function dragIdFor(
+  props: BaseListCardProps,
+  actionable: boolean,
+): string | number | undefined {
+  return props.draggable === false || !actionable ? undefined : props.dragId;
+}
+
+/**
+ * What the meta cluster amounts to — asked once, used three times: to size the
+ * rail, to close the cluster with a rule, and to decide whether the value has
+ * anything to be divided FROM.
+ */
+function metaShape(props: BaseListCardProps): { columns: number; present: boolean } {
+  const columns = props.meta?.length ?? 0;
+  return { columns, present: columns > 0 || props.metaSlot != null };
+}
+
 /**
  * Everything the row derives before it can render — extracted so the component
  * stays inside the size budget.
@@ -263,9 +267,18 @@ function useRowShell(props: BaseListCardProps) {
     theme: useTheme(),
     selectable: isSelectable(props),
     slot: slotTestIds(props.testId),
-    drag: useDragItem(props.draggable === false || !actionable ? undefined : props.dragId),
-    pad: 1.5 * scale,
-    padY: DENSITY_ROW_PADDING[group?.density ?? props.density ?? "cozy"] * scale,
+    drag: useDragItem(dragIdFor(props, actionable)),
+    // Standalone holds no gutter open: there is no list beside it to line up
+    // with, so a reserved-but-empty rail is pure inset.
+    reserve: group?.reserveGutters ?? false,
+    // 1, not 1.5. The row's contents still have to line up with the toolbar
+    // above them, but 12px of card padding stacked on the checkbox's own 9px
+    // and an empty drag gutter's 24px read as a row indented for no reason.
+    //
+    // Not multiplied by `scale` — the row's `zoom` already scales it, and doing
+    // both would square the factor on padding alone.
+    pad: 1,
+    padY: DENSITY_ROW_PADDING[group?.density ?? props.density ?? "cozy"],
     // A card that navigates does so with a real anchor, so it takes no click
     // handler of its own — the stretched link IS the target.
     acts: props.onClick != null && props.href == null && actionable,
@@ -285,15 +298,45 @@ function actionProps(onClick: (() => void) | undefined) {
   };
 }
 
+/** The surface and the geometry, merged — the row's whole `sx` in one place. */
+function rowStyles(
+  props: BaseListCardProps,
+  shell: ReturnType<typeof useRowShell>,
+): Record<string, unknown> {
+  const { group, theme, selectable, drag, reserve, pad, padY, scale, acts } = shell;
+  return {
+    ...cardSurfaceStyles(
+      {
+        ...props,
+        selectable,
+        shape: "row",
+        state: drag.dragging ? "disabled" : props.state,
+      },
+      theme,
+    ),
+    ...rowSx({
+      inGroup: group !== null,
+      gutters: { drag: reserve || drag.draggable, select: reserve || selectable },
+      metaColumns: metaShape(props).columns,
+      pad,
+      padY,
+      scale,
+      divider: props.divider ?? false,
+      interactive: acts || props.href != null,
+      draggable: drag.draggable && drag.handleProps === undefined,
+    }),
+  };
+}
+
 export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
-  const { selected = false, divider = false, href, onClick } = props;
-  const { group, actionable, scale, theme, selectable, slot, drag, pad, padY, acts } =
-    useRowShell(props);
+  const { selected = false, href, onClick } = props;
+  const shell = useRowShell(props);
+  const { actionable, selectable, slot, drag, reserve, pad, acts } = shell;
+  const meta = metaShape(props);
 
   return (
     <Card
       variant="outlined"
-      borderRadius="lg"
       className={props.className}
       dataTestId={props.testId}
       aria-label={props["aria-label"]}
@@ -302,22 +345,13 @@ export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
       {...(acts ? actionProps(onClick) : {})}
       {...drag.itemProps}
       // A PLAIN OBJECT: `Card` merges by spreading, so a function sx vanishes.
-      sx={{
-        ...cardSurfaceStyles({ ...props, selectable, shape: "row", state: drag.dragging ? "disabled" : props.state }, theme),
-        ...rowSx({
-          inGroup: group !== null,
-          pad,
-          padY,
-          divider,
-          interactive: acts || href != null,
-          draggable: drag.draggable && drag.handleProps === undefined,
-        }),
-      }}
+      sx={rowStyles(props, shell)}
     >
-      <DragSlot drag={drag} testId={slot("drag")} />
+      <DragSlot drag={drag} reserve={reserve} testId={slot("drag")} />
       <SelectSlot
         selectable={selectable}
         selected={selected}
+        reserve={reserve}
         onToggleSelect={props.onToggleSelect}
         testId={slot("checkbox")}
       />
@@ -329,17 +363,20 @@ export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
         subtitle={props.subtitle}
         href={href}
         target={props.target}
-        scale={scale}
         testId={slot("title")}
       />
-      <ListCardMeta meta={props.meta} metaSlot={props.metaSlot} />
+      <ListCardMeta
+        meta={props.meta}
+        metaSlot={props.metaSlot}
+        trailingRule={props.value != null}
+      />
       <ListCardTail
         value={props.value}
+        separated={meta.present}
         status={props.status}
         actions={actionable ? props.actions : undefined}
         actionsAlwaysVisible={props.actionsAlwaysVisible}
         menu={props.menu}
-        scale={scale}
         testId={slot}
       />
       {props.children != null && (

package/src/components/data-display/DataViews/card-surface.ts

@@ -125,6 +125,20 @@ export interface CardSurfaceProps {
   "aria-label"?: string;
 }
 
+/**
+ * ONE RADIUS FOR BOTH SHAPES, off the token scale on purpose.
+ *
+ * `Card`'s own steps are 4px and 8px and its `lg` is 16px, all chosen for a
+ * surface nearly as tall as it is wide. A 56px row is not that shape — the
+ * corner runs most of the way down both ends and curves away from the square
+ * checkbox and square thumbnail inside it — and a tile that rounds harder than
+ * the row it sits beside in the same view reads as a different component.
+ *
+ * 3px takes the hard point off the corner without being seen as a curve.
+ * `divider` rows override it back to 0; a bottom rule has no corners to round.
+ */
+export const CARD_RADIUS = "3px";
+
 /** Every slot's test id, derived from the card's one. */
 export function slotTestIds(testId: string | undefined): (slot: string) => string | undefined {
   return (slot) => (testId ? `${testId}-${slot}` : undefined);
@@ -150,7 +164,7 @@ export function isActionable(state: CardState | undefined): boolean {
  * draw. Ghost is "a surface, quietly"; text is "no surface at all", which is
  * what a host wants when it is drawing the container itself.
  */
-function variantSx(variant: CardSurfaceVariant): CardSx {
+function variantSx(variant: CardSurfaceVariant, theme: Theme): CardSx {
   if (variant === "ghost") {
     return {
       border: 0,
@@ -162,10 +176,26 @@ function variantSx(variant: CardSurfaceVariant): CardSx {
     return { border: 0, backgroundColor: "transparent", boxShadow: "none" };
   }
   if (variant === "glass") {
+    // THEME-AWARE, and it keeps its edges.
+    //
+    // This was a hardcoded `rgba(255,255,255,·)` fill with a near-white border,
+    // which had two problems. On a dark palette a 55%-white pane is not frosted
+    // glass, it is a pale rectangle. And on a light one BOTH the fill and the
+    // border land on white and vanish, so `glass` rendered as `text` — the same
+    // nothing, reached by a different name.
+    //
+    // The blur is what makes it glass, and a blur is only visible over
+    // something. So the pane keeps a real hairline and a shallow shadow: over a
+    // plain surface it still reads as a raised pane rather than as absence, and
+    // over an image or a gradient the blur does the rest.
     return {
-      backgroundColor: "rgba(255,255,255,0.55)",
+      backgroundColor: alpha(theme.palette.background.paper, 0.55),
       backdropFilter: "blur(8px)",
-      borderColor: "rgba(255,255,255,0.35)",
+      // `divider` as-is. NOT `alpha(divider, …)`: MUI's `alpha` REPLACES the
+      // channel rather than scaling it, and `divider` is already a 12% black —
+      // so asking for 80% of it produced an 80% black slab of a border.
+      borderColor: theme.palette.divider,
+      boxShadow: `0 1px 3px ${alpha(theme.palette.common.black, 0.1)}`,
     };
   }
   return {};
@@ -210,13 +240,28 @@ function accentBar(main: string): CardSx {
 }
 
 /**
- * The tile's halo. Button's glow, kept for `BaseCard` — a grid of tiles has gaps
- * around each card, so the spread has somewhere to go that a row does not.
+ * The tile's lift — a card that has been RAISED, not one that is lit from within.
+ *
+ * This was Button's glow: a 20px bloom at 0.6 over a 40px bloom at 0.3, plus
+ * `brightness(1.05)`. On a button, which is small and pressed and gone, that
+ * reads as energy. On a tile it read as a neon sign — 40px of saturated colour
+ * bleeding into the gaps of a grid whose whole job is to let the eye compare
+ * cards, and the brightness filter washing the image and the caption with it.
+ *
+ * Three shadows doing three jobs instead: a hairline ring that tints the card's
+ * own edge in the accent colour, a tight contact shadow, and one soft shadow
+ * offset DOWNWARD. Offset is what separates elevation from emission — a glow is
+ * symmetrical because its source is the object; a shadow falls because the
+ * light is somewhere else. It stays legible on a dark canvas, where the old
+ * bloom was the brightest thing on the screen.
  */
-function glowSx(main: string): CardSx {
+function liftSx(main: string): CardSx {
   return {
-    boxShadow: `0 0 20px 5px ${alpha(main, 0.6)}, 0 0 40px 10px ${alpha(main, 0.3)}`,
-    filter: "brightness(1.05)",
+    boxShadow: [
+      `0 0 0 1px ${alpha(main, 0.45)}`,
+      `0 1px 2px ${alpha(main, 0.12)}`,
+      `0 8px 20px -6px ${alpha(main, 0.3)}`,
+    ].join(", "),
   };
 }
 
@@ -251,10 +296,10 @@ function pulseSx(main: string): CardSx {
 /** The emphasis treatments, in the terms the shape can actually carry. */
 function emphasisSx(emphasis: CardEmphasis, main: string, shape: CardShape): CardSx {
   if (emphasis === "attention") {
-    // The bar on both; the halo only where there is room for it to spread.
+    // The bar on both; the lift only where there is room for it to spread.
     return {
       ...accentBar(main),
-      ...(shape === "tile" ? glowSx(main) : {}),
+      ...(shape === "tile" ? liftSx(main) : {}),
       ...pulseSx(main),
     };
   }
@@ -271,6 +316,42 @@ function emphasisSx(emphasis: CardEmphasis, main: string, shape: CardShape): Car
  * The shared half of a card's styling. Each component adds its own geometry —
  * a tile's aspect ratio, a row's rails.
  */
+/**
+ * WHAT THE TWO NON-DEFAULT STATES LOOK LIKE — and why they cannot look alike.
+ *
+ * Both were `opacity: 0.6` and nothing else, so a record the business CANCELLED
+ * and a row this user merely cannot touch were pixel-identical. The type has
+ * always drawn the distinction (`CardState`); only the styling had not, which
+ * made `cancelled` a comment rather than a state.
+ *
+ * `cancelled` is a VOIDED record: still there, still worth reading, no longer
+ * counting. The figures get struck through, because a dimmed `R$ 1.250,00`
+ * still reads as money owed and a struck one cannot.
+ *
+ * `disabled` is INERT: nothing to read into, nothing to do with. It goes
+ * greyscale — which also drains the status chip's colour, the one thing on the
+ * row still shouting for attention — and says so on hover.
+ */
+function stateSx(state: CardState): CardSx {
+  if (state === "cancelled") {
+    return {
+      opacity: 0.65,
+      // The META CLUSTER is struck too. It was left out, so a voided row kept a
+      // crisp `05/08/2026, 13:45` and `PIX` between a struck title and a struck
+      // total — the middle of the row reading as live data on a record the two
+      // ends call void. Both lines of each pair go, as both lines of the caption
+      // already do: on a cancelled record the label is as void as the value.
+      '& [data-slot="value"], & [data-slot="caption"], & [data-slot="meta"]': {
+        textDecoration: "line-through",
+      },
+    };
+  }
+  if (state === "disabled") {
+    return { opacity: 0.45, filter: "grayscale(1)", cursor: "not-allowed" };
+  }
+  return { opacity: 1 };
+}
+
 export function cardSurfaceStyles(
   props: CardSurfaceProps & { selectable: boolean; shape: CardShape },
   theme: Theme,
@@ -283,8 +364,8 @@ export function cardSurfaceStyles(
   const showSelected = selectable && selected;
   return {
     transition: "border-color 120ms, box-shadow 120ms, background-color 120ms",
-    opacity: state === "default" ? 1 : 0.6,
-    ...variantSx(variant),
+    ...stateSx(state),
+    ...variantSx(variant, theme),
     ...(showSelected
       ? {
           borderColor: `${color}.main`,

package/src/components/data-display/DataViews/list-card-rails.tsx

@@ -32,8 +32,9 @@ export interface ListRails {
   /** Reserved even when nothing is selectable, for the same reason. */
   select: string;
   leading: string;
-  /** The one column that absorbs spare width. */
+  /** Absorbs spare width, alongside `meta`. */
   caption: string;
+  /** Also absorbs spare width, so the middle columns spread rather than bunch. */
   meta: string;
   /** The value's own rail, with a fixed right edge. */
   value: string;
@@ -42,14 +43,56 @@ export interface ListRails {
   actions: string;
 }
 
-const DEFAULT_RAILS: ListRails = {
+/**
+ * The meta rail, sized to sit its pairs on even intervals WITH the caption.
+ *
+ * ONE SHARE OF THE SPARE WIDTH PER PAIR, not one for the cluster. A single `1fr`
+ * handed the whole cluster as much room as the title and then split it between
+ * the pairs, so the title sat on a full share while `DATA` and `MÉTODO` had half
+ * a share each — which is why the gap after the title came out twice the gap
+ * between the pairs. Even columns need even shares, so the rail grows with the
+ * number of pairs it has to hold.
+ *
+ * `max-content` still floors it: the evenness is never paid for with a clipped
+ * label on a row too narrow to afford it.
+ */
+export function metaRail(columns: number): string {
+  return `minmax(max-content, ${Math.max(columns, 1)}fr)`;
+}
+
+/**
+ * The caption and meta rails, resolved TOGETHER — because exactly one of them
+ * has to be the flexible track, and which one depends on whether the row has any
+ * middle columns at all.
+ *
+ * A grid distributes its free space to `fr` tracks; with no `fr` present it
+ * spreads it across every `auto` track instead — including the empty gutters,
+ * the empty meta rail and the empty status rail. So a row with a title and a
+ * value and nothing between them drifted its title into the middle of the row,
+ * each empty rail having claimed an equal share of the slack.
+ *
+ * With pairs to place, `meta` is the flexible one and the caption sizes to its
+ * title (the spare width belongs to the only rail with several things to space
+ * out). With no pairs, there is nothing to distribute and the caption takes the
+ * slack back, which is what it always did.
+ */
+export function contentRails(metaColumns: number): Pick<ListRails, "caption" | "meta"> {
+  return metaColumns > 0
+    ? { caption: "minmax(0, auto)", meta: metaRail(metaColumns) }
+    : { caption: "minmax(0, 1fr)", meta: "auto" };
+}
+
+export const DEFAULT_RAILS: ListRails = {
   drag: "auto",
   select: "auto",
   leading: "auto",
-  caption: "minmax(0, 1fr)",
-  meta: "auto",
+  // Two is the canonical row (a date and a method); a list carrying a different
+  // number says so with `metaColumns`, and a standalone card counts its own.
+  ...contentRails(2),
   // `max-content` on the value, so the rail is as wide as the widest amount in
   // the list and no wider — a fixed px guess is either clipping or dead space.
+  // NOT an `fr`: the value's whole promise is a fixed right edge, and a rail
+  // that grows with the spare width moves that edge on every list.
   value: "max-content",
   status: "max-content",
   actions: "auto",
@@ -68,8 +111,16 @@ export function useListRails(): ListRailsValue | null {
   return useContext(ListRailsContext);
 }
 
-/** The column template, as one `grid-template-columns` value. */
-export function railsTemplate(rails: ListRails): string {
+/**
+ * The column template, as one `grid-template-columns` value.
+ *
+ * A rail set to `null` is DROPPED rather than sized to zero. The two are not the
+ * same: a zero-width track still takes a `column-gap` beside it, so a gutter
+ * nobody is using still pushes the row's contents inward. Only a standalone card
+ * may drop one — inside a group the rails are subgrid over a shared template and
+ * every row must span the same count.
+ */
+export function railsTemplate(rails: RailOverrides): string {
   return [
     rails.drag,
     rails.select,
@@ -79,7 +130,50 @@ export function railsTemplate(rails: ListRails): string {
     rails.value,
     rails.status,
     rails.actions,
-  ].join(" ");
+  ]
+    .filter((rail): rail is string => rail != null)
+    .join(" ");
+}
+
+/** A rail set, where `null` means "this rail is not in the template at all". */
+type RailOverrides = { [K in keyof ListRails]: ListRails[K] | null };
+
+/** The gap between rails, in theme spacing units. */
+export const RAIL_GAP = 3;
+
+/** …the same gap in pixels, for anything drawing INTO it. */
+export const RAIL_GAP_PX = RAIL_GAP * 8;
+
+/**
+ * AN EMPTY GUTTER COSTS ITS OWN WIDTH *AND* THE RAIL GAP BESIDE IT.
+ *
+ * A zero-width grid track still gets a `column-gap`, and no margin on the item
+ * inside it can win that back — gaps sit between TRACKS, and a track's position
+ * is settled before any item's margin is applied. (Tried it; the box simply
+ * overhangs its own track and everything after it stays put.) So a row with
+ * nothing to drag was paying 24px for a rail holding nothing, which was the
+ * single biggest contributor to the left inset the checkbox appeared to have.
+ *
+ * The only way out is for the track NOT TO EXIST: the slot renders nothing and
+ * the rail leaves the template, which is safe because grid auto-placement fills
+ * the remaining tracks in DOM order. Standalone only — inside a
+ * {@link ListCardGroup} the rails are subgrid across a shared template and the
+ * count cannot vary per row, which is also where `reserveGutters` earns its
+ * keep: a selectable list and a read-only one still line up, and turning drag
+ * mode on does not shift every row sideways.
+ */
+export function railsTemplateFor(
+  gutters: { drag: boolean; select: boolean },
+  metaColumns: number,
+): string {
+  return railsTemplate({
+    ...DEFAULT_RAILS,
+    // Standalone, the card can simply COUNT its pairs — no `metaColumns` to be
+    // told, and no guess.
+    ...contentRails(metaColumns),
+    ...(gutters.drag ? {} : { drag: null }),
+    ...(gutters.select ? {} : { select: null }),
+  });
 }
 
 /** How many rails there are — the span a card claims. */
@@ -97,6 +191,7 @@ export const RAIL_COUNT = 8;
 export function ListCardGroup({
   children,
   density = "cozy",
+  metaColumns,
   rails,
   reserveGutters = true,
   gap,
@@ -104,6 +199,15 @@ export function ListCardGroup({
 }: {
   children: ReactNode;
   density?: DataViewsDensity;
+  /**
+   * How many labelled pairs the rows in this list carry.
+   *
+   * The rail claims one share of the spare width per pair, so the title and
+   * every pair land on even intervals. A list is homogeneous — its rows show
+   * the same fields — but the group renders its children opaquely and cannot
+   * count them, so this is the one thing it has to be told.
+   */
+  metaColumns?: number;
   /** Override individual rails; anything omitted keeps its default. */
   rails?: Partial<ListRails>;
   /**
@@ -117,7 +221,11 @@ export function ListCardGroup({
   gap?: number;
   dataTestId?: string;
 }): React.JSX.Element {
-  const resolved = { ...DEFAULT_RAILS, ...rails };
+  const resolved = {
+    ...DEFAULT_RAILS,
+    ...(metaColumns == null ? {} : contentRails(metaColumns)),
+    ...rails,
+  };
   return (
     <ListRailsContext.Provider value={{ density, reserveGutters }}>
       <Box

package/src/components/form/Button/Button.styles.ts

@@ -61,14 +61,49 @@ export const getColorFromTheme = (theme: Theme, color: string): ColorPalette =>
   };
 };
 
-export const SIZE_MAP: Record<string, CSSObject> = {
+/** What an unrecognised size falls back to, named so indexing can never be undefined. */
+const DEFAULT_SIZE: CSSObject = { padding: '8px 16px', fontSize: '1rem' };
+
+const SIZE_MAP: Record<string, CSSObject> = {
   xs: { padding: '2px 8px', fontSize: '0.75rem' },
   sm: { padding: '6px 12px', fontSize: '0.875rem' },
-  md: { padding: '8px 16px', fontSize: '1rem' },
+  md: DEFAULT_SIZE,
   lg: { padding: '10px 20px', fontSize: '1.125rem' },
   xl: { padding: '12px 24px', fontSize: '1.25rem' },
 };
 
+/**
+ * A BUTTON THAT IS ONLY AN ICON IS SQUARE.
+ *
+ * MUI puts a 64px `min-width` on every button, which is right for a label and
+ * wrong for a glyph: three dots in a 64px slab reads as a button that failed to
+ * load its text, and at the end of a dense row it claims space the row needs.
+ * The horizontal padding goes too — a square of padding round a square glyph —
+ * and so does the gap MUI reserves beside a start/end icon, since there is
+ * nothing on the other side of it.
+ *
+ * Derived, not declared: a button with an `icon` and no children can only be an
+ * icon button, so no consumer has to opt in and none can forget to.
+ */
+const ICON_ONLY_PADDING: Record<string, string> = {
+  xs: '2px',
+  sm: '5px',
+  md: '7px',
+  lg: '9px',
+  xl: '11px',
+};
+
+const iconOnlySize = (size: string): CSSObject => ({
+  minWidth: 0,
+  padding: ICON_ONLY_PADDING[size] ?? ICON_ONLY_PADDING.md,
+  fontSize: SIZE_MAP[size]?.fontSize ?? DEFAULT_SIZE.fontSize,
+  '& .MuiButton-startIcon, & .MuiButton-endIcon': { margin: 0 },
+});
+
+/** The size styles for a button, square when it carries nothing but an icon. */
+export const buttonSize = (size: string, iconOnly: boolean): CSSObject =>
+  iconOnly ? iconOnlySize(size) : (SIZE_MAP[size] ?? DEFAULT_SIZE);
+
 /**
  * MUI centres icons with a negative margin that fights our own padding, so the
  * flex alignment is restated here rather than fought with `!important`.

package/src/components/form/Button/Button.tsx

@@ -8,7 +8,7 @@ import {
   buttonVariantStyles,
   getColorFromTheme,
   iconAlignmentStyles,
-  SIZE_MAP,
+  buttonSize,
 } from './Button.styles';
 import type { ButtonProps } from './Button.types';
 
@@ -53,6 +53,22 @@ const muiColorFor = (color: NonNullable<ButtonProps['color']>): MuiButtonColor =
   return color === 'neutral' ? 'inherit' : color;
 };
 
+/**
+ * An icon and nothing else — the shape that should render square.
+ *
+ * A separate predicate rather than three clauses inline: the component function
+ * is already at the complexity ceiling, and "what counts as an icon button" is
+ * a rule worth naming anyway. `loading` disqualifies, because a spinner
+ * replaces the children and would otherwise make every loading button square.
+ */
+function isIconOnly({
+  loading,
+  icon,
+  children,
+}: Pick<ButtonProps, 'loading' | 'icon' | 'children'>): boolean {
+  return !loading && icon != null && children == null;
+}
+
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
   (rawProps, ref) => {
     const {
@@ -81,6 +97,9 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
     const iconWithTestId =
       !loading && icon ? <span data-testid={testId('icon')}>{icon}</span> : undefined;
 
+    // Only an icon, so the button is a square rather than a 64px slab.
+    const iconOnly = isIconOnly({ loading, icon, children });
+
     const mergedClassName =
       [active ? 'active' : '', props.className].filter(Boolean).join(' ') || undefined;
 
@@ -101,7 +120,7 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
         onClick={onClick}
         onFocus={onFocus}
         onBlur={onBlur}
-        sx={SIZE_MAP[size]}
+        sx={buttonSize(size, iconOnly)}
         data-testid={dataTestId || 'button'}
         {...props}
         className={mergedClassName}