@sovereignfs/ui 0.45.0 → 0.83.1

package/src/components/Badge/Badge.module.css

@@ -19,7 +19,7 @@
 /* role — neutral fill, border */
 .role {
   background: var(--sv-color-surface-sunken);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   color: var(--sv-color-text-primary);
   font-weight: var(--sv-font-weight-semibold);
 }
@@ -31,32 +31,32 @@
 
 .chipGreen {
   background: var(--sv-color-success-surface);
-  border: 1px solid var(--sv-color-success-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-success-border);
   color: var(--sv-color-success-text);
 }
 
 .chipAmber {
   background: var(--sv-color-warning-surface);
-  border: 1px solid var(--sv-color-warning-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-warning-border);
   color: var(--sv-color-warning-text);
 }
 
 .chipRed {
   background: var(--sv-color-error-surface);
-  border: 1px solid var(--sv-color-error-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-error-border);
   color: var(--sv-color-error-text);
 }
 
 .chipNeutral {
   background: var(--sv-color-surface-sunken);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   color: var(--sv-color-text-muted);
 }
 
 /* mono — monospace font, neutral surface, for type tags / versions */
 .mono {
   background: var(--sv-color-surface-sunken);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   color: var(--sv-color-text-muted);
   font-family: var(--sv-font-family-mono);
 }
@@ -66,7 +66,15 @@
    composed partials fighting over the same properties. `.role.md`,
    `.status.md`, and `.mono.md` reproduce the badge's original (and, until
    now, only) sizing exactly, so the default (no `size` prop) renders
-   pixel-identical to before this scale existed. */
+   pixel-identical to before this scale existed. `xs` was added later, for a
+   badge sitting inline next to larger text where `sm` (already the smallest
+   type-scale token, `--sv-font-size-label`) still read oversized — it needed
+   a new, smaller primitive (`--sv-font-size-2xs`) rather than reusing one. */
+.role.xs {
+  padding: 1px 3px;
+  font-size: var(--sv-font-size-2xs);
+}
+
 .role.sm {
   padding: 1px var(--sv-space-1);
   font-size: var(--sv-font-size-label);
@@ -82,6 +90,11 @@
   font-size: var(--sv-font-size-sm);
 }
 
+.mono.xs {
+  padding: 1px 3px;
+  font-size: var(--sv-font-size-2xs);
+}
+
 .mono.sm {
   padding: 1px var(--sv-space-1);
   font-size: var(--sv-font-size-label);
@@ -100,6 +113,11 @@
 /* status keeps a tighter left edge than right at every size — the dot +
    gap already read as space before the text, so a full padding-inline-start
    would double it up. */
+.status.xs {
+  padding: 1px 3px 1px 2px;
+  font-size: var(--sv-font-size-2xs);
+}
+
 .status.sm {
   padding: 1px var(--sv-space-1) 1px 3px;
   font-size: var(--sv-font-size-label);
@@ -122,6 +140,11 @@
   flex-shrink: 0;
 }
 
+.xs .dot {
+  width: 4px;
+  height: 4px;
+}
+
 .sm .dot {
   width: 5px;
   height: 5px;

package/src/components/Badge/Badge.stories.tsx

@@ -10,13 +10,13 @@ const meta = {
     docs: {
       description: {
         component:
-          'Compact label for roles (`role`), lifecycle states (`status`), and type/version tags (`mono`). Three sizes (`sm`/`md`/`lg`); ALL CAPS by default, or set `uppercase={false}` for title case. RSC-safe — no state.',
+          'Compact label for roles (`role`), lifecycle states (`status`), and type/version tags (`mono`). Four sizes (`xs`/`sm`/`md`/`lg`); ALL CAPS by default, or set `uppercase={false}` for title case. RSC-safe — no state.',
       },
     },
   },
   argTypes: {
     variant: { control: 'select', options: ['role', 'status', 'mono'] },
-    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    size: { control: 'select', options: ['xs', 'sm', 'md', 'lg'] },
     status: {
       control: 'select',
       options: ['active', 'enabled', 'deactivated', 'failed', 'invited', 'pending', 'neutral'],
@@ -56,7 +56,7 @@ export const MonoPlatform: Story = { args: { variant: 'mono', children: 'platfor
 export const MonoCommunity: Story = { args: { variant: 'mono', children: 'community' } };
 export const MonoVersion: Story = { args: { variant: 'mono', children: 'v0.1.0' } };
 
-/** sm / md (default) / lg side by side, across all three variants. */
+/** xs / sm / md (default) / lg side by side, across all three variants. */
 export const Sizes: Story = {
   render: () => {
     const rowStyle: React.CSSProperties = { display: 'flex', alignItems: 'center', gap: 8 };
@@ -65,6 +65,9 @@ export const Sizes: Story = {
       <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
         <div style={sectionStyle}>
           <div style={rowStyle}>
+            <Badge variant="role" size="xs">
+              Owner
+            </Badge>
             <Badge variant="role" size="sm">
               Owner
             </Badge>
@@ -76,6 +79,9 @@ export const Sizes: Story = {
             </Badge>
           </div>
           <div style={rowStyle}>
+            <Badge variant="status" status="active" size="xs">
+              Active
+            </Badge>
             <Badge variant="status" status="active" size="sm">
               Active
             </Badge>
@@ -87,6 +93,9 @@ export const Sizes: Story = {
             </Badge>
           </div>
           <div style={rowStyle}>
+            <Badge variant="mono" size="xs">
+              v0.1.0
+            </Badge>
             <Badge variant="mono" size="sm">
               v0.1.0
             </Badge>
@@ -193,8 +202,11 @@ export const AllVariants: Story = {
           </div>
         </div>
         <div style={sectionStyle}>
-          <span style={headingStyle}>Sizes (sm / md / lg)</span>
+          <span style={headingStyle}>Sizes (xs / sm / md / lg)</span>
           <div style={{ ...groupStyle, alignItems: 'center' }}>
+            <Badge variant="role" size="xs">
+              Owner
+            </Badge>
             <Badge variant="role" size="sm">
               Owner
             </Badge>

package/src/components/Badge/Badge.tsx

@@ -2,20 +2,17 @@ import type { ReactNode } from 'react';
 import styles from './Badge.module.css';
 
 export type BadgeVariant = 'role' | 'status' | 'mono';
-export type BadgeSize = 'sm' | 'md' | 'lg';
+export type BadgeSize = 'xs' | 'sm' | 'md' | 'lg';
 export type BadgeStatus =
-  | 'active'
-  | 'enabled'
-  | 'deactivated'
-  | 'failed'
-  | 'invited'
-  | 'pending'
-  | 'neutral';
+  'active' | 'enabled' | 'deactivated' | 'failed' | 'invited' | 'pending' | 'neutral';
 
 export interface BadgeProps {
   variant?: BadgeVariant;
-  /** 'sm' | 'md' (default) | 'lg'. 'md' is the badge's original — and until
-   * now, only — size, so the default renders unchanged. */
+  /** 'xs' | 'sm' | 'md' (default) | 'lg'. 'md' is the badge's original — and
+   * until now, only — size, so the default renders unchanged. 'xs' is the
+   * smallest tier (`--sv-font-size-2xs`, 10px) — for a badge sitting inline
+   * next to larger text (e.g. a status chip beside a card's headline value)
+   * where even 'sm' still reads oversized next to it. */
   size?: BadgeSize;
   /** Only relevant when variant="status" — determines the dot colour. */
   status?: BadgeStatus;
@@ -54,7 +51,7 @@ const STATUS_CHIP_CLASS: Record<BadgeStatus, string> = {
  * - `status` tinted chip with leading colour dot — for Active / Deactivated / etc.
  * - `mono`   monospace font, neutral surface — for platform / community / v0.1.0
  *
- * Three sizes (`sm`/`md`/`lg`, default `md`). ALL CAPS by default
+ * Four sizes (`xs`/`sm`/`md`/`lg`, default `md`). ALL CAPS by default
  * (`uppercase`) — set `uppercase={false}` for a title-case badge instead.
  */
 export function Badge({

package/src/components/Badge/__tests__/Badge.test.tsx

@@ -69,8 +69,10 @@ describe('Badge', () => {
     expect(screen.getByText('Admin').closest('span')?.className).toContain('md');
   });
 
-  it('applies sm and lg size classes', () => {
-    const { rerender } = render(<Badge size="sm">Admin</Badge>);
+  it('applies xs, sm, and lg size classes', () => {
+    const { rerender } = render(<Badge size="xs">Admin</Badge>);
+    expect(screen.getByText('Admin').closest('span')?.className).toContain('xs');
+    rerender(<Badge size="sm">Admin</Badge>);
     expect(screen.getByText('Admin').closest('span')?.className).toContain('sm');
     rerender(<Badge size="lg">Admin</Badge>);
     expect(screen.getByText('Admin').closest('span')?.className).toContain('lg');

package/src/components/BalanceChip/BalanceChip.module.css

@@ -4,7 +4,7 @@
   max-width: 100%;
   min-height: 24px;
   padding: 2px var(--sv-space-2);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-full);
   font-family: var(--sv-font-family);
   font-size: var(--sv-font-size-xs);

package/src/components/Button/Button.module.css

@@ -3,7 +3,7 @@
   align-items: center;
   justify-content: center;
   gap: var(--sv-space-2);
-  border: 1px solid transparent;
+  border: var(--sv-border-width-hairline) solid transparent;
   border-radius: var(--sv-radius-md);
   font-family: var(--sv-font-family);
   font-weight: var(--sv-font-weight-medium);
@@ -12,10 +12,15 @@
   /* Removes the ~300ms double-tap-to-zoom delay on touch — this is a tap
      target, never a pinch-zoom surface. */
   touch-action: manipulation;
+  /* --sv-button-shadow defaults to `none` (semantic.css) — this box-shadow
+     line is a no-op for every theme that doesn't set it (RFC 0094). */
+  box-shadow: var(--sv-button-shadow);
   transition:
     background-color 0.15s ease,
     border-color 0.15s ease,
-    color 0.15s ease;
+    color 0.15s ease,
+    transform 0.1s ease,
+    box-shadow 0.1s ease;
 }
 
 .button:focus-visible {
@@ -28,6 +33,17 @@
   cursor: not-allowed;
 }
 
+/* --sv-button-press-x/-y default to 0 (semantic.css) — translate(0, 0) is a
+   no-op, so this rule only produces a visible "press into shadow" effect
+   for a theme preset that sets non-zero values (RFC 0094). Unguarded by
+   (hover: hover) deliberately: :active press feedback is wanted on every
+   input type, the same reasoning documented for Button's existing
+   color-mix() :active background changes below. */
+.button:active:not(:disabled) {
+  transform: translate(var(--sv-button-press-x), var(--sv-button-press-y));
+  box-shadow: none;
+}
+
 /* Touch target: gated to (pointer: coarse) — the *primary* pointer, not
    (any-pointer: coarse) — so a touchscreen laptop with mouse/trackpad as
    primary keeps desktop density (see mobile design-system plan, Part 4 #5). */

package/src/components/Card/Card.module.css

@@ -6,7 +6,7 @@
    exists. */
 .card {
   background: var(--sv-color-surface-raised);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-lg);
   box-shadow: var(--sv-shadow-card);
 }

package/src/components/CardTile/CardTile.module.css

@@ -0,0 +1,181 @@
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--sv-card-tile-min-width, 200px), 1fr));
+  gap: var(--sv-space-4);
+}
+
+/* A fixed column width (not `1fr`, and — as important — not `max-content`
+   either) — every real consumer of `dense` mode (Docs' folder/document
+   tiles, this file's own Storybook gallery) pairs it with `variant="icon"`
+   tiles carrying a name of unpredictable length that must ellipsis-truncate
+   past a point. `max-content` was tried first, on the reasoning that "a
+   tile keeps its own natural width instead of stretching to fill leftover
+   row space, so the empty area around a small icon tile stays roughly
+   square" — but `max-content` track sizing through this grid's nested
+   grid → flex → block(/inline-block) → text chain did not reliably account
+   for a descendant label's true content width in practice: measured live,
+   a 110px-wide label landed in a track that resolved to 97px, silently
+   overflowing with no ellipsis ever triggering (not the intended "grows to
+   fit," and not truncated either — just broken). A uniform fixed width
+   sidesteps that whole class of bug: every tile in a `dense` grid is
+   exactly `--sv-card-tile-min-width` wide, full stop, and the descendant
+   label (an `overflow: hidden; text-overflow: ellipsis` `inline-block` with
+   `max-width: 100%`) truncates reliably against that always-known width —
+   short names still read as compact/square, long ones truncate cleanly
+   instead of bleeding past their tile. Tighter gap to match. */
+.gridDense {
+  grid-template-columns: repeat(auto-fill, var(--sv-card-tile-min-width, 200px));
+  gap: var(--sv-space-2);
+}
+
+/* Chrome (border/radius/shadow/background) lives on this outer box, same
+   tokens `Card` itself uses — but padding-free, so `.banner` below can
+   bleed all the way to the edges, which `Card`'s single padded box can't
+   do. */
+.tile {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow: hidden;
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  background: var(--sv-color-surface-raised);
+  box-shadow: var(--sv-shadow-card);
+}
+
+.banner {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 40px;
+  color: var(--sv-color-text-subtle);
+  /* Neutral default when no `bannerColor` is supplied — an inline style
+     on the element overrides this. */
+  background-color: var(--sv-color-surface-sunken);
+}
+
+.footer {
+  padding: var(--sv-space-3) var(--sv-space-4);
+}
+
+/* `variant="icon"` modifier — a plain "Finder icon" tile: no card chrome,
+   just a large centered icon with a label beneath it. `.banner`/`.footer`
+   are the same two elements the card variant uses, restyled here rather
+   than duplicated, so both variants stay structurally identical. */
+.tileIcon {
+  align-items: center;
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: none;
+  box-shadow: none;
+  padding: var(--sv-space-3) var(--sv-space-2);
+}
+
+@media (hover: hover) {
+  .tileIcon:hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.tileIcon .banner {
+  height: auto;
+  background: none;
+  color: var(--sv-color-text-muted);
+}
+
+.tileIcon .banner svg {
+  width: 48px;
+  height: 48px;
+}
+
+/* `width: 100%` is load-bearing, not decorative — `.tile` sets
+   `align-items: center` (so the icon banner centers itself horizontally),
+   and cross-axis `center` alignment sizes a flex item to its own preferred
+   (content-based) width and centers *that* within the container, rather
+   than clamping it to the container's width the way `stretch` would.
+   Without an explicit width here, a `nowrap` + `text-overflow: ellipsis`
+   label inside (a consumer's own truncation CSS) keeps its full
+   content-driven preferred width and gets centered straddling both edges of
+   `.tile` — `overflow: hidden` on `.tile` doesn't help, since this child's
+   box is genuinely laid out wider than its own container, not merely
+   painting past an already-settled one. `min-width: 0` alone (the more
+   common flex-truncation fix) does NOT fix this specific case: that only
+   lifts the auto-min-size floor that blocks *shrinking under stretch*, and
+   this axis was never being stretched to begin with. Confirmed live at a
+   viewport narrow enough that `.tile`'s own resolved width is well under
+   the label's preferred width — only `width: 100%` actually constrains it;
+   a wider test viewport had accidentally masked the bug by giving `.tile`
+   enough natural room that the oversized `.footer` fit anyway. */
+.tileIcon .footer {
+  width: 100%;
+  min-width: 0;
+  padding: var(--sv-space-2) 0 0;
+  color: var(--sv-color-text-primary);
+  text-align: center;
+  text-decoration: none;
+}
+
+/* Plain centered placeholder — no banner strip, so a ghost "add new" tile
+   reads as an empty slot rather than mimicking a real tile's anatomy.
+   `min-height` matches a real `.tile`'s own natural height (banner +
+   single-line footer) so the two read as the same size. */
+.newTile {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sv-space-2);
+  min-height: 87px;
+  width: 100%;
+  height: 100%;
+  color: var(--sv-color-text-muted);
+  border: 1px dashed var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-lg);
+  background: none;
+  cursor: pointer;
+  transition:
+    border-color 0.15s ease,
+    color 0.15s ease;
+}
+
+@media (hover: hover) {
+  .newTile:hover {
+    border-color: var(--sv-color-text-muted);
+    color: var(--sv-color-text-primary);
+  }
+}
+
+.newTile:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+/* `variant="icon"` modifier — matches a `variant="icon"` `CardTile`'s own
+   footprint. Icon-only, no visible label (see `NewCardTile`'s own doc
+   comment) — a plain "+" at the DS's own `size="md"` (unlike
+   `.tileIcon .banner svg`'s real-content 48px override, deliberately not
+   repeated here) reads as self-explanatory once every sibling tile in the
+   grid is already an unlabeled icon.
+   `width`/`height: 100%` (not `auto`, despite this being a "shrink to
+   content" variant conceptually) — a real `CardTile` sibling in the same
+   `dense` grid fills its grid cell via the grid's own item-stretch, which
+   only reaches an `auto`-sized *direct* grid child; wrapping this trigger
+   in a `Menu`/`Popover` (`HomeWorkbooksList.tsx`'s "add workbook" tile)
+   inserts an intermediate `display: inline-flex` container between this
+   button and the grid, and a flex container's default cross/main-axis
+   sizing does not itself relay grid-stretch through to a `width: auto`
+   flex child — confirmed live: the button rendered full-height but only
+   as wide as its own icon+padding (~38px) inside a 160px cell. Explicit
+   100% percentages resolve against whichever immediate parent box is
+   sized to the grid cell — the grid track directly, or the intermediate
+   flex container once IT has already been stretched to that width — so
+   this works correctly either way, unlike relying on stretch alone. */
+.newTileIcon {
+  flex-direction: column;
+  justify-content: center;
+  gap: 0;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  padding: var(--sv-space-3) var(--sv-space-2);
+  border-radius: var(--sv-radius-md);
+}

package/src/components/CardTile/CardTile.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Icon } from '../Icon/Icon';
+import { CardTile, CardTileGrid, NewCardTile } from './CardTile';
+
+const meta = {
+  title: 'Components/CardTile',
+  component: CardTile,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'A colored/iconed banner over a footer label, used as a grid of navigable tiles (projects, boards, and similar top-level entities). Pair with `CardTileGrid` for layout and `NewCardTile` for the grid\'s "add new" affordance. Not link-aware — wrap a tile in the host framework\'s own link component to make it navigable.',
+      },
+    },
+  },
+  args: {
+    children: 'Q4 Planning',
+  },
+} satisfies Meta<typeof CardTile>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithBannerIcon: Story = {
+  args: {
+    banner: <Icon name="folder" size="lg" aria-hidden={true} />,
+    children: 'Q4 Planning',
+  },
+};
+
+export const WithBannerColor: Story = {
+  args: {
+    bannerColor: '#c7d8ff',
+    children: 'Marketing site',
+  },
+};
+
+export const Grid: Story = {
+  render: () => (
+    <CardTileGrid>
+      <CardTile banner={<Icon name="folder" size="lg" aria-hidden={true} />}>Q4 Planning</CardTile>
+      <CardTile bannerColor="#ffd8c7">Design reviews</CardTile>
+      <CardTile bannerColor="#c7ffd9">Onboarding</CardTile>
+      <NewCardTile label="New project" />
+    </CardTileGrid>
+  ),
+};
+
+/** `variant="icon"` — a plain "Finder icon" tile: no card chrome, just a large centered icon with a label beneath it. */
+export const IconVariant: Story = {
+  args: {
+    variant: 'icon',
+    banner: <Icon name="folder-closed" size="lg" aria-hidden={true} />,
+    children: 'Handbook',
+  },
+};
+
+/** `dense` — natural-width tiles (no stretch-to-fill) with a tighter gap, the pairing `variant="icon"` tiles normally want. `NewCardTile`'s own `variant="icon"` matches the same footprint, so the "add new" tile sits naturally alongside the rest instead of stretching into a wide pill. */
+export const IconVariantGrid: Story = {
+  render: () => (
+    <CardTileGrid dense minTileWidth={100}>
+      <CardTile variant="icon" banner={<Icon name="folder-closed" size="lg" aria-hidden={true} />}>
+        Handbook
+      </CardTile>
+      <CardTile variant="icon" banner={<Icon name="folder-closed" size="lg" aria-hidden={true} />}>
+        Q4 Planning
+      </CardTile>
+      <CardTile variant="icon" banner={<Icon name="folder-closed" size="lg" aria-hidden={true} />}>
+        Design reviews
+      </CardTile>
+      <NewCardTile variant="icon" label="New" />
+    </CardTileGrid>
+  ),
+};
+
+export const NewTile: StoryObj<typeof NewCardTile> = {
+  render: () => <NewCardTile label="New document" />,
+};
+
+/** `variant="icon"` — matches a `variant="icon"` `CardTile`'s footprint (icon above a short label) instead of the default horizontal pill. */
+export const NewTileIconVariant: StoryObj<typeof NewCardTile> = {
+  render: () => <NewCardTile variant="icon" label="New" />,
+};

package/src/components/CardTile/CardTile.tsx

@@ -0,0 +1,128 @@
+import type { ButtonHTMLAttributes, CSSProperties, HTMLAttributes, ReactNode } from 'react';
+import { Icon } from '../Icon/Icon';
+import type { IconName } from '../Icon/Icon';
+import styles from './CardTile.module.css';
+
+export interface CardTileGridProps {
+  children: ReactNode;
+  /** Minimum tile width (px) before the grid wraps to fewer columns. */
+  minTileWidth?: number;
+  className?: string;
+  /**
+   * Tight spacing with tiles that keep their natural width instead of
+   * stretching to fill the row — for small `variant="icon"` tiles (e.g. a
+   * folder grid), where the default grid's spacious gap and `1fr`-stretched
+   * columns leave a lot of empty space around a tile that's really just an
+   * icon + short label.
+   */
+  dense?: boolean;
+}
+
+/** Responsive grid of `CardTile`/`NewCardTile` children — `repeat(auto-fill, minmax(minTileWidth, 1fr))`, or `minmax(minTileWidth, max-content)` with a tighter gap when `dense`. */
+export function CardTileGrid({
+  children,
+  minTileWidth = 200,
+  className,
+  dense = false,
+}: CardTileGridProps) {
+  const style = { '--sv-card-tile-min-width': `${minTileWidth}px` } as CSSProperties;
+  return (
+    <div
+      className={[styles.grid, dense && styles.gridDense, className].filter(Boolean).join(' ')}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface CardTileProps extends HTMLAttributes<HTMLDivElement> {
+  /** Content centered in the tile's full-bleed top banner — typically an `<Icon>`. Omit for a plain strip. */
+  banner?: ReactNode;
+  /** Banner background color (applied inline). Falls back to a neutral sunken-surface strip when omitted. Ignored by `variant="icon"`, which has no banner box. */
+  bannerColor?: string;
+  /** Tile footer content — typically the item's name. */
+  children: ReactNode;
+  /**
+   * `"card"` (default): a bordered card with a colored/iconed banner strip
+   * over a footer label. `"icon"`: a plain "Finder icon" tile — no card
+   * chrome at all, just a large centered icon with a label beneath it. Use
+   * `"icon"` for entities that read as a single glyph + name (e.g. a
+   * folder), where a bordered card reads as heavier than the content needs.
+   */
+  variant?: 'card' | 'icon';
+}
+
+/**
+ * A colored/iconed banner over a footer label — a card shape `Card` can't
+ * express, since `Card`'s `padding` prop always pads its single box with no
+ * way for a top region to bleed to the edges. Not link-aware: wrap it in the
+ * host framework's own link component (e.g. Next's `<Link>`) to make it
+ * navigable, same as every existing consumer of this pattern does.
+ */
+export function CardTile({
+  banner,
+  bannerColor,
+  children,
+  className,
+  variant = 'card',
+  ...rest
+}: CardTileProps) {
+  const isIcon = variant === 'icon';
+  return (
+    <div
+      className={[styles.tile, isIcon && styles.tileIcon, className].filter(Boolean).join(' ')}
+      {...rest}
+    >
+      <div
+        className={styles.banner}
+        aria-hidden="true"
+        style={!isIcon && bannerColor ? { backgroundColor: bannerColor } : undefined}
+      >
+        {banner}
+      </div>
+      <div className={styles.footer}>{children}</div>
+    </div>
+  );
+}
+
+export interface NewCardTileProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Icon shown beside the label (`"card"`) or alone (`"icon"`). Defaults to `"plus"`. */
+  icon?: IconName;
+  /** Visible next to the icon for `"card"`. For `"icon"`, not rendered as text — used as the button's `aria-label` instead, since the tile is icon-only. */
+  label: string;
+  /**
+   * `"card"` (default): a dashed box matching a `variant="card"` `CardTile`'s
+   * footprint — icon beside a visible label. `"icon"`: matches a
+   * `variant="icon"` `CardTile`'s footprint instead, but icon-only, no
+   * visible label — a plain "+" reads as self-explanatory once every
+   * sibling tile in the same `dense` grid is already an unlabeled icon
+   * (the dashed border alone marks it as the "add new" affordance).
+   */
+  variant?: 'card' | 'icon';
+}
+
+/** Dashed ghost tile matching a real `CardTile`'s footprint — the grid's own "add new" affordance. */
+export function NewCardTile({
+  icon = 'plus',
+  label,
+  type = 'button',
+  variant = 'card',
+  className,
+  ...rest
+}: NewCardTileProps) {
+  const isIcon = variant === 'icon';
+  return (
+    <button
+      type={type}
+      className={[styles.newTile, isIcon && styles.newTileIcon, className]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+      aria-label={isIcon ? label : undefined}
+    >
+      <Icon name={icon} size={isIcon ? 'md' : 'sm'} aria-hidden={true} />
+      {!isIcon && label}
+    </button>
+  );
+}