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

package/agents/patterns/app-shell.md

@@ -0,0 +1,223 @@
+---
+# A Magma building block: the format and the commands are in docs/PATTERNS.md, "A building block".
+id: app-shell
+kind: block
+title: Application shell
+group: navigation
+layer: magma
+status: decided
+need: >-
+  The person knows which application they are in, reaches each of its sections from any page,
+  and sees who they are signed in as.
+principle: One bar names the application and opens its sections at every width; each page lives in one main under it.
+keywords: [application shell, app shell, application bar, top bar, navigation bar, main navigation, sections of the application, menu, hamburger, account menu, sign in, sign out, frame of the page]
+not-for:
+  - need: the head of the content of a page, its title and its actions
+    use: page-header
+assumptions:
+  - Each section of the application is a page of its own, with an address.
+  - The application knows who is signed in, or that nobody is.
+high-stakes: false
+components: [mds-header, mds-header-bar, mds-text, mds-button, mds-dropdown, mds-separator]
+used-by: [list-with-filters, record-detail, empty-state, message-placement]
+related: [page-header, list-with-filters, record-detail, empty-state, message-placement]
+validated-on: []
+
+variables:
+  sections: { values: [few, many], means: "few: the sections of the application fit in the bar, five at most with short names; many: more than five, or names too long for the bar" }
+  person: { values: [signed-in, guest], means: "signed-in: someone is signed in (a back office, always); guest: nobody is signed in yet (a public service before the sign-in)" }
+
+regions:
+  - { id: product, required: true, what: "the name of the application at the start of the bar, as text; a product may put its logo in its place (logo)", use: ["mds-text typography=h6 tag=p"] }
+  - { id: sections, when: { sections: few }, what: "the sections of the application as links, in the order of the work, the current one marked: aria-current=page and a look of its own; in the bar from the width of the desktop, in the menu under it", use: ["mds-button slot=nav href variant=dark tone=text"] }
+  - { id: person, when: { person: signed-in }, what: "the last element of the bar: a button named after the person signed in, which opens their menu: their name, Profilo, then Esci after a separator", use: ["mds-button slot=nav icon variant=dark tone=text", "mds-dropdown", "mds-separator"] }
+  - { id: sign-in, when: { person: guest }, what: "the last element of the bar: Accedi, a link to the sign-in", use: ["mds-button slot=nav href variant=dark tone=outline"] }
+  - { id: menu, what: "the menu of the bar, opened by its button: the sections, the current one marked, then after a separator the name of the person, Profilo and Esci, or Accedi, which keeps its outline; under the width of the desktop with few sections, at every width with many", use: ["mds-header menu", "mds-button href variant=dark tone=text", "mds-button href variant=dark tone=outline", "mds-separator"] }
+  - { id: main, required: true, what: "the content of the page, under the bar: one main in the frame of the page, its header first (page-header), then its sections" }
+
+always-true:
+  - id: one-bar
+    rule: "The application has one bar: mds-header with one mds-header-bar, first in the page; the page starts under it, with no room reserved by hand."
+    checked-by: review
+  - id: sections-are-links
+    rule: "The sections are links to their pages (mds-button with href), the current one marked with aria-current=\"page\"; never a button that runs a script to change page."
+    checked-by: review
+  - id: every-width
+    rule: "Every section is reached at every width: in the bar from the width of the desktop, in the menu of the bar under it; never menu=\"none\" on a bar with sections."
+    checked-by: review
+  - id: person-named
+    rule: "The button of the person is named after them (\"Account di Mario Rossi\") and their menu opens with their name: the person always sees who is signed in."
+    checked-by: review
+  - id: one-main
+    rule: "The content of a page is one main under the bar, in the frame of the page, its header first; the bar never holds the title or the actions of a page."
+    checked-by: review
+  - id: not-the-app-bar
+    from: page-header
+  - id: page
+    from: widths
+  - id: start-edge
+    from: widths
+  - id: band
+    from: surfaces
+  - id: between-sections
+    from: rhythm
+
+open-choices:
+  - { id: logo, default: "the name of the application, as text", may: "put the logo of the product in its place, an mds-img with the name of the application as its alt" }
+
+situations:
+  - { id: back-office, situation: "A back office with four sections, an operator signed in", sections: few, person: signed-in }
+  - { id: many-sections, situation: "An application with a dozen sections, an operator signed in", sections: many, person: signed-in }
+  - { id: public-service, situation: "A public service a citizen opens before signing in", sections: few, person: guest }
+---
+
+# Application shell
+
+**One bar names the application and opens its sections at every width; each page lives in one main under it.**
+
+## When to use it
+
+Around every page of an application: the bar on top, with the name of the application, its
+sections and the person signed in, and the main under it, where the page lays out its header
+and its sections. It came out of the round of the building blocks (2026-11-03): every
+whole-page preview of `list-with-filters`, `record-detail`, `empty-state` (`not-found`) and
+`message-placement` (`app-failed`) wrote the bar and the frame by hand, each a little
+differently, with the sections as buttons with no address, none of them marked as the current
+one, and none reachable on a phone. Not the head of the content of a page, its title and its
+actions (`page-header`), and not the views of a page: tabs are a section of their own, under
+the header.
+
+## What decides it
+
+Two questions: whether the sections fit in the bar (then they stand in it on a wide screen and
+in its menu on a narrow one), and whether someone is signed in (then the bar ends with their
+menu, otherwise with Accedi).
+
+## Regions
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `sections` | `few`, `many` | few: the sections of the application fit in the bar, five at most with short names; many: more than five, or names too long for the bar |
+| `person` | `signed-in`, `guest` | signed-in: someone is signed in (a back office, always); guest: nobody is signed in yet (a public service before the sign-in) |
+
+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 |
+| --- | --- | --- | --- | --- |
+| `product` | any | yes | the name of the application at the start of the bar, as text; a product may put its logo in its place (logo) | `mds-text typography=h6 tag=p` |
+| `sections` | sections: few |  | the sections of the application as links, in the order of the work, the current one marked: aria-current=page and a look of its own; in the bar from the width of the desktop, in the menu under it | `mds-button slot=nav href variant=dark tone=text` |
+| `person` | person: signed-in |  | the last element of the bar: a button named after the person signed in, which opens their menu: their name, Profilo, then Esci after a separator | `mds-button slot=nav icon variant=dark tone=text`, `mds-dropdown`, `mds-separator` |
+| `sign-in` | person: guest |  | the last element of the bar: Accedi, a link to the sign-in | `mds-button slot=nav href variant=dark tone=outline` |
+| `menu` | any |  | the menu of the bar, opened by its button: the sections, the current one marked, then after a separator the name of the person, Profilo and Esci, or Accedi, which keeps its outline; under the width of the desktop with few sections, at every width with many | `mds-header menu`, `mds-button href variant=dark tone=text`, `mds-button href variant=dark tone=outline`, `mds-separator` |
+| `main` | any | yes | the content of the page, under the bar: one main in the frame of the page, its header first (page-header), then its sections |  |
+
+## Layout
+
+- The bar is `mds-header` with one `mds-header-bar`, the first element of the page: a band that
+  stays put at the top, in the flow, so the page starts under it (`surfaces/band`).
+- In the bar: the name of the application at the start (the default slot of the bar), then in
+  its `nav` slot the sections and, last, the button of the person or Accedi, with the gap the
+  bar gives them.
+- With few sections, `mds-header` keeps its defaults (`menu="mobile"`, `nav="desktop"`): from
+  the width of a tablet (768 px) the sections and the person stand in the bar, and under 1024 px
+  the button of the menu opens them too (Magma gaps). With many, `menu="all"`: the sections
+  live only in the menu, at every width; the bar keeps the name and, from 768 px, the person,
+  who is in the menu under it.
+- The menu (`slot="menu"` of `mds-header`) is one column at its inset (`p-inset`): the sections
+  as links as wide as the menu, aligned to the start, the current one marked, then an
+  `mds-separator`, then the name of the person, Profilo and Esci, or Accedi; `gap-inline` (300)
+  between the entries, as between the actions of a row, until the rhythm names a relation for
+  a column of links. A long menu scrolls inside its panel.
+- The main is `page-frame` (`widths/page`): the column the bar gives its own content, with
+  `gap-between-sections` between its sections and as its padding at the top and the bottom
+  (`py-between-sections`, `rhythm/between-sections`); its first section is the header of the
+  page (`page-header`). Everything in it starts at the start edge of the frame, on the edge of
+  the name of the application (`widths/start-edge`).
+
+## 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-bar` | The application has one bar: mds-header with one mds-header-bar, first in the page; the page starts under it, with no room reserved by hand. | review |
+| `sections-are-links` | The sections are links to their pages (mds-button with href), the current one marked with aria-current="page"; never a button that runs a script to change page. | review |
+| `every-width` | Every section is reached at every width: in the bar from the width of the desktop, in the menu of the bar under it; never menu="none" on a bar with sections. | review |
+| `person-named` | The button of the person is named after them ("Account di Mario Rossi") and their menu opens with their name: the person always sees who is signed in. | review |
+| `one-main` | The content of a page is one main under the bar, in the frame of the page, its header first; the bar never holds the title or the actions of a page. | 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. (from `page-header`) | review |
+| `page` | `page-frame` on the page: at most 1280 px, centred in the window, a gutter of `600` outside it, the column the bar gives its own content; everything inside starts at the start edge of the frame, and a table or a list takes the whole frame (from `widths`) |  |
+| `start-edge` | Capped content (text, forms) stands at the start edge of its frame, never centred inside it: the title, the text, the form and the table of a page start on the edge of the content of the bar. (from `widths`) | review |
+| `band` | a band, a strip of surface as wide as the page, drawn by the component that stays put, which keeps its room: the bar of the application (mds-header-bar in mds-header, `surface-raised`, `shadow-md-sharp`, in the flow at the top and sticky, so the page starts under it), the actions of an edit (mds-status-bar, `surface-overlay`, `shadow-md`, its room kept at the end of the page); never the header of the page (`section`) made sticky (from `surfaces`) |  |
+| `between-sections` | `gap-between-sections` (1600) between two sections of a page, each with its title (from `rhythm`) |  |
+
+## Open choices
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+The default decides these; a product layer may narrow them.
+
+| Id | Default | A product may |
+| --- | --- | --- |
+| `logo` | the name of the application, as text | put the logo of the product in its place, an mds-img with the name of the application as its alt |
+
+## 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 |
+| --- | --- | --- |
+| `back-office` | A back office with four sections, an operator signed in | `product`, `sections`, `person`, `menu`, `main` |
+| `many-sections` | An application with a dozen sections, an operator signed in | `product`, `person`, `menu`, `main` |
+| `public-service` | A public service a citizen opens before signing in | `product`, `sections`, `sign-in`, `menu`, `main` |
+
+## Accessibility
+
+- `mds-header-bar` draws the `nav` landmark around its `nav` slot; the content of the page is
+  the one `main` landmark.
+- The current section carries `aria-current="page"` on its `mds-button`, which keeps the role
+  of link on its host; its look is not the only sign of it.
+- The button of the person has an `aria-label` that names them, and opens its menu with
+  `mds-dropdown`, a `menu` by default: the arrows walk its entries, Esc closes it and gives the
+  focus back to the button.
+- The menu of the bar opens in the `mds-modal` of `mds-header`, whose button Magma names
+  ("Apri il menu" in Italian).
+
+## Content
+
+- The name of the application is what the people who use it call it ("Servizi demografici"),
+  not the name of the company or of the product line.
+- A section is the plural of what it holds ("Pratiche", "Contatti", "Scadenze"), in the order of
+  the work, the most used first.
+- The menu of the person: their name and surname, then "Profilo", then "Esci" after the
+  separator. Nobody signed in: "Accedi".
+
+## Magma gaps
+
+- `mds-button` has no state for the current section of a bar: `active` is the pressed look, which
+  the button clears when the pointer is released. The look of the current section is a decision
+  of the round of the building blocks, written with the props Magma has: `tone="weak"`, a filled shape, which still stands at 1.45:1 against the bar in the light mode and 2.48:1 in the dark, under the 3:1 of a state.
+- No side navigation: with many sections, the menu of the bar holds them at every width, and
+  they are not in view beside the page.
+- No link that skips the bar to the content: a screen reader jumps to the `main` landmark, a
+  keyboard passes the sections first.
+- The two breakpoints of `mds-header` do not meet: `nav="desktop"` shows the sections from
+  768 px, `menu="mobile"` hides the button of the menu only from 1024 px, so between them the
+  bar shows both; at 768 px five sections wrap the name of the application on two lines.
+- `mds-dropdown` gives `role="menuitem"` to every child, the name of the person and the
+  separator too, so the arrows stop on them, while its `mds-button href` entries keep
+  `role="link"` and `tabindex="0"`, in the Tab order of a `menu`.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-11-03 | The application shell is a block: the bar and the frame of the page come back in `list-with-filters`, `record-detail`, `empty-state` and `message-placement` | The round of the building blocks: every whole-page preview wrote them by hand, each a little differently; the docs site already names the app shell among the building blocks (`plan/DIRECTION.md`, Patterns section, Navigation). |
+| 2026-11-03 | The sections are links with the current one marked, and they reach a phone through the menu of the bar | The previews had buttons with no address, no current section and `menu="none"`, which hides every section under the width of the desktop (`nav="desktop"` is the default of `mds-header`). |
+| 2026-11-03 | The current section is `variant="dark" tone="weak"`, the others `tone="text"`, in the bar and in the menu | A filled shape, not only a colour: `primary text` (B) changed only the ink, and in the dark mode the accent is near the other sections (1.22:1), so the current one could not be seen. Neither reaches 3:1 against the bar: a Magma gap. The maintainer's choice A in the review of round 3. |

package/agents/patterns/choose-items.md

@@ -0,0 +1,18 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: choose-items
+kind: pattern
+title: Choose items
+group: data
+layer: magma
+status: candidate
+need: >-
+  The person picks items from a long list to use them for something else, such as members to
+  add to a group or documents to attach.
+---
+
+# Choose items
+
+A candidate: a need Magma knows and has not defined yet, split from `list-with-filters` on
+2026-10-29. Until it is defined, the agent says that no default covers it, and proposes the
+pattern (`get_guide reporting`).

package/agents/patterns/concurrent-editing.md

@@ -0,0 +1,17 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: concurrent-editing
+kind: pattern
+title: Concurrent editing
+group: data
+layer: magma
+status: candidate
+need: >-
+  Two people change the same record at the same time, and neither loses their changes.
+---
+
+# Concurrent editing
+
+A candidate: a need Magma knows and has not defined yet, cited by `error-recovery` (`changed-
+meanwhile`). Until it is defined, the agent says that no default covers it, and proposes the
+pattern (`get_guide reporting`).

package/agents/patterns/confirm-action.md

@@ -0,0 +1,216 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: confirm-action
+kind: pattern
+title: Confirm an action
+group: messages-and-states
+layer: magma
+status: decided
+need: >-
+  The person is about to do something that cannot be taken back, and must decide knowing what
+  will happen.
+principle: An action that cannot be taken back asks first, naming the item and the consequence.
+keywords: [confirm, are you sure, delete, remove, undo, cannot be undone, irreversible, permanently]
+not-for:
+  - need: where the outcome of the action is told
+    use: message-placement
+  - need: payments, signatures and consent
+    use: consent-and-legal
+assumptions:
+  - The action starts from a control the person chose (a button, a menu item).
+high-stakes: true
+components: [mds-modal, mds-button, mds-banner, mds-toast]
+related: [message-placement, error-recovery, notification-center, labels-and-values]
+validated-on: []
+
+variables:
+  reversible: { values: ["yes", "no"], means: "can the person undo it afterwards" }
+  reaches-others: { values: ["no", "yes"], means: "does it send something to other people or systems, which cannot be called back" }
+  items: { values: [one, many], means: "how many items the action acts on" }
+  frequency: { values: [occasional, frequent], means: "how often the same person does it in a working day" }
+  stakes: { values: [normal, legal], means: "legal: money, a signature or consent, which have rules of their own" }
+  preview: { values: [seen, unseen], means: "does the person see what goes and to whom when acting" }
+
+cases:
+  - { id: act-then-undo, reversible: "yes", reaches-others: "no", stakes: normal, where: "act at once, then a toast with Undo, the default light toast, which stays until closed", use: ["mds-toast duration=0 dismissible", "mds-button slot=action size=sm variant=dark tone=outline"] }
+  - { id: ask-first, reversible: "no", reaches-others: "no", items: one, frequency: occasional, stakes: normal, where: "a dialog before acting: the question names the item, the text says the consequence", use: ["mds-modal"] }
+  - { id: make-reversible, reversible: "no", reaches-others: "no", items: one, frequency: frequent, stakes: normal, where: "make it reversible: act at once, then a toast with Undo; the item is kept for a while to restore it", use: ["mds-toast duration=0 dismissible", "mds-button slot=action size=sm variant=dark tone=outline"], see: act-then-undo }
+  - { id: ask-first-many, reversible: "no", reaches-others: "no", items: many, stakes: normal, where: "a dialog before acting that says how many", use: ["mds-modal"] }
+  - { id: send-as-shown, reaches-others: "yes", preview: seen, stakes: normal, where: "no dialog: the Send button, with what and to whom in front of the person, is the confirmation; once sent, a success banner takes the place of the form, so nothing goes twice, and its action brings back an empty form", use: ["mds-button type=submit await", "mds-banner variant=success tone=strong", "mds-button slot=action"] }
+  - { id: ask-before-sending, reaches-others: "yes", preview: unseen, stakes: normal, where: "a dialog that shows what goes and to whom before sending", use: ["mds-modal"] }
+gaps: []
+not-applicable:
+  - { stakes: legal, why: "payments, signatures and consent have legal rules of their own: the candidate consent-and-legal" }
+
+always-true:
+  - id: irreversible-asks
+    rule: An action that cannot be taken back asks first.
+    checked-by: review
+  - id: names-item-and-consequence
+    rule: The question names the item, the text says the consequence.
+    checked-by: review
+  - id: verb-not-ok
+    rule: The confirm button repeats the verb ("Delete"), never "OK" or "Yes".
+    checked-by: review
+    note: a lint on the known words is possible
+  - id: cancel-is-safe
+    rule: Cancel and Esc never do the action.
+    checked-by: review
+
+open-choices:
+  - { id: typed-confirmation, default: "none: the dialog that names the item and says how many is enough", may: "ask to type the name or the number for its gravest cases" }
+
+situations:
+  - { situation: A document is removed from a draft, case: act-then-undo }
+  - { situation: An item is deleted for good, case: ask-first }
+  - { situation: 12 items are deleted for good, case: ask-first-many }
+  - { situation: "An item is archived, and can be restored", case: act-then-undo }
+  - { situation: "An operator closes dozens of tickets a day, for good", case: make-reversible }
+  - { situation: "A message is sent from its form, with the text and the recipient on screen", case: send-as-shown }
+  - { situation: A reminder is sent to a person from the menu of a row, case: ask-before-sending }
+  - { situation: A payment is confirmed, use: consent-and-legal }
+---
+
+# Confirm an action
+
+**An action that cannot be taken back asks first, naming the item and the consequence.**
+
+## When to use it
+
+An action the person chose that cannot be taken back, or that sends something to other people:
+delete for good, close for good, send. Not where its outcome is told (`message-placement`), not
+payments, signatures and consent (`consent-and-legal`).
+
+## What decides it
+
+Six questions: whether the person can undo the action afterwards, whether it sends something
+to other people or systems, whether it acts on one item or many, how often the same person does
+it in a working day, whether money, a signature or consent is at stake, and whether the person
+sees what goes and to whom when acting.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `reversible` | `yes`, `no` | can the person undo it afterwards |
+| `reaches-others` | `no`, `yes` | does it send something to other people or systems, which cannot be called back |
+| `items` | `one`, `many` | how many items the action acts on |
+| `frequency` | `occasional`, `frequent` | how often the same person does it in a working day |
+| `stakes` | `normal`, `legal` | legal: money, a signature or consent, which have rules of their own |
+| `preview` | `seen`, `unseen` | does the person see what goes and to whom when acting |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use |
+| --- | --- | --- | --- |
+| `act-then-undo` | reversible: yes; reaches-others: no; stakes: normal | act at once, then a toast with Undo, the default light toast, which stays until closed | `mds-toast duration=0 dismissible`, `mds-button slot=action size=sm variant=dark tone=outline` |
+| `ask-first` | reversible: no; reaches-others: no; items: one; frequency: occasional; stakes: normal | a dialog before acting: the question names the item, the text says the consequence | `mds-modal` |
+| `make-reversible` | reversible: no; reaches-others: no; items: one; frequency: frequent; stakes: normal | make it reversible: act at once, then a toast with Undo; the item is kept for a while to restore it; see `act-then-undo` | `mds-toast duration=0 dismissible`, `mds-button slot=action size=sm variant=dark tone=outline` |
+| `ask-first-many` | reversible: no; reaches-others: no; items: many; stakes: normal | a dialog before acting that says how many | `mds-modal` |
+| `send-as-shown` | reaches-others: yes; stakes: normal; preview: seen | no dialog: the Send button, with what and to whom in front of the person, is the confirmation; once sent, a success banner takes the place of the form, so nothing goes twice, and its action brings back an empty form | `mds-button type=submit await`, `mds-banner variant=success tone=strong`, `mds-button slot=action` |
+| `ask-before-sending` | reaches-others: yes; stakes: normal; preview: unseen | a dialog that shows what goes and to whom before sending | `mds-modal` |
+
+Not applicable:
+
+| When | Why |
+| --- | --- |
+| stakes: legal | payments, signatures and consent have legal rules of their own: the candidate consent-and-legal |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+The dialog of `ask-first` and `ask-first-many`:
+
+- the title is the question, with the name of the item ("Delete Mario Rossi?") or how many
+  ("Delete 12 items?"); it is also the accessible name of the dialog;
+- a sentence with the consequence ("They will no longer be able to sign in. Their changes
+  stay, under their name.");
+- an error banner, hidden, for when the action fails, `tone="strong"`, right above the row
+  (`message-placement`, `action-failed-in-place`);
+- at the end, Cancel (`variant="dark" tone="outline"`), then the action with its verb
+  (`variant="error"` when it destroys).
+
+The dialog of `ask-before-sending` is the same, with what goes and to whom in place of the
+consequence (the recipient and the text, as labels and values), and the action with its verb in
+the default `primary strong`: sending does not destroy.
+
+The toast with Undo of `act-then-undo` and `make-reversible` is the default `light` toast, with
+Undo as `mds-button size="sm" variant="dark" tone="outline"` in its `action` slot.
+
+After `send-as-shown`, a success banner (`tone="strong"`) takes the place of the form: it names
+what went and to whom, and its action ("Write another message") brings back the form, empty.
+
+## Behaviour over time
+
+- On the action: `await` on its button, which cannot be pressed again.
+- A message sent from its form (`send-as-shown`): the form goes when the message went, so the
+  same message cannot be sent twice by pressing again; the banner that takes its place is read
+  out, and the focus goes to the title of the page.
+- It works: the dialog closes, a toast that names what went, the default `light` toast of a
+  removal (`message-placement`, `removal-toast-neutral`); if the element that opened the dialog
+  is gone, the focus goes to the title of the page.
+- It fails: the banner in the dialog, "Nothing was changed"; the dialog stays open.
+- Cancel or Esc: the dialog closes (to verify on `mds-modal`: the focus goes back to what
+  opened it).
+- On opening, the focus is on Cancel, the safe choice; Esc means Cancel, so the dialog is not
+  `strict`.
+- The toast with Undo stays until it is closed, as every toast with an action
+  (`message-placement`, `toast-action-stays`): the time limit to undo is kept by the
+  application, which keeps the item for a while, not by the toast.
+
+## 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 |
+| --- | --- | --- |
+| `irreversible-asks` | An action that cannot be taken back asks first. | review |
+| `names-item-and-consequence` | The question names the item, the text says the consequence. | review |
+| `verb-not-ok` | The confirm button repeats the verb ("Delete"), never "OK" or "Yes". | review; a lint on the known words is possible |
+| `cancel-is-safe` | Cancel and Esc never do the action. | review |
+
+## Open choices
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+The default decides these; a product layer may narrow them.
+
+| Id | Default | A product may |
+| --- | --- | --- |
+| `typed-confirmation` | none: the dialog that names the item and says how many is enough | ask to type the name or the number for its gravest cases |
+
+## Situations
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+Situations every application has, each with its case: they give the examples, the texts and the keywords. The situations of a product's own domain go in its layer.
+
+| Situation | Case |
+| --- | --- |
+| A document is removed from a draft | `act-then-undo` |
+| An item is deleted for good | `ask-first` |
+| 12 items are deleted for good | `ask-first-many` |
+| An item is archived, and can be restored | `act-then-undo` |
+| An operator closes dozens of tickets a day, for good | `make-reversible` |
+| A message is sent from its form, with the text and the recipient on screen | `send-as-shown` |
+| A reminder is sent to a person from the menu of a row | `ask-before-sending` |
+| A payment is confirmed | not here: `consent-and-legal` |
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-16 | Proposed: an irreversible action always asks, naming the item and the consequence | Open decision of the docs site, `agents/patterns.md`. |
+| 2026-10-28 | Draft with variables; the frequent irreversible action and the action that reaches others left as gaps | The sources do not settle them. |
+| 2026-10-28 | An irreversible action done many times a day is made reversible, with Undo (`make-reversible`) | Asking every time teaches to confirm without reading, where the confirmation matters most. |
+| 2026-10-28 | An action that reaches others asks only when the person does not see what goes and to whom (`send-as-shown`, `ask-before-sending`) | With the content and the recipient in front of them, the Send button is already the confirmation. |
+| 2026-10-28 | The toast with Undo stays until closed | The rule of every toast with an action, there for accessibility; the time limit is the application's. |
+| 2026-10-28 | No typed confirmation in the default; a product may add it (`typed-confirmation`) | The dialog that names the item and says how many is enough for a default. |
+| 2026-11-01 | The toast of a removal, with Undo or after a confirmation, is the default `light` toast, not `success` (`act-then-undo`, `make-reversible`) | A removal is a loss the person wanted, and green celebrates it; on the neutral toast no colour judges the removal or Undo (`removal-toast-neutral` of `message-placement`). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6556983924 |
+| 2026-11-03 | Cancel is `dark outline`, the error banner of the dialog `tone="strong"` right above the row; the action of the toast with Undo is `size="sm" variant="dark" tone="outline"` | The rules of the domain Actions (`secondary`, `failed`, `toast`), which are newer than this pattern. Applied in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |
+| 2026-11-03 | After `send-as-shown`, a success banner takes the place of the form, and its action brings back an empty form; no toast | With the text still on screen and a toast that goes, the person may send the same message again in a few seconds without knowing it went. Asked in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |

package/agents/patterns/consent-and-legal.md

@@ -0,0 +1,16 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: consent-and-legal
+kind: pattern
+title: Consent and legal steps
+group: input
+layer: magma
+status: candidate
+need: >-
+  The person pays, signs or gives consent: steps with legal rules of their own.
+---
+
+# Consent and legal steps
+
+A candidate: a need Magma knows and has not defined yet, cited by `confirm-action`. Until it is
+defined, the agent says that no default covers it, and proposes the pattern (`get_guide reporting`).