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

package/AGENTS.md

@@ -5,7 +5,7 @@
 -->
 # @maggioli-design-system/magma-react - agent install guide
 
-> Version 2.2.0. You (the agent) are installing Magma into THIS project. Do not
+> Version 2.4.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
 
@@ -65,8 +78,10 @@ Once installed, do not guess component APIs or rules - read only the file you ne
 | 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.