ionbase-ui 0.18.1 → 0.20.0

package/dist/meta/Avatar.json

@@ -4,6 +4,72 @@
   "propsType": "AvatarProps",
   "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.",
   "import": "import { Avatar } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A person or entity marker. Content is chosen by precedence — image, then initials, then icon — not by a type prop.",
+  "useWhen": [
+    "identifying who owns, authored or is assigned to something",
+    "a table cell, menu row or header needs a compact identity marker beside a name"
+  ],
+  "useInstead": [
+    {
+      "when": "the thing being marked is a status, count or category rather than a person",
+      "use": "Badge"
+    },
+    {
+      "when": "you only need a decorative graphic with no identity behind it",
+      "use": "Icon"
+    }
+  ],
+  "variants": {
+    "size": {
+      "mini": {
+        "use": "24px — inline beside body text, dense table rows"
+      },
+      "sm": {
+        "use": "32px — menu rows, compact lists"
+      },
+      "md": {
+        "use": "the default, 40px"
+      },
+      "lg": {
+        "use": "48px — profile headers and detail pages"
+      }
+    },
+    "shape": {
+      "circle": {
+        "use": "the default — people"
+      },
+      "square": {
+        "use": "organisations, projects, workspaces and other non-human entities"
+      }
+    }
+  },
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "the last fallback — rendered only when there is neither `src` nor `initials`"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "`alt` falls back to `initials`, so the avatar is never announced as an unlabelled image",
+      "a `src` that fails to load falls through to initials, then icon — never the browser's broken-image glyph"
+    ],
+    "requires": [
+      "`alt` describing the person, not the picture — \"Ada Lovelace\", not \"profile photo\""
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "passing `src` without `initials`",
+      "why": "a 404 leaves the fallback empty; initials are what make the failure invisible"
+    },
+    {
+      "dont": "using Avatar as a button",
+      "do": "put the Avatar inside a Button or Link",
+      "why": "Avatar renders a <span> with no role and takes no focus"
+    }
+  ],
   "stylesheet": "src/styles/avatar.css",
   "tokens": [
     "--border-strong",

package/dist/meta/AvatarGroup.json

@@ -4,6 +4,63 @@
   "propsType": "AvatarGroupProps",
   "description": "AvatarGroup overlaps its children by a quarter of the avatar size, matching\nFigma's -6 / -8 / -10 / -12 gaps at Mini / Small / Medium / Large.\n\nGroup defaults fill in `size` / `shape` only when a child Avatar has not set\nthem itself — an explicit child prop wins. Non-Avatar children are left\nalone so `size`/`shape` are never pushed onto arbitrary DOM nodes.\n\nChildren render in source order because that is Figma's stacking: each avatar\npaints over the one before it, so the `+N` overflow ends up on top. Later\nsiblings paint later, so this needs no z-index.",
   "import": "import { AvatarGroup } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Overlapping Avatars with a `+N` overflow, for showing several people in one row's width.",
+  "useWhen": [
+    "several people share one thing — assignees, participants, collaborators",
+    "the exact list matters less than the fact that there are several"
+  ],
+  "useInstead": [
+    {
+      "when": "each person needs their own name, role or action visible",
+      "use": "Table",
+      "why": "an overlapping stack hides everything but the picture"
+    }
+  ],
+  "variants": {
+    "size": {
+      "mini": {
+        "use": "24px — inline beside body text, dense table rows"
+      },
+      "sm": {
+        "use": "32px — menu rows, compact lists"
+      },
+      "md": {
+        "use": "the default, 40px"
+      },
+      "lg": {
+        "use": "48px — profile headers and detail pages"
+      }
+    },
+    "shape": {
+      "circle": {
+        "use": "the default — people"
+      },
+      "square": {
+        "use": "organisations, projects, workspaces"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "Avatar",
+      "note": "group `size`/`shape` fill in only where a child has not set its own; a child's explicit prop wins. Non-Avatar children are left untouched."
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`alt` on every child Avatar — the overflow avatar is the only one the group names for you"
+    ],
+    "notes": [
+      "Children paint in source order, so the `+N` overflow lands on top without any z-index."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "omitting `max` on an unbounded list",
+      "why": "twenty overlapping avatars is not a summary; it is a smear"
+    }
+  ],
   "stylesheet": "src/styles/avatar.css",
   "tokens": [
     "--border-strong",

package/dist/meta/Badge.json

@@ -4,6 +4,71 @@
   "propsType": "BadgeProps",
   "description": "Badge is presentational — no role, no interaction. React Aria has nothing to\noffer here, so this is a plain span rather than a hook wrapper for its own\nsake.\n\nIt carries no `status` or `alert` role on purpose: a badge is a label on\nsomething else, and announcing it as a live region would interrupt screen\nreader users on every render. Wrap it yourself if the value genuinely changes\nand matters.",
   "import": "import { Badge } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A small, non-interactive label that classifies the thing next to it. Presentational — no role, no live region.",
+  "useWhen": [
+    "labelling a record's status, type, count or category",
+    "the label belongs to something else on the page and is read as part of it"
+  ],
+  "useInstead": [
+    {
+      "when": "the message is a standalone statement the user must read",
+      "use": "Alert",
+      "why": "Badge carries no role and is not announced on its own"
+    },
+    {
+      "when": "the label should be clickable — a filter chip, a removable tag",
+      "use": "Button",
+      "why": "Badge takes no focus and fires nothing"
+    }
+  ],
+  "variants": {
+    "intent": {
+      "neutral": {
+        "use": "the default — a category with no judgement attached"
+      },
+      "primary": {
+        "use": "brand emphasis: Beta, New, Pro"
+      },
+      "success": {
+        "use": "a terminal good state: Active, Paid, Passed"
+      },
+      "warning": {
+        "use": "needs attention but is not broken: Pending, Expiring"
+      },
+      "error": {
+        "use": "a failed or blocked state: Failed, Overdue, Rejected"
+      },
+      "information": {
+        "use": "a neutral fact worth marking: Draft, Scheduled"
+      }
+    }
+  },
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "mutually exclusive with `dot` — `dot` wins and `icon` is dropped when both are set"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the dot marker is `aria-hidden`, so the badge announces its text only",
+      "no `status` or `alert` role, so a re-render never interrupts a screen reader"
+    ],
+    "notes": [
+      "If the value genuinely changes and the change matters, wrap the Badge in your own live region — the component will not do it for you."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "relying on intent colour alone to carry the meaning",
+      "why": "colour is not a label (WCAG 1.4.1); the text has to say Failed, not just be red"
+    },
+    {
+      "dont": "putting a Button or Link inside a Badge",
+      "why": "it renders a plain <span>; interactive content there has no affordance and no focus style"
+    }
+  ],
   "stylesheet": "src/styles/badge.css",
   "tokens": [
     "--border-default",

package/dist/meta/Checkbox.json

@@ -4,6 +4,88 @@
   "propsType": "CheckboxProps",
   "description": "Checkbox wraps a native `<input type=\"checkbox\">` and hides it.\n\nThe native input is kept rather than replaced by a div with `role=checkbox`\nbecause it brings form association, the indeterminate property, label\nclicking, and correct announcement — none of which are free to reimplement,\nand all of which are easy to get subtly wrong.\n\n`indeterminate` is the reason for the effect below: HTML has no\n`indeterminate` attribute, only a DOM property, so React cannot set it\ndeclaratively and it must be written after every render.",
   "import": "import { Checkbox } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A native checkbox with the system's styling, supporting an indeterminate state.",
+  "useWhen": [
+    "a single on/off choice inside a form that is submitted",
+    "selecting rows in a Table",
+    "several independent options where more than one may be picked"
+  ],
+  "useInstead": [
+    {
+      "when": "the change takes effect immediately rather than on submit",
+      "use": "Toggle",
+      "why": "a switch reads as a setting taking effect now; a checkbox reads as a value being collected"
+    },
+    {
+      "when": "the options are mutually exclusive",
+      "use": "RadioGroup"
+    },
+    {
+      "when": "there are many options and space is tight",
+      "use": "Select"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms and table rows"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "touch targets and prominent single choices"
+      }
+    },
+    "intent": {
+      "brand": {
+        "use": "the default"
+      },
+      "neutral": {
+        "use": "where the checked state is a fact rather than an approval — bulk-selection columns"
+      },
+      "danger": {
+        "use": "consenting to something destructive or irreversible"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the visible label; omit for a bare box and supply `aria-label` instead"
+    }
+  },
+  "a11y": {
+    "role": "checkbox",
+    "guarantees": [
+      "a real <input type=\"checkbox\">, so form association, label clicking, and correct announcement come from the platform",
+      "`isIndeterminate` is written to the DOM property after every render — HTML has no such attribute, so React cannot set it declaratively"
+    ],
+    "requires": [
+      "`children`, or `aria-label` when the box has no visible label — a row-selection checkbox always needs one"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a bare checkbox with no `children` and no `aria-label`",
+      "why": "every row announces an unnamed checkbox"
+    },
+    {
+      "dont": "`isIndeterminate` on a leaf checkbox",
+      "why": "indeterminate means \"some of my children are checked\"; on a leaf it is a state the user can never reach"
+    },
+    {
+      "dont": "a div with `role=\"checkbox\"`",
+      "why": "form association, the indeterminate property and label clicking are not free to reimplement"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/checkbox.css",
   "tokens": [
     "--border-disabled",

package/dist/meta/Divider.json

@@ -4,6 +4,45 @@
   "propsType": "DividerProps",
   "description": "A single `<hr>`, matching Figma's `Border` (70:22153).\n\n`<hr>` rather than a styled `<div>`: it is a semantic thematic break, so a\nscreen reader announces it as one, and it needs no `role` to get there.\n`aria-orientation` is set for the vertical case, since a vertical rule\ninside a horizontal toolbar is the one shape a screen reader cannot infer\nfrom the element alone.",
   "import": "import { Divider } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A semantic thematic break, rendered as a real <hr>.",
+  "useWhen": [
+    "separating groups of content or controls that are related but distinct",
+    "a menu, toolbar or form needs a visible section break"
+  ],
+  "useInstead": [
+    {
+      "when": "you only want space between two things",
+      "use": "CSS gap or margin",
+      "why": "a rule announces a break to a screen reader; whitespace does not, and usually shouldn't"
+    }
+  ],
+  "variants": {
+    "orientation": {
+      "horizontal": {
+        "use": "the default — between stacked sections"
+      },
+      "vertical": {
+        "use": "inside a horizontal row: toolbars, button groups, header bars"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "`<hr>` is a thematic break to assistive tech without needing a role",
+      "`aria-orientation=\"vertical\"` is set for the vertical case — the one thing a screen reader cannot infer from the element"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a styled <div> for a rule",
+      "why": "that is what this component exists to replace"
+    },
+    {
+      "dont": "a Divider between every row of a list",
+      "why": "a break announced on every row is noise; use the list's own row borders"
+    }
+  ],
   "stylesheet": "src/styles/divider.css",
   "tokens": [
     "--border-strong",

package/dist/meta/FullCard.json

@@ -4,6 +4,83 @@
   "propsType": "FullCardProps",
   "description": "Full Card — the full-bleed case study row from Figma `Full Card` (592:857).\n\nA text column beside a framed media panel, split down the middle, mirrored\nby the `Alignment` variant.\n\nThe split holds from 1080 and stacks below it, media above content in BOTH\nalignments — `Alignment` names a horizontal side and\nstops meaning anything once there is one column, so it does not get to\ndecide the vertical order too. Size is a media query, not a prop, the same\ncall Header makes about Device.\n\nWHY THE `show*` BOOLEANS ARE GONE\n\nFigma carries `Show Eyebrow`, `Show Description` and `Show Actions` beside\nthe slots they gate, because a Figma component instance always holds every\nlayer and needs a switch to hide one. React has no such constraint — an\nabsent prop is the switch. Badge made the same call with `Show Dot`, and\nkeeping both would have let `showActions` and `actions` disagree.\n\n`headline` is required, and it is the only required prop. The heading is\nwhat makes this a section rather than a decorated div, and every other part\nof the card is optional in Figma too.\n\nNo `'use client'`: nothing here is stateful or interactive. The interactive\nparts arrive through `actions`, and they carry their own boundary.",
   "import": "import { FullCard } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A full-bleed row: a text column beside a framed media panel, mirrored by `alignment`.",
+  "useWhen": [
+    "a marketing or overview section presents one thing with a screenshot beside it",
+    "a case-study or feature row on a landing or product page"
+  ],
+  "useInstead": [
+    {
+      "when": "you are listing records with comparable fields",
+      "use": "Table"
+    },
+    {
+      "when": "it is a short status message rather than a content section",
+      "use": "Alert"
+    }
+  ],
+  "slots": {
+    "eyebrow": {
+      "accepts": "Badge",
+      "note": "any node works"
+    },
+    "headline": {
+      "accepts": "text",
+      "note": "required — the heading is what makes this a section rather than a decorated div"
+    },
+    "description": {
+      "accepts": "text"
+    },
+    "actions": {
+      "accepts": "Button",
+      "note": "a secondary Button in the design"
+    },
+    "media": {
+      "accepts": "img or video",
+      "note": "rendered inside the framed screen holder — pass the screenshot or embed itself, not the frame"
+    },
+    "children": {
+      "accepts": "any",
+      "note": "extra content below the description"
+    }
+  },
+  "variants": {
+    "alignment": {
+      "left": {
+        "use": "media on the left, text on the right"
+      },
+      "right": {
+        "use": "media on the right — the variant names the media, not the text"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the headline renders as a real heading, so the card appears in the document outline"
+    ],
+    "requires": [
+      "`headingLevel` matching the surrounding outline — `h3` is the default because Figma applies Type/H3, but only the page knows the real level",
+      "`alt` on whatever you pass as `media`"
+    ],
+    "notes": [
+      "`h1` is deliberately not available: a full card is a section within a page, never the page's own title."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "looking for `showEyebrow` / `showDescription` / `showActions`",
+      "why": "an absent prop is the switch — Figma needs the boolean because an instance always holds every layer; React does not"
+    },
+    {
+      "dont": "leaving `headingLevel` at the default inside a section that is already at h3",
+      "why": "it produces a skipped or duplicated outline level"
+    },
+    {
+      "dont": "passing your own frame or border around `media`",
+      "why": "the component already draws the screen holder"
+    }
+  ],
   "stylesheet": "src/styles/full-card.css",
   "tokens": [
     "--border-default",

package/dist/meta/Header.json

@@ -4,6 +4,65 @@
   "propsType": "HeaderProps",
   "description": "Header renders Figma's four Device variants — Desktop, Tablet,\nMobile-Closed, Mobile-Open — from one DOM tree.\n\nTWO AXES, AND THEY ARE NOT THE SAME KIND OF THING\n\nFigma spells Device as a single four-way variant, but it is really two: a\n*breakpoint* (Desktop / Tablet / Mobile) and a *state* (Closed / Open). They\nare modelled differently here because they are known by different people.\n\n  Breakpoint is a media query. It is the one variant axis in the system the\n  browser already knows the answer to — a header is Mobile because the\n  viewport is narrow — and having React duplicate that judgement is how the\n  two drift apart. Breakpoints match the Breakpoint collection's container\n  widths: Tablet below 1216, Mobile below 896.\n\n  Open/Closed is a prop, because only the caller knows. It follows the\n  controlled/uncontrolled pair the rest of the system uses.\n\nONE TREE, TWO LAYOUTS\n\n`center` and `end` sit inline in the bar on Desktop and Tablet, and inside\nthe dropped Menu-Container on Mobile-Open. They are rendered once, in one\nwrapper, which is `display: contents` above the mobile breakpoint and an\nabsolutely positioned panel below it. Rendering them twice — or moving them\nwith JavaScript — would mean the same nav link exists twice in the\naccessibility tree, and would reset any state a caller put in a slot every\ntime the viewport crossed 896px.\n\nThe centre slot is no longer hidden on Tablet. Figma's Tablet variant ships\nit populated; the previous release collapsed it, which was correct for the\nprevious design and is not for this one.\n\nA `<header>` element with no explicit role: it is a landmark already when it\nis a direct child of body, which is where a page header sits.",
   "import": "import { Header } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The page header bar. Renders Figma's Desktop, Tablet, Mobile-Closed and Mobile-Open from one DOM tree.",
+  "useWhen": [
+    "the app needs a top bar with a brand, navigation and actions",
+    "that bar must collapse to a mobile menu below 896px"
+  ],
+  "useInstead": [
+    {
+      "when": "it is a sidebar rather than a top bar",
+      "use": "NavItem",
+      "why": "Header owns a horizontal bar and its own breakpoint behaviour"
+    }
+  ],
+  "slots": {
+    "brand": {
+      "accepts": "LogoMark or Logo",
+      "note": "rendered at the start; never shrinks"
+    },
+    "center": {
+      "accepts": "NavItem",
+      "note": "inline on Desktop and Tablet; moves into the mobile menu below 896px. Rendered once, so slot state survives crossing the breakpoint"
+    },
+    "end": {
+      "accepts": "Button, Avatar",
+      "note": "actions; same placement rules as `center`"
+    },
+    "children": {
+      "accepts": "any",
+      "note": "escape hatch — rendered in the bar after the menu wrapper and before the mobile toggle. Prefer the named slots"
+    }
+  },
+  "a11y": {
+    "role": "banner, from the <header> element when it is a direct child of body",
+    "guarantees": [
+      "the mobile toggle carries `aria-expanded` and `aria-controls` pointing at the menu container",
+      "Escape closes the open mobile menu — and the listener sits on the header, so a header that never opens never listens",
+      "the slots are rendered once, so no nav link exists twice in the accessibility tree"
+    ],
+    "requires": [
+      "`menuLabel` — the mobile toggle is icon-only and has no other name"
+    ],
+    "notes": [
+      "This is a disclosure, not a modal: no focus trap and no scroll lock, so Escape is the whole dismissal contract."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "rendering a second copy of the nav for mobile",
+      "why": "Header already moves the one copy; two copies duplicate every link in the accessibility tree"
+    },
+    {
+      "dont": "driving the mobile layout from JS state",
+      "why": "the breakpoint is a media query — the browser already knows the answer, and duplicating that judgement is how the two drift"
+    },
+    {
+      "dont": "passing `open` without `onOpenChange`",
+      "why": "controlled with no handler means the toggle can never change it"
+    }
+  ],
   "stylesheet": "src/styles/header.css",
   "tokens": [
     "--border-default",

package/dist/meta/Icon.json

@@ -4,6 +4,60 @@
   "propsType": "IconProps",
   "description": "Wrapper that applies the design system's icon sizing and accessibility\ndefaults to whatever icon component you hand it.\n\n  import { Plus } from 'lucide-react';\n  <Icon as={Plus} size=\"sm\" />\n  <Icon as={Plus} label=\"Add item\" />   // meaningful, gets an a11y name\n\nTakes the icon as a prop rather than re-exporting a set: a barrel of a\nthousand-plus icons defeats tree-shaking in several bundlers, and pinning one\nicon library would force it on every consumer. You import the one icon you\nneed, from whichever library you use, and it is the only one bundled.",
   "import": "import { Icon } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Applies the system's icon sizing and accessibility defaults to any SVG component you hand it. The package ships no icon set.",
+  "useWhen": [
+    "rendering any icon inside this design system, from any library — lucide, heroicons, react-icons, your own SVG"
+  ],
+  "useInstead": [
+    {
+      "when": "the graphic is a brand mark",
+      "use": "Logo or LogoMark"
+    },
+    {
+      "when": "you need a coloured status marker with text",
+      "use": "Badge"
+    }
+  ],
+  "a11y": {
+    "guarantees": [
+      "with `label`, the icon gets `role=\"img\"` and that name",
+      "without `label`, it is `aria-hidden` and `focusable=\"false\"` — decoration, never read twice"
+    ],
+    "requires": [
+      "`label` when the icon carries meaning on its own — an icon-only button, a standalone status marker"
+    ],
+    "notes": [
+      "Omit `label` for an icon beside a visible text label. The text already names it."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "`<Button startIcon={<Icon as={Plus} label=\"Add\" />}>Add</Button>`",
+      "do": "drop the `label`",
+      "why": "the button's own text names it; the labelled icon makes it announce twice"
+    },
+    {
+      "dont": "hardcoding `width`/`height` in px",
+      "do": "a `size` rung, or omit `size` to inherit the surrounding font size",
+      "why": "inheriting is what lets an icon sit correctly inside a Button without the Button knowing about it"
+    },
+    {
+      "dont": "assuming `size=\"xs\"` is 12px",
+      "why": "the ladder shifted in 2026-08: `xs` is 14, and `2xs` is the old 12. This raises no type error"
+    }
+  ],
+  "sizes": {
+    "note": "The rungs map one-to-one onto the Semantics `icon-size/*` tokens. Any CSS length is also accepted for a one-off.",
+    "ladder": {
+      "2xs": 12,
+      "xs": 14,
+      "sm": 16,
+      "md": 20,
+      "lg": 24,
+      "xl": 32
+    }
+  },
   "stylesheet": "src/styles/icon.css",
   "tokens": [],
   "props": {

package/dist/meta/Link.json

@@ -4,6 +4,73 @@
   "propsType": "LinkProps",
   "description": "Link — Figma `Link` (774:1516).\n\nRenders an `<a>` when given an `href` and a `<button>` otherwise, the same\njudgment `NavItem` makes: the element follows what the caller is actually\nbuilding rather than a separate `as` prop. A link that does not navigate is\na button, and shipping one as an anchor breaks middle-click, \"open in new\ntab\" and the screen-reader announcement all at once.\n\nNO SIZE PROP, DELIBERATELY. A link is an inline element and inherits its\ntype from the text around it — `font-size: inherit` in the stylesheet, and\nicons sized in `em` so they scale with it. Figma has to draw its variants at\nsome concrete size (16/24, `type/body`), but that is one sample of an\ninheriting element, not a specification. Do not add a size ladder to match\nthe drawing.",
   "import": "import { Link } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Navigation to somewhere else. Renders an <a> when given `href`, a <button> otherwise.",
+  "useWhen": [
+    "the interaction takes the user to a different page, view or resource",
+    "the destination should support middle-click, open-in-new-tab and copy-link"
+  ],
+  "useInstead": [
+    {
+      "when": "the interaction changes something rather than going somewhere",
+      "use": "Button",
+      "why": "a link that does not navigate breaks middle-click, open-in-new-tab and the screen-reader announcement all at once"
+    },
+    {
+      "when": "it is a primary navigation destination in a header or sidebar",
+      "use": "NavItem"
+    }
+  ],
+  "variants": {
+    "variant": {
+      "inline": {
+        "use": "the default — a link inside a paragraph. Underlined in every state, because a link in body copy must not rely on colour alone (WCAG 1.4.1)"
+      },
+      "standalone": {
+        "use": "a link that already reads as interactive from its position — a card footer, an action row. Underlines on hover only"
+      }
+    }
+  },
+  "slots": {
+    "startIcon": {
+      "accepts": "Icon",
+      "note": "omit Icon's `label` — the link text already names it"
+    },
+    "endIcon": {
+      "accepts": "Icon",
+      "note": "the external-link or arrow affordance; same rule about `label`"
+    }
+  },
+  "a11y": {
+    "role": "link when `href` is set, button when it is not",
+    "guarantees": [
+      "the rendered element follows what the caller is actually building, so the announcement is always honest",
+      "`inline` stays underlined in every state, so it never depends on colour alone"
+    ],
+    "requires": [
+      "link text that makes sense read on its own — screen-reader users navigate by a list of links"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "\"click here\" or \"read more\" as the whole link text",
+      "why": "out of context in a links list it names nothing"
+    },
+    {
+      "dont": "adding a size prop or wrapper to scale it",
+      "why": "a link is inline and inherits its type from the text around it, by design — icons are sized in `em` to follow"
+    },
+    {
+      "dont": "`target=\"_blank\"` with no warning in the text or endIcon",
+      "why": "an unannounced new tab disorients screen-reader and low-vision users"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/link.css",
   "tokens": [
     "--border-width-thick",