@hanzo/design 0.4.8 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.4.8",
+  "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,30 +140,38 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
     : fail('base.css is UNLAYERED — its element rules outrank every utility an app writes')
 }
 
-// ── 1d. a focused element gets exactly ONE indicator ─────────────────────
-// The field rule and the generic ring rule both compute to (0,1,0) — :where()
-// zeroes its contents and each side keeps one pseudo-class — so the cascade
-// falls through to SOURCE ORDER inside @layer base. The generic rule was
-// written later, so it overrode the `outline:none` that the field rule states
-// expressly to prevent it, and every focused input on every consumer drew the
-// 2px ring AND the edge+halo. Both rules read as correct in isolation; only
-// their order was wrong, which is why nobody saw it in either file.
+// ── 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 instead: a rule
-// that paints an outline on focus must not be able to land on a field.
+// 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')))
-  const FIELDS = 'input,select,textarea'
-  // `outline:none` disarms; anything else paints. `outline-offset` is a
-  // different property and never matches — the colon must follow `outline`.
-  const paints = (body) => /(?:^|[;{\s])outline\s*:\s*(?!none\b)[^;}]+/.test(body)
-  const scoped = (sel) => sel.includes(`:where(${FIELDS})`) || sel.includes(`:not(${FIELDS})`)
-  const doubled = [...base.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+  // `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, body }) => sel.includes(':focus-visible') && paints(body) && !scoped(sel))
-  doubled.length
-    ? doubled.forEach(({ sel }) => fail(`\`${sel}\` paints an outline on a field that already draws its own edge + halo — two focus indicators`))
-    : pass('one focus indicator per element: fields brighten their edge, everything else rings')
+    .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 ──────────────

package/styles.css

@@ -834,20 +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. `outline:none` drops the UA's own focus ring,
-     which would otherwise draw a second, harder box around this one; the
-     generic ring below excludes fields for the same reason. */
-  :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}
@@ -887,17 +893,20 @@
     }
   }
 
-  /* The generic ring — for everything that is NOT a field. The exclusion is
-     load-bearing, not tidiness. This rule and the control rule above both
-     compute to (0,1,0): :where() zeroes whatever it wraps, leaving one
-     pseudo-class on each side. Equal specificity inside one layer falls through
-     to source order, this rule sits 46 lines LATER, so it overrode the
-     `outline:none` written above to prevent precisely this — and every focused
-     input, select and textarea on every consumer drew BOTH the 2px ring and the
-     edge+halo. Two indicators, from the two rules that each say there is one.
-     Stating the exclusion in the selector fixes it by MEANING rather than by
-     position, so reordering either rule cannot bring it back. */
-  :where(:not(input,select,textarea)):focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  /* 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. */
   ::selection{background:var(--selection);color:var(--text-primary)}

package/tailwind.css

@@ -857,20 +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. `outline:none` drops the UA's own focus ring,
-     which would otherwise draw a second, harder box around this one; the
-     generic ring below excludes fields for the same reason. */
-  :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}
@@ -910,17 +916,20 @@
     }
   }
 
-  /* The generic ring — for everything that is NOT a field. The exclusion is
-     load-bearing, not tidiness. This rule and the control rule above both
-     compute to (0,1,0): :where() zeroes whatever it wraps, leaving one
-     pseudo-class on each side. Equal specificity inside one layer falls through
-     to source order, this rule sits 46 lines LATER, so it overrode the
-     `outline:none` written above to prevent precisely this — and every focused
-     input, select and textarea on every consumer drew BOTH the 2px ring and the
-     edge+halo. Two indicators, from the two rules that each say there is one.
-     Stating the exclusion in the selector fixes it by MEANING rather than by
-     position, so reordering either rule cannot bring it back. */
-  :where(:not(input,select,textarea)):focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  /* 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. */
   ::selection{background:var(--selection);color:var(--text-primary)}

package/tokens/base.css

@@ -99,20 +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. `outline:none` drops the UA's own focus ring,
-     which would otherwise draw a second, harder box around this one; the
-     generic ring below excludes fields for the same reason. */
-  :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}
@@ -152,17 +158,20 @@
     }
   }
 
-  /* The generic ring — for everything that is NOT a field. The exclusion is
-     load-bearing, not tidiness. This rule and the control rule above both
-     compute to (0,1,0): :where() zeroes whatever it wraps, leaving one
-     pseudo-class on each side. Equal specificity inside one layer falls through
-     to source order, this rule sits 46 lines LATER, so it overrode the
-     `outline:none` written above to prevent precisely this — and every focused
-     input, select and textarea on every consumer drew BOTH the 2px ring and the
-     edge+halo. Two indicators, from the two rules that each say there is one.
-     Stating the exclusion in the selector fixes it by MEANING rather than by
-     position, so reordering either rule cannot bring it back. */
-  :where(:not(input,select,textarea)):focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  /* 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. */
   ::selection{background:var(--selection);color:var(--text-primary)}