@maggioli-design-system/magma-react 2.5.0 → 2.6.0

package/AGENTS.md

@@ -5,7 +5,7 @@
 -->
 # @maggioli-design-system/magma-react - agent install guide
 
-> Version 2.5.0. You (the agent) are installing Magma into THIS project. Do not
+> Version 2.6.0. You (the agent) are installing Magma into THIS project. Do not
 > assume the setup - detect it from the project, then ask the user only for what you
 > cannot infer. The detailed steps live in [`agents/install.md`](agents/install.md)
 > (this target) and [`agents/assets.md`](agents/assets.md) (shared styles, fonts,
@@ -53,14 +53,26 @@ Ask the user only what detection left undecided. Typical questions:
 4. Register components: import the Mds* components from '@maggioli-design-system/magma-react' (no defineCustomElements needed).
 5. Set up editor autocomplete - see [`agents/assets.md`](agents/assets.md) section 5: MERGE the
    keys into `.vscode/settings.json` and `.vscode/extensions.json`, never overwrite them.
+6. Set up the lint - see [`agents/lint.md`](agents/lint.md): the ESLint and Stylelint rules ship
+   in this package; MERGE the Magma presets into the project's ESLint and Stylelint
+   configurations, never overwrite them.
+7. Set up the MCP server - see [`agents/mcp.md`](agents/mcp.md): it ships in this package as
+   the `magma-mcp` command, started with `npx --no magma-mcp` (never without `--no`, which
+   would let npx install a package of that name from the registry). For Claude Code, register
+   the Magma plugin in the project's `.claude/settings.json` instead: it starts the server and
+   adds the Magma skills (`/magma:setup`, `/magma:review`, `/magma:migrate`). For the other
+   clients MERGE the entry into `.vscode/mcp.json` or `.cursor/mcp.json`; never both the
+   plugin and an `.mcp.json` entry, or the server runs twice. Then call its `check_setup`
+   tool: it lists what the integration still misses.
 
 ## Step 4 - verify
 
 Build the app and confirm an `mds-*` component renders and every icon it names loads
 from the configured path (no 404 on `<path><slug>.svg`). In VS Code, check both halves of
 the autocomplete: `var(--magma-` completes Magma tokens in a CSS file and, with Tailwind,
-`bg-surface-default` shows a swatch. Report what was installed, the cascade order used, the
-icon route and the icon path.
+`bg-surface-default` shows a swatch. Run the lint ([`agents/lint.md`](agents/lint.md)): no
+error. Report what was installed, the cascade order used, the icon route, the icon path and
+the lint configuration.
 
 ## Using the components
 
@@ -68,15 +80,18 @@ Once installed, do not guess component APIs or rules - read only the file you ne
 
 | You need | Read |
 | -------- | ---- |
-| Which component to reach for | [`agents/components.md`](agents/components.md) - the catalogue, one line each |
+| Which component to reach for | [`agents/components.md`](agents/components.md) - the catalogue by category, one line each |
 | One component's API (props with allowed values, events, methods, slots, parts, CSS vars) | its `AGENTS.md`, linked from the catalogue |
 | Correct usage and mistakes for one component | `pattern.md` / `antipattern.md` beside its `AGENTS.md` |
 | Rules shared by every component: naming, events, slots, compound, icons, a11y, styling from outside | [`agents/conventions.md`](agents/conventions.md) |
 | `variant` and `tone` values | [`agents/variants.md`](agents/variants.md) |
 | Mistakes to avoid with any component | [`agents/anti-patterns.md`](agents/anti-patterns.md) |
 | Coloring your own UI | [`agents/color.md`](agents/color.md) |
+| Colors in an Android, iOS or Flutter app, where the components do not run | [`agents/color.md`](agents/color.md), "Outside the web" |
 | Typography utilities | [`agents/typography.md`](agents/typography.md) |
 | Dark mode, preferences, named themes, surface levels and elevation, global design decisions, corner geometry | [`agents/theming.md`](agents/theming.md) |
+| Asking instead of reading: the API of a component, the role for a need, a class, an icon slug, a guide section, a snippet checked before writing | the tools of the `magma` MCP server, [`agents/mcp.md`](agents/mcp.md) |
+| Checking what you wrote: run ESLint and Stylelint with the Magma presets after every change, and fix what they report | [`agents/lint.md`](agents/lint.md) |
 | Reporting a problem that is Magma's, not this project's (bug, wrong guide, missing token), with this project's origin label | [`agents/reporting.md`](agents/reporting.md) |
 | What changed between the installed version and a newer one, before upgrading | `CHANGELOG.md` of each Magma package, newest release first (`magma-react` and `magma-angular` carry the releases of `magma`) |
 

package/CHANGELOG.md

@@ -7,6 +7,67 @@ package.
 It is released together with `magma`, at the same version: the sections are the
 releases of `magma`.
 
+## [magma@2.6.0] - 2026-10-24
+
+### Bug Fixes
+
+- *(mds-book)* Cut the caps of a rounded spine on the arc of its slats
+- *(magma,lint)* Start magma-mcp with npx --no, never letting npx install it
+
+### Changes
+
+- *(mds-book)* Show the side-to-side drag with an ew-resize cursor
+
+### Documentation
+
+- *(magma)* Point the Copilot instructions to AGENTS.md
+- *(mds-book)* Show the Catalogue story as a page of a bookshop
+- *(magma,styles)* Allow dark: for a deliberate per-mode choice
+- *(design-tokens,magma)* Document the Android, iOS and Flutter color files
+- *(stencil)* Give an alt to the images of the usage examples, a name to the paginator arrows
+- *(magma)* Set up the lint at bootstrap and run it after every change
+- *(magma)* Set up the MCP server at bootstrap and say when to call each tool
+- *(magma)* Get the Claude Code plugin at bootstrap, the MCP entry for the other clients
+- *(magma,stencil)* Describe the component categories and group the reference by them
+- *(storybook)* File the component stories under their categories, keeping their URLs
+- *(magma,stencil)* Describe where a component page sits in Storybook
+- *(magma)* Name only public CSS custom properties in the usage docs
+- *(magma)* The contract of the component CSS custom properties
+
+### Features
+
+- *(mds-book)* Add a book drawn as a physical object in 3D from its front cover
+- *(lint)* Add the ESLint and Stylelint rules that check consumer code against the installed Magma
+- *(lint)* Point no-color-scheme-override to the dark variant for a per-mode choice
+- *(magma,lint)* Ship the consumer lint inside magma as ./eslint and ./stylelint
+- *(lint)* The MCP server, ten read-only tools on the data of the installed magma
+- *(magma,lint)* Ship the MCP server in magma as the magma-mcp command
+- *(lint)* Check_setup counts the Magma plugin as the MCP server of Claude Code
+- *(stencil)* Sort the components into categories, their parts under their parent
+- *(stencil)* Carry the public or internal mark of each CSS custom property
+- *(magma)* Promise 184 CSS custom properties, the other 520 are internal
+- *(lint)* Reject internal custom properties, let the static ones take a colour
+
+### Styling
+
+- *(mds-push-notification)* Paint the light fade with --magma-surface-sunken
+
+## [magma@2.5.1] - 2026-10-22
+
+### Bug Fixes
+
+- *(mds-stepper-bar-item)* Show the status of the step in its badge
+- *(mds-input-range)* Draw a light thumb in dark, apart from the progress
+- *(mds-input-range)* Keep the disabled colours in dark
+- *(mds-input)* Show the validation messages in the language of the page
+- *(mds-input-select)* Emit no change on load, before any selection
+- *(mds-status-bar)* Keep the bar inside its area at 480px and less
+- *(mds-keyboard)* Start the test with Enter without failing it at once
+- *(mds-input)* Wait for the first blur to validate a required field
+- *(mds-emoji)* Draw the emoji in Firefox, keep the inner svg flat
+- *(mds-input)* Report maxlength and minlength under their own error keys
+- *(stencil)* Give a page language with a region the texts of its base language
+
 ## [magma@2.5.0] - 2026-10-21
 
 ### Bug Fixes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Maggioli S.p.A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agents/assets.md

@@ -389,7 +389,7 @@ names through functions (`clsx`, `cva`, `cn`), list the ones it uses in
 
 Verify, after reloading the window:
 
-- in a CSS file, `var(--magma-surface` lists the surface roles, in order, with swatches;
+- in a CSS file, `var(--magma-surface-` lists the surface roles, in order, with swatches;
 - with Tailwind, in markup: hovering `p-600` shows `1.5rem = 24px`, and `bg-surface-default`
   shows a swatch in the completion list. No swatch on the semantic classes means an older
   `@maggioli-design-system/styles`: update it.

package/agents/color.md

@@ -16,15 +16,15 @@ Paint your UI with the semantic roles (`--magma-*`), not with a raw palette step
 with Tailwind's own palette:
 
 ```html
-<!-- correct: roles follow the mode, the named theme and high contrast -->
+<!-- CORRECT: roles follow the mode, the named theme and high contrast -->
 <section class="bg-surface-raised text-fg-default border border-border-muted">
   <p class="text-fg-muted">Secondary text</p>
 </section>
 
-<!-- incorrect: raw Magma steps only flip with the mode -->
+<!-- INCORRECT: raw Magma steps only flip with the mode -->
 <section class="bg-tone-neutral-seed text-tone-neutral-01 border-tone-neutral-09">...</section>
 
-<!-- incorrect: Tailwind's palette ignores Magma entirely -->
+<!-- INCORRECT: Tailwind's palette ignores Magma entirely -->
 <section class="bg-white text-gray-700">...</section>
 ```
 
@@ -150,7 +150,11 @@ measured.
   what the element is, not by the shade you want, and give `raised` / `overlay` a shadow
   ([`theming.md`](theming.md#surfaces-and-elevation)). A grey that has to look marked in
   both modes (a pill, a chip, a hover) is a wash, not a surface.
-- **No `dark:` variants and no dark-mode media queries.** The roles already flip.
+- **The roles already flip: `dark:` never corrects them.** Keep `dark:` for a deliberate
+  choice that differs per mode (a well that sits on the page in light and rises to
+  `surface-raised` in dark). It follows the Magma mode, `system` included
+  ([`theming.md`](theming.md#dark-mode-and-preferences)), in the light DOM only. Never
+  write a dark-mode media query by hand.
 
 ## When a raw palette colour is right
 
@@ -170,6 +174,20 @@ with `data-theme-name` ([`theming.md`](theming.md)), do not paint them by hand.
 Deprecated: `--magma-neutral-emphasis` / `--magma-neutral-on-emphasis` are aliases of
 `--magma-surface-inverse` / `--magma-on-inverse`.
 
+## Outside the web
+
+The roles (`--magma-*`), the utilities and the components are web only. An Android, iOS or
+Flutter app takes its colours from `@maggioli-design-system/design-tokens`, as files to copy
+into the app: `dist/android/colors.xml`, one of `dist/ios-swift/*.swift`,
+`dist/flutter/colors.dart`. They hold the palettes and the surface, border and text colours
+of each family, both modes side by side (`color_surface_neutral_light_default`,
+`..._dark_...`), and nothing else: no type, spacing or motion tokens, no theme or contrast
+switch. Paint with the family of the default theme, `neutral` (`surface_neutral_*`,
+`border_neutral_*`, `text_neutral_*`), switch the mode in the app, and take any other role
+from the step it points at. The names per platform, the mode switch and the outputs that do
+not compile (`dist/ios/`, `dist/flutter/fonts.dart`) are in
+`node_modules/@maggioli-design-system/design-tokens/README.md`, "Native platforms".
+
 ## Migrating Magma 1 colour classes
 
 Magma 1 code paints raw steps, often with a hand-tuned `dark:` override. These steps have

package/agents/components.md

@@ -3,129 +3,201 @@
   Source of truth: docs/agents/ in the magma monorepo.
   Regenerate with: npm run sync.agent-docs (from the stencil package).
 -->
-# Magma components catalogue (116 components)
+# Magma components catalogue (117 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).
+>
+> Grouped by category (the `@category` docs tag of each component in
+> `dist/documentation.json`). A part of a compound component (`@parent`) follows its
+> component and names the components it sits in: it always composes inside them.
+
+## Actions
+
+Controls that make something happen: buttons, links, action bars and menus.
 
 | 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-link`](../../magma/dist/collection/components/mds-link/AGENTS.md) | The `<mds-link>` web component is the inline link of Magma: a word or a phrase inside running text, usually inside an `<mds-text>`, that opens a URL or runs an inline action |
+| [`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), part of `mds-radial-menu` | The `<mds-radial-menu-item>` web component is a single actionable spoke of the `<mds-radial-menu>` compound |
+| [`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 |
+
+## Forms
+
+Fields that take a value, and the calendar and the filters that help pick one.
+
+| Component | What it is |
+| --------- | ---------- |
 | [`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-calendar-cell`](../../magma/dist/collection/components/mds-calendar-cell/AGENTS.md), part of `mds-calendar` | The `<mds-calendar-cell>` web component represents a single selectable day inside the `<mds-calendar>` grid |
 | [`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-filter-item`](../../magma/dist/collection/components/mds-filter-item/AGENTS.md), part of `mds-filter` | The `<mds-filter-item>` web component is a single selectable option inside the `<mds-filter>` container 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-tip`](../../magma/dist/collection/components/mds-input-tip/AGENTS.md), part of `mds-input` or `mds-input-date` or `mds-input-select` | 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), part of `mds-input-tip` | The `<mds-input-tip-item>` web component is a single contextual hint row rendered inside the `<mds-input-tip>` container |
 | [`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-date-range-preselection`](../../magma/dist/collection/components/mds-input-date-range-preselection/AGENTS.md), part of `mds-input-date-range` | 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-link`](../../magma/dist/collection/components/mds-link/AGENTS.md) | The `<mds-link>` web component is the inline link of Magma: a word or a phrase inside running text, usually inside an `<mds-text>`, that opens a URL or runs an inline action |
-| [`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 |
+
+## Navigation
+
+Where the user is and where they can go: breadcrumbs, tabs, steps, pages, trees.
+
+| Component | What it is |
+| --------- | ---------- |
+| [`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), part of `mds-breadcrumb` | The `<mds-breadcrumb-item>` web component represents a single navigable depth in a breadcrumb trail |
 | [`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, usually slotted inside the `<mds-pref>` panel 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, usually a direct child of the `<mds-pref>` panel |
-| [`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, usually 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-paginator-item`](../../magma/dist/collection/components/mds-paginator-item/AGENTS.md), part of `mds-paginator` | 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-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), part of `mds-stepper-bar` | 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-item`](../../magma/dist/collection/components/mds-tab-item/AGENTS.md), part of `mds-tab` | 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-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), part of `mds-tab-bar` | The `<mds-tab-bar-item>` web component is a single selectable tab within the `<mds-tab-bar>` container |
+| [`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), part of `mds-tree` or `mds-tree-item` | 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 |
+
+## Feedback
+
+Messages, progress and empty states that tell the user what is happening.
+
+| Component | What it is |
+| --------- | ---------- |
+| [`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-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-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-push-notification-item`](../../magma/dist/collection/components/mds-push-notification-item/AGENTS.md), part of `mds-push-notification` | The `<mds-push-notification-item>` web component is a single notification card rendered inside its parent container `<mds-push-notification>` |
 | [`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-toast-region`](../../magma/dist/collection/components/mds-toast-region/AGENTS.md) | The `<mds-toast-region>` web component is the place where an application shows its toasts: placed once in the application shell, at an edge of the viewport, it lines up the `<mds-toast>` elements visible at the same time, each one readable, and announces them to assistive technologies |
+| [`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 |
+
+## Overlays
+
+Surfaces that float over the page: dialogs, dropdowns, tooltips, help.
+
+| Component | What it is |
+| --------- | ---------- |
+| [`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-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-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-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 |
+
+## Data
+
+Sets of values and the people they belong to: tables, lists, figures, avatars.
+
+| Component | What it is |
+| --------- | ---------- |
+| [`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), part of `mds-avatar-stack` | 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-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-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-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), part of `mds-kpi` | 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-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), part of `mds-list` | 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-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), part of `mds-price-table` | 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), part of `mds-price-table-features-row` | 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), part of `mds-price-table-features` | 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), part of `mds-price-table` | 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), part of `mds-price-table` or `mds-price-table-header` | 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), part of `mds-price-table-list` | 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-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), part of `mds-table` | 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), part of `mds-table-row` or `mds-table-footer` | 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), part of `mds-table` | 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), part of `mds-table` | 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), part of `mds-table-header` | 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), part of `mds-table-body` | 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) |
+
+## Tags
+
+Short markers attached to other content: badges, chips, labels, mentions, keys.
+
+| Component | What it is |
+| --------- | ---------- |
+| [`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-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-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), part of `mds-keyboard` | 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-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-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-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 |
+
+## Structure
+
+Containers and dividers that lay the page out: cards, accordions, headers, rules.
+
+| 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), part of `mds-accordion` | 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), part of `mds-accordion-timer` | 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-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), part of `mds-card` | 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), part of `mds-card` | 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), part of `mds-card` | 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), part of `mds-card` | 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-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-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), part of `mds-header` | 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-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-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 |
+
+## Content
+
+Text, media and files: typography, images, icons, quotes, notes, previews.
+
+| Component | What it is |
+| --------- | ---------- |
+| [`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-book`](../../magma/dist/collection/components/mds-book/AGENTS.md) | The `<mds-book>` web component shows a book as a physical object, from the image of its front cover alone: front cover, spine and page block drawn in CSS 3D, turned a little so the spine shows |
+| [`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-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-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-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-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-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-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 |
+
+## Preferences
+
+The controls a user tunes the interface with: mode, theme, contrast, motion, language.
+
+| Component | What it is |
+| --------- | ---------- |
+| [`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, usually slotted inside the `<mds-pref>` panel alongside the other preference children |
+| [`mds-pref-language-item`](../../magma/dist/collection/components/mds-pref-language-item/AGENTS.md), part of `mds-pref-language` | 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, usually a direct child of the `<mds-pref>` panel |
+| [`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, usually a direct child of `<mds-pref>` |
+| [`mds-pref-theme-item`](../../magma/dist/collection/components/mds-pref-theme-item/AGENTS.md), part of `mds-pref-theme` | The `<mds-pref-theme-item>` web component is a single selectable theme entry inside the `<mds-pref-theme>` preference picker |

package/agents/conventions.md

@@ -99,6 +99,10 @@ Parent/child pairs communicate internally. Rules:
 2. Never use a child outside its parent (no `mds-accordion-item` without `mds-accordion`).
 3. Never mix child types across parents.
 
+Which parent a child belongs in: [`components.md`](components.md) lists every part right
+after its compound and names the components it sits in (the `@parent` docs tag of the
+component in `documentation.json`).
+
 ```html
 <mds-accordion>
   <mds-accordion-item>...</mds-accordion-item>
@@ -173,22 +177,35 @@ Maggioli):
 - Use the preference components / classes for high contrast and reduced motion - do not
   hard-code those styles (see [`theming.md`](theming.md)).
 
+## Language
+
+- The texts of the components (labels, tooltips, validation messages) follow the language of
+  the page, `<html lang>`: Magma has them in `el`, `en`, `es` and `it`. A language with a
+  region gets the texts of its base language (`it-IT` and `it-CH` get `it`), and any other
+  language gets English. To let the user choose, add `mds-pref-language`.
+
 ## Styling components from outside
 
 A component's styling API is what its `AGENTS.md` documents:
 
-1. **CSS custom properties** ("CSS custom properties" table), named
+1. **Public 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.
+   parent selector. The table lists only the public ones, the ones the component promises;
+   its other custom properties are internal (`"visibility": "internal"` in
+   `documentation.json`): they may change or go in any release, so never set or read
+   them, and the lint reports them (`magma/no-internal-tokens`, [`lint.md`](lint.md)). A
+   component with no public custom property is styled with its props, its parts and the
+   roles around it. A public one marked **Static** takes a value of its own, not a role
+   (the colours of an illustration, a cover colour from a catalogue record).
 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.
+Never reach past that: internal custom properties, undocumented parts, internal class
+names, `>>>` or `/deep/` break on any release.
 
 ```css
-/* correct */
+/* CORRECT */
 mds-button { --mds-button-radius: var(--magma-radius-full); }
 
 .featured-card mds-button {
@@ -196,10 +213,10 @@ mds-button { --mds-button-radius: var(--magma-radius-full); }
   --mds-button-radius: var(--magma-radius-lg);
 }
 
-/* correct, deep customisation: `icon` is a documented part of mds-button */
+/* 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 */
+/* INCORRECT - internal nodes are not API */
 mds-button >>> .internal { color: red; }
 ```
 

package/agents/install.md

@@ -201,6 +201,13 @@ With React Router the handler is `(href) => navigate(href)` from `useNavigate()`
 `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.
 
+## 7. Lint
+
+The ESLint and Stylelint rules ship in `@maggioli-design-system/magma`: nothing more to
+install from Magma. Add the block for this target to the project's ESLint configuration and
+the Stylelint preset for its stylesheets, as [`lint.md`](lint.md) shows ([React](lint.md#react)),
+merging into what the project already has, and run both after every change.
+
 ## Gotchas
 
 - The icon path effect must run on the client. In Next.js App Router the wrapper that

package/agents/lint.md

@@ -0,0 +1,270 @@
+<!--
+  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 lint
+
+> Scope: checking the code you write against the installed Magma, with the ESLint and
+> Stylelint rules that ship inside `@maggioli-design-system/magma`. Set them up once, when
+> you install Magma, and run them after every change.
+
+The rules make the prose of these guides executable: a prop value the component does not
+take, a boolean turned "off" with `"false"`, an icon-only control without a name, a colour
+painted with Tailwind's palette or a raw palette step, a hand-written dark mode. They read
+the API and the tokens of the installed version, the same release as the components, so
+they follow every update with nothing to keep in sync.
+
+## Set it up
+
+Nothing to install from Magma: the rules are in `@maggioli-design-system/magma`, which
+`magma-react` and `magma-angular` require too. The project needs ESLint 9 and Stylelint 16
+(`npm i -D eslint stylelint` when it has none) and the parser of its templates:
+
+| Templates | Parser |
+| --- | --- |
+| HTML | `@html-eslint/parser` |
+| Angular (external `.html` templates) | `@angular-eslint/template-parser` (with angular-eslint) |
+| React (JSX, TSX) | the one the project already uses |
+
+MERGE the blocks below into the project's `eslint.config.js` and `stylelint.config.mjs`:
+never replace an existing configuration. Each ESLint preset sets rules only, so it goes in
+the block that parses the templates.
+
+### HTML and web components
+
+```js
+// eslint.config.js
+import html from '@html-eslint/parser';
+import magma from '@maggioli-design-system/magma/eslint';
+
+export default [
+  { files: ['**/*.html'], languageOptions: { parser: html }, ...magma.configs.recommended },
+];
+```
+
+### React
+
+```js
+// eslint.config.js
+import magma from '@maggioli-design-system/magma/eslint';
+
+export default [
+  // ...the block that parses .jsx and .tsx
+  { files: ['**/*.{jsx,tsx}'], ...magma.configs.recommended },
+];
+```
+
+The rules read both `<mds-button>` and the wrappers of `magma-react` (`<MdsButton>`), and a
+`className` written as a string or a template literal.
+
+### Angular
+
+```js
+// eslint.config.js, next to the blocks of angular-eslint
+import angularTemplate from '@angular-eslint/template-parser';
+import magma from '@maggioli-design-system/magma/eslint';
+
+export default [
+  { files: ['**/*.html'], languageOptions: { parser: angularTemplate }, ...magma.configs.recommended },
+];
+```
+
+With the inline-template processor of angular-eslint, the inline `template` of a component
+is linted as an `.html` file too.
+
+### CSS and SCSS
+
+```js
+// stylelint.config.mjs
+export default {
+  extends: ['@maggioli-design-system/magma/stylelint/recommended'],
+};
+```
+
+### Presets
+
+- `recommended`, for a product that already exists: what is broken or not accessible is an
+  error, the palette and an internal custom property a warning;
+- `strict` (`magma.configs.strict`, `@maggioli-design-system/magma/stylelint/strict`), for a
+  new product: every rule is an error.
+
+## Run it after writing
+
+After every change, run ESLint on the templates you touched and Stylelint on the
+stylesheets, and fix what they report before you hand the work over:
+
+```bash
+npx eslint src
+npx stylelint "src/**/*.{css,scss}"
+```
+
+An error is something broken or not accessible; a warning of `recommended` is a colour that
+does not follow the mode, the named theme and the contrast preference, or a custom property a
+component may change in any release. When a rule is wrong about Magma itself, report it
+([`reporting.md`](reporting.md)) instead of disabling it.
+
+## Rules
+
+| Rule | Tool | `recommended` | `strict` |
+| --- | --- | --- | --- |
+| [`valid-attribute-values`](#valid-attribute-values) | ESLint | error | error |
+| [`no-false-boolean`](#no-false-boolean) | ESLint | error | error |
+| [`accessible-name`](#accessible-name) | ESLint | error | error |
+| [`no-raw-palette-classes`](#no-raw-palette-classes) | ESLint | warn | error |
+| [`no-color-scheme-override`](#no-color-scheme-override) | Stylelint | error | error |
+| [`no-raw-color`](#no-raw-color) | Stylelint | warning | error |
+| [`no-internal-tokens`](#no-internal-tokens) | ESLint, Stylelint | warn | error |
+
+The ESLint rules are named `magma/<rule>` once the preset is loaded, the Stylelint rules
+`magma/<rule>` once the plugin (`@maggioli-design-system/magma/stylelint`) is.
+
+### valid-attribute-values
+
+A prop whose type is a union of literals takes one of them (the values each prop takes are
+in the component's `AGENTS.md`).
+
+```html
+<!-- INCORRECT: tone takes "box", "strong" or "weak" -->
+<mds-banner tone="outline">Saved</mds-banner>
+
+<!-- CORRECT -->
+<mds-banner tone="weak">Saved</mds-banner>
+```
+
+A value bound to an expression (`[tone]="tone"`, `tone={tone}`) is known only at run time and
+is not checked; a literal binding (`[tone]="'box'"`) is.
+
+### no-false-boolean
+
+A boolean prop is turned off by removing its attribute
+([`conventions.md`](conventions.md#boolean-disabled-and-await-props)): a form-associated
+component reads any value as on, `"false"` included.
+
+```html
+<!-- INCORRECT -->
+<mds-button disabled="false">Save</mds-button>
+
+<!-- CORRECT -->
+<mds-button>Save</mds-button>
+```
+
+Reported: the string `"false"` in any form, and an Angular attribute binding
+(`[attr.disabled]="false"`), which writes the attribute `"false"`. Bind a real boolean to the
+property instead: `<MdsButton disabled={isDisabled}>`, `[disabled]="isDisabled"`.
+
+### accessible-name
+
+A component that takes an `icon` next to a `label` or a default slot, shown with its icon
+alone, needs a name: without `label` or `aria-label`, `mds-button` is announced by the slug of
+its icon, which names the icon and not the action. An `mds-img` with a `src` and no `alt` is
+named after its file: describe the image, or set `alt=""` when it is decorative.
+
+```html
+<!-- INCORRECT -->
+<mds-button icon="mi/baseline/send"></mds-button>
+<mds-img src="/img/report-2024.jpg"></mds-img>
+
+<!-- CORRECT -->
+<mds-button icon="mi/baseline/send" label="Send"></mds-button>
+<mds-img src="/img/report-2024.jpg" alt="Annual report 2024"></mds-img>
+```
+
+Left alone, because one element does not show its name: an element with an `id` (an
+`mds-tooltip` with `relation="label"`, or an `aria-labelledby` elsewhere, may name it) and
+one that spreads its props (`{...props}`).
+
+### no-raw-palette-classes
+
+A colour class names a role ([`color.md`](color.md)), never Tailwind's palette (`bg-white`,
+`text-gray-700`), which ignores Magma, nor a raw Magma step (`bg-tone-neutral-03`,
+`border-surface-neutral-default`), which follows the mode only. Variants, `!` and opacity are
+read through: `dark:hover:bg-white/50` is `bg-white`.
+
+```html
+<!-- INCORRECT -->
+<section class="bg-white text-gray-700">...</section>
+
+<!-- CORRECT -->
+<section class="bg-surface-raised text-fg-default">...</section>
+```
+
+Not reported: `label-*` and `brand-*`, for colour that encodes data, and the seed of a tone,
+the pure extreme of the mode. Only the classes written in the template are read: a class
+built at run time (`clsx(...)`, an Angular `[ngClass]`) is not.
+
+### no-color-scheme-override
+
+A `prefers-color-scheme` media query follows the OS, not the mode the user picked
+(`mds-pref-mode`). The roles follow both: paint with them, and dark mode comes with no
+query. For a deliberate choice that differs per mode, use the `dark` variant of the Magma
+Tailwind theme, which follows the Magma mode ([`theming.md`](theming.md)).
+
+```css
+/* INCORRECT */
+@media (prefers-color-scheme: dark) {
+  .panel {
+    background: rgb(var(--magma-surface-overlay));
+  }
+}
+
+/* CORRECT */
+.panel {
+  background: rgb(var(--magma-surface-raised));
+}
+```
+
+### no-raw-color
+
+A hex, `rgb()`, `hsl()`, `oklch()` or other colour literal where a role belongs. A colour that
+names a token is fine (`rgb(var(--magma-text-muted) / 0.5)`), and so are the keywords
+(`currentColor`, `transparent`). In a shadow the hint is the shadow ink,
+`rgb(var(--magma-shadow-ink) / <alpha>)`. Not read: `mask` and `mask-image`, and the
+`initial-value` of an `@property`.
+
+Not reported either: the public custom properties marked **Static** in a component's
+`AGENTS.md`, which take a colour of their own, not a role (the skin of an illustration, the
+cover of a book from its catalogue record):
+
+```css
+mds-emoji[name='simi'] {
+  --mds-emoji-simi-skin: #f5c8a0;
+}
+```
+
+Any other colour that is not a role keeps its literal under a disable comment that says why:
+`/* stylelint-disable-next-line magma/no-raw-color -- <the reason> */`.
+
+### no-internal-tokens
+
+An `--mds-*` custom property, set or read, that no component promises. A component's
+`AGENTS.md` lists its public custom properties, the only ones a product sets; the others are
+internal, its implementation, and may change or go in any release without notice. A name no
+component documents is reported too. Stylelint reads the stylesheets; ESLint reads the
+inline styles of the templates: a `style` attribute, a React `style={{ '--mds-<name>': ... }}`
+object, an Angular `[style.--mds-<name>]` binding.
+
+```css
+/* INCORRECT: internal, it may change in any release */
+mds-chip {
+  --mds-chip-icon-color: rgb(var(--magma-accent-fg));
+}
+
+/* CORRECT: a public custom property of the chip */
+mds-chip {
+  --mds-chip-icon-background: rgb(var(--magma-accent-surface));
+}
+```
+
+When no public custom property does what you need, use a prop, a documented part, or a role
+on the markup around the component; if none does, ask for one ([`reporting.md`](reporting.md))
+rather than setting an internal one.
+
+## Settings
+
+The rules need no settings: they read the `documentation.json` beside them in the installed
+`magma`, and the tokens of the `design-tokens` and `styles` it depends on. To check against
+other files, set their paths under `settings.magma` in the ESLint configuration (relative to
+`root`, the project by default): `documentation`, `tokens`, `consumption`. The Stylelint rules
+take `root` and `documentation` as secondary options:
+`'magma/no-internal-tokens': [true, { documentation: './documentation.json' }]`.

package/agents/mcp.md

@@ -0,0 +1,103 @@
+<!--
+  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 MCP server
+
+> Scope: asking Magma precise questions while you work, through the MCP server that ships
+> inside `@maggioli-design-system/magma`. Set it up once, when you install Magma; then reach
+> for its tools instead of reading whole files.
+
+The server answers from the version installed in the project: the components and their
+API, the roles and tokens with what each one is for, the classes of the Magma Tailwind
+theme, the icon slugs that exist, the sections of these guides, and the lint
+([`lint.md`](lint.md)) on a snippet before it is written. It is read-only: no tool changes
+a file.
+
+## Set it up
+
+Nothing to install: the server is the `magma-mcp` command of `@maggioli-design-system/magma`,
+which `magma-react` and `magma-angular` require too. The agent's client starts it on stdio
+from the project's root; MERGE the entry into the client's configuration, never replace
+the file.
+
+### Claude Code: the Magma plugin
+
+In Claude Code, the Magma plugin starts the server for you and adds the skills that run a
+whole job: `/magma:setup`, `/magma:review`, `/magma:migrate`, and `ui`, which Claude loads by
+itself for UI work. Register it for the whole team in the project's committed
+`.claude/settings.json`; Claude Code loads it once the folder is trusted, in the terminal and
+in the desktop app, which reads the same settings:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "magma": { "source": { "source": "github", "repo": "magma-design-system/magma" }, "autoUpdate": true }
+  },
+  "enabledPlugins": { "magma@magma": true }
+}
+```
+
+On one machine only, in a Claude Code session in the terminal:
+`/plugin marketplace add magma-design-system/magma`, then `/plugin install magma@magma`.
+
+With the plugin, do not also add the `.mcp.json` entry below: the server would run twice.
+
+### Claude Code without the plugin, and the other clients
+
+Claude Code, `.mcp.json` at the project root (committed, so the whole team gets it; Claude
+Code asks once before it starts a project server):
+
+```json
+{
+  "mcpServers": {
+    "magma": { "command": "npx", "args": ["--no", "magma-mcp"] }
+  }
+}
+```
+
+VS Code (GitHub Copilot), `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "magma": { "type": "stdio", "command": "npx", "args": ["--no", "magma-mcp"] }
+  }
+}
+```
+
+Cursor, `.cursor/mcp.json`: the same entry as Claude Code, under `mcpServers`.
+
+`npx --no magma-mcp` runs the installed version, so the answers always match the components
+the project uses. Keep `--no`: without it, a client that starts the server before
+`npm install` (a fresh clone with the configuration committed) lets `npx` download and run
+whatever package the npm registry has under that name; with it, `npx` stops instead. When the
+client starts servers elsewhere than the project's root, pass it:
+`"args": ["--no", "magma-mcp", "--root", "<the project's folder>"]`.
+
+## The tools
+
+| Tool | Ask it | Instead of |
+| --- | --- | --- |
+| `find_component` | which component fits a need ("a date range picker") | reading the catalogue |
+| `get_component` | the API of one component: props with their values and default, events, methods, slots, parts, public CSS custom properties | reading its `AGENTS.md` |
+| `get_usage` | how HTML, React or Angular writes it: import, props, events (`onMdsInputChange`, `(mdsInputChange)`) | guessing the names |
+| `list_tokens` | the role for a need ("secondary text"), with its value and class | reading [`color.md`](color.md) |
+| `suggest_role` | the role for a colour, a raw class or a palette step | picking a role by eye |
+| `explain_class` | what a class does with the Magma theme | the trap of the scale: `p-4` is 0.01rem, `p-400` is 1rem |
+| `find_icon` | a slug that exists, by meaning, or whether a slug exists | an `icon="..."` that renders nothing |
+| `get_guide` | one section of a guide | reading the whole file |
+| `check_markup` | whether a snippet passes the lint, before it is written | a lint run after the fact |
+| `check_setup` | what the Magma integration of the project misses | checking the install steps by hand |
+
+`check_markup` uses the ESLint, Stylelint and template parsers the project installed with
+the lint ([`lint.md`](lint.md)).
+
+## When to call them
+
+- Before writing a component: `find_component`, then `get_component` and `get_usage`.
+- Before a colour, a spacing or a class: `list_tokens`, `suggest_role`, `explain_class`.
+- Before an icon: `find_icon`.
+- After writing: `check_markup`, then the project's lint ([`lint.md`](lint.md)).
+- After the bootstrap, or when something does not render: `check_setup`.

package/agents/theming.md

@@ -28,6 +28,14 @@ let the user choose, each preference has its component - `mds-pref-mode`,
 `mds-pref-language` - and `mds-pref` groups them in one panel; they write the classes and
 remember the choice. Never write `color-scheme` or dark-mode media queries by hand.
 
+Tailwind's `dark:` follows the same mode: the Magma Tailwind theme brings a `dark`
+variant that turns on where the palette turns dark - `pref-mode-dark`, `pref-mode-system`
+or no controller on a dark OS, a theme locked to dark (`pref-theme-scheme-dark`) - and
+never under `pref-mode-light` or a theme locked to light (`pref-theme-scheme-light`). The
+roles flip without it, so `dark:` is never needed to correct a colour: use it only for a
+deliberate per-mode choice. It matches the light DOM only (pages, layouts, stories);
+inside a component's shadow root it matches nothing.
+
 ## Named themes
 
 A named theme retints the whole neutral scaffolding of the page at once - surfaces,

package/dist/components.js

@@ -15,6 +15,7 @@ export { MdsBadge } from "./mds-badge.js";
 export { MdsBanner } from "./mds-banner.js";
 export { MdsBenchmarkBar } from "./mds-benchmark-bar.js";
 export { MdsBibliography } from "./mds-bibliography.js";
+export { MdsBook } from "./mds-book.js";
 export { MdsBreadcrumbItem } from "./mds-breadcrumb-item.js";
 export { MdsBreadcrumb } from "./mds-breadcrumb.js";
 export { MdsButtonDropdown } from "./mds-button-dropdown.js";

package/dist/components.server.js

@@ -15,6 +15,7 @@ export { MdsBadge } from "./mds-badge.server.js";
 export { MdsBanner } from "./mds-banner.server.js";
 export { MdsBenchmarkBar } from "./mds-benchmark-bar.server.js";
 export { MdsBibliography } from "./mds-bibliography.server.js";
+export { MdsBook } from "./mds-book.server.js";
 export { MdsBreadcrumbItem } from "./mds-breadcrumb-item.server.js";
 export { MdsBreadcrumb } from "./mds-breadcrumb.server.js";
 export { MdsButtonDropdown } from "./mds-button-dropdown.server.js";

package/dist/mds-book.js

@@ -0,0 +1,12 @@
+'use client';
+import { createComponent } from '@stencil/react-output-target/runtime';
+import React from 'react';
+import { MdsBook as MdsBookElement, defineCustomElement as defineMdsBook } from "@maggioli-design-system/magma/dist/components/mds-book.js";
+export const MdsBook = /*@__PURE__*/ createComponent({
+    tagName: 'mds-book',
+    elementClass: MdsBookElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: {},
+    defineCustomElement: defineMdsBook
+});

package/dist/mds-book.server.js

@@ -0,0 +1,23 @@
+'use client';
+import { createComponent } from '@stencil/react-output-target/ssr';
+// @ts-ignore - ignore potential type issues as the project is importing itself
+import * as clientComponents from "@maggioli-design-system/magma-react";
+export const serializeShadowRoot = "declarative-shadow-dom";
+export const MdsBook = /*@__PURE__*/ createComponent({
+    tagName: 'mds-book',
+    properties: {
+        alt: 'alt',
+        author: 'author',
+        binding: 'binding',
+        format: 'format',
+        loading: 'loading',
+        name: 'name',
+        pages: 'pages',
+        pose: 'pose',
+        publisher: 'publisher',
+        src: 'src'
+    },
+    hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,
+    clientModule: clientComponents.MdsBook,
+    serializeShadowRoot
+});

package/dist/types/components.d.ts

@@ -14,6 +14,7 @@ export { MdsBadge } from "./mds-badge.js";
 export { MdsBanner } from "./mds-banner.js";
 export { MdsBenchmarkBar } from "./mds-benchmark-bar.js";
 export { MdsBibliography } from "./mds-bibliography.js";
+export { MdsBook } from "./mds-book.js";
 export { MdsBreadcrumbItem } from "./mds-breadcrumb-item.js";
 export { MdsBreadcrumb } from "./mds-breadcrumb.js";
 export { MdsButtonDropdown } from "./mds-button-dropdown.js";

package/dist/types/components.server.d.ts

@@ -16,6 +16,7 @@ export { MdsBadge } from "./mds-badge.server.js";
 export { MdsBanner } from "./mds-banner.server.js";
 export { MdsBenchmarkBar } from "./mds-benchmark-bar.server.js";
 export { MdsBibliography } from "./mds-bibliography.server.js";
+export { MdsBook } from "./mds-book.server.js";
 export { MdsBreadcrumbItem } from "./mds-breadcrumb-item.server.js";
 export { MdsBreadcrumb } from "./mds-breadcrumb.server.js";
 export { MdsButtonDropdown } from "./mds-button-dropdown.server.js";

package/dist/types/mds-book.d.ts

@@ -0,0 +1,9 @@
+/**
+ * This file was automatically generated by the Stencil React Output Target.
+ * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+import type { StencilReactComponent } from '@stencil/react-output-target/runtime';
+import type { Components } from "@maggioli-design-system/magma/dist/components";
+import { MdsBook as MdsBookElement } from "@maggioli-design-system/magma/dist/components/mds-book.js";
+export type MdsBookEvents = NonNullable<unknown>;
+export declare const MdsBook: StencilReactComponent<MdsBookElement, MdsBookEvents, Components.MdsBook>;

package/dist/types/mds-book.server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * This file was automatically generated by the Stencil React Output Target.
+ * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+import type { StencilReactComponent } from '@stencil/react-output-target/runtime';
+import { type SerializeShadowRootOptions } from '@stencil/react-output-target/ssr';
+import type { Components } from "@maggioli-design-system/magma/dist/components";
+import { MdsBook as MdsBookElement } from "@maggioli-design-system/magma/dist/components/mds-book.js";
+export declare const serializeShadowRoot: SerializeShadowRootOptions;
+export type MdsBookEvents = NonNullable<unknown>;
+export declare const MdsBook: StencilReactComponent<MdsBookElement, MdsBookEvents, Components.MdsBook>;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@maggioli-design-system/magma-react",
-  "version": "2.5.0",
+  "version": "2.6.0",
+  "license": "MIT",
   "main": "dist/components.js",
   "module": "dist/components.js",
   "types": "dist/types/components.d.ts",
@@ -34,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@maggioli-design-system/magma": "2.5.0",
+    "@maggioli-design-system/magma": "2.6.0",
     "@stencil/react-output-target": "1.6.5"
   },
   "repository": {