@nadicodeai/ui 12.1.95 → 12.1.97

package/dist/showcase/usage.generated.js

@@ -0,0 +1,1788 @@
+// Generated by scripts/generate-usage.mjs from the components' doc comments.
+// Do not edit: `npm run generate:usage -w @nadicodeai/ui` rewrites it.
+export const USAGE_FAMILIES = [
+    "Compositions",
+    "Actions",
+    "Inputs",
+    "Choices",
+    "Status",
+    "Navigation",
+    "Data",
+    "Feedback",
+    "Menus",
+    "Charts",
+    "Other",
+];
+export const USAGE = [
+    {
+        name: "ActivityFeed",
+        module: "activity-feed",
+        family: "Compositions",
+        summary: "What happened to a record, and when: one row per event under its day, newest first.",
+        when: "A record's history: a Customer's, a Partner's or an Installation's Activity tab in the Portal, the company wiki's updates in Nadia. Each answers \"what happened, and when?\".",
+        instead: 'The steps of one Agent run, read in order, are a RunTimeline; a list of records a person finds and acts on is a CollectionPage; a single "last changed" fact is a RecordTime.',
+        behaviour: "The search, filters and window sit right above the rows, kept in the URL by the product. Days stand newest first, each a title and a muted date over one card of rows; a row is the time of day, the actor's 24 px mark, the sentence with a status badge only for an exception, and one muted line of detail. \"Show older events\" follows the last day; there is never a page count. States, first that holds: failed, loading (still rows in the row's shape), no match with Clear filters, nothing yet in one line, the days. Under 900 px the time moves under the sentence. It draws no card header: the tab is the title.",
+        words: 'The sentence names the actor in `<strong>`, the action in the past tense and the object as a link that keeps the text\'s colour: "Marco Rinaldi created the Agent Acme Quotes". Day titles are "Today", "Yesterday", then the weekday; dates are the product\'s own ("14 October"). Nothing yet: "No events yet." and what will appear. No match: "No events match these filters.".',
+        access: "The toolbar is named by `label`; each day's title is a level-3 heading over a list of its events; while loading, one status named by `loadingLabel` stands for the rows; each time is a `<time>` with its exact moment for assistive technology. A system event has no mark, so nothing empty is announced.",
+    },
+    {
+        name: "AgentProfileCard",
+        module: "agent-profile",
+        family: "Compositions",
+        summary: "The card an Agent's Profile opens with in every product.",
+        when: "The head of an Agent's Profile: who she is, what she does, her state, and her model and reasoning beside them.",
+        instead: "An Agent in a gallery is `AgentCard`; in a list `AgentListRow`. Another object's page is `ObjectPage`.",
+        behaviour: "Her orb at 64, her name with the pencil, her description and her facts on the left; her model and reasoning on the right; the card's footer saves both sides. The pencil turns her name and description into fields in place. A fact being read draws its place; a missing one keeps its label and a dash.",
+        words: "Each product brings its own data, fields and words; the shape, sizes and order are this component's. Her state is a word: *Working*, *Waiting for you*.",
+        access: "Her name is the page's `h1`, kept as the heading while she is edited; the pencil is named (*Edit Nadia*); the orb is decorative beside her name.",
+    },
+    {
+        name: "CatalogDrawer",
+        module: "catalog-drawer",
+        family: "Compositions",
+        summary: "A catalogue to choose from in the right-side drawer, each entry added from its own row.",
+        when: "A person picks one or more things from a list too long for a dialog, the page still behind it: add a skill, add an app to a new Agent.",
+        instead: 'The shelf of everything the company holds, on its own page, is a `LibraryShelf`; a setup in steps is a `FormDrawer` with `job="steps"`; a new record from a few fields is a `FormDialog`.',
+        behaviour: "The header holds the title, the description and Close; the body holds the search, then the entries in one column under their section titles. It draws one state at a time: the failure with its retry, three still entries while the catalogue loads, no match with a way to clear the search, nothing at all, or the entries. An entry already held shows a muted check and its word in place of Add. The footer's one button closes the drawer.",
+        words: 'The title names the job: "Add a skill". The search names what it finds: "Search the hub". Each entry\'s button is "Add"; the held word is "Added"; the footer\'s is "Done".',
+        access: "A modal dialog named by its title; focus starts in the search, Escape and Close close it, and focus returns to the opener. The loading entries are one status named by `loadingLabel`.",
+    },
+    {
+        name: "CollectionFilters",
+        module: "collection-filters",
+        family: "Compositions",
+        summary: "The filters in a collection's toolbar: one Add filter button, a chip for each facet in force, and the facets most often narrowed to waiting as dashed chips.",
+        when: "A collection or a feed a person narrows by a property its records share: a status, an owner, a kind. It stands in the toolbar after the search and before the sort.",
+        instead: "Finding one record by its name is the search. Changing the order is the sort. Switching between sibling collections is the page's tabs.",
+        behaviour: "Add filter opens a picker of the facets, then of a facet's values, each searchable; Backspace in an empty search goes back to the facets. A facet in force is a chip that reopens its values, with a button that removes it. A suggested value waits as a dashed chip while its facet is unset and applies in one click. Focus returns to Add filter when a facet is removed. The product keeps each facet's value, in the URL where it has one.",
+        words: 'Every string is the product\'s: `copy` names Add filter, the two searches, the empty result, Back and Remove; each facet names itself, its values and its "All" choice.',
+        access: "Each chip is a group named by its facet; its remove button reads Remove with the facet's name. The pickers are searchable lists named by what they search.",
+    },
+    {
+        name: "CollectionPage",
+        module: "collection-page",
+        family: "Compositions",
+        summary: "A page whose job is a list of records: its title with the page's actions on one row, its sibling collections, one toolbar, then one line per record.",
+        when: "A list of records a person finds one of and acts on: Customers, Agents, Skills, Apps, MCP servers, Mailboxes.",
+        instead: "Figures compared across records are a DataTable with headings; a list inside another page's section is a RecordList with its heading.",
+        behaviour: "Nothing sits under the title. The title row holds at most one secondary, the primary, then the three dots, which open only for two commands or more. A primary that is also the first use's action waits until there are records; while a different primary stays, the first use's action is an outline button. One toolbar holds the search, which grows, then the filters, then the sort; it shows while there are records or a search or filter is set, and is glass only where the rows scroll under it. While a new search, filter or sort is read, the toolbar is busy and, after a second, shows the one waiting line, while the last rows stay. The rows, their states and their loading are the RecordList's; no match is offered only while a search or filter is set.",
+        words: 'Every string is the product\'s. The title names the collection in the plural ("Agents"); the search says what it finds ("Find a skill"); no match says what found nothing and offers to clear it ("Clear search", "Clear filters").',
+        access: "The title is the page's h1 when the composition draws it. The toolbar is named by `label` and busy while `pending`; the rows are the RecordList's table, named by `label`.",
+    },
+    {
+        name: "CollectionToolbar",
+        module: "collection-toolbar",
+        family: "Compositions",
+        summary: "A collection's control bar: its filters, its search and its sort, over its own rows.",
+        when: "The row above a collection's rows that holds its search, filters, sort and status.",
+        instead: "A page action never sits here: it is `PageActions` on the title's row. Finding across the product is `CommandDialog`.",
+        behaviour: 'Glass on the floating height, held at the top of the scrolling content while the rows pass under it; inside a titled `TableCard`, or with `surface="plain"`, the plain row. A search alone is always the plain row.',
+        words: "The label names the collection's tools: *Customer filters*.",
+        access: '`role="toolbar"` named by `label`.',
+    },
+    {
+        name: "ConfirmDialog",
+        module: "confirm-dialog",
+        family: "Compositions",
+        summary: "A consequence confirmed before it happens, in a blocking alert dialog.",
+        when: "An action removes, disconnects or deletes something, or otherwise cannot be taken back: remove a mailbox, delete an Agent.",
+        instead: "An action that can be undone runs at once and offers its undo in a toast; a form of a few fields is a `FormDialog`; a choice from a catalogue is a `CatalogDrawer`.",
+        behaviour: "The title names the record, the description the consequence; a failed confirm keeps the dialog open with the catalogue's message and its actions under the description. Cancel then the confirm at the footer's trailing edge, the confirm in the error colour when `destructive`. While `loading` both hold, Escape does not close it, and the confirm says its pending word. The backdrop does not dismiss it.",
+        words: 'The title is a statement naming the record, never a question: "Remove pec@acme.it". The description says what stops and what stays. The confirm repeats the verb and the noun, "Remove mailbox", never just "Delete" or "OK".',
+        access: '`role="alertdialog"` named by its title and described by its consequence; focus starts on Cancel, Escape cancels, and focus returns to the opener.',
+    },
+    {
+        name: "EntryScene",
+        module: "entry-scene",
+        family: "Compositions",
+        summary: "Nadia's entry screen, contained: the approved picture of the surface behind, the wordmark at the upper left, Nadia's ribbon and her words centred as one group. The screen is black in every theme.",
+        when: "Nadia's installer and the desktop's sign-in, start, update and failure screens, which paint the same screen; a page that shows that screen beside other things.",
+        instead: "The Portal's entry pages are its funnel frame with the shared entry header; Alveare Server's entry is the HiveScene; a wait inside the product is a WaitingLine.",
+        behaviour: "It holds no state and decides nothing: which view is open, the words and when the screen ends belong to whoever mounts it. It fills a box of the window's own shape (`aspectRatio`), so the picture's figure stands on the window's floor (`pictureFeet`). A failure quiets the picture and never removes it. Its children stand in order: the message, the actions, the progress line, the stage list.",
+        words: 'The heading names the surface and is never seen. Instructions and status are one plain sentence that changes only when the real stage changes ("Loading your tools").',
+        access: "One level-1 heading for the screen, read but not shown; a message that reports work in progress is a status.",
+    },
+    {
+        name: "FormDialog",
+        module: "form-dialog",
+        family: "Compositions",
+        summary: "A new record, or one or two values from a command, in a centred dialog.",
+        when: "A person adds a record through a few fields, or changes one or two values a command asks for: new customer, add a mailbox, add an MCP server.",
+        instead: 'A record already in a list edits in its row with `RowEditForm`; a choice from a catalogue is a `CatalogDrawer`; a setup in steps with a wait is a `FormDrawer` with `job="steps"`; a consequence is confirmed in a `ConfirmDialog`.',
+        behaviour: "Centred over a scrim without blur: the title and its help, the fields in a body that scrolls, then the footer with Cancel and the primary at its trailing edge. A refusal or a failed save sits above the footer and the fields keep what was typed. While its save runs it holds open, Cancel and the primary hold, and the waiting line runs under them.",
+        words: 'The title names the job and its object: "New customer", "Add a mailbox". The primary repeats it: "Create customer", "Add mailbox", never "OK" or "Submit".',
+        access: "A modal dialog named by its title; focus starts in its first field or `initialFocus`, Escape and Close close it unless the save runs, and focus returns to the opener or `finalFocus`.",
+    },
+    {
+        name: "FormDrawer",
+        module: "form-drawer",
+        family: "Compositions",
+        summary: "The right-side drawer for a catalogue or a setup in steps, at one width.",
+        when: "Choosing from a catalogue too long for a dialog (through `CatalogDrawer`), or setting something up in several steps with a wait: connect a messaging channel, Telegram's code.",
+        instead: "A new record from a few fields is a `FormDialog`; a record already in a list edits in its row with `RowEditForm`; a fact on the record's own page changes in place in its section; a consequence is confirmed in a `ConfirmDialog`.",
+        behaviour: 'Opens from the right edge at one width, 560 px (the full width on a compact screen), with the page still behind it; 12 px corners on the edges not flush with the window. The header holds the step ("Step 2 of 3") over the title, the description and Close; the body scrolls between the header and a recessed footer that stays, Cancel then the primary at its trailing edge. Cancel holds while a save runs.',
+        words: 'The title names the job and its object: "Connect Telegram", "Add a skill". The step reads "Step N of M". The primary says what it does: "Connect", "Continue", never "OK".',
+        access: "A modal dialog named by its title; focus moves inside on open and returns to the opener on close, or to `finalFocus` when the opener is gone. Escape and Close close it; the step is read before the title.",
+    },
+    {
+        name: "LibraryShelf",
+        module: "library-shelf",
+        family: "Compositions",
+        summary: "A Library shelf: the one line saying what it holds, the search, then the reusable things a person adds, as two-column entries or Agent template cards.",
+        when: "A page of reusable things a person adds to an Agent: Skills, Plugins, Agent templates.",
+        instead: "Records a person already has and acts on are a CollectionPage; choosing from a catalogue without leaving the page is a CatalogDrawer.",
+        behaviour: "Shows, the first that holds: the failure; still entries while the shelf loads; noMatch while the search finds nothing; empty when the shelf holds nothing; then each section's title over its entries, two to a row from md, or the templates three to a row. Each entry has its kind's tile, its name (the link to its page), one line, one fact, one Add control or the word saying it is already added, then its menu. A failed add puts its message in the entry's line and its next steps beside its controls. The search shows unless the shelf is empty.",
+        words: "The product words every string: the definition (one sentence on what the shelf holds), the search's label (\"Search skills\"), the loading label, each entry's name, line, Add label and added word, the empty, noMatch and failed messages.",
+        access: "Each section is a region named by its h2; entries are list items; loading is a status named by loadingLabel and aria-busy; a failed add is announced as an alert; each entry's menu is named by its label.",
+    },
+    {
+        name: "ObjectPage",
+        module: "object-page",
+        family: "Compositions",
+        summary: "One object's page: its mark, name, one line and key facts on the page ground, its commands on the name's row, then its sections as cards.",
+        when: "One thing a person opened from a list and now reads or acts on: a customer, a partner, an Installation, a Library entry.",
+        instead: "A list of records is a CollectionPage; a page of settings only is a SettingsPage; an Agent opens on its AgentProfileCard, the documented exception.",
+        behaviour: "The header sits on the page, never in a card: the mark at 64, the name, one line, the facts in one row, and at the trailing edge one secondary action then the three dots; below `md` the actions wrap under the name. The sections follow, 24 apart, each drawing its own states.",
+        words: 'The name as the object is called everywhere else; the line says what it is and whose ("Customer of Partner Alpha · since 3 August 2026"); a fact\'s label is a noun ("Plan"), its value the figure; the menu\'s trigger reads "More for {name}".',
+        access: "With `headingProps` the name is the page's h1; without them it is text, for a product whose chrome already titles the page. The facts are a description list; the mark is decorative beside the name.",
+    },
+    {
+        name: "ObjectSection",
+        module: "object-workspace",
+        family: "Compositions",
+        summary: "A section of an object's page: a card that owns one decision about the object.",
+        when: "A part of an ObjectPage a person reads or changes on its own: a customer's Company details, an Agent's Instructions, a Library entry's source.",
+        instead: "Values a person edits and saves together are a SettingsSection; a list of the object's records is a RecordList with its heading; a passing condition is a MessageNotice.",
+        behaviour: "A resting card: its title and an optional line, at the trailing edge `meta` (muted) then `action` as an outline button, then its body. No icon in the header.",
+        words: 'The title names what the section holds ("Company", "Instructions"); the action is a verb on it ("Edit"); `meta` is a short count or time ("2 of 5 Agents").',
+        access: "The title is a heading one level under the page (h2), deeper only under another heading through `headingLevel`.",
+    },
+    {
+        name: "OverviewPage",
+        module: "overview-page",
+        family: "Compositions",
+        summary: 'The page that answers "what needs attention?": is anything wrong, and where.',
+        when: "The landing page of an area a person checks: the Portal's Dashboard, Analytics, Statements, System health, an Agent's Usage.",
+        instead: "A list of records a person finds one of is a `CollectionPage`; one record is an `ObjectPage`. Never a stack of previews of every section: each exception links to its owner instead.",
+        behaviour: "The reading period on the title row, then the figures in one row of equal `KpiCard`s (four columns from md, fewer when fewer, one column below), then the chart cards, then the exceptions, 16 px apart. It has no states of its own: each card and the exceptions' `RecordList` draw theirs.",
+        words: 'The product words every figure, chart and exception. A figure\'s label names its measure ("Active Agents", "Spend"), the chart\'s title names its reading ("Usage"), and the exceptions\' heading says what they are ("Needs attention").',
+        access: "Each chart card is a named section at the page's heading level, and the exceptions carry their own heading; figures are text, never colour alone.",
+    },
+    {
+        name: "PageHeader",
+        module: "page-header",
+        family: "Compositions",
+        summary: "The top of a product page: its title, and the page's actions on the title's row.",
+        when: "The top of every collection and working page: the title at heading size, `PageActions` at the trailing edge of its row.",
+        instead: "An object's own header is `ObjectPage`'s. The path above it is the top bar's `Breadcrumb`; filters, search and sort sit in the toolbar below.",
+        behaviour: "Nothing explains the page under its title. The actions arrive through the `PageActions` slot, so the page draws its commands once.",
+        words: "The title is the page's name as the sidebar writes it: *Customers*, *Agents*.",
+        access: "The title is the page's `h1`; DOM order is visual order.",
+    },
+    {
+        name: "RecordList",
+        module: "record-list",
+        family: "Compositions",
+        summary: "One line per record, on one resting card: its identity mark and name over what it is, a few comparable facts, a status only for the exception, when it happened, the row's one command, and its three dots last.",
+        when: "A list of records inside another page: an Overview's exceptions, an object page's \"Needs attention\", any section that lists records a person opens or acts on. A page whose whole job is the list is a `CollectionPage`, which draws this.",
+        instead: "Figures compared across records, read by their column headings, are a `DataTable`. Events in time are an `ActivityFeed`. Reusable things a person adds from a catalogue are a `LibraryShelf`.",
+        behaviour: "Each row reads left to right at fixed measures: the mark and name (at most a third of the row), facts on one line, the status in its 150 px slot only when the record is the exception, the time right-aligned in tabular figures with the exact moment on hover, the row command at most 192 px wide with its label cut short, then the three dots, or a muted chevron when the row only opens. On a card too narrow for them (768 px, or 1024 px for seven columns or more or a row command), the facts, the status and the time move under the record's line, leaving out a fact or status the record does not have, and the name and its commands keep theirs. A menu of one command that is not destructive, with no row command, is that command's outline button. With `open` the whole row is one target. A failed or refused action of the record replaces its detail line, with its next steps beside its commands; the record being edited opens its form under its own line. While the records load, three still skeleton rows hold the place; then, first that holds: the failed read, no match, the empty state, the rows. A list with no records and no empty state draws nothing.",
+        words: 'Every string is the product\'s: `label` names the list, a time\'s `phrase` writes its sentence ("Updated {when}"), `missing` is what a screen reader hears for a record with no time, the menu\'s `label` reads "More for {record}". A status is the exception\'s word ("Needs attention"), never "Active" on every row.',
+        access: "A table named by `label`, its column headings read by assistive technology only. The row link carries `open.label`; the three dots carry the menu's `label`, and the menu's first line names the record. The loading rows are a busy status named by `loadingLabel`.",
+    },
+    {
+        name: "RecordSheet",
+        module: "record-sheet",
+        family: "Compositions",
+        summary: "One record from a list, looked at in a sheet at the right edge, then back to the list.",
+        when: "A list's record holds more than its row shows and is only read, not changed: a Stripe event in Billing, a usage row.",
+        instead: "A record changed from its list edits in its row with `RowEditForm`; a record with sections and commands of its own has its own page, an `ObjectPage`; a choice from a catalogue is a `CatalogDrawer`.",
+        behaviour: "Opens from the right, 420 px wide and 8 px from the window, the list still behind it, with 12 px corners on its free edges. The header holds the record's name, one muted line and Close; the body scrolls through its facts as labelled values, then the read-only payload with its copy button; the footer holds one command to the record's owner. It has no states of its own: it opens only on a record.",
+        words: "The title is the record's own name, as its row shows it. The footer's command names where it goes: \"Open Beta Studio\".",
+        access: "A modal dialog named by its title; Escape and Close close it, and focus returns to the row it opened from (`finalFocus`). The payload is a read-only text area named by its label.",
+    },
+    {
+        name: "RowEditForm",
+        module: "row-edit-form",
+        family: "Compositions",
+        summary: "A record's form opened inside its own row, the rows above and below staying where they are.",
+        when: "A person changes a record they see in a list: edit a mailbox, a task, an MCP server, a channel. It is a `RecordList`'s `editor` or a `DataTable`'s `rowEditor`.",
+        instead: "A new record from a few fields is a `FormDialog`; a fact on the record's own page changes in place in its section; a choice from a catalogue is a `CatalogDrawer`.",
+        behaviour: "The fields open under the record's line; a refusal or a failed save sits above the footer. The footer, one tone below, holds an optional hint at its leading edge, then Cancel and the save rightmost. Save stays off until a field changes: the caller sets `submit.disabled` from its own fields. Cancel holds while the save runs, and the waiting line runs under them.",
+        words: 'The save says what it does, "Save"; Cancel is "Cancel". The hint is a way on, such as where to find a token, never a restatement of a field\'s label.',
+        access: "A form in the row's place, which the caller moves focus into. The running save is marked busy, and the line saying why the save cannot run yet is its description (`submit.describedBy`).",
+    },
+    {
+        name: "SettingsPage",
+        module: "settings-page",
+        family: "Compositions",
+        summary: "A page of settings: a centred column of section cards, each saving its own values.",
+        when: "A place whose job is changing how something behaves: an account's profile, a company's identity, Nadia's notifications.",
+        instead: "One object's page with a settings card among its sections is an ObjectPage; Theme and Language, which apply on change, stay in the account menu.",
+        behaviour: "The sections stack 20 apart in a centred column at most 56rem wide. The page draws no header and no save of its own: each SettingsSection saves from its footer.",
+        words: '`title` names the place as the navigation does ("Profile"); the sections\' titles and lines carry the rest.',
+        access: "`title` becomes a visually hidden h1 for a product whose chrome shows the place without a heading; leave it out where the chrome already draws the h1.",
+    },
+    {
+        name: "SettingsSection",
+        module: "settings-section",
+        family: "Compositions",
+        summary: "A card of related settings that says what changing them does and saves them from its own footer.",
+        when: "A few related values a person changes and saves together, on a SettingsPage or as a section of an ObjectPage: Personal details, Company identity, Notifications.",
+        instead: "Read-only values are a SettingsFactsSection; Theme and Language, which apply on change, live in the account menu; a record's edit in a list is a RowEditForm.",
+        behaviour: "With `save`: Save stays disabled until a field differs from what is saved, says `pendingLabel` while saving with Cancel held beside it, then the footer shows the ok check and `savedLabel` until the next change. A failure keeps every value and shows under its field until that field changes, or above the footer until the next save. A `cancel` that runs work of its own says its `pendingLabel` while `pending`. Without `save`, the footer holds `footerHint` and `footer`, and is left out when both are.",
+        words: 'The title names the values ("Personal details"); the description says what changing them does, in one line; the hint says where the save applies ("Saved for every device you sign in on."); Save, Saving and Saved come from the product\'s catalogue.',
+        access: "The title is the section's h2 and names the form that saves it. The footer's hint and saved line are one status, announced politely; a failure under a field marks the control invalid and describes it.",
+    },
+    {
+        name: "Button",
+        module: "button",
+        family: "Actions",
+        summary: "The package's one button: five looks at 36 px, the label naming the result.",
+        when: "A command that changes something or opens a surface. One `default` per surface: the thing this page or dialog is for.",
+        instead: "Going somewhere is a link drawn with `buttonVariants`, and a link inside a sentence is `TextLink`, blue and underlined. A record's secondary commands go in `ActionMenu`. An on/off value is a `Switch`.",
+        behaviour: "Enter and Space run it. A press settles at 97% scale in 180 ms, except on a trigger that opens a popup. Disabled is 50% and ignores the pointer, and its reason is written beside it. On touch the target grows to 44 px while the drawing stays 36. `sm` and `xs` are for a control nested in dense content, such as a composer or an input group, never for chrome.",
+        words: "Sentence case, verb + noun naming the result: *Invite member*, *Remove mailbox*; never OK, Submit or Confirm. Italian runs about a third longer (*Rimuovi casella*), so a footer leaves room and a label never wraps.",
+        access: 'A native `button`, `type="button"` unless it submits. An icon-only button carries an `aria-label` naming action and target. Focus is the 2 px ink outline at 2 px offset, drawn once by the base layer, never repainted.',
+    },
+    {
+        name: "ButtonGroup",
+        module: "button-group",
+        family: "Actions",
+        summary: "Two or three buttons that share one edge and read as one control.",
+        when: "Two or three buttons that act on one thing and read as one control: an applied filter with its remove, a pager. A split action (*Download PDF* with its chevron for CSV and Excel) is a group of a `Button` and a `DropdownMenu` trigger.",
+        instead: "Choosing one value of several is a `RadioGroup` drawn as a segmented control, or a `ToggleGroup`. Unrelated actions stay separate buttons 8 px apart. A destructive command never sits in a split, neither as the default nor in its menu.",
+        behaviour: "One shared edge between members and rounded outer corners only. The focused member rises above its neighbours so its whole outline shows. Each member keeps its own tab stop. In a split, the left half runs the default and the chevron opens the menu with the default listed first and checked.",
+        words: "Each member is labelled on its own. The group's name says what it holds: *Status filter*, *Pages*. A split's default names its variant (*Download PDF*); its chevron names the family: *More download formats*.",
+        access: '`role="group"` with an `aria-label`. An icon member names its action and target: *Remove filter: Status*. A split\'s chevron has `aria-haspopup="menu"`, `aria-expanded` and its own `aria-label`.',
+    },
+    {
+        name: "CopyButton",
+        module: "copy-button",
+        family: "Actions",
+        summary: "Copies an exact value someone will paste elsewhere.",
+        when: "An exact value someone will paste elsewhere: an Agent ID, a server address, a command. A shell prompt shown before a command stays outside the copied value.",
+        instead: "Several lines of code are a `CodeBlock`. Ordinary prose never gets copy chrome. A secret needs its reveal policy first.",
+        behaviour: "Copies the full underlying value even when the shown one is shortened. The check shows for 2 s, and only after the clipboard confirms. A failure shows the alert mark and the button stays for a retry. Sizes: `icon` (36), `icon-sm` (32) after a value, `icon-xs` (24) inside a field.",
+        words: 'Three catalogue strings: `copyLabel` names the target ("Copy Agent ID"), `copiedLabel` ("Copied"), `copyFailedLabel` ("Couldn\'t copy").',
+        access: '`aria-label` is the copy label and does not change. The result is read once from a hidden `role="status"`. The button stays focusable while it works.',
+    },
+    {
+        name: "PageActions",
+        module: "page-actions",
+        family: "Actions",
+        summary: "A page's actions, drawn on its title's row. Only the page shown last owns the row: a page kept hidden for a quick return gives the row back. Outside a `PageActionsHostProvider`, they render where they stand.",
+        when: "The actions of a collection, an object or an overview page, on the title's row at its trailing edge. A Configuration page has none: each section saves from its footer.",
+        instead: "A row's actions are the row's one button and its `ActionMenu`. A collection toolbar holds search and filters, never a page action.",
+        behaviour: "Takes `period`, `secondary`, `primary` and `menu` and draws their order and variants itself: the period, outline, default, then the three dots last. The menu needs two commands or more; a single extra command is the secondary. A destination outside the product ends in the arrow. A running command keeps its place and icon, says its pending word and holds.",
+        words: 'The primary is the page\'s main job as verb and noun: "Invite member", "New Agent". The pending word is its -ing form: "Inviting member". The menu names the page\'s record at its top and keeps the destructive command last, after a divider.',
+        access: 'DOM order is visual order. A command whose label does not name its target carries `accessibleName`. A running command is `aria-busy` and keeps focus. The three dots carry "More for {record}"; the menu returns focus to them when it closes.',
+    },
+    {
+        name: "Calendar",
+        module: "calendar",
+        family: "Inputs",
+        summary: "A month grid for choosing a day or a range of days.",
+        when: "A date or a window whose day and month matter. A chart or a report's window is one `DateRangeControl` in its toolbar, which opens this calendar from its *Custom* preset.",
+        instead: "A row of range buttons is never drawn; the presets live in one select. A time of day or a recurring schedule is its own field, not a calendar.",
+        behaviour: "The first click starts a range, the second ends it. 28 px days, Monday first in Italian, ends in ink, today in the muted fill. Arrow keys move by day, Page Up and Down by month.",
+        words: "Dates are written in the reader's locale (*7 Oct – 13 Oct*, *7–13 ott*), never the ISO pair a URL stores.",
+        access: "A grid of day buttons, each named with its full date. Focus goes into the grid when it opens and back to its trigger when it closes, and the chosen range is read out.",
+    },
+    {
+        name: "CollectionSearch",
+        module: "collection-search",
+        family: "Inputs",
+        summary: "The search a collection toolbar fills its row with.",
+        when: "Finding a record inside one collection, at the start of its toolbar.",
+        instead: "Finding anything across the product is `CommandDialog`. Narrowing by a facet is `CollectionFilters`. A free value in a form is `Input`.",
+        behaviour: "Results stay on screen while a search updates. Escape clears only while the box holds the interaction and has a value; otherwise it closes the overlay as usual.",
+        words: "The search's label is what it finds, also shown as its placeholder: *Find a skill*, *Search the hub*.",
+        access: 'The input carries `aria-label` from `label` and `type="search"`; the search mark is decorative.',
+    },
+    {
+        name: "Field",
+        module: "field",
+        family: "Inputs",
+        summary: "A control with its label, its help and its error, tied together.",
+        when: "Every control with a name: it ties the label, the help and the error to the control. Inside a settings section `SettingsField` does it and hands the control its `controlProps`. A rich choice tile is a `FieldLabel` holding a `Field` with its radio or checkbox.",
+        instead: "A group of radios or checkboxes is a `FieldSet` with a `FieldLegend`. A whole save group is `SettingsSection`.",
+        behaviour: "Label, then help, then the error, then the control, 8 px apart. Invalid turns the label and message red and puts the red edge and outline on the control. Validate on submit or on leaving a field, then update the message as the value is corrected.",
+        words: "The help says what the setting changes, in one sentence. The error says how to fix it, not what went wrong: *Enter a full address, like name@company.it.* A disabled field says why.",
+        access: '`FieldError` is `role="alert"`. The control carries `id`, `aria-invalid`, `aria-describedby` (help, then error), `disabled` and `required`.',
+    },
+    {
+        name: "Form",
+        module: "form",
+        family: "Inputs",
+        summary: "A react-hook-form form whose fields bind their label, help and message for the reader.",
+        when: "A client form whose values, validation and submit run through react-hook-form: `FormField` binds a control, `FormMessage` shows its error.",
+        instead: "A settings group that saves on its own is `SettingsSection`. A short form in a dialog is `FormDialog`; one in a row is `RowEditForm`. A form with no client validation is a plain `form` with `Field`.",
+        behaviour: 'Validation runs on submit and on leaving a field, then updates while the value is corrected. A failed save keeps every value. The submit is `type="submit"`, so Enter in a field submits.',
+        words: "Messages come from the product's catalogue or schema: how to fix the value, not what went wrong.",
+        access: "`FormControl` gives the control its `id`, `aria-invalid` and `aria-describedby` (help, then message); `FormMessage` is read when it appears.",
+    },
+    {
+        name: "Input",
+        module: "input",
+        family: "Inputs",
+        summary: "One line of free text, edged in the input grey.",
+        when: "One free-form value on one line: a name, an address, a number.",
+        instead: "Text with a fixed prefix, an icon or a button inside is `InputGroup`. Several lines are `Textarea`. A known set of values is a select, radios or a combobox.",
+        behaviour: "36 px, edged in the `input` role's grey with no shadow, 6 px corners. Focus is the 2 px outline. Invalid keeps a red edge and a red outline even without focus. Disabled is 50% on a half-grey fill. The value survives a failed save.",
+        words: "The label is a noun in sentence case with no colon. The placeholder is an example (*Bizeta Arredamenti*), never the label or an instruction. In a configuration section the box stops at 20 rem under its label.",
+        access: "A visible `label` tied by `id`, the help and the error joined through `aria-describedby`, `aria-invalid` when wrong. Use the right `type`, `autocomplete` and `inputMode`.",
+    },
+    {
+        name: "InputGroup",
+        module: "input-group",
+        family: "Inputs",
+        summary: "One input box with something fixed inside it: a mark, a prefix, a button.",
+        when: "A single-line value with something fixed inside the box: a search mark, a clear button, a prefix like *https://*, a copy button.",
+        instead: "A collection's search is `CollectionSearch`, never a hand-built group. A plain value is `Input`. Many known values to filter is `Combobox`.",
+        behaviour: "The group draws the edge and the focus outline for the input inside it. The clear button empties the value and puts focus back in the box. Escape clears only while the box holds the interaction and has a value; otherwise it closes the overlay as usual.",
+        words: "Prefix and suffix are literal text, never the label. An inline button names what it does: *Clear search*, *Copy address*.",
+        access: '`role="group"` around the box. The input inside keeps its own label. Inline buttons are named: *Clear search*, *Copy address*.',
+    },
+    {
+        name: "InputOTP",
+        module: "input-otp",
+        family: "Inputs",
+        summary: "A fixed-length code typed into one slot per character.",
+        when: "A fixed-length code a person types: the two-factor code at the Portal's sign-in.",
+        instead: "A code a person only compares between two screens is `PairingCode`. A long token is `Input` with a copy or paste action.",
+        behaviour: "One real input behind the slots: paste fills them all, Backspace walks back. The active slot carries the focus outline and a still caret. A wrong code turns the group red and keeps the digits so the person can correct them. Resend follows the product's real policy.",
+        words: "The label says where the code comes from. The error says what to do: *That code didn't match. Check the newest code in your app.*",
+        access: 'One labelled input with `autocomplete="one-time-code"` and `inputMode="numeric"`. The separator is decorative to the reader.',
+    },
+    {
+        name: "Label",
+        module: "label",
+        family: "Inputs",
+        summary: "The visible name of one control.",
+        when: "A control standing on its own that needs a visible name: a checkbox's sentence, a switch's setting.",
+        instead: "A control inside a form takes `FieldLabel` through `Field`; a group of controls takes `FieldLegend`. A short tag of metadata is `MetaLabel`.",
+        behaviour: "Sits beside or above its control and dims with it when the control is disabled. Clicking it moves to its control.",
+        words: "A noun or a positive statement in sentence case, no colon: *Approvals*, *Send a copy to the person who asked*.",
+        access: "A `label` tied to its control by `htmlFor`. Never replaced by a placeholder or overridden by another `aria-label`.",
+    },
+    {
+        name: "NativeSelect",
+        module: "native-select",
+        family: "Inputs",
+        summary: "The platform's own select, drawn as our input box.",
+        when: "A long fixed list inside a native form, where the platform's own picker serves best: a time zone, a country.",
+        instead: "Two or three options are radios or a segmented control. Up to about ten, drawn in our style, is `Select`. A list people type into is `Combobox`.",
+        behaviour: "Same box as `Input`, the chevron 10 px from the edge in the muted grey. It opens the system's list, with native keyboard and typing. As an uncontrolled field it keeps a saved value instead of snapping back to the page's first default.",
+        words: "The label names the thing chosen (*Time zone*). A placeholder option is distinct from a real one and never preselected as if chosen.",
+        access: "A real `select` with a visible label; option groups are `optgroup`. The chevron is decorative.",
+    },
+    {
+        name: "SettingsField",
+        module: "settings-section",
+        family: "Inputs",
+        summary: "One setting: its label and help above its control, and what went wrong under it.",
+        when: "A value inside a SettingsSection: a name, an address, a choice, a switch.",
+        instead: "A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only value is a fact in a SettingsFactsSection.",
+        behaviour: 'The control is 20rem wide under its label and help by default; a switch row passes `orientation="horizontal"` and sits at the end of its label\'s row at its own width. A validation `error`, or a failed save about this field, shows under the control and marks it invalid.',
+        words: 'The label is a noun for the value ("Display name"); the help is one line saying what it is for or where it shows; an error says what to do next.',
+        access: "The control receives its id, `aria-invalid` and `aria-describedby` through `controlProps`, so the label, help and error are read with it.",
+    },
+    {
+        name: "Slider",
+        module: "slider",
+        family: "Inputs",
+        summary: "A bounded number chosen by a thumb's position on a track.",
+        when: "A bounded number where the position matters more than the digit: a limit, a share.",
+        instead: "An exact number is `Input`; pair the two when precision counts. A few named levels are radios.",
+        behaviour: "A 4 px track, the filled part in ink, a 12 px thumb edged in the input grey. Hover, drag and focus outline the thumb. Arrows step, Page Up and Down jump, Home and End reach the bounds. The thumb's touch target is 44 px.",
+        words: "The label names the quantity; the current value and its unit are always written beside it (*€ 400*). The help states the bounds and the step.",
+        access: '`role="slider"` with a name, min, max and `aria-valuetext` carrying the unit.',
+    },
+    {
+        name: "Textarea",
+        module: "textarea",
+        family: "Inputs",
+        summary: "Several lines of free text that grow with their content.",
+        when: "Several lines of free text: an Agent's instructions, a description, notes.",
+        instead: "One line is `Input`. Code or a value to copy is `CodeBlock`, read-only.",
+        behaviour: "At least 64 px, then it grows with its content (`field-sizing: content`). The same edge, focus, invalid and disabled as `Input`. Whitespace is kept exactly; nothing trims it. A character count shows only when a real limit exists.",
+        words: "The label names the content (*Instructions*); the help says who reads it and when. The placeholder is a short example, not a paragraph.",
+        access: "A visible label tied by `id`; help and error through `aria-describedby`. In a dialog, the footer's Save stays reachable while the box grows.",
+    },
+    {
+        name: "Checkbox",
+        module: "checkbox",
+        family: "Choices",
+        summary: "A box that is checked, unchecked or mixed.",
+        when: "Independent yes-or-no choices in a form, an acknowledgment before a step, selecting rows.",
+        instead: "A setting that is on or off is a `Switch`. One of several is a `RadioGroup`. Several values from a long list is a multi-select.",
+        behaviour: "Unchecked is only the input-grey edge, showing the surface beneath. Checked fills with ink and a 14 px check; mixed shows a minus and is worked out from the rows below. The label toggles it too, and on touch the target is 44 px. A required acknowledgment is checked on submit.",
+        words: "The label says what is true when checked, positively: *Send a copy to the person who asked*, not *Don't send*. A related set gets a legend.",
+        access: '`role="checkbox"` with `aria-checked` true, false or mixed. A row\'s box is named for its record: *Select pec@acme.it*. A set sits in a `FieldSet` with its legend.',
+    },
+    {
+        name: "CollectionSort",
+        module: "collection-sort",
+        family: "Choices",
+        summary: "The order a collection's rows are read in, at the toolbar's trailing edge.",
+        when: "A collection whose rows can be read in more than one order: newest, name, cost.",
+        instead: "Sorting by a column of a comparison table is `DataTable`'s own header. Narrowing rows is `CollectionFilters`.",
+        behaviour: "An outline button names the order in force; its menu offers the others as radio rows with the current one checked. Choosing the current order changes nothing. It renders nothing without options.",
+        words: "The label says what the control does (*Sort by*); each option names an order: *Newest first*, *Name*.",
+        access: "The trigger reads the label and the current order: *Sort by: Newest first*. The options are menu radio items.",
+    },
+    {
+        name: "Combobox",
+        module: "combobox",
+        family: "Choices",
+        summary: "Type to find one value, or several, in a known set.",
+        when: "Typing to find in a known set: assign an Agent, choose a time zone, add several Agents at once with `multiple`.",
+        instead: "A short fixed list is a `Select`. Free text is an `Input`. Narrowing a collection is `CollectionFilters`.",
+        behaviour: "Typing filters the list. Loading and no match are different states; the chosen value stays while results load. Enter picks the highlighted row and never submits the form around it. Clear empties the box and keeps focus there. With `multiple`, each choice is a chip with its own remove; Backspace in an empty box removes the last.",
+        words: "The hint is scoped: *Find an Agent*. No match quotes the query: *No Agent matches “Xy”.* A chip reads as the record's name.",
+        access: "A visible label; combobox and listbox roles; each chip's remove is named: *Remove Acme Quotes*. An Agent's orb in a row is a decorative mark beside her name.",
+    },
+    {
+        name: "ModelSelect",
+        module: "agent-profile",
+        family: "Choices",
+        summary: "A model chosen from a list, each read with its maker's mark.",
+        when: "Choosing the model an Agent runs on, from the models the product offers.",
+        instead: "A model shown, not chosen, is `ModelIdentity`. A list people search across many makers is a `Combobox`.",
+        behaviour: "A `Select` whose trigger and every option read the model as `ModelIdentity` does: the maker's mark, one name, the muted maker. It shows `placeholder` until a model is chosen.",
+        words: "Model names come from `modelDisplayName`, or the product's own `nameOf` when its runtime names models itself. The placeholder says what to choose: *Choose a model*.",
+        access: "The trigger takes a visible label; listbox and option roles from Base UI; the marks are decorative beside the names.",
+    },
+    {
+        name: "RadioGroup",
+        module: "radio-group",
+        family: "Choices",
+        summary: "One option of a few, all shown at once.",
+        when: "One of 2 to 6 options that exclude each other, all shown at once.",
+        instead: "Options that each need a sentence are choice tiles. Seven or more is a `Select`; a list to search is a `Combobox`. Another view of the same thing is `Tabs`.",
+        behaviour: "One tab stop for the group; the arrows move and choose. The chosen circle fills with ink and a white 8 px dot. Preselect the safe option when there is one; leave a consequential choice empty until the person makes it.",
+        words: "Options are parallel phrases in sentence case with no end punctuation: *Only me*, *Everyone in the company*. The legend names the setting; it does not ask a question.",
+        access: '`role="radiogroup"` named by its legend, each radio by its label. A disabled option shows why in its own help line.',
+    },
+    {
+        name: "SegmentedChoice",
+        module: "agent-profile",
+        family: "Choices",
+        summary: "One choice among a few short levels, drawn as segments that share a row.",
+        when: "One of two to five short levels a person compares at a glance, such as an Agent's reasoning: Default, Low, Medium, High.",
+        instead: "Options that each need a sentence are choice tiles. Seven or more is a `Select`. The theme is `ThemeModeSwitcher`.",
+        behaviour: "A `RadioGroup` drawn with the toggle classes: one outline, one seam between members, the chosen one in the selection fill. Arrows move and choose; it applies through the form it sits in.",
+        words: "Each segment is one or two words of equal weight, in sentence case.",
+        access: "A `radiogroup` named by its label; each segment a radio named by its word.",
+    },
+    {
+        name: "Select",
+        module: "select",
+        family: "Choices",
+        summary: "A short fixed list in our style, opened from a trigger that shows the choice.",
+        when: "Four to about ten fixed options in our style, each short enough to need no sentence: how often a task runs.",
+        instead: "Two or three options are radios or a segmented control. A list to type into is a `Combobox`. Inside a native form a long list is `NativeSelect`.",
+        behaviour: "The trigger shows the chosen value; the list floats under it with 12 px corners and a check at the chosen row's end. Arrows, typing, Enter, Escape. A placeholder reads in the muted grey and is never an option.",
+        words: "Options are parallel phrases in sentence case: *Every hour*, *Every weekday*. The trigger never says *Select…*.",
+        access: "A visible label tied to the trigger; listbox and option roles from Base UI; focus returns to the trigger on close.",
+    },
+    {
+        name: "Switch",
+        module: "switch",
+        family: "Choices",
+        summary: "A setting that is on or off.",
+        when: "A setting that is either on or off, inside a settings section that saves.",
+        instead: "Choosing or agreeing to something is a `Checkbox`. A tool button that stays pressed is a `Toggle`. Choosing between named values is a `RadioGroup`.",
+        behaviour: "Off is the input grey, on is ink; the thumb travels 16 px. Space flips it. On a settings page the change waits for the section's Save, which lights up; only Theme and Language in the account menu apply at once. A failed save leaves the switch showing the true state.",
+        words: "The label names what on means: *Approvals*, with help saying when. Never *Enable approvals*, and no On/Off text beside the switch.",
+        access: '`role="switch"` with `aria-checked`. The name is the visible label and stays the same in both states. `sm` only inside a dense row.',
+    },
+    {
+        name: "ThemeModeSwitcher",
+        module: "theme-mode-switcher",
+        family: "Choices",
+        summary: "The three appearances side by side, each with its glyph and its name.",
+        when: "An Appearance setting on a settings page, where the choice has room to show its names.",
+        instead: "Inside a menu, the same choice is ThemeModeMenu; a choice that is not the appearance is a RadioGroup or a ToggleGroup.",
+        behaviour: "Exclusive: one mode is selected, and choosing one applies it at once with no Save. The order is System, Light, Dark everywhere.",
+        words: 'The setting\'s name, then each mode\'s name from the product\'s catalogue: "System", "Light", "Dark".',
+        access: "A radio group named by `aria-label`; each mode is a radio with its name, moved through with the arrow keys.",
+    },
+    {
+        name: "Toggle",
+        module: "toggle",
+        family: "Choices",
+        summary: "A button that stays pressed.",
+        when: "A button that stays pressed, where pressing is the action: pin a chat, mute a thread, show hidden rows in a toolbar.",
+        instead: "A setting saved with its section is a `Switch`. Choosing one value of several is a `RadioGroup`, drawn segmented when it is short.",
+        behaviour: "Space or Enter flips `aria-pressed`. Pressed takes the accent fill and weight 600; the label does not change. Hover is the muted fill. Disabled is 50%.",
+        words: "The label is the action and stays the same in both states: *Pin*, never *Pinned* or *Unpin*.",
+        access: "A `button` with `aria-pressed`. An icon-only toggle names what it does: *Pin chat*.",
+    },
+    {
+        name: "ToggleGroup",
+        module: "toggle-group",
+        family: "Choices",
+        summary: "Pressed buttons that belong together.",
+        when: "Pressed buttons that belong together: a list or grid view, which details a chat shows.",
+        instead: "A segmented control that sets a value, such as the theme or a period, is a `RadioGroup` drawn with the toggle classes, as `ThemeModeSwitcher` does. Panels of one object are `Tabs`.",
+        behaviour: "Spacing 0 joins the members into one outline with one seam; spacing 2 keeps them 8 px apart. Single or multiple pressed. Arrow keys move between members; Space presses.",
+        words: "Text members are short words of equal weight. Icon members always carry a name: *List*, *Grid*.",
+        access: '`role="group"` with a name; each member a button with `aria-pressed`.',
+    },
+    {
+        name: "ActionStatus",
+        module: "action-status",
+        family: "Status",
+        summary: "A control's three words on one action: what it does, what it is doing, what it did.",
+        when: "A control that reports its own action: what it does, what it is doing, what it did. Waits under about a second.",
+        instead: "The record's resulting state is a `StatusBadge`. A wait past a second adds one waiting line beside the work. An Agent's work is her orb.",
+        behaviour: "Saving keeps the idle icon, the size and the place; only the word changes. The caller sets `disabled` and `aria-busy`. Done shows the check.",
+        words: "Verb and noun idle (*Save changes*), the verb in progress (*Saving*), the result (*Saved*). No ellipsis. Italian: *Salva modifiche*, *Salvataggio*, *Salvato*.",
+        access: 'The button\'s name is the current word. The result is announced once in a `role="status"` region; a failure as an alert.',
+    },
+    {
+        name: "AgentOrb",
+        module: "agent-orb",
+        family: "Status",
+        summary: "An Agent, anywhere: her orb, the only thing that moves on its own.",
+        when: "An Agent, anywhere: 20 in the sidebar, 32 in a row, 64 on her Profile card, 96 in an Agent card, 160 on entry. There is no other Agent picture.",
+        instead: 'A person is an `Avatar`. The system\'s own wait is the waiting line, never an orb. An orb in artwork takes `motion="ambient"` and claims no activity.',
+        behaviour: "The only thing that moves on its own. Idle turns and breathes; working and thinking show their cue; waiting holds; blocked makes one effort and stops; done celebrates once. Reduced motion: still, busy breathes in opacity.",
+        words: "Text sits beside the orb, never on it. Where the exact state matters a word names it: *Working*, *Waiting for you*.",
+        access: '`role="img"` labelled with the Agent\'s name, and her state where it matters; `decorative` when her name is already beside it.',
+    },
+    {
+        name: "AppMark",
+        module: "app-mark",
+        family: "Status",
+        summary: "An app, a channel or anything else a record connects, in the tile every such mark shares.",
+        when: "A connected app or channel beside its name: a toolkit in the Library, a messaging channel on an Agent. 28 px in a row.",
+        instead: "A model's maker is `ModelMark`. A Library skill is its `IdentityMark` tile. An Agent is her orb. A platform alone, with no tile, is `PlatformMark`.",
+        behaviour: "Draws the catalogue's logo (`composioLogo(toolkit)`), else the platform's mark, else the app's initial; never a guessed logo. The logo takes its dark drawing in a dark theme. The glyph is 62% of the tile.",
+        words: "None of its own; the app's name stands beside it.",
+        access: 'Decorative beside the name. A bare mark takes `label` and becomes `role="img"` with that name.',
+    },
+    {
+        name: "ArchIcon",
+        module: "house-icons",
+        family: "Status",
+        summary: "The house's own icons, the arch, the approvals arch and the Agent, as Lucide components.",
+        when: "Wherever an icon names the company (`ArchIcon`), the work waiting on a person (`ApprovalsIcon`), or Agents as a section (`AgentIcon`). 12, 16, 20 and 24 px; 20 in persistent navigation.",
+        instead: "Lucide for everything else. A particular Agent is her orb, not the agent icon. No Lucide glyph, a circle or a bot, stands in for these three.",
+        behaviour: "Rendered exactly as Lucide: 1.5 px line (1.25 at 12), round caps and joins, no fill except the agent's dot, the text colour. Interchangeable with any Lucide icon wherever a `LucideIcon` is expected.",
+        words: "Always beside its label in navigation: *Agents*, *Approvals*.",
+        access: "Decorative beside text. An icon-only control carries its own `aria-label`.",
+    },
+    {
+        name: "Avatar",
+        module: "avatar",
+        family: "Status",
+        summary: "A person or a team: their picture, else their initials.",
+        when: "A person or a team: the account at the foot of the sidebar, a member list, who changed something. The picture stands in for a person's own photo.",
+        instead: "An Agent is always its `AgentOrb`, never an avatar. A company is its initials in a 6 px tile inside `RecordIdentity`.",
+        behaviour: "A picture that fails falls back to initials, then to the person glyph while the owner is unknown; never blank. A group overlaps 8 px with a 2 px ring of the ground. The profile's 80 px upload button is `AvatarUploadButton`.",
+        words: "Two uppercase initials from the name, else from the email. The overflow is a count: *+2*.",
+        access: "Beside a visible name it is `aria-hidden`. Alone, its alt is the person's name. A group is labelled: *5 members*.",
+    },
+    {
+        name: "Badge",
+        module: "badge",
+        family: "Status",
+        summary: 'Short metadata beside its subject: a role, a plan, "Beta".',
+        when: 'Short metadata beside its subject: a role ("Owner"), a plan, "Beta". 20 px high, 6 px corners, 12 px label at 500. The category fills (teal, purple, pink) name a kind.',
+        instead: "For a state use `StatusBadge`, which picks the tone and its mark: the gray, green, red, amber and blue fills are its alone. For one categorical fact in a row use `Tag`. For a change in a figure, `TrendBadge`.",
+        behaviour: "A static label. It becomes a link only through `render` with a real anchor, which then takes the hover. Never a click handler, never nested, never a paragraph.",
+        words: 'One to three words, sentence case, a noun: "Business plan", not "This is on Business".',
+        access: "Read in place as text. A coloured variant still carries its word.",
+    },
+    {
+        name: "BrandWordmark",
+        module: "brand",
+        family: "Status",
+        summary: "The company logo: nadicode in full.",
+        when: "Wherever the company is named by its logo: the Portal's sidebar, the website's header, a footer. `BrandMark`, the plain n, where the name does not fit.",
+        instead: "A product's own mark (Nadia, Alveare) is that product's. A platform's is `PlatformMark`. The company named in a sentence is text.",
+        behaviour: "The letters take the text colour of what they sit in, so one form serves every ground. The dot is the logo's own colour, which turns to the brighter cobalt under any dark ancestor.",
+        words: "None beyond its name, *nadicode*, written as the glossary defines it.",
+        access: '`role="img"` named *nadicode* by default; pass `alt=""` where the name is already beside it, and it is hidden.',
+    },
+    {
+        name: "FileTypeIcon",
+        module: "file-type-icon",
+        family: "Status",
+        summary: "A file's kind as a Lucide icon, from its path or its language.",
+        when: "Beside a file's name: a file an Agent wrote, a code block's language, an attachment.",
+        instead: "An app is `AppMark`; a Library entry is its `IdentityMark`. A file's content is `CodeBlock` or `FileDiff`.",
+        behaviour: "Maps a path's extension or a language name to one icon: terminal, document, braces, settings, database, diff, palette, regex, globe, package, share; anything else is the code icon.",
+        words: "None; the file's name stands beside it.",
+        access: "Always `aria-hidden`.",
+    },
+    {
+        name: "IdentityMark",
+        module: "identity-mark",
+        family: "Status",
+        summary: "What says which thing a record is, at a fixed size at the start of its row, its object's head or its feed line: an Agent's orb, an app's logo, a company's initials, a person's picture, or a record kind's icon on its tile.",
+        when: "The first thing in a record's row (32), at the head of its object page (64), in a feed or a sidebar identity line (24), on a Library entry (40): wherever it tells a person which thing they are looking at.",
+        instead: "An icon beside a card's title, a KPI's label or a section heading only repeats the words and is left out. A picture for a first use or a whole-page moment is the empty state's or the page's own. A model is its `ModelIdentity`.",
+        behaviour: "Static, except an Agent's orb, which moves with her state. An Agent is always her orb from the orb engine, never an avatar or a painted circle, and `frame` lets the product wrap that orb, such as in the transition that carries her to her page; an app keeps its own logo on the white tile; a company is two initials on the ringed card tile; a person is their picture, then their initials; a record with no picture of its own takes its kind's navigation icon, on the purple ground for a skill and the blue one for a plugin.",
+        words: "None of its own: the record's name stands beside it. Initials are the first letters of the name's first two words.",
+        access: "Decorative beside the record's name. Alone, as in a narrow rail, `label` names it.",
+    },
+    {
+        name: "MetaLabel",
+        module: "label-system",
+        family: "Status",
+        summary: "A small muted label of metadata, and its mono sibling for a command's suffix.",
+        when: "A short fixed fact set beside a name in dense chrome: *Built in*, *Read only*. `CommandSuffix` holds a count or a key after a command.",
+        instead: "A state is `StatusBadge`; a category is `Tag`; a plan or role is `Badge`. A bound shortcut is `Kbd`.",
+        behaviour: "20 px, 6 px corners, the muted fill, never interactive, never wraps.",
+        words: "One or two words in sentence case.",
+        access: "Read in place as text.",
+    },
+    {
+        name: "ModelIdentity",
+        module: "model-identity",
+        family: "Status",
+        summary: "A model as every surface reads it: the maker's mark, one name, the muted maker.",
+        when: "Any place a model is shown: a ranked list, a routing table, a settings row, an option in `ModelSelect`.",
+        instead: "A maker's mark with a name already in hand is `ModelMark`. Choosing a model is `ModelSelect`.",
+        behaviour: "The caller passes the id and nothing else about its shape: the split, the name form and the mark all belong here. An id with no maker prefix falls back to the neutral tile.",
+        words: "The maker's own spelling when the table has it (*Claude Opus 5*), else the id without its maker prefix; a product whose runtime names models passes that `name`.",
+        access: "The name is text; the mark beside it is decorative.",
+    },
+    {
+        name: "ModelMark",
+        module: "model-mark",
+        family: "Status",
+        summary: "A model's maker as LobeHub draws it, in the tile every mark shares, with the model's name beside it when one is given.",
+        when: "A maker's mark beside a name the caller already has, such as a usage row reporting an author slug.",
+        instead: "A model read from its id is `ModelIdentity`, which splits the id and names it. An app is `AppMark`. A platform is `PlatformMark`.",
+        behaviour: "Looks the maker up in LobeHub's set by its slug, through the one table of names that differ. While the mark loads the tile keeps its size; a maker with no mark keeps its initials. The glyph is 62% of the tile, 24 px by default.",
+        words: "The model's name as the product reads it; the maker is never spelled by this component.",
+        access: 'Decorative beside the name. A bare mark takes `label` and becomes `role="img"`; with no name it stays hidden.',
+    },
+    {
+        name: "PlatformMark",
+        module: "platform-mark",
+        family: "Status",
+        summary: "A platform's genuine mark: an operating system, a messaging channel or a sign-in provider.",
+        when: "Naming a platform beside its word: *Continue with Google*, a Telegram channel, the macOS download.",
+        instead: "A connected app in its tile is `AppMark`. A model's maker is `ModelMark`. The company is `BrandMark`.",
+        behaviour: "Drawn at once on the server and in the browser from Iconify's `logos` set, one module per mark; Alveare by its own. A silhouette takes the text colour; a coloured mark keeps its paint.",
+        words: "None of its own; the platform's name always stands beside it.",
+        access: "Always `aria-hidden`: the name beside it is the reading.",
+    },
+    {
+        name: "RecordIdentity",
+        module: "record-identity",
+        family: "Status",
+        summary: 'A record\'s identity in a row (DESIGN.md "Tables and missing values"): its mark at 32, its name, and under it one muted `detail` line saying what the record is or where it comes from, so the row reads without a column heading.',
+        when: "The first cell of every collection row: the mark, the name, and one muted line saying what the record is or where it comes from, so the row reads without a heading.",
+        instead: "An Agent in a gallery is `AgentListRow`; a model is `ModelIdentity`. A descriptive item with prose and actions is `Item`.",
+        behaviour: "The name holds one line and ends in an ellipsis, whole in its title, with a `hint` such as an ID read after it. `wraps` only when the name is the whole record, such as a memory. The detail breaks between words, so a failure inside the row is read whole. The table owns the link.",
+        words: 'The name as the record calls itself. Detail: kind, then relation, three to six words: "Company skill · every Agent has it".',
+        access: "The name is the row link's text; the mark is decorative; the title carries the full name.",
+    },
+    {
+        name: "StatusBadge",
+        module: "status-badge",
+        family: "Status",
+        summary: "A record's state: a mark and a word in one of five tones.",
+        when: "A record's state, when it sets the row apart: failed, waiting on a person, a step in motion, paused, connected. Gray is every terminal state that needs no action.",
+        instead: "For a category (an installation, a partner) use `Tag`. For a control reporting its own action use `ActionStatus`. For a mark beside a word that already names the state, `StatusDot`.",
+        behaviour: "Still: a status never moves and is never a button. Each app keeps one value-to-tone map in one module; nothing else picks a status colour. A healthy record shows no badge.",
+        words: "A state, not a verb: *Failed*, *Waiting for you*. Sentence case, one to three words, no trailing ellipsis. Italian runs a third longer: *In attesa di te*.",
+        access: "The word is the name; the mark is `aria-hidden` and repeats the tone as a shape, so colour never carries the state alone. Not focusable.",
+    },
+    {
+        name: "StatusDot",
+        module: "status-dot",
+        family: "Status",
+        summary: "A small still dot beside a word that already names the state.",
+        when: "A small mark in dense chrome, beside a word that already names the state: a channel, a machine in a list.",
+        instead: "A status that stands alone is a `StatusBadge`. Something in motion is the waiting line or an Agent's orb; the dot has no info tone.",
+        behaviour: "Still; never pulses. Tones are `good`, `muted`, `warn`, `bad`, at full strength.",
+        words: "None of its own. The word beside it says the state.",
+        access: "Always `aria-hidden`. If the word is missing, the state is missing.",
+    },
+    {
+        name: "Tag",
+        module: "tag",
+        family: "Status",
+        summary: "One categorical fact in a row, as a pill.",
+        when: "One categorical fact in a row: the installation, the partner, the company a record belongs to. A 24 px pill with its 12 px mark.",
+        instead: "For a state use `StatusBadge`; a tag never carries one. For a removable filter use `CollectionFilters`. For a way to the thing, a link.",
+        behaviour: "Static, truncates inside its width. The same category keeps the same tone across a surface and after sorting. Dashed and muted when it states an absence.",
+        words: "The thing's own name. A quiet tag names the absence in two or three words (*Direct customer*); the note says whose (*Your account*).",
+        access: "Text; the mark is decorative. Never focusable unless wrapped by a real link.",
+    },
+    {
+        name: "AgentListRow",
+        module: "agent-list-row",
+        family: "Navigation",
+        summary: "One Agent in a list of them: the orb, the name, and the line that says what the Agent is doing now or what it is for.",
+        when: "Nadia's Agents in her window's sidebar, and a website scene that shows a list of Agents.",
+        instead: "An Agent as a record among others in a page's list is a RecordList row with an agent IdentityMark; an Agent's own page heads with ObjectPage.",
+        behaviour: "It is the row's presentation alone: the consumer owns the control around it (Nadia's button that opens the Agent, a scene's list item that opens nothing). The current row's name is set in 500. A state tone puts a 6 px dot before the state line. Narrow, the orb stands alone and the words stay for a screen reader.",
+        words: 'The name, then one state line: what she is doing now ("Answering on Telegram", "Working") or what she is for ("Sorts requests"). The tone never says more than the line does.',
+        access: "The orb is decorative; the name and the state line are the row's text, read by its control. The dot is hidden from assistive technology, so the line carries its meaning.",
+    },
+    {
+        name: "Breadcrumb",
+        module: "breadcrumb",
+        family: "Navigation",
+        summary: "The top bar's path to the page.",
+        when: "The top bar of every product page: the sidebar group or the parents, ending at the destination or the object. An object opened from search still shows its parent.",
+        instead: "Never a back button in its place. A return link may remember a visit, beside the path, not instead of it. Sibling views are tabs.",
+        behaviour: "Ancestors are links in the body colour that turn ink on hover; the current item is ink and not a link. A long path folds its middle into `BreadcrumbEllipsis` and keeps the parent and the current item.",
+        words: "The groups' and records' own names, exactly as the sidebar and the record write them. The `aria-label` and the ellipsis's `label` come from the product's catalogue: \"Path\", \"More\".",
+        access: 'A labelled `nav` with an ordered list; the current item has `aria-current="page"`; the chevrons and the ⋯ glyph are hidden, and the folded middle reads its `label`.',
+    },
+    {
+        name: "CommandDialog",
+        module: "command",
+        family: "Navigation",
+        summary: "Find anything across the product and go there.",
+        when: "Finding anything across the product and going there: an Agent, a customer, a page, a creation command. Opened by ⌘K or the sidebar's Find.",
+        instead: "One record's commands are its `ActionMenu`. Search inside one collection is `CollectionSearch`. Choosing the page's scope is `ScopeSwitcher`.",
+        behaviour: "Opens instantly, a third of the way down, on glass at 12 px corners. Arrows move the highlight, Enter goes, Esc closes and returns focus to the trigger. An empty query shows useful defaults; no match says so.",
+        words: "Groups are plural nouns (*Agents*, *Go to*). Items are names, or verb and noun for a command (*New Agent*). No match quotes the query.",
+        access: "A dialog with a screen-reader title and description; the field is a combobox over a listbox; the highlighted item is `aria-selected`.",
+    },
+    {
+        name: "DashboardShell",
+        module: "dashboard-shell",
+        family: "Navigation",
+        summary: "A web product's frame: the sidebar, the top bar with the page's path, and the content.",
+        when: "The Portal's frame around every signed-in page: its sidebar, the top bar and the scrolling content, with an optional inspector.",
+        instead: "A desktop window is `DesktopAppShell`. A page's own title and actions are `PageHeader` inside the content.",
+        behaviour: "The sidebar can be resized and collapsed to its rail; the content scrolls under the top bar. On a narrow window the sidebar opens as a sheet.",
+        words: "None of its own: the sidebar and the header carry the product's words.",
+        access: "The content is the page's `main`, labelled by `contentLabel`; the inspector is a labelled `aside`; the narrow window's navigation button and the sidebar rail are named.",
+    },
+    {
+        name: "DesktopAppShell",
+        module: "desktop-shell",
+        family: "Navigation",
+        summary: "A desktop window's frame: title bar, rails, resizable panes and status bar.",
+        when: "A desktop product's whole window: Nadia's left column (the Agents list, then an Agent's sections behind *‹ Agents*), its workspace and its side panes.",
+        instead: "The Portal's column is `PortalSidebarFrame` inside `DashboardShell`. Both draw their rows with the same `SidebarMenuButton` and end with the same `AccountMenu`.",
+        behaviour: "One 44 px band shares the window buttons and the window's commands. The workspace splits into resizable panes; the secondary pane and the inspector rail appear only when given. Each Agent row is her orb, name and one line.",
+        words: "Every pane label is the product's word for what it holds. An Agent's line says her job in under six words: *Writes quotes from the price list*.",
+        access: "Each pane and rail is a labelled region; the orb beside a name is decorative.",
+    },
+    {
+        name: "Footer",
+        module: "footer",
+        family: "Navigation",
+        summary: "The always-dark site footer: the brand line, link columns and a meta row.",
+        when: "The foot of every website page and the Portal's public pages.",
+        instead: "A dialog's or a card's footer is its recessed strip. A product's account is `AccountMenu`.",
+        behaviour: 'Always dark, in either theme: it scopes `dark` itself. `mega` adds link columns and one hairline above the meta row; `width="page"` puts it on the website\'s one column. The clock is a pre-formatted string, not a live timer.',
+        words: "Link columns are nouns; the identity paragraph names the company as the glossary defines it.",
+        access: "A `footer` landmark; each link group is a labelled `nav`.",
+    },
+    {
+        name: "NavigationMenu",
+        module: "navigation-menu",
+        family: "Navigation",
+        summary: "A website header's top-level links, some opening a panel of links.",
+        when: "The website's header: a few top-level destinations, where one may open a panel of related pages.",
+        instead: "A product's navigation is its `Sidebar`. Commands are a menu; sibling views are tabs.",
+        behaviour: "Opens on hover and on click; one panel at a time, positioned under its trigger. Escape closes it and returns focus.",
+        words: "Nouns, one or two words, sentence case. A panel's links name their page and may carry one short line.",
+        access: 'A labelled `nav`; triggers expose `aria-expanded`; links are real anchors with `aria-current="page"` on the current one.',
+    },
+    {
+        name: "Pagination",
+        module: "pagination",
+        family: "Navigation",
+        summary: "Numbered sibling pages with Previous and Next.",
+        when: "`Pagination` for numbered sibling pages. A table of server pages takes `DataTable`'s own Previous and Next under its card; the card's footer strip holds the count or the paging.",
+        instead: "Appending rows in place is a `Button` with `PendingLabel` (*Load more*). A fixed comparison passes `pagination={false}` and stays whole.",
+        behaviour: "Boundaries are disabled. While the next page loads both buttons disable and the rows stay. The order and the page live in the URL. The labels hide under `sm`, leaving the chevrons.",
+        words: "*Previous*, *Next*. The footer is a count with its noun or *Page 1 of 6*, never a help sentence.",
+        access: 'A labelled `nav`; the current page has `aria-current="page"`; the arrows read *Go to previous page*; a pending button is `aria-busy`.',
+    },
+    {
+        name: "PortalSidebarFrame",
+        module: "portal-sidebar-frame",
+        family: "Navigation",
+        summary: "The Portal's navigation frame, without the Portal's routing: the wordmark and the section name over the collapse control, the Find control with its shortcut, the labelled nav bands, the band that leads out of the Portal, and the account at the foot.",
+        when: "`PortalSidebarFrame` is the Portal's whole left column, and the website's sample of it.",
+        instead: "Nadia's left column belongs to `DesktopAppShell`. Both draw their rows with the same `SidebarMenuButton` and end with the same `AccountMenu`; neither paints its own selected fill or its own account block.",
+        behaviour: "Wordmark and product name over the collapse control, then Find, the bands, the way out (Get Nadia) and the account, split by 1 px guides.",
+        words: "Find is one word beside ⌘K. Bands are short nouns; items are nouns, one or two words, sentence case.",
+        access: 'The column is a labelled `nav`. Find is a button named with its shortcut. The wordmark is `role="img"` named nadicode.',
+    },
+    {
+        name: "ScopeSwitcher",
+        module: "scope-switcher",
+        family: "Navigation",
+        summary: "Says which part of the account a page reads, and changes it.",
+        when: "Changing which part of the account a page reads, such as Analytics' scope: the whole fleet, one partner, one customer. Only when the viewer has more than one.",
+        instead: "A viewer with one scope and nothing to create reads its name with no control, which this draws by itself. Finding anything is `CommandDialog`; narrowing rows is `CollectionFilters`.",
+        behaviour: "A ghost trigger, at most 16rem, opens a 288 px popover with focus in its search. Type to filter, Enter chooses and closes; choosing the current one changes nothing. The caller writes the choice to the URL in `onValueChange`, so sibling pages keep it. An optional create command sits last.",
+        words: '`copy.label` names what is chosen ("Scope") beside the current scope\'s name. Search and empty lines name the thing: "Find a scope", "No scope matches".',
+        access: 'The trigger reads "Scope: All customers"; the popover has a hidden title; options are a listbox with the current one checked.',
+    },
+    {
+        name: "Sidebar",
+        module: "sidebar",
+        family: "Navigation",
+        summary: "A product's navigation column: where a person can go, with the account at its foot.",
+        when: "The Portal's and Nadia's left column: the groups of places, an object's sections when the column swaps, the update offer and the account menu at the foot.",
+        instead: "An object's sections are SidebarSections inside this column, never a second column or a tab row; a page's own views are Tabs.",
+        behaviour: "One row is selected and marked as the current page. Collapsed or narrow, rows keep their icon and show their name in a tooltip; under the mobile breakpoint the column becomes a sheet. A row's count uses SidebarMenuBadge, whose attention tone is for a failure that needs the person.",
+        words: 'Each row is a place\'s noun: "Agents", "Tasks", "Customers". A count is a bare number.',
+        access: 'The column is a landmark; each row is a link or a button with its name, and the current one carries aria-current="page". The badge\'s number is read with its row.',
+    },
+    {
+        name: "SidebarSections",
+        module: "sidebar-sections",
+        family: "Navigation",
+        summary: "The sidebar swapped to one object: the way back, what you are in, and its sections.",
+        when: "Inside an object, the account or Platform settings, the same sidebar column shows these instead of the places: an Agent's or a Customer's sections in the Portal, Nadia's Edit and her company's sections, the Portal's Account and Platform settings.",
+        instead: "The places a person can go are the sidebar's own groups; a page's views are Tabs; a settings page that does not swap the column is a SettingsPage. Never a second column beside the first.",
+        behaviour: "The back row returns to where the person came from and is disabled while leaving is blocked. One section is current. Narrow, the identity and the heading leave, and each row keeps its icon with its name in a tooltip.",
+        words: 'The back row names where it goes ("Agents", "Back to workspace"); the identity is the object\'s own name; the heading names the kind of settings ("Account"); sections are nouns ("Skills", "Members").',
+        access: 'The sections are a nav named by `label`; the current one carries aria-current="page". The identity\'s mark is decorative beside its name.',
+    },
+    {
+        name: "Tabs",
+        module: "tabs",
+        family: "Navigation",
+        summary: "Panels of one surface that switch in place.",
+        when: "Sibling views of one object that switch in place inside one surface.",
+        instead: "Views with their own URL are `TabsNav`. A choice that changes a value is a `RadioGroup` or `ToggleGroup`. A stable destination belongs in the `Sidebar`. A tab never opens a new scope.",
+        behaviour: "One treatment among siblings, chosen through `variant`, never a page border. Arrow keys move, one tab stop. The underline fades on `confirm`, 180 ms.",
+        words: "Nouns, one or two words: *Overview*, *Installations*. Italian (*Installazioni*) scrolls, never wraps or truncates.",
+        access: "`tablist`, `tab`, `tabpanel` with `aria-selected`.",
+    },
+    {
+        name: "TabsNav",
+        module: "tabs",
+        family: "Navigation",
+        summary: "Sibling views of one object, each with its own URL, under the top bar.",
+        when: "Sibling views of one object under the top bar, when each view has its own URL (an object's sections), with `TabsLink` for each.",
+        instead: "Panels that switch in place are `Tabs`. A stable destination belongs in the `Sidebar`. An object's ancestry is the `Breadcrumb`.",
+        behaviour: "Overflow scrolls sideways and brings the current link into view. The current link takes the underline.",
+        words: "Nouns, one or two words: *Overview*, *Installations*. Italian scrolls, never wraps or truncates.",
+        access: 'A labelled `nav` of links with `aria-current="page"` on the current one.',
+    },
+    {
+        name: "textLinkVariants",
+        module: "text-link",
+        family: "Navigation",
+        summary: "The classes of a link that reads as text: `inline` inside a sentence, `plain` on its own, `quiet` for a muted way out.",
+        when: "A link inside a sentence (`inline`, blue and underlined), a link that stands alone as text (`plain`), or a muted secondary way to somewhere such as a footer's *Learn more* (`quiet`).",
+        instead: "A command is a `Button`; a destination drawn as a button is a link with `buttonVariants`. Going to a record from its row is the record's name in `RecordIdentity`.",
+        behaviour: "Classes only: the caller renders the real anchor or router link. `inline` thickens its underline on hover; `plain` and `quiet` underline on hover. Paint changes ride the shared paint transition.",
+        words: "The link's text names where it goes: *Open Billing*, *Read the privacy notice*; never *Click here* or a bare URL.",
+        access: "A real `a` with an `href`. A link that leaves the product says so in its text or carries the arrow with a name. Focus is the base layer's 2 px outline.",
+    },
+    {
+        name: "AgentCard",
+        module: "agent-card",
+        family: "Data",
+        summary: "One Agent, or another pictured object, as a card in a gallery.",
+        when: "A gallery of Agents or templates where each one is chosen by its picture and its job: the Agents to create from, the templates of a hub.",
+        instead: "A list of Agents to open is `AgentListRow`. An Agent's own page opens with `AgentProfileCard`. A Library entry is `CatalogEntry`.",
+        behaviour: "The picture (her orb at 96) on the leading side, the name and job, an optional status under them, and a footer with the meta and one action. A long name wraps inside the card.",
+        words: "The name as the Agent calls herself; the job in one line (*Writes quotes from the price list*); the action verb and noun (*Use template*).",
+        access: "The name is the card's heading text; the orb is decorative beside it; the action is a real button or link.",
+    },
+    {
+        name: "ApprovalRow",
+        module: "approval-row",
+        family: "Data",
+        summary: "One thing waiting for a person's yes: a mark for what is asking, the request in one sentence, what happened underneath it, and the single action that clears it.",
+        when: "Each request in a list of approvals: a mark for what is asking, the request in one sentence, what happened, and the one action that clears it.",
+        instead: "A record's state is a `StatusBadge`. A notice about a condition is `NoticeBanner`. An Agent's question inside a conversation belongs to the conversation.",
+        behaviour: "An outline `Item` at the small size; several sit in an `ItemGroup`. A `failed` description is announced.",
+        words: "The title is the request as a sentence; the action is its yes as verb and noun: *Approve payment*.",
+        access: 'A `listitem`; a failed description is `role="alert"`.',
+    },
+    {
+        name: "Card",
+        module: "card",
+        family: "Data",
+        summary: "A resting surface that holds one thing: a header, content and a recessed footer.",
+        when: "A bounded piece of a page that stands on its own: a settings section, a KPI, a chart, a table. Usually reached through the composition that owns that job.",
+        instead: "A page's own header is never in a card. A row of a list is `Item`. A plane of brand colour is `BrandField`.",
+        behaviour: 'The resting material: 6 px corners and the rest shadow, no border of its own. `CardHeader` lays out title, description and one `CardAction`; `CardFooter` is the recessed strip behind one seam. `size="sm"` for a compact card in a side column.',
+        words: "The title is a noun phrase naming what the card holds; the description one sentence, only when it adds something.",
+        access: "A plain container; give it `render={<section />}` with a heading when it is a region of the page.",
+    },
+    {
+        name: "CardRow",
+        module: "card-row",
+        family: "Data",
+        summary: "The row sibling cards sit in.",
+        when: "Two to four sibling cards side by side: the KPIs of an overview, a pair of charts.",
+        instead: "A list of records is `Item` or a table. A single card needs no row.",
+        behaviour: "One column below `from`, then `columns` columns; `auto` gives each card an equal share. Each card fills its cell, so the bottom edge is even.",
+        words: "None of its own.",
+        access: "A layout container; reading order is source order.",
+    },
+    {
+        name: "CodeBlock",
+        module: "code-block",
+        family: "Data",
+        summary: "Several lines of exact text to read or copy.",
+        when: "Several lines a person reads or copies exactly: a configuration, static JSON, a command sequence.",
+        instead: "One short value to copy is a read-only input with a `CopyButton`. A before and after is `FileDiff`. Code in a conversation is her `MarkdownText`.",
+        behaviour: "Read-only, no wrapping, scrolls in both directions up to 384 px. Copy takes the exact text, says Copied only on success and says when it failed. No syntax colour, no line numbers.",
+        words: "The real filename, or an honest label. The language as its common name: *JSON*. Copy, Copied, Couldn't copy.",
+        access: "The text area is named by its `label`; the copy button names its target (*Copy mcp.json*) and announces the result.",
+    },
+    {
+        name: "DataTable",
+        module: "data-table",
+        family: "Data",
+        summary: "Records that share comparable facts, read across in rows inside their `TableCard`.",
+        when: 'Records that share comparable facts: usage per Agent, statements, invoices, customers with their partner and count. 40 px rows for figures; `density="comfortable"`, the default, gives 48 px for entity rows.',
+        instead: "An entity collection that is the page's whole job is `CollectionPage`, which draws its own 56 px rows. A descriptive list is `ItemGroup`. One object's facts are `ObjectFacts`.",
+        behaviour: "Headings visible by default; numbers trail in tabular figures. Row hover, focus within and an open menu take `accent`; a selected row takes `muted`; headers and footers never highlight. Narrow cards move facts into a detail row, never scroll sideways; an `optional` column's empty value is left out of it. Empty sits outside the body.",
+        words: 'Headings are nouns with their unit: "Cost (€)", "Tokens". The footer is a count or the paging; the summary row is a labelled total. Italian headings run a third longer and never wrap.',
+        access: 'A native table with `aria-label`; `th scope="col"`; the record\'s name is the row\'s one link. A missing value is a hidden "—" with screen-reader text, never blank.',
+    },
+    {
+        name: "DiffCount",
+        module: "diff-count",
+        family: "Data",
+        summary: "Lines added and removed, as +n and −n.",
+        when: "Beside a file or a change: how many lines it adds and removes.",
+        instead: "The lines themselves are `FileDiff`. A change in a figure is `TrendBadge`.",
+        behaviour: "Renders nothing when both are zero. The numbers roll to a new value; still under reduced motion.",
+        words: "Signed counts with a true minus: *+12 −3*.",
+        access: "Read as text.",
+    },
+    {
+        name: "DisclosureRow",
+        module: "disclosure-row",
+        family: "Data",
+        summary: "A row whose label opens what it holds, with an action and a trailing value beside it.",
+        when: "A line in a dense list that opens to show its detail: a tool call, a group of steps.",
+        instead: "Supporting detail on a page is `Disclosure`. A long block cut short is `ExpandableBlock`.",
+        behaviour: "The chevron shows on hover or focus and while open. Without `onToggle` the row is static and draws no chevron.",
+        words: "The label names what is inside; the trailing value is a short figure.",
+        access: "The label is a `button` with `aria-expanded` when it toggles.",
+    },
+    {
+        name: "FileDiff",
+        module: "file-diff",
+        family: "Data",
+        summary: "A file's before and after, line by line.",
+        when: "Showing what changed in a file an Agent edited, or in a configuration before it is saved.",
+        instead: "A file as it stands is `CodeBlock`. A count of changed lines is `DiffCount`.",
+        behaviour: "Added lines on the success fill with a plus, removed on the destructive fill with a true minus; unchanged lines beyond `context` fold into one marker.",
+        words: "The added and removed labels and the folded-lines count come from the product's catalogue.",
+        access: "Each changed line carries its added or removed label in screen-reader text; the plus and minus marks are hidden.",
+    },
+    {
+        name: "Item",
+        module: "item",
+        family: "Data",
+        summary: "A row said in a sentence: media, a title, one line of description, trailing actions.",
+        when: "Things best said in a sentence: an activity feed, a Library shelf, connected accounts. Media, a title, one line of description, trailing actions.",
+        instead: "Facts that compare across records are a `DataTable`. A page whose job is one collection is `CollectionPage`. Agents in a gallery are `AgentListRow`; Library entries `CatalogEntry`.",
+        behaviour: "Inside a card the group is `divided`: no gaps, one hairline between items. An item that is an `a` or `button` takes the `accent` hover and is one hit target; nested controls stay independent. The title holds one line.",
+        words: "Title: the name, or what happened as a short sentence (*Nadia filed 12 invoices*). Description: one sentence. One primary action as a button; the rest in the three dots.",
+        access: "The group is a `list` and each item a list item. A linked item's text is its name; image media is decorative beside the title.",
+    },
+    {
+        name: "Kbd",
+        module: "kbd",
+        family: "Data",
+        summary: "One key of a shortcut, beside the command it triggers.",
+        when: "A shortcut hint next to the command it triggers: Find with ⌘K, the sidebar with ⌘B. 20 px, 2 px corners, mono 12 on the recessed fill.",
+        instead: "A key a person types into is an `Input`; a code a person types is `InputOTP`. In a command list, `CommandShortcut`.",
+        behaviour: "Not interactive. Only shortcuts actually bound are shown. The caller maps the platform: ⌘ on macOS, Ctrl on Windows and Linux.",
+        words: "One key per `Kbd`; symbols for macOS modifiers (⌘ ⇧ ⌥), words elsewhere (*Ctrl*). Surrounding prose stays outside the key.",
+        access: "A `kbd` element, read in order; the command's own name carries the meaning.",
+    },
+    {
+        name: "MemoryItem",
+        module: "memory-item",
+        family: "Data",
+        summary: "One fact an Agent keeps, under its muted label.",
+        when: "A fact from an Agent's memory shown in her conversation or her profile.",
+        instead: "A fact about a record is `ObjectFacts`. A note a person writes is a `Textarea`.",
+        behaviour: "A short label over the fact; `children` replace the plain `fact` when it needs rich content.",
+        words: "The label is the product's word for memory from the catalogue; the fact is in the Agent's own words.",
+        access: "Read in place as text.",
+    },
+    {
+        name: "ObjectFacts",
+        module: "object-workspace",
+        family: "Data",
+        summary: "An object's facts as labelled values in a grid, inside one of its sections.",
+        when: "Read-only values that describe an object, inside an ObjectSection: a company's legal name, VAT number and address.",
+        instead: "Facts under the object's name belong to ObjectPage's `facts`; values a person changes are SettingsFields in a SettingsSection; figures compared across records are a DataTable.",
+        behaviour: "Two columns from `sm`, one below; `compact` tightens the gaps for a dense card; a `block` fact takes the full width and keeps its line breaks.",
+        words: 'A label is a noun ("Billing email"); a value is the fact itself, with no unit the label already says.',
+        access: "A description list: each label is its value's term and names it.",
+    },
+    {
+        name: "PairingCode",
+        module: "pairing-code",
+        family: "Data",
+        summary: "The short code two screens show at once so a person can tell they are talking to each other, such as the four digits Nadia and Alveare Server both show while a Nadia asks to join.",
+        when: "Pairing two devices or apps a person can see side by side: the four digits Nadia and Alveare Server both show while a Nadia asks to join.",
+        instead: "A code a person types is `InputOTP`. A link another device scans is `QrCode`.",
+        behaviour: "Each digit in its own cell, large enough to compare from across a desk. A leading zero is a digit.",
+        words: "The label says what the code is: *Pairing code*.",
+        access: '`role="img"` named by the label and the digits read one by one.',
+    },
+    {
+        name: "Progress",
+        module: "progress",
+        family: "Data",
+        summary: "A known amount against a real maximum, with its label and value.",
+        when: "A known amount against a real maximum, with its label and value: included runs used against the plan's allowance.",
+        instead: "An unknown wait is the waiting line, never a bar with an invented percentage. A run's consumption in a dense spot is a `UsageMeter`. A single figure is a `KpiCard`.",
+        behaviour: "A 4 px track in the `line` colour. The fill moves only when the reading changes, on `open`; still under reduced motion. `tone` is the product's threshold, never derived from the value. Past the maximum the bar fills and turns red, whatever the tone.",
+        words: 'Print the work and its unit in `ProgressValue`: "620 of 1,000".',
+        access: "A `progressbar` named by its `ProgressLabel` or `aria-label`, with its value.",
+    },
+    {
+        name: "QrCode",
+        module: "qr-code",
+        family: "Data",
+        summary: "A link drawn as a QR code another device can scan.",
+        when: "Opening something on a phone from a screen: a mobile sign-in, a download link.",
+        instead: "Two screens compared by eye is `PairingCode`. A link a person clicks is a link.",
+        behaviour: "Square dark modules on a white tile in every theme, with the quiet zone a reader needs.",
+        words: "The label names what the code opens: *Open Nadia on your phone*.",
+        access: '`role="img"` named by `label`.',
+    },
+    {
+        name: "RecordTime",
+        module: "record-time",
+        family: "Data",
+        summary: "When something happened to a record: a relative time in the sentence that says what, or the time of day in a feed's time column.",
+        when: 'The moment a record was made, changed or last ran, in its row or its facts ("Updated 3 hours ago"), and the time of each event in an ActivityFeed or a RunTimeline step (`mode="clock"`).',
+        instead: 'A date a person picks is a Calendar; a span of days a page reads is a DateRangeControl; a run\'s duration is a fact written by the product ("Took 4 min").',
+        behaviour: "Relative within a week, then the day and month, with the year only when it is another year; `mode=\"clock\"` prints the time of day in the viewer's zone in tabular figures. Hovering either shows the exact moment in UTC and in the viewer's zone. A page rendered on a server passes the viewer's `timeZone` when it knows it, so the server and the browser write the same time; otherwise the server and the hydrating page write UTC and the page then rewrites it in the browser's zone. A time that names no moment draws nothing.",
+        words: 'The product writes the sentence through `phrase` ("Updated {when}", "Ran {when}"); the clock needs no words. The package formats every date with the person\'s `locale`.',
+        access: "A `<time>` element with the machine-readable moment; assistive technology reads the exact local moment after the visible text.",
+    },
+    {
+        name: "RunTimeline",
+        module: "run-timeline",
+        family: "Data",
+        summary: "One run of an Agent, read step by step on a neutral rail.",
+        when: "The steps of one run, in order: a scheduled task's run, an Agent's handoff. Each step is something the run did or will do.",
+        instead: "What happened to a record over time is an ActivityFeed; steps a person follows are NumberedSteps; the stages a system runs on an entry screen are the EntryStageList.",
+        behaviour: 'Each step is a node on one rail, its label and title, one line of detail, and its time at the trailing edge ("—" until it happens). The node marks the step and never grades it: the current step\'s node is ink, a step to come is drawn in the line colour with its title muted. An outcome that needs a person is the StatusBadge inside its step. Nothing moves.',
+        words: 'The label numbers the step ("Step 01"); a done step\'s title is in the past tense ("Filed the invoices"), a step to come in the imperative ("Send the summary to Marco"); a waiting step\'s detail says what it waits for ("Waits for your decision on step 03").',
+        access: 'An ordered list; the current step carries `aria-current="step"`; the rail and nodes are hidden from assistive technology, and so is the dash of a step that has not happened.',
+    },
+    {
+        name: "SettingsFactsSection",
+        module: "settings-facts",
+        family: "Data",
+        summary: "Read-only facts about one object, framed as a card with a title and one action.",
+        when: "Read-only facts about one object: who it is, where it belongs, its identifiers. `SettingsFactsSection` frames them as a card with a title and one action; `ObjectFacts` is the list alone.",
+        instead: "Facts a person changes are a `SettingsSection` with its own Save. Facts compared across records are a table. A relation is its identity or a `Tag`, never its own card.",
+        behaviour: 'Label above value, two equal columns, one column on a phone. Every label stays when its value is missing, as *—*. A long value spans both columns. No fact gets a box of its own. In a side column, `presentation="summary"` drops the card.',
+        words: "Labels are nouns, sentence case, no colon: *VAT number*. Values are exact: identifiers in mono with a copy button, dates in the person's locale.",
+        access: "A `dl` of `dt` and `dd`, each value named by its label. The section is labelled by its heading, which also takes focus when an editor closes. A dash carries screen-reader text.",
+    },
+    {
+        name: "StatusRow",
+        module: "status-row",
+        family: "Data",
+        summary: "One line of a status panel: a mark, what it is, and controls that show on hover.",
+        when: "Lines inside a side panel that report what is running or connected, grouped under a collapsible `StatusSection`.",
+        instead: "A collection's row is `RecordList`'s. A row with a sentence and actions is `Item`.",
+        behaviour: "When `onActivate` is given the whole row is one button that takes the accent hover; the trailing controls show on hover or focus unless `trailingVisible`. A `StatusSection` starts collapsed.",
+        words: "The row names the thing; the section's label is a plural noun.",
+        access: 'An activatable row is `role="button"`, reached by Tab and run by Enter or Space. The section\'s toggle exposes `aria-expanded`.',
+    },
+    {
+        name: "Table",
+        module: "table",
+        family: "Data",
+        summary: "The native table primitive every comparison table is drawn with.",
+        when: "A fixed table a composition draws itself: a summary inside a card, a list of plan limits. A table of records is `DataTable`, which draws this one.",
+        instead: "Records with sorting, paging and an empty state are `DataTable`. A descriptive list is `ItemGroup`. One object's facts are `ObjectFacts`.",
+        behaviour: "Headings visible; numbers trail in tabular figures. Row hover takes `accent`; headers and footers never highlight. `TableDetailRow` and `tableCompactLayouts` move facts into a detail row on a narrow card instead of scrolling sideways.",
+        words: "Headings are nouns with their unit: *Cost (€)*, *Tokens*. Italian headings run a third longer and never wrap.",
+        access: 'A native `table` with a caption or `aria-label`; `th scope="col"`. A missing value is `TableValue`\'s hidden dash, never blank.',
+    },
+    {
+        name: "TableCard",
+        module: "table-card",
+        family: "Data",
+        summary: "The frame a collection's table sits in: a heading, the collection's own toolbar under it, the table, a labelled total, and the recessed footer strip.",
+        when: "A table of records in a card: its heading, its own toolbar, the table, a labelled total and the recessed footer strip.",
+        instead: "An entity collection that is the page's whole job is `CollectionPage`. A chart is `ChartCard`. One object's facts are `SettingsFactsSection`.",
+        behaviour: "The heading, the toolbar and a separator come first when given; the summary row is a labelled total under the table; the footer strip holds the hint on the left and the count or paging on the right.",
+        words: "The title names the collection. The footer is a count or the paging; the summary is a labelled total. Never a help sentence in the footer.",
+        access: "A `section` whose title is an `h2`; the summary is a `dl`.",
+    },
+    {
+        name: "TableValue",
+        module: "table-value",
+        family: "Data",
+        summary: "One cell's value in a table, in each state a reading can be in.",
+        when: "Every cell of a `DataTable` whose reading can be missing, zero, out of date, unreadable or still loading.",
+        instead: 'A whole table that failed to read is `EmptyState kind="failed"`; a figure on its own is a `KpiCard`.',
+        behaviour: 'Five states that never collapse into a dash: unknown (a muted dash), zero (the figure "0"), stale (the reading, then the stale word), failed (the warning mark and its words) and loading (a still 64 × 12 placeholder). A real value, `0` included, is shown as it is.',
+        words: '`missingLabel` says what the absence means ("Not reported", never "N/A" or "None"); `staleLabel` is one word ("Stale"); `failedLabel` says the read failed ("Couldn\'t read").',
+        access: "The dash is hidden and `missingLabel` is read in its place; the warning mark is hidden beside its words; the placeholder is decorative, and the table is `aria-busy` while it loads.",
+    },
+    {
+        name: "UsageMeter",
+        module: "usage-meter",
+        family: "Data",
+        summary: "Consumption against an allowance in a dense spot.",
+        when: "`UsageMeter`: consumption against an allowance in a dense spot, such as a run's tokens and cost.",
+        instead: "A known amount against a real maximum with its label is `Progress`. An unknown wait is the waiting line, never a bar with an invented percentage. A single figure is a `KpiCard`.",
+        behaviour: "The fill moves only when the reading changes, on `transition`; still under reduced motion. The tone is the product's threshold, never derived from the value. Past the maximum the bar fills and turns red.",
+        words: "Print the work and its unit: *620 of 1,000*. The meter's fields are short and set in uppercase mono by the stylesheet, so they are written in sentence case.",
+        access: "The meter's printed figures are the reading; its track is decorative.",
+    },
+    {
+        name: "Alert",
+        module: "alert",
+        family: "Feedback",
+        summary: "The note primitive under every banner and notice: an icon, a title, a description and an action.",
+        when: "Drawing a notice the composition owners do not cover, inside the package. A product's notice is `NoticeBanner` or `MessageNotice`.",
+        instead: "A condition of a page or the account is `NoticeBanner`; a message about one control or section is `MessageNotice`; a finished action is a toast.",
+        behaviour: "A soft ground, deep text, the 1 px line edge, 6 px corners; the icon leads, the action trails.",
+        words: "Title names the condition; the description what it stops; the action the fix as verb and noun.",
+        access: '`role="alert"` by default; a calmer owner passes `status` or `note`. The icon is hidden.',
+    },
+    {
+        name: "EmptyState",
+        module: "empty-state",
+        family: "Feedback",
+        summary: "What a place with nothing in it says: a first use shows its section's picture, a title, one line and the action that fills it; an empty list, a search that found nothing and a read that failed stay quiet.",
+        when: "A collection, a section or a page has nothing to show: it never had a record (`firstUse`), it is empty right now and fills by itself (`nothingYet`), the search or a filter found nothing (`noResults`), or its read failed (`failed`).",
+        instead: "A list's rows still loading are its skeleton rows, never an empty state. A failure of one record's own action is that record's row message. A failure that blocks the whole page, or a notice about the account, is a `NoticeBanner`.",
+        behaviour: "The frame follows the container: a page or a region stands on a resting card with its own edge, inside a card it takes none, and a collection always passes `card`. A first use's picture comes from the one approved set and arrives once, from faint and soft to sharp, after it loads, with no animation under reduced motion; nothing else moves. Only `firstUse` has a picture or a title; only `failed` has a mark, the warning, with its message as an alert and its actions, Retry among them, as outline buttons.",
+        words: 'A first use\'s title names what is missing ("No mailboxes yet") and its line says what will live there and how it fills, in one sentence. A quiet line is one sentence. Clear says what it clears: "Clear search", "Clear filters". A failure is the catalogue\'s message, never a string of the component\'s own.',
+        access: "A first use's title is a heading, level 2 or, inside a titled section, 3. The picture is decorative. A failure is announced as an alert.",
+    },
+    {
+        name: "EntryProgress",
+        module: "entry-scene",
+        family: "Feedback",
+        summary: "Measured work on an entry screen: a 2 px line with the product's written count under it.",
+        when: "Work on an entry screen whose progress is measured: downloading an update, the stages of starting Nadia.",
+        instead: "Work whose length is unknown is a WaitingLine; the named stages themselves are the EntryStageList; measured work inside the product is a Progress with its count.",
+        behaviour: "The line keeps the measured fraction, clamped between empty and full; the count under it is the product's own words. It never prints a percentage.",
+        words: 'The count says what is measured, in tabular figures: "Step 2 of 3", "12 of 40 MB". Never an invented percentage.',
+        access: "The count is a status, so assistive technology hears it change; the line is hidden.",
+    },
+    {
+        name: "EntryStageList",
+        module: "entry-scene",
+        family: "Feedback",
+        summary: "The stages a system runs on an entry screen, each done, current or still to come.",
+        when: 'The real stages of a long setup on an entry screen: installing Nadia, Alveare Server\'s "Get this computer ready".',
+        instead: "Steps the person does are NumberedSteps; the steps of an Agent's run are a RunTimeline.",
+        behaviour: "One mark per stage: done, current, still to come. Followed by the EntryProgress count. Nothing moves but the stage that changes.",
+        words: 'Each stage is what the system does, in the imperative: "Start the chat service".',
+        access: 'An ordered list; the current stage carries `aria-current="step"`; the marks are hidden.',
+    },
+    {
+        name: "HoverCard",
+        module: "hover-card",
+        family: "Feedback",
+        summary: "A preview of a few facts about something named in a dense row.",
+        when: "A preview of a few facts about something named in a dense row: the exact moment behind a relative time, a record's summary.",
+        instead: "For one phrase use `Tooltip`. For anything to edit or keep open use a `Sheet` or the record's page. Never the only way to an action.",
+        behaviour: "Opens on hover and on focus, below by default, 4 px off; stays while the pointer is on it. Solid floating surface, 12 px padding.",
+        words: "Facts, not prose: the date in words, the time with its zone, the machine timestamp. The trigger keeps its verb sentence: *Updated 3 hours ago*.",
+        access: "The trigger is a real element with its own name (a `time` with its `datetime` for a moment), so the facts never depend on hover. Keyboard opening is tested, not assumed.",
+    },
+    {
+        name: "LabelledPicture",
+        module: "picture-label",
+        family: "Feedback",
+        summary: "A failure page's picture with its label, the way a museum labels a work.",
+        when: "A page that cannot show what was asked for: an address or record that is not there (absence), or a request the product stopped (fault). `PictureLabel` is its label.",
+        instead: "For one region that failed inside a working page use `EmptyState failed`; the rest of the page stays. Never turn the whole page into an error because one card failed.",
+        behaviour: "Picture 256 px, 320 from sm, 384 from lg. The label moves beside the base at lg with an empty column of the same width opposite, so the picture keeps the centre line. Still.",
+        words: "Never apologise, never name the mechanism. The label's title says what the picture is doing; the second line gives its materials and year.",
+        access: "The picture is decorative; the label is a `figcaption`, read once. The page's heading is its `h1`; its actions are real links.",
+    },
+    {
+        name: "MessageNotice",
+        module: "message-notice",
+        family: "Feedback",
+        summary: "A catalogue message about one thing on the screen.",
+        when: "A catalogue message about one thing on the screen: under the control whose write failed (`action`), or atop the section whose condition lasts (`section`).",
+        instead: "For a whole page or the account use `NoticeBanner`. For a finished action use a toast. For a field's wrong value use `FieldError`. For a failed read use `EmptyState failed`.",
+        behaviour: "Tone `destructive` by default, `warning` or `info`. Its actions are outline buttons. Long words wrap, nothing truncates. A successful retry removes it. A `section` message with no action is drawn as the passage under a control, because a banner always carries its fix.",
+        words: "From the catalogue only. Title says what happened to which object; body only when it adds something. Action labelled with its result: *Try again*, *Sign in*.",
+        access: '`action`: `role="alert"` (`status` for info). `section`: `role="status"`, `aria-live="polite"`, atomic. Focus stays where the person was.',
+    },
+    {
+        name: "NoticeBanner",
+        module: "notice-banner",
+        family: "Feedback",
+        summary: "A condition of the whole page, the account or the service, with its fix.",
+        when: "A condition of the whole page, the account or the service that the page itself can resolve, with that resolving action on the banner. One at a time, above the page's content, under its title.",
+        instead: 'For one section use `MessageNotice placement="section"`. For a measured level use a `KpiCard` with its tone; crossing a threshold is a notification in the inbox, not a banner.',
+        behaviour: "Tone `neutral` (the plain card fill), `info`, `warning`, `destructive`: a soft ground, deep text, the 1 px line edge, 6 px corners; neutral and info take the Info mark, warning and destructive the TriangleAlert. No close button on an unresolved condition. No action, no banner: `action` is required.",
+        words: 'Title names the condition, description what it stops, the action the fix as verb and noun: "Open Slack settings", "Sign in". Sentence case, no "Please". The words come from the product\'s catalogue code.',
+        access: '`liveRegion="polite"` gives `role="status"`, announced once when it appears; `"off"` gives `role="note"` for one already there at load. The mark is hidden.',
+    },
+    {
+        name: "PendingLabel",
+        module: "pending-label",
+        family: "Feedback",
+        summary: "A control's own label while the system works on what it was asked to do.",
+        when: "Every control that starts work the system does: from the press until the result, whatever the wait. Under about a second it is the only sign. Every save in a footer goes through it.",
+        instead: "Past a second add one `WaitingLine` beside the control. An Agent's work is never this: it is her orb and a sentence. A queued or paused request is a status.",
+        behaviour: "Swaps the word, nothing else: same place, size and icon. The caller sets `disabled` (50% opacity) and `aria-busy` and blocks a second submit, because only the caller knows which element the wait belongs to. Failure returns the rest label.",
+        words: "The rest label's verb in its -ing form with the same noun: *Remove mailbox* to *Removing mailbox*. No ellipsis, no *Please wait*.",
+        access: "`aria-busy` on the control; its name changes to the pending word and is read once. Focus stays on it.",
+    },
+    {
+        name: "Skeleton",
+        module: "skeleton",
+        family: "Feedback",
+        summary: "A still placeholder in the shape of content whose layout is known.",
+        when: "A page or region whose layout is known while its data loads.",
+        instead: "For a wait on something the person pressed use `PendingLabel` and `WaitingLine`. Unknown layout shows nothing until data. Never both a skeleton and a line.",
+        behaviour: "The `line` fill, which stays visible on the card and on the workspace ground in both modes; 6 px corners or a circle, in the final shape so nothing shifts. Never pulses. Resolves to data, an absence or a failure.",
+        words: 'None. No "Loading" text beside it.',
+        access: "The region is `aria-busy`; each placeholder is hidden and never focusable.",
+    },
+    {
+        name: "Toaster",
+        module: "sonner",
+        family: "Feedback",
+        summary: "The one place toasts appear, mounted once per product.",
+        when: "One acknowledgement of an action the person took, when the result is not already visible where they are looking; and the Undo of a reversible removal. Mount it once; raise toasts through `toast`.",
+        instead: "For a failure that must stay, use `MessageNotice` by the control. For unsaved work, failed payment or lost access never a toast alone. For a condition use a banner.",
+        behaviour: "Tone `success`, `info`, `warning`, `error`; mark in the deep step. The first action with a handler becomes its one button. Undo only where a safe rollback exists. A toast that stays up shows the waiting line, not a spinner.",
+        words: "Completion is noun, past participle: *Mailbox removed*, *Agent created*, paired one to one with its button *Remove mailbox*. No *successfully*, no exclamation.",
+        access: "Announced by the toaster's live region. Never the only route to recovery: the record's own row keeps its controls. Undo is reachable by keyboard (Alt+T moves focus to the toasts) while it shows.",
+    },
+    {
+        name: "Tooltip",
+        module: "tooltip",
+        family: "Feedback",
+        summary: "A short, optional fact about its trigger.",
+        when: "A short, optional fact the visible label cannot hold: why a value looks as it does, or an icon-only button's name, a shortcut only when one is bound.",
+        instead: "For a preview with several facts use `HoverCard`. Help with a link uses a popover. A disabled command's reason is written under it, never only here.",
+        behaviour: "Opens on hover and focus with no delay, above by default, 4 px off. Escape closes it. Never interactive; never the only home of a warning, a price or a reason.",
+        words: "One phrase, sentence case, no full stop: *Resets on 1 November*. Never repeats the visible label (*Save* on Save).",
+        access: "The trigger keeps its own name; the tooltip describes it. An icon-only button carries `aria-label` whether or not the tooltip is open.",
+    },
+    {
+        name: "UpdateCard",
+        module: "update-card",
+        family: "Feedback",
+        summary: "The update offer at the foot of a desktop app's sidebar, above the account.",
+        when: "Nadia's and Alveare's sidebar foot, only while an update is on offer or has just been installed.",
+        instead: "A failed update or a download that needs the person is a NoticeBanner; the Portal's way to get the app is its Downloads row.",
+        behaviour: "Available: the title, the version and one full-width command that keeps its place and says its pending word while it runs. Updated: the title, the version and a close. Narrow, the card is one icon button whose tooltip shows the title and the version. Nothing else in the window offers the update.",
+        words: 'The title says what happened ("Update available"), the version names the product and its number ("Nadia 0.42.0"), and the command says its result ("Update and restart").',
+        access: 'The card is a region named by its title. The narrow button is named by its command and the version ("Update and restart: Nadia 0.42.0"), and the close carries its label; a running command is aria-busy.',
+    },
+    {
+        name: "WaitingLine",
+        module: "waiting-line",
+        family: "Feedback",
+        summary: "The one moving thing a system wait may show: a 2 px ink line, after a second.",
+        when: "A system wait the person asked for that runs past a second: a save, a connection, a download without a count.",
+        instead: "Under a second the `PendingLabel` alone. A known amount is a progress line with a count. A page load is `Skeleton`. An Agent working is her orb and a sentence.",
+        behaviour: "Takes its 2 px from the start and stays empty until 1 s, so its arrival moves nothing. No track colour; the segment is ink, never info blue, crossing at 32% width. Under reduced motion it breathes.",
+        words: "None of its own. The control beside it carries the pending word; a standalone line takes a `label` naming the work: *Connecting Telegram*.",
+        access: 'With a label: `role="status"`, announced once after the second. `decorative` when the control beside it already says it. The segment is hidden.',
+    },
+    {
+        name: "AccountMenu",
+        module: "account-menu",
+        family: "Menus",
+        summary: "The account menu at the foot of a shell's navigation: whose account it is, and the menu opening on that same identity with what they can do beneath it.",
+        when: "The account at the sidebar's foot in the Portal, Nadia and Alveare: the gear to the account's settings, Theme, Language, a product's own settings, its commands, and Sign out.",
+        instead: "A record's or a page's commands are an ActionMenu; a setting with more than a few options or one that needs a Save belongs on a SettingsPage.",
+        behaviour: "The menu opens upward on the identity. In order: the gear, Theme, Language, the product's choices as submenus, its commands with any reading at their end, and Sign out last in the error colour. Theme and Language apply at once and keep the menu open. While signing out, Sign out says its pending word, the menu stays open and the trigger is locked; a failure shows under it. A Sign out that `confirms` closes the menu instead, for the product's own confirmation.",
+        words: 'The menu\'s name ("Account"), the person\'s name and lines, then each row\'s noun or verb from the product\'s catalogue: "Theme", "Language", "Usage", "Sign out" and "Signing out".',
+        access: 'The trigger and the menu are named "{label}: {name}"; the gear carries its label; the pending sign-out is aria-busy and announced through a status; a failure is an alert.',
+    },
+    {
+        name: "ActionContextMenu",
+        module: "action-menu",
+        family: "Menus",
+        summary: "A record's menu opened from its row by a right-click: the mirror of its `ActionMenu`.",
+        when: "A right-click or long-press convenience on a record that already has a visible menu with the same commands.",
+        instead: "For anything a person must find use the visible three dots or a button: a context menu is never the only way. For global search use `CommandDialog`.",
+        behaviour: "The dropdown's surface and rows exactly, opening at the pointer. The same commands in the same order, the same disabled reasons, destructive last after a divider. With no command the row renders alone.",
+        words: "Identical to the visible menu's, in the same order; a command reached two ways reads the same both ways.",
+        access: "The Menu key and Shift+F10 open it on the focused row. The menu is named by `label`; Escape closes it and returns focus to the row.",
+    },
+    {
+        name: "ActionMenu",
+        module: "action-menu",
+        family: "Menus",
+        summary: "A record's three dots: the menu of its secondary commands, headed by the record's name.",
+        when: "The secondary commands of one record from a visible trigger: the row's three dots, or the page's, which comes last in the title row.",
+        instead: "For a record's main task use a visible button (Edit opens the row). For finding across everything use `CommandDialog`. For a value to choose use `Select`. For right-click use the mirror, `ActionContextMenu`.",
+        behaviour: "Ghost 36 px trigger that keeps its fill while open. The menu opens aligned to the trigger's end, 6 px below: the record's name, the commands with their icons first and the value one acts on in mono under it, then the destructive ones after a divider in the error colour. Typeahead, arrows, Escape returns focus. A disabled command stays, greyed, with its reason under it. Nothing renders with no command.",
+        words: 'The trigger reads "More for {record}"; the header is the record\'s name. Commands are verb and noun in sentence case, "Remove mailbox", never a bare "Delete". About ten at most; rows wrap, never truncate.',
+        access: 'The trigger is a ghost icon button named by `label`, `aria-expanded` while open. `role="menu"`, items `menuitem` in a group named by the record; the value a command acts on and its reason are the item\'s description; icons hidden.',
+    },
+    {
+        name: "AlertDialog",
+        module: "alert-dialog",
+        family: "Menus",
+        summary: "The blocking dialog primitive under `ConfirmDialog`.",
+        when: "Before an action that stops or loses something, through `ConfirmDialog`, which owns the words and the pending state.",
+        instead: "A product confirms with `ConfirmDialog`, never a hand-built alert dialog. A reversible local change needs no confirmation; give it Undo in a toast.",
+        behaviour: "No backdrop dismissal; Escape cancels. `AlertDialogAction` closes on press; a confirm that can fail is a plain button so the dialog stays open with the error.",
+        words: "Title a statement naming the record, never a question. Body the consequence, once.",
+        access: '`role="alertdialog"`, named by the title and described by the consequence. Focus starts on Cancel, the safe choice.',
+    },
+    {
+        name: "ContextMenu",
+        module: "context-menu",
+        family: "Menus",
+        summary: "A menu that opens at the pointer on a right-click, from the dropdown's own parts.",
+        when: "A right-click on a canvas or a surface no record owns, whose commands are also reachable another way.",
+        instead: "A record's right-click is `ActionContextMenu`, from the same data as its `ActionMenu`. A context menu is never the only way to a command: give it a visible trigger too.",
+        behaviour: "The dropdown's surface and rows exactly, opening at the pointer on the right. Destructive last, after a divider. One level of submenu at most.",
+        words: "Identical to the visible menu's, in the same order; a command reached two ways reads the same both ways.",
+        access: "The Menu key and Shift+F10 open it on the focused element. Escape closes it and returns focus to that element.",
+    },
+    {
+        name: "Dialog",
+        module: "dialog",
+        family: "Menus",
+        summary: "A centred modal for a bounded job the person finishes or cancels.",
+        when: "A new record through a few fields, or one or two values changed from a command: a bounded job the person finishes or cancels. Usually reached through `FormDialog`.",
+        instead: "A record already in a list edits inside its row. A catalogue or a setup in steps is `FormDrawer`. A consequence is `ConfirmDialog`. A linkable workflow is its own page.",
+        behaviour: "Centred, 384 px, 24 px padding, 16 px gaps, 12 px corners, modal height over the 50% scrim. `DialogBody` scrolls between a header and footer that stay. Footer recessed behind a hairline, Cancel then the primary at the trailing edge.",
+        words: "Title is verb and noun (*Add MCP server*); the primary repeats it (*Add server*); the pending word is its -ing form. The failure comes from the catalogue, above the footer.",
+        access: '`role="dialog"` named by its title. Focus starts on the first field, is held inside, returns to the opener. Escape and the named close button dismiss when nothing is running.',
+    },
+    {
+        name: "Drawer",
+        module: "drawer",
+        family: "Menus",
+        summary: "The low-level swipe drawer primitive.",
+        when: "A surface that slides from an edge and follows a swipe. No screen calls it today; screens use `FormDrawer`.",
+        instead: "A catalogue or a setup in steps is `FormDrawer`. Context beside a record is `Sheet`. A few fields are `FormDialog`.",
+        behaviour: "Opens from its swipe direction and follows the finger; nested drawers stack. The header and footer stay while the body scrolls, each drawing the one hairline that separates it.",
+        words: "Title is what it does to which record: *Connect Telegram*.",
+        access: "A modal dialog named by its title with a named close; focus returns to the trigger.",
+    },
+    {
+        name: "DropdownMenu",
+        module: "dropdown-menu",
+        family: "Menus",
+        summary: "A menu that floats from a visible trigger, built from its parts: the surface, labelled groups, commands, choices and dividers.",
+        when: "A menu no composition draws: a column chooser, a sort, a product's own choices in a submenu.",
+        instead: "A record's or a page's commands are `ActionMenu` or `PageActions`' menu, from data. The account's rows are `AccountMenu`. A value to choose in a form is `Select`; finding across everything is `CommandDialog`.",
+        behaviour: "Solid floating surface, 12 px corners, 4 px inset, at least 224 px. Rows 36 px (44 on touch), 12 px padding, accent fill on hover and focus. Opens on click; typeahead, arrows, Escape returns focus to the trigger. A `DropdownMenuCommand` leads with its icon; one that cannot run stays, greyed, with its reason under it.",
+        words: 'Commands are verb and noun in sentence case, "Remove mailbox", never a bare "Delete". About ten at most. Italian runs a third longer; rows wrap, never truncate.',
+        access: '`role="menu"`, items `menuitem`, the trigger `aria-expanded` while open. A command\'s icon is hidden; the value it acts on and its reason are its description.',
+    },
+    {
+        name: "GlassControl",
+        module: "glass-control",
+        family: "Menus",
+        summary: "A control or a bar on glass, floating over content that moves under it.",
+        when: "A control that floats over content passing under it: a period picker over a chart, a bar over the product view.",
+        instead: "A control on a solid ground is drawn plain; glass over nothing reads as a bordered box. A toolbar over its own rows is `CollectionToolbar`.",
+        behaviour: 'The glass material at the floating height; `shape="control"` takes 6 px corners, `shape="bar"` none. The caller renders the element through `render`.',
+        words: "None of its own.",
+        access: "Takes the semantics of what it renders; the glass is paint.",
+    },
+    {
+        name: "MenuChoiceRow",
+        module: "menu-choice-row",
+        family: "Menus",
+        summary: "A named preference inside a menu: its icon and label at the leading edge, the exclusive choices together at the trailing edge, close enough to read as one control.",
+        when: "A setting that applies at once from inside a menu: the account menu's Theme and Language.",
+        instead: "A product's own setting with more choices or longer names is a submenu of radio items (`AccountMenu`'s `choices`). A setting on a page is a `ToggleGroup` or a `Select` in its section.",
+        behaviour: "Icon and label lead, on the commands' 12 px line; the choices sit in one bordered group at the trailing edge. Choosing applies at once and keeps the menu open, so the result shows without reopening it.",
+        words: 'The label is a noun: "Theme", "Language". Each choice carries a full name even when it shows a glyph or a short code: "EN" is named "English".',
+        access: "A radio group named by the label; each choice is a radio named by its `label`, with the same text as its tooltip. The icon is hidden.",
+    },
+    {
+        name: "Menubar",
+        module: "menubar",
+        family: "Menus",
+        summary: "A row of menus, as a desktop application's menu bar.",
+        when: "A desktop surface whose commands are many and grouped, as an application's File and Edit menus are.",
+        instead: "A record's commands are its `ActionMenu`; a page's are `PageActions`. Finding anything is `CommandDialog`.",
+        behaviour: "Each menu has the dropdown's surface and rows. Arrow keys move between menus and through items; Escape closes and returns focus to the bar.",
+        words: "Menu names are single nouns; items are verb and noun in sentence case.",
+        access: '`role="menubar"`; each trigger exposes `aria-expanded`; items are `menuitem`s.',
+    },
+    {
+        name: "Popover",
+        module: "popover",
+        family: "Menus",
+        summary: "A small control set tied to its trigger, on glass.",
+        when: "A small control set tied to its trigger: filters, a scope chooser, a date range, a feedback form. The page stays live behind it.",
+        instead: "For commands use `DropdownMenu`. For a form that adds a record use `FormDialog`. For one phrase use `Tooltip`; for facts on hover use `HoverCard`.",
+        behaviour: "Glass floating surface, 12 px padding and gap. Opens on click, closes on Escape or outside press, focus returns to the trigger. Applies at once; no Save inside.",
+        words: "Title names the control's job (*Filter skills*); an optional one-line description. Options are nouns.",
+        access: "Trigger has a visible name and `aria-expanded`. The popup is a labelled dialog that does not trap focus; Tab leaves it in order.",
+    },
+    {
+        name: "Sheet",
+        module: "sheet",
+        family: "Menus",
+        summary: "A panel beside a record, or the navigation on a narrow window.",
+        when: "Context that belongs beside a record: inspecting a row's details. And the product's navigation when the window is too narrow for the sidebar.",
+        instead: "For a catalogue or steps use `FormDrawer` (built on this). For editing use the row or the record's page. For a blocking decision use `ConfirmDialog`.",
+        behaviour: "From any side, 12 px from the edges, 12 px corners all round, modal over the scrim. Default 3/4 of the window up to 384 px; navigation 288 px. Header 24 px padding; body scrolls; footer recessed.",
+        words: "Title is the record's name, never the page's heading again. A footer link names where it goes: *Open Rossi Ottica*.",
+        access: "A modal dialog named by its title with a named close. Focus returns to the row it inspects, or to the navigation button.",
+    },
+    {
+        name: "ThemeModeMenu",
+        module: "theme-mode-switcher",
+        family: "Menus",
+        summary: "The appearance as one row of a menu: its name and the current mode's glyph leading, the three modes as compact choices at its end.",
+        when: "The account menu's Theme row, in the Portal and in Nadia.",
+        instead: "On a settings page the choice is ThemeModeSwitcher, with its names shown.",
+        behaviour: "Choosing a mode applies it at once and keeps the menu open, so the result shows without reopening it. The order is System, Light, Dark.",
+        words: "The row's name (\"Theme\") and each mode's name, read as the choice's accessible name and tooltip.",
+        access: "A radio group inside the menu, named by the row's label; each mode is a menu radio item with its name.",
+    },
+    {
+        name: "ActivityCalendar",
+        module: "activity-calendar",
+        family: "Charts",
+        summary: "On which days activity happened, as a year of cells.",
+        when: "On which measured days activity happened, over the window the data covers, up to the last 365 days.",
+        instead: "Never added to fill a row. Amounts over time are a bar or area chart. It follows the selected metric and names its own from-to window.",
+        behaviour: "One hue, chart-1, at four steps of opacity over an empty day; a legend from Less to More. Only measured history: unknown coverage stays unknown, never zero.",
+        words: "The window as dates in the description. Each day's label: *8 October 2026: 42 requests*.",
+        access: "Every day is a named cell for assistive technology; the legend steps are named too. Colour is never the only reading: the value is in each label.",
+    },
+    {
+        name: "ChartAreaStacked",
+        module: "chart-area-stacked",
+        family: "Charts",
+        summary: "A continuous volume building up over time, as stacked areas.",
+        when: "A continuous volume building up over time, in three series or fewer: Included usage against Extra usage.",
+        instead: "More than three series, or discrete daily totals, use `ChartBarStacked`. A cap reading is `Progress`.",
+        behaviour: "Stacked natural curves, each filled with its entity's hue at 40% and stroked at full strength. Value axis and dashed grid as every chart.",
+        words: 'Series named for what the person buys: "Included usage", "Extra usage". Axis scale in M; the tooltip prints the exact token count.',
+        access: "Named by its title. A delta that is neither good nor bad, like volume, takes the neutral tone.",
+    },
+    {
+        name: "ChartBarHorizontal",
+        module: "chart-bar-horizontal",
+        family: "Charts",
+        summary: "A signed comparison across entities: profit to the right, loss to the left of a zero line.",
+        when: "Which Customers contribute profit or loss: a signed comparison across entities.",
+        instead: "Never encode a loss as a share. An unsigned ranking is the compact `Progress` ranking or a `DataTable`.",
+        behaviour: "Horizontal bars from a 1.5 px zero line: favourable values to the right in success with right corners rounded, unfavourable to the left in destructive with left corners rounded.",
+        words: "The money unit in the period or the axis. Losses stay negative, written with a true minus: −€360.",
+        access: "Each bar's sign is in its position and its tooltip, never only its colour. Category labels are text, readable without hue.",
+    },
+    {
+        name: "ChartBarMultiple",
+        module: "chart-bar-multiple",
+        family: "Charts",
+        summary: "Grouped bars: two or more measures side by side per period, on one axis in one unit.",
+        when: "Two money measures compared period by period: monthly recurring revenue against model cost.",
+        instead: "Never a second axis: a ratio such as gross margin is a `KpiCard` beside it. One measure split by entity is `ChartBarStacked`.",
+        behaviour: "Bars side by side in series order, 4 px gap, every corner 4 px, at most 48 px wide, one shared value axis on nice steps.",
+        words: 'Series named in full: "Monthly recurring revenue", "Model cost". Months as short names on the axis, the full month in the tooltip.',
+        access: "The plot is named by its title; each bar's figure is in the tooltip and, where the page needs it, a table.",
+    },
+    {
+        name: "ChartBarStacked",
+        module: "chart-bar-stacked",
+        family: "Charts",
+        summary: "One total over time, each bar split by entity; with `share`, one bar split to 100%.",
+        when: "How a total moved over time split by Customer, member account or model; with `share`, what part of one total each holds, with no time axis.",
+        instead: "For a continuous volume in three series or fewer use `ChartAreaStacked`. Two measures side by side use `ChartBarMultiple`. Exact lookup is a table.",
+        behaviour: 'Stacked in series order, bottom segment rounded below and top above at 4 px, bars at most 48 px. The Portal names five entities and folds the rest into "Everything else". The share plot is 64 px, legend included.',
+        words: 'Entity names as the reader knows them, never ids. The neutral remainder is "Everything else". Values through the page\'s shared money formatter.',
+        access: "The plot is an image named by the card title; the tooltip and legend are read with it. The share bar sits above the full-width table that carries each figure.",
+    },
+    {
+        name: "ChartCard",
+        module: "chart-card",
+        family: "Charts",
+        summary: "The card every chart in the kit renders: one header, the summary, the plot, its legend and the reading's time. The plots (`ChartBarStacked`, `ChartAreaStacked`, `ChartBarMultiple`, `ChartBarHorizontal`) hold only their own plot; a page never builds a chart card frame by hand.",
+        when: "Every chart and every reading built around one: the frame a page never builds by hand. A chart is a named section of its page.",
+        instead: "A single figure is a `KpiCard`, never nested inside a chart. A ranking beside the plot goes in the card's `aside`, not a second card.",
+        behaviour: "Header grid: title and period in the first column, controls in the second from a 28 rem card width, under the title below it. Summary, plot, legend, footer in that order. An empty dataset shows its `emptyState` in the plot's place. The footer is a recessed strip behind a hairline: the reading's time left, the link to its owner right.",
+        words: 'Title names the measure and its split: "Model spend by Customer". Period as dates. Footer: the reading\'s time, "Updated 4 minutes ago" or "Read at 12:42", and the way to its owner, "Open in Analytics". Sentence case throughout.',
+        access: "The title is a heading at the page's level (default 2) and labels the plot. The plot is focusable and shows the 2 px focus outline only on keyboard focus.",
+    },
+    {
+        name: "ChartContainer",
+        module: "chart",
+        family: "Charts",
+        summary: "shadcn's chart foundation: the Recharts container, its tooltip and its legend, themed by the series config.",
+        when: "Inside a kit plot only: `ChartBarStacked`, `ChartAreaStacked`, `ChartBarMultiple`, `ChartBarHorizontal`, `ChartSparkline` render through it.",
+        instead: "A page renders a kit plot in its `ChartCard`, never this container or a Recharts import of its own. A chart the kit lacks is pulled from the shadcn registry into the kit first.",
+        behaviour: "Maps each series id to its colour token, sizes the plot to its frame, and draws the tooltip with the exact figure and the legend below the plot: an 8 px dot, 6 px to the name, 16 px between, left-aligned and wrapping.",
+        words: "None of its own: series labels come from the config the plot builds from the page's words.",
+        access: "The plot it holds is named by the card title through `aria-labelledby`; Recharts' accessibility layer makes it keyboard focusable.",
+    },
+    {
+        name: "ChartSparkline",
+        module: "chart-sparkline",
+        family: "Charts",
+        summary: "The stock linear line with nothing around it: no axes, no grid, no tooltip, no card.",
+        when: "What is trending: a row in a list, beside its name and its delta.",
+        instead: "When the reader needs values, axes or a period, use a full chart card. A KPI value carries its delta badge, not a sparkline, unless the card owns one.",
+        behaviour: "96 by 32 px, a 2 px linear line. Stroke is one chart token or the entity's colour.",
+        words: 'None of its own. The row names the measure and the window: "Requests · past 8 weeks".',
+        access: "Decorative by default, hidden from assistive technology, because the value and delta beside it carry the reading. Standalone it takes a `label` and becomes an image.",
+    },
+    {
+        name: "DateRangeControl",
+        module: "chart-date-range-control",
+        family: "Charts",
+        summary: "The period a chart reads: a `Select` of presets with a custom window from a calendar.",
+        when: "The reading period of an overview or a chart: on the title row through `PageActions`' `period`, or in a `ChartCard`'s `controls` where the page has none.",
+        instead: "A choice of metric is a `ToggleGroup` in the card's controls. A date a person enters in a form is a date field.",
+        behaviour: "One select with the presets and a custom window; the value is encoded into the URL by the caller with `encodeDateRange`.",
+        words: 'Presets name the window: "Past 7 days", "Past 14 days", "Past 30 days", "This cycle". A custom window reads as its dates.',
+        access: "The select carries the control's accessible name and announces the current range.",
+    },
+    {
+        name: "KpiCard",
+        module: "kpi-card",
+        family: "Charts",
+        summary: "One measured figure, the way the dashboard-01 section card shows it: the label above the value, the change top right as a badge, and the named comparison in the footer (`rule/kpi-card-trend-top-right`).",
+        when: "One figure a person checks at a glance: Active Agents, Spend, Tasks done, Need attention, in an overview's row of figures.",
+        instead: "A figure read over time is a `ChartCard`, and a single figure is never nested inside one. A ratio beside two money measures is a `KpiCard` next to the chart, never a second axis. A level against a cap is `Progress`.",
+        behaviour: "Label left and the change badge right on the first line, the value under them, the comparison in the footer. A figure with no comparison shows no badge and no empty footer. Direction crossed with whether up is good sets the badge icon's tone: success, blocked, or grey for a flat or neutral measure. `tone` marks the value itself as warning or critical when it crosses a threshold.",
+        words: 'The label names the measure in sentence case: "Active Agents", "Spend". The change is signed with a true minus and its unit ("+12.4%", "−1"), the comparison names the period: "vs 16 last week", "vs August 2026". No icon beside the label.',
+        access: "The trend icon is hidden and the direction is read as a word in the reader's language (`directionLabel`). Figures use tabular digits. The value is text, never only colour.",
+    },
+    {
+        name: "TrendBadge",
+        module: "trend-badge",
+        family: "Charts",
+        summary: "A change against a stated period, as an outline badge with its direction.",
+        when: "A change against a stated period: on a `KpiCard` top right, in a chart's summary, on a Trending row. A figure with no comparison shows no badge.",
+        instead: "A level that crosses a threshold is the card's own tone; crossing it is a notification. Status is a `StatusBadge`, never a delta.",
+        behaviour: "Direction crossed with whether up is good (`trendTone`) sets the icon's tone: success green or blocked red; flat or a neutral measure stays grey. The badge text stays ink.",
+        words: "Signed value with a true minus and its unit (+12.4%, −€360), then *vs previous 30 days* or *vs August 2026*. Never bare signed text, colour alone or a triangle glyph.",
+        access: "The icon is hidden and the direction is read as a word (*up*, *down*, *unchanged*) in the reader's language; tabular figures keep the digits aligned.",
+    },
+    {
+        name: "createEntityColorMap",
+        module: "chart-entity-colors",
+        family: "Charts",
+        summary: 'Assigns `var(--nc-chart-1..6)` in fixed order by FIRST APPEARANCE of each stable entity id. Duplicate ids keep their first assignment. Entities past the sixth unique id fold to the neutral "other" register.',
+        when: "Once per surface, from the full list of entities the page shows, passed to every chart and table row on it.",
+        instead: "Never a hue picked by rank, position or index, and never a colour meaning health or trend: status is a `StatusBadge`, a change is a `TrendBadge`.",
+        behaviour: "A hue follows its entity: one assignment per surface, the same in the chart and its table, stable through filtering and sorting. Six categorical hues colour data and nothing else; past six the tail folds into one neutral series in the muted ink, summed per bucket.",
+        words: 'None of its own. The folded tail is named by the page: "Everything else".',
+        access: "Hue is never the only reading: the legend is always on and every value is text in the tooltip or a table.",
+    },
+    {
+        name: "Accordion",
+        module: "accordion",
+        family: "Other",
+        summary: "Sections that open and close under their headings.",
+        when: "Optional or advanced content in named sections, such as the questions of a help page.",
+        instead: "One piece of supporting detail is `Disclosure`. A long block cut short is `ExpandableBlock`. The page's main answer is never hidden in one.",
+        behaviour: "Related sections may stay open together; exclusive ones open one at a time. The trigger's chevron turns when open.",
+        words: "Each trigger names its topic as a noun phrase or a question a person asks.",
+        access: "Each trigger is a `button` with `aria-expanded` controlling its panel; headings keep the page's outline.",
+    },
+    {
+        name: "AspectRatio",
+        module: "aspect-ratio",
+        family: "Other",
+        summary: "A box that keeps its width-to-height ratio.",
+        when: "A picture or a captured screen that must keep its shape while its width changes.",
+        instead: "A fixed-size mark is its own component (`AppMark`, `AgentOrb`).",
+        behaviour: "The height follows the width at `ratio`; the content fills it.",
+        words: "None of its own.",
+        access: "A layout container; the content keeps its own alternative text.",
+    },
+    {
+        name: "BrandField",
+        module: "brand-field",
+        family: "Other",
+        summary: "BrandField is the fixed white-on-ink identity plane for composition.",
+        when: "A plane of the company's identity on the website or an entry screen, where the brand is the ground.",
+        instead: "A product surface is a `Card` or the page ground. Identity colour as a ground belongs to the website.",
+        behaviour: "Dark by nature: every role and control inside takes its dark value in either theme. No interaction, state or colour variant.",
+        words: "None of its own.",
+        access: "A plain container.",
+    },
+    {
+        name: "Carousel",
+        module: "carousel",
+        family: "Other",
+        summary: "A rail of slides moved with Previous and Next.",
+        when: "A controlled rail of like items on the website: screens, testimonials.",
+        instead: "A product's records are a list or a table, never a carousel. One overflowing row is `ScrollArea`.",
+        behaviour: "Slides move by swipe, drag or the Previous and Next buttons; the buttons disable at the ends. Arrow keys move when the carousel holds focus.",
+        words: "The buttons name their move: *Previous slide*, *Next slide*.",
+        access: "A `region` described as a carousel; each slide is a `group` described as a slide.",
+    },
+    {
+        name: "ChannelView",
+        module: "channel-view",
+        family: "Other",
+        summary: "A work-chat channel, as presentation only: the channel's header, the day it opens on, the messages in it, the replies gathered under a message, a file left in the conversation, and the card a voice call leaves behind.",
+        when: "Showing a channel of Alveare's work chat: its header, its days, messages, replies, files and calls.",
+        instead: "An Agent's conversation is the Agents interface (`@nadicodeai/ui/agents`). A list of records is a list or table.",
+        behaviour: "A 36 px member column, a 10 px gap to the text, the author and the time on one baseline; replies gather in a pill under their message, and cards sit at the resting fill inside the line: Alveare's channel geometry.",
+        words: "The product's members and messages; every label (members, replies, reactions) comes from its catalogue.",
+        access: 'A person\'s picture is `role="img"` named by their name; the member stack is named by `membersLabel`; a reaction is named by its `label`, its glyph hidden.',
+    },
+    {
+        name: "Collapsible",
+        module: "collapsible",
+        family: "Other",
+        summary: "Content that a trigger shows and hides.",
+        when: "Building a disclosure the complete owners do not cover: nested files in a sidebar, a group of rows.",
+        instead: "Supporting detail on a page is `Disclosure`; sections are `Accordion`; a long block is `ExpandableBlock`.",
+        behaviour: "The trigger toggles the content; closed content is not rendered for the reader.",
+        words: "The trigger names what is inside.",
+        access: "The trigger exposes `aria-expanded` and controls its content.",
+    },
+    {
+        name: "CompanyCard",
+        module: "company-card",
+        family: "Other",
+        summary: "The company's nadicode card: what the person is making while they sign up, and what the website shows being issued.",
+        when: "Sign-up, where a person watches their company's card being made, and the website, which shows one being issued.",
+        instead: "A company's facts are `SettingsFactsSection`. A company in a row is its `IdentityMark`.",
+        behaviour: "Fills in as the form is typed and turns to the pointer so its foil catches the light; a company's card takes the cool foil, a Partner's the warm. Still under reduced motion.",
+        words: "Every word it shows is a prop from the product's catalogue.",
+        access: "Hidden from assistive technology and holds nothing interactive; the form beside it carries the same words.",
+    },
+    {
+        name: "Disclosure",
+        module: "disclosure",
+        family: "Other",
+        summary: "Supporting detail a person opens on demand, such as other download formats or a checksum.",
+        when: "Supporting detail a person opens on demand, such as other download formats or a checksum.",
+        instead: "Named sections are `Accordion`. A long block cut short is `ExpandableBlock`. A warning is never hidden in one.",
+        behaviour: "Opens without JavaScript and renders on the server; the chevron turns when open.",
+        words: "The closed label names what is inside: *Other formats*, *Checksum*.",
+        access: "A native `details` and `summary`, announced as a disclosure.",
+    },
+    {
+        name: "ExpandableBlock",
+        module: "expandable-block",
+        family: "Other",
+        summary: "A tall block cut to its first lines, with a control to read the rest.",
+        when: "A long output inside a conversation or a run: a tool's result, a pasted log.",
+        instead: "Supporting detail behind a label is `Disclosure`. Exact text to copy is `CodeBlock`.",
+        behaviour: "Shows the control only when the content runs past 120 px; expanding shows it whole.",
+        words: "The expand and collapse labels come from the product's catalogue.",
+        access: "The control is a `button` with `aria-expanded` and the current label as its name.",
+    },
+    {
+        name: "HiveScene",
+        module: "hive-scene",
+        family: "Other",
+        summary: "Alveare's entry scene: its picture, its logo and six Agent orbs around the words.",
+        when: "Alveare's entry screens, on its desktop and on Alveare Server: joining, loading, a failure.",
+        instead: "Nadia's entry screens are `EntryScene`. A product page never stands on a scene.",
+        behaviour: "`join` puts the words in the hexagon's middle, `loading` draws the orbs in with no words, `still` shows no Agent and no work. Only the orbs and the particles move; reduced motion stops both. Black in every theme.",
+        words: "The words are the screen's own: a title, a line, one action. The logo's label names Alveare.",
+        access: 'The canvases are hidden; the logo\'s image is named by its label. In `loading` the scene is `role="status"` named by `label`; otherwise the words and their action are the reading.',
+    },
+    {
+        name: "NadiaPresence",
+        module: "nadia-presence",
+        family: "Other",
+        summary: "Nadia at an entry screen: her ribbon, arriving through the picture behind her.",
+        when: "Nadia's entry, sign-in and update screens, standing in the middle of `EntryScene`.",
+        instead: "Nadia anywhere else is her `AgentOrb`. A system wait is the waiting line.",
+        behaviour: "`reveal` drives one opacity from a trace to whole; each presence state maps to her orb's state, so a person sees whether she is working, waiting, finished or stopped. 160 px unless the scene sets its size.",
+        words: "The label names the arrival: *Nadia is getting ready*.",
+        access: "A hidden `progressbar` named by `label` carries the same value the person sees; the ribbon is decorative.",
+    },
+    {
+        name: "NumberedSteps",
+        module: "numbered-steps",
+        family: "Other",
+        summary: "Steps a person follows, each with its number, its words and its own action.",
+        when: "A short sequence the person does: installing Nadia from Downloads, connecting Teams, the Dashboard's setup guide; or a sequence whose real progress the page tracks, such as the company check.",
+        instead: 'Stages the system runs on an entry screen are the EntryStageList; the steps of an Agent\'s run are a RunTimeline; a setup with a wait is a FormDrawer with its "Step 2 of 3" line.',
+        behaviour: "Each step is a 28 px square number in label-mono, its title, one muted description and, under it, the step's own action. Instructions mark no step and every number stays muted, because the page cannot know which one the person is on. Where the page tracks real progress, `current` turns that step's number to ink and writes its word beside the title. `framed` draws one bordered list with a seam between steps. It is the one owner of a drawn step number.",
+        words: 'The title is what the person does, in the imperative ("Install Nadia"), or a finished step in the past tense ("Sofia looked up acme.it"). The current step\'s word is short: "Now". An action names its verb and carries its platform line ("macOS · 2.14.0 · Apple silicon").',
+        access: 'An ordered list named by `label`, so assistive technology reads the count and position; the drawn numbers are hidden. The current step carries `aria-current="step"`. The titles are not headings, so the list never breaks the page\'s heading order.',
+    },
+    {
+        name: "PluginSlotBoundary",
+        module: "plugin-slot-boundary",
+        family: "Other",
+        summary: "The frame around content a plugin draws inside a product.",
+        when: "Any surface a plugin renders into: it names the plugin, its permissions and its state around the plugin's own content.",
+        instead: "The product's own sections are `SettingsSection` or `ObjectSection`.",
+        behaviour: "A title and description, the permissions with their levels, a warning or an error when given, then the plugin's content in a labelled region and its footer. `disabled` dims the content.",
+        words: "The plugin's title as the plugin names itself; permissions are short nouns with a sentence each.",
+        access: "The permissions are a labelled list and the plugin's content a region labelled `contentLabel`, so a reader knows where the plugin begins and ends.",
+    },
+    {
+        name: "ReadingColumn",
+        module: "reading-column",
+        family: "Other",
+        summary: "The column a page's content stands in: full, reading or configuration width.",
+        when: "Setting a page's measure: `reading` for prose and conversations, `configuration` for settings, `full` for collections.",
+        instead: "A settings page's column is `SettingsPage`'s. A card row is `CardRow`.",
+        behaviour: "Centred with a maximum width per kind; full takes the content's width.",
+        words: "None of its own.",
+        access: "A layout container.",
+    },
+    {
+        name: "ResizablePanelGroup",
+        module: "resizable",
+        family: "Other",
+        summary: "Panels a person resizes by dragging the handle between them.",
+        when: "Side-by-side panes whose balance a person sets: a conversation and its side panel.",
+        instead: "The product frame's sidebar resizes through `DashboardShell` or `DesktopAppShell`.",
+        behaviour: "The handle moves on drag and on arrow keys; each panel keeps its minimum and maximum.",
+        words: "None of its own.",
+        access: "The handle is the resizable library's focusable separator.",
+    },
+    {
+        name: "ScrollArea",
+        module: "scroll-area",
+        family: "Other",
+        summary: "An area that scrolls with the product's own thin scrollbar.",
+        when: "A bounded area whose content overflows on one axis: a side panel's list, a menu's long body.",
+        instead: "A page scrolls as the document. A rail of slides is `Carousel`.",
+        behaviour: "The viewport scrolls natively, so wheel, touch and keyboard all reach it; the thin scrollbar is drawn over the content.",
+        words: "None of its own.",
+        access: "The content keeps its own semantics; the scrollbar is paint.",
+    },
+    {
+        name: "Separator",
+        module: "separator",
+        family: "Other",
+        summary: "A 1 px line between groups.",
+        when: "Separating groups inside one surface: menu sections, a card's header from its toolbar.",
+        instead: "A card's footer draws its own seam; a list in a card is a `divided` `ItemGroup`. Never a border around a region.",
+        behaviour: "Horizontal or vertical, in the line colour.",
+        words: "None.",
+        access: "A `separator` from Base UI with no name of its own.",
+    },
+    {
+        name: "ToolIcon",
+        module: "tool-icon",
+        family: "Other",
+        summary: "The mark of a tool an Agent used, at the head of its row in the conversation.",
+        when: "A tool call's row in an Agent's conversation: running a command, reading or editing a file, searching, browsing.",
+        instead: "A file in a list takes its `FileTypeIcon`; an app takes its brand mark in `AppMark`; an Agent is her `AgentOrb`.",
+        behaviour: "Lucide's glyph for the tool's kind, 1.5 px line in the text colour, 14 px unless `size` says otherwise. An unknown kind draws the question mark, so a new tool still has a mark.",
+        words: "None. The tool's title stands beside it.",
+        access: "Hidden: the row's title is the name.",
+    },
+];