Every Magma package ships guides written for AI coding agents, such as Claude Code, Codex, Cursor or Copilot: how to install Magma, which component to use for what, the API of each component, the right and the wrong ways to use it. They are Markdown files inside the package, versioned with it. An agent that reads them works with the components of the version you installed, instead of what it remembers of Magma, which may be another version or nothing at all.

Start a project

Create the app with the tool of your framework, then install the Magma package: from then on its guides are in node_modules, where the agent can read them.

npm create vite@latest my-app -- --template vanilla
cd my-app
npm i @maggioli-design-system/magma

npm create vite@latest my-app -- --template react
cd my-app
npm i @maggioli-design-system/magma-react @maggioli-design-system/magma

npx @angular/cli new my-app
cd my-app
npm i @maggioli-design-system/magma-angular @maggioli-design-system/magma

Then ask the agent to install the rest:

Prompt

Read node_modules/@maggioli-design-system/magma/AGENTS.md and follow it to install Magma into this project.

Prompt

Read node_modules/@maggioli-design-system/magma-react/AGENTS.md and follow it to install Magma into this project.

Prompt

Read node_modules/@maggioli-design-system/magma-angular/AGENTS.md and follow it to install Magma into this project.

The guide tells the agent to look at the project first (framework, bundler, Tailwind, server rendering), to ask you only what it cannot find out, such as where the icons are served from or whether you want dark mode, and then to install the styles, the fonts and the icons and to register the components. It ends with a build, a component on the page and an icon loaded. Check the result against Installation: the same steps, written for people.

Give the agent the context

An agent starts every session from scratch. Write in the instructions file of the project where the context of Magma is, and it reads it every time: AGENTS.md at the root of the project is read by many agents. Claude Code reads CLAUDE.md: write @AGENTS.md in it, and it reads the same file.

AGENTS.md

## User interface: Magma

The UI is built with Magma, the Maggioli design system (`@maggioli-design-system/magma`). Before writing UI code, read `node_modules/@maggioli-design-system/magma/AGENTS.md`, section "Using the components", and only the files it points to that you need:

- choose components from `agents/components.md`, the catalogue;
- for each component you use, read its `AGENTS.md`, `pattern.md` and `antipattern.md`;
- color, type and spacing come from Magma's tokens and utilities (`agents/color.md`, `agents/typography.md`), never from literal values.

Never guess a prop, a value or an event: the guides describe the installed version.

AGENTS.md

## User interface: Magma

The UI is built with Magma, the Maggioli design system (`@maggioli-design-system/magma-react`). Before writing UI code, read `node_modules/@maggioli-design-system/magma-react/AGENTS.md`, section "Using the components", and only the files it points to that you need:

- choose components from `agents/components.md`, the catalogue;
- for each component you use, read its `AGENTS.md`, `pattern.md` and `antipattern.md`;
- color, type and spacing come from Magma's tokens and utilities (`agents/color.md`, `agents/typography.md`), never from literal values.

Never guess a prop, a value or an event: the guides describe the installed version.

AGENTS.md

## User interface: Magma

The UI is built with Magma, the Maggioli design system (`@maggioli-design-system/magma-angular`). Before writing UI code, read `node_modules/@maggioli-design-system/magma-angular/AGENTS.md`, section "Using the components", and only the files it points to that you need:

- choose components from `agents/components.md`, the catalogue;
- for each component you use, read its `AGENTS.md`, `pattern.md` and `antipattern.md`;
- color, type and spacing come from Magma's tokens and utilities (`agents/color.md`, `agents/typography.md`), never from literal values.

Never guess a prop, a value or an event: the guides describe the installed version.

The guides are split so that the agent reads only what the task needs: AGENTS.mdHow to install Magma, then the map of the other filesagents/components.mdThe catalogue: every component in one line, with a link to its own guide<tag>/AGENTS.mdThe API of one component: props and their values, events, methods, slots, parts, CSS properties<tag>/pattern.md, <tag>/antipattern.mdHow to use the component, with examples, and the mistakes to avoidagents/conventions.mdThe rules shared by every component: naming, events, slots, icons, accessibility, stylingagents/variants.md, agents/anti-patterns.mdThe values of variant and tone, and the mistakes to avoid with any componentagents/color.md, agents/typography.mdColoring and setting text in your own interface with Magma’s tokens and utilitiesagents/theming.mdDark mode and the other preferences, named themes, surfaces and elevation, corners The guides of each component are in @maggioli-design-system/magma/dist/collection/components/<tag>/, also when the project uses a wrapper: the catalogue links them. dist/documentation.json of magma has the same data for tools, too large to give to an agent whole.

Work with the agent

Ask for the result, and let the agent find the components: with the instructions above, it reads the catalogue and the guides of the components it picks before writing code.

Prompt

Add a page with the list of the user's documents: a table with name, date and size, a search field above it, and a button to upload a document.

To check what it built, ask which guides it read, and compare the code with agents/anti-patterns.md and the antipattern.md of each component. They list the mistakes to avoid, such as a plain <button> or <input> in place of a Magma component, colors written by hand instead of Magma’s roles, or disabled="false" to turn off a boolean attribute.

After an update

The guides change with the package: after an update the agent reads those of the new version, with no change to your instructions. After a major release, run the codemod first, as Versions and migrations says, then ask the agent to review what the codemod reported: it reads the guides of the new version to fix it.