@maggioli-design-system/magma-react 2.0.1 → 2.2.0

package/AGENTS.md

@@ -0,0 +1,72 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# @maggioli-design-system/magma-react - agent install guide
+
+> Version 2.2.0. You (the agent) are installing Magma into THIS project. Do not
+> assume the setup - detect it from the project, then ask the user only for what you
+> cannot infer. The detailed steps live in [`agents/install.md`](agents/install.md)
+> (this target) and [`agents/assets.md`](agents/assets.md) (shared styles, fonts,
+> icons). This package targets: **React / Next.js**.
+
+## Step 1 - detect (read, do not ask)
+
+Inspect the consumer project before asking anything:
+
+| What | Where to look |
+| ---- | ------------- |
+| Framework | `package.json` deps: `@angular/core` -> Angular, `react`/`next` -> React, else vanilla |
+| Magma wrapper installed | presence of `magma-angular` / `magma-react` / `magma` in deps |
+| Bundler / static dir | `angular.json` (Angular CLI assets), `vite.config.*`, `next.config.*` (`public/`), webpack |
+| Tailwind + version | `tailwindcss` in deps: v4 -> the CSS imports, v3 -> the JS preset (see agents/assets.md) |
+| SSR | `@angular/ssr` / Angular Universal, or Next App Router |
+| Compatible versions | derive from the installed `@maggioli-design-system/magma` major (see matrix in install.md) |
+
+## Step 2 - ask only the gaps
+
+Ask the user only what detection left undecided. Typical questions:
+
+1. **Icons**: use the prebuilt set (`@maggioli-design-system/svg-icons`) or do you need
+   **iconsauce** for tree-shaking / custom icons? Most consumers do NOT need iconsauce -
+   Magma already ships resolved SVGs; iconsauce is an internal build dependency. Only
+   add `@iconsauce/*` if the user wants their own icon pipeline.
+2. **Static assets path**: where are static files served from? This sets `mdsIconSvgPath`
+   and the SVG copy destination.
+3. **Dark mode / preferences**: needed? If yes, wire the preference classes and components.
+4. Confirm the version row if the installed major is ambiguous.
+
+## Step 3 - execute
+
+1. Install packages and the shared assets - see [`agents/install.md`](agents/install.md).
+2. Wire styles in the exact cascade-layer order - see [`agents/assets.md`](agents/assets.md).
+3. Copy the icon SVGs to the static path and set `mdsIconSvgPath`.
+4. Register components: import the Mds* components from '@maggioli-design-system/magma-react' (no defineCustomElements needed).
+
+## Step 4 - verify
+
+Build the app and confirm an `mds-*` component renders and at least one icon loads from
+the configured path. Report what was installed, the cascade order used, and the icon path.
+
+## Using the components
+
+Once installed, do not guess component APIs or rules - read only the file you need:
+
+| You need | Read |
+| -------- | ---- |
+| Which component to reach for | [`agents/components.md`](agents/components.md) - the catalogue, one line each |
+| One component's API (props with allowed values, events, methods, slots, parts, CSS vars) | its `AGENTS.md`, linked from the catalogue |
+| Correct usage and mistakes for one component | `pattern.md` / `antipattern.md` beside its `AGENTS.md` |
+| Rules shared by every component: naming, events, slots, compound, icons, a11y, styling from outside | [`agents/conventions.md`](agents/conventions.md) |
+| `variant` and `tone` values | [`agents/variants.md`](agents/variants.md) |
+| Mistakes to avoid with any component | [`agents/anti-patterns.md`](agents/anti-patterns.md) |
+| Coloring your own UI | [`agents/color.md`](agents/color.md) |
+| Typography utilities | [`agents/typography.md`](agents/typography.md) |
+| Dark mode, preferences, named themes, surface levels and elevation, global design decisions, corner geometry | [`agents/theming.md`](agents/theming.md) |
+| Reporting a problem that is Magma's, not this project's (bug, wrong guide, missing token), with this project's origin label | [`agents/reporting.md`](agents/reporting.md) |
+
+Tooling that needs structured data reads `documentation.json`: one per component beside
+its `AGENTS.md`, or `@maggioli-design-system/magma/dist/documentation.json` for all of them
+(over 2 MB - do not load it into context). `dist/types/components.d.ts` drives editor
+IntelliSense.

package/agents/anti-patterns.md

@@ -0,0 +1,39 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# Magma components - system-level anti-patterns
+
+> Scope: mistakes that apply to **every** component. Each component's own
+> `antipattern.md` (next to its `AGENTS.md`) covers the component-specific ones; the
+> ones below are universal. The rules they break: [`conventions.md`](conventions.md),
+> [`variants.md`](variants.md), [`color.md`](color.md), [`theming.md`](theming.md).
+
+- Replacing a Magma component with a raw HTML element (`<button>`, `<input>`, `<a>` for
+  an action) when an `mds-*` equivalent exists.
+- Wrapping an interactive `mds-*` component in another interactive element
+  (`<a><mds-button></mds-button></a>` - use the `href` prop instead).
+- Reaching into shadow DOM past the documented API: undocumented `::part()` names,
+  internal class names, `>>>`, `/deep/`, or attribute-selector hacks. Use the CSS custom
+  properties and, for a deep customisation, the parts listed in the component's
+  `AGENTS.md` (see [`conventions.md`](conventions.md)).
+- Setting boolean attributes to the string `"false"` (e.g. `disabled="false"`,
+  `await="false"`). Stencil reads `"false"` as `false`, but the attribute stays in the
+  DOM on a prop that is not reflected (and until the first render on one that is), so
+  `[disabled]` selectors and scripts reading the attribute still see it set. **Remove
+  the attribute** to turn it off.
+- Embedding nested HTML in a default slot when the component documents a `label` prop.
+- Using raw Tailwind colour utilities (`bg-white`, `text-gray-700`) on or inside Magma
+  components - use the semantic role classes (`bg-surface-default`, `text-fg-muted`),
+  see [`color.md`](color.md).
+- Writing `@media (prefers-color-scheme: dark)` overrides - dark mode is handled by the
+  palette layer.
+- Hand-rolling focus styles instead of `focus-bounce` / `focus-zoom`.
+- Listening for native DOM events (`change`, `input`) when the component emits a
+  documented `mds*` event - they may not bubble out of shadow DOM the way you expect.
+- Applying a `tone`, `variant`, or `size` value to a component without checking its
+  typed signature (the Props table of its `AGENTS.md`, or
+  `dist/types/components.d.ts`). The same prop name accepts different value sets per
+  component - e.g. `<mds-banner tone="outline">` is invalid because `mds-banner.tone` is
+  `ToneMinimalBoxVariantType` (`strong | weak | box` only).

package/agents/assets.md

@@ -0,0 +1,203 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# install assets.md
+
+## Purpose
+
+Canonical setup for the assets every Magma consumer needs, **identical for all three
+targets** (web components, React, Angular): styles, fonts, icons and optional brand
+identity. The per-target tracks ([`install.md`](install.md)) link here instead of repeating
+this. If something about styles/fonts/icons setup is unclear, this file wins.
+
+This file is the minimum to get a consumer running. Once it runs: coloring your own UI
+in [`color.md`](color.md), the typography utilities in [`typography.md`](typography.md),
+dark mode, preferences, named themes, the `--magma-*` global decisions and the corner
+geometry in [`theming.md`](theming.md).
+
+## 1. Styles
+
+### Packages
+
+```bash
+npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens
+```
+
+Pin both to the row matching your `magma` major (see [`AGENTS.md`](../AGENTS.md) matrix).
+
+### Import order (mandatory)
+
+Magma styles rely on a fixed cascade-layer order. Import them in exactly this order
+in your global CSS entry point, or specificity conflicts and dark mode will break:
+
+```css
+@layer reset, vendor, theme, base, components, utilities, overrides;
+/* or @import '@maggioli-design-system/styles/dist/css/layer.css'; */
+
+@import 'normalize.css' layer(reset);
+
+/* Fonts - see section 2 */
+@import '@fontsource/karla/400.css' layer(vendor);
+@import '@fontsource/karla/700.css' layer(vendor);
+@import '@fontsource/merriweather/300.css' layer(vendor);
+@import '@fontsource/merriweather/400.css' layer(vendor);
+@import '@fontsource/merriweather/700.css' layer(vendor);
+@import '@fontsource/roboto/500.css' layer(vendor);
+@import '@fontsource/roboto/700.css' layer(vendor);
+@import '@fontsource/roboto/900.css' layer(vendor);
+@import '@fontsource/roboto-mono/400.css' layer(vendor);
+
+/* Magma styles */
+@import '@maggioli-design-system/styles/dist/css/colors-rgb.css' layer(theme);
+@import '@maggioli-design-system/styles/dist/css/typography.css' layer(theme);
+@import '@maggioli-design-system/styles/dist/css/reset.css' layer(reset);
+@import '@maggioli-design-system/styles/dist/css/hydrated.css' layer(base);
+@import '@maggioli-design-system/styles/dist/css/transitions.css' layer(base);
+@import '@maggioli-design-system/styles/dist/css/animations.css' layer(base);
+@import '@maggioli-design-system/styles/dist/css/globals.css' layer(theme);
+@import '@maggioli-design-system/styles/dist/css/semantic.css' layer(theme);
+@import '@maggioli-design-system/styles/dist/css/themes.css' layer(theme);
+@import '@maggioli-design-system/styles/dist/css/base.css' layer(base);
+
+/* your Tailwind entry point, if any */
+@import './tailwind.css';
+```
+
+What each file provides:
+
+| File | Purpose |
+| ---- | ------- |
+| `colors-rgb.css` | RGB color tokens (`--tone-*`, `--status-*`, ...). Required by components and Tailwind. Also redefines tokens for dark / high-contrast |
+| `typography.css` | The non-color tokens as CSS vars: fonts, type sizes, spacing, radius, shadows (`--shadow-md-sharp`, ...). Components carry their own fallbacks; your CSS needs this file for `var(--shadow-*)`, `var(--radius-*)` and the `--magma-radius-*` corner scale |
+| `reset.css` | Opinionated CSS reset |
+| `hydrated.css` | Anti-FOUC for Stencil - hides components until hydrated |
+| `transitions.css`, `animations.css` | Shared motion |
+| `globals.css` | Global `--magma-*` design decisions |
+| `semantic.css` | The semantic color roles (`--magma-surface-*`, `--magma-text-*`, ..., see [`color.md`](color.md)). Required: without it the page `body` has no colour, the Tailwind role utilities paint nothing, and components lose named themes and high contrast |
+| `themes.css` | The named themes (`data-theme-name`): retint the semantic roles. Import it after `semantic.css` |
+| `base.css` | Base element styles (sets `--font-info` body font, etc.) |
+
+DO NOT import `colors-hex-*.css` when using components or Tailwind - they cannot be
+used with opacity modifiers and bypass dark mode. Use `colors-rgb.css`.
+
+### Tailwind (optional)
+
+With Tailwind 4, import Magma's Tailwind layer in your Tailwind entry point (the
+`./tailwind.css` of the block above), after Tailwind's own theme and utilities. Leave out
+`@import 'tailwindcss'`: its preflight would duplicate Magma's reset.
+
+```css
+/* tailwind.css */
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+@import '@maggioli-design-system/styles/dist/tailwind/theme.css';
+@import '@maggioli-design-system/styles/dist/tailwind/typography.css';
+@import '@maggioli-design-system/styles/dist/tailwind/utilities.css';
+```
+
+`theme.css` brings the palette, the typography tokens and the semantic color utilities
+(`bg-surface-raised`, `text-fg-muted`, ..., see [`color.md`](color.md)), `typography.css`
+the `text-title-*` / `text-info-*` / `text-read-*` / `text-code-*` utilities,
+`utilities.css` the `focus-bounce` / `focus-zoom` helpers.
+
+Do not use the JS preset (`presets: [require('@maggioli-design-system/styles')]`) with
+Tailwind 4: it is the Tailwind 3 path (with the layers in
+`@maggioli-design-system/styles/dist/tailwind3/`), its colours are Tailwind 3 colour
+functions, and Tailwind 4 generates none of the Magma utilities from it.
+
+## 2. Fonts
+
+Magma does NOT bundle webfonts. The typography tokens point to **Roboto** (title),
+**Karla** (info / UI), **Merriweather** (read / editorial) and **Roboto Mono**
+(code), each with a system fallback. The consumer must load the actual fonts, easiest
+via [`@fontsource`](https://fontsource.org/):
+
+```bash
+npm i @fontsource/karla @fontsource/merriweather @fontsource/roboto @fontsource/roboto-mono
+```
+
+The `@import` lines are already in the section 1 block (under `layer(vendor)`). They
+are the weights the type scale uses: Roboto 500/700/900 (actions, h6, h1-h5), Karla
+400/700, Merriweather 300/400 (reading paragraph and detail, caption) plus 700 for bold in
+reading text, Roboto Mono 400. Add more weights as needed.
+
+Self-hosting via `@fontsource` is preferred over a CDN `<link>` so the fonts respect
+the `vendor` cascade layer and ship offline.
+
+## 3. Icons
+
+Icons are consumed at runtime by `mds-icon`, which fetches each icon as an SVG file from
+a path the host app configures. A slug starts with its icon set (`mi/` Material Icons,
+`mdi/` Material Design Icons, `mgg/` Maggioli) and resolves to
+`<mdsIconSvgPath><slug>.svg`: with the path `/svg/`, `mi/baseline/email` is fetched from
+`/svg/mi/baseline/email.svg`.
+
+### Package and asset copy
+
+```bash
+npm i @maggioli-design-system/svg-icons
+```
+
+Copy the SVG library to a publicly served path. The package ships the files under
+`@maggioli-design-system/svg-icons/dist/svg/`. Copy them to e.g. `public/svg/` (the
+mechanism depends on the bundler - see each track file).
+
+### Tell mds-icon where the icons are
+
+The simplest way: set `mdsIconSvgPath` in `sessionStorage` before components hydrate.
+The value is the public URL of the folder you copied the SVGs into:
+
+```javascript
+window.sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+```
+
+Alternatives, documented in
+the mds-icon readme:
+
+- `IconsSetService.setSvgPath('/svg/')`, imported from
+  `@maggioli-design-system/magma/services`: sets the path in code, without
+  `sessionStorage`, and reloads the icons already mounted
+- `mdsIcon.setSvgPath('/svg/')` - instance method on a temporary `mds-icon` node, after
+  `defineCustomElements()` has run
+- dispatch `new CustomEvent('mdsIconSvgPathUpdate')` on `window` to force a refresh
+  after changing the path
+
+Reference an icon by slug, never inline SVG and never import from an icon-set package:
+
+```html
+<mds-icon name="mi/baseline/email"></mds-icon>
+<mds-button icon="mi/baseline/send">Send</mds-button>
+```
+
+The mgg-icons webfont (`@maggioli-design-system/icons`) is an alternative output and
+is NOT used by Magma at runtime - prefer the SVG-file strategy above.
+
+## 4. Identity / brand (optional)
+
+Logos and avatars for Maggioli Group products. Install only if the app renders brand
+assets:
+
+```bash
+npm i @maggioli-design-system/identity
+```
+
+Assets live under `@maggioli-design-system/identity/dist/`:
+
+- `dist/brand/` - logos per brand (gruppo-maggioli, maggioli-editore, rnd, ...)
+- `dist/avatar/` - avatar illustrations (svg / webp / png / pdf)
+- `dist/illustrations/`, `dist/products/` - additional brand imagery
+
+These are static read-only files - serve them like any other asset, do not modify
+them in the consumer project.
+
+## Checklist
+
+- [ ] `styles` + `design-tokens` installed on the matching version row
+- [ ] Global CSS imports in the exact cascade-layer order above
+- [ ] `@fontsource` fonts installed and imported in the `vendor` layer
+- [ ] `svg-icons` SVGs copied to a public path
+- [ ] `mdsIconSvgPath` set to that public path before hydration
+- [ ] (optional) `identity` installed if brand assets are used
+- [ ] Components registered per your target track

package/agents/color.md

@@ -0,0 +1,193 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# Magma styles - color
+
+> Scope: coloring your own UI with Magma's semantic color roles, in Tailwind and in
+> plain CSS. Requires the styles setup in [`assets.md`](assets.md), including
+> `semantic.css`. Dark mode, contrast and named themes: [`theming.md`](theming.md).
+> The `variant` prop of the components: [`variants.md`](variants.md).
+
+## Name the role, not the colour
+
+Paint your UI with the semantic roles (`--magma-*`), not with a raw palette step and never
+with Tailwind's own palette:
+
+```html
+<!-- correct: roles follow the mode, the named theme and high contrast -->
+<section class="bg-surface-raised text-fg-default border border-border-muted">
+  <p class="text-fg-muted">Secondary text</p>
+</section>
+
+<!-- incorrect: raw Magma steps only flip with the mode -->
+<section class="bg-tone-neutral-seed text-tone-neutral-01 border-tone-neutral-09">...</section>
+
+<!-- incorrect: Tailwind's palette ignores Magma entirely -->
+<section class="bg-white text-gray-700">...</section>
+```
+
+A role resolves per mode (light / dark), per named theme (`data-theme-name` retints the
+neutral scaffolding and the accent) and per contrast preference (`pref-contrast-more`
+promotes text and borders, and the page). A raw step (`tone-neutral-03`,
+`status-error-05`, `variant-primary-04`) only flips with the mode: it stays grey under a
+tinted theme and gains no contrast when the user asks for more.
+
+## One token, two faces
+
+Every role is a CSS custom property holding an RGB channel triplet, and a Tailwind color
+of the same role.
+
+```css
+/* plain CSS: always inside rgb(), alpha with the slash syntax */
+.panel {
+  background: rgb(var(--magma-surface-raised));
+  color: rgb(var(--magma-text-default));
+  border: 1px solid rgb(var(--magma-border-muted));
+  box-shadow: 0 2px 8px rgb(var(--magma-shadow-ink) / 0.12);
+}
+```
+
+Tailwind names the TEXT roles `fg-*`, so a utility never reads `text-text-*`:
+`--magma-text-muted` is `text-fg-muted`, `--magma-danger-text-default` is
+`text-danger-fg-default`. Every other role keeps its name: `bg-surface-raised`,
+`border-border-default`, `bg-accent-emphasis`, `bg-danger-wash-base`.
+
+Both faces need the setup in [`assets.md`](assets.md): the values come from
+`styles/dist/css/semantic.css` (without it every role paints nothing), the Tailwind
+utilities from `styles/dist/tailwind/theme.css`. A Tailwind modifier works as usual
+(`bg-surface-raised/80`).
+
+## The roles
+
+### Neutral scaffolding
+
+Backgrounds, text and borders of everything that is neither an action nor a state. A
+named theme retints all of it at once.
+
+| Token (`--magma-*`) | Tailwind | Use |
+| --- | --- | --- |
+| `surface-default` | `bg-surface-default` | the page canvas (the `body` already has it) |
+| `surface-raised` | `bg-surface-raised` | cards, panels, sticky headers |
+| `surface-overlay` | `bg-surface-overlay` | modal, dropdown, popover, sheet |
+| `surface-sunken` | `bg-surface-sunken` | wells, insets, code blocks, tracks |
+| `surface-muted` | `bg-surface-muted` | same-plane grouping: zebra rows, a subtle section |
+| `wash-soft` / `wash-base` / `wash-strong` | `bg-wash-*` | a neutral pill or chip, by how marked it is |
+| `surface-inverse` / `surface-inverse-muted` | `bg-surface-inverse*` | the chip that flips with the mode (dark on a light UI) |
+| `on-inverse` | `text-on-inverse` | text and icons on either inverse level |
+| `text-default` | `text-fg-default` | body text, titles, primary data |
+| `text-muted` | `text-fg-muted` | secondary text that is still essential (an address, a phone) |
+| `text-subtle` | `text-fg-subtle` | non-essential text only: captions, units, hints |
+| `text-disabled` | `text-fg-disabled` | disabled labels |
+| `text-on-emphasis` | `text-fg-on-emphasis` | text on a solid fill |
+| `border-muted` | `border-border-muted` | decorative: dividers, table grid |
+| `border-default` | `border-border-default` | functional outlines: inputs, cards |
+| `border-strong` | `border-border-strong` | a border that conveys state (selected) |
+| `border-focus` | `border-border-focus` | focus indication; follows the accent |
+| `neutral-fg` / `neutral-border` | `text-neutral-fg` / `border-neutral-border` | neutral ink and border on a colored context |
+| `shadow-ink` | `shadow-shadow-ink` | the colour of a projected shadow; compose it with your own geometry and alpha |
+
+`--magma-on-backdrop` (in `globals.css`) is the ink on the modal scrim, fixed in both modes.
+
+How the five surfaces stack, their values in light and dark, why a raised element needs a
+shadow in light, and how themes and high contrast move them: [`theming.md`](theming.md#surfaces-and-elevation).
+
+### Accent: actions and selection
+
+Two accents with the same nine roles: `accent` (the brand action colour) and `accent-ai`
+(AI-driven features). A named theme can repoint them.
+
+| Token | Tailwind | Use |
+| --- | --- | --- |
+| `--magma-accent-emphasis` | `bg-accent-emphasis` | solid fill: the primary action |
+| `--magma-accent-emphasis-hover` / `-emphasis-active` | `hover:bg-accent-emphasis-hover` | the fill hovered / pressed |
+| `--magma-accent-on-emphasis` | `text-accent-on-emphasis` | text and icons on the fill |
+| `--magma-accent-surface` | `bg-accent-surface` | tinted background: a selected row or chip |
+| `--magma-accent-surface-subtle` / `-surface-hover` | `bg-accent-surface-*` | the tinted background, lighter / hovered |
+| `--magma-accent-fg` | `text-accent-fg` | accent text or icon on a neutral surface (a link) |
+| `--magma-accent-border` | `border-accent-border` | tinted border |
+
+`accent-ai` is the same set with the infix: `--magma-accent-ai-emphasis`,
+`bg-accent-ai-surface`, `text-accent-ai-fg`.
+
+### Status: info, success, warning, danger
+
+Each status publishes the same vocabulary. The hue is named `danger` (the palette family
+is `status-error`). A named theme never retints a status.
+
+| Token (`<hue>` = `info`, `success`, `warning`, `danger`) | Tailwind | Use |
+| --- | --- | --- |
+| `--magma-<hue>-wash-soft` / `-wash-base` / `-wash-strong` | `bg-<hue>-wash-*` | colored background, by how marked it is |
+| `--magma-<hue>-text-default` / `-muted` / `-subtle` / `-disabled` | `text-<hue>-fg-*` | colored text on that wash |
+| `--magma-<hue>-border-muted` / `-default` / `-strong` | `border-<hue>-border-*` | colored border |
+| `--magma-<hue>-emphasis` (+ `-hover`, `-active`) | `bg-<hue>-emphasis*` | solid fill: a destructive button, a solid badge |
+| `--magma-<hue>-on-emphasis` | `text-<hue>-on-emphasis` | text and icons on the fill |
+
+Shortcuts at the default prominence, kept for brevity: `--magma-<hue>-surface` =
+`wash-base`, `--magma-<hue>-fg` = `text-default`, `--magma-<hue>-border` =
+`border-default` (Tailwind `bg-<hue>-surface`, `text-<hue>-fg`, `border-<hue>-border`).
+
+## Pairing rules
+
+These are the pairs the contrast gate measures in CI; any other combination is not
+measured.
+
+- **`-fg` on a neutral surface, `-on-emphasis` on the fill.** `--magma-accent-fg` is ink
+  for the page; on `--magma-accent-emphasis` use `--magma-accent-on-emphasis`. Swapping
+  them is the quickest way to break contrast.
+- **Text on a wash is bounded.** `wash-soft` carries the whole text ladder, `wash-base`
+  carries `text-default` only, `wash-strong` carries icons only (no essential text). Same
+  rule for the neutral band and for every status.
+- **Hierarchy without dropping contrast.** `text-muted` is for essential secondary text,
+  `text-subtle` only for what the user can skip. For more hierarchy use weight, size and
+  spacing, and soften the chrome (`border-muted`, zebra on `surface-muted`) instead of the
+  text.
+- **Elevation is a role.** Page `surface-default`, card
+  `surface-raised`, floating layer `surface-overlay`, well `surface-sunken`: choose by
+  what the element is, not by the shade you want, and give `raised` / `overlay` a shadow
+  ([`theming.md`](theming.md#surfaces-and-elevation)). A grey that has to look marked in
+  both modes (a pill, a chip, a hover) is a wash, not a surface.
+- **No `dark:` variants and no dark-mode media queries.** The roles already flip.
+
+## When a raw palette colour is right
+
+Only when the colour encodes data rather than an interface role:
+
+- `label-*` (`bg-label-sky-09`, `rgb(var(--label-orchid-04))`): a category, a tag, a
+  colour the user picked;
+- `brand-*`: Maggioli brand identity;
+- `--tone-neutral-seed` (`#fff` in light, `#000` in dark): the rare pure extreme, a
+  knockout; not a page or card background.
+
+Never use `--magma-tint-*`: it is the internal pointer a named theme repoints, not a role.
+`tone-porcelain` and `tone-bisque` back the named themes `cool` and `warm`: switch them on
+with `data-theme-name` ([`theming.md`](theming.md)), do not paint them by hand.
+`variant-*` has no role of its own: the accents are `accent` and `accent-ai`.
+
+Deprecated: `--magma-neutral-emphasis` / `--magma-neutral-on-emphasis` are aliases of
+`--magma-surface-inverse` / `--magma-on-inverse`.
+
+## Migrating Magma 1 colour classes
+
+Magma 1 code paints raw steps, often with a hand-tuned `dark:` override. These steps have
+a role with the same light value; switch to the role and delete the `dark:` override:
+
+| Magma 1 step | As | Role |
+| --- | --- | --- |
+| `tone-neutral-01` / `-03` / `-04` / `-05` | text | `fg-default` / `fg-muted` / `fg-subtle` / `fg-disabled` |
+| `tone-neutral-10` / `-09` / `-08` | background | `wash-soft` / `wash-base` / `wash-strong` |
+| `tone-neutral-02` / `-03` | background | `surface-inverse` / `surface-inverse-muted` |
+| `tone-neutral-06` | border | `neutral-border` |
+| `tone-neutral` (the bare seed) | background | by context: `surface-default`, `-raised` or `-overlay` |
+| `status-<x>-01` / `-02` / `-03` / `-05` | text | `<hue>-fg-default` / `-muted` / `-subtle` / `-disabled` |
+| `status-<x>-04` / `-03` / `-02` | background | `<hue>-emphasis` / `-emphasis-hover` / `-emphasis-active` |
+| `status-<x>-10` / `-09` / `-08` | background | `<hue>-wash-soft` / `-wash-base` / `-wash-strong` |
+| `variant-primary-04` / `-03` / `-02` | background | `accent-emphasis` / `-emphasis-hover` / `-emphasis-active` |
+| `variant-primary-09` / `-08` / `-10` | background | `accent-surface` / `-surface-hover` / `-surface-subtle` |
+| `variant-primary-03` / `-06` | text / border | `accent-fg` / `accent-border` |
+
+`variant-ai-*` maps the same way onto `accent-ai-*`. The codemod
+(`@maggioli-design-system/magma-codemods`, `--accept-semantic=exact`) applies this table
+to markup, `clsx()`, Angular bindings and `@apply`, and reports what a value cannot
+decide.