@microbit/ui 0.1.0-alpha.3

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Micro:bit Educational Foundation and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @microbit/ui
+
+react-aria-components + Panda CSS primitives with a design language ported from
+the Micro:bit Educational Foundation apps' original Chakra UI v2 themes.
+
+The package **ships as source**: components import `styled-system/*`, which
+each consumer generates with its own Panda preset stack. There is no build
+step and no CSS shipped — the consumer's codegen produces exactly the styles
+its tree uses.
+
+## App-side installation
+
+This package's own Storybook (`.storybook/` + `panda.config.ts`) is a
+worked example of the setup below, minus the app/brand presets. Everything
+an app must do:
+
+1. **Panda preset stack** (`panda.config.ts`): `@pandacss/preset-base`, then
+   the **base preset** (`@microbit/ui/base-preset` — the complete micro:bit
+   design system , then optionally the app's own preset, then optionally a
+   **private brand preset** (these are used for Foundation colours, licensed
+   fonts).
+
+   Later presets override earlier ones token-by-token — the base recipes and
+   semantic tokens reference the brand tokens, which is how a brand swap
+   restyles everything without touching recipes. Set `eject: true` (the stack
+   supplies the full token system). After changing an _external_ preset
+   dependency, regenerate clean: `rm -rf styled-system styled-system.css &&
+npm run panda` — incremental codegen does not detect external preset
+   changes.
+
+2. **Include this package's source** in `panda.config.ts` so Panda extracts
+   the styles the components use:
+   ```ts
+   include: [
+     "./src/**/*.{ts,tsx}",
+     "./node_modules/@microbit/ui/src/**/*.{ts,tsx}",
+   ],
+   ```
+3. **Resolve `styled-system/*` onto the generated output** for all
+   importers, this package's source included — a `styled-system` alias in
+   both `tsconfig.json` `paths` and the bundler config (see the
+   `viteFinal` in `.storybook/main.ts`).
+4. **Cascade layers** (`src/layers.css`, imported first): declares the
+   document-wide layer order including the `vendor` layer for third-party
+   stylesheets — import any vendor CSS with `@import "..." layer(vendor)`
+   so it beats the preflight but loses to app styling.
+5. **react-intl**: an `IntlProvider` above any shared-ui usage. English
+   works with no setup (components carry inline `defaultMessage`); for
+   other locales compile this package's `lang/ui.<locale>.json` into the
+   app's per-locale catalogs as part of the app's formatjs compile step,
+   e.g. `formatjs compile lang/ui.fr.json
+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.
+
+## The CSS-variable contract
+
+Panda emits every token as a CSS custom property with its default naming —
+`{category}-{path}` with dots become dashes, camelCase becomes kebab-case:
+
+- `colors.brand.500` → `var(--colors-brand-500)`
+- `colors.statusBarBg` → `var(--colors-status-bar-bg)`
+- `fonts.display` → `var(--fonts-display)`
+
+These names are **API** for styling that lives outside React/Panda — e.g.
+CodeMirror highlight styles or xterm themes written as raw CSS. Two rules
+keep them stable:
+
+- Never set `hashing` or `prefix` in `panda.config.ts`.
+- Brand/app presets may change token _values_, never token _names_.
+
+Semantic tokens (`languageText`, `statusBarBg`, `danger.*`, `toast*Bg`,
+`controlCheckedBg`, `focusBorder`, …) are the extension points brand presets
+override; they resolve through var indirection, so overrides apply wherever
+the token is consumed.
+
+## Runtime token lookups
+
+For values that feed _computation_ rather than stylesheets (canvas painting,
+colour math, inline `style` for data-driven values — see gotcha #9 in
+RAC-MIGRATION.md), import the runtime lookup:
+
+```ts
+import { token } from "@microbit/ui"; // re-exports styled-system/tokens
+
+token("colors.brand.500"); // "#007dbc" — raw value, safe for colour math
+token("colors.statusBarBg"); // "var(--colors-brand2-500)" — CSS contexts only
+```
+
+Base tokens resolve to raw values; **semantic tokens resolve to `var()`
+references**, which are only meaningful where the browser interprets CSS.
+For computation, look up the base token the semantic one points at, or read
+the computed style. `token.var("colors.x.y")` returns the variable reference
+form explicitly.
+
+## Strings
+
+Components never hardcode user-facing text. The few strings this package
+needs internally (close-button labels, toast status announcements) are
+react-intl messages with ids in the `ui.` namespace; everything else is
+passed in by the caller as already-localized content.
+
+The `lang/ui.<locale>.json` files (formatjs extracted format) are the source
+of truth and are shipped as-is (exported at `./lang/*`); consuming apps
+compile them into their own per-locale catalogs (see the consumption setup
+above). Components also carry the English text inline as `defaultMessage`,
+so an app that compiles no catalogs still renders English.
+
+`en` is hand-edited; `en-US` is maintained manually. Other locales come from
+Crowdin via the repo-root `npm run update-translations -- <path to extracted
+Crowdin ZIP>` (config-driven over packages in
+`bin/update-translations.cjs`), after which you run `npm run i18n:tidy`
+from the root.

package/lang/ui.ca.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Tanca ",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.en-us.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Close",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.en.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Close",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.es-es.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Cerrar",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.fr.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Fermer",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.ja.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "閉じる",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.ko.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "닫기",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.lol.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "crwdns362700:0crwdne362700:0",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.nl.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Afsluiten",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.pl.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Zamknij",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.pt-br.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Fechar",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.zh-tw.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "關閉",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@microbit/ui",
+  "version": "0.1.0-alpha.3",
+  "description": "micro:bit design-system primitives: react-aria-components + Panda CSS with a Chakra v2 design language. Ships as source; see README for the consumption setup.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./base-preset": "./src/base-preset.ts",
+    "./chakra-tokens": "./src/chakra-tokens.ts",
+    "./messages": "./src/messages.ts",
+    "./lang/*": "./lang/*"
+  },
+  "files": [
+    "src",
+    "lang",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "panda": "panda codegen && panda cssgen --outfile styled-system.css",
+    "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/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",
+  },
+});