ionbase-ui 0.18.1 → 0.19.0

package/dist/meta/Logo.json

@@ -4,6 +4,55 @@
   "propsType": "LogoProps",
   "description": "The full lockup: mark + wordmark, matching Figma's `Logo-Ionbase`\n(52:21369).\n\nFigma also has a `Property=Name` axis — wordmark only, no mark — but both\nof its variants currently render the placeholder text \"raza\" rather than\n\"IonBase\", in an unbound raw colour. That is leftover debug content, not a\nreal asset, so it is not implemented here. Reproducing it would ship a\nstranger's name into a design system; extending `LogoMark` alone already\ncovers \"no wordmark\" for the cases that are real.",
   "import": "import { Logo } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The full IonBase lockup — mark plus wordmark.",
+  "useWhen": [
+    "the product needs to identify itself: header, sign-in page, empty state, marketing surface"
+  ],
+  "useInstead": [
+    {
+      "when": "space is tight, or a wordmark already appears nearby",
+      "use": "LogoMark"
+    },
+    {
+      "when": "you need any graphic that is not the brand",
+      "use": "Icon"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "the default — a 24px mark, which is what a header bar wants"
+      },
+      "lg": {
+        "use": "a 32px mark — sign-in, splash, or anywhere the brand is the subject"
+      }
+    },
+    "wordmark": {
+      "vector": {
+        "use": "the default and the safe choice — Figma's serif logotype as frozen artwork, immune to font substitution and visually distinct from the UI type"
+      },
+      "text": {
+        "use": "live, selectable Host Grotesk at `text/tertiary` — for surfaces where the name should behave like text (copyable, searchable) rather than like a mark"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the wordmark carries the accessible name, so the mark beside it is not announced twice",
+      "artwork uses `currentColor` rather than Figma's baked hex, so it themes with the rest of the icon layer"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "recolouring the lockup with your own fill",
+      "why": "it inherits `icon/default`; overriding it is how a brand mark ends up failing contrast in one theme"
+    },
+    {
+      "dont": "putting the Logo inside a Link with its own text \"IonBase\"",
+      "why": "the name is announced twice; label the link, not both"
+    }
+  ],
   "stylesheet": "src/styles/logo.css",
   "tokens": [
     "--font-family-sans",

package/dist/meta/LogoMark.json

@@ -4,6 +4,44 @@
   "propsType": "LogoMarkProps",
   "description": "The bare icon glyph, no wordmark — what `Header` actually uses.\n\nColour comes from the `.ion-logo__mark` class (`icon/default`), not the SVG\nitself, so it themes the same way every other icon in the system does.",
   "import": "import { LogoMark } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The bare mark, no wordmark — what Header uses.",
+  "useWhen": [
+    "a wordmark is already visible nearby, or the bar is too narrow for the lockup",
+    "a favicon-scale identity marker inside the product"
+  ],
+  "useInstead": [
+    {
+      "when": "this is the only place the product names itself",
+      "use": "Logo",
+      "why": "a mark alone identifies nothing to someone who has not learned it yet"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "the default, 24px — header bars"
+      },
+      "lg": {
+        "use": "32px — sign-in and other brand-forward surfaces"
+      }
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` when the mark stands alone — it is the only thing naming it"
+    ],
+    "notes": [
+      "Omit `label` when a visible wordmark sits beside it; that text already carries the name."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "`label=\"logo\"`",
+      "do": "`label=\"IonBase\"`",
+      "why": "the name of the brand is the useful announcement; the word \"logo\" is not"
+    }
+  ],
   "stylesheet": "src/styles/logo.css",
   "tokens": [
     "--font-family-sans",

package/dist/meta/Menu.json

@@ -4,6 +4,60 @@
   "propsType": "MenuProps",
   "description": "Menu is the list surface, not a popover.\n\nFigma models the list alone — there is no trigger, anchor or open state in\nthe design — so this renders the surface and nothing else. Positioning it\nagainst a button is the caller's job until Figma has a component that says\nhow. Building a popover here would be inventing design, and it would be the\nhard half to unpick later.\n\n`role=\"menu\"` is deliberately NOT set. A real ARIA menu owes the user\nroving-tabindex arrow navigation, typeahead and focus containment; claiming\nthe role without them is worse for a screen-reader user than an honest list,\nbecause it promises interactions that are not there. When the popover exists,\nthe role comes with it.",
   "import": "import { Menu } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The list surface only — no trigger, no anchor, no open state. Positioning it is the caller's job.",
+  "useWhen": [
+    "rendering a list of actions or options as a surface you have already positioned",
+    "the rows need icons, a selected check, or two lines — more than a native <select> can hold"
+  ],
+  "useInstead": [
+    {
+      "when": "you want a self-contained dropdown with a trigger and open state",
+      "use": "Popover",
+      "why": "Menu is the surface alone; Popover owns the trigger, positioning, focus containment and Escape"
+    },
+    {
+      "when": "one value is picked from a modest list of plain text options",
+      "use": "Select",
+      "why": "the native picker brings keyboard handling, type-ahead and the mobile platform picker for free"
+    },
+    {
+      "when": "it is primary navigation rather than a dropdown",
+      "use": "NavItem"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Menu",
+      "MenuItem"
+    ],
+    "example": "<Menu><MenuItem icon={<Icon as={Copy} />}>Duplicate</MenuItem><MenuItem isSelected>Archive</MenuItem></Menu>"
+  },
+  "slots": {
+    "children": {
+      "accepts": "MenuItem"
+    }
+  },
+  "a11y": {
+    "role": "none — it is a plain <ul>",
+    "guarantees": [
+      "no `role=\"menu\"`, deliberately: a real ARIA menu owes the user roving tabindex, arrow-key navigation and typeahead, and claiming the role without them promises interactions that are not there"
+    ],
+    "notes": [
+      "Each MenuItem is a real <button>, so Tab reaches every row. That is honest, and it is not the same as arrow-key menu navigation.",
+      "The role arrives when the popover that owns it does."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "adding `role=\"menu\"` yourself",
+      "why": "the keyboard behaviour that role promises is not implemented; an honest list is better for a screen-reader user than a lying menu"
+    },
+    {
+      "dont": "using Menu as a dropdown without positioning it",
+      "why": "it renders in flow — it has no anchor logic of its own"
+    }
+  ],
   "stylesheet": "src/styles/menu.css",
   "tokens": [
     "--border-focus",

package/dist/meta/MenuItem.json

@@ -3,6 +3,57 @@
   "source": "src/components/Menu.tsx",
   "propsType": "MenuItemProps",
   "import": "import { MenuItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One row in a Menu. A real <button> inside an <li>, with an optional leading icon and a trailing selected check.",
+  "useWhen": [
+    "a row in a Menu surface"
+  ],
+  "useInstead": [
+    {
+      "when": "it is a top-level navigation destination",
+      "use": "NavItem"
+    },
+    {
+      "when": "it is a standalone action outside a list",
+      "use": "Button"
+    }
+  ],
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "leading icon; omit its `label` — the row's text names it"
+    },
+    "children": {
+      "accepts": "text",
+      "note": "the row label"
+    }
+  },
+  "a11y": {
+    "role": "button",
+    "guarantees": [
+      "`isSelected` sets `aria-pressed`, so the selected state is announced and not only drawn",
+      "the check glyph always occupies its slot, so rows never reflow as the selection moves"
+    ],
+    "requires": [
+      "a text label in `children`"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "using MenuItem outside a Menu",
+      "why": "it renders an <li>, which is only valid inside a list"
+    },
+    {
+      "dont": "an icon-only MenuItem with no children",
+      "why": "the row announces nothing"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/menu.css",
   "tokens": [
     "--border-focus",

package/dist/meta/NavItem.json

@@ -4,6 +4,59 @@
   "propsType": "NavItemProps",
   "description": "Nav Item renders an `<a>` when given `href`, a `<button>` otherwise —\nchosen by what the caller is actually building, the same judgment call\nMenu and Select make. A primary nav bar is links; a nav item with\n`showChevron` that opens a menu (no `href` of its own) is a button.\n\nInteraction state comes from React Aria rather than CSS pseudo-classes,\nmatching Button: `useHover` is pointer-aware so a tap does not stay\n\"hovered\" until the next tap elsewhere, and `useFocusRing` shows the ring\nonly for keyboard navigation. The CSS keeps its own `:hover` /\n`:focus-visible` rules so the stylesheet still works without React.",
   "import": "import { NavItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A primary navigation destination. Renders an <a> when given `href`, a <button> otherwise.",
+  "useWhen": [
+    "building a header nav bar, a sidebar or a section switcher",
+    "an item opens a menu rather than navigating — pass `showChevron` and no `href`"
+  ],
+  "useInstead": [
+    {
+      "when": "the link sits inside body copy or a content block",
+      "use": "Link"
+    },
+    {
+      "when": "it is a row in a dropdown list rather than a top-level destination",
+      "use": "MenuItem"
+    }
+  ],
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "leading icon; omit its `label` — the item's text names it"
+    }
+  },
+  "a11y": {
+    "role": "link when `href` is set, button when it is not",
+    "guarantees": [
+      "hover state comes from React Aria's pointer-aware `useHover`, so a tap does not stay hovered until the next tap elsewhere",
+      "the focus ring shows for keyboard navigation only",
+      "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React"
+    ],
+    "requires": [
+      "an accessible name — `children`, or `aria-label` on an icon-only item"
+    ],
+    "notes": [
+      "NavItem is one item, not the landmark. Wrap the set in a <nav> with its own accessible name."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "`showChevron` on a plain link that navigates",
+      "why": "the chevron promises a menu; nothing opens"
+    },
+    {
+      "dont": "marking the current page with colour only",
+      "do": "`aria-current=\"page\"`",
+      "why": "a screen-reader user is otherwise never told where they are"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/nav-item.css",
   "tokens": [
     "--border-focus",

package/dist/meta/PhoneInput.json

@@ -4,6 +4,66 @@
   "propsType": "PhoneInputProps",
   "description": "PhoneInput — Figma `Input/Phone` (80:372).\n\nA dial-code block butted against an Input, sharing one outline: the block\ncarries the left radii and the control the right, so the seam is square on\nboth sides and reads as a single control. Both keep their full 1px border,\nwhich is what Figma draws — the 2px seam is the two strokes meeting, not an\naccident.\n\nThree sizes, no State axis. Every interaction state is the Input's, reached\nthrough the ordinary props, because Figma composes this from the same `Input`\ninstance rather than redrawing it.\n\nWHAT THIS DELIBERATELY DOES NOT DO\n\nIt does not pick countries. The chevron implies a menu and Figma specifies no\nopen state for it — no list, no flags, no search, no selected state. Country\ndata and the picker are application concerns with real editorial weight (which\nterritories, which names, which order), and inventing them here would be\ndesigning rather than implementing.\n\nSo the trigger is a real `<button>` with an accessible name, and\n`countryButtonProps` is how you wire it to a `Menu`, a popover or your own\nlistbox — including the `aria-haspopup` and `aria-expanded` that only the\nthing owning the popup can set honestly.",
   "import": "import { PhoneInput } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A dial-code block butted against an Input, sharing one outline. It does not pick countries.",
+  "useWhen": [
+    "collecting a phone number where the country calling code matters"
+  ],
+  "useInstead": [
+    {
+      "when": "the number is free-form and the code does not matter",
+      "use": "Input"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "prominent single-field forms"
+      }
+    }
+  },
+  "slots": {
+    "trailingIcon": {
+      "accepts": "Icon",
+      "note": "passed through to the Input"
+    },
+    "countryButtonProps": {
+      "accepts": "button props",
+      "note": "how a country picker is attached — spread your trigger's props here, including the `aria-haspopup` and `aria-expanded` only the thing owning the popup can set honestly"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the dial-code trigger is a real <button> with an accessible name",
+      "every interaction state is the Input's, reached through the ordinary Input props"
+    ],
+    "requires": [
+      "`label`, or `aria-label` when no visible label is rendered",
+      "`countryLabel` if you change the default — the trigger shows only `+1`, which names a value rather than an action"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "expecting the chevron to open a country list",
+      "why": "the picker is deliberately not implemented — country data and ordering are editorial application decisions, and Figma specifies no open state. Wire your own through `countryButtonProps`"
+    },
+    {
+      "dont": "wrapping it in your own bordered container",
+      "why": "the block and the control already share one outline; a second border reads as two controls"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/phone-input.css",
   "tokens": [
     "--border-default",

package/dist/meta/Popover.json

@@ -4,6 +4,98 @@
   "propsType": "PopoverProps",
   "description": "Popover — Figma `Popover` (825:1853).\n\nSITS BETWEEN TOOLTIP AND MODAL. A tooltip is a hint that cannot hold\nfocusable content; a modal is a task that takes over the page. A popover\nholds interactive content but stays attached to the control that opened it.\n\n`usePopover` contains focus, closes on Escape or an outside click, and hides\nthe rest of the page from assistive tech while open — the same guarantees\nModal gives. What differs is the framing, and it is deliberate: no visible\nscrim, anchored to its trigger, and `surface/raised` rather than Modal's\n`surface/overlay`. It reads as attached to the page rather than replacing it.",
   "import": "import { Popover } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "An anchored panel that holds interactive content. Sits between Tooltip and Modal.",
+  "useWhen": [
+    "the content is interactive — a form, a filter, a list of actions — but should stay attached to the control that opened it",
+    "the surrounding page should stay visible and in context"
+  ],
+  "useInstead": [
+    {
+      "when": "the content is a short hint with nothing focusable in it",
+      "use": "Tooltip",
+      "why": "a tooltip cannot be focused or scrolled and closes when the pointer leaves"
+    },
+    {
+      "when": "the task takes over the page or must be completed before anything else",
+      "use": "Modal"
+    },
+    {
+      "when": "you only need the list surface and will position it yourself",
+      "use": "Menu"
+    }
+  ],
+  "variants": {
+    "placement": {
+      "top": {
+        "use": "above the trigger"
+      },
+      "bottom": {
+        "use": "below the trigger — the usual choice for a control in a header"
+      },
+      "left": {
+        "use": "to the left of the trigger"
+      },
+      "right": {
+        "use": "to the right of the trigger"
+      }
+    },
+    "size": {
+      "sm": {
+        "use": "a couple of actions or one short field"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a small form or a filter panel"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "Button",
+      "note": "the trigger. Must forward both a ref and DOM props — every component in this library does"
+    },
+    "content": {
+      "accepts": "any"
+    },
+    "title": {
+      "accepts": "text",
+      "note": "also gives the dialog its accessible name"
+    },
+    "footer": {
+      "accepts": "Button",
+      "note": "action row, right-aligned"
+    }
+  },
+  "a11y": {
+    "role": "dialog",
+    "guarantees": [
+      "focus is contained while open, Escape and outside clicks close it, and the rest of the page is hidden from assistive tech",
+      "`placement` is a preference, not a guarantee — it flips when there is no room, and the arrow follows"
+    ],
+    "requires": [
+      "`title`, or `aria-label` on the popover — a dialog with no name announces nothing about what opened"
+    ],
+    "notes": [
+      "`placement` names where the POPOVER sits, not where the arrow points."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a function-component trigger that drops its ref",
+      "why": "it renders, but the popover has nothing to position against"
+    },
+    {
+      "dont": "using a Popover where a Modal belongs",
+      "why": "a popover closes on an outside click; a task that must be finished should not be dismissible by a stray click"
+    },
+    {
+      "dont": "nesting a Popover inside another Popover",
+      "why": "two overlapping focus containments, and dismissing the outer one takes the inner one with it"
+    }
+  ],
   "stylesheet": "src/styles/popover.css",
   "tokens": [
     "--border-subtle",

package/dist/meta/Radio.json

@@ -3,6 +3,83 @@
   "source": "src/components/Radio.tsx",
   "propsType": "RadioProps",
   "import": "import { Radio } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One option inside a RadioGroup. Meaningless on its own — the group owns the name and the selected value.",
+  "useWhen": [
+    "a child of RadioGroup"
+  ],
+  "useInstead": [
+    {
+      "when": "the user may pick more than one",
+      "use": "Checkbox"
+    },
+    {
+      "when": "there are more than about five options",
+      "use": "Select",
+      "why": "a long radio list costs vertical space no one reads"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "touch targets and prominent choices"
+      }
+    },
+    "intent": {
+      "brand": {
+        "use": "the default"
+      },
+      "neutral": {
+        "use": "a choice with no positive reading — sort order, display mode"
+      },
+      "danger": {
+        "use": "selecting a destructive option"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the option's visible label"
+    }
+  },
+  "a11y": {
+    "role": "radio",
+    "guarantees": [
+      "`name` and the selected value come from the group's context, so no Radio has to repeat them",
+      "`isDisabled` falls back to the group's"
+    ],
+    "requires": [
+      "a `value` unique within the group",
+      "a text label in `children`"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a Radio outside a RadioGroup",
+      "why": "it has no name and no siblings, so it can be selected but never unselected"
+    },
+    {
+      "dont": "wiring `checked`/`onChange` on each Radio",
+      "why": "the group owns selection; per-option wiring is what the context exists to remove"
+    },
+    {
+      "dont": "a group of one radio",
+      "why": "a single radio cannot be cleared once chosen — that is a Checkbox"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/radio.css",
   "tokens": [
     "--border-disabled",

package/dist/meta/RadioGroup.json

@@ -4,6 +4,90 @@
   "propsType": "RadioGroupProps",
   "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.",
   "import": "import { RadioGroup } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value.",
+  "useWhen": [
+    "exactly one choice from a small set, all worth showing at once",
+    "the options need explaining — each one can carry its own label text"
+  ],
+  "useInstead": [
+    {
+      "when": "the list is long, or space is tight",
+      "use": "Select"
+    },
+    {
+      "when": "more than one may be picked",
+      "use": "Checkbox"
+    },
+    {
+      "when": "there are exactly two states and the change is immediate",
+      "use": "Toggle"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "touch targets and prominent choices"
+      }
+    },
+    "intent": {
+      "brand": {
+        "use": "the default"
+      },
+      "neutral": {
+        "use": "a choice with no positive reading — sort order, display mode"
+      },
+      "danger": {
+        "use": "a set where the options are destructive"
+      }
+    }
+  },
+  "slots": {
+    "label": {
+      "accepts": "text",
+      "note": "renders as the <legend> — the question the options answer"
+    },
+    "children": {
+      "accepts": "Radio"
+    }
+  },
+  "a11y": {
+    "role": "group, from <fieldset> and <legend>",
+    "guarantees": [
+      "a real fieldset rather than `role=\"radiogroup\"`: both announce correctly, but the fieldset also groups the inputs for form submission and native validation",
+      "`name` is generated when omitted, so two groups on one page never collide",
+      "`isDisabled` cascades to every Radio that has not set its own"
+    ],
+    "requires": [
+      "`label`, or `aria-label` when the question is already visible elsewhere"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "an unlabelled group",
+      "why": "the options are announced with no question attached"
+    },
+    {
+      "dont": "passing both `value` and `defaultValue`",
+      "why": "controlled and uncontrolled at once; the controlled value wins and `defaultValue` silently does nothing"
+    },
+    {
+      "dont": "no option selected by default with no \"none\" option",
+      "why": "a radio group cannot be returned to empty once touched"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/radio.css",
   "tokens": [
     "--border-disabled",

package/dist/meta/ScrollProgress.json

@@ -4,6 +4,47 @@
   "propsType": "ScrollProgressProps",
   "description": "The compact rail is the disclosure trigger. It is a real `<button>`, so a\nkeyboard user reaches it by Tab and opens it the same way as any button —\nEnter or Space — no `:focus-within` trick required; a mouse user can also\njust hover it. Built as a WAI-ARIA Disclosure (`aria-expanded` +\n`aria-controls`) rather than a menu: see the CSS header for why\n`role=\"menu\"` is deliberately not used here.\n\nCloses on outside pointerdown and on Escape — the minimum a disclosure\nneeds to not trap the page once opened, not a full popover/focus-trap\nimplementation.",
   "import": "import { ScrollProgress } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A compact progress rail that expands into a section list. A disclosure, not a menu — and it computes nothing itself.",
+  "useWhen": [
+    "a long document or page needs an in-page section index with reading progress",
+    "the caller already knows the scroll fraction and the active section"
+  ],
+  "useInstead": [
+    {
+      "when": "the sections are peer views rather than positions in one document",
+      "use": "Tabs"
+    },
+    {
+      "when": "it is site navigation rather than in-page position",
+      "use": "NavItem"
+    }
+  ],
+  "a11y": {
+    "role": "disclosure — a real <button> with aria-expanded and aria-controls",
+    "guarantees": [
+      "the rail is reachable by Tab and opens with Enter or Space, not just hover",
+      "closes on outside pointerdown and on Escape"
+    ],
+    "requires": [
+      "`progress` as 0–100 and `activeId` — the component has no opinion on where they come from",
+      "handling `onSelect` yourself: it reports the choice and does not scroll anywhere"
+    ],
+    "notes": [
+      "Deliberately not `role=\"menu\"` — see the stylesheet header. It is a disclosure with a list inside it, not a menu with roving focus.",
+      "Not a focus trap: it is the minimum a disclosure needs to not trap the page once opened."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "expecting it to scroll the page when a section is chosen",
+      "why": "it reports the choice, matching Menu — what \"select this section\" means is the page's decision"
+    },
+    {
+      "dont": "deriving `progress` from a scroll listener without throttling",
+      "why": "this re-renders the rail on every scroll frame"
+    }
+  ],
   "stylesheet": "src/styles/scroll-progress.css",
   "tokens": [
     "--border-default",