@maggioli-design-system/magma-react 2.9.0 → 2.11.0

package/AGENTS.md

@@ -5,7 +5,7 @@
 -->
 # @maggioli-design-system/magma-react - agent install guide
 
-> Version 2.9.0. You (the agent) are installing Magma into THIS project. Do not
+> Version 2.11.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,
@@ -60,10 +60,11 @@ Ask the user only what detection left undecided. Typical questions:
    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.
+   adds the Magma skills (`/magma:setup`, `/magma:review`, `/magma:migrate`,
+   `/magma:pattern-layer`). For the other
+   clients MERGE the entry into `.vscode/mcp.json`, `.cursor/mcp.json` or
+   `opencode.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
 
@@ -81,11 +82,13 @@ 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 by category, one line each |
+| A task that spans components, solved the same way in every product: where a message goes, confirming an action, an empty, a loading or a failed part | [`agents/patterns.md`](agents/patterns.md) - the catalogue of the patterns; ask `get_pattern` of the MCP server for the case of your situation |
+| How the parts of a screen stand together: the space between two elements, which action weighs more, the style of a title, when a surface, how wide | [`agents/patterns.md`](agents/patterns.md), section Foundation - the domains of the design language; ask `get_pattern` for the rule of your context, `get_guide` for a domain by its id (`rhythm`) |
 | 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` |
+| Correct usage and mistakes for one component | `examples.md` / `mistakes.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) |
+| Mistakes to avoid with any component | [`agents/mistakes.md`](agents/mistakes.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) |

package/CHANGELOG.md

@@ -7,6 +7,115 @@ package.
 It is released together with `magma`, at the same version: the sections are the
 releases of `magma`.
 
+## [magma@2.11.0] - 2026-11-04
+
+### Bug Fixes
+
+- *(mds-pref-theme)* Mark the business item when the theme is left on its default
+
+### Build
+
+- *(stencil)* Build magma again when docs/agents changes
+
+### Documentation
+
+- *(storybook)* Watch the contrast promotion under editorial in the semantic lab
+- *(magma)* Build magma before checking a new or changed preview
+
+### Features
+
+- *(mds-pref-theme-item)* Show in the swatch the theme the item names
+- *(lint)* Let render_preview take the base theme by its name
+- *(magma,lint)* Ship an image of each preview, light and dark, beside its stage
+
+## [magma@2.10.0] - 2026-11-04
+
+### Bug Fixes
+
+- *(mds-book)* Bind a book with an image in paper, keep the accent for the drawn cover
+- *(styles,mds-input)* Leave the text of an input untrimmed, so a drag no longer scrolls it
+- *(magma,lint)* Check_setup finds magma-mcp in the configuration of OpenCode
+- *(lint)* Find the tokens a domain carries in the DTCG data too
+- *(mds-status-bar)* Hug the bar again under the dialog width of the window slot
+- *(lint)* No box of nothing reported where the content stands out of it by design
+- *(magma)* The previews of the widths on the roles and the carriers that ship
+- *(lint)* Judge no flat colour where the image cannot show the content
+- *(lint)* Judge no flat colour on a box another element covers
+- *(mds-input-date)* Show the custom calendar button on firefox and hide the native one
+- *(mds-input-date)* Clip only the native calendar button on firefox, not the year
+
+### Build
+
+- *(stencil)* Rate a type alias without its closing semicolon
+- *(magma)* Track the editor setup of the repository in .vscode
+
+### Documentation
+
+- *(mds-book)* Show binding none on a document, the first page of its minutes
+- *(magma)* The carriers of the rhythm ship, so its cases name them
+- *(magma)* Put the page header at the step of the sections
+- *(magma)* Show the new items of a list in the line of the summary
+- *(magma)* Point the gap of the attention dot at its issue
+- *(magma)* Write the spaces of the page header by their role
+- *(magma)* Write the other five domains of the design language as files
+- *(magma,design-tokens,styles)* Point the guides to the domains
+- *(magma)* Show the cases of widths at work, the pilot of the domain previews
+- *(magma)* Write the planned carriers of density as plain text
+- *(magma)* Keep the table of the widths/page preview to two columns
+- *(magma)* Give the toast of a removal the default light variant
+- *(magma)* Let closing the deadline dialog mean staying connected
+- *(magma)* Stack a row of actions under 380 px of its container
+- *(magma)* Put the actions beyond the third in the menu of the item
+- *(magma)* Lay out the previews with Tailwind, the default
+- *(magma)* Show the error of action-failed-in-place in the strong tone
+- *(mds-accordion-item)* Write h6 for the title of an item, until the default moves
+- *(magma)* The rhythm names the row of actions and lets an image reach its edges
+- *(magma)* Link the decisions of the card to their comments on #1189
+- *(magma)* The titles and the widths on the carriers that ship
+- *(magma)* The patterns follow the design language and the choices of review round 2
+- *(magma)* Draw the architecture of every project in its README
+- *(magma)* Colour the diagrams of the projects by axis
+- *(magma)* Move the shipped carriers of titles and widths to carried-by
+
+### Features
+
+- *(lint)* Read the patterns and answer get_pattern
+- *(magma)* Ship the five patterns of Messages and states
+- *(magma)* The plugin skill that writes a product's pattern layer
+- *(magma,lint)* Ship the usage files of a component as examples.md and mistakes.md
+- *(magma)* Fail the build on a usage file the readers of documentation.json do not know
+- *(mds-book)* Binding none, a document as a stack of loose sheets
+- *(magma,lint)* A live preview for every case of a pattern, checked and shipped
+- *(magma)* Render_preview renders Magma markup, checks the image and asks with it
+- *(magma,lint)* Render_preview renders the preview of a case, and every one is checked
+- *(magma)* Domains of Foundation in the pattern format, with serves and carried-by
+- *(magma)* The rhythm, first domain of Foundation
+- *(magma,lint)* The rules of the design language in get_guide, get_pattern, get_component
+- *(design-tokens,styles,mds-text)* The reading measure reaches the text (56ch)
+- *(magma,lint)* Building blocks in the pattern format, the patterns of Data and the page header
+- *(lint)* Give a preview that is a whole page no inset, with whole-page
+- *(lint)* Serve the previews of the patterns live, on the page of render_preview
+- *(lint)* Name the whole file of each stage, a link that opens it in VS Code
+- *(lint)* Show the file of a stage from the root of its repository
+- *(lint)* Compile the Tailwind classes of the markup in the page of a render
+- *(lint)* Build the page of serve.previews with Magma components
+- *(lint)* Write the Tailwind entry point of the editor beside the drafts
+- *(mds-text)* Write a title by its role, page, section, dialog, part or group
+- *(mds-card)* One inset shared by the regions, the image to the edges it touches
+- *(mds-input-field)* Short, a short answer that field-group lays out on half the column
+- *(mds-modal)* The window slot stops at the width of a dialog
+- *(mds-header-bar,mds-header)* The content of the bar on the frame of the page
+- *(stencil,styles)* Rows of actions stack, the status bar keeps its room, fields step down
+- *(mds-header,styles)* The bar stands in the flow, sticky: drop the padding kept for it
+- *(lint,magma)* Previews of the rules of a domain, and more examples of a case
+- *(magma)* The previews of the rhythm, the actions, the titles and the surfaces
+- *(magma)* A preview for every case of the seven decided patterns
+- *(magma,lint)* A preview for each situation of a building block
+- *(magma)* The building blocks app-shell, item-list and labels-and-values
+- *(magma)* The previews of the four blocks, and the previews of the patterns realigned
+- *(mds-notification)* A status variant, and a pulse when the count grows
+- *(magma)* The dot of the new items from mds-notification, pulsing when the count grows
+
 ## [magma@2.9.0] - 2026-10-27
 
 ### Bug Fixes

package/README.md

@@ -2,6 +2,44 @@
 
 Magma React specific building blocks on top of [@maggioli-design-system/magma](https://www.npmjs.com/package/@maggioli-design-system/magma) components.
 
+## Architecture
+
+Every source of this package is written by the stencil build: a client wrapper per component, a
+server wrapper that renders it with the hydrate module of magma, and a barrel of re-exports. The
+package compiles them; at runtime the wrappers load the custom elements of magma.
+
+```mermaid
+flowchart LR
+  WC["stencil<br/>package magma, reactOutputTarget"]
+  subgraph re["stencil-react<br/>package @maggioli-design-system/magma-react"]
+    CLIENT["client wrappers<br/>src/tag.ts, generated"]
+    SERVER["server wrappers<br/>src/tag.server.ts, generated"]
+    BARREL["src/components.ts<br/>re-exports only"]
+  end
+  WC -->|"writes src/ at every build"| CLIENT & SERVER & BARREL
+  BARREL -->|"MdsX, imported by its React fixtures"| CM["codemod"]
+  WC -.->|"dist/components/tag.js"| CLIENT
+  WC -.->|"./hydrate: renderToString, declarative shadow DOM"| SERVER
+  SERVER -.->|"on the client"| CLIENT
+  BARREL -.->|"MdsButton, MdsText, ... from magma-react"| APP(["React app, Next.js"])
+  class WC,CLIENT,SERVER,BARREL components
+  class CM tooling
+  class APP outside
+  class re area
+  classDef ai fill:#efe5ff,stroke:#8250df,color:#3e1f79
+  classDef assets fill:#fff1d6,stroke:#bf8700,color:#5c3d00
+  classDef visual fill:#dcf5ec,stroke:#1a7f64,color:#0b4a3a
+  classDef components fill:#ddf0ff,stroke:#0969da,color:#0a3069
+  classDef tooling fill:#eceff3,stroke:#57606a,color:#24292f
+  classDef outside fill:#ffffff,stroke:#8c959f,color:#24292f
+  classDef area fill:none,stroke:#8c959f
+```
+
+Rectangles: this repository; rounded boxes: outside it. Solid arrows: inside the repository;
+dashed: where the package is installed. Labels: the file, export or command that crosses.
+Colours: purple ai, amber assets, teal visual, blue components, grey tooling, white outside
+([convention](../../docs/ARCHITECTURE.md#diagrams-of-the-projects)).
+
 ## Install with an AI agent
 
 This package ships an agent-readable install guide, versioned with the package. Point

package/agents/assets.md

@@ -76,7 +76,7 @@ What each file provides:
 | `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 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` |
+| `themes.css` | The named themes (`data-theme-name`): retint the semantic roles, and publish the preview of each theme for a picker (`--magma-preview-<name>-*`). Import it after `semantic.css` |
 | `base.css` | Base element styles (sets `--font-info` body font, etc.) |
 
 DO NOT import `colors-hex-*.css` when using components or Tailwind - they cannot be
@@ -318,7 +318,7 @@ IconsSetService.setSvgPath('/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).
+[`mds-icon` examples](../../magma/dist/collection/components/mds-icon/examples.md).
 
 Reference an icon by slug, never inline SVG and never import from an icon-set package:
 

package/agents/color.md

@@ -71,10 +71,10 @@ named theme retints all of it at once.
 | Token (`--magma-*`) | Tailwind | Use |
 | --- | --- | --- |
 | `surface-default` | `bg-surface-default` | the page canvas (the `body` already has it) |
-| `surface-raised` | `bg-surface-raised` | cards, panels, sticky headers |
+| `surface-raised` | `bg-surface-raised` | cards (an item of a set), panels; the bars that stay put draw it themselves (`surfaces/band`) |
 | `surface-overlay` | `bg-surface-overlay` | modal, dropdown, popover, sheet, and anything lifted with a shadow |
 | `surface-sunken` | `bg-surface-sunken` | wells, insets, code blocks, tracks |
-| `surface-muted` | `bg-surface-muted` | same-plane grouping: zebra rows, a subtle section |
+| `surface-muted` | `bg-surface-muted` | same-plane grouping inside a component: zebra rows; never the background of a section (`surfaces/tints-in-components`) |
 | `wash-soft` / `wash-base` / `wash-strong` | `bg-wash-*` | a flat neutral pill or chip (no shadow), by how marked it is |
 | `surface-inverse` / `surface-inverse-muted` | `bg-surface-inverse*` | the chip that flips with the mode (dark on a light UI) |
 | `on-inverse` | `text-on-inverse` | text and icons on either inverse level |
@@ -98,7 +98,9 @@ shadow in light, and how themes and high contrast move them: [`theming.md`](them
 ### Accent: actions and selection
 
 Two accents with the same nine roles: `accent` (the brand action colour) and `accent-ai`
-(AI-driven features). A named theme can repoint them.
+(AI-driven features). A named theme can repoint them. The interface is neutral, so the
+accent stays rare: a view has one primary action in it (`actions/primary`), and which
+weight every other action takes is the domain [`actions`](patterns/actions.md).
 
 | Token | Tailwind | Use |
 | --- | --- | --- |
@@ -167,8 +169,8 @@ Only when the colour encodes data rather than an interface role:
   knockout; not a page or card background.
 
 Never use `--magma-tint-*`: it is the internal pointer a named theme repoints, not a role.
-`tone-porcelain` and `tone-bisque` back the named themes `cool` and `warm`: switch them on
-with `data-theme-name` ([`theming.md`](theming.md)), do not paint them by hand.
+`tone-bisque` backs the named theme `editorial` (and `tone-porcelain` the deprecated `cool`):
+switch it on with `data-theme-name` ([`theming.md`](theming.md)), do not paint it by hand.
 `variant-*` has no role of its own: the accents are `accent` and `accent-ai`.
 
 Deprecated: `--magma-neutral-emphasis` / `--magma-neutral-on-emphasis` are aliases of

package/agents/components.md

@@ -6,10 +6,10 @@
 # Magma components catalogue (117 components)
 
 > Generated from each component's usage description. Each tag links the component's
-> own `AGENTS.md` (its API, with `pattern.md` and `antipattern.md` beside it) in
+> own `AGENTS.md` (its API, with `examples.md` and `mistakes.md` beside it) in
 > `@maggioli-design-system/magma/dist/collection/components/<tag>/`. The rules shared by
 > every component: [`conventions.md`](conventions.md), [`variants.md`](variants.md),
-> [`anti-patterns.md`](anti-patterns.md).
+> [`mistakes.md`](mistakes.md).
 >
 > Grouped by category (the `@category` docs tag of each component in
 > `dist/documentation.json`). A part of a compound component (`@parent`) follows its

package/agents/conventions.md

@@ -9,7 +9,7 @@
 > slots, compound components, icons, accessibility, styling from outside. Apply them
 > once; do not re-derive them per component. The `variant` / `tone` axes have their own
 > file: [`variants.md`](variants.md). Mistakes that apply to every component:
-> [`anti-patterns.md`](anti-patterns.md).
+> [`mistakes.md`](mistakes.md).
 >
 > For one component's API (props with their allowed values, events, methods, slots,
 > parts, CSS custom properties) read its own `AGENTS.md`, listed in

package/agents/mcp.md

@@ -11,9 +11,10 @@
 
 The server answers from the version installed in the project: the components and their
 API, the roles and tokens with what each one is for, the classes of the Magma Tailwind
-theme, the icon slugs that exist, the sections of these guides, and the lint
-([`lint.md`](lint.md)) on a snippet before it is written. It is read-only: no tool changes
-a file.
+theme, the icon slugs that exist, the sections of these guides, the lint
+([`lint.md`](lint.md)) on a snippet before it is written, and an image of markup rendered
+with the installed components. No tool changes the project's code: only `render_preview`
+writes, its images, into `node_modules/.cache/magma/previews/`.
 
 ## Set it up
 
@@ -25,8 +26,9 @@ the file.
 ### Claude Code: the Magma plugin
 
 In Claude Code, the Magma plugin starts the server for you and adds the skills that run a
-whole job: `/magma:setup`, `/magma:review`, `/magma:migrate`, and `ui`, which Claude loads by
-itself for UI work. Register it for the whole team in the project's committed
+whole job: `/magma:setup`, `/magma:review`, `/magma:migrate`, `/magma:pattern-layer` (the
+layer of a pattern for the product, [`patterns.md`](patterns.md)), and `ui`, which Claude loads
+by itself for UI work. Register it for the whole team in the project's committed
 `.claude/settings.json`; Claude Code loads it once the folder is trusted, in the terminal and
 in the desktop app, which reads the same settings:
 
@@ -69,27 +71,52 @@ VS Code (GitHub Copilot), `.vscode/mcp.json`:
 
 Cursor, `.cursor/mcp.json`: the same entry as Claude Code, under `mcpServers`.
 
+OpenCode, `opencode.json` (or `opencode.jsonc`) at the project root: a `local` server, whose
+`command` lists the program and its arguments. OpenCode 2 reads the servers under
+`mcp.servers`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "magma": { "type": "local", "command": ["npx", "--no", "magma-mcp"] }
+    }
+  }
+}
+```
+
+OpenCode 1 reads them right under `mcp` (`"mcp": { "magma": { ... } }`), a form OpenCode 2
+still reads but deprecates.
+
+`render_preview` also needs a browser driver, which Magma does not install:
+`npm i -D playwright-core` (a project with `@playwright/test` has it already). It drives the
+Google Chrome or Microsoft Edge of the machine and downloads no browser; on a machine with
+neither, `npx playwright install chromium`.
+
 `npx --no magma-mcp` runs the installed version, so the answers always match the components
 the project uses. Keep `--no`: without it, a client that starts the server before
 `npm install` (a fresh clone with the configuration committed) lets `npx` download and run
 whatever package the npm registry has under that name; with it, `npx` stops instead. When the
 client starts servers elsewhere than the project's root, pass it:
-`"args": ["--no", "magma-mcp", "--root", "<the project's folder>"]`.
+`"args": ["--no", "magma-mcp", "--root", "<the project's folder>"]` (in OpenCode, at the end
+of `command`).
 
 ## The tools
 
 | Tool | Ask it | Instead of |
 | --- | --- | --- |
 | `find_component` | which component fits a need ("a date range picker") | reading the catalogue |
-| `get_component` | the API of one component: props with their values and default, events, methods, slots, parts, public CSS custom properties | reading its `AGENTS.md` |
+| `get_component` | the API of one component: props with their values and default, events, methods, slots, parts, public CSS custom properties; and in `rules` the rules of the design language that govern it (the inset `mds-banner` draws, from the rhythm) | 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, 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 |
+| `get_guide` | one section of a guide, or of a domain of Foundation, the rules of composition of the design language (`rhythm`, `density`, `actions`, `titles`, `surfaces`, `widths`) | reading the whole file |
+| `get_pattern` | how a task across components is solved in every product (where a message goes, confirming an action, an empty, a loading or a failed part): the list, the patterns for a need, or, with the values of the variables of a pattern, the one case to follow, with its preview (the stage, live, what to try in it and in `images` the paths of its light and dark images, to show where the stage cannot run) when Magma has one and in `rules` the rules of the domains it relies on; the layer of the project (`magma/patterns/<id>.md`) applied; the domains of Foundation first in the list, then the building blocks (`kind: block`, the page header), which answer with the regions to lay out, in order | inventing the flow, or reading [`patterns.md`](patterns.md) and each pattern by hand |
 | `check_markup` | whether a snippet passes the lint, before it is written | a lint run after the fact |
 | `check_setup` | what the Magma integration of the project misses | checking the install steps by hand |
+| `render_preview` | an image of markup with Magma components, or of the preview Magma ships for a case of a pattern (`pattern` and `case`), at the widths (pixels or Magma breakpoints), the mode and the theme you give, with a report of what in it is not representative | describing an interface in words, or a wireframe of your own |
 
 `check_markup` uses the ESLint, Stylelint and template parsers the project installed with
 the lint ([`lint.md`](lint.md)). The same definitions, for a tool that documents them, are in
@@ -99,9 +126,52 @@ the lint ([`lint.md`](lint.md)). The same definitions, for a tool that documents
 
 - Before writing a component: `find_component`, then `get_component` and `get_usage`.
 - Before a colour, a spacing or a class: `list_tokens`, `suggest_role`, `explain_class`.
+- Before a flow that tells the person something or makes them wait or decide: `get_pattern`.
+- Before the head of a page (its title, the way back, its actions): the building block
+  `page-header`, `get_pattern` with its id and the values of its variables.
+- Before laying out a page, a form, a dialog or a card: the domains of Foundation, which
+  `get_pattern` lists first (`kind: foundation`), each read with `get_guide` by its id
+  (`rhythm`, `actions`, `titles`, `surfaces`, `widths`, `density`); follow the `rules` that `get_pattern` gives with a case and `get_component`
+  with a component.
 - 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`.
+- Before asking the person to decide on an interface: `render_preview`, one render per
+  option ([Show the person what you mean](#show-the-person-what-you-mean)).
 - 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").
+
+## Show the person what you mean
+
+A decision on an interface taken from words is taken blind: the person reads the concept and
+imagines a screen of their own. Show the real components instead, rendered on the version the
+project installed.
+
+1. **Render each option.** `render_preview` with the markup of the option, as the product
+   would write it: the real components, the real texts, the layout around them, with the
+   Magma Tailwind utilities (the render compiles them with the project's Tailwind 4). A modal, a
+   drawer or a toast sits on the viewport: give a `height`. One width is enough unless the
+   option changes with it (`["mobile", "desktop"]`).
+2. **Read the report before the image.** `representative: false` names what is wrong,
+   element by element: a component unknown or not hydrated, an element with no size, a
+   component that is one flat colour, a console error, an icon, a font or an image that did
+   not load, a word broken across lines, content cut. Fix your markup and render again; show
+   an image with a problem only with the problem said next to it.
+3. **Show the images.** The tool returns each image as image content and as a file. VS Code
+   and Cursor show the image to the person; Claude Code passes it to you and may not show it,
+   so there attach the file (`file`) the way your client sends a file to the person, or give
+   its path. Never copy the image data by hand.
+4. **Ask.** Each option with its image, a name and one line on what it means, the one you
+   recommend first and marked as such. Ask with your client's question tool when it has one.
+   Always offer:
+   - a way to flag an image ("the second one did not render", "this is not what I meant");
+   - an empty field for an answer of the person's own.
+5. **Render the free answer before acting on it.** What the person writes in the empty field
+   is an instruction you interpret: render what you understood, show it and ask whether that
+   is it. Act only once they confirm; otherwise render again with their correction.
+6. **A flagged image.** Render it again and compare the report. When the markup was yours
+   to fix, fix it. When the markup is right and the image still does not show it (the
+   report says representative, the person sees something else), the render is at fault: tell
+   the person and propose an issue on Magma ([`reporting.md`](reporting.md), "A tool or an
+   answer the MCP server is missing").

package/agents/{anti-patterns.md → mistakes.md}

@@ -3,10 +3,10 @@
   Source of truth: docs/agents/ in the magma monorepo.
   Regenerate with: npm run sync.agent-docs (from the stencil package).
 -->
-# Magma components - system-level anti-patterns
+# Magma components - mistakes to avoid with any component
 
 > Scope: mistakes that apply to **every** component. Each component's own
-> `antipattern.md` (next to its `AGENTS.md`) covers the component-specific ones; the
+> `mistakes.md` (next to its `AGENTS.md`) covers the component-specific ones; the
 > ones below are universal. The rules they break: [`conventions.md`](conventions.md),
 > [`variants.md`](variants.md), [`color.md`](color.md), [`theming.md`](theming.md).