From c7cecae0515440dee203615568364d306741cd67 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 02:09:49 +0000 Subject: [PATCH 1/4] issues: record why component metrics stay in :root rather than @theme MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review bots have now asked twice, on consecutive PRs, to move a component metric into the Tailwind 4 `@theme` block — `cardTextWidth` on #2374 and `--answer-message-gutter` on #2377. Both were declined for the same reason, and that reason lives only in a code comment beside `--answer-mark-*` in globals.css, which the bots do not read. So the same conversation is paid for on every PR that adds one. The record proposes the small docs-only fix: a prohibition-table row in docs/design-system/GATES.md section 3, in the same shape as the #336 breakpoint decision already recorded there — the artifact a reviewer or a future session actually finds. It explicitly does NOT propose converting either value. Queued as an immutable inbox request; a later serialized `issues:reconcile` allocates the id and edits the canonical ledger. `check:outstanding-issues` reports in step (5 pending). Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01AP3MXGx1bGeEBmFKYkeLA8 --- data/outstanding-issues-snapshot.json | 10 ++++++++-- .../970b4089-9e76-4bcf-821e-2e70e16a3617.json | 14 ++++++++++++++ 2 files changed, 22 insertions(+), 2 deletions(-) create mode 100644 docs/outstanding-issues-inbox/970b4089-9e76-4bcf-821e-2e70e16a3617.json diff --git a/data/outstanding-issues-snapshot.json b/data/outstanding-issues-snapshot.json index bac6314625..d618a395f3 100644 --- a/data/outstanding-issues-snapshot.json +++ b/data/outstanding-issues-snapshot.json @@ -2,7 +2,7 @@ "version": "outstanding-issues-snapshot-v1", "ledger_revision": { "sha": "707b965965a9b843c13deb6b5c9ddd158fe2631d", - "committed_at": "2026-08-25T17:45:01Z" + "committed_at": "2026-08-25T17:45:01+00:00" }, "counts": { "open": 91, @@ -10,7 +10,7 @@ "p2": 57, "p3": 33, "queued": 9, - "pending": 4, + "pending": 5, "resolved": 412 }, "queue": [ @@ -954,6 +954,12 @@ "summary": "The answer source-rail card carries three hardcoded pixel measurements, one of them duplicated", "created_at": "2026-08-25" }, + { + "request_id": "970b4089-9e76-4bcf-821e-2e70e16a3617", + "action": "add", + "summary": "Component metrics stay in :root, not @theme — record the rule where reviewers read it, because bots keep re-raising it", + "created_at": "2026-08-26" + }, { "request_id": "d2a6122a-4fcd-4429-92a7-6004fa19eb24", "action": "add", diff --git a/docs/outstanding-issues-inbox/970b4089-9e76-4bcf-821e-2e70e16a3617.json b/docs/outstanding-issues-inbox/970b4089-9e76-4bcf-821e-2e70e16a3617.json new file mode 100644 index 0000000000..6f5e7908ea --- /dev/null +++ b/docs/outstanding-issues-inbox/970b4089-9e76-4bcf-821e-2e70e16a3617.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "970b4089-9e76-4bcf-821e-2e70e16a3617", + "createdOn": "2026-08-26", + "action": "add", + "payload": { + "pri": "P3", + "type": "rec", + "summary": "Component metrics stay in :root, not @theme — record the rule where reviewers read it, because bots keep re-raising it", + "detail": "Review bots have now asked twice, on consecutive PRs, to move a component metric into the Tailwind 4 @theme block: cardTextWidth (max-w-[158px], PR #2374) and --answer-message-gutter (calc(2.75rem + 1px), PR #2377). Both were declined for the same reason and the reasoning currently lives only in a code comment beside --answer-mark-* in src/app/globals.css, which the bots do not read, so the cost repeats every PR that adds one. THE RULE, as already practised: a value that is a component metric rather than a step on a design scale stays a :root custom property. @theme generates a whole utility family from each token (p-, m-, w-, gap-) and implies a scale step, so a one-consumer or off-grid value there reads as a design decision that was never made; --answer-message-gutter is deliberately off the 4px grid because its 1px compensates for a transparent border, and no existing spacing token equals it. It also couples: tests/tailwind-merge-config.test.ts requires every @theme --spacing-* token to have a matching CLINICAL_TWMERGE_THEME.spacing entry, so the move is never one line. NEXT ACTION (small, docs-only): add a prohibition-table row to docs/design-system/GATES.md section 3 stating the :root-versus-@theme boundary and naming both declined instances, in the same shape as the #336 breakpoint decision recorded there. That is the artifact a reviewer or a future session will actually find. Do NOT convert either value as part of it. Worth pairing with .coderabbit.yaml path instructions if the suggestion recurs after the doc lands.", + "source": "session 2026-08-26, PRs #2374 and #2377 (CodeRabbit nitpicks declined twice with the same reasoning)", + "issueUlid": "01M0XX7KC1Z1AG1WQAH2SBH5HD" + } +} From a54e1a3988be5e2588333f95247005a29f6778e0 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Wed, 26 Aug 2026 10:30:35 +0800 Subject: [PATCH 2/4] docs(issues): cancel over-broad component-metric request --- .../40ff11ca-52f3-4b95-9118-5e0c107e68f0.json | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/outstanding-issues-inbox/40ff11ca-52f3-4b95-9118-5e0c107e68f0.json diff --git a/docs/outstanding-issues-inbox/40ff11ca-52f3-4b95-9118-5e0c107e68f0.json b/docs/outstanding-issues-inbox/40ff11ca-52f3-4b95-9118-5e0c107e68f0.json new file mode 100644 index 0000000000..5bcaa73c99 --- /dev/null +++ b/docs/outstanding-issues-inbox/40ff11ca-52f3-4b95-9118-5e0c107e68f0.json @@ -0,0 +1,10 @@ +{ + "version": 2, + "id": "40ff11ca-52f3-4b95-9118-5e0c107e68f0", + "createdOn": "2026-08-26", + "action": "cancel", + "payload": { + "requestId": "970b4089-9e76-4bcf-821e-2e70e16a3617", + "reason": "Superseded before reconciliation: the original wording incorrectly implied every component metric belongs in :root. The replacement distinguishes module-local one-consumer constants from shared CSS custom properties." + } +} From dbde3290afe0570eecf20987f34a33d080bc3383 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Wed, 26 Aug 2026 10:30:41 +0800 Subject: [PATCH 3/4] docs(issues): scope component-metric guidance --- .../b85ad821-4c9b-4925-b86b-2d5767052b20.json | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 docs/outstanding-issues-inbox/b85ad821-4c9b-4925-b86b-2d5767052b20.json diff --git a/docs/outstanding-issues-inbox/b85ad821-4c9b-4925-b86b-2d5767052b20.json b/docs/outstanding-issues-inbox/b85ad821-4c9b-4925-b86b-2d5767052b20.json new file mode 100644 index 0000000000..305a4137e7 --- /dev/null +++ b/docs/outstanding-issues-inbox/b85ad821-4c9b-4925-b86b-2d5767052b20.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "b85ad821-4c9b-4925-b86b-2d5767052b20", + "createdOn": "2026-08-26", + "action": "add", + "payload": { + "pri": "P3", + "type": "rec", + "summary": "Scope the component-metric rule: keep one-consumer values local; use :root only for shared off-scale CSS custom properties, not @theme", + "detail": "The earlier pending request overgeneralised the :root-versus-@theme boundary. Correct rule: keep a one-consumer component metric local to its owning JS/TS module, such as cardTextWidth (max-w-[158px] in src/components/clinical-dashboard/answer-source-rail.tsx); do not promote it to a global CSS custom property or an @theme token. Apply the :root-versus-@theme decision only when a shared CSS custom property is needed by multiple non-nested consumers: a shared off-scale metric such as --answer-message-gutter (calc(2.75rem + 1px), including its transparent-border compensation) belongs in :root, while @theme is reserved for deliberate design-scale tokens that should generate a utility family. NEXT ACTION (small, docs-only): add a prohibition-table row to docs/design-system/GATES.md section 3 that states this three-way boundary (module-local component constant vs shared :root custom property vs @theme scale token), names both prior examples accurately, and explicitly does not convert either value. The existing tailwind-merge coupling still applies to any deliberate @theme --spacing-* token: tests/tailwind-merge-config.test.ts requires CLINICAL_TWMERGE_THEME.spacing coverage.", + "source": "PR #2381 review thread PRRT_kwDOSh5Fis6cUDDj, reviewing request 970b4089-9e76-4bcf-821e-2e70e16a3617; prior instances #2374 and #2377", + "issueUlid": "01M0XNVN00HX1KSZ3K6AVD9KXZ" + } +} From e2993475802b8e46ec693f99105bf6407f5e01a6 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Wed, 26 Aug 2026 10:30:52 +0800 Subject: [PATCH 4/4] docs(issues): refresh pending-request snapshot --- data/outstanding-issues-snapshot.json | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/data/outstanding-issues-snapshot.json b/data/outstanding-issues-snapshot.json index d618a395f3..7e579749ee 100644 --- a/data/outstanding-issues-snapshot.json +++ b/data/outstanding-issues-snapshot.json @@ -10,7 +10,7 @@ "p2": 57, "p3": 33, "queued": 9, - "pending": 5, + "pending": 7, "resolved": 412 }, "queue": [ @@ -942,6 +942,12 @@ "summary": "Cancel request 8b2a3f89-9bdb-4fb1-8fd0-35165d050263: Implemented the requested local source-card width constant in this owning answer-page change.", "created_at": "2026-08-25" }, + { + "request_id": "40ff11ca-52f3-4b95-9118-5e0c107e68f0", + "action": "cancel", + "summary": "Cancel request 970b4089-9e76-4bcf-821e-2e70e16a3617: Superseded before reconciliation: the original wording incorrectly implied every component metric belongs in :root. The replacement distinguishes module-local one-consumer constants from shared CSS custom properties.", + "created_at": "2026-08-26" + }, { "request_id": "485bdac6-7f79-4539-9d90-347866604b35", "action": "add", @@ -960,6 +966,12 @@ "summary": "Component metrics stay in :root, not @theme — record the rule where reviewers read it, because bots keep re-raising it", "created_at": "2026-08-26" }, + { + "request_id": "b85ad821-4c9b-4925-b86b-2d5767052b20", + "action": "add", + "summary": "Scope the component-metric rule: keep one-consumer values local; use :root only for shared off-scale CSS custom properties, not @theme", + "created_at": "2026-08-26" + }, { "request_id": "d2a6122a-4fcd-4429-92a7-6004fa19eb24", "action": "add",