@reliability-design/web 1.4.6 → 1.4.8

package/dist/styles/focus-ring.ts

@@ -0,0 +1,84 @@
+import { css } from "lit";
+
+/**
+ * The composed focus ring (S1).
+ *
+ * Figma draws focus as up to two concentric strokes, and several components
+ * also draw a hover / dragged stroke on the same edge. Implementing those as
+ * per-component `outline` + `box-shadow` pairs does not work: `box-shadow` is
+ * a single property, so a `:hover` rule that sets it wipes the focus ring a
+ * `:focus-visible` rule set, and specificity decides the winner rather than
+ * intent. rel-chip hit exactly this (its subtle tones set `border-color` on
+ * hover, and moving that to an inset shadow clobbered the inner focus ring).
+ *
+ * So the layers are composed ONCE here, and every state rule contributes by
+ * setting a custom property instead of re-declaring `box-shadow`. Widths
+ * default to `0px`, so a layer costs nothing until a state turns it on, and
+ * hover / dragged / focus can all be active at the same time.
+ *
+ *   --_rel-ring-w / -c          outer ring  (Figma strokeAlign=OUTSIDE)
+ *   --_rel-ring-inner-w / -c    inner ring  (Figma strokeAlign=INSIDE)
+ *   --_rel-ring-stroke-w / -c   hover / dragged stroke, also INSIDE
+ *   --_rel-ring-elevation       the element's own box-shadow, if it has one
+ *
+ * ## Why the outer ring is an `outline` and not another shadow layer
+ *
+ * `box-shadow` is not painted in forced-colors mode (Windows High Contrast),
+ * but `outline` is, and the UA forces it to the user's highlight colour. A
+ * ring built entirely from shadows therefore disappears for exactly the users
+ * who most depend on it — a WCAG 2.4.11 failure. Keeping the OUTER ring on
+ * `outline` means focus stays visible there even though the inner ring and the
+ * hover stroke (both decorative refinements) drop out. `outline` also never
+ * affects layout, and at `outline-offset: 0` it sits flush against the border
+ * box, which is precisely what strokeAlign=OUTSIDE means.
+ *
+ * ## Usage
+ *
+ *   static styles = [focusRing, css`…`];
+ *
+ * Put `class="rel-ring"` on the element that carries the ring, then drive it
+ * from state rules:
+ *
+ *   .chip:has(.chip-action:focus-visible) { --_rel-ring-w: 1.5px; --_rel-ring-inner-w: 1px; }
+ *   .chip:hover                           { --_rel-ring-stroke-w: 1px; --_rel-ring-stroke-c: …; }
+ *
+ * Recipe A (button, chip, checkbox, radio, switch): outer `--rel-border-focus`
+ * at 1.5px, plus `--rel-border-focus-inner` INSIDE on filled styles only —
+ * 2px on button, 1px on chip and switch.
+ *
+ * Recipe B (textfield, select, otp, picker triggers): keep the resting 1px
+ * hairline and draw `--rel-border-strong` 2px outside it. Recipe B needs only
+ * the outer ring here; the hairline stays the element's own `border`.
+ *
+ * An element that already has a shadow (elevation) must hand it over as
+ * `--_rel-ring-elevation` instead of declaring `box-shadow` itself, or the
+ * composed declaration below will replace it.
+ */
+export const focusRing = css`
+  :host {
+    --_rel-ring-w: 0px;
+    --_rel-ring-c: var(--rel-border-focus);
+    --_rel-ring-inner-w: 0px;
+    --_rel-ring-inner-c: var(--rel-border-focus-inner);
+    --_rel-ring-stroke-w: 0px;
+    --_rel-ring-stroke-c: transparent;
+    --_rel-ring-elevation: 0 0 #0000;
+  }
+
+  .rel-ring {
+    outline: var(--_rel-ring-w) solid var(--_rel-ring-c);
+    outline-offset: 0;
+    box-shadow:
+      inset 0 0 0 var(--_rel-ring-stroke-w) var(--_rel-ring-stroke-c),
+      inset 0 0 0 var(--_rel-ring-inner-w) var(--_rel-ring-inner-c),
+      var(--_rel-ring-elevation);
+  }
+
+  /* Both inset layers are dropped here by the UA; the outer ring carries the
+     whole indication, so force it to the system highlight colour. */
+  @media (forced-colors: active) {
+    .rel-ring {
+      outline-color: Highlight;
+    }
+  }
+`;