@microbit/ui 0.1.0-alpha.22 → 0.1.0-alpha.24

package/lang/ui.pl.json

@@ -1,6 +1,6 @@
 {
   "ui.breadcrumb": {
-    "defaultMessage": "Breadcrumb",
+    "defaultMessage": "Ścieżka nawigacji",
     "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
   },
   "ui.close-action": {
@@ -12,11 +12,11 @@
     "description": "Accessible label for a ComboBox's dropdown list of suggestions"
   },
   "ui.combobox-trigger": {
-    "defaultMessage": "Wyświetlaj sugestie",
+    "defaultMessage": "Pokaż sugestie",
     "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
   },
   "ui.loading": {
-    "defaultMessage": "Loading",
+    "defaultMessage": "Ładowanie",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
   "ui.numberfield-decrease": {
@@ -32,7 +32,7 @@
     "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
   },
   "ui.select-row-action": {
-    "defaultMessage": "Zaznacz",
+    "defaultMessage": "Wybierz",
     "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
   },
   "ui.toast-region": {
@@ -40,19 +40,19 @@
     "description": "Accessible label for the notifications area; count is the number of notifications showing"
   },
   "ui.toast-status-error": {
-    "defaultMessage": "Error",
+    "defaultMessage": "Błąd",
     "description": "Announced by screen readers before an error notification"
   },
   "ui.toast-status-info": {
-    "defaultMessage": "Information",
+    "defaultMessage": "Informacja",
     "description": "Announced by screen readers before an informational notification"
   },
   "ui.toast-status-success": {
-    "defaultMessage": "Success",
+    "defaultMessage": "Sukces",
     "description": "Announced by screen readers before a success notification"
   },
   "ui.toast-status-warning": {
-    "defaultMessage": "Warning",
+    "defaultMessage": "Ostrzeżenie",
     "description": "Announced by screen readers before a warning notification"
   }
 }

package/lang/ui.pt-br.json

@@ -1,6 +1,6 @@
 {
   "ui.breadcrumb": {
-    "defaultMessage": "Breadcrumb",
+    "defaultMessage": "Trilha de navegação",
     "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
   },
   "ui.close-action": {
@@ -16,7 +16,7 @@
     "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
   },
   "ui.loading": {
-    "defaultMessage": "Loading",
+    "defaultMessage": "Carregando",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
   "ui.numberfield-decrease": {
@@ -32,7 +32,7 @@
     "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
   },
   "ui.select-row-action": {
-    "defaultMessage": "Selecionar",
+    "defaultMessage": "Seleciona",
     "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
   },
   "ui.toast-region": {
@@ -40,19 +40,19 @@
     "description": "Accessible label for the notifications area; count is the number of notifications showing"
   },
   "ui.toast-status-error": {
-    "defaultMessage": "Error",
+    "defaultMessage": "Erro",
     "description": "Announced by screen readers before an error notification"
   },
   "ui.toast-status-info": {
-    "defaultMessage": "Information",
+    "defaultMessage": "Informações",
     "description": "Announced by screen readers before an informational notification"
   },
   "ui.toast-status-success": {
-    "defaultMessage": "Success",
+    "defaultMessage": "Sucesso",
     "description": "Announced by screen readers before a success notification"
   },
   "ui.toast-status-warning": {
-    "defaultMessage": "Warning",
+    "defaultMessage": "Atenção",
     "description": "Announced by screen readers before a warning notification"
   }
 }

package/lang/ui.vi.json

@@ -0,0 +1,58 @@
+{
+  "ui.breadcrumb": {
+    "defaultMessage": "Đường dẫn",
+    "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
+  },
+  "ui.close-action": {
+    "defaultMessage": "Đóng",
+    "description": "Close button text or label"
+  },
+  "ui.combobox-listbox": {
+    "defaultMessage": "Gợi ý",
+    "description": "Accessible label for a ComboBox's dropdown list of suggestions"
+  },
+  "ui.combobox-trigger": {
+    "defaultMessage": "Hiển thị gợi ý",
+    "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
+  },
+  "ui.loading": {
+    "defaultMessage": "Đang tải",
+    "description": "Announced by screen readers for a button showing a loading spinner"
+  },
+  "ui.numberfield-decrease": {
+    "defaultMessage": "Giảm {fieldLabel}",
+    "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.numberfield-increase": {
+    "defaultMessage": "Tăng {fieldLabel}",
+    "description": "Accessible label for a number field's increment stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.select-placeholder": {
+    "defaultMessage": "Chọn một mục",
+    "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
+  },
+  "ui.select-row-action": {
+    "defaultMessage": "Lựa chọn",
+    "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
+  },
+  "ui.toast-region": {
+    "defaultMessage": "{count, plural, other {# thông báo}}.",
+    "description": "Accessible label for the notifications area; count is the number of notifications showing"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Lỗi",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Thông tin",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Thành công",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Cảnh báo",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.zh-cn.json

@@ -1,6 +1,6 @@
 {
   "ui.breadcrumb": {
-    "defaultMessage": "Breadcrumb",
+    "defaultMessage": "痕迹导航",
     "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
   },
   "ui.close-action": {
@@ -16,7 +16,7 @@
     "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
   },
   "ui.loading": {
-    "defaultMessage": "Loading",
+    "defaultMessage": "正在加载",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
   "ui.numberfield-decrease": {
@@ -40,19 +40,19 @@
     "description": "Accessible label for the notifications area; count is the number of notifications showing"
   },
   "ui.toast-status-error": {
-    "defaultMessage": "Error",
+    "defaultMessage": "错误",
     "description": "Announced by screen readers before an error notification"
   },
   "ui.toast-status-info": {
-    "defaultMessage": "Information",
+    "defaultMessage": "信息",
     "description": "Announced by screen readers before an informational notification"
   },
   "ui.toast-status-success": {
-    "defaultMessage": "Success",
+    "defaultMessage": "成功",
     "description": "Announced by screen readers before a success notification"
   },
   "ui.toast-status-warning": {
-    "defaultMessage": "Warning",
+    "defaultMessage": "警告",
     "description": "Announced by screen readers before a warning notification"
   }
 }

package/lang/ui.zh-tw.json

@@ -1,6 +1,6 @@
 {
   "ui.breadcrumb": {
-    "defaultMessage": "Breadcrumb",
+    "defaultMessage": "巡覽路徑",
     "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
   },
   "ui.close-action": {
@@ -16,7 +16,7 @@
     "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
   },
   "ui.loading": {
-    "defaultMessage": "Loading",
+    "defaultMessage": "正在載入",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
   "ui.numberfield-decrease": {
@@ -32,7 +32,7 @@
     "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
   },
   "ui.select-row-action": {
-    "defaultMessage": "選取",
+    "defaultMessage": "選擇",
     "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
   },
   "ui.toast-region": {
@@ -40,19 +40,19 @@
     "description": "Accessible label for the notifications area; count is the number of notifications showing"
   },
   "ui.toast-status-error": {
-    "defaultMessage": "Error",
+    "defaultMessage": "錯誤",
     "description": "Announced by screen readers before an error notification"
   },
   "ui.toast-status-info": {
-    "defaultMessage": "Information",
+    "defaultMessage": "資訊",
     "description": "Announced by screen readers before an informational notification"
   },
   "ui.toast-status-success": {
-    "defaultMessage": "Success",
+    "defaultMessage": "成功",
     "description": "Announced by screen readers before a success notification"
   },
   "ui.toast-status-warning": {
-    "defaultMessage": "Warning",
+    "defaultMessage": "警告",
     "description": "Announced by screen readers before a warning notification"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "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",

package/src/Avatar.recipe.ts

@@ -6,24 +6,20 @@
 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.
+ * Avatar slot recipe — 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).
+ * properties. 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]`
+ * would outrank the call site's utility class on specificity.
  *
- * 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).
+ * The `calc(size / 2.5)` font size is resolved per size so an app preset can
+ * restate either independently (classroom's avatars are a grade larger).
  *
  * Registered in the base preset (base-preset.ts), which also has the
  * `staticCss` entry that keeps the runtime-prop variants generated.
@@ -43,7 +39,7 @@ export const avatar = defineSlotRecipe({
       textTransform: "uppercase",
       fontWeight: "medium",
       borderRadius: "full",
-      // Chakra's no-name defaults; the name-derived pair arrives inline.
+      // The no-name defaults; the name-derived pair arrives inline.
       // gray.350 is the decorative-fill stop — 400+ are reserved for
       // accessible outlines and text (see the ramp in base-preset.ts).
       background: "var(--avatar-bg, token(colors.gray.350))",
@@ -72,12 +68,12 @@ export const avatar = defineSlotRecipe({
     },
   },
   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 container size, and the `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
+    // The font size lands on the root *and* the label. 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.
@@ -139,7 +135,7 @@ export const avatar = defineSlotRecipe({
         label: { fontSize: "calc(token(sizes.32) / 2.5)" },
       },
     },
-    /** Which corner the badge sits in. Chakra's placements, same offsets. */
+    /** Which corner the badge sits in. */
     placement: {
       "top-start": {
         badge: {

package/src/Avatar.tsx

@@ -20,10 +20,10 @@ 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.
+ * A djb2-style hash of the name, its low three bytes read as a colour. The
+ * same name is always the same colour, and the exact hash is a compatibility
+ * contract: apps' existing avatar rosters keep the colours they have always
+ * had, so don't change it.
  */
 const colorFromName = (name: string): string => {
   let hash = 0;
@@ -40,8 +40,8 @@ const colorFromName = (name: string): string => {
 };
 
 /**
- * Chakra's contrast rule for the generated background: perceived brightness
- * (the classic 299/587/114 weighting) below 128 counts as dark, and dark
+ * 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 => {
@@ -52,9 +52,9 @@ const isLight = (hex: string): boolean => {
 };
 
 /**
- * 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.
+ * 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(" ");
@@ -66,9 +66,12 @@ export const avatarInitials = (name: string): string => {
 };
 
 /**
- * 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.
+ * The generic person glyph, the fallback when there is no name. It inherits
+ * `currentColor` — white on the no-name grey background — so it stays visible
+ * if a call site recolours.
+ *
+ * The paths are Chakra UI's avatar glyph, inlined for visual parity with the
+ * apps' original look (see the notice in LICENSE.md).
  */
 export const GenericAvatarIcon = (props: SVGProps<SVGSVGElement>) => (
   <svg viewBox="0 0 128 128" width="100%" height="100%" {...props}>
@@ -86,9 +89,9 @@ export const GenericAvatarIcon = (props: SVGProps<SVGSVGElement>) => (
 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.
+ * 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
@@ -147,13 +150,13 @@ export interface AvatarProps
    */
   src?: string;
   srcSet?: string;
-  /** Shown when there is no name. Defaults to Chakra's person glyph. */
+  /** Shown when there is no name. Defaults to the generic person glyph. */
   icon?: ReactNode;
-  /** Accessible name for the icon fallback. Chakra's default was " avatar". */
+  /** Accessible name for the icon fallback. Defaults to " 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. */
+  /** A 2px ring in the avatar's border colour. */
   showBorder?: boolean;
   /** An `AvatarBadge`. */
   children?: ReactNode;
@@ -163,11 +166,11 @@ export interface AvatarProps
 }
 
 /**
- * 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.
+ * 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.
+ * beside it.
  */
 export const Avatar = ({
   name,
@@ -187,7 +190,7 @@ export const Avatar = ({
   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])`.
+  // Only while the image isn't showing.
   const bg = name && !isLoaded ? colorFromName(name) : undefined;
   return (
     <span
@@ -204,7 +207,7 @@ export const Avatar = ({
           ? ({
               ...style,
               "--avatar-bg": bg,
-              // Chakra's contrast rule, as a variable rather than a state
+              // The 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)
@@ -225,9 +228,9 @@ export const Avatar = ({
         <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
+      ) : // The icon is labelled in place rather than wrapped: 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>>, {
@@ -247,9 +250,8 @@ export interface AvatarBadgeProps
     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).
+   * Per-instance style overrides. The badge has no size of its own — call
+   * sites set one (`boxSize: "1.5em"` scales with the avatar).
    */
   css?: SystemStyleObject;
   className?: string;

package/src/Breadcrumb.recipe.ts

@@ -6,10 +6,9 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Breadcrumb slot recipe — Chakra's Breadcrumb layout: a flex list with a
- * separator between items. The links themselves are the shared `Link`
- * (Chakra's BreadcrumbLink base was identical to its Link base), so there is
- * no link slot; the current page renders as a plain span.
+ * Breadcrumb slot recipe — a flex list with a separator between items. The
+ * links themselves are the shared `Link`, so there is no link slot; the
+ * current page renders as a plain span.
  *
  * Registered in the base preset (base-preset.ts). No variants, so it needs
  * no `staticCss` entry.
@@ -34,9 +33,6 @@ export const breadcrumb = defineSlotRecipe({
       "&:last-of-type [data-separator]": { display: "none" },
     },
     separator: {
-      // Chakra's default `spacing` was a literal 0.5rem; the token follows
-      // the library's existing lean (the button icon gap made the same
-      // call — see the playbook's open token-vs-literal spacing decision).
       mx: "2",
     },
   },

package/src/Breadcrumb.tsx

@@ -14,12 +14,12 @@ import { uiMessage } from "./messages";
 
 // The separator is declared once on the Breadcrumb and rendered by every
 // item; the current-page flag hops from BreadcrumbItem to the BreadcrumbLink
-// inside it (Chakra did both with cloneElement).
+// inside it.
 const SeparatorContext = createContext<ReactNode>("/");
 const CurrentPageContext = createContext(false);
 
 export interface BreadcrumbProps {
-  /** Between items; an element or string. Chakra's default "/". */
+  /** Between items; an element or string. Default "/". */
   separator?: ReactNode;
   /** Per-instance style overrides for the nav (e.g. fontSize). */
   css?: SystemStyleObject;
@@ -29,9 +29,8 @@ export interface BreadcrumbProps {
 }
 
 /**
- * Breadcrumb — navigation trail matching Chakra's: nav > ol > li with a
- * separator between items and the current page as plain text with
- * `aria-current="page"`.
+ * Breadcrumb — a navigation trail: nav > ol > li with a separator between
+ * items and the current page as plain text with `aria-current="page"`.
  */
 export const Breadcrumb = ({
   separator = "/",
@@ -98,9 +97,8 @@ export type BreadcrumbLinkProps = HTMLStyledProps<"a">;
 const CurrentPageText = styled("span");
 
 /**
- * The trail's link: the shared `Link` (Chakra's BreadcrumbLink base was its
- * Link base), or a plain span with `aria-current="page"` inside an item
- * marked `isCurrentPage`.
+ * The trail's link: the shared `Link`, or a plain span with
+ * `aria-current="page"` inside an item marked `isCurrentPage`.
  */
 export const BreadcrumbLink = (props: BreadcrumbLinkProps) => {
   const isCurrentPage = useContext(CurrentPageContext);

package/src/Button.recipe.ts

@@ -5,23 +5,22 @@
  */
 import { defineRecipe } from "@pandacss/dev";
 
-// Chakra's transition.property.common, inlined (Panda has no transitionProperty
-// token category). Matches Chakra's Button base transition.
+// The common transition-property list, inlined (Panda has no
+// transitionProperty token category).
 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`/
+ * Button recipe — the family button base + sizes, with the house
+ * borderRadius (`button` = 2rem). 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>.
+ * react-aria-components' data attributes, so these 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
+ * 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 `button.*` and `languageText` semantic tokens).
@@ -68,7 +67,7 @@ export const button = defineRecipe({
       xs: { h: "6", minW: "6", fontSize: "xs", px: "2" },
     },
     variant: {
-      // Chakra's unstyled reset + this app's border-radius removal.
+      // A full reset: the button renders as plain inline content.
       unstyled: {
         bg: "none",
         color: "inherit",
@@ -78,7 +77,7 @@ export const button = defineRecipe({
         p: "0",
         borderRadius: "unset",
       },
-      // Chakra's link layout (no padding/height) + this app's colours.
+      // Link-shaped button: no padding/height, underline on hover.
       link: {
         padding: 0,
         height: "auto",
@@ -115,10 +114,9 @@ export const button = defineRecipe({
         _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.
+      // 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",
@@ -132,21 +130,12 @@ export const button = defineRecipe({
         },
         _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.
+      // The *destructive* outline (text darker than 500 for contrast).
+      // Two other outline shapes are currently restated per call site in
+      // classroom — a neutral outline (1px gray.200, inherited text,
+      // gray.50/gray.100 hover/press) and an on-colour outline (white 2px +
+      // white text over a coloured bar, whiteAlpha hover/press) — worth
+      // considering as variants if a second consumer wants them.
       warning: {
         borderWidth: "2px",
         borderColor: "danger.600",
@@ -155,10 +144,10 @@ export const button = defineRecipe({
         _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
-      // recording UI and destructive actions can diverge - hence danger
-      // tokens here, red.* literals there.
+      // The destructive solid (confirm buttons). Same values as ml-trainer's
+      // `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",