Andreas Reinhold / reiniandClaude Opus 5
3365730610
Plan step 37 review. Removing material.css left README.md, the development skill, UPGRADE.md and the tailwind.css and foundation.css headers telling an application to import foundation.css, tailwindcss and tailwind.css in its place. material.css was also what brought layout.css and components.css, so that install rendered every component unstyled, and without a layer statement Tailwind's preflight would have outranked the package's layers. The skill's snippet is now the Tailwind-free one 2.0.0 ends with: the foundation, then the stylesheet of each component the views render, or all.css. README.md, whose layout and prose still assume Tailwind, shows all.css in its own entry and Tailwind in a second, both opening with the layer statement, the shape the Workbench now builds; the skill and UPGRADE.md describe that interim in a sentence. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9
165 lines
10 KiB
Markdown
165 lines
10 KiB
Markdown
# 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. `material.css` is gone
|
|
|
|
The 1.x single-import shortcut no longer exists. The package's CSS is plain now and goes in an
|
|
entry without Tailwind: `resources/css/all.css` for everything, or `foundation.css` first and then
|
|
the stylesheet of each component the views render. An application whose views still write Tailwind
|
|
classes builds Tailwind and `tailwind.css` in a second entry, never beside the package's imports,
|
|
since `@tailwindcss/vite` would repeat every shared stylesheet; both entries open with
|
|
`@layer properties, theme, base, material, components, utilities;` (see Installation in
|
|
`README.md`).
|
|
|
|
### 7. 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.
|
|
|
|
### 8. 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.
|
|
|
|
### 9. 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.
|