@microbit/ui 0.1.0-alpha.21 → 0.1.0-alpha.23

package/src/Button.tsx

@@ -16,11 +16,11 @@ import { buttonIcon } from "./button-icon";
 import { uiMessage } from "./messages";
 import { Spinner } from "./Spinner";
 
-// Chakra's ButtonSpinner: a 1em spinner centred over the hidden label. Out of
-// flow, so the label alone sets the button's size; the recipe's base
-// `position: relative` is what it anchors to. Its own component so useIntl runs
-// only while a button is actually loading — a bare Button must keep working
-// without an IntlProvider (test renders commonly lack one).
+// A 1em spinner centred over the hidden label. Out of flow, so the label alone
+// sets the button's size; the recipe's base `position: relative` is what it
+// anchors to. Its own component so useIntl runs only while a button is
+// actually loading — a bare Button must keep working without an IntlProvider
+// (test renders commonly lack one).
 const ButtonSpinner = () => {
   const intl = useIntl();
   return (
@@ -47,16 +47,14 @@ export interface ButtonProps
   /** Per-instance style overrides, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
-  /** Icon rendered before the label, matching Chakra's `leftIcon`. */
+  /** Icon rendered before the label. */
   leftIcon?: ReactNode;
-  /** Icon rendered after the label, matching Chakra's `rightIcon`. */
+  /** Icon rendered after the label. */
   rightIcon?: ReactNode;
   /**
-   * Show a spinner in place of the label and disable interaction, matching
-   * Chakra's `isLoading`: the label stays in the layout but invisible, so the
-   * button keeps its size, and the dimmed disabled look applies. Chakra's
-   * `loadingText`/`spinnerPlacement` (a visible label beside the spinner) are
-   * unported — no app in the family used them.
+   * Show a spinner in place of the label and disable interaction: the label
+   * stays in the layout but invisible, so the button keeps its size, and the
+   * dimmed disabled look applies.
    */
   isLoading?: boolean;
   children?: ReactNode;

package/src/ButtonGroup.tsx

@@ -9,8 +9,8 @@ import { SystemStyleObject } from "styled-system/types";
 
 export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
   /**
-   * Square the inner radii so adjacent buttons form one control (Chakra's
-   * `isAttached`). Otherwise buttons get a small gap.
+   * Square the inner radii so adjacent buttons form one control. Otherwise
+   * buttons get a small gap.
    */
   isAttached?: boolean;
   /** Per-instance style overrides. */
@@ -20,7 +20,7 @@ export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
 
 /**
  * ButtonGroup — lays out related buttons in a row. Works with any button
- * elements (shared-ui or native). Replaces Chakra's ButtonGroup.
+ * elements (shared-ui or native).
  */
 export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
   function ButtonGroup({ isAttached, css: cssProp, className, ...rest }, ref) {
@@ -33,10 +33,10 @@ export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
             alignItems: "center",
             // Buttons are position: relative, so without this an attached
             // sibling paints over the focused button's focus-ring shadow.
-            // Chakra raised on :focus, but with the attached -1px overlap a
-            // raised button also paints over a seam its neighbour draws
-            // (e.g. a solid split button's white borderLeft), so raise only
-            // when the ring is actually shown.
+            // Raise only on :focus-visible, when the ring is actually shown:
+            // with the attached -1px overlap a raised button also paints over
+            // a seam its neighbour draws (e.g. a solid split button's white
+            // borderLeft).
             "& > *": { _focusVisible: { zIndex: 1 } },
           }),
           isAttached
@@ -45,8 +45,9 @@ export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
                 // :first-child/:last-child, not :first-of-type: attached
                 // groups can mix element types (e.g. select + button), and
                 // -of-type matches per element type.
-                // marginEnd -1px (Chakra parity): overlaps adjacent borders
-                // so two 1px inner edges read as a single 1px seam.
+                // marginEnd -1px overlaps adjacent borders so two 1px inner
+                // edges read as a single 1px seam. That assumes 1px borders;
+                // the bordered variants are 2px (microbit-foundation/ui#22).
                 "& > *:first-child:not(:last-child)": {
                   borderEndRadius: 0,
                   marginEnd: "-1px",

package/src/Card.recipe.ts

@@ -6,8 +6,7 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Card slot recipe — Chakra's Card at its default md size (light mode), with
- * the `elevated` (default) and `outline` variants this app uses.
+ * Card slot recipe, with `elevated` (default) and `outline` variants.
  *
  * Registered in the base preset (base-preset.ts); `variant` is
  * forwarded as a runtime prop so the variants are generated via `staticCss`.

package/src/Card.tsx

@@ -16,7 +16,8 @@ export interface CardProps
 }
 
 /**
- * Card — Chakra's <Card> equivalent (md size). Place a CardBody inside.
+ * Card — a container styled with the `card` config recipe (md size). Place a
+ * CardBody inside.
  */
 export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
   { variant, css: cssProp, className, ...rest },

package/src/Checkbox.recipe.ts

@@ -6,10 +6,9 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Checkbox slot recipe — Chakra's checkbox with the default blue colorScheme
- * (light mode) and its sm/md/lg size scale. The control's
- * `borderColor: inherit` picks up a `borderColor` set on the root, matching
- * Chakra's convention for tinting the box from the call site.
+ * Checkbox slot recipe with an sm/md/lg size scale. The control's
+ * `borderColor: inherit` picks up a `borderColor` set on the root, so call
+ * sites can tint the box from there.
  *
  * State styling keys off data attributes stamped on the control by the
  * shared-ui Checkbox (react-aria provides the state via render props).
@@ -56,8 +55,8 @@ export const checkbox = defineSlotRecipe({
           borderColor: "controlCheckedHoverBg",
         },
       },
-      // Chakra's disabled greys; the selected block restates _hover so the
-      // widened native-:hover condition can't re-tint a disabled control.
+      // Disabled greys; the selected block restates _hover so the widened
+      // native-:hover condition can't re-tint a disabled control.
       "&[data-disabled]": {
         bg: "gray.100",
         borderColor: "gray.100",
@@ -83,9 +82,8 @@ export const checkbox = defineSlotRecipe({
     },
   },
   variants: {
-    // Chakra's Checkbox size scale. The icon dimensions are Chakra's
-    // 1.2em-wide check glyph at each size's icon fontSize (3xs/2xs/2xs),
-    // resolved to rem.
+    // The icon dimensions are the 1.2em-wide check glyph at each size's icon
+    // fontSize (3xs/2xs/2xs), resolved to rem.
     size: {
       sm: {
         control: { width: "3", height: "3" },

package/src/Checkbox.tsx

@@ -53,9 +53,8 @@ export interface CheckboxProps
 }
 
 /**
- * Checkbox — react-aria-components <Checkbox> styled like Chakra's checkbox.
- * Children render as the label; wrap them in a visually-hidden span for
- * icon-less checkboxes.
+ * Checkbox — a styled react-aria-components <Checkbox>. Children render as
+ * the label; wrap them in a visually-hidden span for icon-less checkboxes.
  */
 export const Checkbox = ({
   size,

package/src/CheckboxGroup.tsx

@@ -16,8 +16,8 @@ export interface CheckboxGroupProps
   extends Omit<RACCheckboxGroupProps, "className" | "style">,
     FieldSupportProps {
   /**
-   * Visible label for the group (Chakra's FormLabel above it). Use
-   * `aria-label` instead where the design has none.
+   * Visible label for the group. Use `aria-label` instead where the design
+   * has none.
    */
   label?: ReactNode;
   /** Label style overrides. */
@@ -30,11 +30,9 @@ export interface CheckboxGroupProps
 /**
  * CheckboxGroup — react-aria-components <CheckboxGroup> for a set of
  * Checkboxes sharing one value array (each Checkbox's `value` marks its
- * entry). Beyond the optional field chrome (label/helperText/errorMessage —
- * Chakra's FormControl parts) it carries no styling of its own: compose with
- * Stack for layout, as RadioGroup does. Chakra's CheckboxGroup was a bare
- * context provider, so ported call sites gain the chrome rather than
- * restating it around the group.
+ * entry). Beyond the optional field chrome (label/helperText/errorMessage)
+ * it carries no styling of its own: compose with Stack for layout, as
+ * RadioGroup does.
  */
 export const CheckboxGroup = ({
   label,

package/src/CloseButton.tsx

@@ -10,7 +10,7 @@ import { CloseIcon } from "./CloseIcon";
 
 export interface CloseButtonProps
   extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className"> {
-  /** Chakra CloseButton sizes: sm 24px box, md 32px (default). */
+  /** sm is a 24px box, md 32px (default). */
   size?: "sm" | "md";
   /**
    * Grow the touch target 8px beyond the visible button on every side via an
@@ -24,7 +24,7 @@ export interface CloseButtonProps
 }
 
 /**
- * CloseButton — Chakra's standalone X button. A plain button (not react-aria)
+ * CloseButton — a standalone X button. A plain button (not react-aria)
  * so call sites can extend the hit area with pseudo-elements, which
  * react-aria's press bounding-rect check would defeat.
  */

package/src/CloseIcon.tsx

@@ -12,10 +12,12 @@ export interface CloseIconProps {
 }
 
 /**
- * CloseIcon — the "✕" glyph used on close buttons (dialogs, toasts). This is
- * Chakra's exact CloseButton path so the visual matches; sized to `1em` and
- * `fill: currentColor` like the other icons. Reused wherever a close control
- * is needed.
+ * CloseIcon — the "✕" glyph used on close buttons (dialogs, toasts). Sized to
+ * `1em` and `fill: currentColor` like the other icons. Reused wherever a
+ * close control is needed.
+ *
+ * The path is Chakra UI's CloseButton icon, inlined for visual parity with
+ * the apps' original look (see the notice in LICENSE.md).
  */
 export const CloseIcon = ({ css: cssProp, className }: CloseIconProps) => (
   <svg

package/src/Code.tsx

@@ -6,7 +6,7 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Code — inline code chip matching Chakra's <Code> (gray subtle, light mode).
+ * Code — an inline code chip (subtle grey, light mode).
  */
 export const Code = styled("code", {
   base: {

package/src/Collapse.tsx

@@ -15,13 +15,13 @@ import { css, cx } from "styled-system/css";
 import { SystemStyleObject } from "styled-system/types";
 
 export interface CollapseProps {
-  /** Expanded when true (Chakra's `in`). */
+  /** Expanded when true. */
   isOpen: boolean;
-  /** Height when collapsed (Chakra's `startingHeight`). */
+  /** Height when collapsed. */
   startingHeight?: number | string;
   /**
-   * Height when expanded (Chakra's `endingHeight`; defaults to the measured
-   * content height, tracked with a ResizeObserver so nested expansion works).
+   * Height when expanded (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. */
@@ -36,15 +36,14 @@ 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.
+ * Collapse — an expand/collapse transition: 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.
+ * 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,
@@ -155,8 +154,8 @@ export const Collapse = ({
         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).
+        // and tab order (kept visible while animating so the exit
+        // transition shows).
         visibility:
           displayOpen || animating || !hideWhenCollapsed ? undefined : "hidden",
         ...style,

package/src/Divider.tsx

@@ -59,10 +59,10 @@ const StyledDivider = styled("hr", {
 export interface DividerProps extends ComponentProps<typeof StyledDivider> {}
 
 /**
- * Divider — a hairline rule matching Chakra's <Divider> (60% opacity; set
- * `borderColor` to tint, `thickness="thick"` for a 2px rule).
+ * Divider — a hairline rule (60% opacity; set `borderColor` to tint,
+ * `thickness="thick"` for a 2px rule).
  * `orientation="vertical"` needs a height from the layout, e.g. a stretched
- * flex row (Chakra's vertical divider likewise relied on `height: 100%`).
+ * flex row.
  *
  * Decorative by default: hidden from assistive tech, since a visual rule
  * between sections is noise as an announced separator (and every call site

package/src/Drawer.recipe.ts

@@ -6,12 +6,11 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Drawer slot recipe — Chakra's default Drawer parts (light mode) at its
- * default `xs` size (20rem panel). Consumed by the shared-ui Drawer, which maps
- * the slots onto react-aria-components' ModalOverlay / Modal / Dialog.
+ * Drawer slot recipe — a 20rem (`xs`) side panel. Consumed by the shared-ui
+ * Drawer, which maps the slots onto react-aria-components' ModalOverlay /
+ * Modal / Dialog.
  *
- * The enter transition approximates Chakra's slide spring (damping 25,
- * stiffness 180) with a decelerating tween; exit matches its 0.15s ease-in-out
+ * The enter transition is a decelerating tween; the exit a 0.15s ease-in-out
  * tween.
  *
  * Registered in the base preset (base-preset.ts); `placement` is

package/src/Drawer.tsx

@@ -24,7 +24,7 @@ export interface DrawerProps extends DrawerVariantProps {
   onClose: () => void;
   /**
    * Called after the drawer has fully closed (exit transition done and the
-   * drawer removed). Matches Chakra's `onCloseComplete`.
+   * drawer removed).
    */
   onCloseComplete?: () => void;
   /** Allow closing by clicking the backdrop / pressing Escape (default true). */
@@ -39,9 +39,8 @@ export interface DrawerProps extends DrawerVariantProps {
 }
 
 /**
- * Drawer — a focus-trapping panel that slides in from the side. Collapses
- * Chakra's Drawer/DrawerOverlay/DrawerContent into a single shell; place
- * DrawerHeader and DrawerBody inside.
+ * Drawer — a focus-trapping panel that slides in from the side, in a single
+ * shell; place DrawerHeader and DrawerBody inside.
  */
 export const Drawer = ({
   isOpen,

package/src/Fade.tsx

@@ -10,12 +10,9 @@ import { SystemStyleObject } from "styled-system/types";
 export interface FadeProps {
   /** Visible when true; faded out (but mounted) when false. */
   isOpen: boolean;
-  /**
-   * Fade-in time in seconds (Chakra's `transition.enter.duration`).
-   * Default 0.2, Chakra's.
-   */
+  /** Fade-in time in seconds. Default 0.2. */
   enterDuration?: number;
-  /** Fade-out time in seconds (Chakra's `transition.exit.duration`). */
+  /** Fade-out time in seconds. Default 0.2. */
   exitDuration?: number;
   css?: SystemStyleObject;
   className?: string;
@@ -23,8 +20,8 @@ export interface FadeProps {
 }
 
 /**
- * Fade — Chakra's Fade transition as a CSS opacity transition (see Slide for
- * the pattern). Content stays mounted throughout.
+ * Fade — a CSS opacity transition (see Slide for the pattern). Content stays
+ * mounted throughout.
  */
 export const Fade = ({
   isOpen,
@@ -37,9 +34,8 @@ export const Fade = ({
   <div
     data-open={isOpen ? "" : undefined}
     // Runtime values, so an inline custom property rather than the css()
-    // object (gotcha #9: a non-literal duration would extract to nothing).
-    // The var switches in the same commit as the opacity, so the transition
-    // picks up the direction's own duration.
+    // object. The var switches in the same commit as the opacity, so the
+    // transition picks up the direction's own duration.
     style={
       {
         "--fade-duration": `${isOpen ? enterDuration : exitDuration}s`,

package/src/Field.recipe.ts

@@ -6,9 +6,9 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Field slot recipe — Chakra's FormControl parts (FormLabel/FormHelperText/
- * FormErrorMessage, light mode), mapped onto react-aria-components'
- * Label/Text/FieldError by `FieldLabel` and `FieldSupport`. Every labelled
+ * Field slot recipe — the label/helper/error chrome, mapped onto
+ * react-aria-components' Label/Text/FieldError by `FieldLabel` and
+ * `FieldSupport`. Every labelled
  * field in the library draws its chrome from here, including Select and
  * ComboBox, whose own recipe styles only the dropdown pair; the input itself is
  * styled by the `input` recipe (Input.recipe.ts).
@@ -35,10 +35,9 @@ export const field = defineSlotRecipe({
     label: {
       display: "block",
       fontSize: "md",
-      // Deliberately not Chakra FormLabel's `medium`: no font in the family's
-      // stack has a 500 face, so the two were pixel-identical on macOS and
-      // Windows, and the only call sites that cared overrode to `normal`
-      // (settings rows). See the playbook's expected behavioural deltas.
+      // Deliberately `normal`, not `medium`: no font in the family's stack
+      // has a 500 face (the two render identically on macOS and Windows),
+      // and the call sites that cared (settings rows) want `normal`.
       fontWeight: "normal",
       marginEnd: "3",
       mb: "2",
@@ -46,7 +45,7 @@ export const field = defineSlotRecipe({
       transitionDuration: "normal",
       // RAC stamps `data-disabled` on the field root and on the control, never
       // on the label, so an `&[data-disabled]` rule here matches nothing — it
-      // has to come down from the root (gotcha #45). Direct child rather than a
+      // has to come down from the root. Direct child rather than a
       // descendant selector, as the select recipe's invalid rule: an app's own
       // disabled form wrapper must not be able to dim every label inside it.
       "[data-disabled] > &": { opacity: 0.4 },
@@ -58,7 +57,7 @@ export const field = defineSlotRecipe({
     helperText: {
       // RAC's Text renders a span, and RadioGroup/CheckboxGroup roots are not
       // flex containers to blockify it, where an inline box would drop the
-      // margin below (gotcha #44).
+      // margin below.
       display: "block",
       mt: "2",
       fontSize: "sm",
@@ -77,9 +76,7 @@ export const field = defineSlotRecipe({
   variants: {
     // The label follows its control's size (the control itself is sized by
     // the `input`/`select` recipes), so one `size` prop scales the whole row.
-    // Chakra's FormLabel never scaled — a deliberate delta; see the playbook's
-    // field-chrome notes. Helper and error text stay `sm` at every size, as
-    // Chakra's did.
+    // Helper and error text stay `sm` at every size.
     size: {
       lg: { label: { fontSize: "lg" } },
       md: { label: { fontSize: "md" } },

package/src/Field.tsx

@@ -15,15 +15,15 @@ import { field, FieldVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 
 /**
- * The label/helper/error chrome every labelled form field shares — Chakra's
- * FormControl parts, generalised out of TextField so Select, ComboBox,
- * NumberField, RadioGroup and CheckboxGroup carry the same props
- * (data-microbit-org's forms attach helper and error text to all of these).
+ * The helper/error chrome every labelled form field shares — TextField,
+ * Select, ComboBox, NumberField, RadioGroup and CheckboxGroup carry the same
+ * props (data-microbit-org's forms attach helper and error text to all of
+ * these).
  */
 export interface FieldSupportProps {
-  /** Help text below the field (Chakra's FormHelperText). */
+  /** Help text below the field. */
   helperText?: ReactNode;
-  /** Shown below the field when invalid (Chakra's FormErrorMessage). */
+  /** Shown below the field when invalid. */
   errorMessage?: ReactNode;
   /** Per-instance style overrides for the helper text. */
   helperTextCss?: SystemStyleObject;
@@ -87,8 +87,8 @@ interface FieldTextProps extends HTMLAttributes<HTMLDivElement> {
 }
 
 /**
- * Context-free helper text (Chakra's FormHelperText) for a control react-aria
- * isn't wiring — a native select or a masked input. Inside a RAC field
+ * Context-free helper text for a control react-aria isn't wiring — a native
+ * select or a masked input. Inside a RAC field
  * container use `FieldSupport`, which wires `aria-describedby` and validation
  * for free; here the caller owns that wiring: give this an `id` and reference
  * it from the control's `aria-describedby` (as `NativeSelectField` does).
@@ -111,8 +111,8 @@ export const FieldHelperText = ({
 );
 
 /**
- * Context-free error message (Chakra's FormErrorMessage), the counterpart to
- * `FieldHelperText` — see its note on the wiring the caller owns. RAC's
+ * Context-free error message, the counterpart to `FieldHelperText` — see its
+ * note on the wiring the caller owns. RAC's
  * `FieldError` renders only while its field is invalid; here that decision is
  * the caller's too: render it conditionally.
  */
@@ -134,9 +134,9 @@ export const FieldErrorMessage = ({
 );
 
 /**
- * The required-field asterisk (Chakra's FormLabel indicator). Render inside
- * the field's label when `isRequired`; aria-hidden because react-aria already
- * announces requiredness from the input itself.
+ * The required-field asterisk. Render inside the field's label when
+ * `isRequired`; aria-hidden because react-aria already announces requiredness
+ * from the input itself.
  */
 export const FieldRequiredIndicator = () => (
   <span aria-hidden className={field().requiredIndicator}>
@@ -158,11 +158,9 @@ export interface FieldLabelProps
 }
 
 /**
- * A field's visible label (Chakra's FormLabel), asterisk included. Every
- * labelled field in the library renders its label through this, so the `field`
- * recipe is the single answer to what a label looks like — Select and ComboBox
- * previously carried a near-identical `label` slot on the `select` recipe,
- * which is how the two drifted.
+ * A field's visible label, asterisk included. Every labelled field in the
+ * library renders its label through this, so the `field` recipe is the single
+ * answer to what a label looks like.
  *
  * Also exported for app-side composites: inside a RAC field container the
  * association is automatic, and outside one (a masked or native input) pass

package/src/GridList.recipe.ts

@@ -11,8 +11,7 @@ import { defineSlotRecipe } from "@pandacss/dev";
  * a listbox: the roving tab index moves through rows, and the controls inside
  * a row are reachable without leaving it).
  *
- * Chakra had no equivalent, so there is no Chakra look to match: the greys
- * here are the family's neutral list styling, and an app with a strong
+ * The greys here are the family's neutral list styling; an app with a strong
  * selection colour restates them (classroom's roster does).
  *
  * Registered in the base preset (base-preset.ts), which also has the

package/src/Heading.recipe.ts

@@ -6,7 +6,7 @@
 import { defineRecipe } from "@pandacss/dev";
 
 /**
- * Heading recipe — Chakra's default Heading base + responsive sizes.
+ * Heading recipe — a bold heading-font base + responsive sizes.
  * A config recipe for the same reasons as `button` (see Button.recipe.ts);
  * the `marketing` variant is token-driven via the `display` font, so brands
  * only override tokens.
@@ -50,10 +50,10 @@ export const heading = defineRecipe({
       //
       // `fontSize` goes through a doubled selector because `size` sets it too,
       // responsively. Source order can't settle that: Panda hoists media
-      // queries below the base rules (gotcha #31) and emits variant rules in
-      // the order it meets them, so which of the two wins would depend on the
-      // breakpoint and on what other call sites exist. Two classes beat one at
-      // every width instead.
+      // queries below the base rules and emits variant rules in the order it
+      // meets them, so which of the two wins would depend on the breakpoint
+      // and on what other call sites exist. Two classes beat one at every
+      // width instead.
       label: {
         "&&": { fontSize: "4xl" },
         color: "headingAccent",

package/src/Heading.tsx

@@ -7,8 +7,8 @@ import { styled } from "styled-system/jsx";
 import { heading } from "styled-system/recipes";
 
 /**
- * Heading — Chakra's <Heading> equivalent, backed by the `heading` config
- * recipe (so the private preset can add brand variants). Defaults to an <h2>;
- * pass `as` to change the element and `size` to pick the type scale.
+ * Heading — a heading backed by the `heading` config recipe (so the private
+ * preset can add brand variants). Defaults to an <h2>; pass `as` to change
+ * the element and `size` to pick the type scale.
  */
 export const Heading = styled("h2", heading);

package/src/Icon.tsx

@@ -11,8 +11,7 @@ import { SystemStyleObject } from "styled-system/types";
  * Any component that renders an `<svg>` from svg props. Deliberately no
  * narrower than the props `Icon` actually passes, so it accepts both
  * react-icons' `IconType` and svgr components (`import X from "./x.svg?react"`,
- * which the apps use for their custom-path icons — Chakra's `<Icon as={…}>`
- * took either).
+ * which the apps use for their custom-path icons).
  */
 export type IconComponent = ComponentType<
   Pick<
@@ -32,10 +31,9 @@ export interface IconProps {
 }
 
 /**
- * Icon — renders a react-icons glyph inline at `1em`, matching Chakra's <Icon>
- * base styles. `fill: currentColor` means the glyph follows the surrounding
- * text colour (set `css={{ color: ... }}` to override), so it inherits colour
- * like Chakra's icons rather than defaulting to black.
+ * Icon — renders a react-icons glyph inline at `1em`. `fill: currentColor`
+ * means the glyph follows the surrounding text colour rather than defaulting
+ * to black (set `css={{ color: ... }}` to override).
  *
  * Unlabelled icons are treated as decorative and hidden from assistive tech;
  * a labelled icon gets `role="img"` (a bare svg aria-label is unreliably
@@ -57,11 +55,9 @@ export const Icon = ({
         lineHeight: "1em",
         flexShrink: 0,
         fill: "currentColor",
-        // Chakra's Icon set this on the element itself, and an inline-block
-        // icon sits ~3px off without it. Panda's preflight happens to set it
-        // on every svg, which hid the omission in apps that had already
-        // flipped — classroom measured the difference at its kill-switch,
-        // where the preflight arrived and moved every icon back.
+        // Set on the element itself: an inline-block icon sits ~3px off
+        // without it. Don't rely on Panda's preflight happening to set it on
+        // every svg.
         verticalAlign: "middle",
         ...cssProp,
       }),

package/src/IconButton.tsx

@@ -11,7 +11,7 @@ export interface IconButtonProps
   /** Icon-only buttons have no visible label, so this is required. */
   "aria-label": string;
   /**
-   * Circular rather than the recipe's border-radius (Chakra's `isRound`).
+   * Circular rather than the recipe's border-radius.
    * Usually a visual no-op here: the 2rem `button` radius already renders
    * square icon buttons as circles. Kept for ported call sites and for
    * variants/overrides with a smaller radius (e.g. `unstyled`).

package/src/Image.tsx

@@ -5,7 +5,7 @@
  */
 import { styled } from "styled-system/jsx";
 
-/** Image — an <img> accepting Panda style props. Replaces Chakra's <Image>. */
+/** Image — an <img> accepting Panda style props. */
 export const Image = styled("img", {
   base: { maxWidth: "100%" },
 });