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

package/AGENTS.md

@@ -5,7 +5,7 @@
 -->
 # @maggioli-design-system/magma-react - agent install guide
 
-> Version 2.5.1. 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,
@@ -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,75 @@ 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
+
+- *(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

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
@@ -389,7 +402,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.
@@ -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/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