@microbit/ui 0.1.0-alpha.27 → 0.1.0-alpha.28

package/README.md

@@ -197,6 +197,50 @@ Semantic tokens (`languageText`, `statusBarBg`, `danger.*`, `toast*Bg`,
 brand presets override; they resolve through var indirection, so overrides
 apply wherever the token is consumed.
 
+`focusRing` and `focusBorder` need more care: their values are condition
+objects and a merge replaces a value wholesale, so the flat form drops the
+on-dark flip below. Keep the shape:
+
+```ts
+focusBorder: { value: { base: "{colors.brand.700}", _onDark: "{colors.white}" } };
+```
+
+## Dark surfaces
+
+Focus indicators are surface-aware through one tag. The default focus ring
+is ink; on a dark surface it must be white, so tag the surface element by
+spreading the exported constant:
+
+```tsx
+import { darkSurface } from "@microbit/ui";
+
+<header {...darkSurface}>…</header>; // a black toolbar, a coloured sidebar bar
+```
+
+Custom properties inherit, so tagging the bar covers the bar itself and
+every control inside it — including ones added later. If the tagged element
+is focusable, tag one level in instead: its own ring is drawn _outside_ it,
+on whatever is behind it. (The Toast does this — the card is dark and
+focusable, so the tag sits on its close button.) Portalled overlays (a
+modal opened from a dark toolbar) escape the tag with the DOM, which is
+correct. Under the hood it is `data-surface="dark"`, which the preset's
+`onDark` condition scopes the `focusRing`/`focusBorder` token flips to.
+
+Two rules:
+
+- **Dark surfaces must tag** — the ink ring is near-invisible on them, and
+  there is no automatic detection.
+- **Tag surfaces, not themes**: "dark" describes the surface's own
+  luminance, so tag surfaces that are dark by design (a black toolbar, a
+  coloured sidebar bar) rather than anything relative to the app's overall
+  look. This is what will let the tag survive a dark mode if we ship one:
+  designed-dark surfaces stay dark and keep their tags; everything else
+  stays untagged, and a dark mode would flip the untagged defaults via
+  token conditions, never via markup.
+
+Rule of thumb for coloured bars: tag when the surface lacks 3:1 contrast
+against ink — roughly, darker than the grey ramp's 500.
+
 ## Runtime token lookups
 
 For values that feed _computation_ rather than stylesheets (canvas painting,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.28",
   "description": "micro:bit design-system primitives: react-aria-components + Panda CSS with a design language ported from Chakra UI v2. Ships as source; see README for the consumption setup.",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,7 @@
   "peerDependencies": {
     "@pandacss/dev": "^1.11.4",
     "react": "^18.3.1",
+    "react-aria": "^3.50.0",
     "react-aria-components": "^1.19.0",
     "react-icons": "^4.12.0 || ^5.0.0",
     "react-intl": "^6.6.8 || ^7.0.0"
@@ -47,6 +48,7 @@
     "@vitejs/plugin-react": "^4.5.2",
     "jsdom": "^29.1.1",
     "react": "^18.3.1",
+    "react-aria": "^3.50.0",
     "react-aria-components": "^1.19.0",
     "react-dom": "^18.3.1",
     "react-icons": "^4.12.0",

package/src/Button.recipe.ts

@@ -6,9 +6,10 @@
 import { defineRecipe } from "@pandacss/dev";
 
 // The common transition-property list, inlined (Panda has no
-// transitionProperty token category).
+// transitionProperty token category). No box-shadow: focus indication
+// must never fade in.
 const transitionCommon =
-  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+  "background-color, border-color, color, fill, stroke, opacity, transform";
 
 /**
  * Button recipe — the family button base + sizes, with the house
@@ -46,7 +47,7 @@ export const button = defineRecipe({
     verticalAlign: "middle",
     outline: "none",
     _focusVisible: {
-      focusShadow: "outline",
+      focusRing: "outline",
     },
     _disabled: {
       opacity: 0.4,
@@ -155,12 +156,13 @@ export const button = defineRecipe({
         _active: { bg: "danger.700" },
       },
       // Family-wide variant (every censused app has toolbar-class buttons).
+      // No ring override: the bar decides, and a dark one must spread
+      // `darkSurface` — an app adopting this variant needs the tag with it.
       toolbar: {
         color: "black",
         bg: "white",
         _hover: { bg: "whiteAlpha.900", _disabled: { bg: "white" } },
         _active: { bg: "whiteAlpha.800" },
-        _focusVisible: { focusShadow: "outlineDark" },
       },
     },
   },

package/src/Checkbox.recipe.ts

@@ -38,8 +38,6 @@ export const checkbox = defineSlotRecipe({
       alignItems: "center",
       justifyContent: "center",
       flexShrink: 0,
-      transitionProperty: "box-shadow",
-      transitionDuration: "normal",
       borderWidth: "2px",
       borderStyle: "solid",
       borderRadius: "sm",
@@ -68,7 +66,7 @@ export const checkbox = defineSlotRecipe({
         _hover: { bg: "gray.200", borderColor: "gray.200" },
       },
       "&[data-focus-visible]": {
-        focusShadow: "outline",
+        focusRing: "outline",
       },
     },
     icon: {

package/src/CloseButton.tsx

@@ -57,7 +57,7 @@ export const CloseButton = forwardRef<HTMLButtonElement, CloseButtonProps>(
               transitionDuration: "normal",
               _hover: { bg: "blackAlpha.100" },
               _active: { bg: "blackAlpha.200" },
-              _focusVisible: { focusShadow: "outline" },
+              _focusVisible: { focusRing: "outline" },
             },
             size === "sm"
               ? { width: "6", height: "6", fontSize: "2xs" }

package/src/ComboBox.tsx

@@ -20,6 +20,7 @@ import {
   Popover,
   PopoverProps,
 } from "react-aria-components";
+import { useFocusVisible } from "react-aria";
 import { useIntl } from "react-intl";
 import { RiArrowDownSLine } from "react-icons/ri";
 import { css, cx } from "styled-system/css";
@@ -136,6 +137,10 @@ const ComboBoxInner = <T extends object>(
   const fieldSlots = field({ size: variantProps.size, labelPosition });
   // Anchor the card to the whole control, not to the bare input inside it —
   // otherwise it hangs off the text baseline and is as narrow as the input.
+  // Global modality (text-input key filter): unlike the input's own RAC
+  // attributes, it survives react-aria's synthetic blur during virtual
+  // focus — the select recipe's ring rule pairs it with :has(input:focus).
+  const { isFocusVisible } = useFocusVisible({ isTextInput: true });
   const triggerRef = useRef<HTMLDivElement>(null);
   // RAC's --trigger-width measures the input it anchors a ComboBox to, which
   // is the control's content box — so a card sized from it is narrower than
@@ -176,6 +181,7 @@ const ComboBoxInner = <T extends object>(
         )}
         <div
           ref={triggerRef}
+          data-keyboard-modality={isFocusVisible || undefined}
           className={cx(
             slots.trigger,
             triggerCss ? css(triggerCss) : undefined,

package/src/Field.recipe.ts

@@ -52,7 +52,8 @@ export const field = defineSlotRecipe({
     },
     requiredIndicator: {
       marginStart: "1",
-      color: "danger.500",
+      // 600: red-as-text needs 4.5:1; danger.500 is border-grade (~4.1:1).
+      color: "danger.600",
     },
     helperText: {
       // RAC's Text renders a span, and RadioGroup/CheckboxGroup roots are not
@@ -70,7 +71,8 @@ export const field = defineSlotRecipe({
       mt: "2",
       fontSize: "sm",
       lineHeight: "normal",
-      color: "danger.500",
+      // 600: red-as-text needs 4.5:1 (the invalid border stays 500).
+      color: "danger.600",
     },
   },
   variants: {

package/src/GridList.recipe.ts

@@ -50,7 +50,7 @@ export const gridList = defineSlotRecipe({
         _hover: { bg: "gray.100" },
         "&:has([aria-expanded=true])": { bg: "gray.100" },
       },
-      "&[data-focus-visible]": { focusShadow: "outline" },
+      "&[data-focus-visible]": { focusRing: "outline" },
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },
   },

package/src/Input.recipe.ts

@@ -8,25 +8,16 @@ import { defineRecipe } from "@pandacss/dev";
 // The common transition-property list, inlined (Panda has no
 // transitionProperty token category).
 const transitionCommon =
-  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+  "background-color, border-color, color, fill, stroke, opacity, transform";
 
 /**
  * Input recipe — the outline text field with an sm/md/lg size scale. Used by
  * the shared-ui Input and NativeSelect, and by TextField's input slot.
  *
- * Focus matches both native `:focus-visible` (plain inputs; browsers treat any
- * focus in a text field as focus-visible) and react-aria's `data-focused`
- * (inputs inside RAC TextField).
- *
- * Hover, invalid and focus all set `borderColor`, so their precedence has to be
- * hover < invalid < focus. Declaration order will not buy that: Panda sorts a
- * recipe's state rules itself, ranking selectors against a fixed
- * link/visited/focus/hover/active table, which puts `_hover` *after* focus and
- * after anything the table doesn't mention (`[data-invalid]`). Equal-specificity
- * rules then leave hover winning. So the ladder is spelled with repeated `&`
- * instead — `&&` and `&&&` emit `.input.input` and `.input.input.input`, making
- * precedence specificity rather than order, which nothing downstream can
- * resort. Variants still override freely; they land in a later cascade layer.
+ * hover < focused < invalid is a specificity ladder (`&&`, `&&&`): Panda
+ * sorts state rules against its own pseudo-class table, not declaration
+ * order, so equal-specificity borderColor ties would leave hover winning.
+ * Variants still override freely (later cascade layer).
  *
  * Registered in the base preset (base-preset.ts), which also has the
  * `staticCss` entry that keeps the runtime-prop size variants generated.
@@ -42,27 +33,30 @@ export const input = defineRecipe({
     font: "inherit",
     transitionProperty: transitionCommon,
     transitionDuration: "normal",
-    border: "1px solid",
-    // The accessible outline stops: gray.400 is the ramp's 3:1-on-white
-    // boundary grey (WCAG 1.4.11), and hover steps darker, never lighter.
-    borderColor: "gray.400",
+    border: "2px solid",
+    // Deliberately below 3:1 — valid while something else visually
+    // identifies the field (label, or a ≥3:1 icon/placeholder).
+    // Checkbox/Radio keep gray.400: their box IS the identifier.
+    // Rationale: ui-private docs/a11y-positions.md.
+    borderColor: "gray.300",
     bg: "inherit",
     color: "inherit",
     _hover: { borderColor: "gray.500" },
-    "&&:is([data-invalid], :user-invalid)": {
+    // Any focus, pointer included; the keyboard ring composes on top.
+    // zIndex so the border — and the ring with it — paint over
+    // attached-group neighbours.
+    "&&:is(:focus, [data-focused])": { zIndex: 1, borderColor: "focusBorder" },
+    "&&&:is([data-invalid], :user-invalid)": {
       borderColor: "danger.500",
-      boxShadow: "0 0 0 1px token(colors.danger.500)",
-    },
-    "&&&:is(:focus-visible, [data-focused])": {
-      zIndex: 1,
-      borderColor: "focusBorder",
-      boxShadow: "0 0 0 1px token(colors.focusBorder)",
-      // Focus indicator for forced-colors modes, which strip the box-shadow
-      // and force the border colour (the focusShadow utility's technique; the
-      // ring here is the 1px border tint, not an outline* shadow token).
-      outline: "2px solid transparent",
-      outlineOffset: "2px",
     },
+    // Modality-tracked: RAC's attribute, or Input.tsx's. Native
+    // :focus-visible is the fallback for a bare element wearing the recipe,
+    // but not text-entry ones — browsers match it there on a pointer click,
+    // which is what the tracking exists to exclude.
+    "&&&:is([data-focus-visible], :focus-visible:not([data-rac], input, textarea))":
+      {
+        focusRing: "outline",
+      },
     "&:is(:disabled, [data-disabled])": {
       opacity: 0.4,
       cursor: "not-allowed",

package/src/Input.tsx

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { forwardRef, InputHTMLAttributes } from "react";
+import { mergeProps, useFocusRing } from "react-aria";
 import { css, cx } from "styled-system/css";
 import { input, InputVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
@@ -30,15 +31,19 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
   // groups to the recipe (classroom adds `variant`), and cherry-picking would
   // silently drop them onto the DOM as unknown attributes instead.
   const [variantProps, rest] = input.splitVariantProps(props);
+  // A native input never gets RAC's data-focus-visible, which the recipe's
+  // ring keys off — track modality ourselves, as TextField's input does.
+  const { isFocusVisible, focusProps } = useFocusRing({ isTextInput: true });
   return (
     <input
       ref={ref}
+      data-focus-visible={isFocusVisible || undefined}
       className={cx(
         input(variantProps),
         cssProp ? css(cssProp) : undefined,
         className,
       )}
-      {...rest}
+      {...mergeProps(rest, focusProps)}
     />
   );
 });

package/src/Link.tsx

@@ -18,6 +18,6 @@ export const Link = styled("a", {
       "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform",
     transitionDuration: "normal",
     _hover: { textDecoration: "underline" },
-    _focusVisible: { focusShadow: "outline" },
+    _focusVisible: { focusRing: "outline" },
   },
 });

package/src/ListBox.recipe.ts

@@ -36,7 +36,7 @@ export const listBox = defineSlotRecipe({
       transitionTimingFunction: "ease-in",
       _hover: { bg: "gray.50" },
       "&[data-selected]": { bg: "gray.100", _hover: { bg: "gray.100" } },
-      "&[data-focus-visible]": { focusShadow: "outline" },
+      "&[data-focus-visible]": { focusRing: "outline" },
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },
   },

package/src/Menu.recipe.ts

@@ -66,12 +66,11 @@ export const menu = defineSlotRecipe({
       color: "inherit",
       textDecoration: "none",
       outline: "none",
-      transitionProperty: "background",
-      transitionDuration: "ultra-fast",
-      transitionTimingFunction: "ease-in",
-      // RAC highlights the active item (keyboard or pointer) with data-focused;
-      // data-pressed is the pressed state.
+      // data-focused is RAC's active item, either modality. The highlight
+      // is focus indication: no transition (it snaps with the ring, which
+      // keyboard nav adds; inset, the rows being full-bleed).
       "&[data-focused]": { bg: "gray.100" },
+      "&[data-focus-visible]": { focusRing: "outlineInset" },
       "&[data-pressed]": { bg: "gray.200" },
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },

package/src/Modal.tsx

@@ -368,7 +368,7 @@ export const ModalCloseButton = ({
           transitionDuration: "normal",
           _hover: { bg: "blackAlpha.100" },
           _active: { bg: "blackAlpha.200" },
-          _focusVisible: { focusShadow: "outline" },
+          _focusVisible: { focusRing: "outline" },
         }),
       )}
     >

package/src/NumberField.recipe.ts

@@ -25,6 +25,15 @@ export const numberField = defineSlotRecipe({
     group: {
       position: "relative",
       zIndex: 0,
+      // The stepper overlays the input as a sibling, so the input's own
+      // :hover misses it — the group carries the hover tint. The :not()
+      // list is required: slot recipes layer above plain recipes
+      // (recipes.slots), so this would otherwise override focused/invalid
+      // (see docs/hints.md). :user-invalid takes its own :not(): :not() is
+      // not forgiving, so one list would drop the whole selector on a
+      // browser that doesn't know the pseudo-class (Safari < 16.5).
+      "&:hover input:not(:focus, [data-focused], [data-invalid]):not(:user-invalid)":
+        { borderColor: "gray.500" },
     },
     // A column overlaying the input's right edge, inset by the input border.
     stepper: {
@@ -33,8 +42,8 @@ export const numberField = defineSlotRecipe({
       position: "absolute",
       insetEnd: "0",
       top: "0",
-      height: "calc(100% - 2px)",
-      margin: "1px",
+      height: "calc(100% - 4px)",
+      margin: "2px",
       width: "6",
       zIndex: 1,
     },
@@ -52,18 +61,18 @@ export const numberField = defineSlotRecipe({
       borderColor: "gray.200",
       transitionProperty: "background",
       transitionDuration: "ultra-fast",
-      // Follow the input's corners, less the 1px border the stepper is inset
+      // Follow the input's corners, less the 2px border the stepper is inset
       // by, so the hover and pressed fills curve away with the border instead
       // of squaring off over its arc. Radii track the input recipe's size
       // scale, so the `sm` variant restates them.
       "&:first-child": {
-        borderStartEndRadius: "calc(token(radii.md) - 1px)",
+        borderStartEndRadius: "calc(token(radii.md) - 2px)",
       },
       "&:last-child": {
         borderTop: "1px solid",
         borderTopColor: "gray.200",
         marginTop: "-1px",
-        borderEndEndRadius: "calc(token(radii.md) - 1px)",
+        borderEndEndRadius: "calc(token(radii.md) - 2px)",
       },
       "&[data-hovered]": { bg: "gray.100" },
       "&[data-pressed]": { bg: "gray.200" },
@@ -84,10 +93,10 @@ export const numberField = defineSlotRecipe({
         stepperButton: {
           fontSize: "calc(token(fontSizes.sm) * 0.75)",
           "&:first-child": {
-            borderStartEndRadius: "calc(token(radii.sm) - 1px)",
+            borderStartEndRadius: "calc(token(radii.sm) - 2px)",
           },
           "&:last-child": {
-            borderEndEndRadius: "calc(token(radii.sm) - 1px)",
+            borderEndEndRadius: "calc(token(radii.sm) - 2px)",
           },
         },
       },

package/src/Radio.recipe.ts

@@ -38,8 +38,6 @@ export const radio = defineSlotRecipe({
       alignItems: "center",
       justifyContent: "center",
       flexShrink: 0,
-      transitionProperty: "box-shadow",
-      transitionDuration: "normal",
       borderWidth: "2px",
       borderStyle: "solid",
       borderRadius: "full",
@@ -78,7 +76,7 @@ export const radio = defineSlotRecipe({
         _hover: { bg: "gray.200", borderColor: "gray.200" },
       },
       "&[data-focus-visible]": {
-        focusShadow: "outline",
+        focusRing: "outline",
       },
     },
     label: {

package/src/Select.recipe.ts

@@ -7,8 +7,10 @@ import { defineSlotRecipe } from "@pandacss/dev";
 
 // The common transition-property list, inlined (Panda has no
 // transitionProperty token category).
+// No box-shadow: nothing in this recipe uses one, and the focus ring's
+// layers must never fade in.
 const transitionCommon =
-  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+  "background-color, border-color, color, fill, stroke, opacity, transform";
 
 /**
  * Select slot recipe — the dropdown pair, shared by `Select` (a listbox behind
@@ -62,47 +64,35 @@ export const select = defineSlotRecipe({
       cursor: "pointer",
       transitionProperty: transitionCommon,
       transitionDuration: "normal",
-      border: "1px solid",
-      // As the input recipe: the ramp's accessible outline stop, with hover
-      // stepping darker. The dropdown card below keeps the light gray.200 —
-      // it's a surface edge, not a form-control boundary.
-      borderColor: "gray.400",
+      border: "2px solid",
+      // As the input recipe (rationale there). The dropdown card below
+      // keeps gray.200 — a surface edge, not a form-control boundary.
+      borderColor: "gray.300",
       bg: "white",
       color: "inherit",
-      // As the input recipe, so a Select, a NativeSelect and a TextField in one
-      // form all tint together on hover. (react-aria's TextField has no hover
-      // effect, but matching the family beats matching their docs.)
+      // As the input recipe, so mixed fields tint together on hover.
       _hover: { borderColor: "gray.500" },
       // `data-invalid` lands on the root — and, in a ComboBox, on the input —
       // but never on the trigger: a RAC Button has no validity state, and our
       // ComboBox control is a plain div. So it comes down from the parent.
       // `> &` rather than a descendant selector, so an app's own invalid form
-      // wrapper cannot paint every control inside it red.
-      //
-      // Doubled `&` for the same reason as the input recipe: hover, invalid and
-      // focus all set `borderColor`, and Panda sorts state rules by its own
-      // pseudo-class table rather than declaration order, so hover would win
-      // these ties. The repeated `&` makes the hover < invalid < focus ladder a
-      // matter of specificity instead.
-      "[data-invalid] > &&": {
+      // wrapper cannot paint every control inside it red. Repeated `&`: the
+      // hover < focused < invalid specificity ladder, as the input recipe.
+      "&&:is([data-focused], :has(input:focus))": {
+        borderColor: "focusBorder",
+      },
+      // Border colour alone, as the input recipe.
+      "[data-invalid] > &&&": {
         borderColor: "danger.500",
-        boxShadow: "0 0 0 1px token(colors.danger.500)",
       },
-      // Two focus cases. `data-focus-visible` is Select's button on keyboard
-      // focus only (RAC leaves it unset for mouse, matching the react-aria
-      // docs' Select). The `:has()` arm is ComboBox: its control is a plain
-      // div wrapping an input, so it gets no RAC attributes itself, and as a
-      // text field it should show focus on any modality. That arm watches
-      // native `:focus` rather than the input's `data-focused`, because
-      // react-aria dispatches a synthetic blur at the input whenever virtual
-      // focus moves to an option (aria-activedescendant) — which strips RAC's
-      // attribute for as long as the list has an active option, real focus
-      // never having left. Select's trigger holds no input, so it can't match.
-      "&&&[data-focus-visible], &&&:has(input:focus)": {
-        boxShadow: "0 0 0 1px token(colors.focusBorder)",
-        borderColor: "focusBorder",
-        outline: "2px solid transparent",
-        outlineOffset: "2px",
+      // Keyboard-only ring, two cases. Select's button: RAC's attribute.
+      // ComboBox: the input's RAC attributes are stripped by react-aria's
+      // synthetic blur during virtual focus, so its case combines the two
+      // signals that survive — native :focus plus the global-modality
+      // attribute the component renders (see ComboBox.tsx). No flicker
+      // during list navigation; can't match Select (no input).
+      "&&&[data-focus-visible], &&&[data-keyboard-modality]:has(input:focus)": {
+        focusRing: "outline",
       },
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },
@@ -181,10 +171,11 @@ export const select = defineSlotRecipe({
       cursor: "pointer",
       color: "inherit",
       outline: "none",
-      transitionProperty: "background",
-      transitionDuration: "ultra-fast",
-      transitionTimingFunction: "ease-in",
+      // As the menu recipe: the highlight is focus indication (no
+      // transition — it snaps with the ring, which keyboard nav adds;
+      // inset, the rows being full-bleed).
       "&[data-focused]": { bg: "gray.100" },
+      "&[data-focus-visible]": { focusRing: "outlineInset" },
       "&[data-pressed]": { bg: "gray.200" },
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },

package/src/Slider.recipe.ts

@@ -85,7 +85,7 @@ export const slider = defineSlotRecipe({
       },
       transform: "translate(-50%, -50%)",
       "&[data-focus-visible]": {
-        focusShadow: "outline",
+        focusRing: "outline",
       },
       "&[data-disabled]": {
         bg: "gray.300",

package/src/Switch.recipe.ts

@@ -42,7 +42,7 @@ export const switchRecipe = defineSlotRecipe({
         bg: "controlCheckedBg",
       },
       "&[data-focus-visible]": {
-        focusShadow: "outline",
+        focusRing: "outline",
       },
       "&[data-disabled]": { opacity: 0.4 },
       // Forced-colors modes strip author backgrounds, flattening track and

package/src/Toast.recipe.ts

@@ -67,6 +67,11 @@ export const toast = defineSlotRecipe({
       color: "white",
       maxW: "sm",
       pointerEvents: "auto",
+      // The card is focusable (RAC gives it tabindex), so it takes the
+      // house ring rather than the UA default. Ink, because the ring is
+      // drawn on the page, not the card — Toast.tsx tags the close button.
+      outline: "none",
+      _focusVisible: { focusRing: "outline" },
     },
     // The icon has to be inside the alert region to be announced with the
     // message, so this row — not the root — is what lays the two out.
@@ -115,7 +120,7 @@ export const toast = defineSlotRecipe({
       // Hover is a subtle dark overlay (blackAlpha), not a bright highlight.
       _hover: { bg: "blackAlpha.100" },
       _active: { bg: "blackAlpha.200" },
-      _focusVisible: { focusShadow: "outline" },
+      _focusVisible: { focusRing: "outline" },
     },
   },
   variants: {

package/src/Toast.tsx

@@ -23,6 +23,7 @@ import { toast as toastRecipe } from "styled-system/recipes";
 import { CloseIcon } from "./CloseIcon";
 import { Icon } from "./Icon";
 import { uiMessage } from "./messages";
+import { darkSurface } from "./system";
 
 export type ToastStatus = "info" | "success" | "warning" | "error";
 
@@ -162,6 +163,11 @@ export const ToastProvider = () => {
               <RACButton
                 slot="close"
                 aria-label={intl.formatMessage(uiMessage("ui.close-action"))}
+                // The card is dark at every status, and no app can tag a
+                // surface the package ships. Tagged here, not on the card:
+                // the tag covers the element it sits on, whose own ring is
+                // drawn outside it, on the page.
+                {...darkSurface}
                 className={slots.closeButton}
               >
                 <CloseIcon />

package/src/TooltipButton.tsx

@@ -56,7 +56,7 @@ const triggerStyle: SystemStyleObject = {
   lineHeight: "1",
   cursor: "pointer",
   borderRadius: "50%",
-  _focusVisible: { focusShadow: "outline" },
+  _focusVisible: { focusRing: "outline" },
 };
 
 export interface TooltipButtonProps {

package/src/base-preset.ts

@@ -55,10 +55,11 @@ import { toast } from "./Toast.recipe";
 // - 350 is the decorative/state fill stop (~2.1:1): avatar discs, skeleton
 //   pulse, pressed fills. Never text or boundaries.
 // - 400–900 are ink stops (outlines, placeholders, text) with a contrast
-//   contract on white: 400 ≥ 3:1, the accessible form-outline stop
-//   (WCAG 1.4.11); 500 ≥ 4.5:1, text-safe secondary (placeholders, muted
-//   icons). Presets may re-tint these only luminance-matched — the
-//   contrast figures are the contract, hue is free.
+//   contract on white: 400 ≥ 3:1, the floor for boundaries that identify
+//   a control (checkbox-family boxes; fields rest lighter — see the input
+//   recipe); 500 ≥ 4.5:1, text-safe secondary. Presets may re-tint these
+//   only luminance-matched — the contrast figures are the contract, hue
+//   is free.
 //
 // Override values, never names: raw var(--colors-gray-*) references and
 // paired private presets depend on the names, so a rename is a breaking
@@ -85,7 +86,8 @@ const gray = {
 /**
  * The base preset: the complete, working micro:bit design system. The base
  * token scales (base-tokens.ts), the micro:bit house style
- * (pill `radii.button`, `outline*` focus shadows, Helvetica fonts, the
+ * (pill `radii.button`, the `focusRing` utility/token pair, Helvetica
+ * fonts, the
  * `toolbar` button variant in Button.recipe.ts, the
  * `languageText`/`toast*Bg`/`statusBarBg` semantic tokens), the shared-ui
  * component recipes, the react-aria condition widening, the `globalCss`
@@ -166,11 +168,6 @@ export const basePreset = definePreset({
       },
       shadows: {
         ...shadows,
-        // The 4px focus outline shadow, plus dark/light-surface
-        // companions. Consumed via the `focusShadow` utility.
-        outline: { value: "0 0 0 4px rgba(66, 153, 225, 0.6)" },
-        outlineDark: { value: "0 0 0 4px rgba(0, 0, 0, 0.5)" },
-        outlineLight: { value: "0 0 0 4px rgba(255, 255, 255, 0.8)" },
       },
       fonts: {
         // Helvetica heading/body (4/4 apps); a brand preset leaves these and
@@ -189,13 +186,28 @@ export const basePreset = definePreset({
     },
     semanticTokens: {
       colors: {
-        // Checked/focus states of form controls: Checkbox/Switch/Radio
-        // checked backgrounds and the Input/Select focus border. Semantic
-        // so a brand can diverge them from its ramp — e.g. a light
-        // brand.500 needing a darker 3:1 focus border.
+        // Checked states of form controls: Checkbox/Switch/Radio checked
+        // backgrounds. Semantic so a brand can diverge them from its ramp.
         controlCheckedBg: { value: "{colors.brand.500}" },
         controlCheckedHoverBg: { value: "{colors.brand.600}" },
-        focusBorder: { value: "{colors.brand.500}" },
+        // Focused form-control border, any modality: the dark brand stop
+        // (all-ink read flat next to the ink ring). Flips white under the
+        // dark-surface tag, like `focusRing`.
+        // Both flips are condition objects, and a merge replaces a token
+        // value wholesale: an override must keep the `{ base, _onDark }`
+        // shape or silently lose the flip.
+        focusBorder: {
+          value: { base: "{colors.brand.600}", _onDark: "{colors.white}" },
+        },
+        // The focus ring colour: ink, or white inside `data-surface="dark"`
+        // (the `onDark` condition). The var inherits — tag the bar, cover
+        // its controls; portalled overlays escape with the DOM. Dark
+        // surfaces MUST tag (ink is near-invisible there). Opaque
+        // deliberately: translucent rings washed out (classroom #780).
+        // Both tag states: the Button "Variants" story.
+        focusRing: {
+          value: { base: "{colors.gray.900}", _onDark: "{colors.white}" },
+        },
         // Error/destructive ramp. Destructive button variants,
         // field error states and the error toast; the record* button
         // variants deliberately stay on red.* (recording vocabulary, not
@@ -287,6 +299,11 @@ export const basePreset = definePreset({
     html: {
       textRendering: "optimizeLegibility",
       touchAction: "manipulation",
+      // Alias preset-base's ring plumbing to our colour, so a stray use
+      // of its focusVisibleRing/focusRing* utilities renders in our
+      // ink rather than #005FCC. Still don't use them: un-gated focus
+      // selector, and this alias resolves on <html> (no tag awareness).
+      "--global-color-focus-ring": "var(--colors-focus-ring)",
     },
     body: {
       // No `position: relative` (Chakra had it): it breaks react-aria's
@@ -391,19 +408,51 @@ export const basePreset = definePreset({
   },
   utilities: {
     extend: {
-      // The app-wide focus indicator, usually inside `_focusVisible`. Values
-      // are the outline* shadow token names. The transparent outline is for
-      // forced-colors modes, which strip box-shadows but recolour outlines to
-      // a visible system colour. (Named to avoid preset-base's outline-based
-      // `focusRing` utility, whose values would break this transform.)
-      focusShadow: {
-        className: "focus-shadow",
-        values: ["outline", "outlineDark", "outlineLight"],
-        transform: (value: string, { token }) => ({
-          outline: "2px solid transparent",
-          outlineOffset: "2px",
-          boxShadow: token(`shadows.${value}`),
-        }),
+      // The app-wide focus indicator, usually inside `_focusVisible`: a
+      // 2px `focusRing`-coloured outline at 2px offset — the surface shows
+      // through the gap, and call sites never pick a ring per background.
+      // A real outline, so forced-colors modes keep a ring; longhands
+      // because Panda resolves tokens per-property. Thickness/contrast
+      // rationale: ui-private docs/a11y-positions.md. Shadows
+      // preset-base's `focusRing`: our transform replaces theirs, but the
+      // values arrays union, so its outside/inside/mixed/none typecheck
+      // here. `none` is honoured — the alternative is a permanent un-gated
+      // ring; the other three fall through to the standard one. Don't use
+      // them.
+      focusRing: {
+        className: "focus-ring",
+        // `outlineInset` draws the ring just inside — for full-bleed rows
+        // whose outward ring would overhang their popover.
+        values: ["outline", "outlineInset"],
+        transform: (value: string, { token }) =>
+          value === "none"
+            ? { outlineStyle: "none" }
+            : {
+                outlineStyle: "solid",
+                outlineWidth: "2px",
+                outlineColor: token("colors.focusRing"),
+                outlineOffset: value === "outlineInset" ? "-2px" : "2px",
+              },
+      },
+      // preset-base's remaining ring plumbing sets --focus-ring-* custom
+      // properties only its own utilities read. Repointed at the outline
+      // longhands ours draws with, rather than left as no-ops that read
+      // like working knobs.
+      focusRingWidth: {
+        className: "focus-ring-w",
+        values: "borderWidths",
+        transform: (value: string) => ({ outlineWidth: value }),
+      },
+      focusRingOffset: {
+        className: "focus-ring-o",
+        values: "spacing",
+        transform: (value: string) => ({ outlineOffset: value }),
+      },
+      focusRingStyle: {
+        className: "focus-ring-s",
+        values: "borderStyles",
+        // `outlineStyle` is a keyword union, hence the cast.
+        transform: (value: string) => ({ outlineStyle: value as "solid" }),
       },
     },
   },
@@ -414,9 +463,18 @@ export const basePreset = definePreset({
     extend: {
       hover: "&:is(:hover, [data-hovered])",
       active: "&:is(:active, [data-pressed])",
-      focusVisible: "&:is(:focus-visible, [data-focus-visible])",
+      // Native :focus-visible counts only on elements RAC doesn't manage:
+      // react-aria's modality tracking is stricter than the browser's
+      // (e.g. focus restored from a menu after mouse-only use).
+      focusVisible:
+        "&:is(:focus-visible:not([data-rac]), [data-focus-visible])",
       disabled:
         "&:is(:disabled, [disabled], [data-disabled], [aria-disabled=true])",
+      // A dark-by-design surface (spread the exported `darkSurface` onto
+      // the bar element); scopes the focusRing/focusBorder flips. Never
+      // theme-relative: a future dark mode flips untagged defaults via
+      // token conditions, not markup.
+      onDark: '[data-surface="dark"] &',
       // High-contrast/forced-palette modes (e.g. Windows High Contrast), which
       // strip author backgrounds and box-shadows.
       forcedColors: "@media (forced-colors: active)",

package/src/base-tokens.ts

@@ -960,9 +960,6 @@ export const shadows = {
   "2xl": {
     value: "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
   },
-  outline: {
-    value: "0 0 0 3px rgba(66, 153, 225, 0.6)",
-  },
   inner: {
     value: "inset 0 2px 4px 0 rgba(0,0,0,0.06)",
   },

package/src/system.ts

@@ -43,3 +43,15 @@ export {
   Wrap,
   styled,
 } from "styled-system/jsx";
+
+/**
+ * Spread onto a surface element that is dark by design — a black toolbar,
+ * a coloured sidebar header — so focus indicators inside it flip to their
+ * on-dark colours: `<header {...darkSurface}>`.
+ *
+ * Tag a surface's own designed luminance, never anything theme-relative
+ * (a future dark mode flips untagged defaults via token conditions, not
+ * markup). One inherited data attribute (the `onDark` condition): tag the
+ * bar, cover its controls; portalled overlays escape with the DOM.
+ */
+export const darkSurface = { "data-surface": "dark" } as const;