From e154908251c7eebea074a026559856b69916bccf Mon Sep 17 00:00:00 2001
From: Yigit Gurbulak <yigitgurbulakk@gmail.com>
Date: Wed, 30 Sep 2026 04:30:14 +0300
Subject: [PATCH 1/3] fix(a11y): contrast, touch targets and terminal motion
 from design audit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 app/blog/[slug]/page.tsx         | 12 ++---
 app/blog/page.tsx                |  2 +-
 app/globals.css                  | 92 ++++++++++++++++++++++----------
 components/site/Footer.tsx       | 16 +++---
 components/site/HeroTerminal.tsx | 34 ++++++++----
 components/ui/ComparisonRow.tsx  |  8 ++-
 components/ui/Frame.tsx          |  4 +-
 components/ui/LegalDoc.tsx       |  2 +-
 components/ui/PanelFigure.tsx    |  9 ++--
 components/ui/PostRow.tsx        |  8 +--
 components/ui/brand.tsx          |  6 ++-
 11 files changed, 127 insertions(+), 66 deletions(-)

diff --git a/app/blog/[slug]/page.tsx b/app/blog/[slug]/page.tsx
index a480924..78304d1 100644
--- a/app/blog/[slug]/page.tsx
+++ b/app/blog/[slug]/page.tsx
@@ -111,7 +111,7 @@ export default async function BlogPost({
           <Link
             href="/blog/"
             aria-label="Back to field notes"
-            className="meta inline-flex items-center gap-2 self-start opacity-50 no-underline transition-opacity hover:opacity-100"
+            className="meta inline-flex items-center gap-2 self-start opacity-60 no-underline transition-opacity hover:opacity-100"
           >
             <span aria-hidden>←</span> field notes
           </Link>
@@ -121,7 +121,7 @@ export default async function BlogPost({
               notes" back-link above stays flush-left as nav chrome. */}
           <header className="flex flex-col items-center gap-6 text-center">
             <div
-              className={`${META} flex flex-wrap items-center justify-center gap-x-3 gap-y-1 tabular-nums opacity-50`}
+              className={`${META} flex flex-wrap items-center justify-center gap-x-3 gap-y-1 tabular-nums opacity-60`}
             >
               <span>§ {num}</span>
               <span aria-hidden>·</span>
@@ -168,10 +168,10 @@ export default async function BlogPost({
                   {/* The title holds steady on hover — the glyph slides +
                       greens and the label lifts, mirroring the index row's
                       `→`. */}
-                  <span className="meta opacity-50 transition-opacity duration-300 ease-out group-hover:opacity-90">
+                  <span className="meta opacity-60 transition-opacity duration-300 ease-out group-hover:opacity-90">
                     <span
                       aria-hidden
-                      className="inline-block transition-all duration-300 ease-out group-hover:-translate-x-1 group-hover:text-whisper"
+                      className="inline-block transition-[translate,color] duration-300 ease-out group-hover:-translate-x-1 group-hover:text-whisper"
                     >
                       ←
                     </span>{" "}
@@ -189,11 +189,11 @@ export default async function BlogPost({
                   href={`/blog/${newer.slug}/`}
                   className="group flex flex-col gap-2 no-underline @xl:items-end @xl:text-right"
                 >
-                  <span className="meta opacity-50 transition-opacity duration-300 ease-out group-hover:opacity-90">
+                  <span className="meta opacity-60 transition-opacity duration-300 ease-out group-hover:opacity-90">
                     later{" "}
                     <span
                       aria-hidden
-                      className="inline-block transition-all duration-300 ease-out group-hover:translate-x-1 group-hover:text-whisper"
+                      className="inline-block transition-[translate,color] duration-300 ease-out group-hover:translate-x-1 group-hover:text-whisper"
                     >
                       →
                     </span>
diff --git a/app/blog/page.tsx b/app/blog/page.tsx
index 72c6240..60e6d85 100644
--- a/app/blog/page.tsx
+++ b/app/blog/page.tsx
@@ -92,7 +92,7 @@ export default function BlogIndex() {
           <div className="mt-16 flex flex-col">
             <div
               aria-hidden
-              className={`meta hidden pb-3 opacity-50 @xl:grid ${BLOG_GRID_COLS}`}
+              className={`meta hidden pb-3 opacity-60 @xl:grid ${BLOG_GRID_COLS}`}
             >
               <span>#</span>
               <span>date</span>
diff --git a/app/globals.css b/app/globals.css
index d65fe44..de8c078 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -4,6 +4,13 @@
   --ink: #000000;
   --paper: #ffffff;
   --whisper: #0f9d6a;
+  /* Raw --whisper is ~3.5:1 on paper, short of AA for text, so text on paper
+     uses it mixed 68% with ink (~6.5:1). On ink the raw accent already clears
+     AA (~6:1). --whisper-text is what brand-coloured text reads: raw by
+     default (the page ground is ink), swapped to --whisper-deep by
+     Frame tone="paper". */
+  --whisper-deep: color-mix(in srgb, var(--whisper) 68%, var(--ink));
+  --whisper-text: var(--whisper);
   /* Intentionally 0: anchor jumps land flush at viewport top (under
      the fixed nav). Section headers don't get clipped because every
      Frame's --spacing-frame-pad-y floor (5rem = 80px) sits comfortably
@@ -25,6 +32,7 @@
   --color-ink: var(--ink);
   --color-paper: var(--paper);
   --color-whisper: var(--whisper);
+  --color-whisper-text: var(--whisper-text);
 
   --font-sans:
     var(--font-geist-sans), ui-sans-serif, system-ui, -apple-system,
@@ -204,7 +212,6 @@ body {
     opacity 800ms var(--ease-soft),
     transform 800ms var(--ease-soft);
   transition-delay: var(--reveal-delay, 0ms);
-  will-change: opacity, transform;
 }
 
 [data-reveal][data-revealed="true"] {
@@ -320,18 +327,17 @@ a.cta-primary:focus-visible {
   outline-offset: 9px;
 }
 
-/* The status link under the hero terminal. Raw --whisper is ~3.5:1 on
-   paper, short of AA at body size, so the value text uses whisper mixed
-   68% with ink (~6.6:1). The label is ink like the stat labels; the dot
-   and the arrow keep the full accent. */
+/* The status link under the hero terminal. The value text takes
+   --whisper-deep (see :root) for AA on paper. The label is ink like the
+   stat labels; the dot and the arrow keep the full accent. */
 a.hero-status {
-  color: color-mix(in srgb, var(--whisper) 68%, var(--ink));
+  color: var(--whisper-deep);
 }
 
 .hero-status-text {
   padding-bottom: 1px;
   border-bottom: 1px solid transparent;
-  transition: border-bottom-color 260ms cubic-bezier(0.2, 0.8, 0.2, 1);
+  transition: border-bottom-color 260ms var(--ease-soft);
 }
 
 a.hero-status:hover .hero-status-text {
@@ -340,7 +346,7 @@ a.hero-status:hover .hero-status-text {
 
 a.hero-status .arrow {
   margin-right: 0;
-  transition: transform 260ms cubic-bezier(0.16, 1, 0.3, 1);
+  transition: transform 260ms var(--ease-expo);
 }
 
 a.hero-status:hover .arrow {
@@ -485,7 +491,7 @@ a.hero-status:hover .arrow {
 }
 
 .terminal .dim {
-  opacity: 0.45;
+  opacity: 0.6;
 }
 
 .terminal .amount {
@@ -506,8 +512,9 @@ a.hero-status:hover .arrow {
 .terminal .progress-fill {
   position: absolute;
   inset: 0;
-  width: 0%;
   background: var(--whisper);
+  transform: scaleX(0);
+  transform-origin: left center;
   animation: term-progress 4.5s linear infinite;
   animation-delay: 1.1s;
 }
@@ -515,20 +522,20 @@ a.hero-status:hover .arrow {
 @keyframes term-progress {
   0%,
   24% {
-    width: 0%;
+    transform: scaleX(0);
   }
   44% {
-    width: 100%;
+    transform: scaleX(1);
   }
   80% {
-    width: 100%;
+    transform: scaleX(1);
   }
   88% {
-    width: 100%;
+    transform: scaleX(1);
     opacity: 0;
   }
   100% {
-    width: 0%;
+    transform: scaleX(0);
     opacity: 0;
   }
 }
@@ -560,10 +567,28 @@ a.hero-status:hover .arrow {
     transform: none;
   }
   .terminal .progress-fill {
-    width: 100%;
+    transform: none;
+  }
+}
+
+/* Hovering the terminal holds the current settlement fully drawn: the
+   cascade stops, so no animationiteration fires and HeroTerminal doesn't
+   advance. Leaving re-applies the animation, which replays the cascade
+   from the top. The cursor keeps blinking. */
+@media (hover: hover) {
+  .terminal:hover .tl,
+  .terminal:hover .progress-fill {
+    animation: none;
+    opacity: 1;
+    transform: none;
   }
 }
 
+/* Set by HeroTerminal while the panel is scrolled out of view. */
+[data-offscreen] .terminal :is(.tl, .progress-fill, .cursor) {
+  animation-play-state: paused;
+}
+
 /* --- fleet status panel (§05) -----------------------------------------
    Sits on the paper Contact section as an inverted panel. Same "tool
    panel" vocabulary as .terminal — soft corners, solid rule, hard
@@ -760,9 +785,12 @@ a.hero-status:hover .arrow {
 
 .fleet-spark-cell {
   flex: 1;
-  height: max(1px, calc(var(--level, 0) * 100%));
+  height: 100%;
   background: var(--whisper);
-  transition: height 0.6s var(--ease-term);
+  /* 0.08 of the 13px strip is the ~1px hairline a zero hour keeps. */
+  transform: scaleY(max(0.08, var(--level, 0)));
+  transform-origin: bottom;
+  transition: transform 0.6s var(--ease-term);
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -1090,13 +1118,16 @@ a.hero-status:hover .arrow {
    Phone-only (<md) slide-out drawer. See MobileMenu.tsx for the
    portal/focus model. */
 
+/* A 44px hit area around an 18px glyph. The box overhangs the gutter by
+   11px so the glyph sits where the old 22px button drew it, centred on the
+   nav's ~70px bar. */
 .mm-toggle {
   position: fixed;
-  top: 24px;
-  right: var(--spacing-frame-gutter);
+  top: 13px;
+  right: calc(var(--spacing-frame-gutter) - 11px);
   z-index: 65;
-  width: 22px;
-  height: 22px;
+  width: 44px;
+  height: 44px;
   color: var(--ink);
   background: transparent;
   border: 0;
@@ -1104,6 +1135,9 @@ a.hero-status:hover .arrow {
   cursor: pointer;
   transition: color 400ms var(--ease-soft);
 }
+.mm-toggle:focus-visible {
+  outline-offset: -6px;
+}
 .mm-toggle[data-tone="ink"] {
   color: var(--paper);
 }
@@ -1112,8 +1146,8 @@ a.hero-status:hover .arrow {
 .mm-toggle::after {
   content: "";
   position: absolute;
-  left: 2px;
-  right: 2px;
+  left: 13px;
+  right: 13px;
   height: 1px;
   background: currentColor;
   transition:
@@ -1122,18 +1156,18 @@ a.hero-status:hover .arrow {
 }
 
 .mm-toggle::before {
-  top: 8px;
+  top: 19px;
 }
 .mm-toggle::after {
-  top: 14px;
+  top: 25px;
 }
 
 .mm-toggle[data-open="true"]::before {
-  top: 11px;
+  top: 22px;
   transform: rotate(45deg);
 }
 .mm-toggle[data-open="true"]::after {
-  top: 11px;
+  top: 22px;
   transform: rotate(-45deg);
 }
 
@@ -1195,7 +1229,7 @@ a.hero-status:hover .arrow {
 }
 .mm-head-link:hover,
 .mm-head-link:active {
-  color: var(--whisper);
+  color: var(--whisper-deep);
 }
 
 .mm-list {
diff --git a/components/site/Footer.tsx b/components/site/Footer.tsx
index b1415fb..5740dea 100644
--- a/components/site/Footer.tsx
+++ b/components/site/Footer.tsx
@@ -6,32 +6,32 @@ export function Footer() {
     <footer className="bg-paper px-frame-gutter pb-10 text-ink">
       <div className="@container mx-auto flex max-w-frame flex-col gap-3">
         <span aria-hidden className="rule opacity-40" />
-        <div className="grid grid-cols-1 gap-6 text-micro tracking-[0.2em] uppercase opacity-80 @md:grid-cols-3 @md:items-start @md:gap-2">
-          <span>© decdn labs · open source</span>
-          <span className="@md:text-center">
+        <div className="grid grid-cols-1 gap-6 text-micro tracking-[0.2em] uppercase @md:grid-cols-3 @md:items-start @md:gap-2">
+          <span className="opacity-80">© decdn labs · open source</span>
+          <span className="opacity-80 @md:text-center">
             built in rust · probably over-engineered
           </span>
           {/* Right-aligned vertical list: legal pages stacked above the
               presskit download. */}
           <nav
             aria-label="Legal and resources"
-            className="flex flex-col gap-2 @md:items-end @md:justify-self-end"
+            className="-mt-1 flex flex-col @md:items-end @md:justify-self-end"
           >
             <Link
               href={links.privacy}
-              className="no-underline transition-opacity hover:opacity-100"
+              className="py-1 underline-offset-4 opacity-80 transition-opacity hover:underline hover:opacity-100"
             >
               privacy
             </Link>
             <Link
               href={links.terms}
-              className="no-underline transition-opacity hover:opacity-100"
+              className="py-1 underline-offset-4 opacity-80 transition-opacity hover:underline hover:opacity-100"
             >
               terms
             </Link>
             <Link
               href={links.disclaimer}
-              className="no-underline transition-opacity hover:opacity-100"
+              className="py-1 underline-offset-4 opacity-80 transition-opacity hover:underline hover:opacity-100"
             >
               disclaimer
             </Link>
@@ -39,7 +39,7 @@ export function Footer() {
               href={links.presskit}
               download
               aria-label="Download presskit"
-              className="mt-1 inline-flex items-baseline gap-2 border-b border-current pb-[2px] no-underline hover:opacity-100"
+              className="mt-2 inline-flex items-baseline gap-2 border-b border-current pb-[2px] no-underline opacity-80 transition-opacity hover:opacity-100"
             >
               <span>presskit</span>
               <span aria-hidden>↓</span>
diff --git a/components/site/HeroTerminal.tsx b/components/site/HeroTerminal.tsx
index 16080f2..8540e27 100644
--- a/components/site/HeroTerminal.tsx
+++ b/components/site/HeroTerminal.tsx
@@ -1,25 +1,38 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { type AnimationEvent, useEffect, useRef, useState } from "react";
 import { PanelFigure } from "@/components/ui/PanelFigure";
 import { PANEL_CAPTIONS } from "@/lib/copy";
 import { STATS_URL, terminalSessions, timeAgo } from "@/lib/stats";
 import { useStats } from "@/lib/use-stats";
 
-const CYCLE_MS = 4500;
-
 export function HeroTerminal({ className }: { className?: string }) {
   const result = useStats();
   const sessions = result.status === "ok" ? terminalSessions(result.stats) : [];
   const [index, setIndex] = useState(0);
+  const figureRef = useRef<HTMLElement>(null);
+
+  // The next session is cued by the cascade itself: each loop of the first
+  // line's 4.5s animation advances one. Anything that stops the CSS stops
+  // the cycle with it — reduced motion (no animation), hovering the panel
+  // (holds the lines, see globals.css), a background tab (animations don't
+  // run) and scrolling out of view (paused below). A timer would keep
+  // swapping content through all of those.
+  const advance = (e: AnimationEvent<HTMLDivElement>) => {
+    if (e.target !== e.currentTarget || sessions.length < 2) return;
+    setIndex((i) => (i + 1) % sessions.length);
+  };
 
+  // An attribute rather than state: pausing needs no re-render.
   useEffect(() => {
-    if (sessions.length < 2) return;
-    const id = window.setInterval(() => {
-      setIndex((i) => (i + 1) % sessions.length);
-    }, CYCLE_MS);
-    return () => window.clearInterval(id);
-  }, [sessions.length]);
+    const el = figureRef.current;
+    if (el === null) return;
+    const io = new IntersectionObserver(([entry]) => {
+      el.toggleAttribute("data-offscreen", !entry.isIntersecting);
+    });
+    io.observe(el);
+    return () => io.disconnect();
+  }, []);
 
   const s = sessions.length > 0 ? sessions[index % sessions.length] : null;
   const catchingUp = result.status === "ok" && !result.stats.caughtUp;
@@ -29,6 +42,7 @@ export function HeroTerminal({ className }: { className?: string }) {
     // file; PanelFigure carries the caption that says so, outside the
     // aria-hidden subtree.
     <PanelFigure
+      ref={figureRef}
       className={className}
       panelClassName="terminal"
       caption={PANEL_CAPTIONS.terminal}
@@ -46,7 +60,7 @@ export function HeroTerminal({ className }: { className?: string }) {
             and progress bar restart cleanly when the session flips. */}
       {s ? (
         <div className="terminal-body" key={s.key}>
-          <div className="tl tl-0">
+          <div className="tl tl-0" onAnimationIteration={advance}>
             <span className="prompt">$</span>
             <span> settled </span>
             <span className="hash">tx {s.tx}</span>
diff --git a/components/ui/ComparisonRow.tsx b/components/ui/ComparisonRow.tsx
index 73aa0ea..c2cdf01 100644
--- a/components/ui/ComparisonRow.tsx
+++ b/components/ui/ComparisonRow.tsx
@@ -15,7 +15,13 @@ function Rate({ value, strike }: { value: string; strike?: true }) {
     <>
       {figure}
       {unit && (
-        <span className="meta ml-1 align-baseline opacity-70">{unit}</span>
+        // Struck, the unit already sits inside the <s>'s 55%; dimming it
+        // again would take 11px text under AA on ink.
+        <span
+          className={`meta ml-1 align-baseline ${strike ? "" : "opacity-70"}`}
+        >
+          {unit}
+        </span>
       )}
     </>
   );
diff --git a/components/ui/Frame.tsx b/components/ui/Frame.tsx
index 9c537ac..6084bb5 100644
--- a/components/ui/Frame.tsx
+++ b/components/ui/Frame.tsx
@@ -10,9 +10,11 @@ type FrameProps = {
   children: ReactNode;
 };
 
+// Paper also swaps brand-coloured text to the deeper whisper, which is what
+// clears AA on white (see --whisper-text in globals.css).
 const TONE_CLASS: Record<Tone, string> = {
   ink: "bg-ink text-paper",
-  paper: "bg-paper text-ink",
+  paper: "bg-paper text-ink [--whisper-text:var(--whisper-deep)]",
 };
 
 export function Frame({ id, tone, className = "", children }: FrameProps) {
diff --git a/components/ui/LegalDoc.tsx b/components/ui/LegalDoc.tsx
index afc709c..1289ed1 100644
--- a/components/ui/LegalDoc.tsx
+++ b/components/ui/LegalDoc.tsx
@@ -20,7 +20,7 @@ export function LegalDoc({ slug }: { slug: LegalSlug }) {
             >
               {doc.title}
             </h1>
-            <p className="meta opacity-50">
+            <p className="meta opacity-60">
               effective{" "}
               <time dateTime={doc.effective}>{doc.effectiveLabel}</time>
             </p>
diff --git a/components/ui/PanelFigure.tsx b/components/ui/PanelFigure.tsx
index 0116578..f9682b1 100644
--- a/components/ui/PanelFigure.tsx
+++ b/components/ui/PanelFigure.tsx
@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import type { ReactNode, Ref } from "react";
 
 /**
  * A decorative data panel with a plain-language caption.
@@ -17,21 +17,24 @@ import type { ReactNode } from "react";
  *
  * `className` lands on the `<figure>` rather than the panel; both call sites
  * pass "block w-full", which behaves identically there (preflight zeroes
- * figure margin).
+ * figure margin). `ref` lands there too (HeroTerminal observes it to pause
+ * offscreen).
  */
 export function PanelFigure({
   panelClassName,
   caption,
   className,
+  ref,
   children,
 }: {
   panelClassName: string;
   caption: string;
   className?: string;
+  ref?: Ref<HTMLElement>;
   children: ReactNode;
 }) {
   return (
-    <figure className={className}>
+    <figure ref={ref} className={className}>
       <div aria-hidden className={panelClassName}>
         {children}
       </div>
diff --git a/components/ui/PostRow.tsx b/components/ui/PostRow.tsx
index 54930b3..6872b34 100644
--- a/components/ui/PostRow.tsx
+++ b/components/ui/PostRow.tsx
@@ -33,7 +33,7 @@ export function PostRow({ post, delay }: { post: PostMeta; delay: number }) {
       >
         {/* mobile-only meta line */}
         <div
-          className={`${META} flex items-baseline justify-between gap-4 opacity-50 @xl:hidden`}
+          className={`${META} flex items-baseline justify-between gap-4 opacity-60 @xl:hidden`}
         >
           <span>
             {num} <span aria-hidden>·</span>{" "}
@@ -44,7 +44,7 @@ export function PostRow({ post, delay }: { post: PostMeta; delay: number }) {
 
         {/* # */}
         <span
-          className={`${META} hidden self-start opacity-35 @xl:mt-1.5 @xl:block`}
+          className={`${META} hidden self-start opacity-60 @xl:mt-1.5 @xl:block`}
         >
           {num}
         </span>
@@ -52,7 +52,7 @@ export function PostRow({ post, delay }: { post: PostMeta; delay: number }) {
         {/* date */}
         <time
           dateTime={post.date}
-          className={`${META} hidden self-start opacity-55 @xl:mt-1.5 @xl:block`}
+          className={`${META} hidden self-start opacity-75 @xl:mt-1.5 @xl:block`}
         >
           {date}
         </time>
@@ -116,7 +116,7 @@ export function PostRow({ post, delay }: { post: PostMeta; delay: number }) {
         {/* arrow */}
         <span
           aria-hidden
-          className="hidden self-start text-lg leading-none opacity-30 transition-all duration-300 ease-out group-hover:translate-x-1.5 group-hover:text-whisper group-hover:opacity-100 @xl:mt-2 @xl:block @xl:text-right"
+          className="hidden self-start text-lg leading-none opacity-30 transition-[translate,color,opacity] duration-300 ease-out group-hover:translate-x-1.5 group-hover:text-whisper group-hover:opacity-100 @xl:mt-2 @xl:block @xl:text-right"
         >
           →
         </span>
diff --git a/components/ui/brand.tsx b/components/ui/brand.tsx
index c7a72d3..487ecb3 100644
--- a/components/ui/brand.tsx
+++ b/components/ui/brand.tsx
@@ -2,7 +2,9 @@ import type { ReactNode } from "react";
 
 /**
  * Wraps every case-insensitive `decdn` in a copy string with the whisper-green
- * brand span, normalising the casing to `deCDN` on the way through.
+ * brand span, normalising the casing to `deCDN` on the way through. The span
+ * reads `--whisper-text`, which Frame deepens on paper so the brand stays AA
+ * there (see globals.css :root).
  *
  * Lives here rather than beside any one caller because the strings it decorates
  * come from lib/copy.ts, which several components render — without a shared
@@ -12,7 +14,7 @@ import type { ReactNode } from "react";
 export function highlightBrand(s: string): ReactNode[] {
   return s.split(/(decdn)/gi).map((part, i) =>
     part.toLowerCase() === "decdn" ? (
-      <span key={i} className="text-whisper">
+      <span key={i} className="text-whisper-text">
         deCDN
       </span>
     ) : (

From aa2cdf0d43812a9389f055998c6852811f08fbea Mon Sep 17 00:00:00 2001
From: Yigit Gurbulak <yigitgurbulakk@gmail.com>
Date: Wed, 30 Sep 2026 04:37:43 +0300
Subject: [PATCH 2/3] docs: tighten audit comments and guard the brand-text
 token

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 app/globals.css                   | 35 +++++++++++++---------
 components/site/FleetStatus.tsx   |  2 +-
 components/site/HeroTerminal.tsx  | 13 +++++----
 components/ui/ComparisonRow.tsx   |  5 ++--
 components/ui/Frame.test.ts       | 48 +++++++++++++++++++++++++++++++
 components/ui/Frame.tsx           |  5 ++--
 components/ui/PanelFigure.test.ts | 13 +++++++++
 components/ui/PanelFigure.tsx     |  4 +--
 8 files changed, 100 insertions(+), 25 deletions(-)
 create mode 100644 components/ui/Frame.test.ts

diff --git a/app/globals.css b/app/globals.css
index de8c078..a8a362b 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -4,11 +4,13 @@
   --ink: #000000;
   --paper: #ffffff;
   --whisper: #0f9d6a;
-  /* Raw --whisper is ~3.5:1 on paper, short of AA for text, so text on paper
-     uses it mixed 68% with ink (~6.5:1). On ink the raw accent already clears
-     AA (~6:1). --whisper-text is what brand-coloured text reads: raw by
-     default (the page ground is ink), swapped to --whisper-deep by
-     Frame tone="paper". */
+  /* Raw --whisper is ~3.5:1 on paper (short of AA for text) and ~6:1 on
+     ink. --whisper-deep mixes it 68% with ink for ~6.5:1 on paper.
+     --whisper-text is what readable brand text uses (highlightBrand, via
+     `text-whisper-text`): raw by default, matching the body's ink ground,
+     and swapped to --whisper-deep by every Frame tone="paper". Decorative
+     glyphs and icons (prompt and arrow marks, the pin, the hero's full stop)
+     keep raw --whisper — ~3.5:1 clears the 3:1 non-text bar. */
   --whisper-deep: color-mix(in srgb, var(--whisper) 68%, var(--ink));
   --whisper-text: var(--whisper);
   /* Intentionally 0: anchor jumps land flush at viewport top (under
@@ -328,8 +330,9 @@ a.cta-primary:focus-visible {
 }
 
 /* The status link under the hero terminal. The value text takes
-   --whisper-deep (see :root) for AA on paper. The label is ink like the
-   stat labels; the dot and the arrow keep the full accent. */
+   --whisper-deep (see :root) for AA on paper — directly rather than via
+   --whisper-text, so the link holds AA even outside a paper Frame. The label
+   is ink like the stat labels; the dot and the arrow keep the full accent. */
 a.hero-status {
   color: var(--whisper-deep);
 }
@@ -376,8 +379,11 @@ a.hero-status:hover .arrow {
    Replays recent on-chain settlements from the live stats file
    (lib/stats.ts), one per cycle: tx → block → operator → bytes → paid.
    All lines share one 4.5s loop; each line fades in at its own delay.
-   Progress bar fills during the "delivered" line. Cursor blinks
-   independently. The cascade restarts every cycle. Shares the "tool
+   Progress bar fills during the "delivered" line. HeroTerminal advances to
+   the next settlement on .tl-0's animationiteration, so anything that stops
+   the cascade stops the rotation: reduced motion, the hover hold and the
+   offscreen pause below. The cursor blinks independently except offscreen.
+   The cascade restarts every cycle. Shares the "tool
    panel" vocabulary with .fleet and .faq-card: soft corners, a solid
    1px rule, a hard offset shadow. */
 
@@ -771,7 +777,8 @@ a.hero-status:hover .arrow {
 
 /* Hourly spark strip under each aggregate: one cell per hour of the 24h
    window, oldest left, each cell's height its share of the busiest hour
-   (--level, 0–1). A zero hour keeps a hairline so the strip reads as a
+   (--level, 0–1) — drawn as a scaleY of a full-height cell, so it animates
+   on the compositor. A zero hour keeps a hairline so the strip reads as a
    timeline rather than a gap. */
 .fleet-spark {
   display: flex;
@@ -787,7 +794,8 @@ a.hero-status:hover .arrow {
   flex: 1;
   height: 100%;
   background: var(--whisper);
-  /* 0.08 of the 13px strip is the ~1px hairline a zero hour keeps. */
+  /* 0.08 × the strip's 13px content box (14px height minus the 1px
+     border-bottom) ≈ the 1px hairline. Retune if either changes. */
   transform: scaleY(max(0.08, var(--level, 0)));
   transform-origin: bottom;
   transition: transform 0.6s var(--ease-term);
@@ -1119,8 +1127,9 @@ a.hero-status:hover .arrow {
    portal/focus model. */
 
 /* A 44px hit area around an 18px glyph. The box overhangs the gutter by
-   11px so the glyph sits where the old 22px button drew it, centred on the
-   nav's ~70px bar. */
+   11px and insets the bars 13px, so the glyph sits 2px inside the gutter;
+   top: 13px centres it on the nav's ~70px bar (py-5 + 30px wordmark, see
+   :root). Retune if the nav height changes. */
 .mm-toggle {
   position: fixed;
   top: 13px;
diff --git a/components/site/FleetStatus.tsx b/components/site/FleetStatus.tsx
index 22feb96..bd4c5a7 100644
--- a/components/site/FleetStatus.tsx
+++ b/components/site/FleetStatus.tsx
@@ -20,7 +20,7 @@ const EMPTY_LABEL = {
 const FLAT = Array<number>(FLEET_WINDOW_HOURS).fill(0);
 
 /** One hourly spark strip: a cell per hour, its height the hour's share of
- *  the window's busiest hour. */
+ *  the window's busiest hour (drawn as a scaleY in globals.css). */
 function Spark({ levels }: { levels: number[] }) {
   return (
     <div className="fleet-spark">
diff --git a/components/site/HeroTerminal.tsx b/components/site/HeroTerminal.tsx
index 8540e27..3be26de 100644
--- a/components/site/HeroTerminal.tsx
+++ b/components/site/HeroTerminal.tsx
@@ -12,11 +12,14 @@ export function HeroTerminal({ className }: { className?: string }) {
   const [index, setIndex] = useState(0);
   const figureRef = useRef<HTMLElement>(null);
 
-  // The next session is cued by the cascade itself: each loop of the first
-  // line's 4.5s animation advances one. Anything that stops the CSS stops
-  // the cycle with it — reduced motion (no animation), hovering the panel
-  // (holds the lines, see globals.css), a background tab (animations don't
-  // run) and scrolling out of view (paused below). A timer would keep
+  // The next session is cued by the cascade itself: each time the first
+  // line's 4.5s animation completes an iteration, advance one (the key below
+  // then remounts the body, restarting the cascade). Anything that stops the
+  // CSS stops the rotation with it — reduced motion (no animation), hovering
+  // the panel on a pointer device (holds the lines, see globals.css), a
+  // background tab (no frames render, so no iteration events; at most one
+  // fires on return) and scrolling out of view (the observer below sets
+  // data-offscreen; globals.css pauses the lines). A timer would keep
   // swapping content through all of those.
   const advance = (e: AnimationEvent<HTMLDivElement>) => {
     if (e.target !== e.currentTarget || sessions.length < 2) return;
diff --git a/components/ui/ComparisonRow.tsx b/components/ui/ComparisonRow.tsx
index c2cdf01..479edd2 100644
--- a/components/ui/ComparisonRow.tsx
+++ b/components/ui/ComparisonRow.tsx
@@ -15,8 +15,9 @@ function Rate({ value, strike }: { value: string; strike?: true }) {
     <>
       {figure}
       {unit && (
-        // Struck, the unit already sits inside the <s>'s 55%; dimming it
-        // again would take 11px text under AA on ink.
+        // Struck, the unit already inherits the <s>'s 55%. Stacking
+        // opacity-70 on top (≈38% effective, ~3.4:1) would put 11px text
+        // under AA on the ink Compare section.
         <span
           className={`meta ml-1 align-baseline ${strike ? "" : "opacity-70"}`}
         >
diff --git a/components/ui/Frame.test.ts b/components/ui/Frame.test.ts
new file mode 100644
index 0000000..c68bf10
--- /dev/null
+++ b/components/ui/Frame.test.ts
@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createElement, isValidElement } from "react";
+import { describe, expect, it } from "vitest";
+import { Frame } from "./Frame";
+import { highlightBrand } from "./brand";
+import { asElement, attrs } from "@/test-utils/react-tree";
+
+// The paper-contrast fix is a string contract across three files: Frame sets
+// --whisper-text on paper, highlightBrand reads it through `text-whisper-text`,
+// and globals.css declares the tokens that utility resolves against. A typo
+// in any one of them makes Tailwind emit nothing or the variable fall back to
+// raw --whisper (~3.5:1 on white) — lint, typecheck and build all stay green.
+// These pin the names; the rendered colour itself is outside vitest's reach.
+
+const PAPER_SWAP = "[--whisper-text:var(--whisper-deep)]";
+
+const sectionClass = (tone: "ink" | "paper") =>
+  String(
+    attrs(
+      asElement(
+        Frame({ id: "t", tone, children: createElement("p", null, "x") }),
+      ),
+    ).className,
+  );
+
+describe("brand-text contrast wiring", () => {
+  it("points --whisper-text at the deep whisper on paper only", () => {
+    expect(sectionClass("paper")).toContain(PAPER_SWAP);
+    expect(sectionClass("ink")).not.toContain(PAPER_SWAP);
+  });
+
+  it("colours the brand span through --whisper-text", () => {
+    const spans = highlightBrand("run decdn").filter(isValidElement);
+    expect(spans).toHaveLength(1);
+    expect(attrs(asElement(spans[0])).className).toBe("text-whisper-text");
+  });
+
+  it("declares the tokens the utility and the swap resolve against", () => {
+    const css = fs.readFileSync(
+      path.join(process.cwd(), "app", "globals.css"),
+      "utf8",
+    );
+    expect(css).toMatch(/--whisper-deep:/);
+    expect(css).toMatch(/--whisper-text:/);
+    expect(css).toMatch(/--color-whisper-text:\s*var\(--whisper-text\)/);
+  });
+});
diff --git a/components/ui/Frame.tsx b/components/ui/Frame.tsx
index 6084bb5..0d3b8ab 100644
--- a/components/ui/Frame.tsx
+++ b/components/ui/Frame.tsx
@@ -10,8 +10,9 @@ type FrameProps = {
   children: ReactNode;
 };
 
-// Paper also swaps brand-coloured text to the deeper whisper, which is what
-// clears AA on white (see --whisper-text in globals.css).
+// Paper also points --whisper-text (read by highlightBrand's span) at
+// --whisper-deep, which clears AA on white. Plain `text-whisper` is not
+// swapped; see globals.css :root.
 const TONE_CLASS: Record<Tone, string> = {
   ink: "bg-ink text-paper",
   paper: "bg-paper text-ink [--whisper-text:var(--whisper-deep)]",
diff --git a/components/ui/PanelFigure.test.ts b/components/ui/PanelFigure.test.ts
index 3f3d88b..cb6a19e 100644
--- a/components/ui/PanelFigure.test.ts
+++ b/components/ui/PanelFigure.test.ts
@@ -25,6 +25,19 @@ describe("PanelFigure", () => {
     expect(attrs(figure).className).toBe("block w-full");
   });
 
+  // HeroTerminal pauses offscreen through an IntersectionObserver on this
+  // ref; typecheck wouldn't notice the prop being accepted but not forwarded.
+  it("forwards the caller's ref to the figure", () => {
+    const ref = { current: null };
+    const withRef = PanelFigure({
+      panelClassName: "fleet",
+      caption: CAPTION,
+      ref,
+      children: null,
+    });
+    expect(attrs(asElement(withRef)).ref).toBe(ref);
+  });
+
   it("puts the caller's panel class on the hidden panel, not the figure", () => {
     const panel = findAll(tree, "div").filter(
       (el) => attrs(el)["aria-hidden"] === true,
diff --git a/components/ui/PanelFigure.tsx b/components/ui/PanelFigure.tsx
index f9682b1..7ce3172 100644
--- a/components/ui/PanelFigure.tsx
+++ b/components/ui/PanelFigure.tsx
@@ -17,8 +17,8 @@ import type { ReactNode, Ref } from "react";
  *
  * `className` lands on the `<figure>` rather than the panel; both call sites
  * pass "block w-full", which behaves identically there (preflight zeroes
- * figure margin). `ref` lands there too (HeroTerminal observes it to pause
- * offscreen).
+ * figure margin). `ref` is forwarded to the `<figure>` too (e.g. for an
+ * IntersectionObserver).
  */
 export function PanelFigure({
   panelClassName,

From cd0c3187ae5145aadb539dad02382f961327ead1 Mon Sep 17 00:00:00 2001
From: Yigit Gurbulak <yigitgurbulakk@gmail.com>
Date: Wed, 30 Sep 2026 05:04:27 +0300
Subject: [PATCH 3/3] fix(hero): keep the terminal cycling while hovered

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 app/globals.css                  | 17 ++---------------
 components/site/HeroTerminal.tsx |  3 +--
 2 files changed, 3 insertions(+), 17 deletions(-)

diff --git a/app/globals.css b/app/globals.css
index a8a362b..11e6d14 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -381,8 +381,8 @@ a.hero-status:hover .arrow {
    All lines share one 4.5s loop; each line fades in at its own delay.
    Progress bar fills during the "delivered" line. HeroTerminal advances to
    the next settlement on .tl-0's animationiteration, so anything that stops
-   the cascade stops the rotation: reduced motion, the hover hold and the
-   offscreen pause below. The cursor blinks independently except offscreen.
+   the cascade stops the rotation: reduced motion and the offscreen pause
+   below. The cursor blinks independently except offscreen.
    The cascade restarts every cycle. Shares the "tool
    panel" vocabulary with .fleet and .faq-card: soft corners, a solid
    1px rule, a hard offset shadow. */
@@ -577,19 +577,6 @@ a.hero-status:hover .arrow {
   }
 }
 
-/* Hovering the terminal holds the current settlement fully drawn: the
-   cascade stops, so no animationiteration fires and HeroTerminal doesn't
-   advance. Leaving re-applies the animation, which replays the cascade
-   from the top. The cursor keeps blinking. */
-@media (hover: hover) {
-  .terminal:hover .tl,
-  .terminal:hover .progress-fill {
-    animation: none;
-    opacity: 1;
-    transform: none;
-  }
-}
-
 /* Set by HeroTerminal while the panel is scrolled out of view. */
 [data-offscreen] .terminal :is(.tl, .progress-fill, .cursor) {
   animation-play-state: paused;
diff --git a/components/site/HeroTerminal.tsx b/components/site/HeroTerminal.tsx
index 3be26de..ed1e0ea 100644
--- a/components/site/HeroTerminal.tsx
+++ b/components/site/HeroTerminal.tsx
@@ -15,8 +15,7 @@ export function HeroTerminal({ className }: { className?: string }) {
   // The next session is cued by the cascade itself: each time the first
   // line's 4.5s animation completes an iteration, advance one (the key below
   // then remounts the body, restarting the cascade). Anything that stops the
-  // CSS stops the rotation with it — reduced motion (no animation), hovering
-  // the panel on a pointer device (holds the lines, see globals.css), a
+  // CSS stops the rotation with it — reduced motion (no animation), a
   // background tab (no frames render, so no iteration events; at most one
   // fires on return) and scrolling out of view (the observer below sets
   // data-offscreen; globals.css pauses the lines). A timer would keep