@maggioli-design-system/magma-react 2.8.0 → 2.10.0

package/agents/patterns/page-header.md

@@ -0,0 +1,201 @@
+---
+# A Magma building block: the format and the commands are in docs/PATTERNS.md, "A building block".
+id: page-header
+kind: block
+title: Page header
+group: navigation
+layer: magma
+status: decided
+need: >-
+  The person sees at once what the page holds or is about, where they are, and what they can do
+  with it.
+principle: The head of the page names what it shows, says where it sits, and puts its actions in one place.
+keywords: [page header, page title, heading, title bar, back link, page actions, header of the page]
+not-for: []
+used-by: [list-with-filters, record-detail]
+high-stakes: false
+components: [mds-button, mds-text, mds-badge, mds-dropdown, mds-separator]
+related: [list-with-filters, record-detail]
+validated-on: []
+
+variables:
+  level: { values: [top, nested], means: "top: a page reached from the navigation of the application (a list, a settings page); nested: a page under another one (a record under its list, a sub-list under a record)" }
+  subject: { values: [set, item], means: "set: the page shows a set of items (a list); item: the page is about one item (a record, a profile)" }
+
+regions:
+  - { id: back, when: { level: nested }, what: "a link to the page above, named after it, with an arrow", use: ["mds-button href icon variant=dark tone=text size=sm"] }
+  - { id: number, when: { subject: item }, what: "the number or code of the item, small, above the title, when it has one", use: ["mds-text typography=caption tag=p"] }
+  - { id: title, required: true, what: "the heading of the page: what the set holds, in the plural, or the subject of the item", use: ["mds-text typography=page tag=h1"] }
+  - { id: status, when: { subject: item }, what: "the status of the item, next to the title, when it has one", use: ["mds-badge"] }
+  - { id: summary, what: "one line: what the set holds, or where the item belongs and when it arrived", use: ["mds-text typography=detail tag=p"] }
+  - { id: actions, what: "the actions on what the page shows, the main one last in the strong tone, the others outlined; an action that destroys the item is never in the row: it goes last in the menu of the item, after a separator; with more than three actions the row keeps the main one, the secondary used most and the menu of the item at its start, which holds the others (actions/more-in-menu)", use: ["mds-button variant=dark tone=outline", "mds-button tone=strong", "mds-button variant=dark tone=text icon", "mds-dropdown", "mds-separator"] }
+
+always-true:
+  - id: one-h1
+    rule: The title is the h1 of the page, and the only one.
+    checked-by: review
+  - id: title-names-the-page
+    rule: "The title names what the page holds or is about: the plural of the set, the subject of the item; never the kind of screen (\"Detail\", \"List\")."
+    checked-by: review
+  - id: back-names-the-parent
+    rule: The way back is a link that names the page it returns to ("Requests"), never "Back".
+    checked-by: review
+  - id: not-the-app-bar
+    rule: The page header is the head of the main content, under the bar of the application; the navigation of the application is never in it.
+    checked-by: review
+  - id: main-action-last
+    from: record-detail
+  - id: at-most-three
+    from: actions
+  - id: more-in-menu
+    from: actions
+  - id: title-content
+    from: rhythm
+  - id: inline
+    from: rhythm
+  - id: between-sections
+    from: rhythm
+
+open-choices: []
+
+situations:
+  - { id: requests-of-an-office, situation: The list of the requests of an office, level: top, subject: set }
+  - { id: request-from-the-list, situation: A request opened from the list, level: nested, subject: item }
+  - { id: members-of-a-group, situation: "The members of a group, on a page of their own", level: nested, subject: set }
+  - { id: own-profile, situation: The profile of the person signed in, level: top, subject: item, note: "no status: a profile has none to show" }
+  - { id: contact-being-edited, situation: A contact being edited, level: nested, subject: item, note: "the way back to the item and the title only, which says the action (\"Edit Mario Rossi\"); no actions: the row of the form docks in mds-status-bar (surfaces/edit-actions)" }
+---
+
+# Page header
+
+**The head of the page names what it shows, says where it sits, and puts its actions in one place.**
+
+## When to use it
+
+At the top of the main content of every page of an application, under the bar of the
+application (`mds-header`): the list of the requests, the page of a request, the members of a
+group, a profile. It came out of the patterns of the group Data, where it comes back in the same
+arrangement (`list-with-filters`: the title with New and Export; `record-detail`: back to the
+list, the identity of the record, its actions). Not the bar of the application, with the logo
+and the navigation (`mds-header`, `mds-header-bar`), and not the views of the page: tabs are a
+section of their own, under the header.
+
+## What decides it
+
+Two questions: whether the page sits under another one (then it has a way back), and whether it
+shows a set or is about one item (then it may have a number and a status).
+
+## Regions
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `level` | `top`, `nested` | top: a page reached from the navigation of the application (a list, a settings page); nested: a page under another one (a record under its list, a sub-list under a record) |
+| `subject` | `set`, `item` | set: the page shows a set of items (a list); item: the page is about one item (a record, a profile) |
+
+A region shows where its When holds, in this order: a required one always, the others when there is something to put in them.
+
+| Region | When | Required | What | Use |
+| --- | --- | --- | --- | --- |
+| `back` | level: nested |  | a link to the page above, named after it, with an arrow | `mds-button href icon variant=dark tone=text size=sm` |
+| `number` | subject: item |  | the number or code of the item, small, above the title, when it has one | `mds-text typography=caption tag=p` |
+| `title` | any | yes | the heading of the page: what the set holds, in the plural, or the subject of the item | `mds-text typography=page tag=h1` |
+| `status` | subject: item |  | the status of the item, next to the title, when it has one | `mds-badge` |
+| `summary` | any |  | one line: what the set holds, or where the item belongs and when it arrived | `mds-text typography=detail tag=p` |
+| `actions` | any |  | the actions on what the page shows, the main one last in the strong tone, the others outlined; an action that destroys the item is never in the row: it goes last in the menu of the item, after a separator; with more than three actions the row keeps the main one, the secondary used most and the menu of the item at its start, which holds the others (actions/more-in-menu) | `mds-button variant=dark tone=outline`, `mds-button tone=strong`, `mds-button variant=dark tone=text icon`, `mds-dropdown`, `mds-separator` |
+
+## Layout
+
+- The way back first, on its own line, aligned to the start.
+- Then the identity (number, title with its status, summary) at the start, and the actions at
+  the end, aligned to the top, on a wide screen; with less room the actions go under the
+  identity, on one line at the start, and under 380 px of the header they stack at the full
+  width, the main one at the bottom (`actions/stacked`, on the header as `@container`).
+- The status sits next to the title and wraps under it when there is no room. The identity
+  keeps at least the width of a row of actions (`basis-actions`, with `min-w-0`): a long title
+  wraps and never moves the actions; with less room than both, the actions go under.
+- The spaces are relations of the rhythm, written by their role: `gap-title-content` (300)
+  inside the identity, between a title and what it names (`rhythm/title-content`);
+  `gap-inline` (300) between the actions, and between the identity and the actions, side by
+  side in one row (`rhythm/inline`).
+- The header is the first section of the page: the page puts `gap-between-sections` (1600)
+  between it and the content under it, as between two sections (`rhythm/between-sections`),
+  with the gap of the container that lays out its sections; the block has no margin of its own.
+- A region with nothing to show is left out, with its space: a page with no actions has no empty
+  bar.
+- The tabs of a page, when it has views, are the first section under the header.
+
+## Always true
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+These hold in every product: a product layer cannot change them.
+
+| Id | Rule | Checked by |
+| --- | --- | --- |
+| `one-h1` | The title is the h1 of the page, and the only one. | review |
+| `title-names-the-page` | The title names what the page holds or is about: the plural of the set, the subject of the item; never the kind of screen ("Detail", "List"). | review |
+| `back-names-the-parent` | The way back is a link that names the page it returns to ("Requests"), never "Back". | review |
+| `not-the-app-bar` | The page header is the head of the main content, under the bar of the application; the navigation of the application is never in it. | review |
+| `main-action-last` | The main action comes last, in the strong tone; the others are outlined, `variant="dark" tone="outline"`; an action that destroys the record is never among them, it goes last in the menu of the record. (from `record-detail`) | review |
+| `at-most-three` | A row has at most three actions, and the labels of a row of three fit in 380 px with their gaps: the threshold of `stacked` is computed on them. Beyond three, the menu of the item takes one of the places (`more-in-menu`). (from `actions`) | review |
+| `more-in-menu` | When an item has more than three actions, its row keeps the main action, the secondary used most and the menu of the item, at the start of the row: an icon-only mds-button (more_vert, variant="dark" tone="text", an aria-label that names the item) with mds-dropdown. The menu holds the other actions, and Elimina last after an mds-separator (`destructive-in-menu`): one menu per item. (from `actions`) | review |
+| `title-content` | `gap-title-content` (300) between a title and the content it names (from `rhythm`) |  |
+| `inline` | `gap-inline` (300) between elements side by side in one row: the actions of a row, a field and the button beside it (from `rhythm`) |  |
+| `between-sections` | `gap-between-sections` (1600) between two sections of a page, each with its title (from `rhythm`) |  |
+
+## Situations
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+Situations every application has, each with the regions it shows: they give the examples, the texts and the keywords. The situations of a product's own domain go in its layer.
+
+| Id | Situation | Regions |
+| --- | --- | --- |
+| `requests-of-an-office` | The list of the requests of an office | `title`, `summary`, `actions` |
+| `request-from-the-list` | A request opened from the list | `back`, `number`, `title`, `status`, `summary`, `actions` |
+| `members-of-a-group` | The members of a group, on a page of their own | `back`, `title`, `summary`, `actions` |
+| `own-profile` | The profile of the person signed in | `number`, `title`, `status`, `summary`, `actions`: no status: a profile has none to show |
+| `contact-being-edited` | A contact being edited | `back`, `number`, `title`, `status`, `summary`, `actions`: the way back to the item and the title only, which says the action ("Edit Mario Rossi"); no actions: the row of the form docks in mds-status-bar (surfaces/edit-actions) |
+
+## Accessibility
+
+- The title is the `h1`; a pattern that moves the focus to it after an action gives it
+  `tabindex="-1"` (`focus-to-heading` of `record-detail`).
+- A `header` element inside `main` is not a landmark: the bar of the application keeps the
+  banner.
+- The way back is a link with the address of the page above, so it also works in a new tab.
+- The number and the summary are text, not headings.
+
+## Content
+
+- The title is the plural of the set ("Requests") or the subject of the item ("Change of
+  residence"); the number goes above it, smaller.
+- The way back is the name of the page above ("Requests"), with the arrow.
+- The summary is one line: what the set holds ("The requests citizens send to the offices"), or
+  where the item belongs and when it arrived ("Registry office, received on 3 March 2026").
+- Actions are verbs on what the page shows: "New request", "Export", "Close request".
+
+## Magma gaps
+
+- `mds-breadcrumb-item` has no `href`: Magma has no trail of links. The default needs none (one
+  link to the page above); a product that needs a trail asks for it with an issue.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-24 | A block is a section of a page that comes back in the same arrangement, structure and layout only; it is born when it comes back in two or three patterns; the page header is a candidate | The docs site, `plan/DIRECTION.md`, Building blocks section. |
+| 2026-10-29 | The page header is the first block: it comes back in `list-with-filters` and `record-detail` | The threshold of two patterns, reached in the group Data. |
+| 2026-10-29 | A block has the base of a pattern, with `regions` in order instead of `cases`: each region says when it shows | Its regions are independent: as cases, the page header would be eight near copies; space is what shows where. |
+| 2026-10-29 | A block ships as markup to apply, with its code in HTML, React and Angular, like a pattern | No new API to version; a component is weighed when the block is stable in the layers of two or three products. |
+| 2026-10-29 | The tabs of a page are a section of their own, under the header | The header stays short; the views belong to the content they switch. |
+| 2026-10-29 | The way back is one link to the page above, named after it; no trail | Management applications have two or three levels, and the navigation of the application says where the person is; `mds-breadcrumb-item` has no links. |
+| 2026-10-31 | The group is `navigation` | The docs site, `plan/DIRECTION.md`, Patterns section: Navigation names the page header among the building blocks. |
+| 2026-10-31 | The actions other than the main one are `variant="dark" tone="outline"`, no longer weak; an action that destroys the item goes in its menu, never in the row | The design language, #1189: `actions/secondary` and `actions/destructive-in-menu`. |
+| 2026-10-31 | The spaces of the Layout are relations of the rhythm, `title-content` and `inline` (`gap-300`), no longer 200 and 400 | The design language, #1189: the rhythm, on main since #1206; the old values came from the previews. |
+| 2026-10-31 | The header is the first section of the page: `gap-1600` between it and the content under it (`rhythm/between-sections`), put by the page, not by the block | The header names the whole page: at the step of the sections it belongs to none of them (`step-ratio`), and the rhythm needs no new relation. Rejected: `gap-1000`, which on a page of several sections puts the header nearer to the first one than that one to the next, so it reads as the head of the first section. Chosen live on a record with sections and on a list (#1210). |
+| 2026-11-01 | With more than three actions, the row keeps the main one, the secondary used most and the menu of the item at its start; the open choice `actions-overflow` goes | The design language, #1189: `actions/at-most-three` and `actions/more-in-menu`. The arrow of the main action (`mds-button-dropdown`) read as another way of doing it; every action visible broke the limit of three. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6561221595 |
+| 2026-11-03 | A block has a preview for each situation, named after the id of the situation | The maintainer's choice for the round of the building blocks: a situation already gives every variable and the words, as a case does; one preview of the whole block would not show what goes when a variable changes. |
+| 2026-11-03 | With less room the actions go under the identity on one line and stack under 380 px of the header; the identity keeps the width of a row of actions, so a long title wraps instead of moving them; the title takes the role `page` | The previews of the round of the building blocks: the old "wrap" made a ragged row that `actions/stacked` forbids, and a long title pushed the actions under it at 1024 px; `typography=h3` was the size, `page` is the role (`titles/by-role`). |

package/agents/patterns/permissions.md

@@ -0,0 +1,17 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: permissions
+kind: pattern
+title: Permissions
+group: data
+layer: magma
+status: candidate
+need: >-
+  The person sees what their role lets them see and do, and understands why an action is not
+  available.
+---
+
+# Permissions
+
+A candidate: a need Magma knows and has not defined yet, cited by `empty-state`. Until it is
+defined, the agent says that no default covers it, and proposes the pattern (`get_guide reporting`).

package/agents/patterns/previews/actions/banner.html

@@ -0,0 +1,21 @@
+<!--
+try: Look at the actions of the ai banner, in its variant: Usa la descrizione filled and last, Ignora outlined. Press Usa la descrizione: the text goes into the field.
+-->
+<div class="grid max-w-form gap-between-fields">
+  <mds-banner id="suggestion" variant="ai" icon="mi/baseline/auto-awesome" headline="Suggerimento IA">
+    <mds-text>L'assistente ha scritto una descrizione della pratica dai tre documenti allegati.</mds-text>
+    <mds-button id="ignore" slot="action" variant="ai" tone="outline">Ignora</mds-button>
+    <mds-button id="use" slot="action" variant="ai" tone="strong">Usa la descrizione</mds-button>
+  </mds-banner>
+  <mds-input-field label="Descrizione">
+    <mds-input id="description"></mds-input>
+  </mds-input-field>
+</div>
+<script>
+  const suggestion = document.getElementById('suggestion');
+  document.getElementById('use').addEventListener('click', () => {
+    document.getElementById('description').value = 'Accesso ai verbali del sopralluogo del 12 marzo.';
+    suggestion.remove();
+  });
+  document.getElementById('ignore').addEventListener('click', () => suggestion.remove());
+</script>

package/agents/patterns/previews/actions/confirm.html

@@ -0,0 +1,11 @@
+<!--
+try: Look at the row of the confirmation: Elimina last, filled in red; Annulla before it, outlined, holds the focus, so Invio cancels.
+height: 320
+-->
+<mds-modal opened aria-label="Eliminare la nota Sopralluogo del 12 marzo?">
+  <mds-banner slot="window" variant="light" tone="box" dismissible headline="Eliminare la nota Sopralluogo del 12 marzo?">
+    <mds-text>La nota viene cancellata e non si può recuperare.</mds-text>
+    <mds-button slot="action" variant="dark" tone="outline" autofocus>Annulla</mds-button>
+    <mds-button slot="action" variant="error" tone="strong">Elimina</mds-button>
+  </mds-banner>
+</mds-modal>

package/agents/patterns/previews/actions/danger-zone.html

@@ -0,0 +1,22 @@
+<!--
+try: Look at the last section of the request: a border of its own, the consequence written next to Elimina la pratica, outlined in red.
+-->
+<div class="grid gap-between-sections">
+  <section class="grid gap-title-content">
+    <mds-text typography="section" tag="h2">Referenti</mds-text>
+    <mds-text tag="p">Anna Rossi, ufficio tecnico; Marco Bianchi, protocollo.</mds-text>
+  </section>
+  <section class="grid gap-title-content">
+    <mds-text typography="section" tag="h2">Zona pericolosa</mds-text>
+    <div class="flex flex-wrap items-center justify-end gap-content-actions rounded-(--magma-radius-2xl) border border-danger-border p-inset">
+      <div class="grid grow basis-(--magma-width-reading) gap-title-content">
+        <mds-text typography="part" tag="h3">Elimina la pratica</mds-text>
+        <mds-text tag="p">
+          Con la pratica se ne vanno 4 allegati, 2 referenti e il protocollo collegato. Non si
+          possono recuperare.
+        </mds-text>
+      </div>
+      <mds-button variant="error" tone="outline">Elimina la pratica</mds-button>
+    </div>
+  </section>
+</div>

package/agents/patterns/previews/actions/destructive-in-menu.html

@@ -0,0 +1,19 @@
+<!--
+try: Look at the open menu of the note: Modifica and Duplica, then a separator, and Elimina nota last, in red with its icon. Press the button of the menu to close and open it.
+height: 340
+-->
+<mds-card class="max-w-form">
+  <mds-card-header>
+    <mds-text typography="part" tag="h2">Sopralluogo del 12 marzo</mds-text>
+    <mds-button id="azioni-nota" slot="action" icon="mi/baseline/more-vert" variant="dark" tone="text" aria-label="Azioni della nota"></mds-button>
+  </mds-card-header>
+  <mds-card-content>
+    <mds-text>Sentire l'ufficio tecnico prima di venerdì.</mds-text>
+  </mds-card-content>
+</mds-card>
+<mds-dropdown target="#azioni-nota" placement="bottom-end" visible>
+  <mds-button icon="mi/baseline/edit" variant="dark" tone="text" label="Modifica"></mds-button>
+  <mds-button icon="mi/baseline/content-copy" variant="dark" tone="text" label="Duplica"></mds-button>
+  <mds-separator></mds-separator>
+  <mds-button icon="mi/baseline/delete" variant="error" tone="text" label="Elimina nota"></mds-button>
+</mds-dropdown>

package/agents/patterns/previews/actions/dismiss-message.html

@@ -0,0 +1,15 @@
+<!--
+try: Press the X of the banner: the message goes, and the section closes the room it took.
+-->
+<section class="grid max-w-form gap-title-content">
+  <mds-text typography="section" tag="h2">Deleghe</mds-text>
+  <div class="grid gap-between-fields">
+    <mds-banner id="notice" variant="info" dismissible headline="Nuovo modulo di delega">
+      <mds-text>Da dicembre le deleghe si presentano con il modulo aggiornato.</mds-text>
+    </mds-banner>
+    <mds-text tag="p">Anna Rossi presenta le pratiche dell'azienda per tutto il 2026.</mds-text>
+  </div>
+</section>
+<script>
+  document.getElementById('notice').addEventListener('mdsBannerClose', (event) => event.target.remove());
+</script>

package/agents/patterns/previews/actions/dismiss.html

@@ -0,0 +1,25 @@
+<!--
+try: Press the X at the end of the title row: it closes the dialog, as Annulla does in the row; Nuovo referente opens it again.
+height: 480
+-->
+<mds-button id="open">Nuovo referente</mds-button>
+<mds-modal id="dialog" opened aria-label="Nuovo referente">
+  <mds-banner slot="window" variant="light" tone="box" dismissible headline="Nuovo referente">
+    <form class="grid gap-between-fields">
+      <mds-input-field label="Nome e cognome">
+        <mds-input value="Marco Bianchi"></mds-input>
+      </mds-input-field>
+      <mds-input-field label="Ufficio">
+        <mds-input value="Protocollo"></mds-input>
+      </mds-input-field>
+    </form>
+    <mds-button id="cancel" slot="action" variant="dark" tone="outline">Annulla</mds-button>
+    <mds-button slot="action">Aggiungi</mds-button>
+  </mds-banner>
+</mds-modal>
+<script>
+  const dialog = document.getElementById('dialog');
+  document.getElementById('open').addEventListener('click', () => (dialog.opened = true));
+  document.getElementById('cancel').addEventListener('click', () => dialog.close());
+  dialog.addEventListener('mdsModalClose', () => (dialog.opened = undefined));
+</script>

package/agents/patterns/previews/actions/more-in-menu.html

@@ -0,0 +1,21 @@
+<!--
+try: Look at the row of the contact: the menu of the item at its start, then Invia email and Modifica; the menu, open, holds Duplica and Stampa, and Elimina contatto last after a separator.
+height: 340
+-->
+<header class="@container flex flex-wrap items-start justify-between gap-inline">
+  <div class="grid min-w-0 grow basis-actions gap-title-content">
+    <mds-text typography="page" tag="h1">Mario Rossi</mds-text>
+    <mds-text typography="detail" tag="p" class="text-fg-muted">Ufficio anagrafe, aggiunto il 12 gennaio 2024</mds-text>
+  </div>
+  <div class="flex gap-inline @max-actions:basis-full @max-actions:flex-col @max-actions:*:self-stretch">
+    <mds-button id="more" class="@max-actions:w-fit" icon="mi/baseline/more-vert" variant="dark" tone="text" aria-label="Azioni di Mario Rossi"></mds-button>
+    <mds-button variant="dark" tone="outline">Invia email</mds-button>
+    <mds-button>Modifica</mds-button>
+  </div>
+</header>
+<mds-dropdown id="menu" target="#more" placement="bottom-start" disable-auto-placement visible class="p-200 gap-200">
+  <mds-button variant="dark" tone="text" icon="mi/baseline/content-copy" label="Duplica"></mds-button>
+  <mds-button variant="dark" tone="text" icon="mi/baseline/print" label="Stampa"></mds-button>
+  <mds-separator class="-mx-200 bg-surface-muted dark:bg-surface-raised"></mds-separator>
+  <mds-button variant="error" tone="text" icon="mi/baseline/delete" label="Elimina contatto"></mds-button>
+</mds-dropdown>

package/agents/patterns/previews/actions/part-primary.html

@@ -0,0 +1,28 @@
+<!--
+try: Look at Scarica in the card of the document: the action of a part, in the accent and outlined, one tone under Invia pratica, the one filled action of the page.
+-->
+<div class="grid gap-between-sections">
+  <mds-text typography="page" tag="h1">Nuova pratica</mds-text>
+  <form class="@container grid max-w-form gap-content-actions">
+    <div class="grid gap-between-fields">
+      <mds-input-field label="Oggetto">
+        <mds-input value="Richiesta di accesso agli atti"></mds-input>
+      </mds-input-field>
+      <mds-card>
+        <mds-card-header>
+          <mds-text typography="part" tag="h2">Modulo di delega</mds-text>
+        </mds-card-header>
+        <mds-card-content>
+          <mds-text>Scaricalo, firmalo e allegalo alla pratica.</mds-text>
+        </mds-card-content>
+        <mds-card-footer>
+          <mds-button type="button" icon="mi/baseline/download" variant="primary" tone="outline">Scarica</mds-button>
+        </mds-card-footer>
+      </mds-card>
+    </div>
+    <div class="flex justify-end gap-inline @max-actions:flex-col @max-actions:*:self-stretch">
+      <mds-button type="button" variant="dark" tone="outline">Annulla</mds-button>
+      <mds-button>Invia pratica</mds-button>
+    </div>
+  </form>
+</div>

package/agents/patterns/previews/actions/primary.html

@@ -0,0 +1,20 @@
+<!--
+try: Look at Salva: the one filled action of the page, in the accent, last in the row at the end of the form; Annulla before it is outlined.
+-->
+<div class="grid gap-between-sections">
+  <mds-text typography="page" tag="h1">Nuova richiesta</mds-text>
+  <form class="@container grid max-w-form gap-content-actions">
+    <div class="grid gap-between-fields">
+      <mds-input-field label="Oggetto">
+        <mds-input value="Accesso agli atti"></mds-input>
+      </mds-input-field>
+      <mds-input-field label="Ufficio">
+        <mds-input value="Ufficio tecnico"></mds-input>
+      </mds-input-field>
+    </div>
+    <div class="flex justify-end gap-inline @max-actions:flex-col @max-actions:*:self-stretch">
+      <mds-button type="button" variant="dark" tone="outline">Annulla</mds-button>
+      <mds-button>Salva</mds-button>
+    </div>
+  </form>
+</div>

package/agents/patterns/previews/actions/remove.html

@@ -0,0 +1,44 @@
+<!--
+try: Press the X next to planimetria.pdf: the attachment goes at once, with no question, and a toast says what went and offers Ripristina.
+height: 340
+-->
+<section class="grid max-w-form gap-title-content">
+  <mds-text typography="section" tag="h2">Allegati</mds-text>
+  <div id="allegati" class="grid">
+    <div class="flex items-center justify-between gap-inline">
+      <mds-text>planimetria.pdf</mds-text>
+      <mds-button icon="mi/baseline/close" variant="dark" tone="text" aria-label="Rimuovi planimetria.pdf"></mds-button>
+    </div>
+    <div class="flex items-center justify-between gap-inline">
+      <mds-text>delega-firmata.pdf</mds-text>
+      <mds-button icon="mi/baseline/close" variant="dark" tone="text" aria-label="Rimuovi delega-firmata.pdf"></mds-button>
+    </div>
+    <div class="flex items-center justify-between gap-inline">
+      <mds-text>visura-catastale.pdf</mds-text>
+      <mds-button icon="mi/baseline/close" variant="dark" tone="text" aria-label="Rimuovi visura-catastale.pdf"></mds-button>
+    </div>
+  </div>
+</section>
+<mds-toast-region>
+  <mds-toast id="toast" duration="0" dismissible>
+    Allegato rimosso: planimetria.pdf
+    <mds-button id="restore" slot="action" size="sm" variant="dark" tone="outline">Ripristina</mds-button>
+  </mds-toast>
+</mds-toast-region>
+<script>
+  const list = document.getElementById('allegati');
+  const toast = document.getElementById('toast');
+  let removed;
+  list.addEventListener('click', (event) => {
+    const item = event.target.closest('mds-button')?.parentElement;
+    if (!item) return;
+    removed = { item, next: item.nextElementSibling };
+    toast.firstChild.data = `Allegato rimosso: ${item.querySelector('mds-text').textContent}`;
+    item.remove();
+    toast.visible = true;
+  });
+  document.getElementById('restore').addEventListener('click', () => {
+    list.insertBefore(removed.item, removed.next);
+    toast.visible = undefined;
+  });
+</script>

package/agents/patterns/previews/actions/secondary.html

@@ -0,0 +1,20 @@
+<!--
+try: Look at Salva come bozza: outlined in the neutral, right before Invia, which stays the one filled action of the page.
+-->
+<div class="grid gap-between-sections">
+  <mds-text typography="page" tag="h1">Nuova comunicazione</mds-text>
+  <form class="@container grid max-w-form gap-content-actions">
+    <div class="grid gap-between-fields">
+      <mds-input-field label="Destinatario">
+        <mds-input value="Ufficio tributi"></mds-input>
+      </mds-input-field>
+      <mds-input-field label="Oggetto">
+        <mds-input value="Rimborso TARI 2025"></mds-input>
+      </mds-input-field>
+    </div>
+    <div class="flex justify-end gap-inline @max-actions:flex-col @max-actions:*:self-stretch">
+      <mds-button name="azione" value="bozza" variant="dark" tone="outline">Salva come bozza</mds-button>
+      <mds-button name="azione" value="invio">Invia</mds-button>
+    </div>
+  </form>
+</div>

package/agents/patterns/previews/actions/stacked.html

@@ -0,0 +1,17 @@
+<!--
+try: Narrow the stage (?width=420, then 520): under 380 px of the row the three actions stack at full width, Invia pratica at the bottom; above it they stay on one line, never a ragged wrap.
+-->
+<mds-banner
+  variant="light"
+  tone="box"
+  dismissible
+  headline="Nuova pratica"
+  class="mx-auto w-full max-w-(--magma-width-dialog)"
+>
+  <mds-input-field label="Oggetto">
+    <mds-input value="Richiesta di accesso agli atti"></mds-input>
+  </mds-input-field>
+  <mds-button slot="action" variant="dark" tone="outline">Annulla</mds-button>
+  <mds-button slot="action" variant="dark" tone="outline">Salva come bozza</mds-button>
+  <mds-button slot="action">Invia pratica</mds-button>
+</mds-banner>

package/agents/patterns/previews/actions/toast.html

@@ -0,0 +1,10 @@
+<!--
+try: Look at Riprova in the error toast: small, outlined, in the variant of the toast; the toast stays until the person acts or sends it away with its arrow.
+height: 160
+-->
+<mds-toast-region position="bottom-center">
+  <mds-toast visible variant="error" duration="0" dismissible>
+    Invio non riuscito
+    <mds-button slot="action" size="sm" variant="error" tone="outline">Riprova</mds-button>
+  </mds-toast>
+</mds-toast-region>

package/agents/patterns/previews/app-shell/back-office.html

@@ -0,0 +1,41 @@
+<!--
+try: Look at the bar: the name of the application, the four sections with Pratiche marked as the current one, and the button of Mario Rossi last. Narrow the stage to a phone: the sections move into the menu of the bar, opened by its button.
+height: 520
+whole-page: true
+-->
+<mds-header>
+  <mds-header-bar>
+    <mds-text typography="h6" tag="p">Servizi demografici</mds-text>
+    <mds-button slot="nav" href="#" aria-current="page" variant="dark" tone="weak">Pratiche</mds-button>
+    <mds-button slot="nav" href="#" variant="dark" tone="text">Contatti</mds-button>
+    <mds-button slot="nav" href="#" variant="dark" tone="text">Scadenze</mds-button>
+    <mds-button slot="nav" href="#" variant="dark" tone="text">Archivio</mds-button>
+    <mds-button id="persona" slot="nav" icon="mi/baseline/account-circle" variant="dark" tone="text" aria-label="Account di Mario Rossi"></mds-button>
+  </mds-header-bar>
+  <nav slot="menu" class="grid gap-inline p-inset">
+    <mds-button href="#" aria-current="page" variant="dark" tone="weak" class="w-full justify-start">Pratiche</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Contatti</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Scadenze</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Archivio</mds-button>
+    <mds-separator></mds-separator>
+    <mds-text typography="detail" tag="p" class="text-fg-muted">Mario Rossi</mds-text>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Profilo</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Esci</mds-button>
+  </nav>
+</mds-header>
+<mds-dropdown target="#persona" placement="bottom-end" strategy="fixed">
+  <mds-text typography="detail" tag="p" class="text-fg-muted">Mario Rossi</mds-text>
+  <mds-button href="#" icon="mi/baseline/person" variant="dark" tone="text" label="Profilo"></mds-button>
+  <mds-separator></mds-separator>
+  <mds-button href="#" icon="mi/baseline/logout" variant="dark" tone="text" label="Esci"></mds-button>
+</mds-dropdown>
+<main class="page-frame grid gap-between-sections py-between-sections">
+  <header class="grid gap-title-content">
+    <mds-text typography="page" tag="h1">Pratiche</mds-text>
+    <mds-text typography="detail" tag="p" class="text-fg-muted">Le pratiche che i cittadini inviano agli uffici.</mds-text>
+  </header>
+  <section class="grid gap-title-content">
+    <mds-text typography="section" tag="h2">Da assegnare</mds-text>
+    <mds-text tag="p">Tre pratiche arrivate oggi aspettano un ufficio.</mds-text>
+  </section>
+</main>

package/agents/patterns/previews/app-shell/many-sections.html

@@ -0,0 +1,45 @@
+<!--
+try: Look at the bar: only the name of the application, the button of Mario Rossi and the button of the menu, which is there at every width. Open the menu: the twelve sections, Certificati marked as the current one, then Mario Rossi with Profilo and Esci.
+height: 520
+whole-page: true
+-->
+<mds-header menu="all">
+  <mds-header-bar>
+    <mds-text typography="h6" tag="p">Servizi demografici</mds-text>
+    <mds-button id="persona" slot="nav" icon="mi/baseline/account-circle" variant="dark" tone="text" aria-label="Account di Mario Rossi"></mds-button>
+  </mds-header-bar>
+  <nav slot="menu" class="grid gap-inline p-inset">
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Pratiche</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Scadenze</mds-button>
+    <mds-button href="#" aria-current="page" variant="dark" tone="weak" class="w-full justify-start">Certificati</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Anagrafe</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Stato civile</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Elettorale</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Cittadinanze</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Cimiteri</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Contatti</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Modelli</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Statistiche</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Archivio</mds-button>
+    <mds-separator></mds-separator>
+    <mds-text typography="detail" tag="p" class="text-fg-muted">Mario Rossi</mds-text>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Profilo</mds-button>
+    <mds-button href="#" variant="dark" tone="text" class="w-full justify-start">Esci</mds-button>
+  </nav>
+</mds-header>
+<mds-dropdown target="#persona" placement="bottom-end" strategy="fixed">
+  <mds-text typography="detail" tag="p" class="text-fg-muted">Mario Rossi</mds-text>
+  <mds-button href="#" icon="mi/baseline/person" variant="dark" tone="text" label="Profilo"></mds-button>
+  <mds-separator></mds-separator>
+  <mds-button href="#" icon="mi/baseline/logout" variant="dark" tone="text" label="Esci"></mds-button>
+</mds-dropdown>
+<main class="page-frame grid gap-between-sections py-between-sections">
+  <header class="grid gap-title-content">
+    <mds-text typography="page" tag="h1">Certificati</mds-text>
+    <mds-text typography="detail" tag="p" class="text-fg-muted">I certificati chiesti allo sportello e online.</mds-text>
+  </header>
+  <section class="grid gap-title-content">
+    <mds-text typography="section" tag="h2">Da firmare</mds-text>
+    <mds-text tag="p">Cinque certificati aspettano la firma del funzionario.</mds-text>
+  </section>
+</main>