livewire-material/UPGRADE.md

# Upgrading

## From 1.x to 2.0.0

2.0.0 aligns the library with Material Design 3 Expressive as Google documents it
(m3.material.io, checked page by page; the audits are in `docs/audits/m3-alignment/`). Most of
the change is inside the components. What reaches an application is below, in the order to do it.

### 1. Breakpoints are M3's window size classes

Tailwind's `sm:`, `md:`, `lg:`, `xl:` and `2xl:` no longer compile. The variants are
`medium:` (600px), `expanded:` (840px), `large:` (1200px) and `extra-large:` (1600px), plus
`max-medium:` and friends for "below"; compact is everything below `medium`. Replace every
prefix in the application's views:

| Was | Becomes |
|---|---|
| `sm:` / `max-sm:` (640) | `medium:` / `max-medium:` (600) |
| `md:` / `max-md:` (768) | `medium:` or `expanded:` — choose by what the layout means |
| `lg:` / `max-lg:` (1024) | `expanded:` / `max-expanded:` (840) |
| `xl:` / `max-xl:` (1280) | `large:` / `max-large:` (1200) |
| `2xl:` (1536) | `extra-large:` (1600) |

Scripts read the same numbers from `resources/js/breakpoints.js` (`from('expanded')`,
`upTo('medium')`). `DesignGuard` reports every leftover prefix with its replacement.

### 2. Only M3's scales compile

Tailwind's default radius, shadow, text-size, weight, leading, tracking and easing utilities are
cleared like its palette was:

| Was | Becomes |
|---|---|
| `rounded-sm` … `rounded-4xl` | `rounded-corner-xs` … `rounded-corner-xxl` (`rounded-corner-full`, `rounded-corner-none`) |
| `shadow-sm` … `shadow-2xl` | `shadow-elevation-1` … `shadow-elevation-5` |
| `text-xs` … `text-9xl`, `leading-*`, `tracking-*`, `font-medium` … `font-black` | one `type-*` style (`type-body-md`, `type-emphasized-title-md` …) |
| `ease-in`, `ease-out`, `ease-in-out`, `duration-300` | `ease-spatial-*` / `ease-effects-*` with `duration-(--md-sys-motion-…-duration)` |

The 4px spacing scale is unchanged. `DesignGuard` names each one with its replacement.

### 3. Regenerate the colour scheme

```bash
php artisan material:scheme "#4f46e5" --variant=tonal-spot   # the command in the file's header
```

- `success`, `warning` and `info` are now built on the 2025 colour spec with the contrast level,
  like `error`; their values change. `--harmonize` blends them toward the seed (off by default).
- The stylesheet gains medium and high contrast blocks, and `material-scheme.json` gains a
  `contrast` key; `light`/`dark` at the top level are still the standard scheme, so the mail
  theme needs nothing. `--contrast` must now be below 0.5; medium (0.5) and high (1.0) are
  generated alongside.
- Config: `theme.contrast` (`default` `system` | `standard` | `medium` | `high`, `storage_key`)
  and `motion.scheme` (`expressive` | `standard`). `$store.theme` gains `contrast`,
  `resolvedContrast` and `setContrast()`; `<x-theme-toggle mode="contrast">` is a row of three.

### 4. Inks are roles, not opacities

`text-meta`, `text-quiet`, `border-chrome` and `border-divider` keep their names but now resolve
to `on-surface-variant`, `outline`, `outline-variant` and `outline-variant`. Where the old
translucent grey was intended, nothing to do; where a template relied on the opacity to blend
over a colour, use the role directly.

### 5. Changed defaults and props

- `<x-toast>` no longer draws a state icon; `type` only picks the announcement role (`alert` for
  error and warning, `status` otherwise). An actioned snackbar stays until acted on; Escape
  dismisses a focused one.
- `<x-fab>` has no `disabled` prop: M3 says to remove a FAB whose action is unavailable, so hide
  it instead (a form-submit FAB uses `wire:loading.attr="disabled"`).
- `<x-alert>` is `role="status"` for every colour; pass `assertive` where the notice answers
  something the person just did.
- `<x-button size="xs">` and `<x-group size="xs">` are 8px wider; a `<x-button-group>` no longer
  wraps; connected `xs`/`sm` segments have a 48px minimum width.
- `<x-menu-item>` rows are 48px with 16px sides; a selected item draws a trailing check unless it
  has `icon-right`; a long menu scrolls.
- `<x-drawer>` renders a close button by default (`:with-close-button="false"` to drop it, ignored
  on a `standard` sheet or when Escape and the scrim are off) and left-aligns its `actions` in a
  72px row. `<x-drawer pane>` is removed; use `<x-list-detail>` for the second pane of a
  list-detail layout.
- `<x-bottom-sheet>` opens at `50dvh` (was `90dvh`); any `height` is capped at
  `calc(100dvh - 72px)`.
- `<x-carousel>` `padding` defaults to `16`; `layout="full-screen"` scrolls vertically with
  edge-to-edge items; items, not the row, are the tab stops.
- `<x-list dividers>` draws a 16px-inset rule; `<x-list selectable>` or `selection="single|multi"`
  makes it a `listbox` of `option`s with `aria-selected`.
- `<x-card>` changes elevation on hover instead of its corner; `data-md-card` carries the variant.
- `<x-modal>` pins its header and actions and scrolls only the body; a `box-class` that set
  `overflow` no longer applies.
- `<x-table>` rows are 52px and the automatic fine-pointer density is gone: pass `dense` for 36px
  rows (`size="xs" dense` is 24px).
- A field in error draws a trailing `error` icon unless it already trails something; a read-only
  field no longer draws a dashed outline.
- The time picker's AM/PM buttons are radios (`aria-checked`); the password reveal no longer sets
  `aria-pressed`.
- `<x-slider size="md">` grows from 44 to 52px and every value indicator from 32 to 44px tall.
- `<x-theme-toggle mode="picker"|"contrast">` is a connected group over native radios: the
  `data-theme-option` hooks are gone; target `input[name="material-theme"][value="…"]`.
- `<x-tab>` panels render `id`, `aria-labelledby` and `display: none` from the server.
- `<x-section-nav>` with five or more sections is a scrollable tab bar, not a grid. The tab bar is
  10px taller; the focus ring sits outside.
- The navigation bar's horizontal label is `label-md`; `place="bottom"` toolbars sit above
  `--material-bottom-bar`; a standard toolbar's icon buttons are `primary`.
- The centred app bar headline is a grid column; the `search` variant bounds its own width, so
  drop hand-written `max-w-*` wrappers.
- `<x-app-shell>` is renamed `<x-scaffold>`, with no alias; it is a column with a nested row
  and gains `banner` and `fab` slots. `<x-navigation-rail>`'s `header` slot takes one
  `<x-fab label icon>` that morphs (replace the two-FAB `rail-collapsed:` swap); new `divider`
  and `fill` props. The `rail-collapsed:` variant is gone: style a rail's collapsed shape in the
  application's CSS with the conditions `resources/css/components/navigation-rail.css` lists. `data-app-shell`, `data-app-shell-bar`, `data-app-shell-actions` and
  `data-app-shell-banner` are `data-md-scaffold`, `data-md-scaffold-bar`, `data-md-scaffold-actions`
  and `data-md-scaffold-banner`; the skip link is `data-md-skip-link`.
- `<x-icon optical="20">` selects the optical-size-20 cut; the components pass it for their own
  small icons, applications pass it for icons drawn at 20px or less.
- A text field stops at 40rem wide from `medium:`, as M3 bounds fields on wider windows; a
  `max-w-*` class on the field beats it, and `full` removes it.
- Every `<x-modal>` draws a rule under its header and over its actions while its body scrolls,
  and neither when the body fits. `separator` now means "always draw both rules" and no longer
  renders two `<x-divider>` elements; the spacing between header, body and actions moved to
  M3's split gaps, so a dialog that fits is a few pixels shorter.
- A snackbar with a `description` is 68px tall, and below `medium:` a two-line snackbar with an
  action puts the action under the text. Alt+G moves focus to an actioned snackbar.
- `<x-bottom-sheet>`'s drag now follows the pointer and settles on the nearest preset height when
  `heights` or `snap` is set; without stops it behaves as before.
- A chip set with `scroll` shows a scroll button over each overflowing edge on fine pointers.

### 6. New in 2.0.0

Nothing to migrate, but worth knowing: submenus (`<x-menu-item submenu>`), a filtering menu
(`<x-menu filter>`), a menu that opens as a bottom sheet on compact windows
(`<x-menu sheet-at-compact>`), gap-grouped menu items (`<x-menu-group gap>`), square button groups
(`shape="square"`), managed selection on connected groups (`selection="single|multi" required`),
FAB collapse on scroll (`<x-fab collapse-on-scroll>`), the tall navigation bar and hide-on-scroll
(`tall`, `hide-on-scroll`; `tall-bar`, `hide-bar-on-scroll` on the shell), the narrow, centred and
hide-when-collapsed rail (`width="narrow"`, `align="center"`, `hide-when-collapsed`), a docked
toolbar with a FAB and a rounded large-screen form (`rounded`), app bar actions that overflow into
a menu (`:actions="[…]"`), the list item's `video` slot, the card's dragged state, the standard
side sheet (`<x-drawer standard>`), bottom sheet preset heights, the multi-aspect carousel
(`layout="multi-aspect"`), the divider with a subheader (`<x-divider text>`), the character counter
(`counter`), the vertical slider (`orientation="vertical"`), the full-screen range date picker on
compact windows, search's icon entry point and suggestions (`trigger="icon"`, `suggestions` slot),
the contrast toggle (`<x-theme-toggle mode="contrast">`) and the Standard motion scheme.

### 7. Tests and guards

Add `DesignGuard`'s new checks to the application's design test (`forbidOpacityInk()` and
`forbidAbsolutes()` are opt-in). Browser tests that assert widths switch at 640/1024/1280 now
switch at 600/840/1200; tests that read `role="alert"` on an alert, `aria-pressed` on the time
picker's period buttons or `data-theme-option` need the new hooks above.

### 8. For AI agents

`php artisan boost:update --discover` picks up the new `material-3` guideline and the
`material-3-design` skill, which state M3's rules and tables beside the library's utilities.