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

package/agents/patterns/previews/widths/page.html

@@ -0,0 +1,49 @@
+<!--
+try: Look at the start edge: the name of the application in the bar, the title and the table start on one line, and the table takes the whole frame. Narrow the stage: the gutter stays the same at every width.
+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">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">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 di residenza</mds-text>
+    <mds-text typography="detail" tag="p" class="text-fg-muted">Le richieste degli ultimi trenta giorni, dalla più recente.</mds-text>
+  </header>
+  <mds-table class="w-full">
+    <mds-table-header>
+      <mds-table-header-cell label="Protocollo"></mds-table-header-cell>
+      <mds-table-header-cell label="Richiedente"></mds-table-header-cell>
+    </mds-table-header>
+    <mds-table-body>
+      <mds-table-row>
+        <mds-table-cell><mds-text typography="detail">2026/0412</mds-text></mds-table-cell>
+        <mds-table-cell><mds-text typography="detail">Giulia Bianchi</mds-text></mds-table-cell>
+      </mds-table-row>
+      <mds-table-row>
+        <mds-table-cell><mds-text typography="detail">2026/0398</mds-text></mds-table-cell>
+        <mds-table-cell><mds-text typography="detail">Luca Ferri</mds-text></mds-table-cell>
+      </mds-table-row>
+    </mds-table-body>
+  </mds-table>
+</main>

package/agents/patterns/previews/widths/reading.html

@@ -0,0 +1,15 @@
+<!--
+try: Narrow the stage with the handle at its right: the lines stay at about 70 characters, and follow the stage only once it is narrower than the measure.
+-->
+<div class="grid gap-title-content">
+  <mds-text typography="h3" tag="h1">Cambio di residenza</mds-text>
+  <mds-text typography="detail" tag="p">
+    Comunica il nuovo indirizzo entro venti giorni dal trasloco. L'ufficio anagrafe verifica la
+    dimora abituale con un sopralluogo della polizia locale e, se la verifica conferma quanto
+    dichiarato, registra la nuova residenza dalla data della richiesta.
+  </mds-text>
+  <mds-text typography="detail" tag="p">
+    A ogni passaggio della pratica ti scriviamo alla posta certificata che indichi: la conferma
+    della richiesta, la data del sopralluogo e l'esito della verifica.
+  </mds-text>
+</div>

package/agents/patterns/record-detail.md

@@ -0,0 +1,268 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: record-detail
+kind: pattern
+title: Record detail
+group: data
+layer: magma
+status: decided
+need: >-
+  The person opens one record to read it and act on it, then goes back to the list as it was.
+principle: The page shows the record as the back end saved it, and only the actions its status allows.
+keywords: [detail, record, details page, view, status, actions, tabs, documents, history, edit, back to list]
+not-for:
+  - need: finding the record in a long list
+    use: list-with-filters
+  - need: an action that cannot be taken back
+    use: confirm-action
+  - need: what a role may not see or do on the record
+    use: permissions
+  - need: two people changing the same record at the same time
+    use: concurrent-editing
+  - need: a record that does not exist
+    use: empty-state
+  - need: a record that is loading, or could not be loaded
+    use: loading
+assumptions:
+  - The back end returns the record after every action, with its status and the actions the status allows.
+  - The application knows whether other people or systems change the record while it is on screen.
+high-stakes: false
+components: [mds-text, mds-badge, mds-button, mds-dropdown, mds-separator, mds-tab, mds-tab-item, mds-file, mds-author, mds-modal, mds-input-field, mds-input, mds-banner]
+related: [list-with-filters, message-placement, confirm-action, empty-state, loading, error-recovery, form-and-validation, concurrent-editing, permissions, page-header, labels-and-values, app-shell]
+validated-on: []
+
+variables:
+  process: { values: ["yes", "no"], means: "yes: the record moves through a process, with a status, the actions the status allows and a history (a request, a payment); no: a record of data with no process (a contact, a product)" }
+  action: { values: [none, at-once, with-words, edit], means: "what the person is doing: none, reading; at-once, an action that needs nothing (take in charge); with-words, an action that needs a note or a reason (request documents, close with a reason); edit, changing the data of the record" }
+  changes: { values: ["no", by-others], means: "by-others: other people or systems change the record while it is on screen" }
+
+cases:
+  - { id: work-on-it, process: "yes", action: none, changes: "no", where: "back to the list; the number, the subject as the heading, the status, where it belongs and when it arrived; the actions the status allows, the main one last; the parts in tabs (data, documents, history)", use: ["mds-text tag=h1", "mds-badge", "mds-button", "mds-tab", "mds-tab-item href", "mds-file", "mds-author"] }
+  - { id: read-the-data, process: "no", action: none, changes: "no", where: "back to the list; the name as the heading; Edit, and Delete last in the menu of the record, after a separator, in the error text tone with its icon (it asks first); the data as labels and values, the parts in tabs when there is more than one", use: ["mds-text tag=h1", "mds-button", "mds-dropdown", "mds-separator", "mds-button variant=error tone=text icon", "mds-text tag=dl"], see: confirm-action }
+  - { id: run-at-once, action: at-once, changes: "no", where: "the button waits; then the page shows the record the back end returns, the outcome is a toast, and the focus goes to the heading when the button is gone", use: ["mds-button await"], see: message-placement }
+  - { id: ask-for-words, action: with-words, changes: "no", where: "a dialog named after the action, with a required field; left empty, the field says what is missing and takes the focus; the confirm button repeats the action; a failure stays in the dialog with what was written", use: ["mds-modal", "mds-input-field", "mds-input type=textarea required", "mds-button type=submit await"] }
+  - { id: edit-data, action: edit, changes: "no", where: "Edit, one of the actions the status allows, turns the page into the form, at the address of the record with /edit; Save returns to the detail with a toast and the focus on the heading; Cancel or Back return to it as it was", use: ["mds-button"], see: form-and-validation }
+  - { id: record-changed, changes: by-others, action: [none, at-once, with-words], where: "an info banner under the identity says who changed the record and when, and that the actions on screen may no longer hold; Show, its action, loads the record again; nothing else changes before the click; then the banner goes and the focus goes to the heading", use: ["mds-banner variant=info", "mds-button slot=action variant=info tone=strong"] }
+gaps: []
+not-applicable:
+  - { action: edit, changes: by-others, why: "two people changing the same record at the same time is the candidate concurrent-editing" }
+
+always-true:
+  - id: status-decides-actions
+    rule: Only the actions the status allows are on screen; never an action shown disabled to guess about.
+    checked-by: review
+  - id: main-action-last
+    rule: "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."
+    checked-by: review
+  - id: shows-what-was-saved
+    rule: After an action the page shows the record the back end returns, never a guess of the page.
+    checked-by: review
+  - id: address-holds-record-and-tab
+    rule: "The address holds the record and the tab: a link to the history of a record opens on its history."
+    checked-by: review
+  - id: back-as-it-was
+    rule: Back to the list returns to it with its search, its filters and its page.
+    checked-by: review
+  - id: focus-to-heading
+    rule: When the control of an action is gone, the focus goes to the heading of the page, never to the top of the page.
+    checked-by: review
+  - id: keep-the-work
+    from: error-recovery
+  - id: verb-not-ok
+    from: confirm-action
+  - id: not-an-error
+    from: empty-state
+  - id: nothing-moves-by-itself
+    from: list-with-filters
+
+open-choices:
+  - { id: next-record, default: "none: Back returns to the list as it was", may: "add Previous and Next, which follow the query of the list, for a product that works through a queue" }
+
+situations:
+  - { situation: An operator opens a request from the list and reads its documents, case: work-on-it }
+  - { situation: "A colleague sends a link to the history of a request", case: work-on-it, note: "it opens on the History tab" }
+  - { situation: A contact opens from the address book, case: read-the-data }
+  - { situation: A request is taken in charge, case: run-at-once }
+  - { situation: "Documents are requested from the applicant, with a note", case: ask-for-words }
+  - { situation: A request is closed with a reason, case: ask-for-words }
+  - { situation: "An operator works through a queue of requests, one after the other", case: work-on-it, note: "Previous and Next are a choice of the product (next-record)" }
+  - { situation: The address of a contact is corrected, case: edit-data }
+  - { situation: A colleague takes the request in charge while it is open, case: record-changed }
+  - { situation: A contact is deleted, use: confirm-action }
+  - { situation: Two people change the same contact at the same time, use: concurrent-editing }
+  - { situation: An address leads to a request that was deleted, use: empty-state }
+---
+
+# Record detail
+
+**The page shows the record as the back end saved it, and only the actions its status allows.**
+
+## When to use it
+
+The page of one record people work on over time, opened from a list (`list-with-filters`) or a
+link: a request, a payment, a document; or a record of data with no process, a contact, a
+product. Something else fits better: a record with a few fields and nothing to do with it goes
+in its row of the list, or in a panel next to it, with no page of its own; records to compare go
+in the list, side by side in its columns.
+
+## What decides it
+
+Three questions: whether the record moves through a process (a status, actions, a history),
+what the person is doing on it (reading, an action that needs nothing, an action that needs
+words, changing its data), and whether other people change it while it is on screen.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `process` | `yes`, `no` | yes: the record moves through a process, with a status, the actions the status allows and a history (a request, a payment); no: a record of data with no process (a contact, a product) |
+| `action` | `none`, `at-once`, `with-words`, `edit` | what the person is doing: none, reading; at-once, an action that needs nothing (take in charge); with-words, an action that needs a note or a reason (request documents, close with a reason); edit, changing the data of the record |
+| `changes` | `no`, `by-others` | by-others: other people or systems change the record while it is on screen |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use |
+| --- | --- | --- | --- |
+| `work-on-it` | process: yes; action: none; changes: no | back to the list; the number, the subject as the heading, the status, where it belongs and when it arrived; the actions the status allows, the main one last; the parts in tabs (data, documents, history) | `mds-text tag=h1`, `mds-badge`, `mds-button`, `mds-tab`, `mds-tab-item href`, `mds-file`, `mds-author` |
+| `read-the-data` | process: no; action: none; changes: no | back to the list; the name as the heading; Edit, and Delete last in the menu of the record, after a separator, in the error text tone with its icon (it asks first); the data as labels and values, the parts in tabs when there is more than one; see `confirm-action` | `mds-text tag=h1`, `mds-button`, `mds-dropdown`, `mds-separator`, `mds-button variant=error tone=text icon`, `mds-text tag=dl` |
+| `run-at-once` | action: at-once; changes: no | the button waits; then the page shows the record the back end returns, the outcome is a toast, and the focus goes to the heading when the button is gone; see `message-placement` | `mds-button await` |
+| `ask-for-words` | action: with-words; changes: no | a dialog named after the action, with a required field; left empty, the field says what is missing and takes the focus; the confirm button repeats the action; a failure stays in the dialog with what was written | `mds-modal`, `mds-input-field`, `mds-input type=textarea required`, `mds-button type=submit await` |
+| `edit-data` | action: edit; changes: no | Edit, one of the actions the status allows, turns the page into the form, at the address of the record with /edit; Save returns to the detail with a toast and the focus on the heading; Cancel or Back return to it as it was; see `form-and-validation` | `mds-button` |
+| `record-changed` | action: none or at-once or with-words; changes: by-others | an info banner under the identity says who changed the record and when, and that the actions on screen may no longer hold; Show, its action, loads the record again; nothing else changes before the click; then the banner goes and the focus goes to the heading | `mds-banner variant=info`, `mds-button slot=action variant=info tone=strong` |
+
+Not applicable:
+
+| When | Why |
+| --- | --- |
+| action: edit; changes: by-others | two people changing the same record at the same time is the candidate concurrent-editing |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+- **Back to the list**: a link that returns to the list as it was.
+- **The identity**: the number of the record, small, above its subject, which is the heading of
+  the page (`h1`, `tabindex="-1"` so the focus can go to it); the status as `mds-badge`; a line
+  with where it belongs and when it arrived.
+- **The actions**: the ones the status allows, as `mds-button`, the main one last in the strong
+  tone. Back to the list, the identity and the actions are the block `page-header`.
+- **The tabs**: the data, the documents and the history, one at a time (`mds-tab`), only when
+  there is more than one part; a section of their own, right under the header.
+- **The data**: labels and values, in two columns when there is room: the block
+  `labels-and-values`, a `dl` of `mds-text` (`tag="dt"`, `tag="dd"`).
+- **The documents**: one `mds-file` for each file.
+- **The history**: who did what, and when (`mds-author`), the newest first, with the note written
+  with the action.
+
+## Behaviour over time
+
+- The first load is `loading`; a record that does not exist is the `not-found` case of
+  `empty-state`; a record that could not be loaded is `retry-content` of `error-recovery`.
+- An action that needs nothing runs at once; one that needs words asks for them in a dialog
+  first.
+- After an action the status, the actions and the history come from the answer of the back end;
+  the outcome is a toast (`message-placement`); the button that ran it may be gone, so the focus
+  goes to the heading.
+- A failed action changes nothing: the record stays as it was, the dialog stays open with what
+  was written, and a banner in it says to try again.
+- When the list opened the record, Back to the list goes back in the history of the browser, and
+  the list comes back with its query; from a link, it opens the list with no filters.
+- A record that is deleted takes the person back to the list, with a toast (`message-placement`).
+- Edit turns the page into the form, at its own address: Back leaves it, a reload keeps it. What
+  is checked and when, and what happens to changes not saved, is `form-and-validation`.
+- Someone else changes the record: an info banner under the identity says who and when ("Anna
+  Bianchi took the request in charge at 10:42") and that the actions may no longer hold, and
+  Show loads it again; the banner goes and the focus goes to the heading. Nothing else changes
+  before that: the banner pushes the content down once, when it comes. An action sent
+  meanwhile, from the page or from an open dialog, that the new status no longer allows is
+  refused by the back end: `changed-meanwhile` of `error-recovery`.
+
+## 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 |
+| --- | --- | --- |
+| `status-decides-actions` | Only the actions the status allows are on screen; never an action shown disabled to guess about. | 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. | review |
+| `shows-what-was-saved` | After an action the page shows the record the back end returns, never a guess of the page. | review |
+| `address-holds-record-and-tab` | The address holds the record and the tab: a link to the history of a record opens on its history. | review |
+| `back-as-it-was` | Back to the list returns to it with its search, its filters and its page. | review |
+| `focus-to-heading` | When the control of an action is gone, the focus goes to the heading of the page, never to the top of the page. | review |
+| `keep-the-work` | A failure never loses what the person wrote or chose. (from `error-recovery`) | review |
+| `verb-not-ok` | The confirm button repeats the verb ("Delete"), never "OK" or "Yes". (from `confirm-action`) | review; a lint on the known words is possible |
+| `not-an-error` | A part that failed to load is an error, never an empty state. (from `empty-state`) | review |
+| `nothing-moves-by-itself` | Items added or changed by others never move what is on screen; they wait until the person asks for them. (from `list-with-filters`) | 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 |
+| --- | --- | --- |
+| `next-record` | none: Back returns to the list as it was | add Previous and Next, which follow the query of the list, for a product that works through a queue |
+
+## 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 |
+| --- | --- |
+| An operator opens a request from the list and reads its documents | `work-on-it` |
+| A colleague sends a link to the history of a request | `work-on-it`: it opens on the History tab |
+| A contact opens from the address book | `read-the-data` |
+| A request is taken in charge | `run-at-once` |
+| Documents are requested from the applicant, with a note | `ask-for-words` |
+| A request is closed with a reason | `ask-for-words` |
+| An operator works through a queue of requests, one after the other | `work-on-it`: Previous and Next are a choice of the product (next-record) |
+| The address of a contact is corrected | `edit-data` |
+| A colleague takes the request in charge while it is open | `record-changed` |
+| A contact is deleted | not here: `confirm-action` |
+| Two people change the same contact at the same time | not here: `concurrent-editing` |
+| An address leads to a request that was deleted | not here: `empty-state` |
+
+## Accessibility
+
+- The subject is the heading of the page; the number above it and the line below are text.
+- The outcome of an action is a toast in the `mds-toast-region`, read out without moving the
+  focus.
+- The dialog is named by its title and takes the focus when it opens; the required field says in
+  words what is missing.
+- The data is a description list, so every value is read with its label.
+- The line of a change made by others is read out when it appears, without moving the focus.
+- The documents are buttons, announced as such and opened from the keyboard (`mds-file`).
+
+## Content
+
+- The heading is what the record is about, "Change of residence"; the number goes above it,
+  smaller: people recognise a subject, and copy a number.
+- Actions are named after what they do to the record, with a verb: "Request documents", "Close
+  request", never "OK" or "Proceed"; the confirm button of a dialog repeats it.
+- The text of a dialog says what follows: who receives what, and whether it can be undone.
+- A line of the history says who did what, and when; the note stays as it was written.
+- The outcome of an action is in the past: "The request was closed."
+
+## Magma gaps
+
+- No component for labels and values in two columns: a `dl` of `mds-text` with `tag="dt"` and
+  `tag="dd"`, laid out as the block `labels-and-values` says.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-29 | The status decides the actions, an action that needs words asks for them first, the page shows what the back end returns, a failed action changes nothing, the address holds the record and the tab, Back returns to the list as it was, not found is not an error | The draft page of the docs site, `patterns/record-detail`, and its example. |
+| 2026-10-29 | Draft with variables; changing the data and the record changed by others left as gaps | The sources do not settle them. |
+| 2026-10-29 | Edit turns the page into the form, at its own address (`edit-data`) | One rule for any length of form; Back and a reload work; the form follows `form-and-validation`. |
+| 2026-10-29 | A change made by others waits behind a line with who, when and Show (`record-changed`) | As in `list-with-filters`: nothing moves under the pointer, and the person learns before the click that an action may no longer hold. |
+| 2026-10-29 | Previous and Next are a product's choice (`next-record`) | Most records are opened one at a time; a product that works through a queue adds them. |
+| 2026-10-31 | The actions other than the main one are outlined (`variant="dark" tone="outline"`); Delete leaves the row for the menu of the record, last after a separator, in the error text tone with its icon | The design language, #1189: `actions/secondary`, `actions/destructive-in-menu` and the severity of a deletion (level 2: the menu of the item, and a confirmation that names it). |
+| 2026-11-03 | A record changed by others shows an info banner under the identity, with Show (`record-changed`), not the quiet line of `show-new-items` | The change of the record that is open can make its actions wrong, and the banner is not missed; it moves the content once, which the line of a list avoids. Chosen in review round 2 of the previews (https://github.com/magma-design-system/magma/issues/1233), over the line. |

package/agents/patterns/rhythm.md

@@ -0,0 +1,212 @@
+---
+id: rhythm
+kind: foundation
+title: Rhythm
+layer: magma
+status: decided
+need: >-
+  Space two elements of a composition by how they relate, so that each one stands nearer to
+  what it belongs to than to its neighbour.
+principle: >-
+  The space between two elements says how they relate: one step of a ladder for each relation,
+  never a value of your own.
+keywords: [rhythm, spacing, space, gap, padding, margin, proximity, distance, inset, ladder]
+assumptions:
+  - "The values are those of the standard density: a denser or a roomier screen scales every step by one factor (the domain density)."
+  - "The space inside a control (the padding of a button, of an input) is the component's own, not a relation."
+components: [mds-input-field, mds-banner, mds-note, mds-dropdown, mds-card]
+related: []
+validated-on: []
+
+variables:
+  relation:
+    values: [inline, title-content, label-control, between-fields, content-actions, between-groups, between-sections, inset, between-containers]
+    means: "How the two elements relate: side by side in one row, a title and what it names, a label and its control, two fields of a group, the content of a container and the row of actions that closes it, two groups of a section, two sections of the page, the content and the edge of its container, two containers with a boundary of their own."
+
+cases:
+  - id: inline
+    relation: inline
+    where: "`gap-inline` (300) between elements side by side in one row: the actions of a row, a field and the button beside it"
+    serves: intuitive
+    carried-by: [--magma-rhythm-inline, gap-inline]
+  - id: title-content
+    relation: title-content
+    where: "`gap-title-content` (300) between a title and the content it names"
+    serves: intuitive
+    carried-by: [--magma-rhythm-title-content, gap-title-content]
+  - id: label-control
+    relation: label-control
+    where: "`gap-label-control` (300) between the label of a field, its control and its message"
+    serves: intuitive
+    carried-by: [mds-input-field, --magma-rhythm-label-control, gap-label-control]
+  - id: between-fields
+    relation: between-fields
+    where: "`gap-between-fields` (600) between two fields of a form, or two rows of data"
+    serves: intuitive
+    carried-by: [--magma-rhythm-between-fields, gap-between-fields]
+  - id: content-actions
+    relation: content-actions
+    where: "`gap-content-actions` (600) between the content of a container and the row of actions that closes it: the footer of a card, the row of a form, the actions of the window of a dialog"
+    serves: intuitive
+    carried-by: [mds-card, --magma-rhythm-content-actions, gap-content-actions]
+  - id: between-groups
+    relation: between-groups
+    where: "`gap-between-groups` (1000) between two groups of fields of one form (the fieldsets of personal data and of residence)"
+    serves: intuitive
+    carried-by: [--magma-rhythm-between-groups, gap-between-groups]
+  - id: between-sections
+    relation: between-sections
+    where: "`gap-between-sections` (1600) between two sections of a page, each with its title"
+    serves: intuitive
+    carried-by: [--magma-rhythm-between-sections, gap-between-sections]
+  - id: inset
+    relation: inset
+    where: "`p-inset` (600) inside a container of a part (a card, a banner, a note, a dropdown, the window of a dialog), shared by its regions"
+    serves: intuitive
+    carried-by: [mds-card, mds-banner, mds-note, mds-dropdown, --magma-rhythm-inset, p-inset]
+  - id: between-containers
+    relation: between-containers
+    where: "`gap-between-containers` (400) between containers with a boundary of their own (the cards of a section, of a grid, of a list of cards)"
+    serves: intuitive
+    carried-by: [--magma-rhythm-between-containers, gap-between-containers]
+
+gaps: []
+not-applicable: []
+
+always-true:
+  - id: step-ratio
+    rule: "Between relations with no boundary, each step is at least 1.5 times the step it contains: an element stands nearer to what it belongs to than to its neighbour."
+    serves: intuitive
+    checked-by: review
+  - id: shared-inset
+    rule: "The regions of a container share its inset: the title, the content and the actions of a card stand inside one p-600, their paddings never add up."
+    serves: intuitive
+    carried-by: [mds-card, mds-banner]
+    checked-by: review
+  - id: media-bleed
+    rule: "The media of a container (the image of a card) reaches the edges of the container it touches and stands from the other regions as they stand from each other: the inset keeps text away from the edge, and an image has no text to keep away."
+    serves: intuitive
+    carried-by: [mds-card]
+    checked-by: review
+  - id: ladder-only
+    rule: "Every space between the elements of a composition is the step of its relation: 300, 400 between containers only, 600, 1000, 1600 at the standard density. No other value, no Tailwind t-shirt name (gap-lg)."
+    serves: [intuitive, flexible]
+    checked-by: review
+    note: "check.patterns will hold the previews to it (#1189, the previews redone on the rules)"
+
+open-choices: []
+
+situations:
+  - { situation: "Annulla and Salva side by side at the end of a form", case: inline }
+  - { situation: "The title of a card and its text", case: title-content }
+  - { situation: "The label of a field above its input", case: label-control }
+  - { situation: "The fields of a form in a dialog", case: between-fields }
+  - { situation: "Apri under the data of a card in a list of requests", case: content-actions }
+  - { situation: "The personal data and the residence of a long form, each in its fieldset", case: between-groups }
+  - { situation: "The sections of the page of a record", case: between-sections }
+  - { situation: "The header of a page and the content under it", case: between-sections, note: "the header (the block page-header) is the first section of the page" }
+  - { situation: "The content of a card, a banner or the window of a dialog", case: inset }
+  - { situation: "The cards of a list of results", case: between-containers }
+---
+
+# Rhythm
+
+**The space between two elements says how they relate: one step of a ladder for each relation, never a value of your own.**
+
+## When to use it
+
+Every time two elements stand together in a composition: in a page, a form, a dialog, a card,
+a banner. The relation between them picks the step; the step is never chosen by eye.
+
+Not here: the space inside a control (the padding of a button, the height of an input), which
+the component draws and the density scales; the width of a column or of a dialog, which is the
+domain of the widths.
+
+## What decides it
+
+One question: how do the two elements relate? Side by side in one row; a title and the content
+it names; a label and its control; two fields of one group; the content of a container and the
+row of actions that closes it; two groups of one form; two sections of the page; the content and
+the edge of the container around it; two containers that have a boundary of their own (a border,
+a shadow, a surface). An image is not text: it reaches the edges of its container instead of
+keeping the inset from them (`media-bleed`).
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `relation` | `inline`, `title-content`, `label-control`, `between-fields`, `content-actions`, `between-groups`, `between-sections`, `inset`, `between-containers` | How the two elements relate: side by side in one row, a title and what it names, a label and its control, two fields of a group, the content of a container and the row of actions that closes it, two groups of a section, two sections of the page, the content and the edge of its container, two containers with a boundary of their own. |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use | Serves | Carried by |
+| --- | --- | --- | --- | --- | --- |
+| `inline` | relation: inline | `gap-inline` (300) between elements side by side in one row: the actions of a row, a field and the button beside it |  | intuitive | `--magma-rhythm-inline`, `gap-inline` |
+| `title-content` | relation: title-content | `gap-title-content` (300) between a title and the content it names |  | intuitive | `--magma-rhythm-title-content`, `gap-title-content` |
+| `label-control` | relation: label-control | `gap-label-control` (300) between the label of a field, its control and its message |  | intuitive | `mds-input-field`, `--magma-rhythm-label-control`, `gap-label-control` |
+| `between-fields` | relation: between-fields | `gap-between-fields` (600) between two fields of a form, or two rows of data |  | intuitive | `--magma-rhythm-between-fields`, `gap-between-fields` |
+| `content-actions` | relation: content-actions | `gap-content-actions` (600) between the content of a container and the row of actions that closes it: the footer of a card, the row of a form, the actions of the window of a dialog |  | intuitive | `mds-card`, `--magma-rhythm-content-actions`, `gap-content-actions` |
+| `between-groups` | relation: between-groups | `gap-between-groups` (1000) between two groups of fields of one form (the fieldsets of personal data and of residence) |  | intuitive | `--magma-rhythm-between-groups`, `gap-between-groups` |
+| `between-sections` | relation: between-sections | `gap-between-sections` (1600) between two sections of a page, each with its title |  | intuitive | `--magma-rhythm-between-sections`, `gap-between-sections` |
+| `inset` | relation: inset | `p-inset` (600) inside a container of a part (a card, a banner, a note, a dropdown, the window of a dialog), shared by its regions |  | intuitive | `mds-card`, `mds-banner`, `mds-note`, `mds-dropdown`, `--magma-rhythm-inset`, `p-inset` |
+| `between-containers` | relation: between-containers | `gap-between-containers` (400) between containers with a boundary of their own (the cards of a section, of a grid, of a list of cards) |  | intuitive | `--magma-rhythm-between-containers`, `gap-between-containers` |
+
+No gaps: every combination has a case or is not applicable.
+
+## 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 | Serves | Carried by | Checked by |
+| --- | --- | --- | --- | --- |
+| `step-ratio` | Between relations with no boundary, each step is at least 1.5 times the step it contains: an element stands nearer to what it belongs to than to its neighbour. | intuitive | the guide | review |
+| `shared-inset` | The regions of a container share its inset: the title, the content and the actions of a card stand inside one p-600, their paddings never add up. | intuitive | `mds-card`, `mds-banner` | review |
+| `media-bleed` | The media of a container (the image of a card) reaches the edges of the container it touches and stands from the other regions as they stand from each other: the inset keeps text away from the edge, and an image has no text to keep away. | intuitive | `mds-card` | review |
+| `ladder-only` | Every space between the elements of a composition is the step of its relation: 300, 400 between containers only, 600, 1000, 1600 at the standard density. No other value, no Tailwind t-shirt name (gap-lg). | intuitive, flexible | the guide | review; check.patterns will hold the previews to it (#1189, the previews redone on the rules) |
+
+## 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 |
+| --- | --- |
+| Annulla and Salva side by side at the end of a form | `inline` |
+| The title of a card and its text | `title-content` |
+| The label of a field above its input | `label-control` |
+| The fields of a form in a dialog | `between-fields` |
+| Apri under the data of a card in a list of requests | `content-actions` |
+| The personal data and the residence of a long form, each in its fieldset | `between-groups` |
+| The sections of the page of a record | `between-sections` |
+| The header of a page and the content under it | `between-sections`: the header (the block page-header) is the first section of the page |
+| The content of a card, a banner or the window of a dialog | `inset` |
+| The cards of a list of results | `between-containers` |
+
+## Magma gaps
+
+- `mds-banner` draws its 600 (the inset, the space between its body and its actions) with
+  `--spacing(600)`, not with the roles: a density theme does not move it (`inset`,
+  `content-actions`).
+- The previews of the patterns use other steps (300 between fields, 200 between actions): they
+  are redone on these rules (#1189, "The previews and the Layout of the blocks redone on the
+  rules").
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-29 | The space by relation, in steps of `--spacing`: in a row 200, a title and its content 300, between fields 600, between groups 1000, between sections 1600; each step at least 1.5 times the one it contains (`step-ratio`). | An element stands nearer to what it belongs to than to its neighbour; the ladder starts from the 300 that `mds-input-field` puts between a label and its control. Rejected: the scale of the previews (200, 200, 300, 600, 600), with fields as near as a label to its control. Comment on #1189: https://github.com/magma-design-system/magma/issues/1189#issuecomment-6510058376 |
+| 2026-10-30 | The inset of a container of a part is `p-600`, shared by its regions (`inset`, `shared-inset`). | Banner, note and dropdown already pad 600; a card that pads 400 in each region puts its title 800 from its content, farther than two fields. Rejected: the card of today; `p-400` shared. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6510576013 |
+| 2026-10-30 | In a row 300, not 200: the ladder has four steps, 300, 600, 1000, 1600 (`inline`). | The 200 between the actions of a row came from the previews, and no rule had chosen it; next to an inset of 600 and fields at 600 it was too tight. Rejected: 200; 400, the cap of the 1.5 rule. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6510635910 |
+| 2026-10-30 | The ids: a domain of `kind: foundation`, the file `rhythm`, its relations the cases and its rules the always-true entries, cited `{ id, from: rhythm }`, in short `rhythm/<id>`. | An id is a contract in the format of the patterns, and every decision names the id it decides. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6516863055 |
+| 2026-10-30 | Between containers with a boundary `gap-400`; the 400 joins the ladder for this relation only, and `step-ratio` holds for the relations with no boundary (`between-containers`, `ladder-only`). | A boundary (a border, a shadow, a surface) separates by itself. Chosen live against 600 (as the inset) and 1000 (as between groups). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6517707506 |
+| 2026-10-30 | The carriers: a role token per relation, `--magma-rhythm-<id>`, bridged to Tailwind as `--spacing-<id>` (`gap-<id>`, `p-<id>`); the components paint with the tokens, and a density redefines them. | An agent writes the relation, never its step, and a density or a theme moves every space from one place. Rejected: utilities with a fixed property (`rhythm-inset`); numeric steps with a guide and a lint rule. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6518548217 |
+| 2026-10-31 | The principle each rule serves (`serves`), written with the format (#1196): intuitive for every relation and rule, since the relation reads from the space without being learned, the same in every product; `ladder-only` flexible too, one ladder a density or a theme moves at once. | Foundation asks every decision to say the principle it serves (the Principles page of the docs site). Proposed with the format, to confirm in its review. |
+| 2026-10-31 | The header of a page and the content under it are two sections: `between-sections`, `gap-1600`; the header is the first section of the page. | The header names the whole page, so at the step of the sections it belongs to none of them (`step-ratio`); no new relation. Rejected: `gap-1000`, which puts the header nearer to the first section than that one to the next. Chosen live on a record with sections and on a list (#1210, `page-header`). |
+| 2026-11-02 | The media of a card reaches the edges of the card it touches and stands 300 from the other regions (`media-bleed`); the sides follow the layout the card picks with its container query, never a class or the order of the slots. | The inset keeps text away from the edge, and an image has no text to protect; the title stays 300 from what it names (`step-ratio`); the cards with an image of today stay edge to edge. Rejected: the media inside the inset with a radius of its own (48 px narrower, two nested radii); the media at the edges with the text 600 from it, as from an edge, which puts the title of a card 600 from the image it names. Chosen live on a set of cards at two widths (#1201). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6571508146 |
+| 2026-11-02 | The row of actions that closes a container stands 600 from its content, a relation of its own (`content-actions`), as the row of a form and the actions of the window of a dialog. | The actions act on the whole container, not on its last line: at 300 the footer of a card stood nearer to the last row of data than the rows to each other (`step-ratio`). Rejected: one gap of 300 between every region of a card. Chosen live on cards with rows of data and with an image (#1201). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6571508481 |