Ogni pacchetto di Magma contiene guide scritte per gli agenti AI di sviluppo, come Claude Code, Codex, Cursor o Copilot: come installare Magma, quale componente usare per cosa, l’API di ogni componente, i modi giusti e sbagliati di usarlo. Sono file Markdown dentro il pacchetto, con la sua stessa versione. Un agente che li legge lavora con i componenti della versione che hai installato, invece che con quello che ricorda di Magma, che può essere un’altra versione o niente del tutto.

Iniziare un progetto

Crea l’app con lo strumento del tuo framework, poi installa il pacchetto di Magma: da quel momento le sue guide sono in node_modules, dove l’agente può leggerle.

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

Poi chiedi all’agente di installare il resto:

Prompt

Leggi node_modules/@maggioli-design-system/magma/AGENTS.md e seguilo per installare Magma in questo progetto.

Prompt

Leggi node_modules/@maggioli-design-system/magma-react/AGENTS.md e seguilo per installare Magma in questo progetto.

Prompt

Leggi node_modules/@maggioli-design-system/magma-angular/AGENTS.md e seguilo per installare Magma in questo progetto.

La guida dice all’agente di guardare prima il progetto (framework, bundler, Tailwind, rendering lato server), di chiederti solo quello che non riesce a capire da solo, come da dove sono servite le icone o se vuoi la modalità scura, e poi di installare gli stili, i font e le icone e di registrare i componenti. Finisce con una build, un componente nella pagina e un’icona caricata. Controlla il risultato con Installazione: gli stessi passaggi, scritti per le persone.

Dare il contesto all’agente

Un agente inizia ogni sessione da zero. Scrivi nel file di istruzioni del progetto dove si trova il contesto di Magma, e lo leggerà ogni volta: AGENTS.md alla radice del progetto è letto da molti agenti. Claude Code legge CLAUDE.md: scrivici @AGENTS.md e leggerà lo stesso file.

AGENTS.md

## Interfaccia utente: Magma

L'interfaccia è costruita con Magma, il design system di Maggioli (`@maggioli-design-system/magma`). Prima di scrivere codice di interfaccia, leggi `node_modules/@maggioli-design-system/magma/AGENTS.md`, sezione "Using the components", e solo i file a cui rimanda che ti servono:

- scegli i componenti da `agents/components.md`, il catalogo;
- per ogni componente che usi, leggi il suo `AGENTS.md`, `pattern.md` e `antipattern.md`;
- colori, testo e spaziature vengono dai token e dalle utility di Magma (`agents/color.md`, `agents/typography.md`), mai da valori scritti a mano.

Non indovinare mai una proprietà, un valore o un evento: le guide descrivono la versione installata.

AGENTS.md

## Interfaccia utente: Magma

L'interfaccia è costruita con Magma, il design system di Maggioli (`@maggioli-design-system/magma-react`). Prima di scrivere codice di interfaccia, leggi `node_modules/@maggioli-design-system/magma-react/AGENTS.md`, sezione "Using the components", e solo i file a cui rimanda che ti servono:

- scegli i componenti da `agents/components.md`, il catalogo;
- per ogni componente che usi, leggi il suo `AGENTS.md`, `pattern.md` e `antipattern.md`;
- colori, testo e spaziature vengono dai token e dalle utility di Magma (`agents/color.md`, `agents/typography.md`), mai da valori scritti a mano.

Non indovinare mai una proprietà, un valore o un evento: le guide descrivono la versione installata.

AGENTS.md

## Interfaccia utente: Magma

L'interfaccia è costruita con Magma, il design system di Maggioli (`@maggioli-design-system/magma-angular`). Prima di scrivere codice di interfaccia, leggi `node_modules/@maggioli-design-system/magma-angular/AGENTS.md`, sezione "Using the components", e solo i file a cui rimanda che ti servono:

- scegli i componenti da `agents/components.md`, il catalogo;
- per ogni componente che usi, leggi il suo `AGENTS.md`, `pattern.md` e `antipattern.md`;
- colori, testo e spaziature vengono dai token e dalle utility di Magma (`agents/color.md`, `agents/typography.md`), mai da valori scritti a mano.

Non indovinare mai una proprietà, un valore o un evento: le guide descrivono la versione installata.

Le guide sono divise in modo che l’agente legga solo quello che serve al compito: AGENTS.mdCome installare Magma, poi la mappa degli altri fileagents/components.mdIl catalogo: ogni componente in una riga, con il link alla sua guida<tag>/AGENTS.mdL’API di un componente: proprietà e loro valori, eventi, metodi, slot, part, proprietà CSS<tag>/pattern.md, <tag>/antipattern.mdCome usare il componente, con esempi, e gli errori da evitareagents/conventions.mdLe regole comuni a tutti i componenti: nomi, eventi, slot, icone, accessibilità, stili dall’esternoagents/variants.md, agents/anti-patterns.mdI valori di variant e tone, e gli errori da evitare con qualsiasi componenteagents/color.md, agents/typography.mdColorare e comporre il testo della tua interfaccia con i token e le utility di Magmaagents/theming.mdModalità scura e le altre preferenze, temi con nome, superfici ed elevazione, angoli Le guide di ogni componente sono in @maggioli-design-system/magma/dist/collection/components/<tag>/, anche quando il progetto usa un wrapper: il catalogo rimanda lì. dist/documentation.json di magma ha gli stessi dati per gli strumenti, troppo grande per darlo intero a un agente.

Lavorare con l’agente

Chiedi il risultato e lascia che sia l’agente a trovare i componenti: con le istruzioni qui sopra, legge il catalogo e le guide dei componenti che sceglie prima di scrivere codice.

Prompt

Aggiungi una pagina con l'elenco dei documenti dell'utente: una tabella con nome, data e dimensione, un campo di ricerca sopra e un pulsante per caricare un documento.

Per controllare cosa ha costruito, chiedigli quali guide ha letto e confronta il codice con agents/anti-patterns.md e con l’antipattern.md di ogni componente. Elencano gli errori da evitare, come un <button> o un <input> semplice al posto di un componente Magma, colori scritti a mano invece dei ruoli di Magma, o disabled="false" per spegnere un attributo booleano.

Dopo un aggiornamento

Le guide cambiano con il pacchetto: dopo un aggiornamento l’agente legge quelle della nuova versione, senza cambiare le tue istruzioni. Dopo una major, esegui prima il codemod, come dice Versioni e migrazioni, poi chiedi all’agente di rivedere quello che il codemod ha segnalato: legge le guide della nuova versione per sistemarlo.