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

package/LICENSE.md

@@ -19,3 +19,35 @@ 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.
+
+---
+
+## Third-party notices
+
+This package includes design tokens and component styling derived from
+[Chakra UI](https://github.com/chakra-ui/chakra-ui) v2: the token scales in
+`src/base-tokens.ts` were snapshotted from `@chakra-ui/theme`'s default
+values, and the component recipes were ported from Chakra's component styles.
+Chakra UI is used under the MIT License:
+
+> MIT License
+>
+> Copyright (c) 2019 Segun Adebayo
+>
+> 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

@@ -1,12 +1,15 @@
 # @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 Micro:bit Educational Foundation apps' original
+[Chakra UI](https://chakra-ui.com/) v2 themes (see
+[Chakra UI heritage](#chakra-ui-heritage-and-license)).
 
 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.
+step and no CSS shipped — the consumer's Panda run produces exactly the styles
+its tree uses (`panda codegen` for the `styled-system/*` helpers, the Panda
+PostCSS plugin for the CSS).
 
 ## App-side installation
 
@@ -16,17 +19,15 @@ 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).
+   design system), 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
    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.
+   dependency, regenerate clean: `rm -rf styled-system && 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:
@@ -40,10 +41,25 @@ npm run panda` — incremental codegen does not detect external preset
    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.
+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;
+   ```
+   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
@@ -58,6 +74,64 @@ node_modules/@microbit/ui/lang/ui.fr.json --ast --out-file ...` (multiple
    app can dismiss open menus from outside the tree (e.g. the Android
    hardware back button). Apps without one can omit the provider.
 
+## Legacy browser support (Safari < 15) — temporary
+
+Panda's output uses two things Safari below 15 mishandles. If an app must
+support that far back (e.g. Safari 14.1 web views), add the app-side wiring
+below. **All of it is meant to be deleted once the app's support floor rises
+past these browsers** — it lives entirely in the consuming app's build config,
+never in shipped component source. This package's own Storybook does _not_ use
+any of it (it targets modern browsers, where these work natively).
+
+Two concerns:
+
+1. **`@layer`** — Safari < 15.4 drops `@layer` blocks wholesale, leaving the
+   app unstyled. Flatten them with `@csstools/postcss-cascade-layers` (which
+   rewrites layers into `:not(#\#)` specificity fallbacks; ~+8% gzipped CSS,
+   mostly compressible).
+2. **Logical shorthands + `var()`** — Safari 14.x silently drops
+   `padding-inline: var(--…)` and friends (a literal value, or the -start/-end
+   longhands, both work). Panda emits these shorthands for its px/py/mx/my
+   utilities, so most token spacing collapses. Expand them to longhands with
+   this package's `postcss-legacy-safari` plugin (kept logical, so RTL flips).
+
+```bash
+npm i -D @csstools/postcss-cascade-layers
+```
+
+```js
+// postcss.config.cjs — the two legacy plugins run AFTER Panda's (step 4), so
+// switch that config to array form:
+const {
+  expandLogicalShorthands,
+} = require("@microbit/ui/postcss-legacy-safari");
+
+module.exports = {
+  plugins: [
+    require("@pandacss/dev/postcss")(),
+    expandLogicalShorthands(),
+    require("@csstools/postcss-cascade-layers"),
+  ],
+};
+```
+
+```ts
+// vite.config.ts — pin the CSS/JS floor. Otherwise the lightningcss minifier
+// inherits build.target and downlevels logical longhands into fragile
+// :lang()-based physical rules. Keep in sync with package.json "browserslist".
+const BUILD_TARGETS = ["safari14.1", "ios14.5", "chrome90", "edge90", "firefox88"];
+// ...
+build: {
+  target: BUILD_TARGETS,
+  cssTarget: BUILD_TARGETS,
+  cssMinify: "lightningcss", // lightningcss as minifier only, not the transformer
+},
+```
+
+To drop it all: raise `BUILD_TARGETS`/`browserslist` past the affected
+browsers, then remove the two PostCSS plugins (and this package's
+`postcss-legacy-safari` export).
+
 ## The CSS-variable contract
 
 Panda emits every token as a CSS custom property with its default naming —
@@ -82,8 +156,9 @@ 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:
+colour math, inline `style` for data-driven values — see gotcha #9 in the
+repo's [migration playbook](../../docs/migration-playbook.md)), import the
+runtime lookup:
 
 ```ts
 import { token } from "@microbit/ui"; // re-exports styled-system/tokens
@@ -116,3 +191,17 @@ 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.
+
+## Chakra UI heritage and license
+
+This package's design language began as a faithful port of
+[Chakra UI](https://chakra-ui.com/) v2's, done so the apps it serves could
+leave Chakra without a redesign: `src/base-tokens.ts` was snapshotted from
+`@chakra-ui/theme`'s default token scales, and the `*.recipe.ts` files were
+ported from Chakra's component styles onto Panda config recipes.
+However far it evolves from that starting point, it owes its foundations to
+Chakra. Thanks to Segun Adebayo and the Chakra UI contributors.
+
+The package is [MIT](LICENSE.md) © Micro:bit Educational Foundation and
+contributors; Chakra UI is MIT © Segun Adebayo, and its notice is carried
+in [LICENSE.md](LICENSE.md).

package/lang/ui.de.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Schließen",
+    "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.ga-ie.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Dún",
+    "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-cn.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

@@ -1,25 +1,27 @@
 {
   "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.",
+  "version": "0.1.0-alpha.5",
+  "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",
-    "./chakra-tokens": "./src/chakra-tokens.ts",
+    "./base-tokens": "./src/base-tokens.ts",
     "./messages": "./src/messages.ts",
+    "./postcss-legacy-safari": "./postcss-legacy-safari.cjs",
     "./lang/*": "./lang/*"
   },
   "files": [
     "src",
     "lang",
+    "postcss-legacy-safari.cjs",
     "README.md",
     "LICENSE.md"
   ],
   "sideEffects": false,
   "scripts": {
-    "panda": "panda codegen && panda cssgen --outfile styled-system.css",
+    "panda": "panda codegen",
     "typecheck": "npm run panda && tsc --noEmit",
     "prestorybook": "npm run panda",
     "storybook": "storybook dev -p 6006 --no-open",

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/src/Code.tsx

@@ -0,0 +1,20 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Code — inline code chip matching Chakra's <Code> (gray subtle, light mode).
+ */
+export const Code = styled("code", {
+  base: {
+    fontFamily: "mono",
+    fontSize: "sm",
+    px: "0.2em",
+    borderRadius: "sm",
+    bg: "gray.100",
+    color: "gray.800",
+  },
+});

package/src/Collapse.tsx

@@ -0,0 +1,168 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  CSSProperties,
+  ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface CollapseProps {
+  /** Expanded when true (Chakra's `in`). */
+  isOpen: boolean;
+  /** Height when collapsed (Chakra's `startingHeight`). */
+  startingHeight?: number | string;
+  /**
+   * Height when expanded (Chakra's `endingHeight`; defaults to the measured
+   * content height, tracked with a ResizeObserver so nested expansion works).
+   */
+  endingHeight?: number | string;
+  /** Remove the content from the DOM once the exit transition finishes. */
+  unmountOnExit?: boolean;
+  css?: SystemStyleObject;
+  className?: string;
+  style?: CSSProperties;
+  children: ReactNode;
+}
+
+const toCssSize = (v: number | string) =>
+  typeof v === "number" ? `${v}px` : v;
+
+/**
+ * Collapse — Chakra's Collapse transition without framer-motion: the content
+ * is measured and the wrapper's height (and opacity, when collapsing to zero)
+ * transitions between the collapsed and expanded sizes. Content stays mounted
+ * unless `unmountOnExit` is set.
+ *
+ * As with framer-motion, only `isOpen` changes animate: initial mounts render
+ * at rest, and height corrections (late measurement, content growth) snap —
+ * otherwise a collapse mounted inside an entering view morphs during the
+ * outer animation.
+ */
+export const Collapse = ({
+  isOpen,
+  startingHeight = 0,
+  endingHeight,
+  unmountOnExit = false,
+  css: cssProp,
+  className,
+  style,
+  children,
+}: CollapseProps) => {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [measuredHeight, setMeasuredHeight] = useState<number>();
+  // For unmountOnExit: stay in the DOM until the exit transition ends.
+  const [present, setPresent] = useState(isOpen);
+  // The state the DOM shows. It follows isOpen from a layout effect so the
+  // transition-enable and the height flip land in the same commit (a
+  // render-time flip detector is unreliable: React can discard renders,
+  // losing the state update while keeping ref mutations).
+  const [displayOpen, setDisplayOpen] = useState(isOpen);
+  const [animating, setAnimating] = useState(false);
+
+  useLayoutEffect(() => {
+    if (isOpen === displayOpen) {
+      return;
+    }
+    if (isOpen) {
+      // Opening: mount (collapsed) first, then flip on the next frame so
+      // the browser has a computed collapsed state to transition from.
+      setPresent(true);
+      const raf = requestAnimationFrame(() => {
+        setAnimating(true);
+        setDisplayOpen(true);
+      });
+      return () => cancelAnimationFrame(raf);
+    }
+    // Closing: enable the transition and flip together, pre-paint.
+    setAnimating(true);
+    setDisplayOpen(false);
+  }, [isOpen, displayOpen]);
+
+  useLayoutEffect(() => {
+    const el = contentRef.current;
+    if (!el || endingHeight !== undefined) {
+      return;
+    }
+    setMeasuredHeight(el.scrollHeight);
+    const observer = new ResizeObserver(() =>
+      setMeasuredHeight(el.scrollHeight),
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [endingHeight, present]);
+
+  // Fallback for browsers/edge cases where transitionend doesn't fire.
+  useEffect(() => {
+    if (animating) {
+      const timeout = setTimeout(() => {
+        setAnimating(false);
+        if (!isOpen && unmountOnExit) {
+          setPresent(false);
+        }
+      }, 400);
+      return () => clearTimeout(timeout);
+    }
+  }, [animating, isOpen, unmountOnExit]);
+
+  if (unmountOnExit && !present) {
+    return null;
+  }
+
+  const expanded =
+    endingHeight !== undefined
+      ? toCssSize(endingHeight)
+      : measuredHeight !== undefined
+        ? `${measuredHeight}px`
+        : "auto";
+  const collapsed = toCssSize(startingHeight);
+  const hideWhenCollapsed = collapsed === "0px" || collapsed === "0";
+
+  return (
+    <div
+      onTransitionEnd={(e) => {
+        if (e.propertyName === "height" && e.target === e.currentTarget) {
+          setAnimating(false);
+          if (!isOpen && unmountOnExit) {
+            setPresent(false);
+          }
+        }
+      }}
+      className={cx(
+        css(
+          {
+            overflow: "hidden",
+            display: "block",
+            transitionDuration: "0.25s",
+            transitionTimingFunction: "cubic-bezier(0.4, 0, 0.2, 1)",
+            _motionReduce: { transition: "none" },
+          },
+          cssProp,
+        ),
+        className,
+      )}
+      // Runtime-measured/caller-supplied heights; transitions enabled only
+      // while an isOpen change is in flight.
+      style={{
+        transitionProperty: animating ? "height, opacity" : "none",
+        height: displayOpen ? expanded : collapsed,
+        opacity: displayOpen || !hideWhenCollapsed ? 1 : 0,
+        // At rest fully-collapsed, remove the content from the a11y tree
+        // and tab order, as Chakra did (kept visible while animating so
+        // the exit transition shows).
+        visibility:
+          displayOpen || animating || !hideWhenCollapsed ? undefined : "hidden",
+        ...style,
+      }}
+    >
+      <div ref={contentRef}>{children}</div>
+    </div>
+  );
+};

package/src/Divider.tsx

@@ -3,19 +3,50 @@
  *
  * SPDX-License-Identifier: MIT
  */
+import { ComponentProps, forwardRef } from "react";
 import { styled } from "styled-system/jsx";
 
-/**
- * Divider — a horizontal rule matching Chakra's <Divider> (hairline at 60%
- * opacity; set `borderColor` to tint). Horizontal only.
- */
-export const Divider = styled("hr", {
+const StyledDivider = styled("hr", {
   base: {
     border: 0,
-    borderBottomWidth: "1px",
-    borderBottomStyle: "solid",
     borderColor: "gray.200",
     opacity: 0.6,
-    width: "100%",
   },
+  variants: {
+    orientation: {
+      horizontal: {
+        borderBottomWidth: "1px",
+        borderBottomStyle: "solid",
+        width: "100%",
+      },
+      vertical: {
+        borderLeftWidth: "1px",
+        borderLeftStyle: "solid",
+        height: "100%",
+      },
+    },
+  },
+  defaultVariants: { orientation: "horizontal" },
 });
+
+export interface DividerProps extends ComponentProps<typeof StyledDivider> {}
+
+/**
+ * Divider — a hairline rule matching Chakra's <Divider> (60% opacity; set
+ * `borderColor` to tint). `orientation="vertical"` needs a height from the
+ * layout, e.g. a stretched flex row (Chakra's vertical divider likewise
+ * relied on `height: 100%`).
+ */
+export const Divider = forwardRef<HTMLHRElement, DividerProps>(
+  function Divider(props, ref) {
+    return (
+      <StyledDivider
+        ref={ref}
+        aria-orientation={
+          props.orientation === "vertical" ? "vertical" : "horizontal"
+        }
+        {...props}
+      />
+    );
+  },
+);