@hanzo/design 0.4.7 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "packageManager": "pnpm@11.17.0",
   "description": "Hanzo Design System \u2014 monochrome, dark-default tokens + components + brand assets, the single source of truth for every Hanzo surface. CSS + typed programmatic tokens.",
   "license": "MIT OR Apache-2.0",

package/scripts/check-tokens.mjs

@@ -140,6 +140,40 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
     : fail('base.css is UNLAYERED — its element rules outrank every utility an app writes')
 }
 
+// ── 1d. exactly ONE rule decides focus ───────────────────────────────────
+// Until 0.4.9 there were two: a field rule that suppressed the outline and drew
+// a brightened edge + halo, and the generic ring. Both computed to (0,1,0) —
+// :where() zeroes its contents and each side keeps one pseudo-class — so the
+// cascade fell through to SOURCE ORDER inside @layer base, the generic rule was
+// written later, and it overrode the `outline:none` the field rule stated
+// expressly to prevent it. Every focused input on every consumer drew BOTH.
+// Each rule read as correct alone; the defect existed only in their order,
+// which is why it survived review in both files.
+//
+// Order is not testable as intent, so this tests the property that replaced it:
+// one rule paints the indicator, and nothing else touches focus. A second rule
+// is how they disagree, `outline:none` is how an indicator disappears, and
+// box-shadow is how a second one appears — none of the three can return quietly.
+{
+  const base = strip(read(join(tokensDir, 'base.css')))
+  // `outline-offset` is a different property and never matches: the colon must
+  // follow `outline` itself.
+  const OUTLINE = /(?:^|[;{\s])outline\s*:\s*([^;}]+)/
+  const rules = [...base.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+    .map(([, sel, body]) => ({ sel: sel.trim().replace(/\s+/g, ' '), body }))
+    .filter(({ sel }) => sel.includes(':focus-visible'))
+
+  const paints = rules.filter(({ body }) => { const m = body.match(OUTLINE); return m && m[1].trim() !== 'none' })
+  const mutes = rules.filter(({ body }) => { const m = body.match(OUTLINE); return m && m[1].trim() === 'none' })
+  const halos = rules.filter(({ body }) => /(?:^|[;{\s])box-shadow\s*:/.test(body))
+
+  paints.length === 1
+    ? pass(`one focus indicator, one rule: \`${paints[0].sel}\``)
+    : fail(`${paints.length} rules paint a focus outline (${paints.map((r) => r.sel).join(' / ')}) — equal specificity inside @layer base, so source order decides which one a user actually sees`)
+  mutes.forEach(({ sel }) => fail(`\`${sel}\` sets outline:none — it removes the focus indicator instead of replacing it`))
+  halos.forEach(({ sel }) => fail(`\`${sel}\` adds a box-shadow on focus — a second indicator beside the ring`))
+}
+
 // ── 2. every var() used inside the token layer must resolve ──────────────
 {
   const declared = new Set()

package/styles.css

@@ -834,19 +834,26 @@
     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. */
+  /* A field has NO focus rule of its own — see the ring at the bottom of this
+     layer, which is the one focus indicator for everything.
+
+     There used to be one here: `outline:none` plus a brightened edge (.15 ->
+     .22) plus a soft halo, the composer look. It was removed because it could
+     not do the job in either of the two ways that matter.
+
+     It was never VISIBLE ENOUGH. Composited on --background the brightened edge
+     measures 1.91:1 and the halo 1.25:1, against the 3:1 that WCAG 1.4.11 asks
+     of a focus indicator and that this package already gates --ring on. The
+     budget was documented as being spent entirely on --ring "because that is
+     what a keyboard user navigates by" — true for a button, and false for a
+     field for exactly as long as this rule told fields not to use it.
+
+     And it was SUPPRESSIBLE. It carried the indicator on `border-color`, so any
+     app that states `border` on its own fields overrode it — @hanzo/id does,
+     unlayered, which beats this layer whatever its specificity, and its focused
+     fields sat at the resting .15 while both files read as correct. An outline
+     is not a border: nothing in an app's field styling reaches it, so the ring
+     paints whether or not the app has opinions about edges. */
   :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}
@@ -886,6 +893,19 @@
     }
   }
 
+  /* THE focus indicator. One rule, every focusable thing, no exceptions — a
+     button, a link, a summary, a field. 2px at --ring is 3.77:1 on the darkest
+     canvas and clears the 2px perimeter WCAG 2.4.13 asks for; the gate in
+     check-tokens holds --ring to that and nothing else here may weaken it.
+
+     There were two rules until 0.4.9, and they collided invisibly. Both computed
+     to (0,1,0) — :where() zeroes whatever it wraps, leaving one pseudo-class on
+     each side — so the cascade fell through to SOURCE ORDER inside this layer,
+     this rule was written later, and it overrode the `outline:none` the field
+     rule stated expressly to prevent it. Every focused input on every consumer
+     drew BOTH the ring and the edge+halo. Each rule read as correct alone, which
+     is why it survived review in both files; the defect existed only in their
+     order. One rule cannot disagree with itself. */
   :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
   /* --white-20 is white-on-white in the light theme, so selection reads through
      --selection, which BOTH themes define. */

package/tailwind.css

@@ -857,19 +857,26 @@
     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. */
+  /* A field has NO focus rule of its own — see the ring at the bottom of this
+     layer, which is the one focus indicator for everything.
+
+     There used to be one here: `outline:none` plus a brightened edge (.15 ->
+     .22) plus a soft halo, the composer look. It was removed because it could
+     not do the job in either of the two ways that matter.
+
+     It was never VISIBLE ENOUGH. Composited on --background the brightened edge
+     measures 1.91:1 and the halo 1.25:1, against the 3:1 that WCAG 1.4.11 asks
+     of a focus indicator and that this package already gates --ring on. The
+     budget was documented as being spent entirely on --ring "because that is
+     what a keyboard user navigates by" — true for a button, and false for a
+     field for exactly as long as this rule told fields not to use it.
+
+     And it was SUPPRESSIBLE. It carried the indicator on `border-color`, so any
+     app that states `border` on its own fields overrode it — @hanzo/id does,
+     unlayered, which beats this layer whatever its specificity, and its focused
+     fields sat at the resting .15 while both files read as correct. An outline
+     is not a border: nothing in an app's field styling reaches it, so the ring
+     paints whether or not the app has opinions about edges. */
   :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}
@@ -909,6 +916,19 @@
     }
   }
 
+  /* THE focus indicator. One rule, every focusable thing, no exceptions — a
+     button, a link, a summary, a field. 2px at --ring is 3.77:1 on the darkest
+     canvas and clears the 2px perimeter WCAG 2.4.13 asks for; the gate in
+     check-tokens holds --ring to that and nothing else here may weaken it.
+
+     There were two rules until 0.4.9, and they collided invisibly. Both computed
+     to (0,1,0) — :where() zeroes whatever it wraps, leaving one pseudo-class on
+     each side — so the cascade fell through to SOURCE ORDER inside this layer,
+     this rule was written later, and it overrode the `outline:none` the field
+     rule stated expressly to prevent it. Every focused input on every consumer
+     drew BOTH the ring and the edge+halo. Each rule read as correct alone, which
+     is why it survived review in both files; the defect existed only in their
+     order. One rule cannot disagree with itself. */
   :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
   /* --white-20 is white-on-white in the light theme, so selection reads through
      --selection, which BOTH themes define. */

package/tokens/base.css

@@ -99,19 +99,26 @@
     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. */
+  /* A field has NO focus rule of its own — see the ring at the bottom of this
+     layer, which is the one focus indicator for everything.
+
+     There used to be one here: `outline:none` plus a brightened edge (.15 ->
+     .22) plus a soft halo, the composer look. It was removed because it could
+     not do the job in either of the two ways that matter.
+
+     It was never VISIBLE ENOUGH. Composited on --background the brightened edge
+     measures 1.91:1 and the halo 1.25:1, against the 3:1 that WCAG 1.4.11 asks
+     of a focus indicator and that this package already gates --ring on. The
+     budget was documented as being spent entirely on --ring "because that is
+     what a keyboard user navigates by" — true for a button, and false for a
+     field for exactly as long as this rule told fields not to use it.
+
+     And it was SUPPRESSIBLE. It carried the indicator on `border-color`, so any
+     app that states `border` on its own fields overrode it — @hanzo/id does,
+     unlayered, which beats this layer whatever its specificity, and its focused
+     fields sat at the resting .15 while both files read as correct. An outline
+     is not a border: nothing in an app's field styling reaches it, so the ring
+     paints whether or not the app has opinions about edges. */
   :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}
@@ -151,6 +158,19 @@
     }
   }
 
+  /* THE focus indicator. One rule, every focusable thing, no exceptions — a
+     button, a link, a summary, a field. 2px at --ring is 3.77:1 on the darkest
+     canvas and clears the 2px perimeter WCAG 2.4.13 asks for; the gate in
+     check-tokens holds --ring to that and nothing else here may weaken it.
+
+     There were two rules until 0.4.9, and they collided invisibly. Both computed
+     to (0,1,0) — :where() zeroes whatever it wraps, leaving one pseudo-class on
+     each side — so the cascade fell through to SOURCE ORDER inside this layer,
+     this rule was written later, and it overrode the `outline:none` the field
+     rule stated expressly to prevent it. Every focused input on every consumer
+     drew BOTH the ring and the edge+halo. Each rule read as correct alone, which
+     is why it survived review in both files; the defect existed only in their
+     order. One rule cannot disagree with itself. */
   :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
   /* --white-20 is white-on-white in the light theme, so selection reads through
      --selection, which BOTH themes define. */