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

package/AGENTS.md

@@ -5,7 +5,7 @@
 -->
 # @maggioli-design-system/magma-react - agent install guide
 
-> Version 2.6.0. You (the agent) are installing Magma into THIS project. Do not
+> Version 2.7.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,

package/CHANGELOG.md

@@ -7,6 +7,30 @@ package.
 It is released together with `magma`, at the same version: the sections are the
 releases of `magma`.
 
+## [magma@2.7.0] - 2026-10-24
+
+### Bug Fixes
+
+- *(lint)* Spell multi-word Material slugs with hyphens, as iconsauce serves them
+- *(lint)* Check_setup accepts every icon path and lint config its guides document
+- *(lint)* Serialise every DTCG type of the token tools, keep the class of suggest_role
+- *(lint)* No-internal-tokens reads the custom properties of Tailwind classes and @apply
+
+### Build
+
+- *(magma)* Keep test fixtures out of the release package map
+
+### Documentation
+
+- *(magma)* Write where each answer of the lint and the MCP server comes from
+- *(magma)* Route agents to the data contracts, stop loading the consumer guides
+
+### Features
+
+- *(lint)* Ship the MCP tools as data, describe the Stylelint rules, link the release
+- *(lint)* Lead the agent to propose an issue when the MCP server lacks a tool
+- *(lint)* Read classes in clsx(), ternaries, [ngClass] and @apply, as the codemod does
+
 ## [magma@2.6.0] - 2026-10-24
 
 ### Bug Fixes

package/agents/assets.md

@@ -154,6 +154,12 @@ with its icon set, and each set comes from its own package, with its own layout:
 | `mdi/<name>` | Material Design Icons | `@mdi/svg` | `svg/<name>.svg` |
 | `mgg/<name>` | Maggioli | `@maggioli-design-system/svg-icons` | `dist/svg/<name>.svg` |
 
+The slugs are the ones iconsauce writes (Route 1), so a Material slug is not the name of
+its folder: a multi-word name takes hyphens in the slug and underscores in the package
+(`mi/baseline/check-circle` is `svg/check_circle/baseline.svg`), and the variants are
+`baseline`, `outline`, `round` and `sharp`. The package's `twotone.svg` has no slug: iconsauce
+never serves it, and a slug spelled with the folder's underscores renders nothing.
+
 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
@@ -200,8 +206,9 @@ 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
+One renaming step: `@material-icons/svg` stores `check_circle/baseline.svg`, while the slug
+wants `mi/baseline/check-circle` (the contract above). `mdi/` and `mgg/` are plain folder
+copies. This script covers
 the three sets with Node built-ins only, so it fits any bundler:
 
 ```bash
@@ -212,7 +219,7 @@ npm i -D @maggioli-design-system/svg-icons @material-icons/svg @mdi/svg
 // 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)
+//   node scripts/copy-icons.mjs              every icon of the three sets (16,530 files, 64 MB)
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
@@ -220,14 +227,18 @@ 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 MI = join(root('@material-icons/svg'), 'svg'); // <name_with_underscores>/<variant>.svg
 const MDI = join(root('@mdi/svg'), 'svg'); // <name>.svg
 const MGG = join(root('@maggioli-design-system/svg-icons'), 'dist/svg'); // <name>.svg
 
+// The Material variants iconsauce serves; a slug spells the folder's underscores as hyphens.
+const MI_VARIANTS = ['baseline', 'outline', 'round', 'sharp'];
+
 // 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 === 'mi' && rest.length === 2 && MI_VARIANTS.includes(rest[0]) && !rest[1].includes('_'))
+    return join(MI, rest[1].replaceAll('-', '_'), `${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}`);
@@ -236,7 +247,9 @@ function source(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}`)),
+    ...readdirSync(MI).flatMap((folder) =>
+      MI_VARIANTS.map((variant) => `mi/${variant}/${folder.replaceAll('_', '-')}`),
+    ),
     ...names(MDI).map((name) => `mdi/${name}`),
     ...names(MGG).map((name) => `mgg/${name}`),
   ];
@@ -256,7 +269,7 @@ 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"]
+["mi/baseline/email", "mi/outline/check-circle", "mdi/github", "mgg/abitazione-principale"]
 ```
 
 ```json
@@ -270,7 +283,7 @@ console.log(`${slugs.length} icons in ${OUT}/`);
 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`
+them deployed: 16,530 files and 64 MB (`mi` 34 MB in four variants, `mdi` 29 MB, `mgg`
 1.3 MB).
 
 ### Only the `mgg/` set
@@ -409,7 +422,8 @@ Known limits, nothing to configure:
 - [ ] `@fontsource` fonts installed and imported in the `vendor` layer
 - [ ] 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
+- [ ] That public path set before hydration (`IconsSetService.setSvgPath()` or the
+      `mdsIconSvgPath` key of `sessionStorage`)
 - [ ] (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`;

package/agents/conventions.md

@@ -121,7 +121,8 @@ Maggioli):
 ```
 
 `mds-icon` fetches `<mdsIconSvgPath><slug>.svg`; the path is configured once at startup
-(see [`assets.md`](assets.md)): `sessionStorage.setItem('mdsIconSvgPath', '/svg/')`.
+(see [`assets.md`](assets.md)): `IconsSetService.setSvgPath('/svg/')`, or
+`sessionStorage.setItem('mdsIconSvgPath', '/svg/')`.
 
 ## Accessibility
 

package/agents/lint.md

@@ -55,8 +55,9 @@ export default [
 ];
 ```
 
-The rules read both `<mds-button>` and the wrappers of `magma-react` (`<MdsButton>`), and a
-`className` written as a string or a template literal.
+The rules read both `<mds-button>` and the wrappers of `magma-react` (`<MdsButton>`), and the
+classes of a `className` wherever its expression writes them, `clsx()` and ternaries included
+(see [`no-raw-palette-classes`](#no-raw-palette-classes)).
 
 ### Angular
 
@@ -111,7 +112,7 @@ component may change in any release. When a rule is wrong about Magma itself, re
 | [`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-raw-palette-classes`](#no-raw-palette-classes) | ESLint, Stylelint | 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 |
@@ -190,8 +191,30 @@ read through: `dark:hover:bg-white/50` is `bg-white`.
 ```
 
 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.
+the pure extreme of the mode.
+
+A class is read wherever the project writes one, in the forms the codemod migrates:
+
+- the `class` attribute of HTML and Angular templates;
+- React: every string in a `className` (or `class`) expression, the arguments and object keys
+  of `clsx()` or `classnames()`, both branches of a ternary, a `||` fallback, and the fixed
+  parts of a template literal;
+- Angular: the key of `[class.<name>]` and the quoted strings of `[ngClass]`, `[class]` and
+  `[attr.class]`;
+- Stylelint: the classes of `@apply`.
+
+```tsx
+// INCORRECT
+<div className={clsx('p-400', active && 'bg-white')} />
+
+// CORRECT
+<div className={clsx('p-400', active && 'bg-surface-raised')} />
+```
+
+Not read: a class put together at run time (`bg-${tone}-03`, of which only the fixed parts are
+read), classes kept in a variable outside the attribute (`const card = clsx(...)`), and HTML
+written as a string in a script (`el.innerHTML = ...`). A string compared in a condition is
+read too, and reported only when it is itself a palette class.
 
 ### no-color-scheme-override
 
@@ -240,9 +263,13 @@ Any other colour that is not a role keeps its literal under a disable comment th
 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.
+component documents is reported too. Stylelint reads the stylesheets, the classes of `@apply`
+included; ESLint reads the inline styles of the templates (a `style` attribute, a React
+`style={{ '--mds-<name>': ... }}` object, an Angular `[style.--mds-<name>]` binding) and their
+Tailwind classes, wherever [`no-raw-palette-classes`](#no-raw-palette-classes) reads a class,
+through variants and `!`: an arbitrary property that sets one
+(`[--mds-<name>:<value>]`, on the component or on a parent that sets it for its descendants)
+and an arbitrary value that reads one (`bg-[var(--mds-<name>)]`, `bg-(--mds-<name>)`).
 
 ```css
 /* INCORRECT: internal, it may change in any release */
@@ -266,5 +293,6 @@ The rules need no settings: they read the `documentation.json` beside them in th
 `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:
+take the paths they read as secondary options, `root` and `documentation` for `no-internal-tokens`
+and `no-raw-color`, `root`, `tokens` and `consumption` for `no-raw-palette-classes`:
 `'magma/no-internal-tokens': [true, { documentation: './documentation.json' }]`.

package/agents/mcp.md

@@ -84,7 +84,7 @@ client starts servers elsewhere than the project's root, pass it:
 | `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 |
+| `suggest_role` | the role for a colour, a raw class or a palette step, as a class of the same utility (`shadow-*/80` stays a shadow class) | 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 |
@@ -92,7 +92,8 @@ client starts servers elsewhere than the project's root, pass it:
 | `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)).
+the lint ([`lint.md`](lint.md)). The same definitions, for a tool that documents them, are in
+`@maggioli-design-system/magma/dist/lint/mcp/tools.json`: what `tools/list` answers.
 
 ## When to call them
 
@@ -101,3 +102,6 @@ the lint ([`lint.md`](lint.md)).
 - 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`.
+- When no tool gives you what the task needs, or an answer carries `gap`: tell the user,
+  and at the end of the task propose an issue on Magma
+  ([`reporting.md`](reporting.md), "A tool or an answer the MCP server is missing").

package/agents/reporting.md

@@ -7,8 +7,9 @@
 
 > 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
+> missing token or utility, a packaging or install issue, or something you needed that
+> the Magma MCP server does not answer (section 7). 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
@@ -125,3 +126,53 @@ the title, the labels and the body to open it by hand at
 
 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.
+
+## 7. A tool or an answer the MCP server is missing
+
+The tools of the Magma MCP server ([`mcp.md`](mcp.md)) are there so you never read the
+installed files by hand or guess. When one of them could not give you what the task
+needed, Magma wants to know: the next tool or field comes from these reports. It is a gap
+when:
+
+- no tool covers the question, and you answered it by reading Magma's files
+  (`documentation.json`, the token data, the guides) or by guessing;
+- a tool said Magma has nothing for a well-formed question: its answer carries `gap`, or
+  its error says it does not know;
+- a tool answered, but not with what the task needed: a field it does not return, a
+  filter or an argument it does not take.
+
+It is not a gap when the answer is right but not the one you hoped for, when your own
+input was wrong (an unknown tag, a missing argument), or when the question is about the
+project rather than Magma.
+
+Tell the user when it happens, carry on with the task, and at the end propose one issue
+per missing capability, gathered from the whole task. Follow steps 2, 3, 4 and 6 (look
+for an existing issue, ask before opening it, the labels, create it), with `feature`,
+`prg-stencil` (the server ships inside `magma`) and the project's `prd-*` label, and this
+title and body instead of the ones of step 5. Title: `magma-mcp: <what is missing>`, e.g.
+`magma-mcp: find_component cannot filter by category`. Body:
+
+```markdown
+## Need
+
+What the task needed to know or to do, in one sentence.
+
+## What the server answered
+
+The tool you called and its arguments, and what it returned; or that no tool covers it.
+
+## What I did instead
+
+Read a file by hand, guessed, asked the user, and what it cost.
+
+## Proposal
+
+The tool, argument or field that would have answered it, if you have one in mind.
+
+## Versions
+
+- @maggioli-design-system/magma: <installed version>
+- Client: <e.g. Claude Code, VS Code, Cursor>
+
+Found in <project> (<repository>).
+```

package/package.json

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