@tangle-network/brand 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.6.0
+
+### Minor Changes
+
+- 4649d22: Replace the hard 2px indigo focus ring with one soft focus treatment for every control.
+  
+  brand adds `--focus-border`, `--focus-halo`, `--focus-border-danger`, `--focus-halo-danger` and `--border-strong`. Each derives from the ring, danger-ink, border and foreground tokens, so every theme, named theme and light island resolves its own values. The focus border clears 3:1 against the field in every theme, which `focus.test.ts` enforces.
+  
+  brand's `globals.css` also gives any control that styles no focus of its own (a hand-rolled button, link, radio card or tab) the same keyboard focus line and halo in the base layer, in place of the browser's blue outline. Component utilities still override it.
+  
+  ui exports `focusField`, `focusFieldWithin`, `focusFieldInvalid`, `focusRing` and `focusRingInset` from `utils`, and the primitives use them:
+  
+  - `Input`, `Textarea`, `SelectTrigger` and `TerminalInput` rest on the neutral `border-border` hairline instead of the muted-text `border-input`, darken slightly on hover, and on focus shift the border to `--focus-border` with a 3px `--focus-halo` ring. The `default` and `sandbox` variants now render the same field.
+  - `Button`, `Tabs`, `Switch`, `Badge`, `SegmentedControl`, the dialog and toast close buttons, the auth menu trigger, and the chat and file controls show a 1px focus line with the same halo on `:focus-visible` only. A mouse click no longer draws a ring.
+  - Interactive `Card`, tool-preview and code-block hovers darken the border instead of tinting it indigo.
+  
+  A consumer that removed the old ring with `focus-visible:ring-0` on a field should pass `focus:ring-0` instead, because the field ring now keys off `:focus`.
+
+### Patch Changes
+
+- 2909c24: `globals.css` gives a native text field that styles no focus of its own a fallback: a 1px `--focus-border` line over its border, in place of the browser's blue outline. It covers `input` (except button-like, checkbox, radio, range, colour, file and hidden types), `select` and `textarea`, on `:focus-visible`, in the base layer. Any outline utility on the field, such as `outline-none` or ui's `focusField`, still wins. The fallback has no halo, so a field that hands its focus to a container and clears its outline shows nothing extra.
+
 ## 1.5.0
 
 ### Minor Changes

package/README.md

@@ -55,6 +55,7 @@ import { Logo, TangleKnot } from "@tangle-network/brand";
 - **Depth stack** — `#0C0B1D` → `#262448` (dark); `#f4f4f9` → `#dcdbe8` (light)
 - **Status** — emerald / amber / coral for running / stopped / error
 - **Radii** — 6/8/12/16px (dark); 2/4/6/8px (light/"vault")
+- **Focus** — `--focus-border` and `--focus-halo` (plus `-danger` variants) for a focused control, and `--border-strong` for a hovered field. They derive from the ring and border tokens, so every theme gets its own. `@tangle-network/ui` applies them through `focusField` and `focusRing`. `globals.css` gives a control or native text field that styles no focus of its own a fallback: a control gets the 1px line and halo on keyboard focus, and a text field gets the 1px line over its border.
 
 Light theme activates via `data-sandbox-theme="vault"` on a parent element.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Tangle brand system — design tokens, logo, Tailwind v4 theme. Single source of truth for every Tangle app.",
   "type": "module",
   "license": "MIT",

package/src/styles/focus.test.ts

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  blockIn,
+  blocksIn,
+  compositeOver,
+  contrastRatio,
+  hexIn,
+  hslIn,
+  hslToRgb,
+} from "./css-test-utils";
+
+/**
+ * The focus palette's contract.
+ *
+ * A focused field keeps a 1px border in --focus-border with a soft
+ * --focus-halo outside it. The halo is too faint to count as an indicator on
+ * its own, so the BORDER must clear the 3:1 non-text floor (WCAG 1.4.11)
+ * against the field it outlines, in every theme a consumer can select.
+ */
+const read = (name: string) =>
+  readFileSync(path.resolve(import.meta.dirname, name), "utf8");
+const tokens = read("tokens.css");
+const themes = read("named-themes.css");
+
+// The focus rule is the one whose selector list ends in `[data-theme]`.
+const FOCUS = blockIn(tokens, "[data-theme]");
+const DARK = blockIn(tokens, ".dark");
+const LIGHT = blockIn(tokens, ".light");
+
+function alphaOf(token: string, pattern: RegExp): number {
+  const m = FOCUS.match(pattern);
+  if (!m) throw new Error(`--${token} does not have the expected shape`);
+  return Number(m[1]) / (m[2] === "%" ? 100 : 1);
+}
+const borderAlpha = alphaOf(
+  "focus-border",
+  /--focus-border:\s*hsl\(var\(--hsl-ring\)\s*\/\s*([\d.]+)()\)/,
+);
+const dangerAlpha = alphaOf(
+  "focus-border-danger",
+  /--focus-border-danger:\s*color-mix\(in srgb, var\(--surface-danger-text\) ([\d.]+)(%), transparent\)/,
+);
+
+/** Reads a token from the first source that declares it, as the cascade would. */
+function effective<T>(sources: string[], readToken: (css: string) => T): T {
+  for (const css of sources) {
+    try {
+      return readToken(css);
+    } catch {
+      // Not declared here; fall through to the scope it inherits from.
+    }
+  }
+  throw new Error("token resolves to nothing");
+}
+
+const lightStatus = blocksIn(themes, '[data-theme="tangle-light"]').join("\n");
+const scopes: Array<{ name: string; sources: string[] }> = [
+  { name: "canonical dark", sources: [DARK] },
+  { name: "canonical light", sources: [LIGHT] },
+  ...["aubergine", "arena", "tangle-dark"].map((name) => ({
+    name,
+    sources: [...blocksIn(themes, `[data-theme="${name}"]`), DARK],
+  })),
+  ...["aubergine-light", "arena-light", "tangle-light"].map((name) => ({
+    name,
+    sources: [...blocksIn(themes, `[data-theme="${name}"]`), lightStatus, DARK],
+  })),
+  {
+    name: "intelligence",
+    sources: [blockIn(themes, '.dark[data-theme="intelligence"]'), DARK],
+  },
+];
+
+describe("the focus palette resolves in every theme scope", () => {
+  it("is declared on each selector that can redefine the tokens it derives from", () => {
+    // A custom property that references another is resolved where it is
+    // declared. Declared on :root alone, a named theme on a descendant would
+    // inherit the root's focus colors instead of its own.
+    const rules = tokens.replace(/\/\*[\s\S]*?\*\//g, "");
+    const header = rules.match(/([^{}]*)\{\s*--focus-border:/)?.[1] ?? "";
+    for (const scope of [":root", ".dark", ".light", "[data-sandbox-ui]", "[data-sandbox-theme]", "[data-theme]"]) {
+      expect(header, `focus rule selector list`).toContain(scope);
+    }
+  });
+});
+
+describe("a focused field's border clears 3:1 against the field", () => {
+  for (const { name, sources } of scopes) {
+    it(name, () => {
+      const field = hslToRgb(effective(sources, (css) => hslIn(css, "hsl-card")));
+      const ring = hslToRgb(effective(sources, (css) => hslIn(css, "hsl-ring")));
+      const border = compositeOver(ring, field, borderAlpha);
+      expect(contrastRatio(border, field), "focus border on field").toBeGreaterThanOrEqual(3);
+
+      const danger = effective(sources, (css) => hexIn(css, "surface-danger-text"));
+      const dangerBorder = compositeOver(danger, field, dangerAlpha);
+      expect(contrastRatio(dangerBorder, field), "danger focus border on field").toBeGreaterThanOrEqual(3);
+    });
+  }
+});

package/src/styles/globals.css

@@ -19,6 +19,61 @@
       "ss01" 1;
   }
 
+  /* The default keyboard focus for any control that does not style its own:
+   * the same 1px --focus-border line and soft halo as ui's `focusRing`, in
+   * place of the browser's blue outline. It sits in the base layer, so a
+   * component's own focus utilities always win over it. Text fields have
+   * their own fallback below. */
+  :where(
+      a[href],
+      button,
+      summary,
+      input:is([type="checkbox"], [type="radio"]),
+      [role="button"],
+      [role="checkbox"],
+      [role="link"],
+      [role="menuitem"],
+      [role="option"],
+      [role="radio"],
+      [role="switch"],
+      [role="tab"],
+      [tabindex]:not([tabindex="-1"])
+    ):focus-visible {
+    outline: 1px solid var(--focus-border);
+    outline-offset: 0;
+    box-shadow: 0 0 0 4px var(--focus-halo);
+  }
+
+  /* The fallback focus for a native text field that styles none: a 1px
+   * --focus-border line laid over the field's own border, in place of the
+   * browser's blue outline. It is an outline because any border-colour
+   * utility on the field outranks a base-layer border colour. It has no halo:
+   * a field that hands its focus to a container clears the line with
+   * `outline-none`, which a base-layer box-shadow would ignore. ui's
+   * `focusField` gives the full border and halo. */
+  :where(
+      input:not(
+          [type="button"],
+          [type="checkbox"],
+          [type="color"],
+          [type="file"],
+          [type="hidden"],
+          [type="image"],
+          [type="radio"],
+          [type="range"],
+          [type="reset"],
+          [type="submit"]
+        ),
+      select,
+      textarea
+    ):focus-visible {
+    outline: 1px solid var(--focus-border);
+    outline-offset: -1px;
+    /* A field with an explicit tabindex also matches the control rule above;
+     * drop that rule's halo. */
+    box-shadow: none;
+  }
+
   ::selection {
     background: var(--bg-selection);
     color: hsl(var(--hsl-foreground));

package/src/styles/tokens.css

@@ -681,3 +681,40 @@
   --radius-composer: 26px;
 }
 
+
+/* Focus and field hover — the palette behind @tangle-network/ui's focus
+ * treatment (`focusField` / `focusRing` in ui's lib/focus.ts).
+ *
+ * A focused field keeps its 1px border and shifts it to --focus-border, with a
+ * 3px --focus-halo ring outside it. A focused button or tab draws a 1px
+ * --focus-border line with the same halo beyond it. Both render as box-shadow,
+ * so they follow border-radius and never move layout.
+ *
+ * The BORDER carries the contrast and the halo is decoration. --focus-border is
+ * the ring at 80%: 4.7:1 on the white light-mode field and 5.7:1 on the dark
+ * card, so the indicator clears the 3:1 non-text floor (WCAG 1.4.11) in every
+ * theme, while reading as a tint of the field instead of a hard indigo outline.
+ * An 18% halo sits near 1.3:1 against the page on purpose: it softens the edge
+ * and is never the only cue. Gated in focus.test.ts.
+ *
+ * Every value is derived from a spine token (--hsl-ring, --surface-danger-text,
+ * --hsl-border, --hsl-foreground), and a custom property that references
+ * another is resolved where it is declared. So this rule names every scope that
+ * can redefine those tokens: a named theme or a light island on a descendant
+ * gets its own focus colors instead of inheriting the root's. */
+:root,
+.dark,
+.light,
+[data-sandbox-ui],
+[data-sandbox-theme],
+[data-theme] {
+  --focus-border: hsl(var(--hsl-ring) / 0.8);
+  --focus-halo: hsl(var(--hsl-ring) / 0.18);
+  /* The danger INK, not the destructive fill: the fill is tuned to carry white
+   * text and measures about 2:1 on the dark card. */
+  --focus-border-danger: color-mix(in srgb, var(--surface-danger-text) 80%, transparent);
+  --focus-halo-danger: color-mix(in srgb, var(--surface-danger-text) 18%, transparent);
+  /* A resting hairline one step toward the ink, for hover: darker on light
+   * paper, lighter on a dark card, never tinted. */
+  --border-strong: color-mix(in srgb, hsl(var(--hsl-border)), hsl(var(--hsl-foreground)) 20%);
+}