@microbit/ui 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -44,22 +44,35 @@ an app must do:
 4. **Generate and load the CSS** with Panda's PostCSS plugin. Keep Vite's
    default transformer — do **not** set `css.transformer: "lightningcss"`,
    which disables PostCSS. Add a `postcss.config.cjs`:
+
    ```js
    module.exports = { plugins: { "@pandacss/dev/postcss": {} } };
    ```
+
    Run `panda codegen` as a `prepare`/`predev` step so the `styled-system/*`
    helpers exist before `tsc`; the plugin generates the CSS during the bundle.
    Import **one** entry stylesheet — first, before app styles — that declares
    the cascade-layer order; the plugin injects the generated CSS into it (the
    declaration must list all of Panda's layers, hence ≥5 names):
+
    ```css
    /* e.g. src/layers.css, imported once at the app root */
    @layer reset, vendor, base, tokens, recipes, utilities;
+
+   @import "@microbit/ui/reset.css" layer(reset);
    ```
+
+   The `reset.css` import is **required**: it carries the Chakra-parity
+   `* { border-color; word-wrap }` defaults, which must sit in the bottom
+   layer (the legacy-Safari cascade-layer flattening specificity-boosts
+   higher layers above CSS it can't see — runtime-injected styles, other
+   files; playbook gotcha #28). Without it, elements that set a border
+   width but no colour render `currentColor` borders.
    The `vendor` layer is for third-party stylesheets: import any vendor CSS
    with `@import "..." layer(vendor)` so it beats the preflight reset but
    loses to app styling. See `.storybook/{layers.css,preview.tsx,main.ts}` +
    `postcss.config.cjs` for the worked example.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "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",
@@ -10,12 +10,14 @@
     "./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"
   ],

package/reset.css

@@ -0,0 +1,23 @@
+/**
+ * (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;
+}

package/src/Button.tsx

@@ -8,25 +8,10 @@ import {
   Button as RACButton,
   ButtonProps as RACButtonProps,
 } from "react-aria-components";
-import { css, cva, cx } from "styled-system/css";
+import { css, cx } from "styled-system/css";
 import { button, ButtonVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
-
-// Chakra's ButtonIcon: keeps the glyph centred and spaced from the label
-// (iconSpacing 0.5rem).
-const buttonIcon = cva({
-  base: {
-    display: "inline-flex",
-    alignSelf: "center",
-    flexShrink: 0,
-  },
-  variants: {
-    side: {
-      left: { marginEnd: "2" },
-      right: { marginStart: "2" },
-    },
-  },
-});
+import { buttonIcon } from "./button-icon";
 
 export interface ButtonProps
   extends Omit<RACButtonProps, "className" | "children">,

package/src/LinkButton.tsx

@@ -0,0 +1,80 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, ReactNode } from "react";
+import {
+  Link as RACLink,
+  LinkProps as RACLinkProps,
+} 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 LinkButtonProps
+  extends Omit<RACLinkProps, "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;
+}
+
+// Anchors pick up underline styling that buttons never have.
+const linkReset = css.raw({
+  textDecoration: "none",
+  _hover: { textDecoration: "none" },
+});
+
+/**
+ * LinkButton — a navigation link that looks like a Button (Chakra's
+ * `Button as="a"`). react-aria-components <Link> renders a real anchor
+ * (`href`, `target`, new-tab/middle-click semantics preserved) with the same
+ * interaction data attributes as Button, so the `button` recipe's
+ * hover/press/focus/disabled states apply unchanged.
+ *
+ * Use for navigation that should read as a call to action (e.g. an external
+ * help page presented as a dialog's primary action); use Button for
+ * in-page actions.
+ */
+export const LinkButton = forwardRef<HTMLAnchorElement, LinkButtonProps>(
+  function LinkButton(
+    {
+      variant,
+      size,
+      css: cssProp,
+      className,
+      leftIcon,
+      rightIcon,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <RACLink
+        ref={ref}
+        className={cx(
+          button({ variant, size }),
+          css(linkReset, cssProp),
+          className,
+        )}
+        {...rest}
+      >
+        {leftIcon ? (
+          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
+        ) : null}
+        {children}
+        {rightIcon ? (
+          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
+        ) : null}
+      </RACLink>
+    );
+  },
+);

package/src/base-preset.ts

@@ -146,13 +146,16 @@ export const basePreset = definePreset({
           600: { value: "{colors.red.600}" },
           700: { value: "{colors.red.700}" },
         },
-        // The `language` button variant's text colour is the one place the
-        // brands diverge structurally (OSS uses the grey brand2 ramp, the
-        // CreateAI brand its blue brand ramp with no hover change). Driven by
-        // these semantic tokens so the recipe stays shared and a brand preset
-        // overrides only the values.
-        languageText: { value: "{colors.brand2.500}" },
-        languageTextHover: { value: "{colors.brand2.600}" },
+        // The `language` button variant's text colour follows the primary
+        // interactive brand: every consumer resolves it to its `brand` ramp
+        // (CreateAI privately to brand.600 with no hover change,
+        // python-editor to brand.500/600 — the default). Semantic tokens so
+        // the recipe stays shared and a brand preset overrides only values.
+        // (Was brand2.* — the grey ml-trainer OSS Chakra look — but both
+        // apps' final values sit on their primary brand, so the default
+        // follows; OSS language buttons are brand blue.)
+        languageText: { value: "{colors.brand.500}" },
+        languageTextHover: { value: "{colors.brand.600}" },
         // Toast status colours: the Chakra-era toast Alert restyle (teal for
         // every status except error) shared across the app family.
         toastInfoBg: { value: "{colors.teal.800}" },
@@ -208,10 +211,12 @@ export const basePreset = definePreset({
     "*::placeholder": {
       color: "gray.500",
     },
-    "*, *::before, *::after": {
-      borderColor: "gray.200",
-      wordWrap: "break-word",
-    },
+    // The `* { border-color; word-wrap }` Chakra-reset parity lives in
+    // ../reset.css, imported into the `reset` layer by consumers'
+    // layers.css — NOT here: globalCss emits into the `base` layer, which
+    // the legacy-Safari cascade-layer flattening specificity-boosts above
+    // runtime-injected CSS (CodeMirror themes) and other app CSS files.
+    // Resets must stay at the bottom (playbook gotcha #28).
     // Panda's preflight, unlike Chakra's reset, doesn't set the pointer
     // cursor on buttons. Recipes' disabled states (cursor: not-allowed)
     // override this from the higher recipes layer.

package/src/button-icon.ts

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

package/src/index.ts

@@ -10,6 +10,7 @@
  */
 export * from "./system";
 export * from "./Button";
+export * from "./LinkButton";
 export * from "./ButtonGroup";
 export * from "./Card";
 export * from "./Checkbox";