@nxgt/material 3.5.0 → 3.7.0

package/docs/guides/theming.md

@@ -90,6 +90,48 @@ container is the accent colour itself, the same as `bg-accent`.
 
 Put `text-foreground` on a container; it stays well above 4.5:1 in both themes.
 
+## The neutral palette
+
+The neutrals of both themes are softly tinted toward violet (hue 290, low
+chroma), to sit with the primary indigo instead of fighting it. The values:
+
+| Token | Light | Dark |
+| --- | --- | --- |
+| `--background` | `oklch(0.973 0.008 293.9)` | `oklch(0.192 0.016 290.5)` |
+| `--card`, `--popover` / `--sidebar` | white / `oklch(0.985 0.006 293.9)` | `oklch(0.232 0.019 289.4)` |
+| `--foreground` | `oklch(0.227 0.017 290)` | `oklch(0.943 0.012 291.3)` |
+| `--muted`, `--accent` | `oklch(0.955 0.012 292)`, `oklch(0.91 0.016 293)` | `oklch(0.27 0.022 290)` |
+| `--muted-foreground` | `oklch(0.478 0.032 292)` | `oklch(0.725 0.03 292.2)` |
+| `--border`, `--input` | `oklch(0.912 0.016 293.7)` | `oklch(0.301 0.025 291.4)`, `oklch(0.34 0.027 291.4)` |
+
+Earlier versions used a blue-slate neutral (hue 247 to 266; the dark
+background `oklch(0.14 0.036 258.53)` was a deep navy). To bring it back,
+redefine the tokens after the stylesheet import, under the same selectors;
+the main ones are below and the changelog of `@nxgt/material` 3.6.0 lists
+every old value (accent, ring, sidebar, tooltip, secondary and the others):
+
+```css
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.14 0.036 258.53);
+  --muted: oklch(0.968 0.007 247.896);
+  --muted-foreground: oklch(0.52 0.046 257.417);
+  --border: oklch(0.929 0.013 255.508);
+  --input: oklch(0.929 0.013 255.508);
+}
+.dark,
+[data-theme="dark"] {
+  --background: oklch(0.14 0.036 258.53);
+  --foreground: oklch(0.984 0.003 247.858);
+  --card: oklch(0.208 0.042 265.755);
+  --popover: oklch(0.208 0.042 265.755);
+  --muted: oklch(0.279 0.041 260.031);
+  --muted-foreground: oklch(0.66 0.046 257.417);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+}
+```
+
 ## Motion and shape tokens
 
 `styles.css` also carries Material 3 expressive motion and corner tokens, as
@@ -227,12 +269,12 @@ any tone, yours included:
 | `--nxgt-tone-on` | `text-tone-on` | what is drawn on it |
 | `--nxgt-tone-container` | `bg-tone-container` | a tint of it over the surface it sits on |
 | `--nxgt-tone-text` | `text-tone-text` | it as text on the page or its container |
-| `--nxgt-tone-ring-share` | — | the share of the text colour in the ring below (`65%`, set on `:root`) |
+| `--nxgt-tone-ring-share` | — | the share of the text colour in the ring below (`68%`, set on `:root`) |
 | `--nxgt-tone-ring` | `border-(--nxgt-tone-ring)` | a hairline: its text colour mixed into the surface at that share, 3:1 against it |
 
 The ring is drawn by: the `Avatar` fallback (the inset hairline, or the stroke of a shaped one); the tonal `StatCard` outline, the edges of its filled card and the ring round its icon chip; the outline and rank badge of a toned metric card; and, in a [calm zone](#calm-zone), the edge of a tonal `Shape`, an `Avatar`, a `StatCard` and a rank badge once their container steps back.
 
-Which knob changes which ring: `--nxgt-tone-ring-share` is the shared one, and being inherited it works on `:root` (`:root { --nxgt-tone-ring-share: 80%; }` makes every ring stronger) or on a wrapper (only the rings inside it). A component with a knob of its own, `--avatar-ring-share` or `--stat-card-ring-share`, takes it over for that component only: it applies to the component's own element, it is not inherited by a tone nested inside it, and `--stat-card-ring-share` draws every edge of the `StatCard`. Keep a ring at 3:1 or more against its surface (65 % does in light and dark) when you change the share.
+Which knob changes which ring: `--nxgt-tone-ring-share` is the shared one, and being inherited it works on `:root` (`:root { --nxgt-tone-ring-share: 80%; }` makes every ring stronger) or on a wrapper (only the rings inside it). A component with a knob of its own, `--avatar-ring-share` or `--stat-card-ring-share`, takes it over for that component only: it applies to the component's own element, it is not inherited by a tone nested inside it, and `--stat-card-ring-share` draws every edge of the `StatCard`. Keep a ring at 3:1 or more against its surface (68 % does in light and dark) when you change the share.
 
 ```tsx
 <span data-tone="success" className="bg-tone-container text-tone-text">
@@ -742,22 +784,22 @@ the rest yourself. Without the class the anchor keeps the prose style.
 ## Contrast and reduced motion
 
 **Contrast.** The shipped light palette keeps the text of every filled status
-colour at 4.5:1 or more (WCAG 1.4.3): `--secondary` 5.7:1, `--success` 5.6:1,
-`--info` 5.8:1 and `--warning` 5.5:1 against their `-foreground`, and
+colour at 4.5:1 or more (WCAG 1.4.3): `--secondary` 6.2:1, `--success` 6.1:1,
+`--info` 6.3:1 and `--warning` 5.5:1 against their `-foreground`, and
 `--secondary` as text (a `tonal`, `outlined` or `link` `Button`) 6.0:1 on
 `--background`, 4.8:1 on its own 15 % `tonal` tint.
 
 The dark theme keeps brighter values, read as text on the dark surfaces: the
-dark `--tertiary` (`oklch(0.7 0.15 310.75)`) is 7.0:1 on `--background` and
-6.3:1 on `--card`, with a dark `--tertiary-foreground` that keeps 7.0:1 on
+dark `--tertiary` (`oklch(0.7 0.15 310.75)`) is 6.5:1 on `--background` and
+5.9:1 on `--card`, with a dark `--tertiary-foreground` that keeps 6.5:1 on
 a filled tertiary surface (light: 7.6:1 under near-white). The dark
-`--secondary` (`oklch(0.66 0.1135 245.65)`) is 6.5:1 on `--background`
-and 5.8:1 on `--card` (a `tonal` secondary `Button` 5.4:1 and 4.6:1). Under
+`--secondary` (`oklch(0.675 0.1135 245.65)`) is 6.3:1 on `--background`
+and 5.8:1 on `--card` (a `tonal` secondary `Button` 5.1:1 and 4.6:1). Under
 near-white text those brights are too light, so every filled surface built on
 them is tinted in the dark theme: a filled `secondary` `Button`, `IconButton`
-or `Badge` at 70 % (5.2:1 on `--background`, 4.9:1 on `--card`), a filled
-`success`, `info` or `warning` one at 60 % (7.3:1, 5.7:1 and 6.0:1 on
-`--background`; 6.7:1, 5.3:1 and 5.6:1 on `--card`; the `warning` `Button` 6.5:1). Their hover, focus and
+or `Badge` at 70 % (4.9 to 5.2:1 on `--background`, 4.7 to 4.9:1 on `--card`), a filled
+`success`, `info` or `warning` one at 60 % (7.1:1, 5.6:1 and 5.8:1 on
+`--background`; 6.8:1, 5.3:1 and 5.5:1 on `--card`; the `warning` `Button` 5.9:1). Their hover, focus and
 pressed states are tinted further down, so they only gain contrast.
 
 In the light theme the filled `primary`, `secondary`, `success`, `info`,
@@ -773,11 +815,11 @@ The `tonal`, `outlined` and `link` variants of `Button` and `IconButton` draw
 their text and icon in one tone per colour, read on `--background`, on
 `--card` and on the variant's own tint (15 % at most, at rest or focused). In
 the light theme `primary`, `secondary`, `info` and `success` use the token
-itself (5.8, 4.8, 4.9 and 4.7:1 at their lowest) and `warning` and `error` the
-token mixed with 15 % black (6.4 and 5.4:1). In the dark theme `primary` is
-mixed with 60 % white, the `--primary-text` token (8.1:1 on `--card`: the token itself is a dark indigo,
-2.2:1), `success` and `warning` with 15 % white (5.0 and 6.3:1), `error` with
-30 % white (5.9:1), and `secondary` and `info` use the token (4.6 and 5.3:1).
+itself (5.4, 4.8, 4.9 and 4.7:1 at their lowest) and `warning` and `error` the
+token mixed with 15 % black (6.0 and 5.0:1). In the dark theme `primary` is
+mixed with 60 % white, the `--primary-text` token (7.7:1 at its lowest: the token itself is a dark indigo,
+2.2:1), `success` and `warning` with 15 % white (4.8 and 5.8:1), `error` with
+30 % white (5.5:1), and `secondary` and `info` use the token (4.6 and 5.0:1).
 The tones are mixed from the tokens (`color-mix(in oklab, var(--color-error)
 85%, black)`), so an override of a token moves its tone with it; a text colour
 of your own on one of those buttons (`className="text-primary-text"`) replaces the tone
@@ -796,32 +838,32 @@ the filled surface's near-white text below 4.5:1 (`0.62` gives 3.85:1).
 the light theme, 70 in the dark one), so a warning `Alert`, `Banner`, `Badge`
 or toast does not read as a failure. Light `oklch(0.52 0.13 62)` is 5.5:1
 under its near-white `-foreground`; dark `oklch(0.7 0.15 70)` reads as text at
-7.3:1 on `--background` and 6.5:1 on `--card` (6.6 and 5.8:1 on its 10 % tint). An app that overrides `--warning` keeps its own
+6.7:1 on `--background` and 6.1:1 on `--card` (5.9 and 5.3:1 on its 10 % tint). An app that overrides `--warning` keeps its own
 value; one that keeps the shipped value sees its `bg-warning` and
 `text-warning` surfaces change hue, and re-checks its custom pairs.
 
 **A selected `DataTable` row** (`TableRow`, `data-state="selected"`) is a 15 %
 primary tint with `foreground` text, a bar on the inline-start edge of its
 first cell (`before:`, primary in the light theme, primary mixed with 60 %
-white in the dark one: 5.9:1 in light and 8.2:1 or more in dark against the
-row), and the checkbox, drawn in the same dark colour (8.2:1 or more). The
-tint is too light to be told from its neighbour alone (1.2:1 in light, 1.06 to
+white in the dark one: 5.4:1 in light and 7.7:1 or more in dark against the
+row), and the checkbox, drawn in the same dark colour (7.7:1 or more). The
+tint is too light to be told from its neighbour alone (1.25:1 in light, 1.10 to
 1.11:1 in dark), which is what keeps the text at 4.5:1 or more on a page and on
-a `Card`: 15.9:1 in light, and in dark 17.5:1 on a page, 17.1:1 in a `DataTable`
-on a `Card` and 15.4:1 for a bare `TableRow` on a `Card`. Links and
-`text-muted-foreground` texts (drawn as `foreground` at 70 %) are 7.0:1 in
-light and 8.15:1 in dark for a bare row on a `Card`. A `text-error-text` text
+a `Card`: 12.6:1 in light, and in dark 14.1:1 on a page, 12.9:1 in a `DataTable`
+on a `Card` and for a bare `TableRow` on a `Card`. Links and
+`text-muted-foreground` texts (drawn as `foreground` at 70 %) are 5.6:1 in
+light and 7.0:1 in dark for a bare row on a `Card`. A `text-error-text` text
 keeps its colour. Do not
 put `text-primary-foreground` in a cell for a selected row: it is near-white
 on that tint.
 
 **Error text has a token of its own**, `--error-text` (`text-error-text`), so
 the fill can stay dark while the text is light enough to read. The light value
-is `color-mix(in oklab, var(--error) 94%, black)` (5.7:1 on `--background`
-and `--card`, 4.8:1 on the `bg-error/10` tint of a focused menu item, where
+is `color-mix(in oklab, var(--error) 92%, black)` (5.6:1 on `--background`,
+6.0:1 on `--card`, 5.0:1 on the `bg-error/10` tint of a focused menu item, where
 `--error` gives 5.0 and 4.2:1); the dark one is
-`color-mix(in oklab, var(--error) 80%, white)`, 5.9:1 on `--background` and
-5.3:1 on `--card`, where `--error` itself gives 4.2 and 3.8:1. Field messages,
+`color-mix(in oklab, var(--error) 76%, white)`, 5.85:1 on `--background` and
+5.35:1 on `--card` (4.78:1 on a focused error menu item), where `--error` itself gives 3.9 and 3.5:1. Field messages,
 `HelperText` in its error state, form, dialog and upload errors, a textarea's
 counter over its limit, the error lines of `Terminal`, a
 `variant="error"` menu item and the falling values of the metric cards use it.
@@ -846,7 +888,8 @@ the override on the root.
 **Primary text has a token of its own**, `--primary-text` (`text-primary-text`),
 for the same reason: the brand colour is a dark fill (it keeps near-white text
 readable on a button) and reads at only about 2:1 as text on the dark surfaces.
-The light value is `var(--primary)`; the dark one is
+The light value is `color-mix(in oklab, var(--primary) 96%, black)` (primary
+4 % toward black, 7.3:1 on the violet page); the dark one is
 `color-mix(in oklab, var(--primary) 40%, white)` (primary mixed 60 % with
 white, the recipe of the tonal `Button` labels). `Typography tone="primary"`,
 the `Alert` primary icon, links, selected labels and the other primary text of
@@ -871,33 +914,33 @@ at rest, hovered, focused and pressed, the tracks and the tabs;
 tokens after an override.
 
 **Tabs.** An `underline` tab's active label is `--primary` in the light
-theme (7.3:1 on `--background` and `--card`, 6.7:1 on `--muted`) and
-`--primary` mixed with 60 % white in the dark one (10.0:1, 9.0:1 and 7.4:1);
+theme (6.8:1 on `--background`, 7.3:1 on `--card`, 6.4:1 on `--muted`) and
+`--primary` mixed with 60 % white in the dark one (9.3:1, 8.5:1 and 7.6:1);
 its bar and every tab's focus outline are `--primary` in the light theme and
-`--track-fill` in the dark one (at least 6.7:1 and 9.0:1 on those surfaces).
+`--track-fill` in the dark one (at least 6.7:1 and 9.4:1 on those surfaces).
 An inactive label is `--muted-foreground`, and turns to `--foreground` when
 hovered. A `segmented` tab's active label is `--foreground` on the raised
-surface (19.9:1 light, 17.0:1 dark); that surface is only 1.1:1 to 1.2:1 on
-the track, so it has a `--muted-foreground` border (5.0:1 light, 4.7:1 dark
+surface (17.1:1 light, 14.2:1 dark); that surface is only 1.1:1 to 1.2:1 on
+the track, so it has a `--muted-foreground` border (5.8:1 light, 6.2:1 dark
 on the track), and the label also changes colour and weight. Storybook's
 `Guides/Theming/Contrast` story `Tabs` measures each label at rest, hovered
 and focused, the outline, the bar and the border, on the three surfaces, in
 both themes.
 
-`--muted-foreground` is 5.5:1 on `--background` and `--card`, 5.1:1 on the
-"paper" tint (`bg-background-paper`, 5 % primary) and 5.0:1 on `--muted` in
-the light theme; in the dark theme it is 6.4:1 on `--background`, 5.7:1 on
-`--card`, 6.3:1 on the paper tint and 4.7:1 on `--muted`. The dark `--muted`
-is a dark surface (`oklch(0.279 0.041 260.031)`, it was the light value, a
-near-white block on a dark page) and `--foreground` on it reaches 14.0:1.
+`--muted-foreground` is 6.2:1 on `--background`, 6.7:1 on `--card`, 5.7:1 on the
+"paper" tint (`bg-background-paper`, 5 % primary) and 5.8:1 on `--muted` in
+the light theme; in the dark theme it is 7.5:1 on `--background`, 6.9:1 on
+`--card`, 7.3:1 on the paper tint and 6.2:1 on `--muted`. The dark `--muted`
+is a dark surface (`oklch(0.27 0.022 290)`, it was the light value, a
+near-white block on a dark page) and `--foreground` on it reaches 12.8:1.
 
 **Tracks.** The empty part of a `Slider`, of the password strength meter and
 the `Drawer` handle use `--track` (`bg-track`), and the `Slider`'s range and
 thumb border `--track-fill` (`bg-track-fill`, `border-track-fill`). In the
-dark theme the track reaches 3.6:1 on `--background` and 3.2:1 on `--card`
+dark theme the track reaches 3.5:1 on `--background` and 3.2:1 on `--card`
 (WCAG 1.4.11; `bg-muted`, a dark surface now, gave 1.4:1 and 1.2:1), and the
-fill 3.4:1 on the track. The light theme keeps a pale track (`--track` is the
-light `--muted`) and `--track-fill` is `--primary`: the thumb, 7.3:1 on the
+fill 3.3:1 on the track. The light theme keeps a pale track (`--track` is the
+light `--muted`) and `--track-fill` is `--primary`: the thumb, 6.8:1 on the
 page, shows the value. A track, bar, handle or divider of your own drawn with
 `bg-muted` is near invisible in the dark theme now that `--muted` is a dark
 surface: draw it with `bg-track`.

package/docs/roadmap.md

@@ -6,6 +6,23 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
+- **Vector drawings in code** (in the next prerelease) — `@nxgt/material/draw`
+  draws a scene of plain data, or JSX primitives (`Rect`, `Path`, `Text`...), as
+  SVG that follows the theme: colours are Material 3 roles and tones, with no
+  inline `style`, so a strict CSP is satisfied and a server renders the same
+  markup as the browser. A drawing is named (`title`) or `decorative`, enforced
+  by the type; nodes with events are focusable buttons with a focus ring; wrapped
+  text breaks with Inter's metrics and is refined once mounted. Material 3
+  Expressive's shapes, morphs and layout helpers (`stack`, `grid`, `align`)
+  come with it. `/draw/sketch` redraws any drawing by hand (seeded, so the
+  server and the browser agree), `/draw/animate` traces strokes, fades nodes in
+  and morphs one scene into another (nothing moves under reduced motion),
+  `/draw/png` saves a PNG with the page's colours, and `/print` places the scene
+  in a PDF as vectors. For e-mail, `toSVG(scene, { standalone: true })` gives an
+  SVG with literal colours and a PNG made in a browser covers the clients that
+  do not show SVG. React only for now; the Vue port is on the Vue roadmap.
+  ([Drawing guide](guides/drawing.md), [Drawing](components/rich-widgets.md#drawing))
+
 - **A modern code editor** — `CodeEditor` and `CodeDiff` get their own entry,
   `@nxgt/material/code-editor`, and theme presets: App (from your tokens),
   Moonlight and Soft, light and dark, or your own `defineCodeTheme`, several on

package/docs/troubleshooting.md

@@ -27,6 +27,7 @@ words in your error.
 
 - [Components render unstyled, with no error](#components-render-unstyled-with-no-error)
 - [A link is blue and underlined on hover and focus](#a-link-of-mine-or-of-a-component-is-blue-and-underlined-on-hover-and-focus)
+- [The light and dark neutrals turned violet after upgrading to 3.6](#the-light-and-dark-neutrals-turned-violet-after-upgrading-to-36)
 - [Math renders in the system fonts](#math-renders-in-the-system-fonts)
 - [`<Icon>` renders nothing](#icon-renders-nothing)
 - [An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry](#an-accessibility-audit-reports-low-contrast-on-a-badge-a-button-a-toast-or-a-menu-entry)
@@ -388,6 +389,19 @@ words in your error.
 - [My gradient colour override stopped working](#my-gradient-colour-override-stopped-working)
 - [A preset's items use class names my own CSS also uses (`fl`, `d1`, `k1`, `mo`)](#a-presets-items-use-class-names-my-own-css-also-uses-fl-d1-k1-mo)
 
+**Drawing**
+
+- [`A decorative drawing has an interactive node: give the Drawing a title instead`](#a-decorative-drawing-has-an-interactive-node-give-the-drawing-a-title-instead)
+- [`Unsafe drawing at <tag>: <reason>` from a scene or a JSX drawing](#unsafe-drawing-at-tag-reason-from-a-scene-or-a-jsx-drawing)
+- [`Tones "a" and "b" meet on one element: use two nodes in a group`](#tones-a-and-b-meet-on-one-element-use-two-nodes-in-a-group)
+- [`No colour for "brand": pass palette: { "brand": "#rrggbb" }`](#no-colour-for-brand-pass-palette--brand-rrggbb-)
+- [`shapeOutline: unknown shape "x"; expected one of SHAPE_NAMES (…)`](#shapeoutline-unknown-shape-x-expected-one-of-shape_names-)
+- [`drawingToPng: cannot read the image "<url>" (<reason>)…`](#drawingtopng-cannot-read-the-image-url-reason)
+- [`drawingToPng: the canvas gave no PNG.` and its siblings](#drawingtopng-the-canvas-gave-no-png-and-its-siblings)
+- [A drawing is black, or its role colours do nothing](#a-drawing-is-black-or-its-role-colours-do-nothing)
+- [A Server Component that renders `Drawing` fails](#a-server-component-that-renders-drawing-fails)
+- [`Duplicate identifier 'text'` when importing from `/draw` and `/print`](#duplicate-identifier-text-when-importing-from-draw-and-print)
+
 **Content Security Policy**
 
 - [`[nxgt-material] html.cspNonce is set, but the CSP is in hash mode (the default): set nxgtMaterial({ csp: { mode: 'nonce' } }) or drop html.cspNonce.`](#nxgt-material-htmlcspnonce-is-set-but-the-csp-is-in-hash-mode-the-default-set-nxgtmaterial-csp--mode-nonce---or-drop-htmlcspnonce)
@@ -740,6 +754,34 @@ public/assets/icons/sprites/sharp-solid.svg ← <Icon name="atom" family="sharp"
 
 Serve one sheet per style you use, from your own Font Awesome Pro kit.
 
+### The light and dark neutrals turned violet after upgrading to 3.6
+
+**When:** after `@nxgt/material` 3.6, the page, cards, borders and muted text
+are softly violet-tinted (the dark background was a deep navy), and a
+screenshot test, or a brand that sat on the old slate, no longer matches.
+**Why:** the neutral tokens moved to hue 290 with low chroma in both themes
+(the palette is listed in the [theming guide](guides/theming.md#the-neutral-palette)).
+Primary and the status colours did not change, except that the light
+`--secondary`, `--success` and `--info` and the dark `--secondary` moved
+0.02 in lightness, so their tonal tints keep 4.5:1 on the new page colour.
+**Fix:** update the screenshots, or redefine the old neutrals after the
+stylesheet import, under `:root` and `.dark, [data-theme="dark"]`:
+
+```css
+.dark,
+[data-theme="dark"] {
+  --background: oklch(0.14 0.036 258.53);
+  --card: oklch(0.208 0.042 265.755);
+  --popover: oklch(0.208 0.042 265.755);
+  --muted: oklch(0.279 0.041 260.031);
+  --border: oklch(1 0 0 / 10%);
+}
+```
+
+The [theming guide](guides/theming.md#the-neutral-palette) has the main old
+values for both themes (the `:root` block too); the changelog of 3.6.0 lists
+every one.
+
 ### An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry
 
 **When:** axe (or Lighthouse) reports `color-contrast` on a `Badge` with
@@ -795,7 +837,7 @@ yours still fail, you override them.
 In the dark theme, a filled `secondary` `Button` gave its near-white text
 4.3:1, a `tonal` secondary one 3.9:1 (3.4:1 on `--card`), and a filled
 `success`, `info` or `warning` one 3.5:1, 2.5:1 and 3.4:1. The dark
-`--secondary` is brighter (`oklch(0.66 ...)`, 6.5:1 as text on
+`--secondary` is brighter (`oklch(0.675 ...)`, 6.3:1 as text on
 `--background`), and the filled `secondary`, `success`, `info` and `warning`
 `Button`s and `IconButton`s are filled in the dark theme with an opaque mix
 toward `--background` (about 70 %), so their text keeps 4.5:1 over any backdrop.
@@ -872,7 +914,7 @@ subtitle colour of your own on a selected `ListTile` must reach 4.5:1 on
 ### An accessibility audit reports low contrast on error text in the dark theme
 
 **When:** an error message, a validation hint or a red value of your own, in
-the dark theme, fails 4.5:1 (about 4.2:1 on the page, 3.8:1 on a card); the
+the dark theme, fails 4.5:1 (about 3.9:1 on the page, 3.5:1 on a card); the
 catalogue's own field messages pass.
 **Why:** it is drawn with `text-error`, the fill colour. The dark `--error` is
 kept dark enough for near-white text on a filled error surface, which makes it
@@ -6759,6 +6801,128 @@ import '@nxgt/material/backgrounds.css'; // every preset
 
 ---
 
+## Drawing
+
+How to use it is in the [Drawing guide](guides/drawing.md); the engine's own
+errors (`Invalid colour`, `Invalid path data`, `Unsupported scene version`,
+`[pdf] A drawing mask is not supported in a PDF: dropped.`) are in the
+[core troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#drawing).
+
+### `A decorative drawing has an interactive node: give the Drawing a title instead`
+
+**When:** a `Drawing` with `decorative` renders, or contains, a node with `onClick` (or any event), `interactive`, or an entry in `handlers`. It throws on the render.
+**Why:** `decorative` is `aria-hidden`, and a focusable node inside it would be reachable by keyboard and invisible to assistive technology.
+**Fix:** give the drawing a `title` (and each interactive node a `label`), or drop the events:
+
+```tsx
+<Drawing scene={board} title="Board columns" onNodeClick={open} />
+```
+
+### `Unsafe drawing at <tag>: <reason>` from a scene or a JSX drawing
+
+**When:** `Drawing`, `toSVG`, `compileScene` or `assertSafeDrawing` throws `Unsafe drawing at <image>: href must be http(s), relative or data:image (png, jpeg, gif, webp)` or another reason (`tag not allowed`, `style not allowed`, `<attribute> not finite`, `id used twice`...).
+**Why:** a strict CSP could not accept what the scene would write. From a scene loaded as JSON the cause is usually an `image` `href` (`javascript:`, `file:` or `data:image/svg+xml`), a `className` or node `id` with unusual characters, or a coordinate that is `NaN`.
+**Fix:** correct the value the message names. Check untrusted JSON before drawing it:
+
+```ts
+import { assertSafeDrawing } from '@nxgt/material/draw';
+
+assertSafeDrawing(scene); // throws with the element and the reason
+```
+
+The reasons are listed in the [core troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#unsafe-drawing-at-tag-reason).
+
+### `Tones "a" and "b" meet on one element: use two nodes in a group`
+
+**When:** a node has `fill: tone('brand')` and `stroke: tone('accent')` where both are app tones.
+**Why:** an app tone is carried by one `data-tone` attribute on the element, so an element can have only one.
+**Fix:** one node per tone, in a group, or name a theme tone for one of them:
+
+```tsx
+group({}, [
+	circle({ cx: 20, cy: 20, r: 14, fill: tone('brand', 'container') }),
+	circle({ cx: 20, cy: 20, r: 14, fill: 'transparent', stroke: tone('accent') }),
+]);
+```
+
+### `No colour for "brand": pass palette: { "brand": "#rrggbb" }`
+
+**When:** `toSVG` (the default `colors: 'literal'`) or a PDF meets an app tone or token that has no literal colour.
+**Why:** a standalone SVG has no theme to read, so every token needs a hex; only the theme's own roles have one.
+**Fix:** pass it, or use `colors: 'vars'` for an inline SVG:
+
+```ts
+toSVG(art, { palette: { brand: '#0a7c59' } });
+```
+
+### `shapeOutline: unknown shape "x"; expected one of SHAPE_NAMES (…)`
+
+**When:** `shape('cookie-99', …)` or `morph` is given a name the registry does not have.
+**Why:** a typo, or a name from another library. The message lists the valid ones.
+**Fix:** use a name of `SHAPE_NAMES`, with or without the `m3-` prefix:
+
+```ts
+import { SHAPE_NAMES, shape } from '@nxgt/material/draw';
+
+shape('cookie-9', { x: 0, y: 0, w: 80, h: 80 }); // or 'm3-cookie-9'
+console.log(SHAPE_NAMES);
+```
+
+### `drawingToPng: cannot read the image "<url>" (<reason>)…`
+
+**When:** `drawingToPng` or `downloadDrawingPng` rejects, and the drawing holds an `image` with a URL.
+**Why:** an SVG drawn as an image loads nothing external, so the function fetches each image and inlines its bytes; the browser refused the fetch, almost always CORS. Nothing is left to taint the canvas: the failure is reported before it can happen.
+**Fix:** serve the image with `Access-Control-Allow-Origin`, or put a `data:image/png|jpeg|gif|webp` URL in the scene:
+
+```ts
+image({ href: 'data:image/png;base64,…', x: 0, y: 0, w: 64, h: 64 });
+```
+
+### `drawingToPng: the canvas gave no PNG.` and its siblings
+
+**When:** a PNG fails with one of `drawingToPng: the canvas gave no PNG.`, `drawingToPng: no 2D canvas in this browser.`, `drawingToPng: scale must be above 0.`, `drawingToPng: the drawing has no size.` or `drawingToPng: the browser could not draw the SVG.`.
+**Why:** respectively a canvas the browser refused to encode (usually far too large: `scale` times the drawing's size), no canvas support, a zero or negative `scale`, a live `<svg>` with no `width`, `height` or `viewBox`, and an SVG that does not load as an image.
+**Fix:** lower the `scale`, pass a positive one, give the `<svg>` a `viewBox`, or draw from the scene instead of the live element:
+
+```ts
+await drawingToPng(scene, { scale: 1 });
+```
+
+### A drawing is black, or its role colours do nothing
+
+**When:** a `Drawing` renders in black (or the browser's default colours), whatever its `fill="primary"`.
+**Why:** role colours are classes of `styles.css` (`nxgt-draw-f-primary`...); without the stylesheet nothing maps them. A standalone `toSVG` file does not use classes: it writes hex.
+**Fix:** import the stylesheet once in the app:
+
+```ts
+import '@nxgt/material/styles.css';
+```
+
+### A Server Component that renders `Drawing` fails
+
+**When:** a Next.js or RSC page imports `Drawing`, a primitive, `Sketch` or the animate hooks and the build reports that a hook or a context only works in a Client Component.
+**Why:** `@nxgt/material/draw` is its own entry whose built files carry no `'use client'` directive (the components use hooks).
+**Fix:** render it from a file of yours that starts with `'use client'`; the builders and `toSVG` can stay in the Server Component and pass the scene as a prop:
+
+```tsx
+// drawing-client.tsx
+'use client';
+export { Drawing } from '@nxgt/material/draw';
+```
+
+### `Duplicate identifier 'text'` when importing from `/draw` and `/print`
+
+**When:** TypeScript reports `Duplicate identifier 'text'` (or `Import declaration conflicts with local declaration of 'text'`, or the same for `image`) in a file that imports from both entries.
+**Why:** `@nxgt/material/draw` and `@nxgt/material/print` each export a `text` and an `image`: the first builds a drawing node, the second a PDF block.
+**Fix:** rename one of them:
+
+```ts
+import { text as drawText } from '@nxgt/material/draw';
+import { text } from '@nxgt/material/print';
+```
+
+---
+
 ## Content Security Policy
 
 How to set up the policy is in the [Content Security Policy guide](guides/csp.md).

package/lib/components/components.css

@@ -196,3 +196,5 @@
 @import "../backgrounds/css/base.css";
 @import "../backgrounds/css/gradient.css";
 @import "../backgrounds/css/motion.css";
+@import "./ui/widgets/drawing/drawing.css"; /* @nxgt/material/draw: role colours, focus ring */
+@import "./ui/widgets/drawing/drawing-animate.css";