1 files changed, 32 insertions, 7 deletions
diff --git a/docs/superpowers/specs/2026-09-12-window-switcher-design.md b/docs/superpowers/specs/2026-09-12-window-switcher-design.md
index ce95f3e..0fabe2f 100644
--- a/docs/superpowers/specs/2026-09-12-window-switcher-design.md
+++ b/docs/superpowers/specs/2026-09-12-window-switcher-design.md
@@ -35,11 +35,32 @@ Per card, top to bottom:
 - The window title, left aligned, elided at the card width.
 - The workspace, centered, in brackets and in the accent colour.
 
-Cards are a fixed size and the grid wraps, centered. A preview is 21:9, so a
-card readable at arm's length is around 380px wide and DP-1 at 2560px fits six
-per row. Six or fewer windows therefore render as the single row this started
-as; more wrap rather than shrinking, so a large window count degrades by
-growing downwards instead of becoming unreadable.
+## Card size and the grid
+
+Previews are not one shape. DP-1 is landscape and its windows are 2556x1034,
+near 21:9. DP-3 has `transform=1`, so it is rotated and its windows are
+1076x1916, portrait 9:16. A fullscreen app is portrait there too. That is a
+4.4x span of aspect ratio inside one grid, so a card cannot take its shape from
+its preview.
+
+Instead the card is a fixed 16:10 box and the preview is fitted inside it,
+preserving aspect. A landscape preview letterboxes slightly, a portrait one
+pillarboxes to roughly a third of the box width, and the empty space reads as
+framing given the box has a background. 16:10 is the compromise: less extreme
+than either input, so neither orientation is punished. The alternative, sizing
+each card to its own preview, was rejected because ragged rows would break the
+alignment of the three text lines under each card, which is what makes a grid
+scannable.
+
+The grid centres, and its column count is the window count capped at six. One
+window sits dead centre, two straddle the middle, three centre on the middle
+one. Seven wraps to a centred 4 and 3.
+
+Cards grow to fill the row they are in, up to a ceiling of 640px wide. So a
+lone window gets a 640px card, where a DP-1 preview renders 640x259 and a DP-3
+one 226x400: bigger, but still a preview rather than something pretending to be
+the window. Six windows give cards around 380px. The ceiling is what stops a
+single preview from becoming a full-screen mirror.
 
 The name is redundant with the icon and usually with the title too. It is kept
 deliberately: it is short and stable, so the eye has something to land on when
@@ -125,6 +146,9 @@ Against Hyprland 0.56.2 and quickshell 0.3.1, in a scratch config:
   `window-close` and for app icons.
 - `DesktopEntries.byId` returns null for bare app ids such as `firefox`. The
   app id itself resolves as an icon name, so lookup falls back to it.
+- DP-3 reports `transform=1`, and the window on it measures 1076x1916 against
+  2556x1034 on DP-1. Both orientations are live at once, which is what the
+  fitted card box exists for.
 
 ## Theme
 
@@ -142,8 +166,9 @@ which is fine.
   window when another is fullscreen on the same workspace. Whether plain
   `focuswindow` still needs it is unknown; it goes back in only if a fullscreen
   window is actually observed staying on top.
-- **Multi-monitor overlays.** DP-1 only. DP-3's windows appear as cards, the
-  overlay just does not paint there.
+- **Multi-monitor overlays.** The overlay paints on DP-1 only. DP-3's windows
+  still appear as cards, and being portrait they are the reason the card box is
+  a fitted 16:10 rather than the shape of a preview.
 - **Hold-and-release ALT + TAB.** Considered and rejected: it depends on the
   switcher seeing the ALT release, and a missed release leaves a stuck
   full-screen overlay.