@tangle-network/brand 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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
+
+- 532a6d8: Add `--shadow-overlay`, the elevation step above `--shadow-dropdown` for a surface that covers the page rather than sitting beside it — a drawer, a modal, a floating dock.
+
+  It is derived from `--hsl-foreground` rather than a fixed `rgba`, so it inverts with the theme: dark ink in light, a soft halo in dark. That is what makes it work on a dark canvas, where a black shadow renders as nothing. One declaration serves both themes, and the token is declared in the `@theme` block as well so Tailwind emits a `shadow-overlay` utility.
+
 ## 1.4.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.4.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/theme-parity.test.ts

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { blockIn } from "./css-test-utils";
+
+/**
+ * A token declared in both files has to carry the same value in both.
+ *
+ * `tokens.css` is what a consumer reads at runtime through `var(--x)`.
+ * `theme.css` is the Tailwind v4 `@theme` block, and it exists because Tailwind
+ * only emits a utility for a token it can see declared there — so the shared
+ * ones are necessarily written twice.
+ *
+ * That duplication is structural and cannot be factored out: `@theme` needs a
+ * literal, and a self-reference would be circular. What it can be is GATED. An
+ * edit to one file that misses the other would leave `shadow-overlay` (the
+ * utility, from theme.css) rendering a different shadow from
+ * `shadow-[var(--shadow-overlay)]` (the variable, from tokens.css), and the
+ * mismatch would show up as an inconsistency no one could reproduce from
+ * either file alone.
+ */
+const read = (name: string) =>
+  readFileSync(path.resolve(import.meta.dirname, name), "utf8");
+
+/** `--token: value;` pairs in one CSS block, whitespace collapsed. */
+function declarationsIn(css: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const m of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+    out.set(m[1] as string, (m[2] as string).split(/\s+/).join(" ").trim());
+  }
+  return out;
+}
+
+// The default spine, which is the one `@theme` mirrors. Anchor on the last
+// selector of the multi-selector header, as the other suites here do.
+const tokensCss = read("tokens.css");
+const runtime = declarationsIn(blockIn(tokensCss, ".dark"));
+const light = declarationsIn(blockIn(tokensCss, ".light"));
+const theme = declarationsIn(blockIn(read("theme.css"), "@theme"));
+
+const shared = [...theme.keys()].filter((t) => runtime.has(t)).sort();
+
+describe("tokens.css and theme.css agree on every token they both declare", () => {
+  it("finds the shared tokens to check", () => {
+    // Guards the parse itself: a selector rename that silently emptied one
+    // block would otherwise make every assertion below vacuously pass.
+    expect(shared.length).toBeGreaterThan(5);
+  });
+
+  for (const token of shared) {
+    it(`${token} carries one value`, () => {
+      expect(theme.get(token)).toBe(runtime.get(token));
+    });
+  }
+});
+
+/**
+ * A token written in terms of `--hsl-foreground` already inverts, because that
+ * ramp is what each spine redefines. Restating it on the light spine would pin
+ * it to one theme's ink and defeat the derivation — the failure would be silent,
+ * since both declarations are individually valid CSS.
+ *
+ * So the omission is the contract, and this asserts it rather than trusting the
+ * comment that states it.
+ */
+const selfInverting = [...runtime.entries()]
+  .filter(([, value]) => value.includes("var(--hsl-foreground)"))
+  .map(([token]) => token)
+  .sort();
+
+describe("a self-inverting token is declared once, not per spine", () => {
+  it("finds the self-inverting tokens to check", () => {
+    expect(selfInverting.length).toBeGreaterThan(0);
+    // The assertions below are absence checks, so they hold trivially against
+    // an empty map. A selector rename that stopped matching the light spine
+    // would otherwise read as "nothing is restated" — the strongest possible
+    // pass from the weakest possible parse.
+    expect(light.size).toBeGreaterThan(5);
+  });
+
+  for (const token of selfInverting) {
+    it(`${token} is not restated on the light spine`, () => {
+      expect(light.has(token)).toBe(false);
+    });
+  }
+});

package/src/styles/theme.css

@@ -104,4 +104,10 @@
   --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.3);
   --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
   --shadow-glow: none;
+  /* Theme-derived, so it inverts — see tokens.css. Declared here as well so
+     Tailwind emits the `shadow-overlay` utility, which is how a consumer
+     reaches it without writing `shadow-[var(--shadow-overlay)]`. */
+  --shadow-overlay:
+    0 2px 6px hsl(var(--hsl-foreground) / 0.1),
+    0 16px 40px hsl(var(--hsl-foreground) / 0.16);
 }

package/src/styles/tokens.css

@@ -319,6 +319,18 @@
   --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
   --shadow-glow: none;
   --shadow-accent: 0 1px 2px rgba(0, 0, 0, 0.3);
+  /* The lift above --shadow-dropdown, for a surface that covers the page
+     rather than sitting beside it: a drawer, a modal, a floating dock.
+     Two layers — a tight contact shadow plus a wide ambient one.
+     Alone among the shadows this is derived from --hsl-foreground instead of
+     a fixed rgba, so it INVERTS with the theme. That is what makes it work in
+     dark: a black shadow on a dark canvas renders as nothing (see the ladder
+     note at the top of this file), while the foreground is near-white there,
+     so the same declaration reads as a soft halo. One definition therefore
+     serves both themes and the light block does not restate it. */
+  --shadow-overlay:
+    0 2px 6px hsl(var(--hsl-foreground) / 0.1),
+    0 16px 40px hsl(var(--hsl-foreground) / 0.16);
   --shadow-status-running: none;
   --shadow-status-creating: none;
   --shadow-status-error: none;
@@ -669,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%);
+}