@hanzo/design 0.4.0 → 0.4.1

package/tailwind.css

@@ -39,9 +39,25 @@
 /* Hanzo is monochrome. One hue rendered through an opacity ladder.
    Base ladder = Tailwind neutral (tailwind.config.ts). Semantic names match
    hanzo.ai's CSS variables exactly, so code copies over 1:1.
-   DARK IS THE DEFAULT THEME (hanzo.ai mounts ThemeProvider defaultTheme="dark"). */
+   DARK IS THE DEFAULT THEME (hanzo.ai mounts ThemeProvider defaultTheme="dark").
+
+   The dark palette is derived from the chat surface in hanzoai/extension
+   (packages/browser/src/sidebar.css), which is the reference aesthetic: a
+   #0a0a0a ground, #fafafa ink, and boundaries drawn as LOW-ALPHA HAIRLINES.
+   Two properties of that reference are load-bearing and easy to lose:
+
+   1. Borders are alpha, not hex. rgb(255 255 255 / .10) composites correctly on
+      #0a0a0a AND on #262626; a solid #1f1f1f reads on the page and vanishes the
+      moment it lands on a lifted surface — which is why anyone who needed a
+      visible edge reached past it for the CONTROL rung and got a wireframe.
+   2. Surfaces lift by tiny steps (0a -> 0f -> 17 -> 26), and ink is a graded
+      ramp (#fafafa -> .78 -> .55 -> #a3a3a3), not one flat white. Pure #ffffff
+      on pure #000000 is 21:1 — the maximum-contrast pair that exists, and it
+      halates. #fafafa on #0a0a0a is 18.1:1: still far past AAA, visibly softer. */
 
 :root{
+  color-scheme:dark;
+
   /* ——— base neutral ladder ——— */
   --neutral-50:#FAFAFA;
   --neutral-100:#F5F5F5;
@@ -61,45 +77,97 @@
   --hanzo-white:#FFFFFF;
 
   /* ——— the opacity ladder: the real palette ——— */
+  /* Every rung below .30 is a HAIRLINE or a LIFT — the two things this system
+     draws with. The rungs are the reference's own values, not a rounded ramp. */
   --white-05:rgb(255 255 255 / .05);
+  --white-06:rgb(255 255 255 / .06);
+  --white-08:rgb(255 255 255 / .08);
   --white-10:rgb(255 255 255 / .10);
   --white-15:rgb(255 255 255 / .15);
+  --white-16:rgb(255 255 255 / .16);
   --white-20:rgb(255 255 255 / .20);
+  --white-22:rgb(255 255 255 / .22);
   --white-30:rgb(255 255 255 / .30);
   --white-40:rgb(255 255 255 / .40);
+  --white-55:rgb(255 255 255 / .55);
   --white-60:rgb(255 255 255 / .60);
+  --white-78:rgb(255 255 255 / .78);
   --white-80:rgb(255 255 255 / .80);
 
   /* ——— semantic aliases (dark, the default) ——— */
-  --background:#000000;
-  --foreground:#ededed;
-  --card:#0a0a0a;
-  --card-foreground:#f5f5f5;
-  --popover:#0a0a0a;
-  --popover-foreground:#f5f5f5;
-  --primary:#ffffff;
-  --primary-foreground:#000000;
-  --secondary:#1a1a1a;
-  --secondary-foreground:#f5f5f5;
-  --muted:#101010;
-  --muted-foreground:#888888;
-  --accent:#1a1a1a;
-  --accent-foreground:#f5f5f5;
+  --background:#0a0a0a;
+  --foreground:#fafafa;
+  --card:#0f0f0f;
+  --card-foreground:#fafafa;
+  --popover:#0f0f0f;
+  --popover-foreground:#fafafa;
+  --primary:#fafafa;
+  --primary-hover:#d4d4d4;
+  --primary-foreground:#0a0a0a;
+  --secondary:#262626;
+  --secondary-foreground:#fafafa;
+  --muted:#171717;
+  --muted-foreground:#a3a3a3;
+  --accent:#262626;
+  --accent-foreground:#fafafa;
   --destructive:#666666;
-  --destructive-foreground:#f5f5f5;
-  --border:#1f1f1f;
-  --input:#1f1f1f;
+  --destructive-foreground:#fafafa;
+
+  /* ——— boundaries ———
+     THREE tiers, and the split is the whole point. The first two are DECORATIVE:
+     they separate content, WCAG imposes no ratio on them, and they must stay
+     quiet. The third is PERCEIVABLE: it is the edge that IS the affordance.
+
+       --border          the hairline. Every card, panel, divider, list row.
+       --border-strong   the SAME hairline, one step up. Hover, active, emphasis.
+       --border-control  a control's edge — input, select, textarea, checkbox,
+                         switch. Must clear 3:1 on every surface in both themes
+                         (WCAG 1.4.11); check-tokens.mjs pins it.
+
+     Before this split there were only two rungs and they were an octave apart:
+     --border at #1f1f1f (1.27:1, invisible on anything lifted) and
+     --border-strong at --neutral-500 (4.43:1). Nothing sat between, so every
+     surface that wanted a border it could actually SEE reached for the control
+     rung — and a 1px mid-grey box around a card on near-black is a wireframe.
+     That is the "garish outlines" complaint, and it is fixed by having a middle.
+
+     A boundary that is WCAG-perceivable on a near-black ground IS a mid-grey;
+     that cannot be tuned away. So it is not tuned away — it is NAMED, so it can
+     only be spent where it is owed. "strong" is a degree word and will always be
+     read as one; "control" is a duty.
+
+     Which ladder a boundary is cut from follows from that, and is the whole
+     rule: DECORATIVE edges come off the ALPHA ladder, because they owe quiet
+     and they must composite over whatever surface they land on. CONTROL edges
+     come off the NEUTRAL ladder, because they owe a contrast ratio, and a ratio
+     you can only meet at a fixed value is not something to express as alpha.
+     --border-focus is therefore one NEUTRAL rung above --border-control, not an
+     alpha step: a focused field has to read brighter than a resting one, and
+     the resting one already sits at the WCAG floor. */
+  --border:var(--white-10);
+  --border-strong:var(--white-16);
+  --border-control:var(--neutral-500);   /* 4.43:1 worst case — see --ring */
+  --border-focus:var(--neutral-400);     /* one rung up: the field is focused  */
+  --input:var(--border-control);         /* shadcn `border-input` — a control  */
   /* A focus indicator is a NON-TEXT CONTRAST target: WCAG 2.4.11/1.4.11 require
      3:1 against every surface it can land on. --neutral-500 is the only rung on
-     this ladder that clears 3:1 on all of them — #000000, #0a0a0a, #101010,
-     #1a1a1a, AND the light theme's #ffffff/#f5f5f5 — so one value serves both
+     this ladder that clears 3:1 on all of them — #0a0a0a, #0f0f0f, #171717,
+     #262626, AND the light theme's #ffffff/#fafafa — so one value serves both
      themes. (Was #333333 = 1.66:1 on --background: not a focus indicator.) */
   --ring:var(--neutral-500);
   --brand:#e4e4e7;
   --brand-foreground:#09090b;
   --brand-muted:#a3a3a3;
   --black:#000000;
-  --white:#f5f5f5;
+  --white:#fafafa;
+  --selection:var(--white-20);
+
+  /* ——— glass: the lift ———
+     How a surface rises WITHOUT a block fill. An alpha-white wash composites
+     over whatever it lands on, so one value works on the page, on a card and
+     inside a popover. This is the mechanism behind the reference's depth. */
+  --glass:var(--white-05);
+  --glass-strong:var(--white-08);
 
   /* ——— surface recipes (card fills used across hanzo.ai) ——— */
   --surface-page:var(--background);
@@ -109,29 +177,22 @@
   --surface-overlay:rgb(10 10 10 / .95);     /* dropdown / popover panels       */
   --surface-header:rgb(0 0 0 / .7);          /* fixed nav, with backdrop blur   */
   --surface-scrim:rgb(0 0 0 / .8);           /* the dialog / sheet backdrop     */
-  /* Boundaries come in two kinds and they are NOT interchangeable.
-     DECORATIVE (--border, --border-hairline, --border-card): separates content;
-     WCAG imposes no ratio. Keep them quiet.
-     PERCEIVABLE (--border-strong): identifies a CONTROL — an input edge, a
-     switch, a checkbox — and must clear 3:1 (WCAG 1.4.11) on every surface.
-     Reach for --border-strong whenever the boundary IS the affordance. */
-  --border-hairline:var(--neutral-800);
-  --border-card:var(--white-10);
-  --border-strong:var(--neutral-500);   /* 3.59:1 worst case — see --ring */
 
   /* ——— the numeric surface ladder ——— */
   /* Aliases onto the semantic canvases above, so a brand fork that retunes
      --card/--muted/--secondary retunes the ladder with it and the light theme
-     inverts for free. Ascending lift: 0 is the page, 3 is a hovered control. */
+     inverts for free. Ascending lift: 0 is the page, 3 is a hovered control.
+     Dark resolves to the reference's own ladder — 0a / 0f / 17 / 26. */
   --surface-0:var(--background);
   --surface-1:var(--card);
   --surface-2:var(--muted);
   --surface-3:var(--secondary);
 
-  /* ——— text ranks ——— */
-  --text-primary:var(--pure-white);
-  --text-secondary:var(--white-80);
-  --text-tertiary:var(--white-60);
+  /* ——— text ranks ———
+     A graded ramp, not one flat white. The steps are the reference's. */
+  --text-primary:#fafafa;
+  --text-secondary:var(--white-78);
+  --text-tertiary:var(--white-55);
   --text-helper:var(--muted-foreground);
   --text-disabled:var(--white-30);
 
@@ -146,47 +207,55 @@
   --chrome-dot-green:rgb(34 197 94 / .6);
 }
 
-/* Light theme — the same tokens, inverted. Rare: only /brand-style docs pages. */
+/* Light theme — the same tokens, inverted.
+   The white-opacity ladder does NOT invert: --white-16 is white-on-white here.
+   So EVERY token whose dark value is a --white-* rung must be restated below,
+   and check-tokens.mjs fails the build if one is missed — that class of bug is
+   silent (the border simply stops existing) and has shipped before. */
 .light{
+  color-scheme:light;
   --background:#ffffff;
   --foreground:#0a0a0a;
-  --card:#f5f5f5;
+  /* A ladder, not four names for #f5f5f5. Light lifts by the same tiny steps
+     dark does — ~2% per rung — so --surface-0..3 mean something in both themes. */
+  --card:#fafafa;
   --card-foreground:#0a0a0a;
   --popover:#ffffff;
   --popover-foreground:#0a0a0a;
   --primary:#0a0a0a;
-  --primary-foreground:#ffffff;
-  --secondary:#f5f5f5;
+  --primary-hover:#262626;
+  --primary-foreground:#fafafa;
+  --secondary:#ededed;
   --secondary-foreground:#0a0a0a;
   --muted:#f5f5f5;
   --muted-foreground:#525252;
-  --accent:#f5f5f5;
+  --accent:#ededed;
   --accent-foreground:#0a0a0a;
   --destructive:#999999;
   --destructive-foreground:#ffffff;
-  --border:#e5e5e5;
-  --input:#e5e5e5;
+  --border:rgb(0 0 0 / .10);
+  --border-strong:rgb(0 0 0 / .16);
+  --border-control:var(--neutral-500);  /* 4.74:1 on #ffffff — conformant here too */
+  --border-focus:var(--neutral-600);    /* one rung DOWN — darker reads as brighter here */
+  --input:var(--border-control);
   /* Same rung as dark: #d4d4d4 measured 1.48:1 on white and could not carry a
      focus indicator either. --neutral-500 is 4.74:1 on #ffffff / 4.38:1 on
      #f5f5f5, so ONE value is conformant in both themes. */
   --ring:var(--neutral-500);
   --black:#0a0a0a;
   --white:#ffffff;
-  --surface-card:#f5f5f5;
+  --selection:rgb(0 0 0 / .16);
+  --glass:rgb(0 0 0 / .04);
+  --glass-strong:rgb(0 0 0 / .07);
+  --surface-card:#fafafa;
   --surface-card-emphasis:#ffffff;
-  --surface-card-quiet:#fafafa;
+  --surface-card-quiet:#fcfcfc;
   --surface-overlay:rgb(255 255 255 / .95);
   --surface-header:rgb(255 255 255 / .8);
   --surface-scrim:rgb(0 0 0 / .5);
-  --border-hairline:var(--neutral-200);
-  --border-card:rgb(0 0 0 / .1);
-  --border-strong:var(--neutral-500);   /* was --neutral-300 = 1.48:1 on white */
-  /* The white-opacity ladder does NOT invert, so --white-40 is white-on-white
-     here (1.00:1). Anything that needs a visible edge in BOTH themes must use
-     --border-strong, never a --white-* rung. */
   --text-primary:var(--neutral-950);
-  --text-secondary:rgb(10 10 10 / .8);
-  --text-tertiary:rgb(10 10 10 / .6);
+  --text-secondary:rgb(10 10 10 / .78);
+  --text-tertiary:rgb(10 10 10 / .55);
   --text-disabled:rgb(10 10 10 / .3);
 }
 
@@ -229,6 +298,19 @@
   --font-size-8xl:var(--text-8xl);
   --font-size-9xl:var(--text-9xl);
 
+  /* The size a FORM CONTROL renders at — and the ONE step in this scale that is
+     not a constant. iOS Safari zooms the viewport whenever a focused input
+     computes below 16px, and this scale's base is 14px, so every surface that
+     sized a field from --text-sm or --text-base bought the zoom.
+
+     It has to be a TOKEN rather than a rule because a control's size is almost
+     always set inline (every component in components/forms does), and an inline
+     style outranks any stylesheet — including a media query. A var() resolves
+     per-device inside that inline style, so this is the only construction that
+     actually reaches the control. Fields ask for --text-control; nothing else
+     should. */
+  --text-control:var(--text-sm);
+
   --weight-normal:400;
   --weight-medium:500;
   --weight-semibold:600;
@@ -257,6 +339,14 @@
   --type-eyebrow:600 0.625rem/1 var(--font-sans);
 }
 
+/* On touch, a control goes to 16px. Below that iOS Safari zooms the viewport on
+   focus and never zooms back out, which is the single most common way a mobile
+   form feels broken. pointer:coarse is the real signal — a desktop mouse keeps
+   the compact 13px field. */
+@media (pointer:coarse){
+  :root{--text-control:1rem}
+}
+
 /* ── tokens/spacing.css ─────────────────────────────────────── */
 /* Spacing: the 4px Tailwind ramp is what ships. The golden-ratio ramp below is
    declared in hanzo.ai's tailwind.config.ts (legacy v3 config, kept for
@@ -290,18 +380,57 @@
   --golden-9:11.749rem;
   --golden-split:38.2% 61.8%; /* @kind other */
 
-  /* layout rules (DESIGN.md §1.3) */
+  /* layout rules (DESIGN.md §1.3) —
+     MOBILE-FIRST: the values authored here are the PHONE values, and the
+     min-width block at the bottom of this file scales them up. A surface that
+     uses the raw token therefore gets a layout that already breathes correctly
+     at 390px, with no media query of its own. (This is also the value the
+     generator captures for tokens.gen.ts — first occurrence wins, and the
+     authored default is the small one.) */
   --container-max:80rem;      /* max-w-7xl — grids            */
   --container-prose:48rem;    /* max-w-3xl — centered text    */
   --container-wide:72rem;     /* max-w-6xl — landing sections */
-  --gutter:1rem;              /* px-4                          */
+  /* The page gutter also clears a notch. env() is 0px on every device without
+     one, so this is exactly `1rem` in the ordinary case and the safe inset when
+     there is something to avoid — no per-app work, no landscape clipping.
+     Requires `<meta name="viewport" content="…,viewport-fit=cover">` on the
+     host page; without it the UA reports 0 and the max() is inert, not wrong. */
+  --gutter:max(1rem,var(--safe-left),var(--safe-right));
   --gutter-sm:1.5rem;         /* sm:px-6                       */
   --gutter-lg:2rem;           /* lg:px-8                       */
-  --section-y:4rem;           /* py-16 — content sections      */
-  --section-y-lg:6rem;        /* py-24 — landing sections      */
-  --hero-y:5rem;              /* py-20 …                       */
-  --hero-y-lg:8rem;           /* … lg:py-32                    */
-  --header-height:4rem;
+  --section-y:2.5rem;         /* py-10 on a phone → py-16 at md */
+  --section-y-lg:3.5rem;      /* py-14 on a phone → py-24 at md */
+  --hero-y:3rem;              /* py-12 on a phone → py-20 at md */
+  --hero-y-lg:4.5rem;         /* py-18 on a phone → py-32 at md */
+  --header-height:3.5rem;     /* 56px is the phone bar; 64px from md */
+
+  /* ——— touch ——— */
+  /* 44px is the floor a pointer-coarse target may render at (Apple HIG 44pt /
+     WCAG 2.5.5 AAA / 2.5.8 AA's 24px, taken at the higher bar). base.css spends
+     it automatically under `@media (pointer:coarse)`, so a button does not have
+     to opt in. It was previously a bare `min-height:44px` literal in
+     hanzoai/id's stylesheet — one app knowing something the system did not. */
+  --tap-target:44px;
+
+  /* ——— safe areas ——— */
+  /* The notch/home-indicator insets, named once. Anything pinned to a viewport
+     edge — a fixed header, a bottom bar, a sheet — adds the matching one. */
+  --safe-top:env(safe-area-inset-top,0px);
+  --safe-right:env(safe-area-inset-right,0px);
+  --safe-bottom:env(safe-area-inset-bottom,0px);
+  --safe-left:env(safe-area-inset-left,0px);
+}
+
+/* Scale up from the phone. `md` (48rem) is the same breakpoint grid.css
+   declares and Tailwind compiles against — one value, not two that agree. */
+@media (min-width:48rem){
+  :root{
+    --section-y:4rem;         /* py-16 — content sections      */
+    --section-y-lg:6rem;      /* py-24 — landing sections      */
+    --hero-y:5rem;            /* py-20 …                       */
+    --hero-y-lg:8rem;         /* … lg:py-32                    */
+    --header-height:4rem;
+  }
 }
 
 /* ── tokens/grid.css ─────────────────────────────────────── */
@@ -509,19 +638,36 @@
    The same trap already bit `text-decoration` here once (see the a:hover note
    below). It was fixed by deleting that one declaration, which left the identical
    defect in `color` untouched. Layering fixes the whole class: these are
-   DEFAULTS, and a default must lose to anything an app states deliberately. */
+   DEFAULTS, and a default must lose to anything an app states deliberately.
+
+   The rules added for controls, media and touch go one step further and wrap
+   their selectors in :where(), which has ZERO specificity. @layer decides who
+   wins BETWEEN layers; :where() decides who wins INSIDE this one. An app that
+   ships its own reset — `input { … }`, `img { … }` — very often lands in the
+   same base layer, and these defaults have to lose that collision too. */
 @layer base {
   *{box-sizing:border-box;border-color:var(--border)}
-  html{-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;scroll-behavior:smooth}
+  html{
+    -webkit-font-smoothing:antialiased;
+    text-rendering:optimizeLegibility;
+    scroll-behavior:smooth;
+    /* iOS inflates text when a phone is rotated to landscape unless this is
+       pinned. It is the single most common reason a mobile layout that was
+       verified in portrait comes apart on its side. */
+    -webkit-text-size-adjust:100%;
+  }
   /* Each font-family carries the stack as a literal fallback. --font-sans lives in
      tokens/fonts.css, which a surface may legitimately import separately; without
      the fallback an unresolved var() makes font-family invalid and the UA drops to
      its SERIF default — the whole console silently rendered in Times. */
-  body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings)}
+  body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings);overflow-wrap:break-word}
   h1,h2,h3,h4{margin:0;font-family:var(--font-display,var(--font-sans,ui-sans-serif,system-ui,sans-serif));letter-spacing:var(--tracking-tight);color:var(--text-primary)}
   p{margin:0;text-wrap:pretty}
   code,pre,kbd{font-family:var(--font-mono,ui-monospace,SFMono-Regular,monospace)}
-  a{color:var(--text-primary);text-decoration:none;text-underline-offset:4px;transition:color var(--duration-fast) var(--ease-out)}
+  /* No `transition` here: the shared interactive rule below states one, and an
+     `a` selector (0,0,1) would outrank that :where() (0,0,0) and replace the
+     whole shorthand — anchors would transition colour and nothing else. */
+  a{color:var(--text-primary);text-decoration:none;text-underline-offset:4px}
   /* Underline is the accessible affordance for a link in RUNNING TEXT and a visual
      bug everywhere else: nav items, cards and anchor-buttons are all <a> too, so a
      blanket `a:hover` underlined every one of them on every surface that imports
@@ -530,8 +676,79 @@
      value `a` already has — a no-op that only served to outrank a component's own
      hover colour. */
   :is(p,li,blockquote,dd,dt,td,th,figcaption) a:hover{text-decoration:underline}
+
+  /* ——— the smooth ———
+     Every interactive element in the reference transitions its colour, its fill
+     and its EDGE. That is most of what separates "classy and smooth" from a
+     correct set of colours: a hairline that steps from .10 to .16 instantly
+     reads as a flicker, and over 150ms reads as a response. Granted once, here,
+     rather than restated on every component. tokens/motion.css already zeroes
+     all of it under prefers-reduced-motion. */
+  :where(a,button,[role=button],input,select,textarea,summary,[tabindex]){
+    transition:color var(--duration-fast) var(--ease-out),
+               background-color var(--duration-fast) var(--ease-out),
+               border-color var(--duration-fast) var(--ease-out),
+               box-shadow var(--duration-fast) var(--ease-out),
+               opacity var(--duration-fast) var(--ease-out);
+  }
+
+  /* ——— controls ———
+     A bare <input> renders in the UA's face (Arial) at the UA's size with the
+     UA's border, which puts two typefaces and a foreign blue focus ring inside
+     Hanzo cards on every surface that has not styled its own fields yet. The
+     rules below are what a control looks like here. --border-control, NOT
+     --border: the boundary IS the affordance, so it is the rung that owes 3:1. */
+  :where(input,select,textarea,button){font:inherit;color:inherit}
+  :where(input:not([type=checkbox]):not([type=radio]):not([type=range]):not([type=color]),select,textarea){
+    background:var(--surface-2);
+    border:1px solid var(--border-control);
+    border-radius:var(--radius-sm);
+    padding:0 var(--space-3);
+  }
+  :where(textarea){padding:var(--space-2) var(--space-3);resize:vertical}
+  :where(input,select,textarea):focus-visible{border-color:var(--border-focus)}
+  :where(input,textarea)::placeholder{color:var(--text-disabled)}
+  :where(input,select,textarea,button):disabled{opacity:.5;cursor:not-allowed}
+  :where(button,[role=button],summary,label,select){cursor:pointer}
+
+  /* ——— media ———
+     An image, a video or an embed at its intrinsic width is the usual cause of a
+     390px page that scrolls sideways. */
+  :where(img,svg,video,canvas,iframe,picture,object){max-width:100%}
+  :where(img,video){height:auto}
+  /* A code block scrolls ITSELF rather than widening the document. */
+  :where(pre){overflow-x:auto}
+
+  /* ——— touch ———
+     Everything a finger aims at clears 44px, and every field renders at 16px so
+     iOS does not zoom the viewport on focus. Both are keyed on pointer:coarse —
+     the actual signal — so a desktop mouse still gets compact controls. This is
+     the whole of "mobile-first without per-app work": an app that never thought
+     about phones still has hittable buttons and a viewport that stays put. */
+  @media (pointer:coarse){
+    :where(button,[role=button],a[role=button],summary,select,textarea,
+           input:not([type=checkbox]):not([type=radio]):not([type=hidden])){
+      min-height:var(--tap-target);
+    }
+    :where(input,select,textarea){font-size:var(--text-control)}
+    /* A checkbox, radio or switch must NOT grow to 44px — the box is 16px
+       because that is what a checkbox looks like. What has to reach 44px is the
+       area a finger may land in, so the target is expanded with a centred
+       pseudo-element that changes nothing about layout or paint. WCAG 2.5.8 puts
+       the floor at 24px; a 16px box misses it, and every one of these ships at
+       16px. */
+    :where([role=checkbox],[role=radio],[role=switch],input[type=checkbox],input[type=radio]){position:relative}
+    :where([role=checkbox],[role=radio],[role=switch],input[type=checkbox],input[type=radio])::after{
+      content:'';position:absolute;top:50%;left:50%;
+      width:var(--tap-target);height:var(--tap-target);
+      transform:translate(-50%,-50%);
+    }
+  }
+
   :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
-  ::selection{background:var(--white-20);color:#fff}
+  /* --white-20 is white-on-white in the light theme, so selection reads through
+     --selection, which BOTH themes define. */
+  ::selection{background:var(--selection);color:var(--text-primary)}
 }
 
 

package/tokens/base.css

@@ -12,19 +12,36 @@
    The same trap already bit `text-decoration` here once (see the a:hover note
    below). It was fixed by deleting that one declaration, which left the identical
    defect in `color` untouched. Layering fixes the whole class: these are
-   DEFAULTS, and a default must lose to anything an app states deliberately. */
+   DEFAULTS, and a default must lose to anything an app states deliberately.
+
+   The rules added for controls, media and touch go one step further and wrap
+   their selectors in :where(), which has ZERO specificity. @layer decides who
+   wins BETWEEN layers; :where() decides who wins INSIDE this one. An app that
+   ships its own reset — `input { … }`, `img { … }` — very often lands in the
+   same base layer, and these defaults have to lose that collision too. */
 @layer base {
   *{box-sizing:border-box;border-color:var(--border)}
-  html{-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;scroll-behavior:smooth}
+  html{
+    -webkit-font-smoothing:antialiased;
+    text-rendering:optimizeLegibility;
+    scroll-behavior:smooth;
+    /* iOS inflates text when a phone is rotated to landscape unless this is
+       pinned. It is the single most common reason a mobile layout that was
+       verified in portrait comes apart on its side. */
+    -webkit-text-size-adjust:100%;
+  }
   /* Each font-family carries the stack as a literal fallback. --font-sans lives in
      tokens/fonts.css, which a surface may legitimately import separately; without
      the fallback an unresolved var() makes font-family invalid and the UA drops to
      its SERIF default — the whole console silently rendered in Times. */
-  body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings)}
+  body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings);overflow-wrap:break-word}
   h1,h2,h3,h4{margin:0;font-family:var(--font-display,var(--font-sans,ui-sans-serif,system-ui,sans-serif));letter-spacing:var(--tracking-tight);color:var(--text-primary)}
   p{margin:0;text-wrap:pretty}
   code,pre,kbd{font-family:var(--font-mono,ui-monospace,SFMono-Regular,monospace)}
-  a{color:var(--text-primary);text-decoration:none;text-underline-offset:4px;transition:color var(--duration-fast) var(--ease-out)}
+  /* No `transition` here: the shared interactive rule below states one, and an
+     `a` selector (0,0,1) would outrank that :where() (0,0,0) and replace the
+     whole shorthand — anchors would transition colour and nothing else. */
+  a{color:var(--text-primary);text-decoration:none;text-underline-offset:4px}
   /* Underline is the accessible affordance for a link in RUNNING TEXT and a visual
      bug everywhere else: nav items, cards and anchor-buttons are all <a> too, so a
      blanket `a:hover` underlined every one of them on every surface that imports
@@ -33,6 +50,77 @@
      value `a` already has — a no-op that only served to outrank a component's own
      hover colour. */
   :is(p,li,blockquote,dd,dt,td,th,figcaption) a:hover{text-decoration:underline}
+
+  /* ——— the smooth ———
+     Every interactive element in the reference transitions its colour, its fill
+     and its EDGE. That is most of what separates "classy and smooth" from a
+     correct set of colours: a hairline that steps from .10 to .16 instantly
+     reads as a flicker, and over 150ms reads as a response. Granted once, here,
+     rather than restated on every component. tokens/motion.css already zeroes
+     all of it under prefers-reduced-motion. */
+  :where(a,button,[role=button],input,select,textarea,summary,[tabindex]){
+    transition:color var(--duration-fast) var(--ease-out),
+               background-color var(--duration-fast) var(--ease-out),
+               border-color var(--duration-fast) var(--ease-out),
+               box-shadow var(--duration-fast) var(--ease-out),
+               opacity var(--duration-fast) var(--ease-out);
+  }
+
+  /* ——— controls ———
+     A bare <input> renders in the UA's face (Arial) at the UA's size with the
+     UA's border, which puts two typefaces and a foreign blue focus ring inside
+     Hanzo cards on every surface that has not styled its own fields yet. The
+     rules below are what a control looks like here. --border-control, NOT
+     --border: the boundary IS the affordance, so it is the rung that owes 3:1. */
+  :where(input,select,textarea,button){font:inherit;color:inherit}
+  :where(input:not([type=checkbox]):not([type=radio]):not([type=range]):not([type=color]),select,textarea){
+    background:var(--surface-2);
+    border:1px solid var(--border-control);
+    border-radius:var(--radius-sm);
+    padding:0 var(--space-3);
+  }
+  :where(textarea){padding:var(--space-2) var(--space-3);resize:vertical}
+  :where(input,select,textarea):focus-visible{border-color:var(--border-focus)}
+  :where(input,textarea)::placeholder{color:var(--text-disabled)}
+  :where(input,select,textarea,button):disabled{opacity:.5;cursor:not-allowed}
+  :where(button,[role=button],summary,label,select){cursor:pointer}
+
+  /* ——— media ———
+     An image, a video or an embed at its intrinsic width is the usual cause of a
+     390px page that scrolls sideways. */
+  :where(img,svg,video,canvas,iframe,picture,object){max-width:100%}
+  :where(img,video){height:auto}
+  /* A code block scrolls ITSELF rather than widening the document. */
+  :where(pre){overflow-x:auto}
+
+  /* ——— touch ———
+     Everything a finger aims at clears 44px, and every field renders at 16px so
+     iOS does not zoom the viewport on focus. Both are keyed on pointer:coarse —
+     the actual signal — so a desktop mouse still gets compact controls. This is
+     the whole of "mobile-first without per-app work": an app that never thought
+     about phones still has hittable buttons and a viewport that stays put. */
+  @media (pointer:coarse){
+    :where(button,[role=button],a[role=button],summary,select,textarea,
+           input:not([type=checkbox]):not([type=radio]):not([type=hidden])){
+      min-height:var(--tap-target);
+    }
+    :where(input,select,textarea){font-size:var(--text-control)}
+    /* A checkbox, radio or switch must NOT grow to 44px — the box is 16px
+       because that is what a checkbox looks like. What has to reach 44px is the
+       area a finger may land in, so the target is expanded with a centred
+       pseudo-element that changes nothing about layout or paint. WCAG 2.5.8 puts
+       the floor at 24px; a 16px box misses it, and every one of these ships at
+       16px. */
+    :where([role=checkbox],[role=radio],[role=switch],input[type=checkbox],input[type=radio]){position:relative}
+    :where([role=checkbox],[role=radio],[role=switch],input[type=checkbox],input[type=radio])::after{
+      content:'';position:absolute;top:50%;left:50%;
+      width:var(--tap-target);height:var(--tap-target);
+      transform:translate(-50%,-50%);
+    }
+  }
+
   :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
-  ::selection{background:var(--white-20);color:#fff}
+  /* --white-20 is white-on-white in the light theme, so selection reads through
+     --selection, which BOTH themes define. */
+  ::selection{background:var(--selection);color:var(--text-primary)}
 }