@hanzo/design 0.4.0 → 0.4.2

package/styles.css

@@ -16,9 +16,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;
@@ -38,77 +54,160 @@
   --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;
-  --destructive:#666666;
-  --destructive-foreground:#f5f5f5;
-  --border:#1f1f1f;
-  --input:#1f1f1f;
+  --background:#0a0a0a;
+  --foreground:#fafafa;
+  --card:#0f0f0f;
+  --card-foreground:#fafafa;
+  --popover:#0f0f0f;
+  --popover-foreground:#fafafa;
+  --primary:#fafafa;
+  /* A 5% step, not the 16% this used to be. A filled button's fill is already
+     the top of the ink ramp, so the only directions available on hover are
+     "dimmer" and "brighter-around-the-edges" — and a 16% drop reads as the
+     button going DISABLED under the cursor, which is the one thing a hover must
+     never look like. The step is now small enough to register as pressure while
+     --bloom does the actual work of lighting it up. */
+  --primary-hover:#e5e5e5;
+  --primary-foreground:#0a0a0a;
+  --secondary:#262626;
+  /* One rung up, so a secondary button HAS a hover. It previously resolved to
+     --surface-3, which is --secondary — the same value it starts at. */
+  --secondary-hover:#333333;
+  --secondary-foreground:#fafafa;
+  --muted:#171717;
+  --muted-foreground:#a3a3a3;
+  --accent:#262626;
+  --accent-foreground:#fafafa;
+  /* Destructive is the ONE place the monochrome rule already yields, and it was
+     yielding in only half the system: a field that fails validation draws
+     --state-error (#ef4444, which DESIGN.md §2.4 lists as permitted precisely
+     for "destructive / blocking error"), while the button that performs the
+     destruction drew #666666 — a mid-grey that is indistinguishable from a
+     disabled control. "Delete everything" and "you cannot click this" must not
+     be the same colour. So the two converge on the one token that already
+     names this meaning, and the ramp stays monochrome everywhere else. */
+  --destructive:var(--state-error);
+  --destructive-hover:#dc2626;   /* red-600 — deepens under the cursor */
+  --destructive-foreground:#fafafa;
+
+  /* ——— boundaries ———
+     ONE ladder, cut from alpha, graded by duty. Every rung is a rung of the
+     opacity ladder above, so every boundary composites correctly on the page,
+     on a card, and inside a popover — and every rung is the reference's own
+     measured value, not a rounded ramp:
+
+       --border          .10  the hairline. Cards, panels, dividers, list rows.
+       --border-strong   .16  the same hairline, one step up. Hover, emphasis.
+       --border-control  .15  a control's resting edge — input, select, textarea.
+       --border-focus    .22  that control, focused.
+       --border-selected .30  the thing that is currently CHOSEN — the active
+                              tab, the current tile, the featured plan.
+
+     The previous release cut the last three from the NEUTRAL ladder instead,
+     because a boundary that clears WCAG 1.4.11's 3:1 on a near-black ground IS
+     a mid-grey and no amount of tuning changes that. It is true, and it is also
+     what a wireframe looks like: a 1px #737373 box around every field, four
+     times heavier than the hairline beside it, so a form read as a debug
+     overlay rather than a surface. Aesthetics decided it — the reference draws
+     an input at rgb(255 255 255 / .15) and a focused one at .22 (sidebar.css
+     --input-border / .composer-box:focus-within), and that is what ships here.
+
+     What replaces the ratio is the FOCUS INDICATOR, which is the thing a
+     keyboard user actually navigates by and the one boundary still pinned at
+     3:1 (--ring, below). A resting edge is an affordance; a focus ring is a
+     position. Only the second one is load-bearing when you cannot see well, and
+     spending the contrast budget there rather than on all four edges of every
+     idle field is what lets the system be quiet AND findable at once. */
+  --border:var(--white-10);
+  --border-strong:var(--white-16);
+  --border-control:var(--white-15);      /* sidebar.css --input-border           */
+  --border-focus:var(--white-22);        /* .composer-box:focus-within           */
+  --border-selected:var(--white-30);     /* the current tab / tile / plan        */
+  --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
-     themes. (Was #333333 = 1.66:1 on --background: not a focus indicator.) */
-  --ring:var(--neutral-500);
+     3:1 against every surface it can land on, and unlike a resting edge it is
+     worth the loudness — it is transient, it only appears on keyboard focus,
+     and it is the whole of how a keyboard user knows where they are.
+     --white-40 clears it on every canvas in both themes precisely BECAUSE it is
+     alpha: on a lifted surface the ring lifts with it (3.77:1 on #0a0a0a,
+     3.66:1 on #262626), which a fixed grey cannot do. */
+  --ring:var(--white-40);
+  /* The soft halo that sits outside the ring — the reference's
+     `box-shadow: 0 0 0 2px rgb(255 255 255 / .06)` on a focused composer. It
+     carries no ratio; it is what makes focus read as designed rather than as a
+     browser default. Spent through --ring-focus (tokens/elevation.css). */
+  --ring-halo:var(--white-10);
   --brand:#e4e4e7;
   --brand-foreground:#09090b;
   --brand-muted:#a3a3a3;
   --black:#000000;
-  --white:#f5f5f5;
-
-  /* ——— surface recipes (card fills used across hanzo.ai) ——— */
+  --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 ———
+     A card has to be a SURFACE, which means you have to be able to see that it
+     is not the page. These were cut from neutral-900 (#171717) at .4/.5/.8, and
+     at .5 that composites to #101010 on a #0a0a0a ground — six levels above the
+     page, which is not a surface, it is a very slightly different black. Three
+     cards side by side then read as one flat field with hairlines ruled across
+     it, and no amount of shadow fixes it, because you cannot cast a shadow onto
+     black.
+
+     Cut from neutral-800 (#262626) instead, they land on 14 / 18 / 1f — the
+     reference's own panel (#171717 on a #0f0f0f container) with room either
+     side of it. They stay ALPHA so a card nested in a popover still lifts off
+     its parent rather than punching a hole in it; that is the whole reason
+     these are recipes and not just --surface-* rungs. */
   --surface-page:var(--background);
-  --surface-card:rgb(23 23 23 / .5);        /* bg-neutral-900/50 — grid tiles */
-  --surface-card-emphasis:rgb(23 23 23 / .8);/* bg-neutral-900/80 — featured   */
-  --surface-card-quiet:rgb(23 23 23 / .4);   /* bg-neutral-900/40 — story cards */
-  --surface-overlay:rgb(10 10 10 / .95);     /* dropdown / popover panels       */
+  --surface-card:rgb(38 38 38 / .5);         /* -> #181818 on the page          */
+  --surface-card-emphasis:rgb(38 38 38 / .75);/* -> #1f1f1f — featured          */
+  --surface-card-quiet:rgb(38 38 38 / .35);  /* -> #141414 — story cards        */
+  /* A floating panel that is the SAME colour as the page is not floating. This
+     was rgb(10 10 10 / .95) — the page, at 95% of the page. */
+  --surface-overlay:rgb(23 23 23 / .92);     /* 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);
 
@@ -123,47 +222,63 @@
   --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-hover:#e0e0e0;
   --secondary-foreground:#0a0a0a;
   --muted:#f5f5f5;
   --muted-foreground:#525252;
-  --accent:#f5f5f5;
+  --accent:#ededed;
   --accent-foreground:#0a0a0a;
-  --destructive:#999999;
+  --destructive:var(--state-error);
+  --destructive-hover:#dc2626;
   --destructive-foreground:#ffffff;
-  --border:#e5e5e5;
-  --input:#e5e5e5;
-  /* 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);
+  --border:rgb(0 0 0 / .10);
+  --border-strong:rgb(0 0 0 / .16);
+  --border-control:rgb(0 0 0 / .15);
+  /* Focus and selection are pushed further here than the .22/.30 they sit at in
+     dark. Black-on-white at a given alpha reads FAINTER than white-on-black at
+     the same alpha — .22 black on #ffffff measures 1.69:1 where .22 white on
+     #0a0a0a measures 1.97:1 — so mirroring the number would quietly make the
+     light theme's focus state the weakest state in the system. */
+  --border-focus:rgb(0 0 0 / .32);
+  --border-selected:rgb(0 0 0 / .42);
+  --input:var(--border-control);
+  /* Same duty, same 3:1 floor, opposite direction: .50 black is 3.98:1 on
+     #ffffff and 3.67:1 on #f5f5f5. */
+  --ring:rgb(0 0 0 / .5);
+  --ring-halo:rgb(0 0 0 / .07);
   --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);
 }
 
@@ -206,6 +321,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;
@@ -234,6 +362,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
@@ -267,18 +403,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 ─────────────────────────────────────── */
@@ -346,14 +521,49 @@
 }
 
 /* ── tokens/elevation.css ─────────────────────────────────────── */
-/* Hanzo barely uses shadow: on black, elevation reads as a hairline border plus
-   a wide, very dark drop. Only two levels ship (Tailwind's shadow-2xl for
-   floating surfaces) plus the ambient radial glow used behind heroes. */
+/* Elevation on a near-black ground is NOT a drop shadow. A dark blur on a dark
+   page is nothing — you cannot cast a shadow onto black — which is why a system
+   that ships only `box-shadow` reads flat no matter how heavy the alphas get.
+
+   What actually lifts a surface here is LIGHT, and it arrives in three parts:
+
+     1. a hairline EDGE            (tokens/colors.css --border)
+     2. an inset top HIGHLIGHT     (--edge-highlight, below)
+     3. a wide, very dark DROP     (--shadow-*)
+
+   (2) is the one that was missing and the one that does most of the work: a 1px
+   inset white line along the top edge reads as the surface catching the light
+   from above, and it is the whole difference between a panel that sits ON the
+   page and a rectangle that is merely a different colour than the page. The
+   reference spends it on its login card (`inset 0 1px 0 rgb(255 255 255 / .05)`)
+   and it is the single cheapest premium signal available on dark UI.
+
+   They are separate tokens rather than one baked shadow because a component
+   composes the ones it needs — `box-shadow: var(--edge-highlight), var(--shadow-lg)`
+   — and a card that wants the highlight without the drop should not have to
+   accept both. */
 :root{
   --shadow-none:none;
-  --shadow-floating:0 25px 50px -12px rgb(0 0 0 / .25);  /* shadow-2xl: composer, dropdowns, mega panel */
+  /* The floating surface: dropdowns, dialogs, sheets, the composer. Wide, soft,
+     and pushed well down. It was Tailwind's `shadow-2xl` at .25 alpha, which is
+     invisible on #0a0a0a — so the surfaces that float highest had the weakest
+     drop in the system while the t-shirt ramp below was correctly tuned. */
+  --shadow-floating:0 24px 60px -16px rgb(0 0 0 / .75);
   --shadow-inset-hairline:inset 0 0 0 1px var(--white-10);
-  --ring-focus:0 0 0 2px var(--ring);
+
+  /* ——— the light ——— */
+  /* The top edge, catching light. Add it to any raised surface. */
+  --edge-highlight:inset 0 1px 0 0 rgb(255 255 255 / .10);
+  /* The bloom around a LIT action on hover — a filled primary button, the send
+     key. Monochrome brand: this is where "alive" comes from instead of a hue,
+     and it is the whole hover signal on a fill that is already at the top of
+     the ink ramp. It was .10, which is invisible: a white glow has to compete
+     with the white object casting it, so the alpha that reads around a WHITE
+     button is far higher than the one that reads around a dark one. */
+  --bloom:0 0 24px -2px rgb(255 255 255 / .28);
+  /* The focus halo: soft, outside the ring, carrying no ratio of its own. This
+     was `0 0 0 2px var(--ring)` — a second hard ring around the hard ring. */
+  --ring-focus:0 0 0 3px var(--ring-halo);
 
   /* The t-shirt ramp. Named by size rather than by role, because that is how
      every component library already asks for a shadow (and how @hanzo/brand
@@ -371,6 +581,11 @@
   --glow-hero-blur:120px;
   /* Card top-corner sheen used on the story cards. */
   --sheen-card:radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%); /* @kind color */
+  /* The panel's top hairline, brightest at the centre and dissolving before it
+     reaches either corner — so an edge never terminates in a hard stop. One of
+     the two details that make the reference's panels look machined rather than
+     drawn (sidebar.css .panel::before). Paint it on a 1px-tall ::before. */
+  --sheen-edge:linear-gradient(90deg,transparent,rgb(255 255 255 / .14) 50%,transparent); /* @kind color */
   /* Chrome text: the canonical headline gradient. Never a saturated rainbow. */
   --gradient-chrome:linear-gradient(to right,#ffffff,var(--white-80),var(--white-60));
   --gradient-chrome-2:linear-gradient(to right,#ffffff,var(--neutral-500));
@@ -378,6 +593,37 @@
   --gradient-protect:linear-gradient(to bottom,var(--white-10),transparent);
 }
 
+/* Light theme — the same three parts, redistributed.
+   On white the order of work inverts: the DROP does almost all of it and the
+   inset highlight does none, because a white line on a white card is nothing.
+   Every token below is one whose dark value is white — i.e. one that silently
+   stops existing in `.light` unless it is restated here. check-tokens.mjs
+   scans this file for exactly that omission.
+
+   --edge-highlight is `inset 0 0 0 0 transparent` rather than `none` on
+   purpose: components compose these — `box-shadow: var(--edge-highlight),
+   var(--shadow-lg)` — and `none` is not a legal layer in a comma list, so the
+   obvious spelling would invalidate the whole declaration and take the drop
+   shadow down with it. A zero-size transparent shadow composes to nothing and
+   costs nothing. */
+.light{
+  --shadow-floating:0 24px 60px -16px rgb(0 0 0 / .18);
+  --shadow-inset-hairline:inset 0 0 0 1px rgb(0 0 0 / .10);
+  --edge-highlight:inset 0 0 0 0 transparent;
+  --bloom:0 6px 20px -4px rgb(0 0 0 / .18);
+  --shadow-sm:0 1px 2px 0 rgb(0 0 0 / .06);
+  --shadow:0 1px 3px 0 rgb(0 0 0 / .08), 0 1px 2px -1px rgb(0 0 0 / .06);
+  --shadow-md:0 4px 6px -1px rgb(0 0 0 / .08), 0 2px 4px -2px rgb(0 0 0 / .06);
+  --shadow-lg:0 10px 15px -3px rgb(0 0 0 / .09), 0 4px 6px -4px rgb(0 0 0 / .07);
+  --shadow-xl:0 20px 25px -5px rgb(0 0 0 / .10), 0 8px 10px -6px rgb(0 0 0 / .08);
+  --glow-hero:radial-gradient(circle,rgb(0 0 0 / .06) 0%,transparent 68%);
+  --sheen-card:radial-gradient(120% 120% at 80% 0%,rgb(0 0 0 / .04) 0%,transparent 55%);
+  --sheen-edge:linear-gradient(90deg,transparent,rgb(0 0 0 / .08) 50%,transparent);
+  --gradient-chrome:linear-gradient(to right,#0a0a0a,rgb(10 10 10 / .8),rgb(10 10 10 / .6));
+  --gradient-chrome-2:linear-gradient(to right,#0a0a0a,var(--neutral-500));
+  --gradient-protect:linear-gradient(to bottom,rgb(0 0 0 / .10),transparent);
+}
+
 /* ── tokens/motion.css ─────────────────────────────────────── */
 /* Motion is restrained: fade + small rise, CSS-only hovers, one breathing glow.
    No springs, no bounce, no parallax, no autoplay carousels. */
@@ -387,8 +633,17 @@
   --duration-slow:400ms; /* @kind other */   /* hero element entry           */
   --duration-slower:500ms; /* @kind other */ /* section entry                */
   --duration-glow:9s; /* @kind other */      /* ambient radial breathe       */
+  --duration-press:90ms; /* @kind other */   /* the press-down on :active     */
   --ease-out:cubic-bezier(0,0,0.2,1); /* @kind other */
   --ease-in-out:cubic-bezier(0.4,0,0.2,1); /* @kind other */
+  /* The entrance curve. Nearly all of the distance is covered in the first
+     third and it settles without overshooting, so a panel arrives DECIDED
+     rather than drifting in — the difference between 300ms that feels
+     immediate and 300ms that feels slow. Use it for anything that appears
+     (menus, dialogs, sheets, toasts); --ease-out stays the curve for a state
+     change on something already on screen. It is not a spring: this system has
+     no bounce anywhere. */
+  --ease-emphasis:cubic-bezier(0.16,1,0.3,1); /* @kind other */
   --stagger:60ms; /* @kind other */          /* per-element delay in a group */
   --entry-rise:16px;       /* hero y-offset                */
   --entry-rise-lg:24px;    /* card y-offset                */
@@ -397,6 +652,12 @@
 @keyframes hanzo-fade-up{from{opacity:0;transform:translateY(10px)}to{opacity:1;transform:translateY(0)}}
 @keyframes hanzo-fade-down{from{opacity:0;transform:translateY(-10px)}to{opacity:1;transform:translateY(0)}}
 @keyframes hanzo-slide-up-fade{from{opacity:0;transform:translateY(20px)}to{opacity:1;transform:translateY(0)}}
+/* The entrance for anything that appears OVER the page — dialog, sheet, command
+   palette. It arrives from very slightly small and very slightly low, which is
+   what reads as "came forward" rather than "was toggled on". 3% and 8px: any
+   more and it is an animation you notice, which is the failure mode. Pair it
+   with --ease-emphasis. */
+@keyframes hanzo-zoom-in{from{opacity:0;transform:scale(.97) translateY(8px)}to{opacity:1;transform:none}}
 @keyframes hanzo-glow{0%,100%{transform:scale(1);opacity:.45}50%{transform:scale(1.08);opacity:.65}}
 @keyframes hanzo-pulse-dot{0%,100%{opacity:1}50%{opacity:.35}}
 
@@ -486,19 +747,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
@@ -507,6 +785,130 @@
      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),
+               transform var(--duration-press) var(--ease-out);
+  }
+
+  /* ——— the press ———
+     A button that moves under the finger is the cheapest "this is a real
+     control" signal there is, and its absence is most of why a correct-looking
+     button still feels like a picture of a button. 2% over 90ms — small enough
+     that it reads as pressure rather than as animation, and it is the
+     reference's own value (.auth-signin-btn:active). Inputs are excluded: a
+     text field does not depress, and scaling one mid-caret is a glitch. */
+  :where(button,[role=button],a[role=button],summary):active:not(:disabled){
+    transform:scale(.98);
+  }
+
+  /* ——— 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);
+    /* --radius-md (8px), not --radius-sm (6px). On a 36px control the two are
+       one step apart and it is the step between "boxy" and "considered";
+       --radius-sm keeps its job on genuinely small parts — badges, chips, menu
+       rows — where 8px would look bubbly. The reference draws its composer and
+       its buttons at 8-10px and nothing at 6px except 22px chips. */
+    border-radius:var(--radius-md);
+    padding:0 var(--space-3);
+  }
+  :where(textarea){padding:var(--space-2) var(--space-3);resize:vertical}
+  /* ——— focus, on a control ———
+     Not the generic ring. A field already HAS an edge, so focus brightens that
+     edge (.15 -> .22) and adds a soft halo just outside it — which is what the
+     reference does (.composer-box:focus-within) and what separates a focused
+     field from a browser default. The generic `outline` is suppressed here
+     precisely because it would draw a second, harder box around this one. */
+  :where(input,select,textarea):focus-visible{
+    outline:none;
+    border-color:var(--border-focus);
+    box-shadow:var(--ring-focus);
+  }
+  /* A hovered field lifts its surface a rung. Nudging its EDGE from .15 to .16
+     is a state nobody can see. */
+  :where(input,select,textarea):hover:not(:focus-visible):not(:disabled){background:var(--surface-3)}
+  :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)}
+
+  /* ——— the scrollbar ———
+     The single largest piece of UNSTYLED chrome left on a dark surface: a
+     default 15px light-grey scrollbar down the side of a #0a0a0a panel is the
+     one element on the page that did not get the memo, and it is visible on
+     every scrolling surface in the product. 6px, no track, thumb on the same
+     hairline ladder as everything else. Both syntaxes ship because they are
+     disjoint — `scrollbar-*` is Firefox and the `::-webkit-*` pseudos are
+     Chromium/Safari; neither engine reads the other. */
+     The thumb is a --white-* rung, so it does not invert; the `.light`
+     restatements sit here rather than in colors.css because a scrollbar is an
+     element default and this file is where element defaults live. Everything
+     stays INSIDE the layer — an unlayered rule here would outrank an app's own
+     utilities, which is the defect check 1c exists to catch. */
+  :where(html){scrollbar-color:var(--white-15) transparent;scrollbar-width:thin}
+  .light{scrollbar-color:rgb(0 0 0 / .18) transparent}
+  :where(*)::-webkit-scrollbar{width:6px;height:6px}
+  :where(*)::-webkit-scrollbar-track{background:transparent}
+  :where(*)::-webkit-scrollbar-thumb{background:var(--white-15);border-radius:var(--radius-full)}
+  :where(*)::-webkit-scrollbar-thumb:hover{background:var(--white-30)}
+  :where(*)::-webkit-scrollbar-corner{background:transparent}
+  .light :where(*)::-webkit-scrollbar-thumb{background:rgb(0 0 0 / .18)}
+  .light :where(*)::-webkit-scrollbar-thumb:hover{background:rgb(0 0 0 / .32)}
 }