@microbit/ui 0.1.0-alpha.16 → 0.1.0-alpha.17

package/README.md

@@ -84,10 +84,13 @@ node_modules/@microbit/ui/lang/ui.fr.json --ast --out-file ...` (multiple
    input files merge; ids are `ui.`-namespaced so they can't collide). This
    keeps the strings in the app's lazily loaded locale chunks rather than
    an eagerly bundled catalog-of-all-locales.
-6. **`ToastProvider`** once near the root, inside the `IntlProvider`.
-7. Optionally **`SharedUIProvider`** with an overlay-close registrar so the
-   app can dismiss open menus from outside the tree (e.g. the Android
-   hardware back button). Apps without one can omit the provider.
+6. **`SharedUIProvider`** inside the `IntlProvider`, wrapping the app. It
+   passes the locale on to react-aria, which translates its own built-in
+   strings (see [Strings](#strings)); without it those follow the browser
+   rather than the app's language setting. Also takes an optional
+   overlay-close registrar, so the app can dismiss open menus from outside
+   the tree (e.g. the Android hardware back button).
+7. **`ToastProvider`** once near the root, inside the two providers above.
 
 ## Legacy browser support (Safari < 15) — temporary
 
@@ -207,6 +210,20 @@ Crowdin ZIP>` (config-driven over packages in
 `bin/update-translations.cjs`), after which you run `npm run i18n:tidy`
 from the root.
 
+### react-aria's own strings
+
+Separately from all of the above, react-aria has built-in strings of its own —
+stepper button labels, the toast region's landmark label, hidden dismiss
+buttons, listbox and selection announcements — and translates them from
+catalogs it bundles, nothing to do with react-intl. `SharedUIProvider` hands it
+the app's locale so the two agree.
+
+It covers 32 locales. Of ours, ca, cy and ga-IE (and the `lol` pseudo-locale)
+are not among them and fall back to English; the rest resolve, including where
+our id is less specific than react-aria's (`fr` finds its fr-FR). There is no
+supported way to supply translations for the locales it misses, so where one of
+its strings matters we pass our own text in as a label instead.
+
 ## Chakra UI heritage and license
 
 This package's design language began as a faithful port of

package/lang/ui.en.json

@@ -1,8 +1,16 @@
 {
+  "ui.breadcrumb": {
+    "defaultMessage": "Breadcrumb",
+    "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
+  },
   "ui.close-action": {
     "defaultMessage": "Close",
     "description": "Close button text or label"
   },
+  "ui.loading": {
+    "defaultMessage": "Loading",
+    "description": "Announced by screen readers for a button showing a loading spinner"
+  },
   "ui.toast-status-error": {
     "defaultMessage": "Error",
     "description": "Announced by screen readers before an error notification"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.17",
   "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",

package/src/Breadcrumb.recipe.ts

@@ -0,0 +1,43 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Breadcrumb slot recipe — Chakra's Breadcrumb layout: a flex list with a
+ * separator between items. The links themselves are the shared `Link`
+ * (Chakra's BreadcrumbLink base was identical to its Link base), so there is
+ * no link slot; the current page renders as a plain span.
+ *
+ * Registered in the base preset (base-preset.ts). No variants, so it needs
+ * no `staticCss` entry.
+ */
+export const breadcrumb = defineSlotRecipe({
+  className: "breadcrumb",
+  slots: ["root", "list", "item", "separator"],
+  base: {
+    root: {},
+    list: {
+      display: "flex",
+      alignItems: "center",
+      listStyle: "none",
+      margin: 0,
+      padding: 0,
+    },
+    item: {
+      display: "inline-flex",
+      alignItems: "center",
+      // The separator renders inside every item (no children introspection);
+      // the last item's simply doesn't show.
+      "&:last-of-type [data-separator]": { display: "none" },
+    },
+    separator: {
+      // Chakra's default `spacing` was a literal 0.5rem; the token follows
+      // the library's existing lean (the button icon gap made the same
+      // call — see the playbook's open token-vs-literal spacing decision).
+      mx: "2",
+    },
+  },
+});

package/src/Breadcrumb.tsx

@@ -0,0 +1,116 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext } from "react";
+import { useIntl } from "react-intl";
+import { css, cx } from "styled-system/css";
+import { styled, type HTMLStyledProps } from "styled-system/jsx";
+import { breadcrumb } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { Link } from "./Link";
+import { uiMessage } from "./messages";
+
+// The separator is declared once on the Breadcrumb and rendered by every
+// item; the current-page flag hops from BreadcrumbItem to the BreadcrumbLink
+// inside it (Chakra did both with cloneElement).
+const SeparatorContext = createContext<ReactNode>("/");
+const CurrentPageContext = createContext(false);
+
+export interface BreadcrumbProps {
+  /** Between items; an element or string. Chakra's default "/". */
+  separator?: ReactNode;
+  /** Per-instance style overrides for the nav (e.g. fontSize). */
+  css?: SystemStyleObject;
+  className?: string;
+  /** BreadcrumbItems. */
+  children: ReactNode;
+}
+
+/**
+ * Breadcrumb — navigation trail matching Chakra's: nav > ol > li with a
+ * separator between items and the current page as plain text with
+ * `aria-current="page"`.
+ */
+export const Breadcrumb = ({
+  separator = "/",
+  css: cssProp,
+  className,
+  children,
+}: BreadcrumbProps) => {
+  const intl = useIntl();
+  const slots = breadcrumb();
+  return (
+    <nav
+      aria-label={intl.formatMessage(uiMessage("ui.breadcrumb"))}
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+    >
+      <SeparatorContext.Provider value={separator}>
+        <ol className={slots.list}>{children}</ol>
+      </SeparatorContext.Provider>
+    </nav>
+  );
+};
+
+export interface BreadcrumbItemProps {
+  /**
+   * Marks this item as the current page: its BreadcrumbLink renders as a
+   * plain span with `aria-current="page"` rather than a link.
+   */
+  isCurrentPage?: boolean;
+  css?: SystemStyleObject;
+  className?: string;
+  children: ReactNode;
+}
+
+export const BreadcrumbItem = ({
+  isCurrentPage = false,
+  css: cssProp,
+  className,
+  children,
+}: BreadcrumbItemProps) => {
+  const separator = useContext(SeparatorContext);
+  const slots = breadcrumb();
+  return (
+    <li
+      className={cx(slots.item, cssProp ? css(cssProp) : undefined, className)}
+    >
+      <CurrentPageContext.Provider value={isCurrentPage}>
+        {children}
+      </CurrentPageContext.Provider>
+      <span
+        data-separator
+        role="presentation"
+        aria-hidden
+        className={slots.separator}
+      >
+        {separator}
+      </span>
+    </li>
+  );
+};
+
+export type BreadcrumbLinkProps = HTMLStyledProps<"a">;
+
+// The current page's text: same element shape as the link (so call-site
+// style props keep working) minus the interactivity.
+const CurrentPageText = styled("span");
+
+/**
+ * The trail's link: the shared `Link` (Chakra's BreadcrumbLink base was its
+ * Link base), or a plain span with `aria-current="page"` inside an item
+ * marked `isCurrentPage`.
+ */
+export const BreadcrumbLink = (props: BreadcrumbLinkProps) => {
+  const isCurrentPage = useContext(CurrentPageContext);
+  if (isCurrentPage) {
+    const { href: _href, children, ...rest } = props;
+    return (
+      <CurrentPageText aria-current="page" {...rest}>
+        {children}
+      </CurrentPageText>
+    );
+  }
+  return <Link {...props} />;
+};

package/src/Button.tsx

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { forwardRef, ReactNode } from "react";
+import { useIntl } from "react-intl";
 import {
   Button as RACButton,
   ButtonProps as RACButtonProps,
@@ -12,6 +13,33 @@ import { css, cx } from "styled-system/css";
 import { button, ButtonVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 import { buttonIcon } from "./button-icon";
+import { uiMessage } from "./messages";
+import { Spinner } from "./Spinner";
+
+// Chakra's ButtonSpinner: a 1em spinner centred over the hidden label. Out of
+// flow, so the label alone sets the button's size; the recipe's base
+// `position: relative` is what it anchors to. Its own component so useIntl runs
+// only while a button is actually loading — a bare Button must keep working
+// without an IntlProvider (test renders commonly lack one).
+const ButtonSpinner = () => {
+  const intl = useIntl();
+  return (
+    <span
+      className={css({
+        position: "absolute",
+        inset: 0,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+      })}
+    >
+      <Spinner
+        aria-label={intl.formatMessage(uiMessage("ui.loading"))}
+        css={{ width: "1em", height: "1em" }}
+      />
+    </span>
+  );
+};
 
 export interface ButtonProps
   extends Omit<RACButtonProps, "className" | "children">,
@@ -23,6 +51,14 @@ export interface ButtonProps
   leftIcon?: ReactNode;
   /** Icon rendered after the label, matching Chakra's `rightIcon`. */
   rightIcon?: ReactNode;
+  /**
+   * Show a spinner in place of the label and disable interaction, matching
+   * Chakra's `isLoading`: the label stays in the layout but invisible, so the
+   * button keeps its size, and the dimmed disabled look applies. Chakra's
+   * `loadingText`/`spinnerPlacement` (a visible label beside the spinner) are
+   * unported — no app in the family used them.
+   */
+  isLoading?: boolean;
   children?: ReactNode;
 }
 
@@ -41,11 +77,23 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
       className,
       leftIcon,
       rightIcon,
+      isLoading,
       children,
       ...rest
     },
     ref,
   ) {
+    const label = (
+      <>
+        {leftIcon ? (
+          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
+        ) : null}
+        {children}
+        {rightIcon ? (
+          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
+        ) : null}
+      </>
+    );
     return (
       <RACButton
         ref={ref}
@@ -54,15 +102,21 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
           cssProp ? css(cssProp) : undefined,
           className,
         )}
+        data-loading={isLoading ? "" : undefined}
         {...rest}
+        isDisabled={isLoading || rest.isDisabled}
       >
-        {leftIcon ? (
-          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
-        ) : null}
-        {children}
-        {rightIcon ? (
-          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
-        ) : null}
+        {isLoading ? (
+          <>
+            <ButtonSpinner />
+            {/* Hidden with opacity, not removed: it keeps the button the size
+                it is when idle, so a row of buttons doesn't reflow. Still in
+                the accessibility tree, so the button keeps its name. */}
+            <span className={css({ opacity: 0 })}>{label}</span>
+          </>
+        ) : (
+          label
+        )}
       </RACButton>
     );
   },

package/src/CheckboxGroup.tsx

@@ -0,0 +1,76 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  CheckboxGroup as RACCheckboxGroup,
+  CheckboxGroupProps as RACCheckboxGroupProps,
+  Label as RACLabel,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { field } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldRequiredIndicator,
+  FieldSupport,
+  FieldSupportProps,
+} from "./FieldSupport";
+
+export interface CheckboxGroupProps
+  extends Omit<RACCheckboxGroupProps, "className" | "style">,
+    FieldSupportProps {
+  /**
+   * Visible label for the group (Chakra's FormLabel above it). Use
+   * `aria-label` instead where the design has none.
+   */
+  label?: ReactNode;
+  /** Per-instance style overrides. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * CheckboxGroup — react-aria-components <CheckboxGroup> for a set of
+ * Checkboxes sharing one value array (each Checkbox's `value` marks its
+ * entry). Beyond the optional field chrome (label/helperText/errorMessage —
+ * Chakra's FormControl parts) it carries no styling of its own: compose with
+ * Stack for layout, as RadioGroup does. Chakra's CheckboxGroup was a bare
+ * context provider, so ported call sites gain the chrome rather than
+ * restating it around the group.
+ */
+export const CheckboxGroup = ({
+  label,
+  helperText,
+  errorMessage,
+  helperTextCss,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: CheckboxGroupProps) => {
+  return (
+    <RACCheckboxGroup
+      className={cx(cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    >
+      {(renderProps) => (
+        <>
+          {label != null && (
+            <RACLabel className={field().label}>
+              {label}
+              {rest.isRequired ? <FieldRequiredIndicator /> : null}
+            </RACLabel>
+          )}
+          {typeof children === "function" ? children(renderProps) : children}
+          <FieldSupport
+            helperText={helperText}
+            errorMessage={errorMessage}
+            helperTextCss={helperTextCss}
+          />
+        </>
+      )}
+    </RACCheckboxGroup>
+  );
+};

package/src/ComboBox.tsx

@@ -25,12 +25,18 @@ import { RiArrowDownSLine } from "react-icons/ri";
 import { css, cx } from "styled-system/css";
 import { select, SelectVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldRequiredIndicator,
+  FieldSupport,
+  FieldSupportProps,
+} from "./FieldSupport";
 import { Icon } from "./Icon";
 import { SelectSlotProvider } from "./Select";
 
 export interface ComboBoxProps<T extends object>
   extends Omit<RACComboBoxProps<T>, "className" | "children" | "style">,
-    SelectVariantProps {
+    SelectVariantProps,
+    FieldSupportProps {
   /** Visible label. Use `aria-label` instead where the design has none. */
   label?: ReactNode;
   placeholder?: string;
@@ -41,8 +47,15 @@ export interface ComboBoxProps<T extends object>
    * that (react-select did it with a custom `SingleValue`).
    */
   startContent?: ReactNode;
-  /** `SelectOption`s. */
-  children: ReactNode;
+  /**
+   * `SelectOption`s, or a render function over the `items` prop for a
+   * dynamic collection — which is how an async lookup works: drive `items`
+   * from loaded results (e.g. react-stately's useAsyncList) and filter
+   * server-side; react-aria skips its own text filtering when `items` is
+   * controlled. Pair with `emptyState` (swap its content while loading) and
+   * `isPopoverHidden` for a minimum query length.
+   */
+  children: ReactNode | ((item: T) => ReactNode);
   /**
    * Replaces the chevron; pass `null` for none, which is what a plain
    * autocomplete wants (react-select's `dropdownIndicator: display none`).
@@ -98,6 +111,9 @@ const ComboBoxInner = <T extends object>(
     isPopoverHidden,
     placement = "bottom start",
     maxHeight,
+    helperText,
+    errorMessage,
+    helperTextCss,
     css: cssProp,
     contentCss,
     className,
@@ -138,7 +154,12 @@ const ComboBoxInner = <T extends object>(
         {...(rest as RACComboBoxProps<T>)}
         className={cx(slots.root, className)}
       >
-        {label != null && <RACLabel className={slots.label}>{label}</RACLabel>}
+        {label != null && (
+          <RACLabel className={slots.label}>
+            {label}
+            {props.isRequired ? <FieldRequiredIndicator /> : null}
+          </RACLabel>
+        )}
         <div
           ref={triggerRef}
           className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
@@ -178,6 +199,11 @@ const ComboBoxInner = <T extends object>(
             </RACListBox>
           </Popover>
         )}
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+        />
       </RACComboBox>
     </SelectSlotProvider>
   );

package/src/Fade.tsx

@@ -3,13 +3,20 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode } from "react";
+import { CSSProperties, ReactNode } from "react";
 import { css, cx } from "styled-system/css";
 import { SystemStyleObject } from "styled-system/types";
 
 export interface FadeProps {
   /** Visible when true; faded out (but mounted) when false. */
   isOpen: boolean;
+  /**
+   * Fade-in time in seconds (Chakra's `transition.enter.duration`).
+   * Default 0.2, Chakra's.
+   */
+  enterDuration?: number;
+  /** Fade-out time in seconds (Chakra's `transition.exit.duration`). */
+  exitDuration?: number;
   css?: SystemStyleObject;
   className?: string;
   children: ReactNode;
@@ -21,12 +28,23 @@ export interface FadeProps {
  */
 export const Fade = ({
   isOpen,
+  enterDuration = 0.2,
+  exitDuration = 0.2,
   css: cssProp,
   className,
   children,
 }: FadeProps) => (
   <div
     data-open={isOpen ? "" : undefined}
+    // Runtime values, so an inline custom property rather than the css()
+    // object (gotcha #9: a non-literal duration would extract to nothing).
+    // The var switches in the same commit as the opacity, so the transition
+    // picks up the direction's own duration.
+    style={
+      {
+        "--fade-duration": `${isOpen ? enterDuration : exitDuration}s`,
+      } as CSSProperties
+    }
     className={cx(
       css(
         {
@@ -34,7 +52,7 @@ export const Fade = ({
           pointerEvents: "none",
           "&[data-open]": { opacity: 1, pointerEvents: "auto" },
           transitionProperty: "opacity",
-          transitionDuration: "0.2s",
+          transitionDuration: "var(--fade-duration)",
           transitionTimingFunction: "ease-out",
           _motionReduce: { transition: "none" },
         },

package/src/FieldSupport.tsx

@@ -0,0 +1,68 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import { FieldError, Text as RACText } from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { field } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+/**
+ * The label/helper/error chrome every labelled form field shares — Chakra's
+ * FormControl parts, generalised out of TextField so Select, ComboBox,
+ * NumberField, RadioGroup and CheckboxGroup carry the same props
+ * (data-microbit-org's forms attach helper and error text to all of these).
+ */
+export interface FieldSupportProps {
+  /** Help text below the field (Chakra's FormHelperText). */
+  helperText?: ReactNode;
+  /** Shown below the field when invalid (Chakra's FormErrorMessage). */
+  errorMessage?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
+}
+
+/**
+ * Helper text and error message for a react-aria field container. Render
+ * inside any RAC component with field validation context (TextField, Select,
+ * ComboBox, NumberField, RadioGroup, CheckboxGroup) — react-aria wires the
+ * description to the input's aria-describedby, and the error renders only
+ * while the field is invalid. Also exported for app-side composites built on
+ * RAC containers.
+ */
+export const FieldSupport = ({
+  helperText,
+  errorMessage,
+  helperTextCss,
+}: FieldSupportProps) => {
+  const slots = field();
+  return (
+    <>
+      {helperText != null && (
+        <RACText
+          slot="description"
+          className={cx(
+            slots.helperText,
+            helperTextCss ? css(helperTextCss) : undefined,
+          )}
+        >
+          {helperText}
+        </RACText>
+      )}
+      <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+    </>
+  );
+};
+
+/**
+ * The required-field asterisk (Chakra's FormLabel indicator). Render inside
+ * the field's label when `isRequired`; aria-hidden because react-aria already
+ * announces requiredness from the input itself.
+ */
+export const FieldRequiredIndicator = () => (
+  <span aria-hidden className={field().requiredIndicator}>
+    *
+  </span>
+);

package/src/Heading.recipe.ts

@@ -44,6 +44,25 @@ export const heading = defineRecipe({
     // GT Walsheim in the private preset.
     variant: {
       marketing: { fontFamily: "display" },
+      // Page-title chrome in the accent colour (`headingAccent` — see
+      // base-preset.ts). Converged from classroom and data-microbit-org,
+      // which carried these two byte-identically app-side.
+      //
+      // `fontSize` goes through a doubled selector because `size` sets it too,
+      // responsively. Source order can't settle that: Panda hoists media
+      // queries below the base rules (gotcha #31) and emits variant rules in
+      // the order it meets them, so which of the two wins would depend on the
+      // breakpoint and on what other call sites exist. Two classes beat one at
+      // every width instead.
+      label: {
+        "&&": { fontSize: "4xl" },
+        color: "headingAccent",
+      },
+      subtitle: {
+        "&&": { fontSize: "xl" },
+        fontWeight: "normal",
+        color: "headingAccent",
+      },
     },
   },
   defaultVariants: {

package/src/Input.recipe.ts

@@ -17,8 +17,17 @@ const transitionCommon =
  *
  * 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). Focus is declared after invalid so a focused
- * invalid field shows the focus ring, as in Chakra.
+ * (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.
  *
  * Registered in the base preset (base-preset.ts), which also has the
  * `staticCss` entry that keeps the runtime-prop size variants generated.
@@ -39,11 +48,11 @@ export const input = defineRecipe({
     bg: "inherit",
     color: "inherit",
     _hover: { borderColor: "gray.300" },
-    "&[data-invalid], &:user-invalid": {
+    "&&:is([data-invalid], :user-invalid)": {
       borderColor: "danger.500",
       boxShadow: "0 0 0 1px token(colors.danger.500)",
     },
-    "&:is(:focus-visible, [data-focused])": {
+    "&&&:is(:focus-visible, [data-focused])": {
       zIndex: 1,
       borderColor: "focusBorder",
       boxShadow: "0 0 0 1px token(colors.focusBorder)",

package/src/NativeSelect.tsx

@@ -47,7 +47,13 @@ export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
         className={cx(
           input({ size }),
           css(
-            { cursor: "pointer" },
+            // Chakra's Select field carried a 1px bottom padding its Input
+            // didn't (its option text sits a hair higher than input text).
+            {
+              cursor: "pointer",
+              paddingBottom: "1px",
+              _disabled: { cursor: "not-allowed" },
+            },
             // Room for the chevron overlay (Chakra Select's icon spacing,
             // constant across sizes).
             hideChevron ? undefined : { paddingRight: "8" },
@@ -84,6 +90,9 @@ export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
             height: "5",
             pointerEvents: "none",
             fill: "currentColor",
+            // The chevron sits outside the select so it doesn't inherit its
+            // disabled dimming; Chakra's Select icon dimmed to 0.5.
+            "select:disabled + &": { opacity: 0.5 },
           })}
         >
           <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" />

package/src/NumberField.tsx

@@ -16,10 +16,16 @@ import { RiArrowDownSFill, RiArrowUpSFill } from "react-icons/ri";
 import { css, cx } from "styled-system/css";
 import { field, input, numberField } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldRequiredIndicator,
+  FieldSupport,
+  FieldSupportProps,
+} from "./FieldSupport";
 import { Icon } from "./Icon";
 
 export interface NumberFieldProps
-  extends Omit<RACNumberFieldProps, "className" | "children" | "style"> {
+  extends Omit<RACNumberFieldProps, "className" | "children" | "style">,
+    FieldSupportProps {
   /** Visible label (optional; otherwise pass `aria-label`). */
   label?: ReactNode;
   /** Root style overrides (e.g. row layout for label-beside-field forms). */
@@ -40,7 +46,17 @@ export interface NumberFieldProps
  */
 export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
   function NumberField(
-    { label, css: cssProp, labelCss, groupCss, inputCss, ...rest },
+    {
+      label,
+      helperText,
+      errorMessage,
+      helperTextCss,
+      css: cssProp,
+      labelCss,
+      groupCss,
+      inputCss,
+      ...rest
+    },
     ref,
   ) {
     const slots = numberField();
@@ -58,6 +74,7 @@ export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
             )}
           >
             {label}
+            {rest.isRequired ? <FieldRequiredIndicator /> : null}
           </RACLabel>
         )}
         <RACGroup
@@ -80,6 +97,11 @@ export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
             </RACButton>
           </div>
         </RACGroup>
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+        />
       </RACNumberField>
     );
   },

package/src/Radio.tsx

@@ -5,37 +5,72 @@
  */
 import { ReactNode } from "react";
 import {
+  Label as RACLabel,
   Radio as RACRadio,
   RadioProps as RACRadioProps,
   RadioGroup as RACRadioGroup,
   RadioGroupProps as RACRadioGroupProps,
 } from "react-aria-components";
 import { css, cx } from "styled-system/css";
-import { radio, RadioVariantProps } from "styled-system/recipes";
+import { field, radio, RadioVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldRequiredIndicator,
+  FieldSupport,
+  FieldSupportProps,
+} from "./FieldSupport";
 
 export interface RadioGroupProps
-  extends Omit<RACRadioGroupProps, "className" | "style"> {
+  extends Omit<RACRadioGroupProps, "className" | "style">,
+    FieldSupportProps {
+  /**
+   * Visible label for the group (Chakra's FormLabel above it). Use
+   * `aria-label` instead where the design has none.
+   */
+  label?: ReactNode;
   /** Per-instance style overrides, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
 }
 
 /**
- * RadioGroup — react-aria-components <RadioGroup> for a set of Radios. Carries
- * no styling of its own: compose with Stack for layout, as Chakra call sites
- * did.
+ * RadioGroup — react-aria-components <RadioGroup> for a set of Radios. Beyond
+ * the optional field chrome (label/helperText/errorMessage — Chakra's
+ * FormControl parts) it carries no styling of its own: compose with Stack for
+ * layout, as Chakra call sites did.
  */
 export const RadioGroup = ({
+  label,
+  helperText,
+  errorMessage,
+  helperTextCss,
   css: cssProp,
   className,
+  children,
   ...rest
 }: RadioGroupProps) => {
   return (
     <RACRadioGroup
       className={cx(cssProp ? css(cssProp) : undefined, className)}
       {...rest}
-    />
+    >
+      {(renderProps) => (
+        <>
+          {label != null && (
+            <RACLabel className={field().label}>
+              {label}
+              {rest.isRequired ? <FieldRequiredIndicator /> : null}
+            </RACLabel>
+          )}
+          {typeof children === "function" ? children(renderProps) : children}
+          <FieldSupport
+            helperText={helperText}
+            errorMessage={errorMessage}
+            helperTextCss={helperTextCss}
+          />
+        </>
+      )}
+    </RACRadioGroup>
   );
 };
 

package/src/Select.recipe.ts

@@ -82,9 +82,12 @@ export const select = defineSlotRecipe({
       // `> &` rather than a descendant selector, so an app's own invalid form
       // wrapper cannot paint every control inside it red.
       //
-      // Declared after hover and before focus so red beats a hover tint and
-      // the focus ring beats red, as in the input recipe.
-      "[data-invalid] > &": {
+      // 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] > &&": {
         borderColor: "danger.500",
         boxShadow: "0 0 0 1px token(colors.danger.500)",
       },
@@ -98,7 +101,7 @@ export const select = defineSlotRecipe({
       // 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)": {
+      "&&&[data-focus-visible], &&&:has(input:focus)": {
         boxShadow: "0 0 0 1px token(colors.focusBorder)",
         borderColor: "focusBorder",
         outline: "2px solid transparent",

package/src/Select.tsx

@@ -20,6 +20,11 @@ import { RiArrowDownSLine } from "react-icons/ri";
 import { css, cx } from "styled-system/css";
 import { select, SelectVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldRequiredIndicator,
+  FieldSupport,
+  FieldSupportProps,
+} from "./FieldSupport";
 import { Icon } from "./Icon";
 
 export type SelectSlots = ReturnType<typeof select>;
@@ -37,7 +42,8 @@ export interface SelectProps<T extends object>
       RACSelectProps<T>,
       "className" | "children" | "style" | "placeholder"
     >,
-    SelectVariantProps {
+    SelectVariantProps,
+    FieldSupportProps {
   /** Visible label. Use `aria-label` instead where the design has none. */
   label?: ReactNode;
   /** Shown in the trigger while nothing is chosen (Chakra's placeholder). */
@@ -78,6 +84,9 @@ export const Select = <T extends object>({
   indicator,
   placement = "bottom start",
   maxHeight,
+  helperText,
+  errorMessage,
+  helperTextCss,
   css: cssProp,
   contentCss,
   className,
@@ -93,7 +102,12 @@ export const Select = <T extends object>({
         {...(rest as RACSelectProps<T>)}
         className={cx(slots.root, className)}
       >
-        {label != null && <RACLabel className={slots.label}>{label}</RACLabel>}
+        {label != null && (
+          <RACLabel className={slots.label}>
+            {label}
+            {props.isRequired ? <FieldRequiredIndicator /> : null}
+          </RACLabel>
+        )}
         <RACButton
           className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
         >
@@ -118,6 +132,11 @@ export const Select = <T extends object>({
         >
           <RACListBox className={slots.list}>{children}</RACListBox>
         </Popover>
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+        />
       </RACSelect>
     </SelectSlotProvider>
   );

package/src/SharedUIProvider.tsx

@@ -4,6 +4,9 @@
  * SPDX-License-Identifier: MIT
  */
 import { createContext, ReactNode, useContext, useMemo } from "react";
+import { I18nProvider } from "react-aria-components";
+import { IntlContext } from "react-intl";
+import { racLocale } from "./rac-locale";
 
 /**
  * Registers the close function of the currently open dismissable overlay, or
@@ -21,27 +24,44 @@ const SharedUIContext = createContext<SharedUIContextValue | null>(null);
 
 export interface SharedUIProviderProps {
   overlayCloseRegistrar?: OverlayCloseRegistrar;
+  /**
+   * Locale for react-aria's own built-in strings. Defaults to the surrounding
+   * IntlProvider's locale, which is what apps want: pass this only where the
+   * two must differ.
+   */
+  locale?: string;
   children: ReactNode;
 }
 
 /**
- * SharedUIProvider — the app-side installation point for optional shared-ui
- * integrations. Currently that is only the overlay-close registrar, so apps
- * without one can omit the provider entirely. Localized strings come from
- * react-intl: an IntlProvider must be mounted above shared-ui components
- * (see the package README for merging this package's message catalogs).
+ * SharedUIProvider — the app-side installation point for shared-ui
+ * integrations: the optional overlay-close registrar, and the locale for
+ * react-aria's built-in strings.
+ *
+ * This package's own strings come from react-intl, so an IntlProvider must be
+ * mounted above shared-ui components (see the package README). react-aria
+ * translates its built-in strings itself, from its own bundled catalogs, and
+ * without this provider it picks the locale from the browser rather than from
+ * the app's language setting — mount it inside the IntlProvider so the two
+ * agree.
  */
 export const SharedUIProvider = ({
   overlayCloseRegistrar,
+  locale,
   children,
 }: SharedUIProviderProps) => {
+  // Read the context rather than calling useIntl(), which throws when there is
+  // no IntlProvider: react-aria falls back to the browser locale, as before.
+  const intlLocale = useContext(IntlContext)?.locale;
   const value = useMemo(
     () => ({ overlayCloseRegistrar }),
     [overlayCloseRegistrar],
   );
   return (
     <SharedUIContext.Provider value={value}>
-      {children}
+      <I18nProvider locale={racLocale(locale ?? intlLocale)}>
+        {children}
+      </I18nProvider>
     </SharedUIContext.Provider>
   );
 };

package/src/TextField.recipe.ts

@@ -37,6 +37,10 @@ export const field = defineSlotRecipe({
       color: "danger.500",
     },
     helperText: {
+      // RAC's Text renders a span, and RadioGroup/CheckboxGroup roots are not
+      // flex containers to blockify it, where an inline box would drop the
+      // margin below (gotcha #44).
+      display: "block",
       mt: "2",
       fontSize: "sm",
       lineHeight: "normal",

package/src/TextField.tsx

@@ -5,31 +5,27 @@
  */
 import { FocusEvent, forwardRef, ReactNode } from "react";
 import {
-  FieldError,
   Input as RACInput,
   Label as RACLabel,
-  Text as RACText,
   TextField as RACTextField,
   TextFieldProps as RACTextFieldProps,
 } from "react-aria-components";
-import { css, cx } from "styled-system/css";
 import { field, input, InputVariantProps } from "styled-system/recipes";
-import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldRequiredIndicator,
+  FieldSupport,
+  FieldSupportProps,
+} from "./FieldSupport";
 
 export interface TextFieldProps
   extends Omit<
       RACTextFieldProps,
       "className" | "children" | "style" | "onFocus" | "onBlur"
     >,
-    InputVariantProps {
+    InputVariantProps,
+    FieldSupportProps {
   /** Visible label (Chakra's FormLabel; asterisk added when `isRequired`). */
   label: ReactNode;
-  /** Help text below the input (Chakra's FormHelperText). */
-  helperText?: ReactNode;
-  /** Shown below the input when `isInvalid` (Chakra's FormErrorMessage). */
-  errorMessage?: ReactNode;
-  /** Per-instance style overrides for the helper text. */
-  helperTextCss?: SystemStyleObject;
   onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
   /** Input autocapitalize attribute (react-aria's TextField omits it). */
   autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters";
@@ -61,11 +57,7 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
       <RACTextField {...rest} className={slots.root}>
         <RACLabel className={slots.label}>
           {label}
-          {rest.isRequired ? (
-            <span aria-hidden className={slots.requiredIndicator}>
-              *
-            </span>
-          ) : null}
+          {rest.isRequired ? <FieldRequiredIndicator /> : null}
         </RACLabel>
         <RACInput
           ref={ref}
@@ -73,18 +65,11 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
           onFocus={onFocus}
           autoCapitalize={autoCapitalize}
         />
-        {helperText && (
-          <RACText
-            slot="description"
-            className={cx(
-              slots.helperText,
-              helperTextCss ? css(helperTextCss) : undefined,
-            )}
-          >
-            {helperText}
-          </RACText>
-        )}
-        <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+        />
       </RACTextField>
     );
   },

package/src/base-preset.ts

@@ -24,6 +24,7 @@ import {
 // 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";
@@ -175,6 +176,12 @@ export const basePreset = definePreset({
         // follows; OSS language buttons are brand blue.)
         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
@@ -216,6 +223,7 @@ export const basePreset = definePreset({
     },
     slotRecipes: {
       avatar,
+      breadcrumb,
       card,
       checkbox,
       dialog,

package/src/index.ts

@@ -10,11 +10,14 @@
  */
 export * from "./system";
 export * from "./Avatar";
+export * from "./Breadcrumb";
 export * from "./Button";
 export * from "./LinkButton";
 export * from "./ButtonGroup";
 export * from "./Card";
 export * from "./Checkbox";
+export * from "./CheckboxGroup";
+export * from "./FieldSupport";
 export * from "./IconButton";
 export * from "./Image";
 export * from "./Input";

package/src/rac-locale.ts

@@ -0,0 +1,33 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Sanitizes one of our locale ids for react-aria's I18nProvider.
+ *
+ * No mapping is needed to reach react-aria's own strings: its fallback chain
+ * runs exact tag, then the bare language, then any variant of that language,
+ * then en-US — so `fr` finds fr-FR, `ja` finds ja-JP, and the locales it has no
+ * strings for at all (ca, cy, ga-IE, and our `lol` pseudo-locale) land on
+ * English.
+ *
+ * What does need handling is a malformed tag: I18nProvider's explicit-locale
+ * path feeds it straight to `new Intl.Locale` with no guard of its own (unlike
+ * its browser-locale path), so a bad tag throws during render and takes out the
+ * tree. Only reachable through SharedUIProvider's `locale` prop in practice —
+ * react-intl rejects a malformed locale before we could read it from context.
+ */
+export const racLocale = (locale: string | undefined): string | undefined => {
+  if (locale === undefined) {
+    // Leave react-aria on its browser-locale default.
+    return undefined;
+  }
+  try {
+    Intl.DateTimeFormat.supportedLocalesOf([locale]);
+  } catch {
+    return "en-GB";
+  }
+  return locale;
+};