@maggioli-design-system/magma-react 2.0.1 → 2.2.0

package/agents/components.md

@@ -0,0 +1,129 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# Magma components catalogue (114 components)
+
+> Generated from each component's usage description. Each tag links the component's
+> own `AGENTS.md` (its API, with `pattern.md` and `antipattern.md` beside it) in
+> `@maggioli-design-system/magma/dist/collection/components/<tag>/`. The rules shared by
+> every component: [`conventions.md`](conventions.md), [`variants.md`](variants.md),
+> [`anti-patterns.md`](anti-patterns.md).
+
+| Component | What it is |
+| --------- | ---------- |
+| [`mds-accordion`](../../magma/dist/collection/components/mds-accordion/AGENTS.md) | The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels |
+| [`mds-accordion-item`](../../magma/dist/collection/components/mds-accordion-item/AGENTS.md) | The `<mds-accordion-item>` web component is a single collapsible panel of the Magma Design System, designed to be slotted inside its parent `<mds-accordion>` |
+| [`mds-accordion-timer`](../../magma/dist/collection/components/mds-accordion-timer/AGENTS.md) | The `<mds-accordion-timer>` web component is the orchestrating parent of an auto-advancing accordion in the Magma Design System |
+| [`mds-accordion-timer-item`](../../magma/dist/collection/components/mds-accordion-timer-item/AGENTS.md) | The `<mds-accordion-timer-item>` web component is the single collapsible panel of a timed, auto-advancing accordion, designed to live exclusively inside its parent `<mds-accordion-timer>` |
+| [`mds-author`](../../magma/dist/collection/components/mds-author/AGENTS.md) | The `<mds-author>` web component is the layout primitive of the Magma Design System for presenting a person's identity: it pairs an avatar with author information (name, role, or any related details) |
+| [`mds-avatar`](../../magma/dist/collection/components/mds-avatar/AGENTS.md) | The `<mds-avatar>` web component renders a compact, circular representation of a user or entity in the Magma Design System |
+| [`mds-avatar-stack`](../../magma/dist/collection/components/mds-avatar-stack/AGENTS.md) | The `<mds-avatar-stack>` web component groups a set of overlapping `<mds-avatar-stack-item>` children into a single horizontal cluster, the Magma Design System pattern for showing the people associated with an entity (assignees, participants, collaborators) in a compact, space-saving row. |
+| [`mds-avatar-stack-item`](../../magma/dist/collection/components/mds-avatar-stack-item/AGENTS.md) | The `<mds-avatar-stack-item>` web component is a compound child that represents a single avatar inside an `<mds-avatar-stack>`, wrapping an internal `<mds-avatar>` so individual avatars can be overlapped, sized, and counted as a group rather than rendered standalone. |
+| [`mds-badge`](../../magma/dist/collection/components/mds-badge/AGENTS.md) | The `<mds-badge>` web component is the Magma Design System's compact status and label indicator, used to attach a short categorical signal (count, state, tag) to other content |
+| [`mds-banner`](../../magma/dist/collection/components/mds-banner/AGENTS.md) | The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box. |
+| [`mds-benchmark-bar`](../../magma/dist/collection/components/mds-benchmark-bar/AGENTS.md) | The `<mds-benchmark-bar>` web component is a read-only data-visualization element of the Magma Design System that pairs a labelled caption with a horizontal progress bar to express a single benchmark value on a 0-100 scale |
+| [`mds-bibliography`](../../magma/dist/collection/components/mds-bibliography/AGENTS.md) | The `<mds-bibliography>` web component renders a single citation entry formatted according to a recognized academic style |
+| [`mds-breadcrumb`](../../magma/dist/collection/components/mds-breadcrumb/AGENTS.md) | The `<mds-breadcrumb>` web component is the navigation-trail container of the Magma Design System |
+| [`mds-breadcrumb-item`](../../magma/dist/collection/components/mds-breadcrumb-item/AGENTS.md) | The `<mds-breadcrumb-item>` web component represents a single navigable depth in a breadcrumb trail |
+| [`mds-button`](../../magma/dist/collection/components/mds-button/AGENTS.md) | The `<mds-button>` web component is the primary interactive action control of the Magma Design System |
+| [`mds-button-dropdown`](../../magma/dist/collection/components/mds-button-dropdown/AGENTS.md) | The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control. |
+| [`mds-button-group`](../../magma/dist/collection/components/mds-button-group/AGENTS.md) | The `<mds-button-group>` web component is a layout container of the Magma Design System that clusters related `<mds-button>` controls into a single, evenly-spaced horizontal group such as toolbars, action bars, or segmented sets of actions |
+| [`mds-calendar`](../../magma/dist/collection/components/mds-calendar/AGENTS.md) | The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range |
+| [`mds-calendar-cell`](../../magma/dist/collection/components/mds-calendar-cell/AGENTS.md) | The `<mds-calendar-cell>` web component represents a single selectable day inside the `<mds-calendar>` grid |
+| [`mds-card`](../../magma/dist/collection/components/mds-card/AGENTS.md) | The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region |
+| [`mds-card-content`](../../magma/dist/collection/components/mds-card-content/AGENTS.md) | The `<mds-card-content>` web component is the body region of a `<mds-card>`, grouping the primary textual or component content of a card |
+| [`mds-card-footer`](../../magma/dist/collection/components/mds-card-footer/AGENTS.md) | The `<mds-card-footer>` web component is the footer region of a `<mds-card>`, grouping the trailing content of a card (typically actions such as buttons or supplementary metadata) into the card's bottom region. |
+| [`mds-card-header`](../../magma/dist/collection/components/mds-card-header/AGENTS.md) | The `<mds-card-header>` web component is the header region of a `<mds-card>`, grouping the card's title, supporting text, and optional inline actions |
+| [`mds-card-media`](../../magma/dist/collection/components/mds-card-media/AGENTS.md) | The `<mds-card-media>` web component is the media region of a `<mds-card>`: it wraps an image, video or other visual asset and provides an optional overlay layer for text or controls rendered on top of that asset |
+| [`mds-chip`](../../magma/dist/collection/components/mds-chip/AGENTS.md) | The `<mds-chip>` web component is the Magma Design System's compact element for representing a discrete piece of information, a filter, a selection, or a removable token |
+| [`mds-details`](../../magma/dist/collection/components/mds-details/AGENTS.md) | The `<mds-details>` web component is the disclosure widget of the Magma Design System: a collapsible block with a clickable header that shows or hides its content on demand |
+| [`mds-dropdown`](../../magma/dist/collection/components/mds-dropdown/AGENTS.md) | The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element |
+| [`mds-emoji`](../../magma/dist/collection/components/mds-emoji/AGENTS.md) | The `<mds-emoji>` web component renders one of the Magma Design System's animated mascot illustrations (`mia` or `simi`) as an interactive SVG |
+| [`mds-entity`](../../magma/dist/collection/components/mds-entity/AGENTS.md) | The `<mds-entity>` web component represents a person, organization, or resource as a compact identity block in the Magma Design System, pairing an avatar with a name, optional secondary details, and contextual actions |
+| [`mds-file`](../../magma/dist/collection/components/mds-file/AGENTS.md) | The `<mds-file>` web component is the Magma Design System control for representing a downloadable file as a rich, clickable card |
+| [`mds-file-preview`](../../magma/dist/collection/components/mds-file-preview/AGENTS.md) | The `<mds-file-preview>` web component is the Magma Design System card that previews an uploaded or referenced file, surfacing its name, size, type, and a format-aware icon or thumbnail |
+| [`mds-filter`](../../magma/dist/collection/components/mds-filter/AGENTS.md) | The `<mds-filter>` web component is a compound container that groups a set of `<mds-filter-item>` chips into a single, scrollable filter bar, coordinating their selection state and exposing the active values as one combined change event |
+| [`mds-filter-item`](../../magma/dist/collection/components/mds-filter-item/AGENTS.md) | The `<mds-filter-item>` web component is a single selectable option inside the `<mds-filter>` container of the Magma Design System |
+| [`mds-header`](../../magma/dist/collection/components/mds-header/AGENTS.md) | The `<mds-header>` web component is the top-level page header container of the Magma Design System |
+| [`mds-header-bar`](../../magma/dist/collection/components/mds-header-bar/AGENTS.md) | The `<mds-header-bar>` web component is the top bar of a Magma application layout: it holds the product branding on the left and the primary navigation actions on the right, collapsing those actions into a hamburger menu on smaller viewports |
+| [`mds-help`](../../magma/dist/collection/components/mds-help/AGENTS.md) | The `<mds-help>` web component is a contextual help affordance of the Magma Design System: a small help icon that reveals an explanatory tooltip on interaction |
+| [`mds-horizontal-scroll`](../../magma/dist/collection/components/mds-horizontal-scroll/AGENTS.md) | The `<mds-horizontal-scroll>` web component is a horizontally scrolling container of the Magma Design System |
+| [`mds-hr`](../../magma/dist/collection/components/mds-hr/AGENTS.md) | The `<mds-hr>` web component is the horizontal rule of the Magma Design System |
+| [`mds-icon`](../../magma/dist/collection/components/mds-icon/AGENTS.md) | The `<mds-icon>` web component is the single glyph primitive of the Magma Design System: it inlines an SVG into the DOM so the artwork inherits color and sizing from CSS, and it is the building block that nearly every other component (button, chip, input, banner, list-item, etc.) composes to render its iconography |
+| [`mds-img`](../../magma/dist/collection/components/mds-img/AGENTS.md) | The `<mds-img>` web component is the responsive image primitive of the Magma Design System |
+| [`mds-input`](../../magma/dist/collection/components/mds-input/AGENTS.md) | The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System |
+| [`mds-input-date`](../../magma/dist/collection/components/mds-input-date/AGENTS.md) | The `<mds-input-date>` web component is the Magma Design System control for capturing a single calendar date |
+| [`mds-input-date-range`](../../magma/dist/collection/components/mds-input-date-range/AGENTS.md) | The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range mode) and optional quick-pick presets |
+| [`mds-input-date-range-preselection`](../../magma/dist/collection/components/mds-input-date-range-preselection/AGENTS.md) | The `<mds-input-date-range-preselection>` web component is a compound child of `<mds-input-date-range>` |
+| [`mds-input-field`](../../magma/dist/collection/components/mds-input-field/AGENTS.md) | The `<mds-input-field>` web component is the form-field wrapper of the Magma Design System |
+| [`mds-input-otp`](../../magma/dist/collection/components/mds-input-otp/AGENTS.md) | The `<mds-input-otp>` web component is the Magma Design System control for entering one-time passcodes, rendering a row of single-digit fields that together compose a single form value |
+| [`mds-input-range`](../../magma/dist/collection/components/mds-input-range/AGENTS.md) | The `<mds-input-range>` web component is the Magma Design System slider control for picking a single numeric value from a continuous interval |
+| [`mds-input-select`](../../magma/dist/collection/components/mds-input-select/AGENTS.md) | The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control |
+| [`mds-input-switch`](../../magma/dist/collection/components/mds-input-switch/AGENTS.md) | The `<mds-input-switch>` web component is the binary/selectable input control of the Magma Design System |
+| [`mds-input-tip`](../../magma/dist/collection/components/mds-input-tip/AGENTS.md) | The `<mds-input-tip>` web component is the floating helper container of the Magma Design System input family: it overlays an input field and carries supplementary content (slotted `mds-input-tip-item` chips: status labels, hints, counters) that slides into place when the field becomes active |
+| [`mds-input-tip-item`](../../magma/dist/collection/components/mds-input-tip-item/AGENTS.md) | The `<mds-input-tip-item>` web component is a single contextual hint row rendered inside the `<mds-input-tip>` container |
+| [`mds-input-upload`](../../magma/dist/collection/components/mds-input-upload/AGENTS.md) | The `<mds-input-upload>` web component is the Magma Design System file-upload control |
+| [`mds-keyboard`](../../magma/dist/collection/components/mds-keyboard/AGENTS.md) | The `<mds-keyboard>` web component renders a keyboard shortcut as a row of physical-looking keycaps, acting as the compound parent for one or more slotted `<mds-keyboard-key>` children |
+| [`mds-keyboard-key`](../../magma/dist/collection/components/mds-keyboard-key/AGENTS.md) | The `<mds-keyboard-key>` web component renders a single physical-looking keycap inside a `<mds-keyboard>` parent, supplying the visual unit for one key of a shortcut combination (e.g |
+| [`mds-kpi`](../../magma/dist/collection/components/mds-kpi/AGENTS.md) | The `<mds-kpi>` web component is the layout container of the Magma Design System for presenting groups of key performance indicators |
+| [`mds-kpi-item`](../../magma/dist/collection/components/mds-kpi-item/AGENTS.md) | The `<mds-kpi-item>` web component is a compound child that represents a single key-performance-indicator entry - a prominent numeric `label` with an optional `description` and `icon` - inside its parent container `<mds-kpi>` |
+| [`mds-label`](../../magma/dist/collection/components/mds-label/AGENTS.md) | The `<mds-label>` web component is the Magma Design System tag/chip used to display a short, non-interactive piece of text such as a status, a category, or a removable selection. |
+| [`mds-list`](../../magma/dist/collection/components/mds-list/AGENTS.md) | The `<mds-list>` web component is the structural container of the Magma Design System list family |
+| [`mds-list-item`](../../magma/dist/collection/components/mds-list-item/AGENTS.md) | The `<mds-list-item>` web component is the single entry of a Magma list, designed to be slotted exclusively inside its parent `<mds-list>` |
+| [`mds-mention`](../../magma/dist/collection/components/mds-mention/AGENTS.md) | The `<mds-mention>` web component renders a compact inline chip that references a person or entity - the kind of token produced when you type `@name` in an editor or comment field |
+| [`mds-modal`](../../magma/dist/collection/components/mds-modal/AGENTS.md) | The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop |
+| [`mds-note`](../../magma/dist/collection/components/mds-note/AGENTS.md) | The `<mds-note>` web component is the annotation surface of the Magma Design System: a short, colored sticky-note block used to attach a remark, reminder, or callout to surrounding content |
+| [`mds-notification`](../../magma/dist/collection/components/mds-notification/AGENTS.md) | The `<mds-notification>` web component is a numeric badge/dot indicator of the Magma Design System that attaches to another element (an icon, a button, an avatar) to signal a count of pending items |
+| [`mds-paginator`](../../magma/dist/collection/components/mds-paginator/AGENTS.md) | The `<mds-paginator>` web component is the page-navigation control of the Magma Design System |
+| [`mds-paginator-item`](../../magma/dist/collection/components/mds-paginator-item/AGENTS.md) | The `<mds-paginator-item>` web component is a compound child of `<mds-paginator>` that renders a single clickable cell of the pagination control: either a numbered page or a navigation arrow |
+| [`mds-policy-ai`](../../magma/dist/collection/components/mds-policy-ai/AGENTS.md) | The `<mds-policy-ai>` web component is the Magma Design System disclosure marker that flags AI-generated content as produced by MIA (Maggioli's artificial intelligence) and links to the official AI usage policy |
+| [`mds-pref`](../../magma/dist/collection/components/mds-pref/AGENTS.md) | The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session |
+| [`mds-pref-animation`](../../magma/dist/collection/components/mds-pref-animation/AGENTS.md) | The `<mds-pref-animation>` web component is a preference control that lets users choose how animations are presented (reduced, system-driven, or fully enabled) |
+| [`mds-pref-consumption`](../../magma/dist/collection/components/mds-pref-consumption/AGENTS.md) | The `<mds-pref-consumption>` web component is a preference control of the Magma Design System that lets the user pick an energy-consumption mode (`low`, `medium`, `high`); it is usually a child of `<mds-pref>` and renders as a tab group with one option per mode, so it has no native HTML primitive equivalent. |
+| [`mds-pref-contrast`](../../magma/dist/collection/components/mds-pref-contrast/AGENTS.md) | The `<mds-pref-contrast>` web component is a preference control that lets users switch the application's contrast mode (`more`, `system`, or `no-preference`) |
+| [`mds-pref-language`](../../magma/dist/collection/components/mds-pref-language/AGENTS.md) | The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, designed to be slotted inside `<mds-pref>` alongside the other preference children |
+| [`mds-pref-language-item`](../../magma/dist/collection/components/mds-pref-language-item/AGENTS.md) | The `<mds-pref-language-item>` web component represents a single selectable language option inside the language-preference picker `<mds-pref-language>` |
+| [`mds-pref-mode`](../../magma/dist/collection/components/mds-pref-mode/AGENTS.md) | The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System, designed to live as a direct child of `<mds-pref>` |
+| [`mds-pref-theme`](../../magma/dist/collection/components/mds-pref-theme/AGENTS.md) | The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, designed to live as a direct child of `<mds-pref>` |
+| [`mds-pref-theme-item`](../../magma/dist/collection/components/mds-pref-theme-item/AGENTS.md) | The `<mds-pref-theme-item>` web component is a single selectable theme entry inside the `<mds-pref-theme>` preference picker |
+| [`mds-price-table`](../../magma/dist/collection/components/mds-price-table/AGENTS.md) | The `<mds-price-table>` web component is the layout container of the Magma Design System pricing-table family |
+| [`mds-price-table-features`](../../magma/dist/collection/components/mds-price-table-features/AGENTS.md) | The `<mds-price-table-features>` web component is the feature-matrix block of the Magma Design System pricing-table family |
+| [`mds-price-table-features-cell`](../../magma/dist/collection/components/mds-price-table-features-cell/AGENTS.md) | The `<mds-price-table-features-cell>` web component is a single cell within a feature comparison row of the Magma price table, rendering one of several visual representations (a support icon, plain text, a label, or arbitrary custom content) depending on its `type` |
+| [`mds-price-table-features-row`](../../magma/dist/collection/components/mds-price-table-features-row/AGENTS.md) | The `<mds-price-table-features-row>` web component is a layout child of `<mds-price-table-features>` that represents a single horizontal row inside the feature-comparison table, conceptually playing the role of a table row (`<tr>`). |
+| [`mds-price-table-header`](../../magma/dist/collection/components/mds-price-table-header/AGENTS.md) | The `<mds-price-table-header>` web component is the layout child that forms the top band of a `<mds-price-table>`, aligning an optional leading title cell with the per-plan `<mds-price-table-list>` columns so the header sits in the same column grid as the feature rows below it |
+| [`mds-price-table-list`](../../magma/dist/collection/components/mds-price-table-list/AGENTS.md) | The `<mds-price-table-list>` web component is a single pricing-plan column inside the `<mds-price-table>` layout container |
+| [`mds-price-table-list-item`](../../magma/dist/collection/components/mds-price-table-list-item/AGENTS.md) | The `<mds-price-table-list-item>` web component represents a single feature row inside a `<mds-price-table-list>`, pairing a supported/unsupported status icon with a textual feature label |
+| [`mds-progress`](../../magma/dist/collection/components/mds-progress/AGENTS.md) | The `<mds-progress>` web component is the progress indicator of the Magma Design System, rendering the completion state of a determinate task as a bar or ring |
+| [`mds-push-notification`](../../magma/dist/collection/components/mds-push-notification/AGENTS.md) | The `<mds-push-notification>` web component is the Magma Design System container that hosts and orchestrates a stack of transient notification items, managing their show/hide lifecycle, entry/exit animations, and overall visibility |
+| [`mds-push-notification-item`](../../magma/dist/collection/components/mds-push-notification-item/AGENTS.md) | The `<mds-push-notification-item>` web component is a single notification card rendered inside its parent container `<mds-push-notification>` |
+| [`mds-quote`](../../magma/dist/collection/components/mds-quote/AGENTS.md) | The `<mds-quote>` web component is the Magma Design System primitive for rendering a stylized blockquote: it wraps quoted text in decorative typographic quotation marks (` .. |
+| [`mds-radial-menu`](../../magma/dist/collection/components/mds-radial-menu/AGENTS.md) | The `<mds-radial-menu>` web component is a floating action menu of the Magma Design System that arranges its child items along a circular arc around a central trigger button, expanding them outward when opened |
+| [`mds-radial-menu-item`](../../magma/dist/collection/components/mds-radial-menu-item/AGENTS.md) | The `<mds-radial-menu-item>` web component is a single actionable spoke of the `<mds-radial-menu>` compound |
+| [`mds-radial-progress`](../../magma/dist/collection/components/mds-radial-progress/AGENTS.md) | The `<mds-radial-progress>` web component renders a circular progress indicator that visualizes a completion ratio as a ring with a numeric percentage at its center |
+| [`mds-separator`](../../magma/dist/collection/components/mds-separator/AGENTS.md) | The `<mds-separator>` web component is the visual divider of the Magma Design System: a thin, full-radius horizontal rule used to partition content into distinct groups |
+| [`mds-spinner`](../../magma/dist/collection/components/mds-spinner/AGENTS.md) | The `<mds-spinner>` web component is the Magma Design System's loading/await indicator: a self-contained, animated SVG spinner used standalone or embedded inside host components (`mds-button`, `mds-input`, `mds-entity`) to signal an in-progress, indeterminate operation |
+| [`mds-status-bar`](../../magma/dist/collection/components/mds-status-bar/AGENTS.md) | The `<mds-status-bar>` web component is a persistent action bar of the Magma Design System that docks a small set of actions (typically `mds-button` elements) to an edge of the viewport, accompanied by an optional descriptive label |
+| [`mds-stepper-bar`](../../magma/dist/collection/components/mds-stepper-bar/AGENTS.md) | The `<mds-stepper-bar>` web component is the Magma Design System container that orchestrates a multi-step progress flow, coordinating a set of slotted `<mds-stepper-bar-item>` children and revealing the matching content panel for the active step |
+| [`mds-stepper-bar-item`](../../magma/dist/collection/components/mds-stepper-bar-item/AGENTS.md) | The `<mds-stepper-bar-item>` web component represents a single step inside a `<mds-stepper-bar>` progress indicator, rendering the step's icon, optional ordinal label, descriptive text and status badge |
+| [`mds-tab`](../../magma/dist/collection/components/mds-tab/AGENTS.md) | The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System |
+| [`mds-tab-bar`](../../magma/dist/collection/components/mds-tab-bar/AGENTS.md) | The `<mds-tab-bar>` web component is the compound container of the Magma Design System that groups a set of `<mds-tab-bar-item>` children into a single selectable navigation bar, owning the mutual-exclusion logic that keeps exactly one item active at a time |
+| [`mds-tab-bar-item`](../../magma/dist/collection/components/mds-tab-bar-item/AGENTS.md) | The `<mds-tab-bar-item>` web component is a single selectable tab within the `<mds-tab-bar>` container |
+| [`mds-tab-item`](../../magma/dist/collection/components/mds-tab-item/AGENTS.md) | The `<mds-tab-item>` web component is the individual, clickable tab control of the Magma Design System, designed to be slotted into the default slot of its parent `<mds-tab>` |
+| [`mds-table`](../../magma/dist/collection/components/mds-table/AGENTS.md) | The `<mds-table>` web component is the root container of the Magma Design System tabular data system |
+| [`mds-table-body`](../../magma/dist/collection/components/mds-table-body/AGENTS.md) | The `<mds-table-body>` web component is the row-group container of the Magma Design System tabular data system, used inside `<mds-table>` |
+| [`mds-table-cell`](../../magma/dist/collection/components/mds-table-cell/AGENTS.md) | The `<mds-table-cell>` web component is the data-cell building block of the Magma table, designed to be slotted inside `<mds-table-row>` |
+| [`mds-table-footer`](../../magma/dist/collection/components/mds-table-footer/AGENTS.md) | The `<mds-table-footer>` web component is a structural child of `<mds-table>` that renders the footer row of a table - typically used for totals or summaries |
+| [`mds-table-header`](../../magma/dist/collection/components/mds-table-header/AGENTS.md) | The `<mds-table-header>` web component is the header region of a Magma table, used exclusively as a direct slot child of its parent `<mds-table>` |
+| [`mds-table-header-cell`](../../magma/dist/collection/components/mds-table-header-cell/AGENTS.md) | The `<mds-table-header-cell>` web component is the column-header cell of a Magma data table |
+| [`mds-table-row`](../../magma/dist/collection/components/mds-table-row/AGENTS.md) | The `<mds-table-row>` web component represents a single data row inside a `<mds-table>` (slotted through `mds-table-body`; `mds-table-header` and `mds-table-footer` are rows themselves) |
+| [`mds-text`](../../magma/dist/collection/components/mds-text/AGENTS.md) | The `<mds-text>` web component is the foundational typography primitive of the Magma Design System |
+| [`mds-toast`](../../magma/dist/collection/components/mds-toast/AGENTS.md) | The `<mds-toast>` web component is the transient notification surface of the Magma Design System, used to surface brief, non-blocking feedback messages that appear over the viewport and auto-dismiss after a timeout |
+| [`mds-tooltip`](../../magma/dist/collection/components/mds-tooltip/AGENTS.md) | The `<mds-tooltip>` web component is the floating contextual hint of the Magma Design System |
+| [`mds-tree`](../../magma/dist/collection/components/mds-tree/AGENTS.md) | The `<mds-tree>` web component is the root container of the Magma Design System tree view, organizing a hierarchy of slotted `<mds-tree-item>` nodes into an expandable/collapsible structure |
+| [`mds-tree-item`](../../magma/dist/collection/components/mds-tree-item/AGENTS.md) | The `<mds-tree-item>` web component is the node primitive of the Magma Design System tree view: it represents a single labeled, expandable/collapsible entry inside an `<mds-tree>` and is also the recursive container for its own descendants |
+| [`mds-url-view`](../../magma/dist/collection/components/mds-url-view/AGENTS.md) | The `<mds-url-view>` web component renders an embedded preview of an external web page inside a framed browser-like window, wrapping a native `<iframe>` with a titled header, an identifying icon, and a dismiss control |
+| [`mds-usage`](../../magma/dist/collection/components/mds-usage/AGENTS.md) | The `<mds-usage>` web component is a documentation-oriented annotation block of the Magma Design System used to frame example content as a recommendation, a warning, or an informational note |
+| [`mds-video-wall`](../../magma/dist/collection/components/mds-video-wall/AGENTS.md) | The `<mds-video-wall>` web component is the Magma Design System's full-bleed background video surface, used to render an autoplaying, looping ambient video behind foreground content |
+| [`mds-zero`](../../magma/dist/collection/components/mds-zero/AGENTS.md) | The `<mds-zero>` web component is the empty-state (zero-data) panel of the Magma Design System: a centered, vertically stacked layout that pairs an illustration, explanatory copy, and a call-to-action to guide users when a list, search, or section has no content to show |

package/agents/conventions.md

@@ -0,0 +1,188 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# Magma components - conventions
+
+> Scope: the rules every `mds-*` component follows - naming, boolean props, events,
+> slots, compound components, icons, accessibility, styling from outside. Apply them
+> once; do not re-derive them per component. The `variant` / `tone` axes have their own
+> file: [`variants.md`](variants.md). Mistakes that apply to every component:
+> [`anti-patterns.md`](anti-patterns.md).
+>
+> For one component's API (props with their allowed values, events, methods, slots,
+> parts, CSS custom properties) read its own `AGENTS.md`, listed in
+> [`components.md`](components.md). Do not guess prop names.
+
+## Naming
+
+- Every tag is prefixed `mds-`, lowercase kebab-case.
+- Compound children share the parent prefix: `mds-accordion` / `mds-accordion-item`.
+- Events are camelCase with the component name as prefix: `mdsInputChange`,
+  `mdsAccordionChange`. Listen for the documented event name (the Events table of the
+  component's `AGENTS.md`); do not synthesize your own. A component with no custom event
+  (`mds-button`) is listened to with the native `click`.
+
+## Boolean, disabled and await props
+
+- Boolean props default to `false`/`undefined`. Prefer removing the attribute over
+  setting it to `false`.
+- Disabled: `<mds-button disabled>`. Never `disabled="false"` - remove it instead. Set
+  `disabled` on the component, not on a wrapper: disabled components are removed from
+  the tab order automatically.
+- Async: `<mds-button await>` shows a spinner and blocks interaction; remove `await`
+  (set `undefined`) when done.
+
+## Sizing
+
+Many components expose `size`, with different value sets: `sm` / `md` / `lg` / `xl` on
+`mds-button`, `sm` / `md` / `lg` on `mds-input-switch`, `sm` / `md` on the `mds-pref-*`
+controls, and on `mds-input-select` it is the number of visible rows, as on a native
+`<select>`. Check the component's `AGENTS.md`. Do not override size via inline
+`width`/`height` - use the prop.
+
+## Events
+
+Listen with `addEventListener` or framework bindings. The payload is on `event.detail`:
+
+```javascript
+document.querySelector('mds-input')
+  .addEventListener('mdsInputChange', (e) => console.log(e.detail.value));
+```
+
+```tsx
+// React
+<MdsInput onMdsInputChange={(e) => console.log(e.detail.value)} />
+```
+
+```html
+<!-- Angular -->
+<mds-input (mdsInputChange)="onChange($event)"></mds-input>
+```
+
+## Slots
+
+- The `default` slot accepts plain text only, unless the component's own docs say
+  otherwise.
+- When a component accepts both a `label` prop and a default slot, **prefer the prop**.
+  Slots are for cases where the prop is insufficient and the component explicitly
+  documents accepted slotted content. Never put nested HTML in a default slot expecting
+  it to render - most Magma components strip non-text nodes.
+- Named slots (`slot="header"`, `slot="footer"`) accept HTML and components. When a
+  component documents a named slot (`<mds-notification slot="notification">`), use that
+  exact slot name on the child element. Do not invent slot names.
+- Do not wrap slotted content in arbitrary elements - it can break layout and
+  compound-component communication.
+
+## Compound components
+
+Parent/child pairs communicate internally. Rules:
+
+1. The child must be a **direct slot child** of its parent - no wrappers.
+2. Never use a child outside its parent (no `mds-accordion-item` without `mds-accordion`).
+3. Never mix child types across parents.
+
+```html
+<mds-accordion>
+  <mds-accordion-item>...</mds-accordion-item>
+</mds-accordion>
+```
+
+## Icons
+
+Reference icons by **slug**, never inline `<svg>` and never import an icon package. A
+slug starts with its icon set (`mi/` Material Icons, `mdi/` Material Design Icons, `mgg/`
+Maggioli):
+
+```html
+<mds-icon name="mi/baseline/email"></mds-icon>
+<mds-button icon="mi/baseline/send">Send</mds-button>
+```
+
+`mds-icon` fetches `<mdsIconSvgPath><slug>.svg`; the path is configured once at startup
+(see [`assets.md`](assets.md)): `sessionStorage.setItem('mdsIconSvgPath', '/svg/')`.
+
+## Accessibility
+
+- `mds-button` sets `role="button"` on the host. Icon-only buttons must set `label` or
+  `aria-label`: without them `mds-button` falls back to the last segment of the icon slug
+  (`mi/baseline/send` -> "send"), which names the icon, not the action. Other components
+  that accept `icon` without a label require `aria-label` (or `title`) on the host
+  element: they do not synthesize one.
+- Form components (`mds-input`, `mds-input-date`, `mds-input-date-range`, `mds-input-otp`,
+  `mds-input-range`, `mds-input-select`, `mds-input-switch`, `mds-input-upload`) are
+  form-associated (`formAssociated`) and behave like the native controls they replace:
+  place them inside `<form>` with a `name` and they submit / reset natively.
+  - Submitted value: what the native control would send. A `multiple` select and
+    `mds-input-upload` send one entry per selected option / accepted file (post the form
+    as `multipart/form-data` to send the file contents), a switch sends its `value` only
+    while checked, a radio group sends the one checked; `mds-input-date-range` sends the
+    JSON string `{ startDate, endDate }`.
+  - Form reset: each component goes back to its state of load (the `value` written in
+    the markup, `checked`, the options marked `selected`), shown and submitted.
+  - Validity: `mds-input`, `mds-input-date` and `mds-input-select` report it, and so do
+    the fields of `mds-input-date-range` (against its `min` / `max`) and
+    `mds-input-upload` (a rejected file). An empty `required` field, or one that breaks
+    another rule (`min` / `max`, `minlength` / `maxlength`, `pattern`, the format of the
+    `email`, `url`, `cf`, `isbn`, `piva` and `cc` types), matches `:invalid` and stops the
+    submit, as a native control does. Like `:user-invalid`, the `'error'` look of the
+    fields that have one waits for the user to edit or leave the field, or for a stopped
+    submit. Add `novalidate` to the `<form>` when your own code validates on submit.
+  - Disabled: `disabled`, or a disabled `<fieldset>` around them, disables `mds-input`,
+    `mds-input-date`, `mds-input-date-range`, `mds-input-otp`, `mds-input-range`,
+    `mds-input-select`, `mds-input-switch` and `mds-input-upload` as it does a native
+    control: they cannot be changed and their value is left out of the form.
+  - Buttons: `mds-button` submits (`type="submit"`, the default) or resets
+    (`type="reset"`) its form like a native button. `mds-button-dropdown` does the same from
+    its primary action, but its `type` defaults to `'button'`, so set `type="submit"`; the
+    chevron never submits. With a `name`, the button that submits sends `name=value`, so the
+    receiver tells apart the actions that submit the same form. A custom element cannot be
+    a submitter: `event.submitter` is a hidden native button with the same `name` / `value`,
+    so build the form data with `new FormData(form, event.submitter)`. The menu items of the
+    dropdown are slotted `mds-button`, whose `type` defaults to `'submit'`: inside a form,
+    give `type="button"` to the ones that must not submit it. A disabled `<fieldset>`
+    disables both buttons, as it does a native one. To run the primary action of the
+    dropdown in your own code, listen for `mdsButtonDropdownClick`: a `click` on the
+    dropdown also comes from its menu items.
+- Focus styles: apply `focus-bounce` (interactive elements) or `focus-zoom` (links /
+  static elements). Do not write `:focus { outline: ... }`. Both are Tailwind utilities
+  (`styles/dist/tailwind/utilities.css`); without Tailwind only `focus-zoom` has a plain
+  CSS class, in `styles/dist/css/utility-typography.css`.
+- Use the preference components / classes for high contrast and reduced motion - do not
+  hard-code those styles (see [`theming.md`](theming.md)).
+
+## Styling components from outside
+
+A component's styling API is what its `AGENTS.md` documents:
+
+1. **CSS custom properties** ("CSS custom properties" table), named
+   `--mds-<component>-<prop>`. The first choice: set them on the host element or on a
+   parent selector.
+2. **Shadow parts** ("Parts" table), for a deep customisation the custom properties do
+   not cover. Only the documented part names: they are public API, the rest of the
+   shadow tree is not.
+
+Never reach past that: undocumented parts, internal class names, `>>>` or `/deep/`
+break on any release.
+
+```css
+/* correct */
+mds-button { --mds-button-radius: var(--magma-radius-full); }
+
+.featured-card mds-button {
+  --mds-button-background: rgb(var(--magma-accent-emphasis));
+  --mds-button-radius: var(--magma-radius-lg);
+}
+
+/* correct, deep customisation: `icon` is a documented part of mds-button */
+mds-button::part(icon) { fill: rgb(var(--magma-accent-fg)); }
+
+/* incorrect - internal nodes are not API */
+mds-button >>> .internal { color: red; }
+```
+
+For colour values inside CSS vars name a semantic role, never a palette step: see
+[`color.md`](color.md). For radii use the `--magma-radius-*` scale, which follows the
+corner geometry ([`theming.md`](theming.md)); a raw `--radius-*` or a pixel value does
+not.

package/agents/install.md

@@ -0,0 +1,215 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# install react.md
+
+## Purpose
+
+Install Magma in a React or Next.js app via the React wrapper
+`@maggioli-design-system/magma-react`. The wrapper exposes typed React components
+(`MdsButton`, `MdsText`, ...) over the underlying custom elements.
+
+First do the shared asset setup in [`assets.md`](assets.md) (styles, fonts, icons).
+This file only covers package install and React-specific registration.
+
+## 1. Install
+
+```bash
+npm i @maggioli-design-system/magma-react @maggioli-design-system/magma
+```
+
+`magma-react` follows the same major version as `magma` (see [`AGENTS.md`](../AGENTS.md)
+matrix). Then install the assets from [`assets.md`](assets.md):
+
+```bash
+npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens @maggioli-design-system/svg-icons
+npm i @fontsource/karla @fontsource/merriweather @fontsource/roboto @fontsource/roboto-mono
+```
+
+## 2. Use the components
+
+Import directly from the wrapper - no `defineCustomElements()` call is needed, the
+React components register their custom element on import:
+
+```tsx
+import { MdsText, MdsButton } from '@maggioli-design-system/magma-react';
+
+export default function Component() {
+  return (
+    <>
+      <MdsText typography="h3">Hello World</MdsText>
+      <MdsButton variant="primary" tone="strong">Save</MdsButton>
+    </>
+  );
+}
+```
+
+The package root is a barrel of pure re-exports and the package declares
+`sideEffects: false`, so importing from it is already tree-shakeable - only the
+components you name reach the bundle. Deep imports are available as an escape
+hatch for bundlers that ignore `sideEffects`:
+
+```tsx
+import { MdsButton } from '@maggioli-design-system/magma-react/mds-button.js';
+```
+
+The per-component event types (`MdsButtonEvents`, ...) live in those per-component
+modules, not in the root barrel - import them from the deep path.
+
+## 3. Set the icon path
+
+`window` / `sessionStorage` are not available during SSR, so set the icon path in a
+client effect, once, near the app root:
+
+```tsx
+import { useEffect } from 'react';
+
+export default function App({ children }) {
+  useEffect(() => {
+    sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+  }, []);
+
+  return <>{children}</>;
+}
+```
+
+### Next.js (App Router)
+
+Put the effect in a Client Component and mount it in the root layout:
+
+```tsx
+// client-globals-wrapper.tsx
+'use client';
+import { useEffect } from 'react';
+
+export default function ClientGlobalsWrapper({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  useEffect(() => {
+    sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+  }, []);
+
+  return <>{children}</>;
+}
+```
+
+```tsx
+// app/layout.tsx
+import ClientGlobalsWrapper from './client-globals-wrapper';
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html>
+      <body>
+        <ClientGlobalsWrapper>
+          <main>{children}</main>
+        </ClientGlobalsWrapper>
+      </body>
+    </html>
+  );
+}
+```
+
+## 4. Serve the icon SVGs and styles
+
+- Copy `@maggioli-design-system/svg-icons/dist/svg/` into the static folder served at
+  `/svg/` (Vite/CRA: `public/svg/`; Next.js: `public/svg/`). Match the path you pass
+  to `mdsIconSvgPath`.
+- Import the global CSS block from [`assets.md`](assets.md) in your global stylesheet
+  (`app/globals.css`, `src/index.css`, ...) so the cascade-layer order is preserved.
+
+## 5. Server-side rendering (Next.js)
+
+Every component ships in two variants:
+
+- `@maggioli-design-system/magma-react` (or `.../mds-button.js`) - the client
+  wrapper. During SSR it emits a bare `<mds-button>` tag with **no** attributes,
+  shadow DOM or geometry: the page shifts when the component hydrates.
+- `@maggioli-design-system/magma-react/mds-button.server.js` - the SSR wrapper.
+  On the server it runs `renderToString` from `@maggioli-design-system/magma/hydrate`
+  and emits the full markup - attributes, `<template shadowrootmode="open">` with
+  the component styles, and the `hydrated` flag - so the HTML paints with its
+  final geometry (CLS close to 0). On the client it delegates to the client wrapper.
+
+In an SSR app, import the `.server` variant:
+
+```tsx
+import { MdsButton } from '@maggioli-design-system/magma-react/mds-button.server.js';
+import { MdsText } from '@maggioli-design-system/magma-react/mds-text.server.js';
+
+export default function Page() {
+  return (
+    <>
+      <MdsText typography="h3">Hello World</MdsText>
+      <MdsButton variant="primary" tone="strong">Save</MdsButton>
+    </>
+  );
+}
+```
+
+SSR notes:
+
+- Import each component from its own `.../mds-<name>.server.js` module, or all of them
+  from the server barrel `@maggioli-design-system/magma-react/components.server.js`.
+- The generated server wrappers carry a `'use client'` directive (an
+  output-target quirk): in Next.js they behave as client components that are
+  still server-rendered, which is exactly what produces the declarative shadow
+  DOM in the initial HTML.
+- Events are not wired on the server wrapper; they attach after hydration via
+  the client wrapper it delegates to.
+- Icons render empty server-side (the box is reserved, no layout shift) and the
+  default theme is rendered - see the SSR section in
+  [`install.md`](install.md).
+- The hydrate module (`magma/hydrate`) bundles all 114 components (~3 MB,
+  server-only). It is imported lazily behind a `typeof window` check and must
+  never end up in a client bundle.
+
+## 6. Client-side routing
+
+The links of the components (`href` of `MdsButton`, `MdsTabItem`, ...) are real anchors
+the browser follows, loading the page. Register the router once, in the client wrapper of
+section 3, and every plain click on a component link is routed on the client instead; a
+modifier or middle click, `target="blank"` and a link to another origin stay with the browser.
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { useRouter } from 'next/navigation';
+import { NavigationService } from '@maggioli-design-system/magma/services';
+
+export default function ClientGlobalsWrapper({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  const router = useRouter();
+
+  useEffect(() => {
+    sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+  }, []);
+  // setHandler returns the function that removes the handler: the cleanup of the effect
+  useEffect(() => NavigationService.setHandler((href) => router.push(href)), [router]);
+
+  return <>{children}</>;
+}
+```
+
+With React Router the handler is `(href) => navigate(href)` from `useNavigate()`. Return
+`false` from the handler for a link the browser is to load. Without a registered router, an
+`onClick` on the component can still cancel the click with `preventDefault()` and route by hand.
+
+## Gotchas
+
+- The icon path effect must run on the client. In Next.js App Router the wrapper that
+  sets it must carry `'use client'`.
+- Client wrappers used in Server Components render as custom elements but only hydrate
+  on the client - use the `.server` variants (section 5) to get real SSR markup.
+- Keep `magma` and `magma-react` on the exact same version; the wrapper is generated
+  against a specific `magma` build.
+
+## See also
+
+- [`assets.md`](assets.md) - styles / fonts / icons / identity (canonical)
+- [`conventions.md`](conventions.md) - component conventions, events, slots