From e3446732b873103f44dfdb53aa0d2b7270a44d5a Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 1 Sep 2026 21:36:46 -0700
Subject: [PATCH] =?UTF-8?q?fix(website):=20legible=20diagram=20text=20on?=
 =?UTF-8?q?=20phones=20=E2=80=94=20600px=20floor=20+=20scroll=20shadows?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The kit's 480px min-width scaled diagram SVGs to 0.75 on phones, rendering
10.5px meta text at ~7.9px with no hint the figure scrolls. Floor the SVG
at 600px (>=94% of designed type size; still fits the ~632px desktop column
scroll-free) and add local/scroll background scroll shadows on the figure,
visible through the transparent dot-grid ground, with a surface-matched
cover var the tinted marketing sections re-point.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/website/src/styles/docs.css              | 21 ++++++++++++++++++-
 apps/website/src/styles/landing.css           |  3 +++
 .../src/styles/style-contracts.spec.ts        |  3 ++-
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/apps/website/src/styles/docs.css b/apps/website/src/styles/docs.css
index 65e132962..697fc9eac 100644
--- a/apps/website/src/styles/docs.css
+++ b/apps/website/src/styles/docs.css
@@ -654,13 +654,32 @@ body:has([data-website-workspace-host]) {
 }
 /* mdx — diagram kit (components/docs/diagrams/*) */
 .tp-diagram-figure {
+  /* The cover layers must match the surface behind the figure; marketing
+   * sections re-point this at their tinted surface. */
+  --diagram-scroll-bg: var(--color-surface);
   margin: 24px 0;
   overflow-x: auto;
+  /* Scroll shadows (cover layers scroll with the content, shadow layers
+   * don't), visible through the SVG's transparent dot-grid ground. They
+   * appear only on the clipped side, so a fully visible diagram stays clean
+   * and a clipped one advertises the internal scroll. */
+  background:
+    linear-gradient(to right, var(--diagram-scroll-bg) 40%, rgba(255, 255, 255, 0)) left / 48px 100%,
+    linear-gradient(to left, var(--diagram-scroll-bg) 40%, rgba(255, 255, 255, 0)) right / 48px 100%,
+    radial-gradient(farthest-side at 0 50%, rgba(28, 28, 28, 0.16), transparent) left / 16px 100%,
+    radial-gradient(farthest-side at 100% 50%, rgba(28, 28, 28, 0.16), transparent) right / 16px 100%;
+  background-repeat: no-repeat;
+  background-attachment: local, local, scroll, scroll;
 }
 .tp-diagram-svg {
   display: block;
   width: 100%;
-  min-width: 480px;
+  /* Floor the render width: shrinking the SVG shrinks its text with it
+   * (10.5px meta was hitting ~7.9px on phones at the old 480px floor). 600
+   * keeps type at ≥94% of designed size, and — unlike a full 640 floor —
+   * still fits the ~632px desktop article column without a stray scrollbar.
+   * Narrower viewports scroll the figure; the scroll shadows advertise it. */
+  min-width: 600px;
   max-width: 680px;
   margin: 0 auto;
 }
diff --git a/apps/website/src/styles/landing.css b/apps/website/src/styles/landing.css
index 86dbc2d4b..40cd5d6d1 100644
--- a/apps/website/src/styles/landing.css
+++ b/apps/website/src/styles/landing.css
@@ -1509,4 +1509,7 @@
    flex column, instead of filling the container like the surrounding text. */
 .stack-diagram-section .tp-diagram-figure {
   width: 100%;
+  /* The section sits on the tinted surface; the scroll-shadow cover layers
+     must match it or they read as white bars at the figure edges. */
+  --diagram-scroll-bg: var(--color-surface-tinted);
 }
diff --git a/apps/website/src/styles/style-contracts.spec.ts b/apps/website/src/styles/style-contracts.spec.ts
index 4d4269cec..fe111f669 100644
--- a/apps/website/src/styles/style-contracts.spec.ts
+++ b/apps/website/src/styles/style-contracts.spec.ts
@@ -131,9 +131,10 @@ const CONTRACTS: StyleContract[] = [
   {
     file: 'docs.css',
     selector: '.tp-diagram-svg',
-    why: 'The docs-scale cap keeps diagrams from ballooning past a readable width in the article column; losing it lets the SVG stretch to the full (scrollable) figure width instead.',
+    why: 'The docs-scale cap keeps diagrams from ballooning past a readable width in the article column; losing it lets the SVG stretch to the full (scrollable) figure width instead. The 600px floor keeps SVG text at >=94% of designed size on phones (shrinking the box shrinks the type with it) while still fitting the ~632px desktop column scroll-free.',
     requires: {
       'max-width': /max-width:\s*680px/,
+      'min-width': /min-width:\s*600px/,
     },
   },
 ];