@maggioli-design-system/magma-react 2.1.0 → 2.3.0

package/AGENTS.md

@@ -5,7 +5,7 @@
 -->
 # @maggioli-design-system/magma-react - agent install guide
 
-> Version 2.1.0. You (the agent) are installing Magma into THIS project. Do not
+> Version 2.3.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,
@@ -23,31 +23,44 @@ Inspect the consumer project before asking anything:
 | Tailwind + version | `tailwindcss` in deps: v4 -> the CSS imports, v3 -> the JS preset (see agents/assets.md) |
 | SSR | `@angular/ssr` / Angular Universal, or Next App Router |
 | Compatible versions | derive from the installed `@maggioli-design-system/magma` major (see matrix in install.md) |
+| Editor | a `.vscode/` folder -> VS Code; nothing -> ask (step 2) |
 
 ## Step 2 - ask only the gaps
 
 Ask the user only what detection left undecided. Typical questions:
 
-1. **Icons**: use the prebuilt set (`@maggioli-design-system/svg-icons`) or do you need
-   **iconsauce** for tree-shaking / custom icons? Most consumers do NOT need iconsauce -
-   Magma already ships resolved SVGs; iconsauce is an internal build dependency. Only
-   add `@iconsauce/*` if the user wants their own icon pipeline.
+1. **Icons**: which sets does the app use, and how should they be served? Every slug must
+   be served at `<mdsIconSvgPath><slug>.svg`, and each set comes from its own package:
+   Magma ships only `mgg/` (`@maggioli-design-system/svg-icons`), while `mi/` and
+   `mdi/` come from `@material-icons/svg` and `@mdi/svg`, and none of them is a
+   dependency of this package. The routes are in agents/assets.md section 3: **iconsauce**,
+   what Magma uses (it reads the sources and writes only the icons they name), or a copy
+   script that serves the files in the slug layout. Copying the `svg-icons` folder as it
+   is renders nothing: its files are not under `mgg/`.
 2. **Static assets path**: where are static files served from? This sets `mdsIconSvgPath`
    and the SVG copy destination.
 3. **Dark mode / preferences**: needed? If yes, wire the preference classes and components.
 4. Confirm the version row if the installed major is ambiguous.
+5. **Editor**: VS Code? It gets token and class autocomplete through two files in
+   `.vscode/` (agents/assets.md section 5); for another editor only the token file applies.
 
 ## Step 3 - execute
 
 1. Install packages and the shared assets - see [`agents/install.md`](agents/install.md).
 2. Wire styles in the exact cascade-layer order - see [`agents/assets.md`](agents/assets.md).
-3. Copy the icon SVGs to the static path and set `mdsIconSvgPath`.
+3. Serve every icon slug the app uses at the static path, with the route from step 2, and
+   set `mdsIconSvgPath`.
 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.
 
 ## Step 4 - verify
 
-Build the app and confirm an `mds-*` component renders and at least one icon loads from
-the configured path. Report what was installed, the cascade order used, and the icon path.
+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.
 
 ## Using the components
 
@@ -64,8 +77,11 @@ Once installed, do not guess component APIs or rules - read only the file you ne
 | Coloring your own UI | [`agents/color.md`](agents/color.md) |
 | 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) |
+| 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`) |
 
 Tooling that needs structured data reads `documentation.json`: one per component beside
 its `AGENTS.md`, or `@maggioli-design-system/magma/dist/documentation.json` for all of them
-(over 2 MB - do not load it into context). `dist/types/components.d.ts` drives editor
-IntelliSense.
+(over 2 MB - do not load it into context). In both, the relative links of the `usage`
+texts resolve from the component's folder, `dist/collection/components/<tag>/`.
+`dist/types/components.d.ts` drives editor IntelliSense.

package/CHANGELOG.md

@@ -0,0 +1,478 @@
+# Changelog
+
+Every release of `@maggioli-design-system/magma-react`, newest first. Each section is the body of the GitHub
+release with the same tag, written by git-cliff from the conventional commits of the
+package.
+
+It is released together with `magma`, at the same version: the sections are the
+releases of `magma`.
+
+## [magma@2.3.0] - 2026-10-15
+
+### Bug Fixes
+
+- *(mds-text)* Read the animation custom properties when the reveal starts
+- *(mds-text)* Paint the revealed text as text, never as html
+- *(magma)* Keep the HTMLElement shim of the loader in consumer bundles
+- *(mds-input-switch)* Give the off knob of a switch a light colour in dark mode
+- *(mds-input-select)* Keep the hover and focus ring in dark mode and with more contrast
+- *(magma)* Keep the icon lists of the story controls out of the published collection
+- *(mds-table)* Paint the scroll area of an interactive table like its rows while hovered
+- *(mds-pref-theme-item)* Show the color preview next to the label
+- *(mds-pref-theme)* Show the label of the selected item in the trigger
+- *(mds-tab,mds-input-switch)* Animate the slider and the knob only on a change of state
+- *(mds-button)* Give back the icon slug title when another element names the button
+- *(mds-pref)* Keep the document flag and the listeners across a move in the DOM
+- *(mds-button)* Leave a button with an icon given as markup without a role again
+- *(magma)* Lay out the label and the tab of every mds-pref-* control alike
+- *(magma)* Cap the radius of buttons, tabs and fields at a part of their height
+- *(mds-file)* Show the downloaded indicator again and drop crypto-js
+- *(magma)* Name the icon-only buttons inside the components and give every mds-button its role
+- *(mds-filter,mds-filter-item)* Announce the selected state and the count, name the reset button
+- *(mds-filter)* Follow the selection the application sets on the items
+- *(mds-list-item)* Take the text colour of the container instead of painting the items muted
+
+### Build
+
+- *(magma)* Prepend the release notes to each package's CHANGELOG.md in the release commit
+- *(design-tokens,identity,styles,svg-icons,icons,magma)* Ship CHANGELOG.md in every package
+
+### Documentation
+
+- *(magma)* Say in the agent guides that hydrated.css keeps the box of the components
+- *(magma)* Point the no-bundler loader example of the readme at a real file
+- *(magma)* Document icon routes that serve every slug where mds-icon fetches it
+- *(mds-text)* Regenerate the readme with the usage docs of the yugop fix
+- *(magma)* Set up editor autocomplete in the agent guides, tokens and classes
+- *(magma)* Link the shipped component docs from the agent guides, never plain text
+- *(magma)* Say in the agent guides what the semantic utilities paint without semantic.css
+- *(stencil)* Drop the hand-written sections of the component readmes
+- *(magma)* Lead the icon path setup with IconsSetService and link the mds-icon pattern
+- *(magma)* Have a reporting agent propose the origin label its project lacks
+- *(magma)* Point the agent guides to the identity manifest
+- *(stencil)* Say every mds-pref-* control also works on its own
+- *(magma)* Point to the changelogs in AGENTS.md and in the commit convention
+- *(mds-tab,mds-input-switch)* Regenerate the readmes from the usage docs
+
+### Features
+
+- *(mds-input,mds-input-select,mds-input-date,mds-input-date-range)* Add size (sm, md, lg)
+- *(mds-tooltip)* Name the caller with relation="label"
+- *(mds-usage)* Give each variant its own header icon and add an icon prop
+- *(mds-table,mds-table-header-cell)* Emit mdsTableHeaderCellSort, let the back end sort the rows
+
+### Performance
+
+- *(mds-button)* Render the spinner only to await, the label without mds-text
+- *(mds-button)* Write each tone once, over the tokens each variant names
+- *(magma)* Prefix the component CSS for the supported browsers, not for IE 11
+- *(magma)* Drop the fallback links that can never resolve
+
+## [magma@2.2.0] - 2026-10-14
+
+### Bug Fixes
+
+- *(mds-table-row)* Show the actions of rows revealed by a streamed ssr boundary
+
+### Build
+
+- *(magma)* Pin typescript to 5.8.3, the version the lockfile installs
+- *(magma)* Move to typescript 5.9.3 with typescript-eslint 8.71.2
+
+### Documentation
+
+- *(magma)* Label issues by the project they come from
+- *(magma)* Never merge a branch with a red pipeline into dev
+- *(magma)* Tell consumer-project agents how to report a Magma problem
+
+### Features
+
+- *(magma)* Render href as a real link and route it through NavigationService
+
+### Refactor
+
+- *(mds-table-row)* Compare sizerWidth with undefined for the actions margin
+
+## [magma@2.1.0] - 2026-10-10
+
+### Bug Fixes
+
+- *(styles,magma)* Require internal dependencies as caret ranges
+- *(magma)* Ship the agent docs in the magma and magma-react tarballs
+- *(stencil)* Apply the mds-pref-* preference once on load, then mirror the shared store
+- *(mds-pref)* Keep data-magma-pref on <html> until the last instance unmounts
+- *(mds-input)* Rebuild the validators when a rule changes after load
+- *(mds-input-date)* Validate again when required, min or max change after load
+- *(mds-input-select)* Show the required tip red when the value is null
+- *(mds-input)* Report the validity to the form, so that required stops the submit
+- *(mds-input-date)* Report the validity to the form
+- *(mds-input-select)* Report a required select left empty to the form
+- *(mds-input-upload)* Submit the files to the form, like a native file input
+- *(mds-input)* Bring back the value of load on a form reset
+- *(mds-input)* Check pattern like a native input, and stop overwriting it
+- *(mds-input)* Emit mdsInputKeydown on keydown, with the KeyboardEvent
+- *(mds-input)* Keep the value when the browser has no Speech API
+- *(mds-input)* Check the format of email and url like the native types
+- *(mds-input)* Check the format of piva and cc
+- *(mds-input-date)* Honour readonly, load pristine and bring back the value on reset
+- *(mds-input-select)* Make multiple work, bring back the selection on reset
+- *(mds-input-switch)* Keep one value per radio group, bring back checked on reset
+- *(mds-input-otp)* Fill the cells from value, bring back the code on reset
+- *(mds-input-range)* Fall back to step 1 like a native input, bring back the value on reset
+- *(mds-input-date-range)* Bound the slotted fields, keep presets in order and in sync at load
+- *(mds-input)* Disable it in a disabled fieldset, like a native input
+- *(mds-input-date)* Disable it in a disabled fieldset, like a native date input
+- *(mds-input-range)* Disable it in a disabled fieldset, like a native range input
+- *(mds-input-select)* Disable it in a disabled fieldset, like a native select
+- *(mds-input-switch)* Disable it in a disabled fieldset, like a native checkbox
+- *(mds-input)* Stop the mic and the steppers on a field the user cannot change
+- *(mds-button-dropdown,mds-button)* Disable the buttons in a disabled fieldset
+
+### Build
+
+- *(magma)* Pin internal dependencies as caret ranges
+- *(stencil)* Write the public API snapshot magma.api.txt from the docs JSON
+- *(stencil)* Compute the review level and the release check of a PR
+- *(stencil)* Rate an event detail that extends the old one as minor
+- *(stencil)* Record the disabled prop of three form inputs in magma.api.txt
+- *(stencil)* Record the API changes of the button family in magma.api.txt
+- *(stencil)* Declare a break no consumer can tell apart with API-Compatible
+
+### Documentation
+
+- *(storybook)* Render the usage docs in the components' Docs pages
+- *(storybook)* Scroll the docs pages to the heading clicked in the table of contents (#834)
+- *(storybook)* Move the Magma preferences to a toolbar menu
+- *(magma,styles,design-tokens)* Rewrite the color docs on the semantic layer
+- *(magma,styles,design-tokens)* Align the styles and design-tokens docs with the build
+- *(magma,stencil)* Align the agent and component docs with the code
+- *(magma,stencil)* Align the 342 component usage docs with the code
+- *(stencil)* Tell how to place mds-table so it scrolls by itself
+- *(magma)* Document how the form components report their validity
+- *(magma)* Document how the form components submit, reset and report validity
+- *(magma)* Say what disabled and a disabled fieldset do to the form components
+- *(magma)* Every form input follows disabled and a disabled fieldset
+- *(stencil)* Document the API snapshot in SPEC.md, AGENTS.md and the PR template
+- *(magma)* Document the review levels and the release check
+- *(stencil)* Put the form reset JSDoc back on formResetCallback
+- *(mds-button)* Let the controls of the Await story drive it
+- *(magma)* Say how the buttons submit a form and tell the actions apart
+
+### Features
+
+- *(magma)* Ship the agent docs as topic fragments and per-component docs
+- *(mds-input-otp)* Add disabled, and disable it in a disabled fieldset
+- *(mds-input-upload)* Add disabled, and disable it in a disabled fieldset
+- *(mds-input-date-range)* Add disabled, and disable it in a disabled fieldset
+- *(mds-input-upload,mds-input-select)* Record name and the selected values in magma.api.txt
+- *(mds-button)* Send name and value to the form it submits, like a native submit button
+- *(mds-button-dropdown,mds-button)* Submit a form from the primary action, with name and value
+- *(mds-button-dropdown)* Emit mdsButtonDropdownClick from the primary action only
+
+### Refactor
+
+- *(magma)* Move the release scope matching to commit-scopes.mjs
+
+## [magma@2.0.1] - 2026-10-05
+
+### Bug Fixes
+
+- *(mds-icon)* Bump idb-keyval to 6.3.0 so the icon cache reopens a closed IndexedDB connection
+- *(mds-icon)* Keep the whole svg path instead of truncating it
+- *(mds-icon)* Render nothing without a name and stop listening once removed from the page
+- *(stencil)* Treat null and missing props as not set again
+
+### Documentation
+
+- *(storybook)* Resolve the story assets relative to the storybook base
+- *(storybook)* Link the published storybook
+
+### Performance
+
+- *(mds-icon)* Check the memory cache before reading IndexedDB
+
+## [magma@2.0.0] - 2026-09-30
+
+### Bug Fixes
+
+- *(mds-modal)* Fix bug animation display
+- *(magma)* Generate agent docs before stencil build
+- *(mds-keyboard,mds-filter-item,mds-paginator-item,mds-url-view)* Typo disconnectedCallback
+- *(stencil)* Set private function
+- *(stencil)* Resolve eslint doc warning
+- *(mds-keyboard)* Remove redundant .bind on test button onClick
+- *(stencil)* Remove .bind in JSX props flagged by react/jsx-no-bind
+- *(stencil)* Resolve react/jsx-no-bind warnings
+- *(stencil)* Avoid top-level call expression in mds-push-notification-item
+- *(mds-icon)* Remove duplicated method
+- *(storybook)* Use accordion disable-close in color-scale
+- *(stencil)* Dedupe repeated @layer order statements in component CSS
+- *(stencil)* Guard preference observer when MutationObserver is missing
+- *(mds-modal)* Correct backdrop click-through selector
+- *(mds-pref-language-item)* Tolerate unset code prop on first render
+- *(mds-video-wall)* [**breaking**] Rename --mds-video-wall-noise-fitler to --mds-video-wall-noise-filter
+- *(mds-file)* [**breaking**] Rename --mds-file-preview-icon-bacground to --mds-file-preview-icon-background
+- *(mds-img)* Tolerate undefined src without crashing
+- *(stencil)* Stop inline components stretching in grid/flex parents
+- *(stencil)* Fall back to the default theme value, not the dark one
+- *(mds-table)* Tolerate lifecycle races on slotted elements
+- *(stencil)* Give the status icons a role, and the contrast that comes with it
+- *(stencil)* Replace :scope selectors with SSR-safe direct-child queries
+- *(stencil)* Guard browser-only APIs for the hydrate/SSR runtime
+- *(stencil)* Declare pre-hydration host geometry
+- *(mds-usage)* Paint the header with its own background token
+- *(stencil)* Point the dead rings at the republished family, and the shadows at the role
+- *(mds-text)* Guard unknown typography against the default variant
+- *(mds-button)* Guard unknown size against the md typography
+- *(stencil,styles)* Close the escape hatch of #624, and repair the registration snapshots
+- *(mds-paginator)* Scroll on item focus only for keyboard navigation so clicks are not lost
+- *(mds-calendar)* Keep the intrinsic width within --mds-calendar-max-width
+- *(mds-input-date)* Give the dropdown calendar a definite width
+- *(stencil)* Center the calendar day numbers and the input date icons
+- *(mds-input-upload)* Widen the infos column and lay the main actions in a row
+- *(mds-file-preview)* Show the extension fallback icon when the icon prop is unset
+- *(mds-input-upload)* Move the width cap from the infos column to the progress bar
+- *(stencil)* Correct the @Element types of three components
+- *(mds-calendar)* Ignore invalid start-date and end-date instead of throwing
+- *(mds-calendar)* Redraw the range and preview the hover without a parent
+- *(mds-input)* Keep the password mask inside the rounded field
+- *(stencil)* Wire the mds-chip selected state to the tokens the docs promise
+- *(mds-emoji)* Keep the thinking pose centred and let expressions take the face over
+- *(mds-emoji)* Keep the prerender out of the browser only pose restore
+- *(mds-input-date-range)* Repair the :host() selector that voided the slotted color
+- *(stencil)* Write the registered <number> opacities as numbers, not percentages
+- *(stencil)* Delete the ten custom properties nothing ever reads
+- *(stencil)* Drop the two dead properties the codemod manifest flagged
+- *(mds-chip)* Expose the selected state to assistive technology
+- *(stencil)* Remove the seven documented APIs that do not exist at all
+- *(stencil)* Close the mechanical dead chains the full sweep found
+- *(stencil)* Apply the two v1 renames we ship to consumers
+- *(mds-table)* Raise the table background to the overlay surface
+- *(mds-tooltip)* Describe the caller as a tooltip, not as a menu it controls
+- *(mds-input-switch)* Make the native input the focusable, labelled control
+- *(mds-tab-item)* Name icon-only tabs after the host title
+- *(mds-keyboard)* Label the combination checker with aria-label
+- *(mds-progress)* Expose the progress value and hide the nested radial gauge
+- *(mds-details)* Expose the header as a disclosure button, not a banner
+- *(mds-file-preview)* Drop the footer landmark from the infos row
+- *(mds-input-field)* Validate the input that emitted inside the slotted element
+- *(stencil)* Spell the pill one way, on the generated radius scale
+- *(stencil)* Put the hand written radii back on the generated scale
+- *(stencil)* Wire the button corner shape, drop the dead tab style queries
+- *(mds-banner)* Show the actions slotted after the first render
+- *(stencil)* Show the slotted content added after the first render
+- *(mds-dropdown)* Leave the ARIA wiring off a caller that delegates its role
+- *(mds-pref-theme-variant)* Drop the caption that never had a string
+- *(mds-label)* Put the tag back on the pill it was drawn as
+- *(mds-label)* Give the close button one state that shows
+- *(storybook)* Emit the icons named only in the stories
+- *(mds-modal)* Release the body scroll lock when the modal closes
+- *(storybook)* Wrap the body tokens in rgb()
+- *(mds-modal)* Let the page colour through the dialog
+- *(mds-modal)* Measure the bars when the dialog becomes visible
+- *(storybook)* Let the header do what it does on a page
+- *(mds-button-group)* Decide the joined edges among the members of the group
+- *(stencil)* Open a floating panel from its arrow, not from its middle
+- *(mds-dropdown,mds-tooltip)* Place a panel that mounts already visible
+- *(mds-filter)* Centre the selected item wherever the filter sits on the page
+- *(mds-stepper-bar-item)* Number the steps by position, not by child node
+- *(stencil)* Position a floating panel only once it has a box to measure
+- *(mds-dropdown)* Give the panel its outro back
+- *(mds-input-select)* Draw the arrow the way mds-input-date draws its icon
+- *(mds-input-select)* Stop the dark block from repainting the arrow
+- *(mds-mention)* Give the remove button a switch and an event
+- *(mds-table)* Count the selected rows in the batch actions badge
+- *(mds-table-header)* Resolve the select-all switch before ticking it
+- *(storybook)* Key the lists the stories build, and lint for it
+- *(mds-button)* Keep the box of an icon-only button while it awaits
+- *(mds-kpi-item)* Hold the line open while the value is still to come
+- *(stencil)* Animate the text at its full length, from the first frame
+- *(stencil)* Paint the two label variants that four components were missing
+- *(mds-toast)* Park a toast that is not visible outside the screen
+- *(stencil)* Hold back every transition under the animation preference
+- *(stencil)* Let the animations written in JS read the preference too
+- *(mds-tree-item)* End the branch on the icon that covers it
+- *(mds-tree-item)* Give the shorter branch to the first child only
+- *(mds-tree)* Stack the items, not the whitespace between them
+- *(stencil)* Give the entries of a dropdown menu the role of entries
+- *(mds-policy-ai)* Declare the chip panel a group, not a menu
+- *(mds-modal)* Name the dialog, and leave only one of them
+- *(mds-dropdown)* Wire the caller and the panel with references that resolve
+- *(mds-dropdown)* Name the entries of the menu from the panel that declares it
+- *(mds-tooltip)* Let the text of the tip reach the caller it describes
+- *(mds-tab-item)* Let the tab tell whether the popup it opens is showing
+- *(mds-dropdown)* Let go of the caller the target no longer names
+- *(stencil)* Take the escape listener off window when it is detached
+- *(mds-pref-theme)* Write the mode as --magma-pref-theme
+- *(stencil)* Inject the global token fallbacks instead of writing them by hand
+- *(storybook)* Align the chrome and the preview on one color scheme
+- *(mds-badge)* Never fill the outline tone
+- *(mds-progress)* Fill the status bars with the hue, not its ink
+- *(mds-modal)* Keep the close icon visible on the scrim in dark
+- *(mds-file)* Split the name from the extension at the last dot
+
+### Build
+
+- *(magma)* Cache agent docs as stencil build outputs
+- *(magma)* Add all target building every project in dependency order
+- *(magma)* Exclude storybook stories and test files from the stencil build
+- *(magma)* Replace yarn with npm as the package manager
+- *(magma)* Drop the @mdi/svg override in favor of @iconsauce/mdi-svg 1.1.0
+- *(magma)* Update dependencies to fix npm audit vulnerabilities
+- *(magma)* Update nx to 23.1.3
+- *(magma)* Make clean-modules remove all nested node_modules and lockfiles
+- *(magma)* Add the root lint configs to the lint target inputs
+- *(magma)* Add @stencil/vitest and align vitest to 4.1.11
+- *(storybook)* Move to the vite builder and run the stories with the vitest addon
+- *(magma)* Declare each dependency in the project that uses it
+- *(magma)* Resolve svg-icons from the workspace and make the Nx graph analysis explicit
+- *(magma)* Pin the remaining dependency ranges
+
+### Changes
+
+- *(stencil)* Name the mode mode and the named theme theme
+- *(mds-pref-mode)* Drop theme from the visible label
+
+### Documentation
+
+- *(magma)* Add module install instructions for agents
+- *(stencil)* Update property descriptions and types across multiple components
+- *(magma)* Rename install->agents, add usage guide + component catalogue
+- *(stencil)* Update components readme
+- *(stencil)* Update components.d.ts
+- *(mds-accordion-item)* Align docs with disableClose rename
+- *(mds-card-content)* Regenerate component docs
+- *(mds-card-media)* Regenerate component docs
+- *(magma)* Enhance issue templates with new fields and labels
+- *(magma)* Add agentic git governance rules and PR template
+- *(magma)* Require linking work branches to their github issue
+- *(stencil)* Clarify the quiet tone migration mapping
+- *(magma)* Require merge commits when promoting dev into main
+- *(magma)* Detail repo structure in README
+- *(magma)* Require PRs to list every resolved issue with a closing keyword
+- *(stencil)* Add the Semantic roles reference story
+- *(stencil)* Allinea la reference story al ruolo inverse-surface
+- *(mds-usage)* Restate why the dark header overrides stay removed
+- *(mds-paginator)* Clarify that the focus auto-scroll follows keyboard navigation only
+- *(mds-calendar)* Document and register --mds-calendar-max-width
+- *(magma)* Point contributor docs at npm instead of yarn
+- *(magma)* Document the lint gate in CI
+- *(magma)* Document the vitest based stencil tests
+- *(mds-input)* Recommend autocomplete tokens on login fields
+- *(mds-chip)* Regenerate the readme after the selected-state rewiring
+- *(mds-emoji)* Restore the css custom properties table dropped by the rewiring
+- *(magma)* Require a covering test for every behaviour change
+- *(magma)* Point the test docs at the vitest storybook project
+- *(styles,magma)* Document the corner axis, and stop recommending the hatch
+- *(mds-dropdown)* Write down the roles of the panel, and point the examples at an id
+- *(magma)* Let agents open pull requests into dev, still never merge them
+- *(stencil)* Customize the entity and tree stories with semantic roles
+- *(mds-badge)* Regenerate the readme for the outline note
+- *(magma)* Document the wrapper tests
+- *(magma)* Document the tag-only beta releases
+- *(styles,magma)* Update the compatibility table for magma 2 stable
+
+### Features
+
+- *(mds-modal)* Update component properties and styles for improved functionality and consistency
+- *(mds-modal)* Refine animation styles and transitions for improved modal behavior
+- *(magma)* Add .browserslistrc for modern CSS support and update package dependencies
+- *(mds-icon)* Expose IconsSetService to set the SVG path without sessionStorage
+- *(mds-calendar,mds-input-date,mds-input-date-range)* Port magma 1.12 from support/v1.x
+- *(stencil)* Inline the semantic layer as var() fallbacks
+- *(stencil)* Adopt --magma-surface-* in surface components
+- *(mds-table)* Consume semantic surfaces and flip text with the theme
+- *(stencil)* Add the semantic surfaces Storybook cheat-sheet
+- *(stencil)* Wire named themes into storybook and fix the variant components
+- *(stencil)* Coordinate lock-dark between the pref theme lanes
+- *(design-tokens,stencil,styles)* Collapse accent roles to {accent, ai}
+- *(stencil)* [**breaking**] Make the published packages tree-shakeable
+- *(design-tokens,styles,stencil)* Publish the hue role scales and promote them under pref-contrast-more
+- *(styles,stencil)* Register the component custom properties from globals.css
+- *(design-tokens,styles,stencil)* Retint the raw ramp with the theme via --magma-scale-*
+- *(stencil)* Enable SSR with declarative shadow DOM
+- *(stencil)* Add check.ssr guard for SSR regressions
+- *(design-tokens,styles,stencil)* Give the colored hues the emphasis band states
+- *(design-tokens,styles,stencil)* A shadow ink role, the ring family back, and a guard
+- *(stencil)* Add hide-today to mds-calendar and the date inputs
+- *(styles,stencil)* Emit the corner axis, shape and scale in one block
+- *(stencil)* Point the shaped components at the shape-aware scale
+- *(stencil)* Let mds-pref-theme-variant drive the corner axis
+- *(stencil)* Forward an accessible name to the native controls of the inputs
+- *(mds-dropdown)* Walk the menu with the keyboard, and close it back on the caller
+
+### Refactor
+
+- *(mds-modal)* Replace @apply with direct gap property for consistency
+- *(mds-avatar-stack)* Drive slotted item size from parent, drop :host-context
+- *(stencil)* Drive slotted child styling from parent, drop :host-context
+- *(stencil)* Drop precautionary safari :host-context in size container queries
+- *(stencil)* Remove ineffective safari :host-context gates
+- *(mds-tab)* Propagate direction/animation to items, drop :host-context
+- *(mds-table)* Propagate selection to rows, drop :host-context
+- *(mds-tree)* Propagate toggle-position/appearance to items, drop :host-context
+- *(mds-tree)* Resolve effective actions in JS, drop last :host-context
+- *(stencil)* Respect strict boolean condition
+- *(mds-accordion)* Rename closable to disableClose
+- *(mds-banner)* Rename cockade to hideCockade
+- *(mds-breadcrumb)* Rename back to hideBack
+- *(mds-card)* Rename autoGrid to disableAutoGrid
+- *(mds-dropdown)* Rename arrow/autoPlacement/shift/smooth to negative props
+- *(mds-file)* Rename showDownloadedIcon to hideDownloadedIcon
+- *(mds-header)* Rename backdrop to hideBackdrop
+- *(mds-help)* Rename autoPlacement to disableAutoPlacement
+- *(mds-input-date)* Use disable-auto-placement on dropdown
+- *(mds-input-date-range)* Use disable-auto-placement on dropdown
+- *(mds-modal)* Rename backdrop to hideBackdrop
+- *(mds-notification)* Rename visible to dismissed
+- *(mds-pref-language)* Drop autoPlacement on dropdown
+- *(mds-pref-theme-variant)* Drop autoPlacement on dropdown
+- *(mds-push-notification-item)* Default deletable to false
+- *(mds-radial-menu-item)* Use disableAutoPlacement on tooltip
+- *(mds-status-bar)* Use hideBackdrop on modal
+- *(mds-tooltip)* Rename arrow/autoPlacement/shift to negative props
+- *(stencil)* Align floating controller with negative floating props
+- *(stencil)* [**breaking**] Drive language and preferences through a shared reactive store
+- *(storybook)* Sync preview preferences through the addon channel
+- *(mds-pref-language-item)* Use explicit comparisons in code validation
+- *(stencil,styles)* [**breaking**] Migrate --tone-*(bare) usages to --tone-*-seed (#572)
+- *(magma)* Move semantic.config into design-tokens to break the build cycle
+- *(mds-toast)* Consuma il ruolo --magma-surface-inverse
+- *(stencil)* Replace stale bare tone utilities in stories
+- *(stencil)* Read the staged semantic layer from styles build dir
+- *(stencil)* Migrate accent variant partials to semantic accent roles
+- *(design-tokens,styles,stencil)* Name the hue background levels wash-*, not surface-*
+- *(stencil)* Adopt semantic color roles in components
+- *(stencil)* Adopt the semantic status roles where the value is identical
+- *(stencil)* Give the step-04 inks a role, split by what they sit on
+- *(stencil)* Put the status fills on the emphasis band
+- *(stencil)* Adopt the neutral wash band for the pill backgrounds
+- *(stencil)* Give the step-02 inks a role, by what they sit on
+- *(stencil)* Give the status borders a role, strong where the border is the affordance
+- *(magma)* Move the react and angular wrappers out of projects/stencil
+- *(stencil)* [**breaking**] Invert the mds-calendar boolean props to their negative form
+- *(mds-stepper-bar)* Scroll the strip from the boxes
+- *(stencil)* Move the neutral seed backgrounds onto the surface roles
+- *(stencil)* Give the remaining neutral seed grounds a role
+- *(stencil)* Let the contrast layer paint the paper ground
+- *(mds-badge)* Drop the leftovers of the text tone
+- *(stencil)* Move the accent residues onto the accent roles
+- *(stencil)* Move the raw status steps onto the hue roles
+- *(stencil)* Move the ramp-step borders onto the border roles
+- *(stencil)* Retire the ramp steps from the *-pref-* sheets
+- *(stencil)* Move the dark variants onto the inverse roles
+- *(stencil)* Move the step 02 inks onto text-default
+- *(stencil)* Move the step 06 inks onto the text and border roles
+- *(stencil)* Move the step 07 inks onto the text and border roles
+- *(stencil)* Move the step 06/07 grounds onto the wash and border roles
+- *(mds-input)* Align the commented counter hover with wash-base
+- *(stencil)* Move the --magma-scale-NN uses with an identical role onto it
+
+### Styling
+
+- *(stencil)* Update accessibility feature with supported browser specs
+- *(stencil)* Move apply tokens to custom proerty based tokens
+- *(stencil)* Replace pref :host-context with dedicated attributes
+- *(stencil)* Replace pref :host-context in variant files with attributes
+- *(stencil)* Various component styles fixes
+- *(stencil)* Quieter unchecked switch track in dark

package/agents/assets.md

@@ -8,8 +8,8 @@
 ## Purpose
 
 Canonical setup for the assets every Magma consumer needs, **identical for all three
-targets** (web components, React, Angular): styles, fonts, icons and optional brand
-identity. The per-target tracks ([`install.md`](install.md)) link here instead of repeating
+targets** (web components, React, Angular): styles, fonts, icons, optional brand
+identity and editor autocomplete. The per-target tracks ([`install.md`](install.md)) link here instead of repeating
 this. If something about styles/fonts/icons setup is unclear, this file wins.
 
 This file is the minimum to get a consumer running. Once it runs: coloring your own UI
@@ -72,10 +72,10 @@ What each file provides:
 | `colors-rgb.css` | RGB color tokens (`--tone-*`, `--status-*`, ...). Required by components and Tailwind. Also redefines tokens for dark / high-contrast |
 | `typography.css` | The non-color tokens as CSS vars: fonts, type sizes, spacing, radius, shadows (`--shadow-md-sharp`, ...). Components carry their own fallbacks; your CSS needs this file for `var(--shadow-*)`, `var(--radius-*)` and the `--magma-radius-*` corner scale |
 | `reset.css` | Opinionated CSS reset |
-| `hydrated.css` | Anti-FOUC for Stencil - hides components until hydrated |
+| `hydrated.css` | Anti-FOUC for Stencil - hides components until hydrated, then keeps the margin, padding and border they give themselves against a page reset such as Tailwind's preflight. Import it into `base`, as above |
 | `transitions.css`, `animations.css` | Shared motion |
 | `globals.css` | Global `--magma-*` design decisions |
-| `semantic.css` | The semantic color roles (`--magma-surface-*`, `--magma-text-*`, ..., see [`color.md`](color.md)). Required: without it the page `body` has no colour, the Tailwind role utilities paint nothing, and components lose named themes and high contrast |
+| `semantic.css` | The semantic color roles (`--magma-surface-*`, `--magma-text-*`, ..., see [`color.md`](color.md)). Required: without it the page `body` has no colour, the Tailwind role utilities are stuck on their light default (the fallback that gives editors a swatch), and components lose dark mode, named themes and high contrast |
 | `themes.css` | The named themes (`data-theme-name`): retint the semantic roles. Import it after `semantic.css` |
 | `base.css` | Base element styles (sets `--font-info` body font, etc.) |
 
@@ -129,40 +129,173 @@ the `vendor` cascade layer and ship offline.
 ## 3. Icons
 
 Icons are consumed at runtime by `mds-icon`, which fetches each icon as an SVG file from
-a path the host app configures. A slug starts with its icon set (`mi/` Material Icons,
-`mdi/` Material Design Icons, `mgg/` Maggioli) and resolves to
-`<mdsIconSvgPath><slug>.svg`: with the path `/svg/`, `mi/baseline/email` is fetched from
-`/svg/mi/baseline/email.svg`.
+a path the host app configures. The components' own icons are inlined, so what needs
+serving is the icons the app names.
 
-### Package and asset copy
+### The contract
+
+Every slug the app uses must be served at `<mdsIconSvgPath><slug>.svg`: with the path
+`/svg/`, `mi/baseline/email` is fetched from `/svg/mi/baseline/email.svg`. A slug starts
+with its icon set, and each set comes from its own package, with its own layout:
+
+| Slug | Set | Package | File in the package |
+| ---- | --- | ------- | ------------------- |
+| `mi/<variant>/<name>` | Material Icons | `@material-icons/svg` | `svg/<name>/<variant>.svg` |
+| `mdi/<name>` | Material Design Icons | `@mdi/svg` | `svg/<name>.svg` |
+| `mgg/<name>` | Maggioli | `@maggioli-design-system/svg-icons` | `dist/svg/<name>.svg` |
+
+Magma ships only the `mgg/` set, and none of these packages is a dependency of `magma`,
+`magma-react` or `magma-angular`: the route you pick installs what it needs. Copying the
+`svg-icons` folder as it is does NOT follow the contract: its files sit directly in
+`dist/svg/`, while `mds-icon` asks for them under `mgg/`.
+
+`mds-usage` still fetches `mi/baseline/info` for its header: serve it too if the app
+uses that component.
+
+Any setup that follows the contract works. Two tested routes, both run before every dev
+start and build, with the output folder kept out of git:
+
+### Route 1: iconsauce (what Magma uses)
+
+iconsauce reads the sources the way Tailwind reads class names and writes only the icons
+they use, one SVG file per slug, in the folders `mds-icon` expects. Its plugins know the
+three sets and bring their packages along.
 
 ```bash
-npm i @maggioli-design-system/svg-icons
+npm i -D @iconsauce/core @iconsauce/material-icons @iconsauce/mdi-svg @iconsauce/mgg-icons
 ```
 
-Copy the SVG library to a publicly served path. The package ships the files under
-`@maggioli-design-system/svg-icons/dist/svg/`. Copy them to e.g. `public/svg/` (the
-mechanism depends on the bundler - see each track file).
+```js
+// iconsauce.config.mjs
+import mi from '@iconsauce/material-icons';
+import mdi from '@iconsauce/mdi-svg';
+import mgg from '@iconsauce/mgg-icons';
 
-### Tell mds-icon where the icons are
+export default {
+  content: ['./index.html', './src/**/*.{html,js,jsx,ts,tsx}'], // every file where icon slugs are written
+  plugin: [mi, mdi, mgg],
+};
+```
 
-The simplest way: set `mdsIconSvgPath` in `sessionStorage` before components hydrate.
-The value is the public URL of the folder you copied the SVGs into:
+```json
+"scripts": {
+  "icons": "iconsauce --config ./iconsauce.config.mjs --output-svg ./public/svg",
+  "predev": "npm run icons",
+  "prebuild": "npm run icons"
+}
+```
 
-```javascript
-window.sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+A slug built at runtime (`'mi/baseline/' + name`) is invisible to iconsauce: write slugs
+in full, or list the computed ones in a file that `content` reads.
+
+### Route 2: serve the files yourself
+
+One renaming step: `@material-icons/svg` stores `<name>/<variant>.svg`, while the slug
+wants `mi/<variant>/<name>`. `mdi/` and `mgg/` are plain folder copies. This script covers
+the three sets with Node built-ins only, so it fits any bundler:
+
+```bash
+npm i -D @maggioli-design-system/svg-icons @material-icons/svg @mdi/svg
 ```
 
-Alternatives, documented in
-the mds-icon readme:
+```js
+// scripts/copy-icons.mjs
+// Copies Magma's icon sets where mds-icon fetches them: <OUT>/<slug>.svg.
+//   node scripts/copy-icons.mjs icons.json   only the slugs listed in icons.json
+//   node scripts/copy-icons.mjs              every icon of the three sets (18,720 files, 73 MB)
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const OUT = 'public/svg'; // served at /svg/ by Vite, Next.js and the Angular CLI
+const require = createRequire(import.meta.url);
+const root = (pkg) => dirname(require.resolve(`${pkg}/package.json`));
+const MI = join(root('@material-icons/svg'), 'svg'); // <name>/<variant>.svg
+const MDI = join(root('@mdi/svg'), 'svg'); // <name>.svg
+const MGG = join(root('@maggioli-design-system/svg-icons'), 'dist/svg'); // <name>.svg
+
+// Source file of a slug: mi/<variant>/<name>, mdi/<name>, mgg/<name>.
+function source(slug) {
+  const [set, ...rest] = slug.split('/');
+  if (set === 'mi' && rest.length === 2) return join(MI, rest[1], `${rest[0]}.svg`);
+  if (set === 'mdi' && rest.length === 1) return join(MDI, `${rest[0]}.svg`);
+  if (set === 'mgg' && rest.length === 1) return join(MGG, `${rest[0]}.svg`);
+  throw new Error(`Not a Magma icon slug: ${slug}`);
+}
+
+function allSlugs() {
+  const names = (dir) => readdirSync(dir).map((file) => file.replace(/\.svg$/, ''));
+  return [
+    ...readdirSync(MI).flatMap((name) => names(join(MI, name)).map((variant) => `mi/${variant}/${name}`)),
+    ...names(MDI).map((name) => `mdi/${name}`),
+    ...names(MGG).map((name) => `mgg/${name}`),
+  ];
+}
+
+const slugs = process.argv[2] ? JSON.parse(readFileSync(process.argv[2], 'utf8')) : allSlugs();
+for (const slug of slugs) {
+  const file = source(slug);
+  if (!existsSync(file)) throw new Error(`No such icon: ${slug} (${file})`);
+  const target = join(OUT, `${slug}.svg`);
+  mkdirSync(dirname(target), { recursive: true });
+  copyFileSync(file, target);
+}
+console.log(`${slugs.length} icons in ${OUT}/`);
+```
+
+`icons.json` lists the slugs the app uses:
+
+```json
+["mi/baseline/email", "mi/baseline/send", "mdi/github", "mgg/abitazione-principale"]
+```
+
+```json
+"scripts": {
+  "icons": "node scripts/copy-icons.mjs icons.json",
+  "predev": "npm run icons",
+  "prebuild": "npm run icons"
+}
+```
+
+A slug that does not exist stops the script with an error. A slug used in the code but
+missing from `icons.json` gives a 404 at runtime: iconsauce avoids that by reading the
+sources. Without `icons.json` the script copies every icon of the three sets, all of
+them deployed: 18,720 files and 73 MB (`mi` 43 MB in five variants, `mdi` 29 MB, `mgg`
+1.3 MB).
+
+### Only the `mgg/` set
+
+An app that uses only Maggioli icons can copy the `svg-icons` folder, into `mgg/` under
+the served path: `@maggioli-design-system/svg-icons/dist/svg/` to `public/svg/mgg/`. With
+the Angular CLI that is an `assets` entry in `angular.json`:
+
+```json
+{ "glob": "**/*.svg", "input": "node_modules/@maggioli-design-system/svg-icons/dist/svg", "output": "/svg/mgg" }
+```
+
+### Tell mds-icon where the icons are
+
+Set the public URL of the folder the icons are served from, before the first `mds-icon`
+renders. Two ways:
 
 - `IconsSetService.setSvgPath('/svg/')`, imported from
-  `@maggioli-design-system/magma/services`: sets the path in code, without
-  `sessionStorage`, and reloads the icons already mounted
-- `mdsIcon.setSvgPath('/svg/')` - instance method on a temporary `mds-icon` node, after
-  `defineCustomElements()` has run
-- dispatch `new CustomEvent('mdsIconSvgPathUpdate')` on `window` to force a refresh
-  after changing the path
+  `@maggioli-design-system/magma/services` (recommended): sets the path in code, without
+  `sessionStorage`, and reloads the icons already mounted.
+- the `mdsIconSvgPath` key in `sessionStorage`, a one-liner the install tracks use. Some
+  browsers block storage (private windows, sandboxed iframes, storage partitioning): there
+  only `IconsSetService` works.
+
+```javascript
+import { IconsSetService } from '@maggioli-design-system/magma/services';
+
+IconsSetService.setSvgPath('/svg/');
+// or: window.sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+```
+
+Icons mounted before a path set through `sessionStorage` reload on
+`window.dispatchEvent(new CustomEvent('mdsIconSvgPathUpdate'))`. Every option, with its
+snippet, is in the
+[`mds-icon` pattern](../../magma/dist/collection/components/mds-icon/pattern.md).
 
 Reference an icon by slug, never inline SVG and never import from an icon-set package:
 
@@ -190,14 +323,84 @@ Assets live under `@maggioli-design-system/identity/dist/`:
 - `dist/illustrations/`, `dist/products/` - additional brand imagery
 
 These are static read-only files - serve them like any other asset, do not modify
-them in the consumer project.
+them in the consumer project. `dist/identity.json` describes them: one entry per family of
+artworks, with its name as the artwork writes it, its owner and kind, and every variant with
+its path, form, colour, the background it is drawn for and its size. Read names and alt texts
+from it instead of from the file names, which lose accents and punctuation.
+
+## 5. Editor autocomplete
+
+Two halves, one extension each. Set them up in VS Code; for another editor, point its CSS
+custom property completion at the same `tokens.editor.css` and leave the rest to the user.
+
+| Completes | Extension | Fed by |
+| --------- | --------- | ------ |
+| Magma tokens inside `var(--...)`, in scale order, with a swatch on colors | CSS Var Complete (`phoenisx.cssvar`) | `@maggioli-design-system/styles/dist/css/tokens.editor.css`, every public token once |
+| Tailwind classes (`bg-surface-default`, `p-600`), with their value | Tailwind CSS IntelliSense (`bradlc.vscode-tailwindcss`), only if the app uses Tailwind | the CSS entry that imports Tailwind and Magma's theme (section 1) |
+
+MERGE these keys into `.vscode/settings.json` and `.vscode/extensions.json`: never overwrite
+a file that exists, the user's own settings stay.
+
+```json
+{
+  "cssvar.files": ["node_modules/@maggioli-design-system/styles/dist/css/tokens.editor.css"],
+  "cssvar.ignore": [],
+  "cssvar.disableSort": true
+}
+```
+
+```json
+{
+  "recommendations": ["phoenisx.cssvar", "bradlc.vscode-tailwindcss"],
+  "unwantedRecommendations": ["vunguyentuan.vscode-css-variables"]
+}
+```
+
+Leave `bradlc.vscode-tailwindcss` out of `recommendations` when the app has no Tailwind.
+
+The traps, all measured:
+
+- `cssvar.ignore` must be `[]`: its default, `["**/node_modules/**"]`, is applied over
+  `cssvar.files`, so the path above is dropped and nothing completes.
+- `cssvar.disableSort: true` keeps the order of the file (a scale from its smallest step
+  up); without it the list is alphabetical.
+- `vunguyentuan.vscode-css-variables` goes in `unwantedRecommendations`: it sorts
+  alphabetically, never opens the list by itself and duplicates every entry next to CSS
+  Var Complete.
+- Never import `tokens.editor.css` in the app: it is for editors only, and holds light
+  defaults that would freeze theming (it is wrapped in a query that never matches, so an
+  import does nothing at best).
+
+Tailwind IntelliSense finds the CSS entry on its own, the split imports of section 1
+included. Only if hovering a class shows nothing, add
+`"tailwindCSS.experimental.configFile": "<path of that CSS file>"`. If the app builds class
+names through functions (`clsx`, `cva`, `cn`), list the ones it uses in
+`"tailwindCSS.classFunctions"`, so the classes inside their calls complete too.
+
+Verify, after reloading the window:
+
+- 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.
+
+Known limits, nothing to configure:
+
+- Tailwind IntelliSense lists the utilities alphabetically, whatever the order of the
+  theme: `bg-surface-bisque-*` comes before `bg-surface-default`. Type the role name.
+- The class list offers Tailwind's stock spacing steps (`p-1` ... `p-96`), not Magma's:
+  with Magma's theme `p-1` is 0.04px. Write the Magma steps in full (`p-600`, `gap-400`):
+  they work and hover with their value, they are just not suggested.
 
 ## Checklist
 
 - [ ] `styles` + `design-tokens` installed on the matching version row
 - [ ] Global CSS imports in the exact cascade-layer order above
 - [ ] `@fontsource` fonts installed and imported in the `vendor` layer
-- [ ] `svg-icons` SVGs copied to a public path
+- [ ] Every icon slug the app uses served at `<mdsIconSvgPath><slug>.svg` (iconsauce or
+      the copy script, run before dev and build, output folder out of git)
 - [ ] `mdsIconSvgPath` set to that public path before hydration
 - [ ] (optional) `identity` installed if brand assets are used
 - [ ] Components registered per your target track
+- [ ] (VS Code) the editor keys merged into `.vscode/settings.json` and `extensions.json`;
+      `var(--magma-` completes, and with Tailwind `bg-surface-default` shows a swatch

package/agents/color.md

@@ -55,9 +55,11 @@ Tailwind names the TEXT roles `fg-*`, so a utility never reads `text-text-*`:
 `border-border-default`, `bg-accent-emphasis`, `bg-danger-wash-base`.
 
 Both faces need the setup in [`assets.md`](assets.md): the values come from
-`styles/dist/css/semantic.css` (without it every role paints nothing), the Tailwind
-utilities from `styles/dist/tailwind/theme.css`. A Tailwind modifier works as usual
-(`bg-surface-raised/80`).
+`styles/dist/css/semantic.css`, the Tailwind utilities from `styles/dist/tailwind/theme.css`.
+Without `semantic.css` a `var(--magma-*)` paints nothing, and a Tailwind utility paints the
+light default of its role, the fallback its bridge carries so editors can show a swatch: in
+dark mode, with a named theme or with more contrast it stays wrong, so the file is still
+required. A Tailwind modifier works as usual (`bg-surface-raised/80`).
 
 ## The roles
 

package/agents/components.md

@@ -83,10 +83,10 @@
 | [`mds-pref-animation`](../../magma/dist/collection/components/mds-pref-animation/AGENTS.md) | The `<mds-pref-animation>` web component is a preference control that lets users choose how animations are presented (reduced, system-driven, or fully enabled) |
 | [`mds-pref-consumption`](../../magma/dist/collection/components/mds-pref-consumption/AGENTS.md) | The `<mds-pref-consumption>` web component is a preference control of the Magma Design System that lets the user pick an energy-consumption mode (`low`, `medium`, `high`); it is usually a child of `<mds-pref>` and renders as a tab group with one option per mode, so it has no native HTML primitive equivalent. |
 | [`mds-pref-contrast`](../../magma/dist/collection/components/mds-pref-contrast/AGENTS.md) | The `<mds-pref-contrast>` web component is a preference control that lets users switch the application's contrast mode (`more`, `system`, or `no-preference`) |
-| [`mds-pref-language`](../../magma/dist/collection/components/mds-pref-language/AGENTS.md) | The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, designed to be slotted inside `<mds-pref>` alongside the other preference children |
+| [`mds-pref-language`](../../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, designed to live as a direct child of `<mds-pref>` |
-| [`mds-pref-theme`](../../magma/dist/collection/components/mds-pref-theme/AGENTS.md) | The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, designed to live as a direct child of `<mds-pref>` |
+| [`mds-pref-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 |

package/agents/install.md

@@ -24,7 +24,7 @@ npm i @maggioli-design-system/magma-react @maggioli-design-system/magma
 matrix). Then install the assets from [`assets.md`](assets.md):
 
 ```bash
-npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens @maggioli-design-system/svg-icons
+npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens
 npm i @fontsource/karla @fontsource/merriweather @fontsource/roboto @fontsource/roboto-mono
 ```
 
@@ -116,9 +116,10 @@ export default function RootLayout({
 
 ## 4. Serve the icon SVGs and styles
 
-- Copy `@maggioli-design-system/svg-icons/dist/svg/` into the static folder served at
-  `/svg/` (Vite/CRA: `public/svg/`; Next.js: `public/svg/`). Match the path you pass
-  to `mdsIconSvgPath`.
+- Write the icons into the static folder served at `/svg/` (Vite and Next.js:
+  `public/svg/`) with one of the routes of [`assets.md`](assets.md) section 3
+  (iconsauce or the copy script, run from `predev` and `prebuild`). Match the path you
+  pass to `mdsIconSvgPath`.
 - Import the global CSS block from [`assets.md`](assets.md) in your global stylesheet
   (`app/globals.css`, `src/index.css`, ...) so the cascade-layer order is preserved.
 
@@ -168,6 +169,38 @@ SSR notes:
   server-only). It is imported lazily behind a `typeof window` check and must
   never end up in a client bundle.
 
+## 6. Client-side routing
+
+The links of the components (`href` of `MdsButton`, `MdsTabItem`, ...) are real anchors
+the browser follows, loading the page. Register the router once, in the client wrapper of
+section 3, and every plain click on a component link is routed on the client instead; a
+modifier or middle click, `target="blank"` and a link to another origin stay with the browser.
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { useRouter } from 'next/navigation';
+import { NavigationService } from '@maggioli-design-system/magma/services';
+
+export default function ClientGlobalsWrapper({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  const router = useRouter();
+
+  useEffect(() => {
+    sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+  }, []);
+  // setHandler returns the function that removes the handler: the cleanup of the effect
+  useEffect(() => NavigationService.setHandler((href) => router.push(href)), [router]);
+
+  return <>{children}</>;
+}
+```
+
+With React Router the handler is `(href) => navigate(href)` from `useNavigate()`. Return
+`false` from the handler for a link the browser is to load. Without a registered router, an
+`onClick` on the component can still cancel the click with `preventDefault()` and route by hand.
+
 ## Gotchas
 
 - The icon path effect must run on the client. In Next.js App Router the wrapper that

package/agents/reporting.md

@@ -0,0 +1,127 @@
+<!--
+  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 - reporting a problem
+
+> Scope: you are working in a project that uses Magma and you hit a problem that is
+> Magma's, not the project's: a component that misbehaves, a guide that is wrong, a
+> missing token or utility, a packaging or install issue. This is how to report it to
+> the Magma repository, `magma-design-system/magma`, labelled with the project it comes
+> from, so the maintainers can tell which project reported what.
+
+## 1. Make sure it is Magma's
+
+- Read the component's `AGENTS.md` and `antipattern.md`, and
+  [`anti-patterns.md`](anti-patterns.md): a documented mistake is the project's to fix,
+  not a Magma bug.
+- Check that the installed `magma`, `styles` and `design-tokens` versions belong
+  together (the ones a `magma` release depends on): mismatched versions break tokens
+  and styles on their own.
+- Reduce it to the smallest markup that still shows the problem, without the project's
+  own CSS or wrappers when you can.
+
+## 2. Look for an existing issue
+
+```bash
+gh issue list --repo magma-design-system/magma --state all --search "<component or keywords>"
+```
+
+If one already describes it, comment there with what is new (your versions, another
+reproduction) and the project you hit it in, instead of opening a duplicate.
+
+## 3. Ask before you open it
+
+The Magma repository is public: opening an issue publishes its text. Draft the issue,
+show it to the user, and create it only once they agree. Leave out anything private to
+the project: internal URLs, credentials, customer data, unreleased features.
+
+## 4. Pick the labels
+
+Every issue carries three kinds of label:
+
+| Label | Says | Values |
+| ----- | ---- | ------ |
+| type | what kind of issue | `bug`, `feature`, `docs` |
+| `prg-*` | which Magma package is affected | `prg-stencil` (the components: `magma`, `magma-react`, `magma-angular`), `prg-styles`, `prg-design-tokens`, `prg-svg-icons`, `prg-icons`, `prg-identity` |
+| `prd-*` | which project it was found in (its origin) | one per project, e.g. `prd-mindy` |
+
+Find this project's origin label. Each one's description names the project and its
+repository:
+
+```bash
+gh label list --repo magma-design-system/magma --search prd-
+```
+
+Match it against this project's repository name (the `origin` remote, or the `name` in
+`package.json`). If none matches, do not create one: the Magma maintainers manage the
+labels of their repository, and a label missing from their configuration is deleted by
+the next sync. Open the issue without it, and propose its name in the body, so the
+maintainers add it as it is: `prd-` and the project's short name, lowercase, in
+kebab-case (`prd-mindy` for `mindy-webapp`, `prd-docs` for the docs site). Leave out
+generic words such as `app`, `webapp`, `frontend` or the organization's name.
+
+GitHub sets labels on a new issue only for users with write access to the repository,
+and drops them for everyone else, often without an error. After creating the issue,
+check what it got:
+
+```bash
+gh issue view <number> --repo magma-design-system/magma --json labels
+```
+
+If the labels were dropped, the `Found in` line of the body is what the maintainers
+label it from.
+
+## 5. Write it
+
+In English. Title: `<component or package>: <what is wrong>`, e.g.
+`mds-modal: the window jumps on open`. Body:
+
+```markdown
+## Problem
+
+What happens, and what should happen instead.
+
+## How to reproduce
+
+The minimal markup or the steps, and the browser if it matters.
+
+## Versions
+
+- @maggioli-design-system/magma (or magma-react / magma-angular): <installed version>
+- @maggioli-design-system/styles: <installed version>
+- @maggioli-design-system/design-tokens: <installed version>
+- Framework: <e.g. Next 16 + React 19, Angular 20, none>
+
+## Workaround
+
+What the project does meanwhile, if anything.
+
+Found in <project> (<repository>): <where in the app>.
+```
+
+When step 4 found no origin label, end the body with the one you propose:
+
+```markdown
+No origin label for this project yet: proposed `prd-<name>`.
+```
+
+Read the installed versions from the lockfile or `npm ls`, not from the ranges in
+`package.json`.
+
+## 6. Create it
+
+```bash
+gh issue create --repo magma-design-system/magma \
+  --title "mds-modal: the window jumps on open" \
+  --label bug --label prg-stencil --label prd-<project> \
+  --body-file magma-issue.md
+```
+
+Pass only labels that exist: `gh` refuses an unknown one. Without `gh`, give the user
+the title, the labels and the body to open it by hand at
+`https://github.com/magma-design-system/magma/issues/new`.
+
+Then give the user the issue URL, and leave a comment in the project next to the
+workaround that links it, so the workaround can go once the fix ships.

package/agents/theming.md

@@ -138,3 +138,18 @@ by itself changes the shape WITHOUT the scale.
 In your own CSS take radii from the `--magma-radius-*` scale (`none`, `3xs` ... `5xl`,
 `full`), which follows the axis: `border-radius: var(--magma-radius-lg)`. A raw
 `--radius-*` token or a pixel value stays the same under every shape.
+
+A browser without `corner-shape` (Firefox, Safari) gets round corners and the round
+scale on its own. A control of your own whose radius is past half its height
+(Chromium clamps it to half the height) needs one more step to keep its look there:
+cap the radius at a part of its height, as Magma's buttons and fields do.
+
+```css
+.my-control {
+  --my-control-height: 2.25rem;
+
+  border-radius: min(var(--magma-radius-2xl), var(--magma-corner-cap) * var(--my-control-height));
+  corner-shape: var(--magma-corner-shape);
+  min-height: var(--my-control-height);
+}
+```

package/dist/mds-input-date-range.server.js

@@ -12,6 +12,7 @@ export const MdsInputDateRange = /*@__PURE__*/ createComponent({
         min: 'min',
         max: 'max',
         delay: 'delay',
+        size: 'size',
         hideToday: 'hide-today',
         dualCalendar: 'dual-calendar',
         name: 'name',

package/dist/mds-input-date.server.js

@@ -13,6 +13,7 @@ export const MdsInputDate = /*@__PURE__*/ createComponent({
         min: 'min',
         max: 'max',
         delay: 'delay',
+        size: 'size',
         hideToday: 'hide-today',
         disabled: 'disabled',
         readonly: 'readonly',

package/dist/mds-input-select.server.js

@@ -14,6 +14,7 @@ export const MdsInputSelect = /*@__PURE__*/ createComponent({
         disabled: 'disabled',
         required: 'required',
         multiple: 'multiple',
+        rows: 'rows',
         size: 'size',
         value: 'value',
         defaultValue: 'default-value',

package/dist/mds-input.server.js

@@ -26,6 +26,7 @@ export const MdsInput = /*@__PURE__*/ createComponent({
         required: 'required',
         variant: 'variant',
         tip: 'tip',
+        size: 'size',
         step: 'step',
         type: 'type',
         typography: 'typography',

package/dist/mds-table-header-cell.js

@@ -7,6 +7,6 @@ export const MdsTableHeaderCell = /*@__PURE__*/ createComponent({
     elementClass: MdsTableHeaderCellElement,
     // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
     react: React,
-    events: {},
+    events: { onMdsTableHeaderCellSort: 'mdsTableHeaderCellSort' },
     defineCustomElement: defineMdsTableHeaderCell
 });

package/dist/mds-table-header-cell.server.js

@@ -8,6 +8,7 @@ export const MdsTableHeaderCell = /*@__PURE__*/ createComponent({
     properties: {
         sortable: 'sortable',
         label: 'label',
+        sortKey: 'sort-key',
         direction: 'direction'
     },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,

package/dist/mds-table.server.js

@@ -8,7 +8,8 @@ export const MdsTable = /*@__PURE__*/ createComponent({
     properties: {
         interactive: 'interactive',
         selectable: 'selectable',
-        selection: 'selection'
+        selection: 'selection',
+        sorting: 'sorting'
     },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,
     clientModule: clientComponents.MdsTable,

package/dist/mds-tooltip.server.js

@@ -13,6 +13,7 @@ export const MdsTooltip = /*@__PURE__*/ createComponent({
         target: 'target',
         offset: 'offset',
         placement: 'placement',
+        relation: 'relation',
         typography: 'typography',
         disableShift: 'disable-shift',
         shiftPadding: 'shift-padding',

package/dist/mds-usage.server.js

@@ -7,7 +7,8 @@ export const MdsUsage = /*@__PURE__*/ createComponent({
     tagName: 'mds-usage',
     properties: {
         variant: 'variant',
-        alias: 'alias'
+        alias: 'alias',
+        icon: 'icon'
     },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,
     clientModule: clientComponents.MdsUsage,

package/dist/types/mds-table-header-cell.d.ts

@@ -2,8 +2,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 { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
+import { type MdsTableHeaderCellCustomEvent, type MdsTableHeaderCellSortEventDetail } from "@maggioli-design-system/magma";
 import type { Components } from "@maggioli-design-system/magma/dist/components";
 import { MdsTableHeaderCell as MdsTableHeaderCellElement } from "@maggioli-design-system/magma/dist/components/mds-table-header-cell.js";
-export type MdsTableHeaderCellEvents = NonNullable<unknown>;
+export type MdsTableHeaderCellEvents = {
+    onMdsTableHeaderCellSort: EventName<MdsTableHeaderCellCustomEvent<MdsTableHeaderCellSortEventDetail>>;
+};
 export declare const MdsTableHeaderCell: StencilReactComponent<MdsTableHeaderCellElement, MdsTableHeaderCellEvents, Components.MdsTableHeaderCell>;

package/dist/types/mds-table-header-cell.server.d.ts

@@ -2,10 +2,13 @@
  * 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 { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
 import { type SerializeShadowRootOptions } from '@stencil/react-output-target/ssr';
+import { type MdsTableHeaderCellCustomEvent, type MdsTableHeaderCellSortEventDetail } from "@maggioli-design-system/magma";
 import type { Components } from "@maggioli-design-system/magma/dist/components";
 import { MdsTableHeaderCell as MdsTableHeaderCellElement } from "@maggioli-design-system/magma/dist/components/mds-table-header-cell.js";
 export declare const serializeShadowRoot: SerializeShadowRootOptions;
-export type MdsTableHeaderCellEvents = NonNullable<unknown>;
+export type MdsTableHeaderCellEvents = {
+    onMdsTableHeaderCellSort: EventName<MdsTableHeaderCellCustomEvent<MdsTableHeaderCellSortEventDetail>>;
+};
 export declare const MdsTableHeaderCell: StencilReactComponent<MdsTableHeaderCellElement, MdsTableHeaderCellEvents, Components.MdsTableHeaderCell>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maggioli-design-system/magma-react",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "main": "dist/components.js",
   "module": "dist/components.js",
   "types": "dist/types/components.d.ts",
@@ -26,13 +26,14 @@
   "files": [
     "dist",
     "AGENTS.md",
-    "agents/"
+    "agents/",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@maggioli-design-system/magma": "2.1.0",
+    "@maggioli-design-system/magma": "2.3.0",
     "@stencil/react-output-target": "1.6.2"
   },
   "repository": {