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

package/agents/patterns/density.md

@@ -0,0 +1,236 @@
+---
+# 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: density
+kind: foundation
+title: Density
+layer: magma
+status: decided
+need: >-
+  Fit more or less on a screen without changing how its parts relate: more for a product that
+  shows a lot at once, less for a person who needs more room to point.
+principle: >-
+  A density is one factor on every unit: the spaces, the controls and the markers shrink or grow
+  together, and the type stays as it is.
+keywords: [density, compact, standard, comfortable, dense, roomy, unit, target size, data grid density]
+assumptions:
+  - "The spaces, the controls and the markers are measured in the three units of the dimension axis of the themes (#691): container, control, marker."
+  - "The type is not part of a density: a person who needs larger text enlarges the text."
+components: []
+related: [rhythm]
+validated-on: []
+
+variables:
+  level:
+    values: [compact, standard, comfortable]
+    means: "The density in force where the element stands, as the theme of the product, a region of the page or the person chose it (scope, region)."
+
+cases:
+  - id: compact
+    level: compact
+    where: "every unit at 3px, the factor 3/4: between fields 450, a button (size md) 675 high, an input (size lg) 1050, a checkbox 450; until the units ship (#691) no product has it, and nothing writes it by hand"
+    serves: flexible
+    carried-by-planned: [--magma-unit-container, --magma-unit-control, --magma-unit-marker, mds-pref-density]
+  - id: standard
+    level: standard
+    where: "every unit at 4px, the default: between fields 600, a button (size md) 900 high, an input (size lg) 1200, a checkbox 600; the values of today"
+    serves: flexible
+    carried-by-planned: [--magma-unit-container, --magma-unit-control, --magma-unit-marker]
+  - id: comfortable
+    level: comfortable
+    where: "every unit at 5px, the factor 5/4: between fields 750, a button (size md) 1125 high, an input (size lg) 1350, a checkbox 750; the level where the default button reaches 1100, the target of WCAG 2.5.5 (AAA); until the units ship (#691) no product has it"
+    serves: [inclusive, flexible]
+    carried-by-planned: [--magma-unit-container, --magma-unit-control, --magma-unit-marker, mds-pref-density]
+
+gaps: []
+not-applicable: []
+
+always-true:
+  - id: scale
+    rule: "A density shrinks or grows every relation of the rhythm by one factor, so the proportions stay those of the standard density and rhythm/step-ratio holds at every level: never one step down per relation, never a table of its own."
+    serves: [intuitive, flexible]
+    checked-by: review
+  - id: controls
+    rule: "The controls (buttons, fields) follow the factor of the rhythm. A field is one line of text plus its padding, and only the padding follows: the text keeps its size."
+    serves: [intuitive, flexible]
+    checked-by: review
+  - id: markers
+    rule: "The markers (a checkbox, a switch, a badge, the space between a marker and its label) follow the same factor, with no exception; a marker stays centred on the first line of its label at every level."
+    serves: [inclusive, intuitive]
+    checked-by: review
+  - id: unit
+    rule: "The rhythm is measured in the container unit: each --magma-rhythm-<id> is that unit times its step (300 = 3 units). The unit is a literal, so a product that changes --spacing does not move the rhythm. Wherever a density applies, the rhythm tokens are declared again next to the units: a custom property resolves where it is declared."
+    serves: flexible
+    checked-by: review
+  - id: levels
+    rule: "Three levels, with symmetric units: compact (3px), standard (4px, the default), comfortable (5px). No other level; the names are not sm, md and lg, which belong to the size of a component."
+    serves: [inclusive, flexible]
+    checked-by: review
+  - id: scope
+    rule: "Three layers choose the density, in the order system < theme < person: the theme of the product for all of it, a region for a part of the page (data-density on any element), the person with mds-pref-density (pref-density-<level> on html)."
+    serves: [inclusive, flexible]
+    checked-by: review
+  - id: region
+    rule: "An explicit choice of the person wins over the regions: mds-pref-density takes auto (the default, the density of the product with its regions), compact, standard or comfortable, and a level the person chose applies everywhere, a compact region included."
+    serves: inclusive
+    checked-by: review
+  - id: dense-targets
+    rule: "At compact a checkbox is 450, under the 600 of WCAG 2.5.8: it passes by the spacing exception while the centres of two neighbouring checkboxes stand at least 600 apart. A list or a table that selects its rows with bare checkboxes keeps its rows at least 600 high."
+    serves: inclusive
+    checked-by: review
+
+open-choices:
+  - { id: product-density, default: "standard", may: "set compact or comfortable for the whole product in its theme" }
+  - { id: region-density, default: "the density of the product", may: "mark a part of the page (a dense table, a side bar) with data-density" }
+
+situations:
+  - { situation: "A management application whose people work through long tables all day", case: compact, note: "the theme of the product, or data-density on the table only" }
+  - { situation: "A form of a public service a citizen fills in once", case: standard }
+  - { situation: "A person who points with difficulty chooses more room in the preferences", case: comfortable, note: "it applies everywhere, the compact regions included (region)" }
+---
+
+# Density
+
+**A density is one factor on every unit: the spaces, the controls and the markers shrink or grow together, and the type stays as it is.**
+
+## When to use it
+
+When a product, a part of a page or a person needs more or less on the screen: a management
+application whose people scan long tables all day, a dense table inside an ordinary page, a
+person who points with difficulty and needs larger targets. Density settles what changes and
+who chooses it; the relations themselves are the domain of the rhythm, which a density scales
+and never redefines.
+
+Not here: the size of one component (`size`, a choice of the composition, not of the
+density), and the size of the text, which a density never touches.
+
+## What decides it
+
+One question: which level is in force where the element stands. The product sets it in its
+theme, a region of the page may set its own, and the person may override both from the
+preferences. The level gives the unit; everything measured in the units follows by itself.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `level` | `compact`, `standard`, `comfortable` | The density in force where the element stands, as the theme of the product, a region of the page or the person chose it (scope, region). |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use | Serves | Carried by |
+| --- | --- | --- | --- | --- | --- |
+| `compact` | level: compact | every unit at 3px, the factor 3/4: between fields 450, a button (size md) 675 high, an input (size lg) 1050, a checkbox 450; until the units ship (#691) no product has it, and nothing writes it by hand |  | flexible | planned: --magma-unit-container, --magma-unit-control, --magma-unit-marker, mds-pref-density |
+| `standard` | level: standard | every unit at 4px, the default: between fields 600, a button (size md) 900 high, an input (size lg) 1200, a checkbox 600; the values of today |  | flexible | planned: --magma-unit-container, --magma-unit-control, --magma-unit-marker |
+| `comfortable` | level: comfortable | every unit at 5px, the factor 5/4: between fields 750, a button (size md) 1125 high, an input (size lg) 1350, a checkbox 750; the level where the default button reaches 1100, the target of WCAG 2.5.5 (AAA); until the units ship (#691) no product has it |  | inclusive, flexible | planned: --magma-unit-container, --magma-unit-control, --magma-unit-marker, mds-pref-density |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+The three levels, as measured on the built components (`standard`) and in the live
+comparisons (the other two):
+
+| | `compact` | `standard` | `comfortable` |
+| --- | --- | --- | --- |
+| Unit | 3px | 4px | 5px |
+| Factor | 3/4 | 1 | 5/4 |
+| `rhythm/inline`, `title-content`, `label-control` | 225 | 300 | 375 |
+| `rhythm/between-containers` | 300 | 400 | 500 |
+| `rhythm/between-fields`, `rhythm/inset` | 450 | 600 | 750 |
+| `rhythm/between-groups` | 750 | 1000 | 1250 |
+| `rhythm/between-sections` | 1200 | 1600 | 2000 |
+| `mds-button` (size `md`), height | 675 | 900 | 1125 |
+| `mds-input` (size `lg`), height | 1050 | 1200 | 1350 |
+| Checkbox icon | 450 | 600 | 750 |
+| Switch (size `md`), height x width | 600 x 1050 | 800 x 1400 | 1000 x 1750 |
+| Badge padding, block / inline | 75 / 150 | 100 / 200 | 125 / 250 |
+| Between a marker and its label | 150 | 200 | 250 |
+
+The steps of `compact` and `comfortable` are not steps of the sizing scale (225, 450, 750):
+that is expected, a space is measured in the unit of its density (`rhythm/ladder-only`).
+
+Who chooses, and how:
+
+| Layer | Who | How |
+| --- | --- | --- |
+| Theme | the product, for all of it | a named theme sets the three units in its block |
+| Region | the product, for a part of the page | `data-density="compact"`, `"standard"` or `"comfortable"` on any element |
+| Preference | the person, for themself | mds-pref-density, next to the other `mds-pref-*`, publishes `pref-density-<level>` on `html`; `auto` keeps the product's density |
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `scale` | A density shrinks or grows every relation of the rhythm by one factor, so the proportions stay those of the standard density and rhythm/step-ratio holds at every level: never one step down per relation, never a table of its own. | intuitive, flexible | the guide | review |
+| `controls` | The controls (buttons, fields) follow the factor of the rhythm. A field is one line of text plus its padding, and only the padding follows: the text keeps its size. | intuitive, flexible | the guide | review |
+| `markers` | The markers (a checkbox, a switch, a badge, the space between a marker and its label) follow the same factor, with no exception; a marker stays centred on the first line of its label at every level. | inclusive, intuitive | the guide | review |
+| `unit` | The rhythm is measured in the container unit: each --magma-rhythm-<id> is that unit times its step (300 = 3 units). The unit is a literal, so a product that changes --spacing does not move the rhythm. Wherever a density applies, the rhythm tokens are declared again next to the units: a custom property resolves where it is declared. | flexible | the guide | review |
+| `levels` | Three levels, with symmetric units: compact (3px), standard (4px, the default), comfortable (5px). No other level; the names are not sm, md and lg, which belong to the size of a component. | inclusive, flexible | the guide | review |
+| `scope` | Three layers choose the density, in the order system < theme < person: the theme of the product for all of it, a region for a part of the page (data-density on any element), the person with mds-pref-density (pref-density-<level> on html). | inclusive, flexible | the guide | review |
+| `region` | An explicit choice of the person wins over the regions: mds-pref-density takes auto (the default, the density of the product with its regions), compact, standard or comfortable, and a level the person chose applies everywhere, a compact region included. | inclusive | the guide | review |
+| `dense-targets` | At compact a checkbox is 450, under the 600 of WCAG 2.5.8: it passes by the spacing exception while the centres of two neighbouring checkboxes stand at least 600 apart. A list or a table that selects its rows with bare checkboxes keeps its rows at least 600 high. | inclusive | the guide | 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 |
+| --- | --- | --- |
+| `product-density` | standard | set compact or comfortable for the whole product in its theme |
+| `region-density` | the density of the product | mark a part of the page (a dense table, a side bar) with data-density |
+
+## Situations
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+Situations every application has, each with its case: they give the examples, the texts and the keywords. The situations of a product's own domain go in its layer.
+
+| Situation | Case |
+| --- | --- |
+| A management application whose people work through long tables all day | `compact`: the theme of the product, or data-density on the table only |
+| A form of a public service a citizen fills in once | `standard` |
+| A person who points with difficulty chooses more room in the preferences | `comfortable`: it applies everywhere, the compact regions included (region) |
+
+## Accessibility
+
+- `comfortable` exists for the people who point with difficulty: the default button reaches
+  1100, the target of WCAG 2.5.5 (AAA), and the smallest targets of the screen grow with it.
+- The choice of the person wins over the product (`region`): a compact table becomes
+  comfortable for whoever asked for room.
+- At `compact` the checkbox is under the 600 of WCAG 2.5.8 and passes by its spacing
+  exception (`dense-targets`): in a compact form two checkboxes stand 1050 apart (a line of
+  label plus 450).
+
+## Magma gaps
+
+- The units are not in Magma yet: --magma-unit-container, --magma-unit-control and
+  --magma-unit-marker, the rhythm tokens written as multiples of the container unit, the
+  levels on `:root`, `[data-density]` and `:root.pref-density-<level> [data-density]`, and
+  mds-pref-density (#691). Until they ship every product is `standard`, and a denser screen
+  is not written by hand: no private variable of a component, no other step of the rhythm.
+- The components measure their own sizes in pixels or in steps of `--spacing`: the icon of the
+  checkbox, the knob and the padding of the switch, the padding of the badge, the padding of
+  the controls become multiples of their unit (#691).
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-30 | A denser screen shrinks every relation of the rhythm by one factor, 3/4 for the compact density (`scale`). | The proportions stay identical, so the relations read the same at every density and `rhythm/step-ratio` holds with nothing to maintain; a further density is one more factor, not one more table, the mechanism #691 drafts for the components. Rejected: one step down for each relation (200, 300, 400, 600, 1000), whose proportions change from one relation to the next. Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6518870918 |
+| 2026-10-30 | The controls shrink by the same factor as the rhythm (`controls`). | The dense screen is the same screen in proportion, one number for the rhythm and the controls; the compact button (675) lands next to `size="sm"` (700) and stays above 600, the minimum target of WCAG 2.5.8. Rejected: 7/8 for the controls (two numbers for one density); the controls left as they are (the fields dominate and the density gains little). Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6518991256 |
+| 2026-10-30 | The rhythm is measured in the container unit of #691; a density is one factor on every unit (`unit`). | The container unit is already the room a container leaves around its content, which is `rhythm/inset`; the groups of #691 are roles of the components, and the rhythm is not one. Rejected: a unit of its own for the rhythm, which would let a theme widen the cards without widening the spaces between the fields, a case nobody has. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6519103714 |
+| 2026-10-30 | Three layers choose the density: the theme, the preference of the person (mds-pref-density), a region (`data-density`), in the order system < theme < person (`scope`). | Each layer reuses a mechanism Magma has (the named themes, `mds-pref-contrast`, `data-corner-shape`), and the units are inherited custom properties, so the components follow without being wired one by one. Rejected: the theme alone; theme and region with no preference; theme and preference with no region. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6519166303 |
+| 2026-10-30 | Three levels with symmetric units: `compact` 3px, `standard` 4px, `comfortable` 5px (`levels`). | `comfortable` has a reason of its own, the default button at 1100, the target of WCAG 2.5.5; the names are those of the `density` of MUI DataGrid, not the `sm`/`md`/`lg` of the size of a component. Rejected: `comfortable` at 4.5px, whose button stays under the AAA target; two levels, where a preference could only tighten. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6519246975 |
+| 2026-10-30 | An explicit choice of the person wins over the regions: mds-pref-density is `auto` by default, and a level the person chose applies to the regions too (`region`). | The precedence system < theme < person carried through: a region is a decision of the product, as the theme is. Who chose `comfortable` because pointing is hard gets it where the targets are densest. Rejected: the region wins inside itself, the choice of the person included. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6519287396 |
+| 2026-10-30 | The markers follow the density like the rhythm and the controls (`markers`); at `compact` the checkbox passes WCAG 2.5.8 by its spacing exception, and a list that selects its rows with bare checkboxes keeps its rows at least 600 high (`dense-targets`). | One factor on every unit, with no exception: the switch stays lower than the button at every level, and at `comfortable` the smallest targets grow too, the reason that level exists. Rejected: the markers unchanged at every density, where the compact switch stands taller than the button and the density has two rules. Chosen live. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6519554134 |
+| 2026-10-31 | The file of the domain, with the levels as its cases, each carried by the units of #691 once they ship, and the rest as always-true rules; `product-density` and `region-density` are the open choices of a product layer. | The format of #1196 and the issue of the five domains (#1197); #1189 names density as the first open choice of a product layer. |

package/agents/patterns/empty-state.md

@@ -0,0 +1,201 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: empty-state
+kind: pattern
+title: An empty part of the page
+group: messages-and-states
+layer: magma
+status: decided
+need: >-
+  The person reaches a part of the page with nothing in it, and must understand why and what
+  to do next.
+principle: An empty part says why it is empty and what comes next, never in a warning tone.
+keywords: [empty state, empty list, no results, nothing found, no items yet, not found, all done, zero data]
+not-for:
+  - need: a part that could not be loaded
+    use: error-recovery
+  - need: a part that is still loading
+    use: loading
+  - need: what a role is not allowed to see
+    use: permissions
+  - need: where the outcome of an action is told
+    use: message-placement
+assumptions:
+  - The application knows why the part is empty (nothing yet, nothing matches, all done, does not exist).
+high-stakes: false
+components: [mds-zero, mds-text, mds-button, mds-img]
+related: [list-with-filters, record-detail, loading, error-recovery, item-list, app-shell]
+validated-on: []
+
+variables:
+  cause: { values: [first-use, filtered, cleared, gone], means: "first-use: nothing yet; filtered: nothing matches the search or the filters; cleared: all handled; gone: the thing asked for does not exist" }
+  can-add: { values: ["yes", "no"], means: "can this person add what is missing" }
+  room: { values: [panel, line], means: "is there room for a panel, or only for a line (a menu, a dropdown, a cell)" }
+
+cases:
+  - { id: add-the-first, cause: first-use, can-add: "yes", room: panel, where: "a panel that says what is missing and what it is for, with the action that adds the first one; an illustration may welcome", use: ["mds-zero", "mds-button slot=action"] }
+  - { id: filled-by-others, cause: first-use, can-add: "no", room: panel, where: "a panel that says who or what fills the part, and when; no button", use: ["mds-zero"] }
+  - { id: clear-filters, cause: filtered, room: panel, where: "a panel that says nothing matches, with Clear filters only; the summary of the results says it too", use: ["mds-zero", "mds-button slot=action"] }
+  - { id: all-done, cause: cleared, room: panel, where: "a panel that says all is done and what will come here; no button", use: ["mds-zero"] }
+  - { id: not-found, cause: gone, room: panel, where: "the panel takes the place of the page: its title is the h1, its action leads to the list", use: ["mds-zero", "mds-button slot=action href"] }
+  - { id: one-line, cause: [first-use, filtered, cleared], room: line, where: "one line of text where the items would be; the control that opened it is the way out", use: ["mds-text"] }
+gaps: []
+not-applicable:
+  - { cause: gone, room: line, why: "a thing that does not exist is reached by its address: the whole page" }
+
+always-true:
+  - id: says-what-next
+    rule: The panel says what to do next, or, when the person has nothing to do, who or what fills the part.
+    checked-by: review
+  - id: no-warning-tone
+    rule: Nothing inside the panel has a warning or error tone.
+    checked-by: review
+    lint-planned: magma/no-warning-in-zero
+  - id: not-an-error
+    rule: A part that failed to load is an error, never an empty state.
+    checked-by: review
+  - id: one-cause-one-action
+    rule: "The action answers the cause: Clear filters for a search, never Create."
+    checked-by: review
+  - id: illustration-on-first-use
+    rule: An illustration only on first use; never on a search, an all-done or a missing page, where the person is working.
+    checked-by: review
+
+situations:
+  - { situation: A new account opens its list of projects, case: add-the-first }
+  - { situation: "A reader opens the documents of a case, which the office has not added yet", case: filled-by-others }
+  - { situation: A search on a list finds nothing, case: clear-filters }
+  - { situation: "An operator searches for a contact by name, finds none, and may create contacts", case: clear-filters, note: "Create stays in the header of the page" }
+  - { situation: "The list of tasks to do is empty: all done", case: all-done }
+  - { situation: An address leads to a request that was deleted, case: not-found }
+  - { situation: A combobox finds no option for the text typed, case: one-line }
+---
+
+# An empty part of the page
+
+**An empty part says why it is empty and what comes next, never in a warning tone.**
+
+## When to use it
+
+A list, a section or a page with nothing to show, and the reason is known: nothing yet,
+nothing matches, all handled, or the thing asked for does not exist. Not a part that failed to
+load (`error-recovery`): no results is not an error. Not a part that is still loading
+(`loading`). Not what a role may not see (`permissions`).
+
+## What decides it
+
+Three questions: why the part is empty, whether this person can add what is missing, and
+whether there is room for a panel or only for a line.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `cause` | `first-use`, `filtered`, `cleared`, `gone` | first-use: nothing yet; filtered: nothing matches the search or the filters; cleared: all handled; gone: the thing asked for does not exist |
+| `can-add` | `yes`, `no` | can this person add what is missing |
+| `room` | `panel`, `line` | is there room for a panel, or only for a line (a menu, a dropdown, a cell) |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use |
+| --- | --- | --- | --- |
+| `add-the-first` | cause: first-use; can-add: yes; room: panel | a panel that says what is missing and what it is for, with the action that adds the first one; an illustration may welcome | `mds-zero`, `mds-button slot=action` |
+| `filled-by-others` | cause: first-use; can-add: no; room: panel | a panel that says who or what fills the part, and when; no button | `mds-zero` |
+| `clear-filters` | cause: filtered; room: panel | a panel that says nothing matches, with Clear filters only; the summary of the results says it too | `mds-zero`, `mds-button slot=action` |
+| `all-done` | cause: cleared; room: panel | a panel that says all is done and what will come here; no button | `mds-zero` |
+| `not-found` | cause: gone; room: panel | the panel takes the place of the page: its title is the h1, its action leads to the list | `mds-zero`, `mds-button slot=action href` |
+| `one-line` | cause: first-use or filtered or cleared; room: line | one line of text where the items would be; the control that opened it is the way out | `mds-text` |
+
+Not applicable:
+
+| When | Why |
+| --- | --- |
+| cause: gone; room: line | a thing that does not exist is reached by its address: the whole page |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+The panel, `mds-zero`:
+
+- the default slot: an illustration, only in `add-the-first` and optional; Magma has none to
+  give, the product brings its own;
+- `slot="content"`: a title that says what is missing ("No requests match"), with the heading
+  level of its place (`h1` when it takes the place of the page), then one sentence with why and
+  what comes next;
+- `slot="action"`: one `mds-button`, when the person has something to do; none in
+  `filled-by-others` and `all-done`.
+
+The line: one `mds-text` in the place of the items, in the muted foreground.
+
+## Behaviour over time
+
+- While a new search loads, the results that were there stay: the empty state does not flash
+  (`loading`).
+- After Clear filters, the panel is gone with its button: the focus goes to the title of the
+  list, as after any action whose control is gone (`record-detail`, `confirm-action`).
+
+## 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 |
+| --- | --- | --- |
+| `says-what-next` | The panel says what to do next, or, when the person has nothing to do, who or what fills the part. | review |
+| `no-warning-tone` | Nothing inside the panel has a warning or error tone. | review; lint `magma/no-warning-in-zero` to write |
+| `not-an-error` | A part that failed to load is an error, never an empty state. | review |
+| `one-cause-one-action` | The action answers the cause: Clear filters for a search, never Create. | review |
+| `illustration-on-first-use` | An illustration only on first use; never on a search, an all-done or a missing page, where the person is working. | 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 |
+| --- | --- |
+| A new account opens its list of projects | `add-the-first` |
+| A reader opens the documents of a case, which the office has not added yet | `filled-by-others` |
+| A search on a list finds nothing | `clear-filters` |
+| An operator searches for a contact by name, finds none, and may create contacts | `clear-filters`: Create stays in the header of the page |
+| The list of tasks to do is empty: all done | `all-done` |
+| An address leads to a request that was deleted | `not-found` |
+| A combobox finds no option for the text typed | `one-line` |
+
+## Accessibility
+
+- The summary of the results is a status region: when a search finds nothing, screen readers
+  read out "No requests match" while the focus stays on the field (`list-with-filters`).
+- An illustration is decorative: its alternative text is empty, the message is in the text.
+
+## Content
+
+- What is missing, then why, then what comes next: "No requests match. Try other words, or
+  clear the filters."
+- When the person has nothing to do, who fills the part and when: "No documents yet. The
+  office adds them when it takes up the case."
+- No blame: "No requests match the filters", not "You found nothing".
+
+## Magma gaps
+
+- `mds-zero`, example "Illustration Only (No Action)": its text is "Nessun risultato", a
+  search, which has Clear filters and no illustration; to rewrite as `filled-by-others`.
+- `mds-zero`, example "Full Empty-State Panel": the text mixes "edit the filters" and
+  "create", the action is only Create; to rewrite as `add-the-first`.
+- No illustration for empty states in `identity` (only a logo set of Maggioli Editore): the
+  product brings its own.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-16 | Proposed: `mds-zero` with a way out, never a warning tone | Open decision of the docs site, `agents/patterns.md`. |
+| 2026-10-28 | Draft with variables; the part this person cannot fill, the all-done and the search where the person may create left as gaps | The sources do not settle them. |
+| 2026-10-28 | "Always a way out" becomes `says-what-next`: an action when there is something to do, otherwise who or what fills the part (`filled-by-others`, `all-done`) | A button with nothing to do sends the person away from where they are. |
+| 2026-10-28 | A search with no results offers Clear filters only, even when the person may create | One action that answers the cause; Create stays in the header of the page. |
+| 2026-10-28 | An illustration only on first use, optional | It welcomes; where the person is working, the space belongs to the data (Illustration guide of the docs site). |