@microbit/ui 0.1.0-alpha.10

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@microbit/ui",
+  "version": "0.1.0-alpha.10",
+  "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",
+  "exports": {
+    ".": "./src/index.ts",
+    "./base-preset": "./src/base-preset.ts",
+    "./base-tokens": "./src/base-tokens.ts",
+    "./messages": "./src/messages.ts",
+    "./postcss-legacy-safari": "./postcss-legacy-safari.cjs",
+    "./reset.css": "./reset.css",
+    "./lang/*": "./lang/*"
+  },
+  "files": [
+    "src",
+    "lang",
+    "postcss-legacy-safari.cjs",
+    "reset.css",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "panda": "panda codegen",
+    "typecheck": "npm run panda && tsc --noEmit",
+    "prestorybook": "npm run panda",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "prebuild-storybook": "npm run panda",
+    "build-storybook": "storybook build"
+  },
+  "peerDependencies": {
+    "@pandacss/dev": "^1.11.4",
+    "react": "^18.3.1",
+    "react-aria-components": "^1.19.0",
+    "react-icons": "^4.12.0 || ^5.0.0",
+    "react-intl": "^6.6.8 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@pandacss/dev": "^1.11.4",
+    "@storybook/react-vite": "^10.5.2",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.5.2",
+    "react": "^18.3.1",
+    "react-aria-components": "^1.19.0",
+    "react-dom": "^18.3.1",
+    "react-icons": "^4.12.0",
+    "react-intl": "^6.6.8",
+    "storybook": "^10.5.2",
+    "typescript": "^5.4.2",
+    "vite": "^6.3.5"
+  },
+  "publishConfig": {
+    "tag": "alpha"
+  }
+}

package/postcss-legacy-safari.cjs

@@ -0,0 +1,96 @@
+/*
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * TEMPORARY compatibility shim for consuming apps that still support Safari
+ * below 15. Delete this file (and the app-side wiring — see the README) once
+ * every consuming app has raised its support floor past the affected browsers.
+ *
+ * The bug: Safari 14.x silently drops logical *shorthands* whose value
+ * contains var() — `padding-inline: var(--spacing-2)` applies nothing, even
+ * though `padding-inline: 10px` (literal) and `padding-inline-start:
+ * var(--spacing-2)` (longhand) both work. Panda emits these shorthands for its
+ * px/py/mx/my utilities, so the bug removes most token-based spacing.
+ *
+ * The fix: rewrite the inline/block logical shorthands into their -start/-end
+ * longhands. Kept logical (not physical left/right) so RTL still flips.
+ *
+ * This is one of TWO legacy concerns for the same era of browsers; the other
+ * is @layer, which those browsers drop wholesale. Apps also run
+ * @csstools/postcss-cascade-layers (de-layering) and pin build.cssTarget — see
+ * the "Legacy browser support" section of the README. All of it is expected to
+ * be removed together when the floor rises.
+ *
+ * Exposed as a PostCSS plugin factory:
+ *   const { expandLogicalShorthands } = require("@microbit/ui/postcss-legacy-safari");
+ *   module.exports = { plugins: [expandLogicalShorthands(), ...] };
+ */
+
+// Logical shorthands whose value is `<start> <end>` (one value applies to
+// both). NOT included: border-inline / border-block — those are compound
+// (`width style color`) and duplicate the whole value to each side rather than
+// splitting, so they would need different handling. Add them explicitly if a
+// consuming app ever emits them.
+const LOGICAL_SHORTHANDS = {
+  "padding-inline": ["padding-inline-start", "padding-inline-end"],
+  "padding-block": ["padding-block-start", "padding-block-end"],
+  "margin-inline": ["margin-inline-start", "margin-inline-end"],
+  "margin-block": ["margin-block-start", "margin-block-end"],
+  "inset-inline": ["inset-inline-start", "inset-inline-end"],
+  "inset-block": ["inset-block-start", "inset-block-end"],
+  "scroll-margin-inline": [
+    "scroll-margin-inline-start",
+    "scroll-margin-inline-end",
+  ],
+  "scroll-margin-block": [
+    "scroll-margin-block-start",
+    "scroll-margin-block-end",
+  ],
+  "scroll-padding-inline": [
+    "scroll-padding-inline-start",
+    "scroll-padding-inline-end",
+  ],
+  "scroll-padding-block": [
+    "scroll-padding-block-start",
+    "scroll-padding-block-end",
+  ],
+};
+
+// Split a value on top-level whitespace, ignoring spaces inside parens so
+// var() fallbacks stay intact. One value applies to both sides; two map to
+// start then end (per the CSS shorthand rules).
+const splitTopLevel = (value) => {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of value) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current.trim()) parts.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+};
+
+const expandLogicalShorthands = () => ({
+  postcssPlugin: "microbit-ui-expand-logical-shorthands",
+  Declaration(decl) {
+    const longhands = LOGICAL_SHORTHANDS[decl.prop.toLowerCase()];
+    if (!longhands) return;
+    const parts = splitTopLevel(decl.value);
+    if (parts.length === 0) return;
+    const [start, end = start] = parts;
+    decl.cloneBefore({ prop: longhands[0], value: start });
+    decl.cloneBefore({ prop: longhands[1], value: end });
+    decl.remove();
+  },
+});
+expandLogicalShorthands.postcss = true;
+
+module.exports = { expandLogicalShorthands };

package/reset.css

@@ -0,0 +1,35 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Chakra-reset parity that must live in the `reset` cascade layer: import
+ * from the app's layers.css with
+ *
+ *   @import "@microbit/ui/reset.css" layer(reset);
+ *
+ * Deliberately not in the preset's globalCss: globalCss emits into the
+ * `base` layer, and the legacy-Safari cascade-layer flattening
+ * specificity-boosts base+ rules above CSS it can't see (runtime-injected
+ * styles such as CodeMirror themes, and other per-file-processed app CSS).
+ * A reset must stay at the bottom of the cascade in production exactly as
+ * it is in dev — see playbook gotcha #28.
+ */
+*,
+*::before,
+*::after {
+  border-color: var(--colors-gray-200);
+  word-wrap: break-word;
+}
+
+/*
+ * Panda's preflight (base layer) beats the rule above with
+ * `border-color: var(--global-color-border, currentcolor)`. The currentcolor
+ * fallback poisons `border-color: inherit` chains (inherit copies the
+ * currentcolor KEYWORD, which then resolves against the child's own `color`
+ * — e.g. white on the checkbox/radio control). Defining the hook keeps the
+ * default border colour a real colour, as Chakra's global reset did.
+ */
+:root {
+  --global-color-border: var(--colors-gray-200);
+}

package/src/Button.recipe.ts

@@ -0,0 +1,162 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+// Chakra's transition.property.common, inlined (Panda has no transitionProperty
+// token category). Matches Chakra's Button base transition.
+const transitionCommon =
+  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+
+/**
+ * Button recipe — Chakra's default Button base + sizes, with this app's
+ * borderRadius (`button` = 2rem) and variant set ported from
+ * `components/button.ts`. Interaction conditions (`_hover`/`_active`/
+ * `_disabled`/`_focusVisible`) are widened in the preset to also match
+ * react-aria-components' data attributes, so these Chakra-shaped variant
+ * objects work unchanged on RAC's <Button>.
+ *
+ * A config recipe (not a component cva): styles land in the `recipes` layer so
+ * call sites can override with plain style props, and presets extend the
+ * variants. This file holds the brand-independent variant set — the core
+ * Chakra variants plus the family-wide `language`/`toolbar` variants; a
+ * consuming app's preset extends it with app vocabulary (e.g. ml-trainer's
+ * `led`/`record*`/`secondary-disabled`). Brand divergence within a variant is
+ * token-driven (see the `languageText` semantic tokens).
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const button = defineRecipe({
+  className: "btn",
+  jsx: ["Button", "IconButton"],
+  base: {
+    lineHeight: "1.2",
+    borderRadius: "button",
+    fontWeight: "semibold",
+    transitionProperty: transitionCommon,
+    transitionDuration: "normal",
+    display: "inline-flex",
+    appearance: "none",
+    alignItems: "center",
+    justifyContent: "center",
+    userSelect: "none",
+    position: "relative",
+    whiteSpace: "nowrap",
+    verticalAlign: "middle",
+    outline: "none",
+    _focusVisible: {
+      focusShadow: "outline",
+    },
+    _disabled: {
+      opacity: 0.4,
+      cursor: "not-allowed",
+      boxShadow: "none",
+    },
+    _hover: {
+      _disabled: {
+        bg: "initial",
+      },
+    },
+  },
+  variants: {
+    size: {
+      lg: { h: "12", minW: "12", fontSize: "lg", px: "6" },
+      md: { h: "10", minW: "10", fontSize: "md", px: "4" },
+      sm: { h: "8", minW: "8", fontSize: "sm", px: "3" },
+      xs: { h: "6", minW: "6", fontSize: "xs", px: "2" },
+    },
+    variant: {
+      // Chakra's unstyled reset + this app's border-radius removal.
+      unstyled: {
+        bg: "none",
+        color: "inherit",
+        display: "inline",
+        lineHeight: "inherit",
+        m: "0",
+        p: "0",
+        borderRadius: "unset",
+      },
+      // Chakra's link layout (no padding/height) + this app's colours.
+      link: {
+        padding: 0,
+        height: "auto",
+        lineHeight: "normal",
+        verticalAlign: "baseline",
+        borderWidth: "0",
+        color: "brand.600",
+        fontWeight: "normal",
+        bg: "transparent",
+        _hover: {
+          textDecoration: "underline",
+        },
+      },
+      secondary: {
+        borderWidth: "2px",
+        borderColor: "brand.500",
+        color: "brand.700",
+        bg: "transparent",
+        _hover: { borderColor: "brand.600" },
+        _active: { bg: "brand.50", borderColor: "brand.700" },
+      },
+      ghost: {
+        color: "black",
+        bg: "transparent",
+        _hover: { bg: "blackAlpha.50" },
+        _active: { bg: "blackAlpha.100" },
+      },
+      // Chakra had no `plain` variant, so `variant="plain"` fell through to
+      // base-only styling: a transparent, colour-inheriting button. Used for the
+      // action-bar icon-button menu triggers (settings/help), which supply their
+      // own colour and shape via instance styles.
+      plain: {
+        bg: "transparent",
+        color: "inherit",
+      },
+      primary: {
+        color: "white",
+        bg: "brand.500",
+        _hover: { bg: "brand.600", _disabled: { bg: "brand.500" } },
+        _active: { bg: "brand.700" },
+      },
+      warning: {
+        borderWidth: "2px",
+        borderColor: "danger.500",
+        color: "danger.500",
+        bg: "transparent",
+        _hover: { borderColor: "danger.600" },
+        _active: { bg: "danger.50", borderColor: "danger.500" },
+      },
+      // Chakra's built-in solid + red colorScheme (destructive confirm
+      // buttons). Same values as `record` today, but a separate variant so
+      // recording UI and destructive actions can diverge - hence danger
+      // tokens here, red.* literals there.
+      warningSolid: {
+        color: "white",
+        bg: "danger.500",
+        _hover: { bg: "danger.600", _disabled: { bg: "danger.500" } },
+        _active: { bg: "danger.700" },
+      },
+      // Family-wide variants (every censused app has language- and
+      // toolbar-class buttons).
+      toolbar: {
+        color: "black",
+        bg: "white",
+        _hover: { bg: "whiteAlpha.900", _disabled: { bg: "white" } },
+        _active: { bg: "whiteAlpha.800" },
+        _focusVisible: { focusShadow: "outlineDark" },
+      },
+      language: {
+        borderWidth: "2px",
+        borderColor: "gray.200",
+        color: "languageText",
+        _hover: { color: "languageTextHover", bg: "gray.100" },
+      },
+    },
+  },
+  defaultVariants: {
+    variant: "secondary",
+    size: "md",
+  },
+});

package/src/Button.tsx

@@ -0,0 +1,69 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, ReactNode } from "react";
+import {
+  Button as RACButton,
+  ButtonProps as RACButtonProps,
+} from "react-aria-components";
+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";
+
+export interface ButtonProps
+  extends Omit<RACButtonProps, "className" | "children">,
+    ButtonVariantProps {
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+  /** Icon rendered before the label, matching Chakra's `leftIcon`. */
+  leftIcon?: ReactNode;
+  /** Icon rendered after the label, matching Chakra's `rightIcon`. */
+  rightIcon?: ReactNode;
+  children?: ReactNode;
+}
+
+/**
+ * Button — react-aria-components <Button> styled with the `button` config
+ * recipe. The recipe's interaction states are driven by RAC's data attributes
+ * (see the preset's widened conditions), so disabled/hover/press/focus all work
+ * without extra wiring.
+ */
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    {
+      variant,
+      size,
+      css: cssProp,
+      className,
+      leftIcon,
+      rightIcon,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <RACButton
+        ref={ref}
+        className={cx(
+          button({ variant, size }),
+          cssProp ? css(cssProp) : undefined,
+          className,
+        )}
+        {...rest}
+      >
+        {leftIcon ? (
+          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
+        ) : null}
+        {children}
+        {rightIcon ? (
+          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
+        ) : null}
+      </RACButton>
+    );
+  },
+);

package/src/ButtonGroup.tsx

@@ -0,0 +1,63 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, HTMLAttributes } from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Square the inner radii so adjacent buttons form one control (Chakra's
+   * `isAttached`). Otherwise buttons get a small gap.
+   */
+  isAttached?: boolean;
+  /** Per-instance style overrides. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * ButtonGroup — lays out related buttons in a row. Works with any button
+ * elements (shared-ui or native). Replaces Chakra's ButtonGroup.
+ */
+export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
+  function ButtonGroup({ isAttached, css: cssProp, className, ...rest }, ref) {
+    return (
+      <div
+        ref={ref}
+        className={cx(
+          css({
+            display: "inline-flex",
+            alignItems: "center",
+            // Buttons are position: relative, so without this an attached
+            // sibling paints over the focused button's focus-ring shadow
+            // (Chakra's Button applied zIndex 1 on focus when grouped).
+            "& > *": { _focus: { zIndex: 1 } },
+          }),
+          isAttached
+            ? css({
+                gap: 0,
+                // :first-child/:last-child, not :first-of-type: attached
+                // groups can mix element types (e.g. select + button), and
+                // -of-type matches per element type.
+                "& > *:first-child:not(:last-child)": {
+                  borderEndRadius: 0,
+                },
+                "& > *:not(:first-child):not(:last-child)": {
+                  borderRadius: 0,
+                },
+                "& > *:not(:first-child):last-child": {
+                  borderStartRadius: 0,
+                },
+              })
+            : css({ gap: 2 }),
+          cssProp ? css(cssProp) : undefined,
+          className,
+        )}
+        {...rest}
+      />
+    );
+  },
+);

package/src/Card.recipe.ts

@@ -0,0 +1,49 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Card slot recipe — Chakra's Card at its default md size (light mode), with
+ * the `elevated` (default) and `outline` variants this app uses.
+ *
+ * Registered in the base preset (base-preset.ts); `variant` is
+ * forwarded as a runtime prop so the variants are generated via `staticCss`.
+ */
+export const card = defineSlotRecipe({
+  className: "card",
+  slots: ["container", "body"],
+  base: {
+    container: {
+      display: "flex",
+      flexDirection: "column",
+      position: "relative",
+      minWidth: 0,
+      wordWrap: "break-word",
+      bg: "white",
+      borderRadius: "md",
+      color: "inherit",
+    },
+    body: {
+      padding: "5",
+      flex: "1 1 0%",
+    },
+  },
+  variants: {
+    variant: {
+      elevated: {
+        container: { boxShadow: "base" },
+      },
+      outline: {
+        container: {
+          borderWidth: "1px",
+          borderStyle: "solid",
+          borderColor: "gray.200",
+        },
+      },
+    },
+  },
+  defaultVariants: { variant: "elevated" },
+});

package/src/Card.tsx

@@ -0,0 +1,56 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, HTMLAttributes } from "react";
+import { css, cx } from "styled-system/css";
+import { card, CardVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface CardProps
+  extends HTMLAttributes<HTMLDivElement>,
+    CardVariantProps {
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+}
+
+/**
+ * Card — Chakra's <Card> equivalent (md size). Place a CardBody inside.
+ */
+export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
+  { variant, css: cssProp, className, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      className={cx(
+        card({ variant }).container,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+      {...rest}
+    />
+  );
+});
+
+export interface CardBodyProps extends HTMLAttributes<HTMLDivElement> {
+  css?: SystemStyleObject;
+}
+
+export const CardBody = forwardRef<HTMLDivElement, CardBodyProps>(
+  function CardBody({ css: cssProp, className, ...rest }, ref) {
+    return (
+      <div
+        ref={ref}
+        className={cx(
+          card({}).body,
+          cssProp ? css(cssProp) : undefined,
+          className,
+        )}
+        {...rest}
+      />
+    );
+  },
+);