@microbit/ui 0.1.0-alpha.13 → 0.1.0-alpha.15

package/README.md

@@ -19,8 +19,10 @@ 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** (Foundation colours, licensed fonts).
+   design system), then optionally `@microbit/ui/dense-preset` (the × 0.88
+   spacing / × 0.9 font-size density the information-dense apps use), then
+   optionally the app's own preset, then optionally a **private brand
+   preset** (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
@@ -162,9 +164,9 @@ keep them stable:
 - 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.
+`button.*`, `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
 

package/lang/ui.cy.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Cau",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Gwall",
+    "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": "Rhybudd",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.it.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Chiudi",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Errore",
+    "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": "Attenzione",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "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",
@@ -8,6 +8,7 @@
     ".": "./src/index.ts",
     "./base-preset": "./src/base-preset.ts",
     "./base-tokens": "./src/base-tokens.ts",
+    "./dense-preset": "./src/dense-preset.ts",
     "./messages": "./src/messages.ts",
     "./postcss-legacy-safari": "./postcss-legacy-safari.cjs",
     "./reset.css": "./reset.css",

package/src/Avatar.recipe.ts

@@ -0,0 +1,168 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Avatar slot recipe — Chakra's avatar: a circle showing an image, the
+ * initials of a name, or a generic person glyph, optionally with a badge
+ * pinned to one corner.
+ *
+ * The background and text colour come from `var(--avatar-bg)` and
+ * `var(--avatar-color)` rather than being flat values, because the component
+ * derives them from the name (see Avatar.tsx) and writes them as inline custom
+ * properties — exactly as Chakra did. Two reasons, both about letting a call
+ * site win with a plain `css={{ bg: …, color: … }}`: an inline *property*
+ * would beat any class, where an inline *variable* only feeds this
+ * declaration; and both must stay single-class selectors, since a state
+ * selector like `&[data-light-bg]` outranks the call site's utility class on
+ * specificity wherever cascade layers aren't in play — which is every app
+ * still coexisting with Chakra (playbook gotcha #40).
+ *
+ * Sizes are Chakra's, with its `calc(size / 2.5)` font size resolved per size
+ * so an app preset can restate either independently (classroom's avatars are
+ * a grade larger than Chakra's).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop variants generated.
+ */
+export const avatar = defineSlotRecipe({
+  className: "avatar",
+  slots: ["root", "label", "image", "badge"],
+  base: {
+    root: {
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flexShrink: 0,
+      position: "relative",
+      verticalAlign: "top",
+      textAlign: "center",
+      textTransform: "uppercase",
+      fontWeight: "medium",
+      borderRadius: "full",
+      // Chakra's no-name defaults; the name-derived pair arrives inline.
+      background: "var(--avatar-bg, token(colors.gray.400))",
+      color: "var(--avatar-color, token(colors.white))",
+      borderColor: "white",
+    },
+    label: {
+      lineHeight: "1",
+    },
+    image: {
+      width: "100%",
+      height: "100%",
+      objectFit: "cover",
+      borderRadius: "inherit",
+    },
+    badge: {
+      position: "absolute",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      borderRadius: "full",
+      // em-relative, so a badge keeps its proportions at every avatar size.
+      borderWidth: "0.2em",
+      borderStyle: "solid",
+      borderColor: "white",
+    },
+  },
+  variants: {
+    // Chakra's scale: the container size, and Chakra's `calc(size / 2.5)`
+    // font size kept as a calc over the same token so both track a preset
+    // that rescales `sizes` (the dense preset does, by 0.88).
+    //
+    // The font size lands on the root *and* the label, as Chakra's did
+    // (through one variable). They are separate declarations so an app can
+    // move one without the other: the root's is the em basis for a badge,
+    // the label's is how big the initials are, and the two are not always
+    // the same wish.
+    size: {
+      "2xs": {
+        root: {
+          width: "4",
+          height: "4",
+          fontSize: "calc(token(sizes.4) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.4) / 2.5)" },
+      },
+      xs: {
+        root: {
+          width: "6",
+          height: "6",
+          fontSize: "calc(token(sizes.6) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.6) / 2.5)" },
+      },
+      sm: {
+        root: {
+          width: "8",
+          height: "8",
+          fontSize: "calc(token(sizes.8) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.8) / 2.5)" },
+      },
+      md: {
+        root: {
+          width: "12",
+          height: "12",
+          fontSize: "calc(token(sizes.12) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.12) / 2.5)" },
+      },
+      lg: {
+        root: {
+          width: "16",
+          height: "16",
+          fontSize: "calc(token(sizes.16) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.16) / 2.5)" },
+      },
+      xl: {
+        root: {
+          width: "24",
+          height: "24",
+          fontSize: "calc(token(sizes.24) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.24) / 2.5)" },
+      },
+      "2xl": {
+        root: {
+          width: "32",
+          height: "32",
+          fontSize: "calc(token(sizes.32) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.32) / 2.5)" },
+      },
+    },
+    /** Which corner the badge sits in. Chakra's placements, same offsets. */
+    placement: {
+      "top-start": {
+        badge: {
+          top: "0",
+          insetStart: "0",
+          transform: "translate(-25%, -25%)",
+        },
+      },
+      "top-end": {
+        badge: { top: "0", insetEnd: "0", transform: "translate(25%, -25%)" },
+      },
+      "bottom-start": {
+        badge: {
+          bottom: "0",
+          insetStart: "0",
+          transform: "translate(-25%, 25%)",
+        },
+      },
+      "bottom-end": {
+        badge: { bottom: "0", insetEnd: "0", transform: "translate(25%, 25%)" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    placement: "bottom-end",
+  },
+});

package/src/Avatar.tsx

@@ -0,0 +1,276 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  cloneElement,
+  CSSProperties,
+  HTMLAttributes,
+  isValidElement,
+  ReactElement,
+  ReactNode,
+  SVGProps,
+  useEffect,
+  useState,
+} from "react";
+import { css, cx } from "styled-system/css";
+import { avatar, AvatarVariantProps } from "styled-system/recipes";
+import { token } from "styled-system/tokens";
+import { SystemStyleObject } from "styled-system/types";
+
+/**
+ * Chakra's `randomColor({ string })`, reproduced exactly: a djb2-style hash of
+ * the name, its low three bytes read as a colour. Not random despite the name
+ * — the same name is always the same colour, which is the point, and
+ * reproducing the hash means avatars keep the colours they had under Chakra.
+ */
+const colorFromName = (name: string): string => {
+  let hash = 0;
+  for (let i = 0; i < name.length; i += 1) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash);
+    hash = hash & hash;
+  }
+  let color = "#";
+  for (let j = 0; j < 3; j += 1) {
+    const value = (hash >> (j * 8)) & 255;
+    color += `00${value.toString(16)}`.slice(-2);
+  }
+  return color;
+};
+
+/**
+ * Chakra's contrast rule for the generated background: perceived brightness
+ * (the classic 299/587/114 weighting) below 128 counts as dark, and dark
+ * backgrounds take white text.
+ */
+const isLight = (hex: string): boolean => {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return (r * 299 + g * 587 + b * 114) / 1000 >= 128;
+};
+
+/**
+ * Chakra's `initials`: first letter of the first and last words. Prefixed
+ * because it is exported from the package root, where a bare `initials`
+ * would be a broad name to claim.
+ */
+export const avatarInitials = (name: string): string => {
+  const names = name.trim().split(" ");
+  const firstName = names[0] ?? "";
+  const lastName = names.length > 1 ? names[names.length - 1] : "";
+  return firstName && lastName
+    ? `${firstName.charAt(0)}${lastName.charAt(0)}`
+    : firstName.charAt(0);
+};
+
+/**
+ * Chakra's generic person glyph, the fallback when there is no name. Chakra
+ * hardcoded it white; here it inherits `currentColor`, which is the same white
+ * on the no-name grey background and stays visible if a call site recolours.
+ */
+export const GenericAvatarIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg viewBox="0 0 128 128" width="100%" height="100%" {...props}>
+    <path
+      fill="currentColor"
+      d="M103,102.1388 C93.094,111.92 79.3504,118 64.1638,118 C48.8056,118 34.9294,111.768 25,101.7892 L25,95.2 C25,86.8096 31.981,80 40.6,80 L87.4,80 C96.019,80 103,86.8096 103,95.2 L103,102.1388 Z"
+    />
+    <path
+      fill="currentColor"
+      d="M63.9961647,24 C51.2938136,24 41,34.2938136 41,46.9961647 C41,59.7061864 51.2938136,70 63.9961647,70 C76.6985159,70 87,59.7061864 87,46.9961647 C87,34.2938136 76.6985159,24 63.9961647,24"
+    />
+  </svg>
+);
+
+type ImageStatus = "pending" | "loading" | "loaded" | "failed";
+
+/**
+ * Chakra's `useImage`: load the photo out of band and report how it went, so
+ * the avatar can show the initials or the icon meanwhile and keep showing
+ * them if it never arrives.
+ *
+ * The <img> element is only mounted once this says "loaded", which is what
+ * keeps a broken URL from leaving the browser's broken-image glyph inside the
+ * circle — the failure mode a fallback exists to prevent.
+ */
+const useImageStatus = (src?: string, srcSet?: string): ImageStatus => {
+  const [status, setStatus] = useState<ImageStatus>(
+    src ? "loading" : "pending",
+  );
+  useEffect(() => {
+    if (!src) {
+      setStatus("pending");
+      return;
+    }
+    // A new src starts again: without this the avatar would keep showing the
+    // previous person's photo, or stay stuck on a fallback it has outgrown.
+    setStatus("loading");
+    const img = new Image();
+    let current = true;
+    img.onload = () => {
+      if (current) {
+        setStatus("loaded");
+      }
+    };
+    img.onerror = () => {
+      if (current) {
+        setStatus("failed");
+      }
+    };
+    // srcSet before src, so the browser has the candidates to choose from
+    // when the load starts.
+    if (srcSet) {
+      img.srcset = srcSet;
+    }
+    img.src = src;
+    return () => {
+      current = false;
+      img.onload = null;
+      img.onerror = null;
+    };
+  }, [src, srcSet]);
+  return status;
+};
+
+export interface AvatarProps
+  extends Omit<HTMLAttributes<HTMLSpanElement>, "color" | "children">,
+    Pick<AvatarVariantProps, "size"> {
+  /**
+   * The person. Shown as initials, and hashed into the background colour, so
+   * two people are unlikely to share one.
+   */
+  name?: string;
+  /**
+   * Photo. The initials (or the icon) show until it has loaded, and go on
+   * showing if it fails — the avatar never renders a broken image.
+   */
+  src?: string;
+  srcSet?: string;
+  /** Shown when there is no name. Defaults to Chakra's person glyph. */
+  icon?: ReactNode;
+  /** Accessible name for the icon fallback. Chakra's default was " avatar". */
+  iconLabel?: string;
+  /** Override how a name becomes initials. */
+  getInitials?: (name: string) => string;
+  /** Chakra's `showBorder`: a 2px ring in the avatar's border colour. */
+  showBorder?: boolean;
+  /** An `AvatarBadge`. */
+  children?: ReactNode;
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * Avatar — Chakra's <Avatar>: a circular identity marker showing a photo, the
+ * initials of a name, or a generic glyph, in a colour derived from the name.
+ *
+ * Decorative in most designs — pass `aria-hidden` where the name is already
+ * beside it, as Chakra's call sites did.
+ */
+export const Avatar = ({
+  name,
+  src,
+  srcSet,
+  icon,
+  iconLabel = " avatar",
+  getInitials = avatarInitials,
+  showBorder,
+  size,
+  children,
+  css: cssProp,
+  className,
+  style,
+  ...rest
+}: AvatarProps) => {
+  const status = useImageStatus(src, srcSet);
+  const isLoaded = status === "loaded";
+  const slots = avatar({ size });
+  // Only while the image isn't showing, matching Chakra's `:not([data-loaded])`.
+  const bg = name && !isLoaded ? colorFromName(name) : undefined;
+  return (
+    <span
+      {...rest}
+      data-loaded={isLoaded || undefined}
+      className={cx(
+        slots.root,
+        showBorder ? css({ borderWidth: "2px" }) : undefined,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+      style={
+        bg
+          ? ({
+              ...style,
+              "--avatar-bg": bg,
+              // Chakra's contrast rule, as a variable rather than a state
+              // selector so a call site's `css` colour still wins (see the
+              // recipe).
+              "--avatar-color": isLight(bg)
+                ? token("colors.gray.800")
+                : token("colors.white"),
+            } as CSSProperties)
+          : style
+      }
+    >
+      {isLoaded ? (
+        <img
+          src={src}
+          srcSet={srcSet}
+          alt={name ?? iconLabel}
+          className={slots.image}
+        />
+      ) : name ? (
+        <span role="img" aria-label={name} className={slots.label}>
+          {getInitials(name)}
+        </span>
+      ) : // The icon is labelled in place rather than wrapped, as Chakra did:
+      // a wrapper would make it an inline child with a line box of its own,
+      // where directly in the flex container it is a flex item and centres
+      // exactly.
+      isValidElement(icon) ? (
+        cloneElement(icon as ReactElement<Record<string, unknown>>, {
+          role: "img",
+          "aria-label": iconLabel,
+        })
+      ) : (
+        icon ?? <GenericAvatarIcon role="img" aria-label={iconLabel} />
+      )}
+      {children}
+    </span>
+  );
+};
+
+export interface AvatarBadgeProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "color">,
+    Pick<AvatarVariantProps, "placement"> {
+  children?: ReactNode;
+  /**
+   * Per-instance style overrides. The badge has no size of its own — Chakra's
+   * didn't either, so call sites set one (`boxSize: "1.5em"` scales with the
+   * avatar).
+   */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/** AvatarBadge — a status dot pinned to a corner of its `Avatar`. */
+export const AvatarBadge = ({
+  placement,
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: AvatarBadgeProps) => (
+  <div
+    {...rest}
+    className={cx(
+      avatar({ placement }).badge,
+      cssProp ? css(cssProp) : undefined,
+      className,
+    )}
+  >
+    {children}
+  </div>
+);

package/src/Button.recipe.ts

@@ -24,7 +24,7 @@ const transitionCommon =
  * 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).
+ * token-driven (see the `button.*` and `languageText` semantic tokens).
  *
  * Registered in the base preset (base-preset.ts).
  */
@@ -92,13 +92,22 @@ export const button = defineRecipe({
           textDecoration: "underline",
         },
       },
+      // Colours come from the `button.*` semantic tokens so the family's two
+      // button idioms (brand-coloured vs black-on-white) share this recipe —
+      // see the token block in base-preset.ts.
       secondary: {
         borderWidth: "2px",
-        borderColor: "brand.500",
-        color: "brand.700",
+        borderColor: "button.secondaryBorder",
+        color: "button.secondaryText",
         bg: "transparent",
-        _hover: { borderColor: "brand.600" },
-        _active: { bg: "brand.50", borderColor: "brand.700" },
+        _hover: {
+          borderColor: "button.secondaryHoverBorder",
+          bg: "button.secondaryHoverBg",
+        },
+        _active: {
+          bg: "button.secondaryActiveBg",
+          borderColor: "button.secondaryActiveBorder",
+        },
       },
       ghost: {
         color: "black",
@@ -116,17 +125,35 @@ export const button = defineRecipe({
       },
       primary: {
         color: "white",
-        bg: "brand.500",
-        _hover: { bg: "brand.600", _disabled: { bg: "brand.500" } },
-        _active: { bg: "brand.700" },
+        bg: "button.primaryBg",
+        _hover: {
+          bg: "button.primaryHoverBg",
+          _disabled: { bg: "button.primaryBg" },
+        },
+        _active: { bg: "button.primaryActiveBg" },
       },
+      // 600/700, matching what python-editor's Chakra outline + red
+      // colorScheme resolved to. (Extracted from ml-trainer at 500/600, but
+      // its one warning button tolerates the darkening; python-editor's
+      // "Reset project" was visibly lighter than its Chakra self.)
+      // NOTE (2026-08-02, from classroom): two Chakra `outline` shapes have
+      // no home here and are currently restated per call site in that app —
+      // worth considering as variants once a second consumer wants them.
+      //   - a neutral outline (transparent, 1px gray.200, inherited text,
+      //     gray.50/gray.100 hover/press): Chakra's default-colorScheme
+      //     `outline`, and python-editor's *default* variant per the
+      //     playbook's cross-app vocabulary, so likely already a 2-app shape.
+      //   - an on-colour outline (white 2px + white text over a coloured bar,
+      //     whiteAlpha hover/press): Chakra's `outline` + `whiteAlpha`.
+      // `warning` below is the *destructive* outline and is not a substitute
+      // for either; `warningSolid` did map exactly onto Chakra solid+red.
       warning: {
         borderWidth: "2px",
-        borderColor: "danger.500",
-        color: "danger.500",
+        borderColor: "danger.600",
+        color: "danger.600",
         bg: "transparent",
-        _hover: { borderColor: "danger.600" },
-        _active: { bg: "danger.50", borderColor: "danger.500" },
+        _hover: { borderColor: "danger.700", color: "danger.700" },
+        _active: { bg: "danger.50" },
       },
       // Chakra's built-in solid + red colorScheme (destructive confirm
       // buttons). Same values as `record` today, but a separate variant so