@microbit/ui 0.1.0-alpha.3 → 0.1.0-alpha.31

package/src/base-preset.ts

@@ -20,39 +20,106 @@ import {
   sizes,
   spacing,
   zIndex,
-} from "./chakra-tokens";
+} from "./base-tokens";
 // Config recipes are colocated with the shared-ui components they style; this
 // preset registers them so Panda merges them at codegen time.
+import { avatar } from "./Avatar.recipe";
+import { breadcrumb } from "./Breadcrumb.recipe";
 import { button } from "./Button.recipe";
 import { card } from "./Card.recipe";
 import { checkbox } from "./Checkbox.recipe";
+import { radio } from "./Radio.recipe";
 import { drawer } from "./Drawer.recipe";
+import { gridList } from "./GridList.recipe";
 import { heading } from "./Heading.recipe";
 import { input } from "./Input.recipe";
+import { listBox } from "./ListBox.recipe";
+import { numberField } from "./NumberField.recipe";
 import { menu } from "./Menu.recipe";
+import { select } from "./Select.recipe";
 import { slider } from "./Slider.recipe";
 import { switchRecipe } from "./Switch.recipe";
 import { dialog } from "./Modal.recipe";
-import { field } from "./TextField.recipe";
+import { text } from "./Text.recipe";
+import { tooltip } from "./Tooltip.recipe";
+import { field } from "./Field.recipe";
 import { toast } from "./Toast.recipe";
 
+// The family gray ramp: pure neutrals as the library default. The two
+// halves have different jobs and different override rules:
+//
+// - 10–300 are surface stops (panels, page backdrops, hairlines, subtle
+//   fills). Presets may freely override these values — pinning an app's
+//   existing surfaces or applying a brand tint — because a few bits of
+//   lightness here reads across a whole viewport.
+// - 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 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
+// change to both and needs every app and paired preset moved in lockstep
+// (as was done when the misnamed darker-than-50 stop `25` became
+// `75`). And never override partially in a way that lets a stop fall
+// through to a different grey system.
+const gray = {
+  10: { value: "#fcfcfc" },
+  50: { value: "#f9f9f9" },
+  75: { value: "#f5f5f5" },
+  100: { value: "#f1f1f1" },
+  200: { value: "#e7e7e7" },
+  300: { value: "#d4d4d4" },
+  350: { value: "#b4b4b4" }, // ~2.1:1 — decorative fills only
+  400: { value: "#949494" }, // 3.05:1 — accessible outline stop
+  500: { value: "#767676" }, // 4.54:1 — text-safe secondary
+  600: { value: "#575757" },
+  700: { value: "#404040" },
+  800: { value: "#262626" },
+  900: { value: "#1a1a1a" },
+};
+
+// The family red, on the gray ramp's ladder — it is the conventional colour
+// for errors and recording, not a brand colour, so it can be graded rather
+// than negotiated. 400 was already exactly gray's 3:1 and stays verbatim,
+// anchoring the hue and saturation the darker stops hold while their
+// lightness solves for gray's ratio. The washes have no contract and keep
+// their values.
+const red = {
+  50: { value: "#FFF5F5" },
+  100: { value: "#FED7D7" },
+  200: { value: "#FEB2B2" },
+  300: { value: "#FC8181" },
+  400: { value: "#F56565" }, // 3.03:1
+  500: { value: "#e22b2b" }, // 4.55:1 — the white-text fill stop
+  600: { value: "#ac1818" },
+  700: { value: "#811212" },
+  800: { value: "#4f0b0b" },
+  900: { value: "#380808" },
+};
+
 /**
- * The base preset: the complete, working micro:bit design system. Chakra v2's
- * default token scales (chakra-tokens.ts snapshot), the micro:bit house style
- * (pill `radii.button`, `outline*` focus shadows, Helvetica fonts, the
- * `language`/`toolbar` button variants in Button.recipe.ts, the
+ * 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`, 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 Chakra-reset
- * parity `globalCss`, and the `staticCss` that keeps runtime-prop recipe
+ * component recipes, the react-aria condition widening, the `globalCss`
+ * defaults, and the `staticCss` that keeps runtime-prop recipe
  * variants generated. Used alone it renders in the OSS default look.
  *
  * ── Brand contract ──────────────────────────────────────────────────────
  * A private brand preset (a sibling repo, e.g. CreateAI) is merged AFTER this
  * one to restyle everything by overriding just these token *values* (never
  * their names — see the CSS-var contract in the README):
- *   - colours: the `brand` and `brand2` ramps (OSS defaults: Chakra
- *     blue / Chakra's unmodified gray). Other ramps a brand tweaks
- *     (teal/purple/pink/…) already exist in the Chakra scales below.
+ *   - colours: the `brand` and `brand2` ramps (OSS defaults: the blue
+ *     ramp / a legacy slate gray). Other ramps a brand tweaks
+ *     (teal/purple/pink/…) already exist in the base scales below.
  *   - font: `display` (OSS default: Helvetica; e.g. GT Walsheim privately).
  * The recipes and semantic tokens here reference those, so a brand swap needs
  * no recipe changes. With no private preset, these OSS defaults stand.
@@ -62,25 +129,44 @@ export const basePreset = definePreset({
   theme: {
     breakpoints,
     keyframes: {
-      // Spinner's revolution (the only keyframe a shared-ui component uses).
+      // Spinner's revolution.
       spin: {
         "0%": { transform: "rotate(0deg)" },
         "100%": { transform: "rotate(360deg)" },
       },
+      // Skeleton's pulse, over the pair of custom properties the component
+      // sets, so a retinted skeleton animates between its own colours.
+      skeletonFade: {
+        from: {
+          borderColor: "var(--skeleton-start-color)",
+          background: "var(--skeleton-start-color)",
+        },
+        to: {
+          borderColor: "var(--skeleton-end-color)",
+          background: "var(--skeleton-end-color)",
+        },
+      },
+      // Toast enter/exit, played on the view-transition snapshots (see the
+      // ::view-transition rules in globalCss): fade + short slide in,
+      // quicker fade + shrink out.
+      toastSlideIn: {
+        from: { opacity: 0, transform: "translateY(-24px)" },
+      },
+      toastSlideOut: {
+        to: { opacity: 0, transform: "scale(0.85)" },
+      },
     },
     tokens: {
       colors: {
         ...colors,
-        gray: {
-          ...colors.gray,
-          // Very light grays the family's designs use below Chakra's 50.
-          10: { value: "#fcfcfc" },
-          25: { value: "#f5f5f5" },
-        },
+        gray,
+        red,
         // OSS default brand ramps (see the brand contract above). `brand`
-        // aliases Chakra blue; `brand2` Chakra's *unmodified* gray (not the
-        // `gray` above, whose 10/25 additions are lighter — getting this
-        // wrong once made card text near-invisible).
+        // aliases the blue ramp; `brand2` is a frozen legacy alias of the
+        // slate gray in base-tokens, deliberately decoupled from the neutral
+        // `gray` above so ml-trainer's OSS look and `statusBarBg`'s default
+        // don't move.
+        // Removing the slot is a follow-up needing an ml-trainer lockstep.
         brand: colors.blue,
         brand2: colors.gray,
       },
@@ -102,16 +188,11 @@ export const basePreset = definePreset({
       },
       shadows: {
         ...shadows,
-        // Chakra's outline shadow widened to 4px, 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
         // overrides only `display` (the marketing font — see the brand
-        // contract above). `mono` is Chakra's default stack.
+        // contract above).
         heading: { value: "Helvetica, Arial, sans-serif" },
         body: { value: "Helvetica, Arial, sans-serif" },
         mono: {
@@ -125,39 +206,86 @@ export const basePreset = definePreset({
     },
     semanticTokens: {
       colors: {
-        // Checked/focus states of form controls (Chakra's default blue
-        // colorScheme). Checkbox/Switch checked backgrounds, Input focus
-        // border, and the Slider/ProgressBar fills (the last two are
-        // near-dead defaults - current call sites override them).
-        controlCheckedBg: { value: "{colors.blue.500}" },
-        controlCheckedHoverBg: { value: "{colors.blue.600}" },
-        focusBorder: { value: "{colors.blue.500}" },
-        sliderFilledTrack: { value: "{colors.blue.500}" },
-        progressFilledTrack: { value: "{colors.blue.500}" },
-        // Error/destructive ramp (Chakra red). Destructive button variants,
-        // field error states and the error toast; the record* button
-        // variants deliberately stay on red.* (recording vocabulary, not
-        // danger).
+        // 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}" },
+        // 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: field error states, the error toast, and
+        // the `danger` button tone. Aliased whole, not just at the stops in
+        // use, so a tone has nowhere to fall through (Button.recipe.ts).
         danger: {
           50: { value: "{colors.red.50}" },
           100: { value: "{colors.red.100}" },
+          200: { value: "{colors.red.200}" },
+          300: { value: "{colors.red.300}" },
+          400: { value: "{colors.red.400}" },
           500: { value: "{colors.red.500}" },
           600: { value: "{colors.red.600}" },
           700: { value: "{colors.red.700}" },
+          800: { value: "{colors.red.800}" },
+          900: { value: "{colors.red.900}" },
         },
-        // The `language` button variant's text colour is the one place the
-        // brands diverge structurally (OSS uses the grey brand2 ramp, the
-        // CreateAI brand its blue brand ramp with no hover change). Driven by
-        // these semantic tokens so the recipe stays shared and a brand preset
-        // overrides only the values.
-        languageText: { value: "{colors.brand2.500}" },
-        languageTextHover: { value: "{colors.brand2.600}" },
-        // Toast status colours: the Chakra-era toast Alert restyle (teal for
-        // every status except error) shared across the app family.
+        // The language-dialog cards' text colour (@microbit/ui-patterns'
+        // LanguageDialog) follows the primary interactive brand: every
+        // consumer resolves it to its `brand` ramp (CreateAI privately to
+        // brand.600 with no hover change, python-editor to brand.500/600 —
+        // the default; data-microbit-org to black). Semantic tokens so the
+        // pattern stays shared and a brand preset overrides only values.
+        languageText: { value: "{colors.brand.500}" },
+        languageTextHover: { value: "{colors.brand.600}" },
+        // The `label`/`subtitle` heading variants' colour (page-title chrome).
+        // classroom and data-microbit-org carried byte-identical variants with
+        // a hardcoded #cd0365 — the brand deep pink, which is data's
+        // `pink.500`; both override this to it. The OSS default follows the
+        // languageText precedent: the primary interactive brand.
+        headingAccent: { value: "{colors.brand.500}" },
+        // The `primary`/`secondary` button variants' colours. Two brand
+        // idioms exist in the family: brand-coloured buttons (ml-trainer,
+        // python-editor — the defaults below) and a black-on-white system
+        // (classroom, data-microbit-org: black solid, black outline, no
+        // border colour change on hover but a blackAlpha wash instead).
+        // Tokens rather than per-app recipe overrides so both idioms share
+        // one recipe — a `variant` fork would be duplicated by every app on
+        // the far side of it. `primary`'s text colour stays a literal
+        // `white`: every app in the family puts white on a dark solid.
+        // `ghost` needs no tokens (black + blackAlpha in all four apps).
+        button: {
+          primaryBg: { value: "{colors.brand.500}" },
+          primaryHoverBg: { value: "{colors.brand.600}" },
+          primaryActiveBg: { value: "{colors.brand.700}" },
+          secondaryText: { value: "{colors.brand.700}" },
+          secondaryBorder: { value: "{colors.brand.500}" },
+          secondaryHoverBorder: { value: "{colors.brand.600}" },
+          secondaryHoverBg: { value: "transparent" },
+          secondaryActiveBorder: { value: "{colors.brand.700}" },
+          secondaryActiveBg: { value: "{colors.brand.50}" },
+        },
+        // Toast status colours (teal for every status except error), shared
+        // across the app family.
         toastInfoBg: { value: "{colors.teal.800}" },
         toastSuccessBg: { value: "{colors.teal.800}" },
         toastWarningBg: { value: "{colors.teal.800}" },
-        toastErrorBg: { value: "{colors.danger.600}" },
+        // 500, the text-safe stop, rather than following the teal toasts'
+        // 800: white on it is 4.55:1 and an error toast should read as red.
+        toastErrorBg: { value: "{colors.danger.500}" },
         // The native app's status-bar area colour, shared by the ActionBar
         // and the full-size dialog's safe-area gradient.
         statusBarBg: { value: "{colors.brand2.500}" },
@@ -167,33 +295,45 @@ export const basePreset = definePreset({
       button,
       heading,
       input,
+      text,
+      tooltip,
     },
     slotRecipes: {
+      avatar,
+      breadcrumb,
       card,
       checkbox,
       dialog,
       drawer,
       field,
+      gridList,
+      listBox,
       menu,
+      numberField,
+      radio,
+      select,
       slider,
       switchRecipe,
       toast,
     },
   },
-  // What ChakraProvider used to inject and Panda's preflight doesn't cover:
-  // the theme's styles.global (body text/background defaults, global
-  // border/placeholder colours) plus the parts of Chakra's CSS reset that
-  // Panda's has no equivalent for — kerning/text-rendering (their absence
-  // shifts glyphs page-wide), word-wrap and touch-action. Token references
-  // resolve against the merged preset stack, so the values track any brand
-  // overrides exactly as they did under Chakra's runtime theme.
+  // Global defaults Panda's preflight doesn't cover: body text/background,
+  // placeholder colour, kerning/text-rendering (their absence shifts
+  // glyphs page-wide) and touch-action. Token references resolve against
+  // the merged preset stack, so the values track any brand overrides.
   globalCss: {
     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: {
-      position: "relative",
+      // No `position: relative` (Chakra had it): it breaks react-aria's
+      // overlay positioning — see Tooltip's "In a scrolling page" story.
       minHeight: "100%",
       fontFeatureSettings: '"kern"',
       fontFamily: "body",
@@ -206,21 +346,70 @@ export const basePreset = definePreset({
     "*::placeholder": {
       color: "gray.500",
     },
-    "*, *::before, *::after": {
-      borderColor: "gray.200",
-      wordWrap: "break-word",
-    },
-    // Panda's preflight, unlike Chakra's reset, doesn't set the pointer
-    // cursor on buttons. Recipes' disabled states (cursor: not-allowed)
-    // override this from the higher recipes layer.
+    // The `* { border-color; word-wrap }` defaults live in ../reset.css,
+    // imported into the `reset` layer by consumers' layers.css — NOT here:
+    // globalCss emits into the `base` layer, which the legacy-Safari
+    // cascade-layer flattening specificity-boosts above runtime-injected
+    // CSS (CodeMirror themes) and other app CSS files. Resets must stay in
+    // the bottom layer.
+    // Panda's preflight doesn't set the pointer cursor on buttons.
+    // Recipes' disabled states (cursor: not-allowed) override this from
+    // the higher recipes layer.
     "button, [role='button']": {
       cursor: "pointer",
     },
-    // Panda's preflight balance-wraps headings; Chakra didn't, and balanced
-    // multi-line headings break at different points (mobile/translations).
+    // Panda's preflight balance-wraps headings; balanced multi-line
+    // headings break at different points (mobile/translations), so undo it.
     "h1, h2, h3, h4, h5, h6": {
       textWrap: "wrap",
     },
+    // The colour of the seams an attached ButtonGroup draws (ButtonGroup.tsx).
+    // Transparent, so a variant with no border of its own divides by letting
+    // the surface show through rather than by a line in the text colour.
+    //
+    // From `base`, so a variant that does bring a border colours its seams
+    // from `recipes` (as the cursor rule above is overridden). Longhands
+    // because Panda resolves `transparent` to a token, and the logical
+    // *shorthand* with a var() value is the one Safari 14.x drops — the
+    // postcss-legacy-safari shim does not cover the border ones.
+    "[data-attached] > *": {
+      borderInlineStartColor: "transparent",
+      borderInlineEndColor: "transparent",
+    },
+    // While a full-size dialog is open (the Modal stamps data-fullsize on
+    // its overlay), release the scrollbar gutter that react-aria's scroll
+    // lock reserves on the root. The reserved strip is scrollbar chrome to
+    // hit-testing — elementFromPoint returns null there, so clicks fall
+    // through to the root and dismiss the dialog, and controls near the
+    // right edge lose part of their target. With the page fully covered,
+    // the reflow this causes is invisible. !important: react-aria sets the
+    // reservation as a non-important inline style.
+    "html:has([data-fullsize])": {
+      scrollbarGutter: "auto !important",
+    },
+    // Toast enter/exit (the ToastQueue wraps updates in
+    // document.startViewTransition — see Toast.tsx, which also stamps the
+    // scoping class on <html> while its transitions run). Timings: 0.4s
+    // fade+slide in, 0.2s fade+shrink out; the
+    // stack reflow comes from the default group animation. `(*)` +
+    // `:only-child` matches exactly the entering/exiting toast groups: the
+    // root snapshot always has both old and new children, and toasts are
+    // the only named groups during a toast transition. The snapshot
+    // overlay must not eat clicks while a toast animates, hence
+    // pointer-events, scoped likewise.
+    "html.microbit-ui-toast-transition::view-transition": {
+      pointerEvents: "none",
+    },
+    // `both` fill: the snapshots must hold the keyframes' end states for
+    // however long the rest of the transition (e.g. the 0.25s default group
+    // animation) outlives them, or they snap back to full size/opacity for
+    // the remainder.
+    "html.microbit-ui-toast-transition::view-transition-new(*):only-child": {
+      animation: "toastSlideIn 0.4s cubic-bezier(0.4, 0, 0.2, 1) both",
+    },
+    "html.microbit-ui-toast-transition::view-transition-old(*):only-child": {
+      animation: "toastSlideOut 0.2s cubic-bezier(0.4, 0, 1, 1) both",
+    },
   },
   // shared-ui components forward `variant`/`size`/etc. as runtime props to
   // the recipe functions, so Panda's static analysis can't see which variants
@@ -229,45 +418,108 @@ export const basePreset = definePreset({
   // can silently lose runtime-prop variants.
   staticCss: {
     recipes: {
-      button: ["*"],
+      // Size is passed responsively at call sites
+      // (`size={["md", "lg"]}`), so generate the breakpoint-prefixed variants
+      // too — otherwise the class lands on the element with no rule behind it
+      // and the button silently falls back to the base size.
+      avatar: ["*"],
+      // `tone` generates as its own rule, not crossed with `variant`: it
+      // only assigns the palette custom properties a shape reads.
+      button: [
+        { size: ["*"], responsive: true },
+        { variant: ["*"] },
+        { tone: ["*"] },
+      ],
+      checkbox: ["*"],
       heading: ["*"],
       card: ["*"],
       // Dialog size is chosen with responsive objects ({ base, md }) passed
       // as a runtime prop, so generate the breakpoint-prefixed variants too.
       dialog: [{ size: ["*"], responsive: true }, { centered: ["*"] }],
       drawer: ["*"],
+      field: ["*"],
+      gridList: ["*"],
+      listBox: ["*"],
+      input: ["*"],
+      numberField: ["*"],
+      radio: ["*"],
+      select: ["*"],
+      switchRecipe: ["*"],
+      text: ["*"],
+      tooltip: ["*"],
       // Toast status is chosen at runtime from the toast content.
       toast: ["*"],
     },
   },
   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" }),
       },
     },
   },
-  // Widen the interaction conditions so the Chakra-shaped recipe/style objects
-  // (`_hover`/`_active`/`_focusVisible`/`_disabled`) also respond to
+  // Widen the interaction conditions so recipe/style objects written with
+  // `_hover`/`_active`/`_focusVisible`/`_disabled` also respond to
   // react-aria-components' data attributes, not just native pseudo-classes.
   conditions: {
     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/{chakra-tokens.ts → base-tokens.ts}

@@ -1,12 +1,15 @@
 /**
  * (c) 2026, Micro:bit Educational Foundation and contributors
  *
+ * Token values (c) 2019, Segun Adebayo — Chakra UI's @chakra-ui/theme
+ * defaults, used under the MIT License (see LICENSE.md third-party notices).
+ *
  * SPDX-License-Identifier: MIT
  */
-/* eslint-disable */
-// GENERATED by bin/gen-chakra-tokens.mjs (snapshot of @chakra-ui/theme defaults).
-// Do not edit by hand. Canonical Chakra v2 foundation values in Panda token
-// format so the OSS preset matches Chakra exactly.
+// The base token scales, in Panda token format. Began as a mechanical
+// snapshot of Chakra UI v2's @chakra-ui/theme defaults; hand-maintained.
+// Deliberately absent: `fonts` (foundation-owned, defined in base-preset.ts)
+// and `transition.property` (no Panda token category; inlined at use sites).
 
 export const colors = {
   transparent: {
@@ -957,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/button-icon.ts

@@ -0,0 +1,22 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { cva } from "styled-system/css";
+
+// Keeps the glyph centred and spaced 0.5rem from the label. Shared by Button
+// and LinkButton; deliberately not exported from the package index.
+export const buttonIcon = cva({
+  base: {
+    display: "inline-flex",
+    alignSelf: "center",
+    flexShrink: 0,
+  },
+  variants: {
+    side: {
+      start: { marginEnd: "2" },
+      end: { marginStart: "2" },
+    },
+  },
+});

package/src/data-attrs.ts

@@ -0,0 +1,16 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * The `data-*` entries of a props object, for components that let a caller
+ * put test hooks on an inner element rather than the one their props land on.
+ *
+ * Internal: not exported from the package.
+ */
+export const dataAttrs = (props: object): Record<string, unknown> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([key]) => key.startsWith("data-")),
+  );