@maggioli-design-system/magma-react 2.9.0 → 2.11.0

package/agents/patterns/surfaces.md

@@ -0,0 +1,212 @@
+---
+# A domain of Foundation, the design language (#1189): the format and the commands are in
+# docs/PATTERNS.md, "A domain of Foundation". The check says what is still missing:
+# nx run stencil:check.patterns (after nx run stencil:build).
+id: surfaces
+kind: foundation
+title: Surfaces
+layer: magma
+status: decided
+need: >-
+  Give a boundary only to what space cannot separate, so that a surface on the screen means
+  something: an item of a set, a thing that stays put, a dialog.
+principle: >-
+  The interface is neutral: the page is one canvas, its sections are bare, and a surface rises
+  only for an item of a set, for what stays put, and for the window of a dialog.
+keywords: [surface, card, band, sheet, background, elevation, container, sticky, panel, fill, well, canvas]
+assumptions:
+  - "The surface roles of the palette (surface-default, -raised, -overlay, -muted, -sunken) flip with the mode by themselves."
+components: [mds-card, mds-header, mds-header-bar, mds-status-bar, mds-modal, mds-banner, mds-button]
+related: [rhythm, titles, widths, actions]
+validated-on: []
+
+variables:
+  content:
+    values: [page, section, item, fixed, edit-actions, dialog]
+    means: "What stands on the screen: the page itself; a group of content of one subject (the data of a record, a part of a form, the header of the page); an item of a set of alike things (a related record, a result, a person); something that stays put while the page scrolls (the bar of the application); the row of actions of a form that is the page; the window of a dialog."
+
+cases:
+  - id: canvas
+    content: page
+    where: "`surface-default`, which the base styles already give the body; the content stands on it with no sheet: only the items of a set, what stays put and the window of a dialog rise from it"
+    serves: intuitive
+    carried-by: [--magma-surface-default]
+  - id: section
+    content: section
+    where: "bare: no surface, no border, no inset of its own; its title (`titles/section`) and `gap-between-sections` (1600) set it apart. The header of the page is the first section, in the flow, and scrolls away with the content"
+    serves: intuitive
+    carried-by: [gap-between-sections]
+  - id: card
+    content: item
+    where: "a card, whose boundary tells where one item ends and the next begins: `p-inset` (600) inside, `gap-between-containers` (400) between the cards, its title `titles/part`"
+    use: ["mds-card"]
+    serves: intuitive
+    carried-by: [mds-card, gap-between-containers]
+  - id: band
+    content: fixed
+    where: "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"
+    use: ["mds-header", "mds-header-bar", "mds-status-bar"]
+    serves: intuitive
+    carried-by: [mds-header, mds-header-bar, mds-status-bar]
+  - id: edit-actions
+    content: edit-actions
+    where: "an mds-status-bar docked at the bottom of the window for the whole edit, in the order of `actions/order` (Annulla, then Salva last); the form has no row at its end. A form inside a page, a dialog or a card keeps its row at its end (`actions/place`)"
+    use: ["mds-status-bar", "mds-button variant=dark tone=outline", "mds-button variant=primary tone=strong"]
+    serves: enabling
+    carried-by: [mds-status-bar]
+  - id: dialog
+    content: dialog
+    where: "the window is `mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible` for a form, a choice and a confirmation; only a dialog that announces a state the person did not ask for, with a decision (the deadline of the application), takes the variant of that state, `box`. The window never changes variant when a state arrives, and no dialog is opened to announce a state that has happened (`message-placement`)"
+    use: ["mds-modal", "mds-banner slot=window variant=light tone=box dismissible", "mds-banner slot=window variant=warning tone=box dismissible"]
+    serves: [inclusive, intuitive]
+    carried-by: [mds-banner slot=window variant=light tone=box]
+
+gaps: []
+not-applicable: []
+
+always-true:
+  - id: tints-in-components
+    rule: "surface-muted and surface-sunken live inside components only (zebra rows, wells, tracks, code), never as the background of a section of a page."
+    serves: intuitive
+    checked-by: review
+
+open-choices: []
+
+situations:
+  - { situation: "The page behind a list of requests", case: canvas }
+  - { situation: "The data of a record: its identity, its addresses, its history", case: section }
+  - { situation: "The header of a page under the bar of the application", case: section, note: "in the flow, with no surface: it scrolls away with the content" }
+  - { situation: "The records related to a request, one card each", case: card }
+  - { situation: "The bar of the application, with the logo and the navigation", case: band }
+  - { situation: "The edit of a record, a form about four windows long", case: edit-actions }
+  - { situation: "The dialog New contact, a form", case: dialog }
+  - { situation: "The confirmation of a deletion", case: dialog, note: "the light window too: the red stands on Elimina only (actions/confirm)" }
+  - { situation: "The warning that the session is about to end", case: dialog, note: "a warning window, its row follows actions/banner" }
+---
+
+# Surfaces
+
+**The interface is neutral: the page is one canvas, its sections are bare, and a surface rises only for an item of a set, for what stays put, and for the window of a dialog.**
+
+## When to use it
+
+Every time something on the screen could get a fill, a border or a shadow of its own: a group
+of data, a list of results, the head of the page, a row of actions, a dialog. The domain says
+when a boundary is earned; the components draw it.
+
+Not here: the colours of the surfaces and their flip with the mode (the palette and
+`docs/agents/color.md`), and the surfaces inside a component (a zebra row, the track of a
+switch), which the component draws.
+
+## What decides it
+
+One question: what is it? The page itself; a group of content of one subject; an item of a set
+of alike things, which needs a boundary to tell where it ends; something that stays put while
+the page scrolls, which needs a surface to stand above it; the row of actions of a form that is
+the whole page; the window of a dialog. The rest is space and titles.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `content` | `page`, `section`, `item`, `fixed`, `edit-actions`, `dialog` | What stands on the screen: the page itself; a group of content of one subject (the data of a record, a part of a form, the header of the page); an item of a set of alike things (a related record, a result, a person); something that stays put while the page scrolls (the bar of the application); the row of actions of a form that is the page; the window of a dialog. |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use | Serves | Carried by |
+| --- | --- | --- | --- | --- | --- |
+| `canvas` | content: page | `surface-default`, which the base styles already give the body; the content stands on it with no sheet: only the items of a set, what stays put and the window of a dialog rise from it |  | intuitive | `--magma-surface-default` |
+| `section` | content: section | bare: no surface, no border, no inset of its own; its title (`titles/section`) and `gap-between-sections` (1600) set it apart. The header of the page is the first section, in the flow, and scrolls away with the content |  | intuitive | `gap-between-sections` |
+| `card` | content: item | a card, whose boundary tells where one item ends and the next begins: `p-inset` (600) inside, `gap-between-containers` (400) between the cards, its title `titles/part` | `mds-card` | intuitive | `mds-card`, `gap-between-containers` |
+| `band` | content: fixed | 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 | `mds-header`, `mds-header-bar`, `mds-status-bar` | intuitive | `mds-header`, `mds-header-bar`, `mds-status-bar` |
+| `edit-actions` | content: edit-actions | an mds-status-bar docked at the bottom of the window for the whole edit, in the order of `actions/order` (Annulla, then Salva last); the form has no row at its end. A form inside a page, a dialog or a card keeps its row at its end (`actions/place`) | `mds-status-bar`, `mds-button variant=dark tone=outline`, `mds-button variant=primary tone=strong` | enabling | `mds-status-bar` |
+| `dialog` | content: dialog | the window is `mds-banner slot="window" variant="light" tone="box" dismissible` for a form, a choice and a confirmation; only a dialog that announces a state the person did not ask for, with a decision (the deadline of the application), takes the variant of that state, `box`. The window never changes variant when a state arrives, and no dialog is opened to announce a state that has happened (`message-placement`) | `mds-modal`, `mds-banner slot=window variant=light tone=box dismissible`, `mds-banner slot=window variant=warning tone=box dismissible` | inclusive, intuitive | `mds-banner slot=window variant=light tone=box` |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+The window of a dialog, by what the dialog does:
+
+| Dialog | Window | Row |
+| --- | --- | --- |
+| A form, a choice | `variant="light" tone="box"` | the main action `primary strong`, Annulla `dark outline` |
+| A confirmation | `variant="light" tone="box"` | Elimina `error strong`, Annulla `dark outline`, the focus on Annulla (`actions/confirm`) |
+| A state the person did not ask for, with a decision: the deadline of the application | the variant of the state, `tone="box"` | `actions/banner`: the main action `strong`, the secondary `outline`, in that variant |
+| Its action fails | unchanged | the error right above the row (`actions/failed`) |
+| A state that has happened | no dialog (`message-placement`) | |
+
+What stays put, and the surface its component draws:
+
+| Component | Surface | Where |
+| --- | --- | --- |
+| `mds-header-bar` (in `mds-header`) | `surface-raised`, `shadow-md-sharp` | a band across the top of the page, in the flow and sticky: the page starts under it |
+| `mds-status-bar` | `surface-overlay`, `shadow-md` | docked to the bottom edge, for the actions of an edit |
+| the window of a dialog | the case `dialog` | over the page, which is inert |
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `tints-in-components` | surface-muted and surface-sunken live inside components only (zebra rows, wells, tracks, code), never as the background of a section of a page. | intuitive | the guide | review |
+
+## 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 |
+| --- | --- |
+| The page behind a list of requests | `canvas` |
+| The data of a record: its identity, its addresses, its history | `section` |
+| The header of a page under the bar of the application | `section`: in the flow, with no surface: it scrolls away with the content |
+| The records related to a request, one card each | `card` |
+| The bar of the application, with the logo and the navigation | `band` |
+| The edit of a record, a form about four windows long | `edit-actions` |
+| The dialog New contact, a form | `dialog` |
+| The confirmation of a deletion | `dialog`: the light window too: the red stands on Elimina only (actions/confirm) |
+| The warning that the session is about to end | `dialog`: a warning window, its row follows actions/banner |
+
+## Accessibility
+
+- A `light` window is `role="presentation"` with no live region, so an ordinary dialog does
+  not read itself out; a `warning` window is `role="alert"`, and a screen reader reads its
+  message as well as the name of the dialog. An `error` window would interrupt the screen
+  reader for a question nothing has gone wrong yet in, which is why a confirmation stays
+  `light`.
+- A bar that stays put must never hide the field that has the focus (WCAG 2.4.11, Focus Not
+  Obscured): the page reserves the room of the bar docked at the bottom while it is visible
+  (#1203), and stops a field reached with Shift+Tab under the bar at the top
+  (`scroll-padding-top`), rules of the styles of Magma with no script.
+
+## Magma gaps
+
+- `mds-card` pads each of its regions with `p-400`: it moves to one `p-inset` shared by its
+  regions (#1201, `rhythm/shared-inset`).
+- The example "Custom Window via `window` Slot" of `mds-modal` takes the default variant of
+  the banner, `primary` with `tone="box"`, and Annulla `primary text`: it takes the window of
+  the case `dialog` (#1189, the examples of the components aligned).
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-30 | The window of a dialog that announces no state is `mds-banner slot="window" variant="light" tone="box" dismissible` (`dialog`). | The interface is neutral and the accent is the colour of the actions: with `light` the title and the X take the colour of the text; a `light` banner has no live region. Rejected: `primary` `box`, the example of the guide of `mds-modal`, the title and the X in the accent and the whole dialog a live region. Chosen live (Actions, decision 11). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6524036553 |
+| 2026-10-30 | The confirmation of a deletion is an ordinary dialog: the `light` window, Elimina `error strong` (`dialog`). | A confirmation asks a question, nothing has happened yet: the red stands on the action with the consequence, the form of Carbon and Primer. Rejected: an `error` window, which says something went wrong, interrupts the screen reader (`role="alert"`) and turns Annulla red. Chosen live (Actions, decision 12). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6524149839 |
+| 2026-10-30 | The window never changes variant when a state arrives, and no dialog is opened to announce a state that has happened (`dialog`). | `message-placement` gives a dialog only to a decision and to a deadline of the application: the error of an action stays inside its dialog, a result goes to a toast once it closes (Actions, decision 14). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6524836581 |
+| 2026-10-30 | The dialog that warns that the session is about to end has a `warning` window, its row in `actions/banner` (`dialog`). | It announces a state of the application the person did not ask for, a problem, and its actions address it. Rejected: the `light` window, where a warning nobody asked for looks like any form. Chosen live (Actions, decision 15). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6525103424 |
+| 2026-10-30 | The groups of content of one subject are bare sections; a card is an item of a set of alike things (`section`, `card`). | The interface is neutral, and a boundary is for what space cannot separate; it is the form of `record-detail`, and the card keeps a meaning, a thing that opens. Rejected: every group in a card, where the boundaries multiply and the title of a group falls to the style of a part. Chosen live on the page of a record. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6527700522 |
+| 2026-10-30 | A band exists only where something stays put while the page scrolls, and a component draws it; the header of the page stays in the flow (`band`). | The surface follows from staying put, and the header does not stay: its actions concern the whole set and are taken before scrolling. Measured: the bar alone covers 51 px of a 520 px window, the bar with a page band 189 px, nearly half on a phone. Rejected: the header of the page as a fixed band. Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6527997628 |
+| 2026-10-30 | When a form is the page, its row is an `mds-status-bar` docked at the bottom for the whole edit; a form inside a page, a dialog or a card keeps its row at its end (`edit-actions`). | Whoever corrects one field saves without scrolling, the edit bar of SAP Fiori and Salesforce, and the bar draws its own surface. Rejected: the row at the end of every form, where a correction costs a scroll of four windows. Chosen live; the recommendation changed on the render. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6530822583 |
+| 2026-10-30 | The page is `surface-default` with no sheet (`canvas`); `surface-muted` and `surface-sunken` live inside components only (`tints-in-components`). | A sheet around one subject is a card around one subject, and the cards of a set would stand on their own fill (both `surface-raised`); a tinted section reads as a well, in dark as a hole. Shown live next to the alternatives and confirmed. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6531557197 |
+| 2026-10-31 | The file of the domain, with the window of a dialog as one case whose Parts give the table; "a subtle section" goes from `docs/agents/color.md` and `theming.md`. | The issue of the five domains (#1197). |
+| 2026-11-02 | A field stands a step off its surface: inside a surface that paints `overlay` (the window of a dialog, `mds-banner`, `mds-status-bar`, `mds-dropdown`, `mds-table`) it paints `surface-default`, passed down as `--magma-field-fill` (#1193). | The fill of a field sets it apart from where it stands, the layers of Carbon; the window keeps `overlay`, the meaning of the ladder in `theming.md`, and stands off the dimmed page in dark. Rejected: the window down a step, and the field as an outline only. Review round 1 of #1189. |
+| 2026-11-02 | While an `mds-status-bar` is visible, the styles reserve its room: a box after the body and `scroll-padding-bottom`, the tallest bar for its content plus `rhythm/between-fields`, counted with `:has()` (#1203). | CSS only, no script that measures (the rule of layout); the content of the bar has limits (one line of description, at most three actions), so its tallest is known. A box, not a padding of `html`, which a reset out of any layer would zero. Rejected: a class the page writes, which a page forgets. Review round 1 of #1189. |
+| 2026-11-02 | The bar of the application stands in the flow: `mds-header` is sticky at the top, the page starts under its bar, and the styles stop a field reached with Shift+Tab under it (`scroll-padding-top`, `band`). The room is the bar alone: the floating bar stands its margin lower, and the box of the header lets the clicks through. | The bar was fixed and nothing reserved its room: the title of a page stood 13 px under it instead of `gap-between-sections`, and a field could end under it. Sticky takes the room by itself, with no number to keep in step with its height; a room that followed the appearance would move the page when `appearance-set` changes it on scroll. Rejected: the bar fixed with a padding of the page from the styles, as at the bottom (#1203), a number to keep in step. A page that kept the room by hand gets it twice. Review round 1 of #1189. |

package/agents/patterns/titles.md

@@ -0,0 +1,208 @@
+---
+# A domain of Foundation, the design language (#1189): the format and the commands are in
+# docs/PATTERNS.md, "A domain of Foundation". The check says what is still missing:
+# nx run stencil:check.patterns (after nx run stencil:build).
+id: titles
+kind: foundation
+title: Titles
+layer: magma
+status: decided
+need: >-
+  Tell at a glance what a title names, the whole page, a section of it, a dialog, a part or a
+  group of fields, and keep the outline of the page true for whoever navigates it by headings.
+principle: >-
+  A title takes the style of its role, and its tag from the outline of the page: the two never
+  follow each other.
+keywords: [title, heading, headline, h1, outline, typography, page title, section title, card title, legend, fieldset]
+assumptions:
+  - "A page of an application: a page to read (an article, a commentary) is a case of its own, not looked at."
+  - "The sizes are those of the default theme: a theme moves a role through its tokens, and the markup stays as it is."
+components: [mds-text, mds-modal, mds-banner, mds-accordion-item, mds-push-notification-item, mds-file]
+related: [rhythm, surfaces, page-header]
+validated-on: []
+
+variables:
+  role:
+    values: [page, section, dialog, part, group]
+    means: "What the title names: the whole page, a section of the page, a dialog, a part (a card, a panel, an item of an accordion, a container a component draws), a group of fields of a form."
+
+cases:
+  - id: page
+    role: page
+    where: "the style `h3` (30px), the tag `h1`"
+    use: ["mds-text typography=page tag=h1"]
+    serves: intuitive
+    carried-by: [text-title-page, --text-size-title-page, mds-text typography=page]
+  - id: section
+    role: section
+    where: "the style `h5` (20px), the tag of its place in the outline (`h2` under the page)"
+    use: ["mds-text typography=section tag=h2"]
+    serves: intuitive
+    carried-by: [text-title-section, --text-size-title-section, mds-text typography=section]
+  - id: dialog
+    role: dialog
+    where: "the style `h5`, the headline of the window; the dialog takes its name from aria-label on mds-modal, since the headline is hidden from screen readers. mds-banner draws its headline in h6 today (#1192)"
+    use: ["mds-modal aria-label", "mds-banner slot=window headline"]
+    serves: intuitive
+    carried-by: [text-title-dialog, --text-size-title-dialog, mds-text typography=dialog]
+  - id: part
+    role: part
+    where: "the style `h6` (16px, weight 700), the tag of its place (`h2` under the page, `h3` in a section); the components that draw a part give it already (the headline of mds-banner, mds-push-notification-item, mds-file); an item of an accordion is a part, `h6` by default"
+    use: ["mds-text typography=part", "mds-accordion-item"]
+    serves: intuitive
+    carried-by: [mds-banner, mds-push-notification-item, mds-file, text-title-part, --text-size-title-part, mds-text typography=part]
+  - id: group
+    role: group
+    where: "a `fieldset` with no border and no inset of its own, its title the `legend` in the style `h6`: not a heading of the page; `field-group` on the fieldset draws it, the legend `gap-title-content` (300) from its first field"
+    serves: [inclusive, intuitive]
+    carried-by: [field-group, text-title-group, --text-size-title-group]
+
+gaps: []
+not-applicable: []
+
+always-true:
+  - id: one-h1
+    rule: The title of the page is its h1, and the only one.
+    serves: inclusive
+    checked-by: review
+  - id: tag-is-structure
+    rule: "The tag follows the outline of the page and never skips a level; the style follows the role of the title. With mds-text the tag is written whenever the style is not the level (typography=\"h3\" tag=\"h1\"): left out, the tag follows the style."
+    serves: inclusive
+    checked-by: review
+  - id: by-role
+    rule: "A title takes the style of its role, never a level chosen by eye or to get a smaller size: page h3, section and dialog h5, part and group h6 at the default theme; the styles h1, h2 and h4 have no role in a page of an application."
+    serves: [intuitive, flexible]
+    checked-by: review
+
+open-choices: []
+
+situations:
+  - { situation: "The title of a list of requests", case: page }
+  - { situation: "The sections Data, Documents and History of the page of a record", case: section }
+  - { situation: "The title of the dialog New contact", case: dialog }
+  - { situation: "The title of a card of a related record", case: part }
+  - { situation: "The questions of an accordion under a section Frequent questions", case: part, note: "the section is h5, its items h6: the section stands above them" }
+  - { situation: "Residence, a group of fields of the form of a change of residence", case: group }
+---
+
+# Titles
+
+**A title takes the style of its role, and its tag from the outline of the page: the two never follow each other.**
+
+## When to use it
+
+Every time a title names something in a page of an application: the page itself, a section of
+it, a dialog, a card or a panel, an item of an accordion, a group of fields. The role picks the
+style; the place in the outline picks the tag.
+
+Not here: the text that is not a title (`detail`, `caption`, `label`, the domain of the
+components and of typography), and a page to read, an article or a commentary, which has a
+ladder of its own not looked at yet.
+
+## What decides it
+
+One question: what does the title name? The whole page; a section of the page; a dialog, which
+is the context of the person while it is open; a part, a thing with a boundary of its own; a
+group of fields of a form. The tag is a second, separate question: the level of the title in the
+outline of the page, never skipped.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `role` | `page`, `section`, `dialog`, `part`, `group` | What the title names: the whole page, a section of the page, a dialog, a part (a card, a panel, an item of an accordion, a container a component draws), a group of fields of a form. |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use | Serves | Carried by |
+| --- | --- | --- | --- | --- | --- |
+| `page` | role: page | the style `h3` (30px), the tag `h1` | `mds-text typography=page tag=h1` | intuitive | `text-title-page`, `--text-size-title-page`, `mds-text typography=page` |
+| `section` | role: section | the style `h5` (20px), the tag of its place in the outline (`h2` under the page) | `mds-text typography=section tag=h2` | intuitive | `text-title-section`, `--text-size-title-section`, `mds-text typography=section` |
+| `dialog` | role: dialog | the style `h5`, the headline of the window; the dialog takes its name from aria-label on mds-modal, since the headline is hidden from screen readers. mds-banner draws its headline in h6 today (#1192) | `mds-modal aria-label`, `mds-banner slot=window headline` | intuitive | `text-title-dialog`, `--text-size-title-dialog`, `mds-text typography=dialog` |
+| `part` | role: part | the style `h6` (16px, weight 700), the tag of its place (`h2` under the page, `h3` in a section); the components that draw a part give it already (the headline of mds-banner, mds-push-notification-item, mds-file); an item of an accordion is a part, `h6` by default | `mds-text typography=part`, `mds-accordion-item` | intuitive | `mds-banner`, `mds-push-notification-item`, `mds-file`, `text-title-part`, `--text-size-title-part`, `mds-text typography=part` |
+| `group` | role: group | a `fieldset` with no border and no inset of its own, its title the `legend` in the style `h6`: not a heading of the page; `field-group` on the fieldset draws it, the legend `gap-title-content` (300) from its first field |  | inclusive, intuitive | `field-group`, `text-title-group`, `--text-size-title-group` |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+The ladder at the default theme, and how to write each role:
+
+| Role | Style | Tag | `mds-text` | Without components |
+| --- | --- | --- | --- | --- |
+| `page` | `h3` (30px) | `h1` | `typography="page" tag="h1"` | `text-title-page` |
+| `section` | `h5` (20px) | `h2` | `typography="section" tag="h2"` | `text-title-section` |
+| `dialog` | `h5` | the headline of the window | drawn by `mds-banner` (`h6` until #1192) | `text-title-dialog` |
+| `part` | `h6` (16px, weight 700) | the level of its place | `typography="part"` with the tag of its place | `text-title-part` |
+| `group` | `h6` | `legend` | `field-group` on the `fieldset` | `text-title-group` |
+
+The three levels read apart, 30, 20 and 16px, 1.5 and 1.25 times the level below. A theme moves
+a role through its token (`--text-size-title-<role>` and its modifiers), not through the
+markup; a theme that applies to a part of the page declares the role tokens again there.
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `one-h1` | The title of the page is its h1, and the only one. | inclusive | the guide | review |
+| `tag-is-structure` | The tag follows the outline of the page and never skips a level; the style follows the role of the title. With mds-text the tag is written whenever the style is not the level (typography="h3" tag="h1"): left out, the tag follows the style. | inclusive | the guide | review |
+| `by-role` | A title takes the style of its role, never a level chosen by eye or to get a smaller size: page h3, section and dialog h5, part and group h6 at the default theme; the styles h1, h2 and h4 have no role in a page of an application. | intuitive, flexible | the guide | review |
+
+## 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 |
+| --- | --- |
+| The title of a list of requests | `page` |
+| The sections Data, Documents and History of the page of a record | `section` |
+| The title of the dialog New contact | `dialog` |
+| The title of a card of a related record | `part` |
+| The questions of an accordion under a section Frequent questions | `part`: the section is h5, its items h6: the section stands above them |
+| Residence, a group of fields of the form of a change of residence | `group` |
+
+## Accessibility
+
+- The `h1` is the title of the page and the only one (`one-h1`); the headings never skip a
+  level (`tag-is-structure`), so the outline a screen reader lists is the structure of the page.
+- A group of fields is a `fieldset` with its `legend`: tabbing into one of its fields, a screen
+  reader says the group before the field ("Residence, group. Town, edit"), and two fields
+  with the same label in two groups read apart. A heading inside the `legend` would add the
+  groups to the outline of the page; a heading with no `fieldset` drops the group.
+- The headline of the window of a dialog is hidden from screen readers: the dialog takes its
+  name from `aria-label` on `mds-modal`.
+- The title of an item of an accordion sits inside the button that opens it, so it is not a
+  heading of the page: its `typography` is a style only.
+
+## Magma gaps
+
+- `mds-banner` draws its headline in `h6`, always: the window of a dialog needs `h5`, a choice
+  of the style of the headline (#1192).
+- The examples of `mds-card-header` give 13 titles `h5` with no `tag`, so a card renders an
+  `<h5>` and skips the levels in between; `mds-note` does the same in 4 of its 7: they take
+  `h6` with the tag of their place (#1189, the examples of the components aligned).
+- The items of `mds-accordion` are not in the headings of the page; the Accordion pattern of
+  the WAI-ARIA Authoring Practices wraps each button in a heading with its level. Whether they
+  should be, with a tag of their own apart from the style, is a question of the component.
+- The Typography page of the docs site says the style `h1` is the title of the page: it moves
+  to this ladder with the pull request of the docs site that reads the domains, before this
+  domain is released (#1197).
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-30 | In a page of an application the title of the page is `h3`, a section `h5`, a part `h6`, whatever their tag (`page`, `section`, `part`); the rules of the Foundation they stand on get their ids, `one-h1` and `tag-is-structure`. | `h6` is the style the components that draw a part give their title, so every part has one style; the page takes `h3` as the block `page-header` has it; 30, 20 and 16px read apart, the ladder of the productive applications of Carbon and Primer. Rejected: the Foundation literally (`h1` 48px, `h2`, `h4`), where the head of the page takes the room of the content and a part has two styles; one step per level (`h3`, `h4`, `h5`), where a section and a card read almost alike. Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6525993908 |
+| 2026-10-30 | The title of a dialog is `h5`, the style of a section (`dialog`). | While it is open the dialog is the context of the person, and its title has to stand above the titles it may hold, `h6`; in `h6` it is as tall as the values of the fields. `h5` is the size of the dialog titles of Carbon and Atlassian and of the examples of `mds-modal`. Rejected: `h6`, the dialog as a part. Chosen live on a form and on a confirmation; `mds-banner` gets a choice of the style of its headline (#1192). https://github.com/magma-design-system/magma/issues/1189#issuecomment-6526234532 |
+| 2026-10-30 | A group of fields is a `fieldset` with no border and no inset, its title the `legend` in the style `h6`, not a heading of the page (`group`). | The native grouping of related controls (WCAG technique H71): the group names every field it holds; a heading inside the `legend` adds the groups to the outline, and inside a dialog, whose title is hidden, they open it with no level above. The three forms look the same: one answer, given with its proof (the accessibility tree of Chromium) and confirmed. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6526567780 |
+| 2026-10-30 | The title of an item of an accordion is `h6`, the title of a part (`part`); the default of `mds-accordion-item` moves from `h5`. | An accordion stands in a section, and the title of the section (`h5`) has to stand above its items. Rejected: `h5`, the default of today, where the section and its questions read as one level. Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6526696932 |
+| 2026-10-30 | The titles are carried by role names: `typography="<role>"` on `mds-text`, `text-title-<role>` without components, one token per role, `--text-size-title-<role>` (`by-role`). | The role reads in the code, so a check can tell a section from a dialog though both are `h5`, and a theme moves one role in one place. Rejected: the style of the level written by hand from the table, with a lint on the pairs of tag and style, the form the previews got wrong. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6526876032 |
+| 2026-10-31 | The file of the domain: a case per role, `one-h1` and `tag-is-structure` written here from the Typography page of the docs site, which keeps the reasons around them. | The issue of the five domains (#1197): the rules the agents do not read on the docs site move into the package. |

package/agents/patterns/widths.md

@@ -0,0 +1,202 @@
+---
+# A domain of Foundation, the design language (#1189): the format and the commands are in
+# docs/PATTERNS.md, "A domain of Foundation". The check says what is still missing:
+# nx run stencil:check.patterns (after nx run stencil:build).
+id: widths
+kind: foundation
+title: Widths and alignment
+layer: magma
+status: decided
+need: >-
+  Give text, forms, pages and dialogs a width that keeps them readable at every size of window
+  and of text, and line them up on one edge.
+principle: >-
+  A box is as wide as its role: text and forms at the reading measure, the page in the frame of
+  the bar, a dialog the column of a form plus its inset; whatever is capped starts at the start
+  edge.
+keywords: [width, max-width, measure, line length, column, container, alignment, frame, gutter, half field, dialog width]
+assumptions:
+  - "The text is set at 16 px in Karla; the measures in ch grow with the text when the person enlarges it."
+  - "The rhythm is at the standard density: the dialog adds the inset of its density."
+components: [mds-text, mds-input-field, mds-modal, mds-banner]
+related: [rhythm, actions, surfaces, page-header]
+validated-on: []
+
+variables:
+  box:
+    values: [text, form, short-field, page, collection, dialog]
+    means: "The box to size: text to be read (paragraphs, list items, captions); the column of a form; a field whose answer is short (a street number, a postcode, a tax code, a date); the page; a table or a list; the window of a dialog."
+
+cases:
+  - id: reading
+    box: text
+    where: "the reading measure, `56ch` (65 to 80 characters on a full line in Karla): the reset caps `p`, `li` and `figcaption`, and mds-text caps itself with those tags, so whoever writes a page writes nothing; `max-w-text` elsewhere"
+    serves: inclusive
+    carried-by: [mds-text, --magma-width-reading, max-w-text]
+  - id: form
+    box: form
+    where: "`max-w-form` on the form, the width of the text around it (`56ch`, 532 px at 16 px); its fields take the whole column, and its row of actions stands at the end of the column (`actions/place`)"
+    serves: [inclusive, enabling]
+    carried-by: [max-w-form, --magma-width-form]
+  - id: field
+    box: short-field
+    where: "half the column of its form: the whole mds-input-field (label, control, message), not the control inside it; two short fields of one subject share a row, in reading order, and under a column of `28rem` the halves take the whole column. `field-group` on the group lays them out, reading the property `short` of mds-input-field"
+    use: ["mds-input-field"]
+    serves: [enabling, intuitive]
+    carried-by: [field-group, mds-input-field short]
+  - id: page
+    box: [page, collection]
+    where: "`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"
+    serves: intuitive
+    carried-by: [page-frame, --magma-width-page, --magma-width-page-gutter]
+  - id: dialog
+    box: dialog
+    where: "at most the column of a form plus its inset, `--magma-width-dialog` (580 px at 16 px), one width for every dialog, confirmations included; on a phone the window takes the screen, as mds-modal does under 480 px; mds-modal gives it to its window"
+    use: ["mds-modal", "mds-banner slot=window"]
+    serves: [enabling, intuitive]
+    carried-by: [--magma-width-dialog]
+
+gaps: []
+not-applicable: []
+
+always-true:
+  - id: start-edge
+    rule: "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."
+    serves: intuitive
+    checked-by: review
+  - id: by-role
+    rule: "A width is written by its role, never by its value: max-w-form, page-frame, short with field-group, the default of mds-modal; never container-sm, a max-w of a value of your own, or the threshold of the halves and the sum of the dialog copied by hand."
+    serves: [intuitive, flexible]
+    checked-by: review
+
+open-choices: []
+
+situations:
+  - { situation: "The description of a service, paragraphs to read", case: reading }
+  - { situation: "The form Report a problem under its introduction", case: form }
+  - { situation: "The street number and the postcode of an address", case: field }
+  - { situation: "The tax code and the date of birth of a person", case: field }
+  - { situation: "A list of requests in a table of six columns", case: page, note: "the table takes the whole frame" }
+  - { situation: "The page of a record in a window 1920 px wide", case: page, note: "the frame stops at 1280 px, the sides stay empty" }
+  - { situation: "The dialog New contact, a form with two short fields", case: dialog }
+  - { situation: "The confirmation of a deletion", case: dialog, note: "the same width as every dialog" }
+---
+
+# Widths and alignment
+
+**A box is as wide as its role: text and forms at the reading measure, the page in the frame of the bar, a dialog the column of a form plus its inset; whatever is capped starts at the start edge.**
+
+## When to use it
+
+Every time a box could run as wide as its container: a paragraph, a form, a short field, the
+content of a page, a table, the window of a dialog. The role picks the width; the edge is
+always the start edge of the frame.
+
+Not here: the space between the elements (the rhythm), and the width of a column of a table,
+which the table sets from its content.
+
+## What decides it
+
+One question: what is the box? Text to be read; the column of a form; a field whose answer has
+a known, short length; the page; a table or a list, which use the whole frame; the window of a
+dialog. A form in a dialog is the same column as a form in a page, so it moves between the two
+without changing shape.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `box` | `text`, `form`, `short-field`, `page`, `collection`, `dialog` | The box to size: text to be read (paragraphs, list items, captions); the column of a form; a field whose answer is short (a street number, a postcode, a tax code, a date); the page; a table or a list; the window of a dialog. |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use | Serves | Carried by |
+| --- | --- | --- | --- | --- | --- |
+| `reading` | box: text | the reading measure, `56ch` (65 to 80 characters on a full line in Karla): the reset caps `p`, `li` and `figcaption`, and mds-text caps itself with those tags, so whoever writes a page writes nothing; `max-w-text` elsewhere |  | inclusive | `mds-text`, `--magma-width-reading`, `max-w-text` |
+| `form` | box: form | `max-w-form` on the form, the width of the text around it (`56ch`, 532 px at 16 px); its fields take the whole column, and its row of actions stands at the end of the column (`actions/place`) |  | inclusive, enabling | `max-w-form`, `--magma-width-form` |
+| `field` | box: short-field | half the column of its form: the whole mds-input-field (label, control, message), not the control inside it; two short fields of one subject share a row, in reading order, and under a column of `28rem` the halves take the whole column. `field-group` on the group lays them out, reading the property `short` of mds-input-field | `mds-input-field` | enabling, intuitive | `field-group`, `mds-input-field short` |
+| `page` | box: page or collection | `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 |  | intuitive | `page-frame`, `--magma-width-page`, `--magma-width-page-gutter` |
+| `dialog` | box: dialog | at most the column of a form plus its inset, `--magma-width-dialog` (580 px at 16 px), one width for every dialog, confirmations included; on a phone the window takes the screen, as mds-modal does under 480 px; mds-modal gives it to its window | `mds-modal`, `mds-banner slot=window` | enabling, intuitive | `--magma-width-dialog` |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+The widths at 16 px, and what an agent writes:
+
+| Role | Width | Writes | Token |
+| --- | --- | --- | --- |
+| `reading` | `56ch`, 532 px | nothing (the reset, `mds-text`); `max-w-text` elsewhere | `--magma-width-reading` |
+| `form` | `56ch`, the column of the text | `max-w-form` on the form | `--magma-width-form` |
+| `field` | half the column; the whole column under `28rem` | `short` on `mds-input-field`, `field-group` on the group | none: `28rem` lives in the utility |
+| `page` | at most 1280 px, gutter `600` outside | `page-frame` on the page | `--magma-width-page`, `--magma-width-page-gutter` |
+| `dialog` | `56ch` plus twice the inset, 580 px | nothing: `mds-modal` carries it | `--magma-width-dialog` |
+
+Why `56ch`: the zero of Karla is 9.5 px at 16 px, wider than an average character, so a measure
+in `ch` holds fewer characters than its number says. `56ch` is the one value whose full lines
+stay inside 60 to 80 characters, under the 80 of WCAG 1.4.8.
+
+Why `28rem`: a half has to hold the longest short answer `mds-input` knows, the tax code (16
+characters, a control of 203 px); two halves and the gap need about 430 px.
+
+A theme moves a role through its token: a theme with the page at 1024 px and the reading
+measure at `65ch` moves the frame, the form and the dialog with them, and the markup stays.
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `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. | intuitive | the guide | review |
+| `by-role` | A width is written by its role, never by its value: max-w-form, page-frame, short with field-group, the default of mds-modal; never container-sm, a max-w of a value of your own, or the threshold of the halves and the sum of the dialog copied by hand. | intuitive, flexible | the guide | review |
+
+## 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 |
+| --- | --- |
+| The description of a service, paragraphs to read | `reading` |
+| The form Report a problem under its introduction | `form` |
+| The street number and the postcode of an address | `field` |
+| The tax code and the date of birth of a person | `field` |
+| A list of requests in a table of six columns | `page`: the table takes the whole frame |
+| The page of a record in a window 1920 px wide | `page`: the frame stops at 1280 px, the sides stay empty |
+| The dialog New contact, a form with two short fields | `dialog` |
+| The confirmation of a deletion | `dialog`: the same width as every dialog |
+
+## Accessibility
+
+- The measures are in `ch`, so text and forms grow with the text when the person enlarges it,
+  and the lines stay inside the 80 characters of WCAG 1.4.8.
+- The halves of short fields take the whole column under `28rem`, so a tax code is never cut on
+  a phone, and the message of a half stays on one line.
+
+## Magma gaps
+
+- `mds-banner` keeps its close button in a column beside the whole body, so in a window the
+  fields end before the row of actions; with the X in the title row (`actions/dismiss`) the body
+  of the window is the column of a form exactly.
+- In a narrow box (a dialog on a phone) `mds-banner` lets its content shrink to its text, so a
+  short form ends up narrower than the window. Kept aside.
+- The previews of the patterns size their forms with `container-sm` (384 px): they move to
+  `max-w-form` (#1189, the previews redone on the rules).
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-30 | Text to be read stops at `max-w-text`, and `--spacing-text` goes from `75ch` to `56ch` (`reading`). | The Foundation already writes the rule, about 60 to 80 characters; `56ch` is the value that keeps it, measured on the build: 65 to 80 characters on a full line in Karla, average 72. Rejected: `75ch`, 86 to 104 characters, over the rule and over WCAG 1.4.8. One answer, shown live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6531852144 |
+| 2026-10-30 | The column of a form is the reading measure; its fields take the whole column, its row the end of it (`form`). | The messages under the fields are text to read and stay on one line; text and form end on one edge; in `ch` the column grows with the text. Rejected: `container-sm` (384 px), the width the widgets used without deciding it, where 2 of 3 messages wrapped. Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6532026182 |
+| 2026-10-30 | A short field is half the column, the whole `mds-input-field`; two of one subject share a row; under `28rem` the halves take the whole column (`field`). | Two widths only, so the form keeps one grid; whoever writes chooses "short" and counts no characters; the form is shorter (654 px against 837). Rejected: the control as wide as its answer (GOV.UK), one edge per field; every control on the whole column; a short field beside a free one, whose error took 5 lines. The proposal of the maintainer, chosen live over the first recommendation. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6532384527 |
+| 2026-10-30 | A page stands in a frame of at most 1280 px, centred, with a gutter of `600`, the column of `mds-header-bar`; everything starts at its start edge, and tables and lists take the whole frame (`page`, `start-edge`). | The bar carries it already: the name of the application, the title and the table start on one edge at every width. Rejected: page and bar at the full width of the window, rows across the whole screen and text against the left edge. Chosen live at 1024, 1440 and 1920 px. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6532525783 |
+| 2026-10-30 | The window of a dialog is the column of a form plus its inset, 580 px, one width for every dialog (`dialog`). | A form moves between a page and a dialog without changing shape: the halves stay side by side, the messages on one line. Rejected: `container-md` (448 px), whose body falls under `28rem`, so a form takes its phone shape. Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6532648084 |
+| 2026-10-30 | The widths are carried by roles: `--magma-width-*`, `max-w-form`, `page-frame`, `short` with `field-group`, the default of `mds-modal` (`by-role`). | The role reads in the code, a check can hold it, a theme moves it in one place, and the threshold and the sum of the dialog live in one place instead of in every product (the previews copied a width and got 384 px). Rejected: the values by hand, the same render with nothing a check can tell apart; the pair as a wrapper, where "short" is not on the field. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6533809808 |
+| 2026-10-31 | The file of the domain; tables and lists are a value of their own in the case `page`. | The issue of the five domains (#1197); `widths/page` names tables and lists among its answers. |