From 634552e5eacc36b7e548c872589b5903238072f8 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Wed, 2 Sep 2026 06:23:13 +0000
Subject: [PATCH 1/3] fix: give four- and five-column stat grids a phone
 breakpoint (#5679)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Eight grids hard-coded four to five columns with no breakpoint prefix, so
at 360px each card got ~65px of outer width and its label wrapped to four
or five lines. AgentList's stat bar was the worst case: it is the first
thing on the Agents page, so the entire above-the-fold region was
unreadable.

Each grid now gets a narrow phone default and opts into the wide layout at
a breakpoint. The two Big Five readouts stay five-across — they are a fixed
five-trait bar chart whose cells are one bar plus a five-character label —
but shrink the gap and the label below `sm`.

`responsiveGridConventions.test.js` enforces the rule tree-wide rather than
per component: a className carrying a bare `grid-cols-N` for N >= 4 must
also carry a prefixed `...:grid-cols-*`. The allowlist holds the month
grid (inherently seven days) and the two Big Five grids, and a companion
assertion fails if an allowlisted file stops having the grid it was
exempted for.
---
 client/src/AGENTS.md                          |   2 +-
 client/src/components/IconPicker.jsx          |   2 +-
 client/src/components/agents/AgentList.jsx    |   4 +-
 .../src/components/cos/DailyTrendsChart.jsx   |   2 +-
 .../src/components/cos/tabs/LearningTab.jsx   |   2 +-
 .../digital-twin/InterviewAnalysisCard.jsx    |   4 +-
 .../digital-twin/tabs/ImportTab.jsx           |   4 +-
 .../src/components/sync/SyncDetailDrawer.jsx  |   2 +-
 client/src/pages/ChiefOfStaff.jsx             |   2 +-
 client/src/responsiveGridConventions.test.js  | 159 ++++++++++++++++++
 10 files changed, 171 insertions(+), 12 deletions(-)
 create mode 100644 client/src/responsiveGridConventions.test.js

diff --git a/client/src/AGENTS.md b/client/src/AGENTS.md
index c2ef406c94..45ee3151ac 100644
--- a/client/src/AGENTS.md
+++ b/client/src/AGENTS.md
@@ -6,7 +6,7 @@ These apply to React/Vite client code. Universal constraints (functional program
 
 - **No window.alert/confirm** - use inline confirmations or toast notifications
 - **Form labels need `htmlFor`/`id` pairing** - when adding a settings/config form field, wire `<label htmlFor="...">` to an `id="..."` on the input — screen readers and click-to-focus both depend on the association. The visual `block`/`mb-1` styling alone doesn't establish it.
-- **Mobile responsive** - all pages should be mobile responsive friendly
+- **Mobile responsive** - all pages should be mobile responsive friendly. **A `grid-cols-N` with N > 3 and no breakpoint prefix is a bug**, not a style nit: at 360px a four-up stat bar gives each card ~65px of outer width, so its label wraps to five lines and the whole above-the-fold region is unreadable. Give the phone a narrow default and let the viewport opt into the wide layout (`grid-cols-2 gap-3 sm:gap-4 lg:grid-cols-4`). Enforced tree-wide by `client/src/responsiveGridConventions.test.js`, which carries the allowlist for the few grids that really are N-across on a phone (a seven-day month grid, the fixed five-trait Big Five bars).
 - **Above the fold** - keep actionable content and info above the fold and design pages for maximum information and access without scrolling
 - **No hardcoded localhost** - use `window.location.hostname` for URLs; app accessed via Tailscale remotely
 - **Chrome floating over media uses `.port-media-overlay`** - a label, status bar, badge, or control panel sitting on top of an image, a video, or a 3D canvas takes its surface and ink from the theme (`.port-media-overlay`, or `.port-media-overlay-strong` for a small label directly on photography; `.port-media-overlay-item` for its buttons, `.port-media-overlay-divider` for its separators — all defined in `index.css`, which carries the mechanism and the rule for picking between this, `.always-dark`, and the OpenWorld HUD remap). **Don't write `bg-black/NN` + `text-white`/`text-gray-N00` for this** — day mode remaps the text to the theme's dark ink while the black scrim stays black, so the label renders dark-on-black. Older overlays outside the 3D/Three.js pages still carry that idiom (migration tracked in #3796), so match the new convention rather than the nearest neighbor.
diff --git a/client/src/components/IconPicker.jsx b/client/src/components/IconPicker.jsx
index d534ccc370..363bacff8c 100644
--- a/client/src/components/IconPicker.jsx
+++ b/client/src/components/IconPicker.jsx
@@ -37,7 +37,7 @@ export default function IconPicker({ value, onChange }) {
             aria-hidden="true"
           />
           <div className="absolute top-full left-0 mt-1 w-full bg-port-card border border-port-border rounded-lg shadow-xl z-50 p-2 max-h-64 overflow-auto">
-            <div className="grid grid-cols-5 gap-1">
+            <div className="grid grid-cols-4 gap-1 sm:grid-cols-5">
               {iconNames.map(name => (
                 <button
                   key={name}
diff --git a/client/src/components/agents/AgentList.jsx b/client/src/components/agents/AgentList.jsx
index 2d3dc272b5..dd0fa546c6 100644
--- a/client/src/components/agents/AgentList.jsx
+++ b/client/src/components/agents/AgentList.jsx
@@ -182,9 +182,9 @@ export default function AgentList() {
         </div>
       </div>
 
-      <div className="flex-1 overflow-auto p-6">
+      <div className="flex-1 overflow-auto p-4 md:p-6">
         {/* Stats Bar */}
-        <div className="grid grid-cols-4 gap-4 mb-6">
+        <div className="grid grid-cols-2 gap-3 sm:gap-4 lg:grid-cols-4 mb-6">
           <div className="p-4 bg-port-card border border-port-border rounded-lg">
             <div className="text-2xl font-bold text-white">{stats.agents}</div>
             <div className="text-sm text-gray-400">Total Agents</div>
diff --git a/client/src/components/cos/DailyTrendsChart.jsx b/client/src/components/cos/DailyTrendsChart.jsx
index 0f0aa9bfb4..74cfec48c5 100644
--- a/client/src/components/cos/DailyTrendsChart.jsx
+++ b/client/src/components/cos/DailyTrendsChart.jsx
@@ -103,7 +103,7 @@ export default function DailyTrendsChart({ days = 30, initialExpanded = true })
       {expanded && (
         <div className="p-4 pt-0">
           {/* Summary Stats */}
-          <div className="grid grid-cols-4 gap-2 mb-4">
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4 mb-4">
             <div className="text-center">
               <div className="text-lg font-bold text-white">{summary.totalTasks}</div>
               <div className="text-xs text-gray-500">Total Tasks</div>
diff --git a/client/src/components/cos/tabs/LearningTab.jsx b/client/src/components/cos/tabs/LearningTab.jsx
index ec96b4bd61..c6f54336ee 100644
--- a/client/src/components/cos/tabs/LearningTab.jsx
+++ b/client/src/components/cos/tabs/LearningTab.jsx
@@ -65,7 +65,7 @@ export function FeedbackSummary({ feedback }) {
             Durable ratings across live and archived agent runs
           </p>
         </div>
-        <div className="grid grid-cols-4 gap-4 sm:gap-6 text-center">
+        <div className="grid grid-cols-2 gap-4 sm:grid-cols-4 sm:gap-6 text-center">
           <div>
             <div className={`text-lg font-bold ${satisfactionClass}`}>{satisfaction}%</div>
             <div className="text-[11px] text-gray-500">helpful</div>
diff --git a/client/src/components/digital-twin/InterviewAnalysisCard.jsx b/client/src/components/digital-twin/InterviewAnalysisCard.jsx
index 7fabf012b6..8af8f86a90 100644
--- a/client/src/components/digital-twin/InterviewAnalysisCard.jsx
+++ b/client/src/components/digital-twin/InterviewAnalysisCard.jsx
@@ -69,10 +69,10 @@ export default function InterviewAnalysisCard({ analysisResult }) {
               {traitsUpdated.bigFive && (
                 <div>
                   <p className="text-gray-400 mb-1">Big Five:</p>
-                  <div className="grid grid-cols-5 gap-2">
+                  <div className="grid grid-cols-5 gap-1 sm:gap-2">
                     {Object.entries(traitsUpdated.bigFive).filter(([k]) => k !== 'notes').map(([k, v]) => (
                       <div key={k} className="text-center">
-                        <div className="text-xs text-gray-500">{k}</div>
+                        <div className="text-[10px] sm:text-xs text-gray-500">{k}</div>
                         <div className="text-white font-medium">{typeof v === 'number' ? v.toFixed(2) : v}</div>
                       </div>
                     ))}
diff --git a/client/src/components/digital-twin/tabs/ImportTab.jsx b/client/src/components/digital-twin/tabs/ImportTab.jsx
index d30aab114a..852d434e9b 100644
--- a/client/src/components/digital-twin/tabs/ImportTab.jsx
+++ b/client/src/components/digital-twin/tabs/ImportTab.jsx
@@ -435,12 +435,12 @@ export default function ImportTab() {
               {analysisResult.insights.personalityInferences.bigFive && (
                 <div className="mb-6">
                   <h4 className="text-sm font-medium text-gray-400 mb-3">Big Five Traits</h4>
-                  <div className="grid grid-cols-5 gap-2">
+                  <div className="grid grid-cols-5 gap-1 sm:gap-2">
                     {Object.entries(analysisResult.insights.personalityInferences.bigFive).map(([trait, score]) => {
                       const labels = { O: 'Open', C: 'Consc', E: 'Extra', A: 'Agree', N: 'Neuro' };
                       return (
                         <div key={trait} className="text-center">
-                          <div className="text-xs text-gray-500 mb-1">{labels[trait] || trait}</div>
+                          <div className="text-[10px] sm:text-xs text-gray-500 mb-1">{labels[trait] || trait}</div>
                           <div className="h-16 bg-port-bg rounded-lg relative overflow-hidden">
                             <div
                               className="absolute bottom-0 left-0 right-0 bg-port-accent/50"
diff --git a/client/src/components/sync/SyncDetailDrawer.jsx b/client/src/components/sync/SyncDetailDrawer.jsx
index 7cd54d4961..6d129422ba 100644
--- a/client/src/components/sync/SyncDetailDrawer.jsx
+++ b/client/src/components/sync/SyncDetailDrawer.jsx
@@ -124,7 +124,7 @@ function CollectionPreview({ collection, loading, error }) {
         <p className="text-gray-500 text-xs">{items.length} item{items.length !== 1 ? 's' : ''}</p>
       </div>
       {imageItems.length > 0 && (
-        <div className="grid grid-cols-4 gap-1">
+        <div className="grid grid-cols-2 gap-1 sm:grid-cols-4">
           {imageItems.map((it) => (
             <MediaImage
               key={`${it.kind}:${it.ref}`}
diff --git a/client/src/pages/ChiefOfStaff.jsx b/client/src/pages/ChiefOfStaff.jsx
index d20ab7ea04..378e739853 100644
--- a/client/src/pages/ChiefOfStaff.jsx
+++ b/client/src/pages/ChiefOfStaff.jsx
@@ -1026,7 +1026,7 @@ export default function ChiefOfStaff() {
       <div className="flex-1 min-h-0 min-w-0 overflow-y-auto overflow-x-hidden p-3 lg:p-4">
         {/* Stats Bar - hidden for SVG/canvas modes (now integrated into CoS sidebar);
             ascii/terminal mode keeps it because TerminalCoSPanel doesn't host the cards. */}
-        <div className={`grid grid-cols-5 gap-1.5 sm:gap-2 lg:gap-3 mb-3 sm:mb-4 lg:mb-6 ${avatarStyle !== 'ascii' ? 'hidden' : ''}`}>
+        <div className={`grid grid-cols-3 gap-1.5 sm:grid-cols-5 sm:gap-2 lg:gap-3 mb-3 sm:mb-4 lg:mb-6 ${avatarStyle !== 'ascii' ? 'hidden' : ''}`}>
           <StatCard
             label="Active"
             value={activeAgentCount}
diff --git a/client/src/responsiveGridConventions.test.js b/client/src/responsiveGridConventions.test.js
new file mode 100644
index 0000000000..257369f173
--- /dev/null
+++ b/client/src/responsiveGridConventions.test.js
@@ -0,0 +1,159 @@
+/**
+ * Repo-wide responsive-grid convention.
+ *
+ * `client/src/AGENTS.md` requires every page to be mobile responsive, and the
+ * overwhelming majority of grids in the tree already carry a column breakpoint
+ * (`grid-cols-1 sm:grid-cols-2 xl:grid-cols-3`). The failure mode this guard
+ * catches is the one that keeps slipping through review: a stat/summary bar
+ * hard-coding four or five columns with no breakpoint prefix at all. At a 360px
+ * viewport that leaves each card ~65px of outer width — after its own padding,
+ * ~34px of content — so a label like "Platform Accounts" wraps to five lines and
+ * the whole above-the-fold region becomes unreadable (issue #5679).
+ *
+ * The rule: a `className` string holding a bare `grid-cols-N` for N >= 4 must
+ * also hold at least one *prefixed* `…:grid-cols-*` in the same string, so the
+ * wide layout is something the viewport opts into rather than the phone default.
+ * Any variant prefix counts — a media breakpoint (`sm:`), a container query
+ * (`@3xl:`), or a custom variant — because each of them makes the column count
+ * conditional on available width.
+ *
+ * Scoped to git-tracked non-test sources under `client/src` so an untracked
+ * scratch file can't fail the suite. Comments are masked first: a doc comment
+ * quoting an example class string is documentation, not markup.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { trackedSourceFiles } from './test/trackedFiles.js';
+
+const CLIENT_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Grids that are legitimately N-across on a phone, with the reason they are.
+ * Adding a row here is a deliberate design call, not a way past the guard — the
+ * cell has to stay readable at 360px on its own merits.
+ */
+const ALLOWED = new Map([
+  [
+    'src/components/calendar/MonthView.jsx',
+    'A month grid is inherently seven days wide; collapsing the columns would stop it being a calendar.',
+  ],
+  [
+    'src/components/digital-twin/tabs/ImportTab.jsx',
+    'Big Five traits are a fixed five-across bar chart; each cell is one bar plus a five-character label, kept legible with a reduced gap and a smaller label below `sm`.',
+  ],
+  [
+    'src/components/digital-twin/InterviewAnalysisCard.jsx',
+    'Same Big Five five-across readout, in the interview-analysis summary.',
+  ],
+]);
+
+/** Blank out `//` and block comments so a quoted example class isn't scanned as markup. */
+function maskComments(source) {
+  let out = '';
+  let i = 0;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === '/' && source[i + 1] === '/') {
+      while (i < source.length && source[i] !== '\n') {
+        out += ' ';
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      while (i < source.length && !(source[i] === '*' && source[i + 1] === '/')) {
+        out += source[i] === '\n' ? '\n' : ' ';
+        i += 1;
+      }
+      out += '  ';
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      out += ch;
+      i += 1;
+      while (i < source.length && source[i] !== ch) {
+        if (source[i] === '\\') {
+          out += source.slice(i, i + 2);
+          i += 2;
+          continue;
+        }
+        out += source[i];
+        i += 1;
+      }
+      out += source[i] ?? '';
+      i += 1;
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+const STRING_LITERAL = /(['"`])((?:\\.|(?!\1)[\s\S])*?)\1/g;
+// A column count that is the phone default: no `variant:` in front of it.
+const BARE_WIDE_GRID = /(?:^|\s)grid-cols-(\d+)(?=\s|$)/;
+// Any variant prefix — `sm:`, `lg:`, `@3xl:`, `roomy-viewport:` — makes it conditional.
+const PREFIXED_GRID = /[\w@[\]().\-/]+:grid-cols-/;
+const MIN_WIDE_COLUMNS = 4;
+
+function lineOf(source, index) {
+  return source.slice(0, index).split('\n').length;
+}
+
+function violationsIn(rawSource, file) {
+  const source = maskComments(rawSource);
+  const found = [];
+  let match;
+  STRING_LITERAL.lastIndex = 0;
+  while ((match = STRING_LITERAL.exec(source))) {
+    const value = match[2];
+    const bare = value.match(BARE_WIDE_GRID);
+    if (!bare || Number(bare[1]) < MIN_WIDE_COLUMNS) continue;
+    if (PREFIXED_GRID.test(value)) continue;
+    found.push(`${file}:${lineOf(source, match.index)} — "${value.trim()}"`);
+  }
+  return found;
+}
+
+const findViolations = (file) =>
+  violationsIn(readFileSync(join(CLIENT_ROOT, file), 'utf8'), file);
+
+describe('responsive grid conventions', () => {
+  const files = trackedSourceFiles(CLIENT_ROOT);
+
+  it('scans a populated client tree', () => {
+    expect(files.length).toBeGreaterThan(100);
+  });
+
+  // Without this the suite would still pass if the detector silently stopped
+  // matching anything — a green tree-wide guard proves nothing on its own.
+  it('flags a bare wide grid and clears every conditional form', () => {
+    const flagged = (markup) => violationsIn(`<div className="${markup}" />`, 'probe.jsx').length;
+    expect(flagged('grid grid-cols-4 gap-4 mb-6')).toBe(1);
+    expect(flagged('grid grid-cols-5 gap-2')).toBe(1);
+    expect(flagged('grid grid-cols-2 gap-3 sm:gap-4 lg:grid-cols-4')).toBe(0);
+    expect(flagged('grid grid-cols-4 sm:grid-cols-8 lg:grid-cols-12 gap-1.5')).toBe(0);
+    expect(flagged('grid grid-cols-2 gap-3 @3xl:grid-cols-4')).toBe(0);
+    // Narrow grids are fine unprefixed — three stat cards still fit at 360px.
+    expect(flagged('grid grid-cols-3 gap-2')).toBe(0);
+    // A doc comment quoting an example class string is not markup.
+    expect(violationsIn('// e.g. "grid grid-cols-4 gap-4"', 'probe.jsx')).toEqual([]);
+  });
+
+  it('never hard-codes four or more columns without a breakpoint', () => {
+    const violations = files
+      .filter((file) => !ALLOWED.has(file))
+      .flatMap((file) => findViolations(file));
+    expect(violations).toEqual([]);
+  });
+
+  it('keeps the allowlist honest — every exempt file still has the wide grid it was exempted for', () => {
+    const stale = [...ALLOWED.keys()].filter((file) => findViolations(file).length === 0);
+    expect(stale).toEqual([]);
+  });
+});

From c10ea256ca98478a2734495e848f4f50bb4b36f3 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Wed, 2 Sep 2026 06:26:15 +0000
Subject: [PATCH 2/3] fix: scan every bare grid-cols token and widen the icon
 picker on phones (#5679)

Local review pass. The guard's bare-column regex had no global flag, so a
class string holding more than one unprefixed grid-cols was judged by its
first token instead of its widest. The icon picker's phone default drops
from four columns to three so the truncated icon name under each 20px tile
has room, and the convention note now says what the guard actually
enforces: a column breakpoint somewhere in the string, not a mobile
default of three or fewer (thumbnail and heatmap grids are legitimately
wider than that on a phone).
---
 client/src/AGENTS.md                         |  2 +-
 client/src/components/IconPicker.jsx         |  2 +-
 client/src/responsiveGridConventions.test.js | 36 +++++++++++++++-----
 3 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/client/src/AGENTS.md b/client/src/AGENTS.md
index 45ee3151ac..a64d26fe0f 100644
--- a/client/src/AGENTS.md
+++ b/client/src/AGENTS.md
@@ -6,7 +6,7 @@ These apply to React/Vite client code. Universal constraints (functional program
 
 - **No window.alert/confirm** - use inline confirmations or toast notifications
 - **Form labels need `htmlFor`/`id` pairing** - when adding a settings/config form field, wire `<label htmlFor="...">` to an `id="..."` on the input — screen readers and click-to-focus both depend on the association. The visual `block`/`mb-1` styling alone doesn't establish it.
-- **Mobile responsive** - all pages should be mobile responsive friendly. **A `grid-cols-N` with N > 3 and no breakpoint prefix is a bug**, not a style nit: at 360px a four-up stat bar gives each card ~65px of outer width, so its label wraps to five lines and the whole above-the-fold region is unreadable. Give the phone a narrow default and let the viewport opt into the wide layout (`grid-cols-2 gap-3 sm:gap-4 lg:grid-cols-4`). Enforced tree-wide by `client/src/responsiveGridConventions.test.js`, which carries the allowlist for the few grids that really are N-across on a phone (a seven-day month grid, the fixed five-trait Big Five bars).
+- **Mobile responsive** - all pages should be mobile responsive friendly. **A `grid-cols-N` with N > 3 and no `…:grid-cols-*` anywhere in the same class string is a bug**, not a style nit: at 360px a four-up stat bar gives each card ~65px of outer width, so its label wraps to five lines and the whole above-the-fold region is unreadable. Give text-bearing cards a narrow phone default and let the viewport opt into the wide layout (`grid-cols-2 gap-3 sm:gap-4 lg:grid-cols-4`); a widened *gap* (`gap-4 sm:gap-6`) is not a column breakpoint. A grid of square thumbnails or heatmap cells may stay four-plus wide on a phone, but it still needs a column breakpoint so the desktop isn't stuck at the phone count. Enforced tree-wide by `client/src/responsiveGridConventions.test.js`, which carries the allowlist for the few grids that really are frozen N-across (a seven-day month grid, the fixed five-trait Big Five bars).
 - **Above the fold** - keep actionable content and info above the fold and design pages for maximum information and access without scrolling
 - **No hardcoded localhost** - use `window.location.hostname` for URLs; app accessed via Tailscale remotely
 - **Chrome floating over media uses `.port-media-overlay`** - a label, status bar, badge, or control panel sitting on top of an image, a video, or a 3D canvas takes its surface and ink from the theme (`.port-media-overlay`, or `.port-media-overlay-strong` for a small label directly on photography; `.port-media-overlay-item` for its buttons, `.port-media-overlay-divider` for its separators — all defined in `index.css`, which carries the mechanism and the rule for picking between this, `.always-dark`, and the OpenWorld HUD remap). **Don't write `bg-black/NN` + `text-white`/`text-gray-N00` for this** — day mode remaps the text to the theme's dark ink while the black scrim stays black, so the label renders dark-on-black. Older overlays outside the 3D/Three.js pages still carry that idiom (migration tracked in #3796), so match the new convention rather than the nearest neighbor.
diff --git a/client/src/components/IconPicker.jsx b/client/src/components/IconPicker.jsx
index 363bacff8c..ca5abff7f2 100644
--- a/client/src/components/IconPicker.jsx
+++ b/client/src/components/IconPicker.jsx
@@ -37,7 +37,7 @@ export default function IconPicker({ value, onChange }) {
             aria-hidden="true"
           />
           <div className="absolute top-full left-0 mt-1 w-full bg-port-card border border-port-border rounded-lg shadow-xl z-50 p-2 max-h-64 overflow-auto">
-            <div className="grid grid-cols-4 gap-1 sm:grid-cols-5">
+            <div className="grid grid-cols-3 gap-1 sm:grid-cols-5">
               {iconNames.map(name => (
                 <button
                   key={name}
diff --git a/client/src/responsiveGridConventions.test.js b/client/src/responsiveGridConventions.test.js
index 257369f173..7ef6b0fe09 100644
--- a/client/src/responsiveGridConventions.test.js
+++ b/client/src/responsiveGridConventions.test.js
@@ -12,10 +12,17 @@
  *
  * The rule: a `className` string holding a bare `grid-cols-N` for N >= 4 must
  * also hold at least one *prefixed* `…:grid-cols-*` in the same string, so the
- * wide layout is something the viewport opts into rather than the phone default.
- * Any variant prefix counts — a media breakpoint (`sm:`), a container query
- * (`@3xl:`), or a custom variant — because each of them makes the column count
- * conditional on available width.
+ * column count is conditional on available width instead of frozen at every
+ * viewport. Any variant prefix counts — a media breakpoint (`sm:`), a container
+ * query (`@3xl:`), or a custom variant.
+ *
+ * Deliberately NOT "the unprefixed default must be <= 3 columns": a grid of
+ * square thumbnails or heatmap cells is legitimately four to six wide on a
+ * phone (`grid-cols-4 sm:grid-cols-8 lg:grid-cols-12` over sprite frames,
+ * `grid-cols-6 sm:grid-cols-12` over a 24-hour heatmap) because the cell holds
+ * no text to wrap. The defect this guard exists for is the *frozen* count — a
+ * grid that never learned the viewport changes — and the author who writes a
+ * breakpoint at all has demonstrably thought about the narrow case.
  *
  * Scoped to git-tracked non-test sources under `client/src` so an untracked
  * scratch file can't fail the suite. Comments are masked first: a doc comment
@@ -95,12 +102,22 @@ function maskComments(source) {
 }
 
 const STRING_LITERAL = /(['"`])((?:\\.|(?!\1)[\s\S])*?)\1/g;
-// A column count that is the phone default: no `variant:` in front of it.
-const BARE_WIDE_GRID = /(?:^|\s)grid-cols-(\d+)(?=\s|$)/;
+// A column count that is the phone default: no `variant:` in front of it. Global,
+// because a single class string can hold more than one bare token and the widest
+// one is the one that decides whether the layout is legible.
+const BARE_GRID = /(?:^|\s)grid-cols-(\d+)(?=\s|$)/g;
 // Any variant prefix — `sm:`, `lg:`, `@3xl:`, `roomy-viewport:` — makes it conditional.
 const PREFIXED_GRID = /[\w@[\]().\-/]+:grid-cols-/;
 const MIN_WIDE_COLUMNS = 4;
 
+function widestBareColumnCount(value) {
+  BARE_GRID.lastIndex = 0;
+  let widest = 0;
+  let bare;
+  while ((bare = BARE_GRID.exec(value))) widest = Math.max(widest, Number(bare[1]));
+  return widest;
+}
+
 function lineOf(source, index) {
   return source.slice(0, index).split('\n').length;
 }
@@ -112,8 +129,7 @@ function violationsIn(rawSource, file) {
   STRING_LITERAL.lastIndex = 0;
   while ((match = STRING_LITERAL.exec(source))) {
     const value = match[2];
-    const bare = value.match(BARE_WIDE_GRID);
-    if (!bare || Number(bare[1]) < MIN_WIDE_COLUMNS) continue;
+    if (widestBareColumnCount(value) < MIN_WIDE_COLUMNS) continue;
     if (PREFIXED_GRID.test(value)) continue;
     found.push(`${file}:${lineOf(source, match.index)} — "${value.trim()}"`);
   }
@@ -136,6 +152,10 @@ describe('responsive grid conventions', () => {
     const flagged = (markup) => violationsIn(`<div className="${markup}" />`, 'probe.jsx').length;
     expect(flagged('grid grid-cols-4 gap-4 mb-6')).toBe(1);
     expect(flagged('grid grid-cols-5 gap-2')).toBe(1);
+    // A widened gap is not a column breakpoint — it leaves four columns frozen.
+    expect(flagged('grid grid-cols-4 gap-4 sm:gap-6 text-center')).toBe(1);
+    // The widest bare token decides, not the first one seen.
+    expect(flagged('grid grid-cols-2 gap-2 grid-cols-6')).toBe(1);
     expect(flagged('grid grid-cols-2 gap-3 sm:gap-4 lg:grid-cols-4')).toBe(0);
     expect(flagged('grid grid-cols-4 sm:grid-cols-8 lg:grid-cols-12 gap-1.5')).toBe(0);
     expect(flagged('grid grid-cols-2 gap-3 @3xl:grid-cols-4')).toBe(0);

From 77112eb83c1c1e26b812e9db8f69b5b384d8b1e6 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Wed, 2 Sep 2026 06:33:05 +0000
Subject: [PATCH 3/3] ci: select the responsive-grid guard whenever a client
 source changes (#5679)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A tree-scanning guard is unreachable through CI's import-graph selection —
nothing imports the file that would violate it. The responsive-grid guard
can only newly fail when a client/src .js/.jsx file changes, the same
trigger the mounted-ref guard already rides, so it joins that
structuralTestsFor branch rather than the always-run list.
---
 scripts/ci-test-plan.js          | 10 ++++++----
 scripts/repo-scan-guards.test.js |  1 +
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.js
index 03097ce3cc..0b7d57a299 100644
--- a/scripts/ci-test-plan.js
+++ b/scripts/ci-test-plan.js
@@ -238,13 +238,15 @@ const structuralTestsFor = (changedFiles, trackedSet) => {
   if (changedFiles.some((path) => /^client\/src\/.*\.jsx$/.test(path))) {
     add('client/src/a11yConventions.test.js');
   }
-  // Both `.js` and `.jsx`: the StrictMode mounted-ref bug this guards against
+  // Both `.js` and `.jsx`: the StrictMode mounted-ref bug the first guard covers
   // reached its widest blast radius through a plain-`.js` hook (`useAsyncAction`),
-  // so a `.jsx`-only trigger would miss the case that matters most. Nothing else
-  // selects this file — it has no source sibling and imports no app module, so
-  // without this entry it only ever runs on a full suite.
+  // so a `.jsx`-only trigger would miss the case that matters most, and the
+  // responsive-grid guard reads class strings out of both extensions. Neither
+  // file has a source sibling or imports an app module, so nothing else selects
+  // them — without this entry they only ever run on a full suite.
   if (changedFiles.some((path) => /^client\/src\/.*\.jsx?$/.test(path))) {
     add('client/src/hooks/mountedRefConventions.test.js');
+    add('client/src/responsiveGridConventions.test.js');
   }
 
   return selected;
diff --git a/scripts/repo-scan-guards.test.js b/scripts/repo-scan-guards.test.js
index b231955ffc..30f70375ad 100644
--- a/scripts/repo-scan-guards.test.js
+++ b/scripts/repo-scan-guards.test.js
@@ -39,6 +39,7 @@ const STRUCTURALLY_SELECTED = new Map([
   // the only way either can start failing.
   ['client/src/a11yConventions.test.js', 'structuralTestsFor: client/src/**.jsx'],
   ['client/src/hooks/mountedRefConventions.test.js', 'structuralTestsFor: client/src/**.js(x)'],
+  ['client/src/responsiveGridConventions.test.js', 'structuralTestsFor: client/src/**.js(x)'],
   // `.ps1` is not in EXECUTABLE_RE, so touching one is an "unclassified changed
   // file" and forces the complete suite. The guard also rides the Windows
   // contract list.