@nxgt/material 2.7.1 → 2.8.0

package/docs/guides/theming.md

@@ -33,8 +33,9 @@ at the top are needed is in [getting started](../getting-started.md#styles).
   highlight.js (`RichTextEditor` code blocks), react-easy-crop
   (`ImageCropper`), the `CodeBlock` theme, and the `nxgt-*` classes of
   `ButtonGroup`, `BottomAppBar`, `ContactItem`, `OpeningHoursItem`,
-  `AttributeForm` and `AttributeValuesForm` (the first three are
-  dependencies, the rest ship in `lib/components/`);
+  `AttributeForm` and `AttributeValuesForm`, and the required-field mark drawn
+  after a `Label` (the first three are dependencies, the rest ship in
+  `lib/components/`);
 - the **tokens**: CSS variables on `:root`, and their dark values on `.dark`
   and `[data-theme="dark"]`;
 - a `@theme` block that maps each token to a Tailwind colour, so `bg-primary`,
@@ -51,9 +52,11 @@ at the top are needed is in [getting started](../getting-started.md#styles).
 | `--primary`, `--primary-foreground` | `bg-primary`, `text-primary-foreground` | filled buttons, active states, focus |
 | `--secondary`, `--secondary-foreground` | `bg-secondary`, … | the secondary colour |
 | `--muted`, `--muted-foreground` | `bg-muted`, `text-muted-foreground` | quiet surfaces, hints, placeholders |
+| `--track`, `--track-fill` | `bg-track`, `bg-track-fill`, `border-track-fill` | the empty part of a slider or meter, the drawer handle; the slider range and thumb |
 | `--accent`, `--accent-foreground` | `bg-accent`, … | hover surfaces |
 | `--error`, `--success`, `--info`, `--warning` (+ `-foreground`) | `bg-error`, `text-success`, … | the status colours of `Button`, `Alert`, `Badge`, toasts |
-| `--destructive` | `bg-destructive`, `text-destructive` | destructive menu items and actions |
+| `--error-text` | `text-error-text` | error drawn as text: field messages, `HelperText` in its error state, form and dialog errors, `variant="error"` menu items |
+| `--destructive` | `bg-destructive`, `text-destructive` | deprecated alias of `--error`: the light theme sets it to `var(--error)`, the dark theme keeps its own value; use `--error` |
 | `--card`, `--popover`, `--tooltip` (+ `-foreground`) | `bg-card`, `bg-popover`, `bg-tooltip` | surfaces |
 | `--border`, `--input`, `--ring` | `border-border`, `border-input`, `ring-ring` | outlines |
 | `--chart-1` … `--chart-5` | `bg-chart-1`, … | chart series (the charts read them at runtime) |
@@ -90,20 +93,145 @@ Redefine the variables **after** the import, for light and dark separately:
 Override the variable, not the `@theme` entry: `--color-primary` is defined as
 `var(--primary)`, so one change reaches both modes and every derived colour.
 
-For a single area of the page, set the variables on a wrapper:
+For a single area of the page, set the `--color-*` variables on a wrapper
+(the `@theme` entries are resolved on the root, so setting `--primary` on an
+element below it changes nothing):
 
 ```tsx
 import { Button } from '@nxgt/material/components';
 
 export function DangerZone() {
   return (
-    <section style={{ ['--primary' as string]: 'var(--error)' }}>
+    <section style={{ ['--color-primary' as string]: 'var(--error)' }}>
       <Button>Delete workspace</Button>
     </section>
   );
 }
 ```
 
+## 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.3: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 `--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
+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 7.5:1 on
+`--background`; 6.7:1, 5.3:1 and 7.0:1 on `--card`). 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`,
+`warning` and `error` buttons darken when hovered, focused or pressed (mixed
+with 10, 15 and 20 % black) rather than fading toward the page, so their
+near-white text only gains contrast (the filled `default` variant's states are
+unchanged); a `tonal` button's focus tint is 10 %
+(lighter than its 15 % rest), an `outlined` one's 15 %, and its hover keeps the
+text colour.
+
+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.0 and 5.4:1). In the dark theme `primary` is
+mixed with 60 % white (8.1:1 on `--card`: the token itself is a dark indigo,
+2.2:1), `success` and `warning` with 15 % white (5.0 and 5.4:1), `error` with
+30 % white (5.9:1), and `secondary` and `info` use the token (4.6 and 5.3: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"`) replaces the tone
+and is yours to check.
+
+A `Badge` used as a link (`asChild` around an `<a>`) darkens on hover like a filled
+button (mixed with 10 % black; in the dark theme its tint drops by ten
+points) rather than fading toward the page. A selected `ListTile` draws its
+subtitle in `text-foreground/70` (7.0:1 on the selected tint, where the muted
+colour gave 4.4:1). The light `--error` is `oklch(0.56 0.245 27.325)`, a shade
+darker than the dark theme's: a filled `error` button's near-white text reaches
+4.8:1 (it was 4.6:1). The dark `--error` keeps `0.577`: a lighter value drops
+the filled surface's near-white text below 4.5:1 (`0.62` gives 3.85:1).
+
+**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
+`--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,
+`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.
+
+Which one to use:
+
+- **`text-error-text`** for an error written as text on a page, card or
+  popover surface (your own validation message, a failed row, an inline
+  error), and for an icon drawn beside that text, so the two match.
+- **`text-error`** (with `bg-error`, `border-error`, `ring-error`,
+  `stroke-error`) for fills, borders, rings and icons that stand alone: those
+  need 3:1 (WCAG 1.4.11), which `--error` reaches in both themes. Text on a
+  filled error surface is `text-error-foreground`.
+
+`--error-text` is computed where it is declared, on the root, and `@theme`
+resolves `--color-error-text` there too: an override of `--error` under `:root`
+and `.dark, [data-theme="dark"]` moves it, but setting `--error-text` or
+`--error` on an element below the root changes nothing. Below the root, set
+`--color-error-text` (and `--color-error` for fills) on that element, or put
+the override on the root.
+
+Storybook's `Guides/Theming/Contrast` measures all of this in both themes:
+the surfaces' text, the error text (`HelperText` and a field's message on
+`--background` and `--card`), the `Alert`s and the `Timeline`, `Button` and
+`IconButton` in every variant and colour, and a `Badge` link in every colour,
+at rest, hovered, focused and pressed, and the tracks; `Data display/ListTile`
+measures the selected tile. Run them against your own tokens after an
+override.
+
+`--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.
+
+**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`
+(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
+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`.
+
+When you override one of these tokens, keep its pair at 4.5:1 (3:1 for an
+icon or a border), or the `Badge`, `Button`, `Alert` and toast text built on it fails
+an accessibility audit. The muted text of a highlighted menu entry (a
+`DropdownMenuShortcut`, the code in `LanguageSwitcher`) switches to
+`--accent-foreground` while the entry is highlighted, so a `--muted-foreground`
+of your own does not have to pass on the highlight colour.
+
+**Reduced motion.** `styles.css` imports `components/reduced-motion.css`: one
+`@media (prefers-reduced-motion: reduce)` rule that turns off the transitions
+and animations of every catalogue component (everything under a `data-slot`,
+and the toasts): dialogs, sheets and menus appear without sliding or fading,
+buttons and toasts without transitions. The `Spinner` and any `animate-spin` element (a spinning
+loading icon) keep turning: they are the only sign that something is loading.
+The rule is `!important` but unlayered and with a specificity of 0, so a
+component's own `duration-*` utility does not outrank it, and your own
+`!important` rule on a class does; to keep one motion for everyone, override it
+on that element with that rule inside `@media (prefers-reduced-motion: reduce)`.
+Your own components outside a `data-slot` are yours: use Tailwind's
+`motion-reduce:` variant on them.
+
 ## Dark mode
 
 Dark values apply under a `.dark` class **or** a `data-theme="dark"`

package/docs/roadmap.md

@@ -18,6 +18,9 @@ Nothing in progress right now; see Next.
 
 ## Later
 
+- **Next major: `ListTile`'s `data-slot` becomes `list-tile`** — it is
+  `item-detail` today, so the name matches the component like every other
+  slot. Breaking for a selector or a test that looks for `item-detail`.
 - **3.0: the same amounts and dates on every machine** — `formatAmount` and
   `formatDate` stop falling back to the runtime's locale when you pass none, so
   a server and a browser always print the same string.
@@ -85,6 +88,24 @@ Nothing in progress right now; see Next.
 
 ## Shipped
 
+- **Accessible by default** — error text in its own `--error-text` colour that
+  reads 4.5:1 in both themes, the empty part of sliders and meters in a
+  `--track` colour that reads 3:1, buttons, badges and status colours that
+  reach WCAG contrast, animations that honour `prefers-reduced-motion`, the
+  page behind a modal layer made `inert`, focus on the first invalid field
+  after a failed submit, Escape that reaches the layer below while one
+  closes, and a `Toaster` at the top of a phone whose toasts a tap does not
+  pause and whose actions work over a dialog. 2.8.0.
+- **Fits a phone** — `DataTable` with no height cap by default (`maxHeight`
+  when it should scroll in a box), a header row at every width, and wide
+  columns that scroll sideways in one region a keyboard can reach; a `Button`
+  never wider than its container (a long label ends in "…", or wraps with
+  `wrap`); `OtpField` slots that shrink to fit a narrow card. 2.8.0.
+- **App shell links, landmarks and scrolling** — menu entries that are real
+  links (middle-click, before hydration, `aria-current="page"`, your router's
+  link through `linkComponent`), one `<main>` landmark, and a shell
+  that lets the document scroll, with `scroll="container"` for a full-height
+  screen. 2.8.0.
 - **DataTable server-side data** — hand the table one page from your loader
   (`manual`): no client paging or sorting, controlled sorting and selection by
   row id (`sorting`, `rowSelection`, `getRowId`), a footer with "41–60 of 133"
@@ -146,7 +167,7 @@ Nothing in progress right now; see Next.
 - **Accessible names, ids and focus across the catalogue** — every field is
   named by its label and says it is required on the element a screen reader
   lands on (the input, the picker's `combobox`, the slider thumbs, the
-  group), with the asterisk hidden from it; groups are named by their question
+  group), with the asterisk drawn by CSS, so in no name or label text; groups are named by their question
   and describe their error instead of carrying `aria-invalid` where ARIA does
   not allow it; ids are generated rather than taken from a field's `name` or
   an option's `value`, so two forms on one page no longer collide; icon