livewire-material/docs/audits/m3-alignment/navigation.md

Audit: navigation

Scope: app-bar, toolbar, tabs/tab, navigation-bar(-item), navigation-rail(-item|-section), app-shell, section-nav, account-menu, theme-toggle, scheme-picker, their CSS/JS, the showcase usage and the matching SKILL.md sections.

Sources abbreviated below: RCB = docs/reference/m3/reference-components-b.md; RF = docs/reference/m3/reference-foundations.md; raw/ = docs/reference/m3/raw/<page>.md; tok/ = docs/reference/m3/tokens/<File>.kt (androidx-main). Anything fetched live is named with its URL.

Summary

The component-level work is unusually faithful: every numeric token I checked for the app bar (64/112/136/120/152dp heights, title-large → headline-medium → display-small, 4dp edge spacing), the navigation bar (64dp, 56×32 indicator, 40dp horizontal pill, 16dp indicator spaces, and even Compose's calculateCenteredContentHorizontalPadding formula reproduced as calc(10% * (count + 3))), the rail (96dp collapsed, 220–360dp expanded, 44dp top space, 40dp header space, 56dp expanded item, modal = surface-container + elevation 2 + CornerLarge inner edge) and both toolbars (64dp, 16dp/4–32dp docked, 8dp/4dp + CornerFull floating) matches the androidx token files exactly. The catalogue is also right about Expressive: the deprecated bottom app bar and navigation drawer are absent, the flexible app bars and the flexible navigation bar are what is implemented, and the expanded rail correctly plays the drawer's role. The real problems are three: the adaptive breakpoint map is Tailwind's, not M3's — sm 640 stands in for 600 and, much worse, lg 1024 stands in for 840, so every window from 840 to 1023px is denied the standard expanded rail and gets a modal that re-closes on every navigation; two hand-rolled buttons (theme-toggle, account-menu) are 40×40 with no 48px target, below M3's stated minimum, while the library's own <x-button> and the rail's menu button both do it correctly; and a few placement rules are simply not wired up — a place="bottom" toolbar sits on top of the app shell's navigation bar, a rail-nested FAB keeps elevation 3 where M3 says level 0, and theme-toggle mode="picker" hand-rolls the Expressive-deprecated segmented button even though the library already ships its successor (<x-group>).

Findings

N-01 · theme-toggle, account-menu · 40×40 controls with no 48px interaction target

• Severity: must-fix
• M3 says: "Touch target minimum 48 × 48dp"; "Web default target size: at least 48 × 48 CSS pixels"; and, precisely for this case, "The size of state layers is 40dp while the interactive target size is 48dp" (RF §Accessibility Values, §States/state-layer mechanics). RF §Layout/Density repeats: "Interaction targets must stay ≥48×48dp even when the visible element is scaled down."
• Library does: resources/views/components/theme-toggle.blade.php:65 renders inline-flex size-10 (40px) with no target extension; resources/views/components/account-menu.blade.php:41 renders inline-flex size-10 … overflow-hidden (40px), likewise none. The library already knows the fix: the icon button applies after:absolute after:top-1/2 after:left-1/2 after:size-full after:min-h-12 after:min-w-12 after:-translate-x-1/2 after:-translate-y-1/2 at xs/sm (resources/views/components/button.blade.php:171-172, comment "Below 48px the touch target reaches past the button, as M3 requires"), and the rail's menu button repeats it at resources/views/components/navigation-rail.blade.php:108 (after:size-12).
• Fix: add the same after: pseudo-target to both class lists. For account-menu, overflow-hidden on the button would clip the pseudo-element — move the clipping to the <img> (class="size-full rounded-corner-full object-cover") and drop overflow-hidden from the button.
• Effort: S
• Breaks API? no

N-02 · toolbar, app-shell · a place="bottom" toolbar sits on top of the navigation bar

• Severity: must-fix
• M3 says: "Docked toolbar and navigation bar occupy the same screen position — never show both simultaneously" (RCB §Toolbars/Behaviour; raw/components_toolbars_guidelines.md). For the floating case: "FAB, when present, floats above the nav bar, right-aligned — must never overlap/cover it" (RCB §Navigation Bar/Behaviour), and the toolbar occupies the same rail region as a FAB (raw/foundations_layout_scaffold_rails.md: "On mobile, a toolbar can float in the rail region" — the rail region sits above the navigation bar, item 1: "A toolbar sits above the navigation bar").
• Library does: resources/css/components/toolbar.css:75-81 pins the toolbar at bottom: calc(1rem + var(--material-safe-bottom, env(safe-area-inset-bottom))) — it ignores --material-bottom-bar, the variable the shell sets for exactly this purpose (resources/views/components/app-shell.blade.php:88). The library's FAB (resources/views/components/button.blade.php:177, max-sm:bottom-[calc(var(--material-bottom-bar,0px)+1rem)]) and the snackbar (resources/views/components/toast.blade.php:36) both do use it. A docked variant="docked" place="bottom" toolbar (toolbar.css:91-96, bottom: 0) lands squarely on the navigation bar with no warning anywhere in the code or in SKILL.md:754-764.
• Fix: in toolbar.css, change [data-toolbar-place="bottom"]'s bottom to calc(var(--material-bottom-bar, 0px) + 1rem + var(--material-safe-bottom, env(safe-area-inset-bottom))) (mirroring the FAB/toast rule, which already folds the safe area into --material-bottom-bar), and for [data-toolbar][data-variant="docked"][data-toolbar-place="bottom"] bottom: var(--material-bottom-bar, 0px). Add one line to SKILL.md's <x-toolbar> section: a docked toolbar and a navigation bar must never be on screen together — show the bar on primary pages, the toolbar on secondary/contextual ones.
• Effort: S
• Breaks API? no

N-03 · navigation-rail · a FAB nested in the rail keeps elevation 3

• Severity: must-fix
• M3 says: "When nested within another component, such as the navigation rail, the FAB's resting elevation should be level 0" (raw/components_navigation-rail_guidelines.md:213; RCB §Navigation Rail/Behaviour: "the site explicitly states this contrasts with a standalone FAB's normal elevation").
• Library does: resources/views/components/fab.blade.php:49 always applies shadow-elevation-3 hover:shadow-elevation-4; resources/css/components/navigation.css contains no rule for a FAB inside a rail (grep for fab in it returns nothing). The documented pattern (navigation-rail.blade.php:7-9, SKILL.md:717-719, showcase/shell.blade.php:48-49) puts a FAB in the header slot, so every documented use is at elevation 3.
• Fix: the FAB has no attribute hook today (fab.blade.php:65 renders <{{ $tag }} {{ $attributes }}> with classes only), so add data-fab to its merged attributes, then add an unlayered rule to navigation.css — shadow-elevation-3 is a Tailwind utility, so a @layer components rule would lose, exactly as toolbar.css:10-12 already explains for its vibrant recolouring: [data-navigation-rail-header] [data-fab], [data-navigation-rail-header] [data-fab]:hover { box-shadow: none; }.
• Effort: S
• Breaks API? no

N-04 · theme-toggle · mode="picker" renders the Expressive-deprecated segmented button

• Severity: must-fix
• M3 says: segmented buttons "are deprecated in the expressive update"; "connected button groups should replace the baseline segmented button" (docs/reference/m3/reference-components-a.md:343-345, :224, :257).
• Library does: resources/views/components/theme-toggle.blade.php:22-48 hand-rolls one — a 40px (h-10) outlined stadium (rounded-corner-full border border-outline) whose segments share dividing borders (not-first:border-s) and whose selected segment is bg-secondary-container with a check icon. That is the OutlinedSegmentedButtonTokens design (40dp, CornerFull, 1dp outline, label-large), point-for-point. Its own header comment says so: "picker: M3's segmented buttons for the three choices". Meanwhile the library ships the successor twice over: resources/views/components/group.blade.php:1-2 ("An M3 Expressive connected button group — the successor of the segmented button", native radios, arrow-key movement, selected segment rounds fully) and resources/views/components/button-group.blade.php (connected). The showcase puts the deprecated control in its own chrome at showcase/layout.blade.php:148.
• Fix: re-implement mode="picker" on top of <x-group> with :options="[['id' => 'light', 'name' => __('Light'), 'icon' => 'light_mode'], …]" and an x-model-ish binding onto $store.theme.choice (a small x-data wrapper writing $store.theme.set() on change). The selected-segment shape morph, the radiogroup semantics and the arrow keys then come for free — which also resolves N-17.
• Effort: M
• Breaks API? no (the mode="picker" prop name and the data-theme-toggle="picker" / data-theme-option hooks can be kept; the internal markup changes, so any app CSS targeting the inner buttons would move)

N-05 · tabs · every panel is visible until Alpine initialises

• Severity: must-fix
• M3 says: tabs show one destination at a time; the active indicator plus a single visible panel is the whole mechanism (RCB §Tabs/Anatomy, /Behaviour). Exposing all panels also breaks the ARIA tabs contract — only the panel for the selected tab may be rendered/visible.
• Library does: resources/views/components/tab.blade.php:10 hides the panel with x-show only, and there is no x-cloak or server-side hidden/style="display:none". [x-cloak]{display:none!important} is defined (resources/css/tokens/state.css:68-70) but unused here. Until Alpine boots, all panels stack vertically (the showcase's 4-tab example renders all four bodies), and a screen reader reaching the page early sees four role="tabpanel" regions at once. The same line binds x-bind:id, so aria-controls="…-panel" on every tab button (tabs.blade.php:65) dangles until Alpine runs.
• Fix: in tab.blade.php, render the id server-side the way the tab buttons already do (pass the $id down, or reuse tabsId via a @aware/slot prop) and add x-cloak plus a server-rendered @if ($name !== $initial) style="display: none" @endif — or simplest: keep x-show, add x-cloak, and add a CSS rule that un-cloaks the initially selected panel. Any of these removes both the flash and the dangling aria-controls.
• Effort: S
• Breaks API? no

N-06 · app-shell, navigation-rail · lg (1024px) stands in for M3's expanded breakpoint (840dp)

• Severity: should-fix
• M3 says: breakpoints are Compact <600, Medium 600–839, Expanded 840–1199, Large 1200–1599, Extra-large ≥1600 (RF §Layout/Breakpoints). For Expanded the recommended navigation is "Modal or standard expanded navigation rail", and the swap table gives Expanded a "Standard expanded navigation rail" (RF §Layout/Breakpoints tables). The rail page: "Expanded → extra-large → use a rail (never a bar); choose Standard vs. Modal based on space and destination count" (RCB §Navigation Rail/Behaviour).
• Library does: the threshold is Tailwind's lg = 64rem = 1024px, in three places that must agree — resources/js/navigation.js:16 (const WIDE = '(min-width: 64rem)'), resources/css/components/navigation.css:51 and :57 (the rail-collapsed variant) and :184-188 (the adaptive rail's 96px layout width). Below it, materialNavigationRail.modal is true (navigation.js:116-118) and expanded ignores $store.rail.collapsed (:124-130). What a user sees at 840–1023px (a landscape tablet, a half-screen desktop window, a 12.9" iPad): a 96px collapsed rail; pressing its menu button opens the expanded rail as a modal over a scrim with a focus trap; document.addEventListener('livewire:navigating', … hide()) (navigation.js:86) closes it on every destination click, so the rail must be re-opened for each navigation; and the remembered $store.rail = expanded preference is silently ignored. M3 lists a standard (in-layout) expanded rail for this whole band.
• Fix: change WIDE to '(min-width: 52.5rem)' (840px) and the three 64rem media queries in navigation.css to 52.5rem. If 840px feels too narrow for a 256px rail beside content, expose the threshold instead of hard-coding it: a --material-rail-expanded-at custom property or a wide-at prop on <x-app-shell>/<x-navigation-rail mode="adaptive">, defaulting to 840px. Update SKILL.md:665 and :735, which both say "to lg" / "from lg".
• Effort: M
• Breaks API? no (unless an app relies on the 1024px switch point visually)

N-07 · app-shell, navigation-bar · sm (640px) stands in for M3's compact/medium boundary (600dp)

• Severity: should-fix
• M3 says: Compact is "Under 600dp"; Medium is "600–839dp" (RF §Layout/Breakpoints). The navigation bar is for "compact (<600dp) and medium (600–839dp)" (RCB §Navigation Bar/Behaviour); at Medium the swap table gives "Collapsed navigation rail" as the primary navigation (RF §Layout/Breakpoints).
• Library does: two different numbers for the same boundary. The bar's own item layout switches at the right place — @container (width >= 37.5rem) = 600px (navigation.css:123, :465, :519, :525, :555, :562), correct and matching ShortNavigationBarArrangement.Centered. The shell, however, switches at sm = 40rem = 640px: app-shell.blade.php:142 (sm:hidden on the bar wrapper), :87 (sm:flex), :88 and :136 (the --material-bottom-bar padding), and navigation.css:190-194 / :235-279 (the adaptive rail is width 0 and display:none below 40rem). What a user sees at 600–639px: the navigation bar is still the only navigation, but it has already flipped to the medium horizontal (icon-beside-label, centred) configuration — so the Expressive medium bar exists in a 40px-wide window band and then disappears entirely at 640px, where the collapsed rail takes over. The two switch points should be the same number.
• Fix: replace the sm:/max-sm: utilities in app-shell.blade.php (lines 87, 88, 136, 142) with arbitrary variants at 600px (max-[37.5rem]: / min-[37.5rem]:), or define a compact/medium custom variant in the theme so the whole package has one name for 600px; change the two 40rem media queries in navigation.css to 37.5rem. Also update the documented wrapper in navigation-bar.blade.php:4 and SKILL.md:700-707, which teach sm:hidden.
• Effort: M
• Breaks API? no (the documented sm:hidden wrapper idiom changes in the docs)

N-08 · navigation-bar-item · the horizontal (medium) item label is label-large, not label-medium

• Severity: should-fix
• M3 says: NavigationBarTokens.LabelTextFont = TypographyKeyTokens.LabelMedium (tok/NavigationBarTokens.kt). There is no per-layout label font: NavigationBarHorizontalItemTokens defines only ActiveIndicatorHeight/LeadingSpace/TrailingSpace/IconSize, and Compose's ShortNavigationBarItem passes labelTextStyle = NavigationBarTokens.LabelTextFont.value for both icon positions (androidx ShortNavigationBar.kt:220, fetched from https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/ShortNavigationBar.kt).
• Library does: resources/css/components/navigation.css:147-148 sets font: var(--md-sys-typescale-label-lg) inside @container (width >= 37.5rem). (The rail's horizontal item is label-large — NavigationRailHorizontalItemTokens.LabelTextFont = LabelLarge — which is probably where this came from; the nav bar has no such token.)
• Fix: navigation.css:147-148 → keep label-md (delete the two lines; the base [data-navigation-pill] rule at :105-106 already sets label-medium).
• Effort: S
• Breaks API? no

N-09 · app-bar · the search variant's container does not follow the 312dp / 50% growth rule

• Severity: should-fix
• M3 says: "The search container of the search app bar should fill 100% of the space between leading and trailing app bar elements until it reaches 312dp. Then, it should only grow further to fill 50% of that space" (raw/components_app-bars_guidelines.md:454; RCB §Top App Bar/Behaviour).
• Library does: resources/css/components/app-bar.css:133-137 — [data-app-bar-search] { flex: 1 1 0%; }, i.e. 100% of the available space at every width. On a 1600px window the search bar spans ~1500px. The showcase works around it by hand (showcase/layout.blade.php:60, class="mx-auto w-full max-w-2xl"), which is evidence the component's own behaviour is wrong, and max-w-2xl (672px) is not the M3 curve either.
• Fix: in app-bar.css, give the search slot the M3 curve: [data-app-bar-search] { flex: 1 1 0%; max-width: calc(19.5rem + (100% - 19.5rem) / 2); margin-inline: auto; } (19.5rem = 312px; below 312px max-width never binds so it still fills 100%). Then drop the manual max-w-2xl in the showcase layout.
• Effort: S
• Breaks API? no

N-10 · tabs · scrollable tabs have no 52dp leading offset

• Severity: should-fix
• M3 says: "When using scrollable tabs, the first visible tab should be offset by 52dp from the left side of the device for both web and mobile"; "Do — Offset the first scrollable tab 52dp from the leading edge so it's clear that more content is available" (raw/components_tabs_guidelines.md:150, :157; RCB §Tabs/Variants).
• Library does: resources/css/components/tabs.css:50-52 only sets flex: none on the tabs when [data-scrollable] is present; there is no leading padding anywhere on [data-tabs-bar]. The showcase's scrollable example (showcase/sections/bars.blade.php:101-105) starts "January" flush against the container edge, so nothing signals that the set scrolls.
• Fix: tabs.css, add [data-tabs-bar][data-scrollable] { padding-inline-start: 3.25rem; } (52px) — logical property, so RTL mirrors for free.
• Effort: S
• Breaks API? no

N-11 · app-bar · the centred headline uses fixed 56px insets and collides with two trailing actions

• Severity: should-fix
• M3 says: the centred configuration is the Expressive replacement for the center-aligned bar ("Merged into small. Use centered-text configuration.", RCB §Top App Bar/Status), and trailing elements are "up to 2 icon buttons after headline" (RCB §Top App Bar/Behaviour). The headline must not be truncated (raw/components_app-bars_guidelines.md:337).
• Library does: resources/css/components/app-bar.css:122-130 absolutely positions the centred headline with inset-inline: 3.5rem — a hard-coded 56px on each side, enough for exactly one 48px icon button. With the M3-sanctioned two trailing buttons (≈96px plus the 4px row padding), the headline box extends ~40px underneath them; a long title ellipsises behind the buttons instead of before them. Nothing in the code adapts the inset to what the navigation/actions slots actually contain.
• Fix: replace the absolute positioning with a three-column grid on the row for the centred variant — [data-app-bar][data-variant="center"] [data-app-bar-row] { display: grid; grid-template-columns: 1fr auto 1fr; } with the leading slot in column 1, the headline (centred, justify-self: center, min-width: 0) in column 2 and the trailing slot in column 3 (justify-self: end) — the headline then shrinks against whatever is actually beside it. Failing that, measure the two slots in app-bar.js (which already runs a ResizeObserver) and publish --app-bar-lead/--app-bar-trail.
• Effort: M
• Breaks API? no

N-12 · toolbar · a vertical floating toolbar placed at end uses a 16px margin, M3 wants ≥24dp

• Severity: should-fix
• M3 says: "Horizontal toolbars should have a minimum 16dp margin from the edge of the window"; "Vertical toolbars should have a minimum 24dp margin" / "Maintain at least a 24dp margin for vertical toolbars" (raw/components_toolbars_guidelines.md:334, :346, :350; RCB §Toolbars/Specs).
• Library does: resources/css/components/toolbar.css:83-89 — [data-toolbar-place="end"] { inset-inline-end: calc(1rem + var(--material-safe-right, …)); }, 16px for every toolbar placed at the end edge, and place="end" is documented as the placement "for a vertical one" (toolbar.blade.php:6).
• Fix: toolbar.css, split the rule: [data-toolbar][data-vertical][data-toolbar-place="end"], [data-toolbar-group][data-vertical][data-toolbar-place="end"] { inset-inline-end: calc(1.5rem + var(--material-safe-right, env(safe-area-inset-right))); } (24px) while horizontal placements keep 16px.
• Effort: S
• Breaks API? no

N-13 · toolbar · standard (non-filled, non-tonal) buttons inside a standard toolbar are on-surface-variant, M3 says Primary

• Severity: should-fix (with a caveat — see both readings)
• M3 says: standard toolbar colour list, verbatim: "1. Surface container / 2. Filled button (Primary, On primary) / 3. Toggle tonal button (Secondary container, On secondary container) / 4. Standard button (Primary)" (raw/components_toolbars_specs.md:228-234; RCB §Toolbars/Specs). The vibrant list gives "Standard button (On primary container)" (:253) — which the library does honour.
• Library does: resources/css/components/toolbar.css:49-61 recolours buttons only in the vibrant case. In a standard toolbar the icon buttons keep the library's default icon-button ink, text-on-surface-variant (resources/views/components/button.blade.php:116 $quietInk, :123 for icon-only text buttons) — the container's own color: var(--md-sys-color-on-surface-variant) (toolbar.css:28, :37) cannot reach them because they carry a utility. The other reading: M3's own icon-button spec gives an unselected standard icon button on-surface-variant, and the toolbar colour list is annotated from an image showing text/standard buttons rather than icon buttons. If the library treats the toolbar list as applying to label buttons only, its current choice is defensible. I lean to the finding because the same list's vibrant row is implemented, so the two rows are being read inconsistently.
• Fix: if adopting the spec, add next to the vibrant rules (same unlayered block): [data-toolbar]:not([data-vibrant]) [data-icon-button]:not([aria-pressed="true"]) { color: var(--md-sys-color-primary); }. If keeping the current behaviour, say so in toolbar.css's header comment with the reason, so the next reader does not re-litigate it.
• Effort: S
• Breaks API? no

N-14 · app-shell · the app bar sits inside the content pane, beside the rail, not across the window

• Severity: should-fix (structural; see both readings)
• M3 says: the scaffold is bars → rails → panes, in that nesting order. "Bars can frame the page"; "Rails create the perimeter space surrounding panes" (raw/foundations_layout_scaffold_overview.md:54-58); "Rails are the next level in layout after bars, filling the perimeter space surrounding panes"; "Rails occupy the spaces immediately adjacent to bars" (raw/foundations_layout_scaffold_rails.md:56, :64). And for the bar itself: "Container always spans 100% of window width at its default height" (RCB §Top App Bar/Behaviour).
• Library does: resources/views/components/app-shell.blade.php:97-139 puts <x-navigation-rail> as a flex sibling before a column that contains {{ $top }} and <main>. From sm the app bar therefore starts 96px (or 256px) in from the window's leading edge and is a pane-level bar, not a page-level one. There is no slot that renders above the rail, so an application cannot opt into the M3 arrangement without abandoning <x-app-shell>. The other reading: NavigationSuiteScaffold in Compose nests the whole content — top bar included — beside the rail, and M3's canonical-layout imagery shows both arrangements. If the library regards the app bar as a pane bar, the current structure is consistent; it is still worth a documented decision rather than an accident of markup order.
• Fix: add a window-top (or banner) slot to <x-app-shell> rendered as the first child of [data-app-shell] with the shell root becoming flex flex-col and the rail+content row nested inside, so an application can choose either. Document which slot means which in SKILL.md:663-695.
• Effort: M
• Breaks API? no (additive slot)

N-15 · account-menu · the avatar trigger has no state layer (no hover or pressed state)

• Severity: should-fix
• M3 says: the six states are Enabled, Disabled, Hover, Focused, Pressed, Dragged, and "States have two visual indicators to ensure accessibility"; the state layer's colour equals the content's "on" colour, at 8% hover / 10% focus / 10% pressed (RF §Interaction/States).
• Library does: resources/views/components/account-menu.blade.php:41 — focus-ring inline-flex size-10 … rounded-corner-full bg-primary-container … text-on-primary-container. It has the focus ring but no state-layer, so there is no hover and no pressed feedback at all. Every comparable trigger in the library (the rail menu button at navigation-rail.blade.php:108, the theme toggle at theme-toggle.blade.php:65, every <x-button>) carries state-layer.
• Fix: add state-layer to the class list. Note the ordering constraint from resources/css/tokens/state.css:13-27 (the utility sets position: relative; isolation: isolate and paints a ::before at z-index: -1) — with overflow-hidden removed per N-01 this composes cleanly.
• Effort: S
• Breaks API? no

N-16 · section-nav · secondary tabs wrapped onto a 3/4-column grid break the tab bar's divider and indicator

• Severity: should-fix
• M3 says: "Container always spans full width, divided into equal sections; bottom-edge divider separates it from content below" (RCB §Tabs/Behaviour). M3's stated answer to "too many tabs" is scrollable tabs — "scrollable allows longer labels and more tabs" (RCB §Tabs/Variants) — and its accessibility page explicitly blesses them: "Horizontal scrolling tabs meet accessibility requirements because they need to increase in width to respond to label text without affecting the layout" (raw/components_tabs_accessibility.md:95).
• Library does: resources/views/components/section-nav.blade.php:31-35, :60 reuses [data-tabs-bar][data-variant="secondary"] but applies sm:grid sm:grid-cols-3 / sm:grid-cols-4, so from 5 items the "tab bar" becomes two or more rows. tabs.css:19 puts the 1px outline-variant divider on the bar, so only the last row gets one and the upper rows' 2px active indicators float in mid-air against nothing. [data-tab] { min-width: 5.625rem } (tabs.css:36) also fights grid-cols-4 in a narrow column.
• Fix: either keep sm:flex with [data-scrollable] semantics (flex: none + the 52dp offset from N-10), which is what M3 prescribes and what the library already implements for <x-tabs scrollable>; or, if the grid is kept deliberately, move the divider to each row ([data-section-nav] [data-tabs-bar] > li { border-bottom: 1px solid var(--md-sys-color-outline-variant); } with the bar's own border removed) and drop the min-width inside the grid. See also "Deliberate deviations" — the stated reason for the grid does not survive M3's text.
• Effort: M
• Breaks API? no

N-17 · theme-toggle · the picker's radiogroup keyboard handling is incomplete

• Severity: should-fix
• M3 says: a single-select segmented control's role is "Radiogroup" (docs/reference/m3/reference-components-a.md:392); RF §Interaction/Inputs and the per-component accessibility pages defer to the APG pattern, in which a radio group handles Up/Down as well as Left/Right and wraps from last to first.
• Library does: resources/views/components/theme-toggle.blade.php:38-39 handles only keydown.arrow-right / keydown.arrow-left, via $el.nextElementSibling / previousElementSibling, so there is no wrap (Right on "System" and Left on "Light" do nothing), no Up/Down, and no Home/End. aria-checked="false" is also rendered on all three server-side (:33), so before Alpine boots the group reports nothing checked.
• Fix: fixed by N-04 — <x-group> uses native radios in a fieldset, where the browser supplies wrap, both axes and the roving tab stop. If N-04 is not taken, add arrow-down/arrow-up, wrap with nextElementSibling ?? firstElementChild, and render the initial aria-checked from the server default.
• Effort: S (as part of N-04)
• Breaks API? no

N-18 · tabs · the primary active indicator is missing its 2dp side inset

• Severity: should-fix
• M3 says: "Primary tab active indicators are additionally inset 2dp on each side" (RCB §Tabs/Specs, from tabs/specs page text); "Active indicator minimum length 24dp".
• Library does: resources/css/components/tabs.css:119-129 — inset-inline: 0 on [data-tab-indicator], which for a primary tab is scoped to [data-tab-content] (min-width: 1.5rem = the 24dp minimum ✓, tabs.css:108). The 3px height, the 3px 3px 0 0 corners and the 2px/square secondary variant are all correct; only the inset is absent.
• Fix: tabs.css, in the primary case: [data-tabs-bar]:not([data-variant="secondary"]) [data-tab-indicator] { inset-inline: 2px; }.
• Effort: S
• Breaks API? no

N-19 · navigation-bar-item · the state layer uses on-surface where the rail uses on-secondary-container

• Severity: should-fix
• M3 says: "The state layer's color equals the content's 'on' color" (RF §Interaction/States, state-layer mechanics). For navigation items androidx is explicit and uses one colour for active and inactive: ItemActiveHoveredStateLayer = ItemActiveFocusedStateLayer = ItemActivePressedStateLayer = ItemInactiveHoveredStateLayer = ItemInactiveFocusedStateLayer = ItemInactivePressedStateLayer = OnSecondaryContainer (tok/NavigationRailColorTokens.kt). NavigationBarTokens.kt ships no state-layer tokens, so the rail's are the only stated ones for a navigation item.
• Library does: two different answers for the same kind of item. The rail is right — navigation.css:544-552 paints both ::before layers with var(--md-sys-color-on-secondary-container). The navigation bar is not: navigation.css:504-517 leaves background-color: var(--md-sys-color-on-surface) for [data-navigation-bar-item]'s indicator and pill layers. On an active bar item the pill is secondary-container, so the hover layer is an on-surface wash over secondary-container rather than the on-secondary-container the content uses.
• Fix: navigation.css, add [data-navigation-bar-item] :is([data-navigation-indicator], [data-navigation-pill])::before { background-color: var(--md-sys-color-on-secondary-container); } after the shared rule, matching the rail's treatment two blocks below.
• Effort: S
• Breaks API? no

N-20 · tabs · the focus ring is drawn inside the tab (outline-offset: -3px) instead of M3's 2px out

• Severity: nice-to-have
• M3 says: Foundations calls the indicator only "ring-like" and gives no number (RF §Interaction/States: "No thickness, offset, or color token is specified anywhere in Foundations"), but the library has picked one convention for the whole package — focus-ring = 3px secondary at outline-offset: 2px (resources/css/tokens/state.css:46-53), and the navigation bar/rail items follow it (navigation.css:554-583).
• Library does: resources/css/components/tabs.css:81-85 uses outline-offset: -3px, drawing the ring inside the tab's own box. (The likely reason is overflow-x: auto on the bar clipping an outward ring; the file says nothing about it.)
• Fix: either keep it and record the reason in tabs.css's header comment, or give the bar padding-block: 3px / scroll-padding-inline: 3px room and switch to outline-offset: 2px so tabs match every other focusable thing in the library.
• Effort: S
• Breaks API? no

N-21 · tabs · aria-current="page" gets the indicator but not the active label colour in the primary variant

• Severity: nice-to-have
• M3 says: primary tabs' active label is Primary; secondary tabs' is On surface (RCB §Tabs/Specs).
• Library does: resources/css/components/tabs.css:87-93 — the active colour rule for the primary variant matches only [aria-selected="true"], while the secondary rule matches :is([aria-selected="true"], [aria-current="page"]) and the indicator rule (:141) matches both. So a link-based tab bar (the pattern section-nav uses, section-nav.blade.php:65-70) built with variant="primary" would show the indicator but keep the label on-surface-variant.
• Fix: tabs.css:87 → [data-tab]:is([aria-selected="true"], [aria-current="page"]).
• Effort: S
• Breaks API? no

N-22 · navigation-rail · no vertical divider and no way to turn the container fill off

• Severity: nice-to-have
• M3 says: "Optional vertical divider separates rail from content, placed on the content-adjacent edge"; "container fill can be turned off (transparent) as long as items keep ≥3:1 contrast"; "If a layout scrolls horizontally, the rail can scroll off-screen or remain fixed. To distinguish that content is scrolling underneath the rail, use a divider or add elevation to the rail" (RCB §Navigation Rail/Behaviour; raw/components_navigation-rail_guidelines.md:456).
• Library does: navigation.css:196-215 always paints background-color: var(--md-sys-color-surface) and draws no divider; there is no prop for either (navigation-rail.blade.php:60-65 has only mode, label, width, menu).
• Fix: add a divider boolean prop rendering border-inline-end: 1px solid var(--md-sys-color-outline-variant) on [data-navigation-rail-panel], and a fill prop (default true) that sets background-color: transparent when false.
• Effort: S
• Breaks API? no (additive props)

N-23 · navigation-rail · the FAB → extended FAB transition is a display swap, not a morph

• Severity: nice-to-have
• M3 says: "Rail transitions from collapsed↔expanded should animate the FAB into/out of an Extended FAB" (RCB §Navigation Rail/Behaviour).
• Library does: the documented pattern is two FABs swapped by display (navigation-rail.blade.php:42-43, SKILL.md:737, showcase/shell.blade.php:48-49) — the collapsed one appears at once while the rail's width is still springing. The rail's own width is animated on the spatial spring (navigation.css:171), so the mismatch is visible.
• Fix: a single <x-fab> whose label is width-animated (grid-template-columns: 0fr → 1fr on the label span, ease-spatial-default) inside the rail-collapsed variant would morph instead of swap; or at minimum mention the limitation in SKILL.md.
• Effort: M
• Breaks API? no

N-24 · navigation-rail · mode="collapsible" has no width floor of its own

• Severity: nice-to-have
• M3 says: "Compact → don't use a standard rail, use a navigation bar" (RCB §Navigation Rail/Behaviour).
• Library does: only mode="adaptive" is width-aware (navigation.css:184-194). A collapsible or expanded rail keeps clamp(13.75rem, 16rem, 22.5rem) at 360px too — two-thirds of a phone screen. The docs point applications at <x-app-shell> for adaptivity, and the showcase only uses collapsible inside a bounded demo box, so nothing in-repo hits it; an application wiring a bare <x-navigation-rail mode="collapsible"> into a page layout will.
• Fix: a one-line guard in navigation.css — @media (width < 37.5rem) { [data-navigation-rail='collapsible'], [data-navigation-rail='expanded'] { width: 6rem; } } plus the matching rail-collapsed variant arm — or an explicit sentence in SKILL.md:735 that these two modes are fixed-width by design and belong behind a min-[37.5rem]: wrapper.
• Effort: S
• Breaks API? no

Deliberate deviations

• Expanded rail items are full-width pills, not label-hugging — navigation-rail-item.blade.php:18-19: "Compose's expanded item hugs its label; the package draws the full-width pill, which leaves room for the count at the end." Holds up. M3 says exactly this is allowed: the indicator "hugs the label text by default (can be overridden to fill the full container width, resembling the old navigation drawer style); target area always spans the full rail width" (RCB §Navigation Rail/Behaviour).
• No drop shadow on a scrolled app bar, colour change only — app-bar.css:12, :59-61. Holds up, and is the right reading. androidx has AppBarTokens.OnScrollContainerElevation = Level2, but the site is explicit: "On scroll: No drop shadow, instead a color fill creates separation from content" (raw/components_app-bars_overview.md:137).
• Medium/large flexible height keyed on whether a subtitle is present — app-bar.css:33-47 maps medium 112/136 and large 120/152 to without/with subtitle. Holds up: those are exactly ContainerHeight/LargeContainerHeight in tok/AppBarMediumFlexibleTokens.kt and tok/AppBarLargeFlexibleTokens.kt, and Compose's flexible app bars pick the taller one when a subtitle is supplied.
• Rail container is surface, modal is surface-container — navigation.css:210, :229. Holds up: tok/NavigationRailCollapsedTokens.kt ContainerColor = Surface; tok/NavigationRailExpandedTokens.kt ModalContainerColor = SurfaceContainer, ModalContainerElevation = Level2, ModalContainerShape = CornerLarge — all three reproduced exactly. (The site's colour list says "Surface container (optional container fill)"; androidx is the more specific source and the library follows it.)
• Every toolbar control stays in the Tab order rather than a roving tabindex — toolbar.js:4-5: "Every control stays in the Tab order, so a control added by a Livewire render is reachable without any bookkeeping." Holds up against M3 (though not against APG's toolbar pattern): M3's own accessibility page says "Initial focus lands on the first interactive element; Tab (or Arrows) moves between all others" (RCB §Toolbars/Accessibility).
• Section nav wraps onto a grid instead of scrolling — section-nav.blade.php:15-16: "tabs that scroll hid the last sections on a tablet." Does not hold up. M3 prescribes scrollable tabs for exactly this case and its accessibility page defends them explicitly ("Horizontal scrolling tabs meet accessibility requirements…", raw/components_tabs_accessibility.md:95), while the grid breaks the tab bar's divider and strands the indicators (N-16). If the grid is kept for product reasons, it should stop presenting itself as [data-tabs-bar].
• Small app-bar titles truncate with an ellipsis — app-bar.css:104-110. M3 says "Don't truncate the headline text" and "Don't wrap text in a small app bar" (raw/components_app-bars_guidelines.md:337, :347); its actual answer is "If headline text is long, use a medium flexible or large flexible app bar" (:342). Truncation is the only remaining web-sane behaviour, so this is a reasonable forced choice — but it is undocumented. Worth one line in the header comment pointing authors at variant="medium".

Aligned

• App bar: 64 / 112 / 136 / 120 / 152px heights; title-large + label-medium (small), headline-medium + label-large (medium flexible), display-small + title-medium (large flexible); 4px leading/trailing space; 0 gap between icon buttons; 16px title inset without a leading button; surface → surface-container on scroll; on-surface title / on-surface-variant subtitle and trailing icons / on-surface leading icon; square container. The pure-CSS collapse (negative sticky top + sticky inner row) is elegant and produces no layout shift; the flexible variants' row headline is aria-hidden so the real <h1> is never announced twice.
• Navigation bar: 64px, surface-container, square, items 0 apart, 56×32 CornerFull indicator, 4px icon–label space, 6px item vertical padding, 40px horizontal indicator with 16px leading/trailing, 24px icons, on-secondary-container active icon, secondary-container indicator, secondary active label (vertical) / on-secondary-container (horizontal), on-surface-variant inactive — all correct. The medium arrangement reproduces calculateCenteredContentHorizontalPadding (items occupy 10 × (count + 3)% of the bar) exactly, and it switches on a container query at 600px, so a bar in a narrow column keeps the compact layout.
• Navigation rail: 96px collapsed, clamp(220px, width, 360px) expanded, 44px top space, 40px header space (32 + 8), 4px between collapsed items, 64px collapsed item, 56px expanded item, 8px/4px icon–label spaces, 56×32 collapsed indicator, CornerFull. Modal = fixed, surface-container, elevation 2, CornerLarge on the inner edge, 32% scrim, x-trap.inert.noscroll, Escape, scrim click, focus returned to the menu button, closed on livewire:navigating. Badges move from the icon (collapsed) to the label end (expanded), which is M3's stated rule. State layers use on-secondary-container per NavigationRailColorTokens.
• Catalogue vs. Expressive: no bottom app bar, no navigation drawer, no baseline medium/large app bar, no baseline navigation bar — all four correctly skipped, and the expanded rail (standard + modal) is what stands in for the drawer, exactly as M3 Expressive directs.
• Tabs: 48px (64px stacked), 24px icons, 1px outline-variant divider, 3px primary indicator with 3px 3px 0 0 corners, 2px square secondary indicator, 24px minimum indicator length, 8px icon–label gap, title-small labels, primary/on-surface active colours, 8%/10% state layers, 38% disabled. Real tablist semantics, arrow keys + Home/End, disabled tabs skipped, aria-selected/tabindex rendered on the server, and the indicator moves in a view transition on the spatial spring with a reduced-motion escape.
• Toolbars: docked 64px / square / surface-container / 16px ends / 4–32px between items (as a clamp); floating 64px / CornerFull / surface-container / 8px ends / 4px between; vibrant = primary-container with on-primary-container ink and a surface-container + on-surface selected button — all matching tok/DockedToolbarTokens.kt and tok/FloatingToolbarTokens.kt. role="toolbar" + aria-orientation + RTL-aware arrow keys.
• Motion: all durations collapse to 0 under prefers-reduced-motion (resources/css/tokens/motion.css:63-75); spatial springs for size/position, effects easing for colour and opacity, throughout this group.
• Safe areas: the app bar pads the top inset, the navigation bar and rail the bottom inset, the docked toolbar the bottom inset — matching M3's safety-region rule.
• Links vs. buttons: navigation items are real <a>s with aria-current="page" (plus the filled icon and the indicator — the two-indicator rule) and degrade to <button> without a link; the section nav uses links with aria-current, not fake tabs.

Missing

M3 variants/configurations in this group with no implementation at all:

• Navigation bar, tall container (80dp) — NavigationBarTokens.TallContainerHeight = 80.0.dp (tok/NavigationBarTokens.kt). Only the 64px short bar exists (navigation.css:76); no prop selects the tall one.
• Navigation bar, hide-on-scroll — "Scrolling: hides on scroll-down, reappears on scroll-up — but never hide it while a screen reader is active" (RCB §Navigation Bar/Behaviour). Not implemented and not mentioned.
• Navigation rail, narrow collapsed width (80dp) — NavigationRailCollapsedTokens.NarrowContainerWidth = 80.0.dp. Only 96px (navigation.css:174).
• Navigation rail, centre alignment — "Alignment: top or center; on tablets prefer center alignment for reach. Menu icon and FAB are always top-aligned" (RCB §Navigation Rail/Behaviour). The rail is top-aligned only.
• Navigation rail, "hide when collapsed" as an explicit configuration — it is in M3's configuration table ("Expanded behavior | Hide when collapsed | — | Available"). The library gets it implicitly below sm in mode="adaptive", but there is no mode that hides a rail in an immersive wide layout.
• Docked toolbar with a FAB — M3's configuration table lists "Other elements | With FAB" for both toolbars; toolbar.blade.php:26 gates the fab slot on $variant === 'floating'.
• App bar, trailing-action overflow at small widths — "trailing actions collapse into an overflow menu at smaller breakpoints and reappear at larger ones" (RCB §Top App Bar/Behaviour). Not implemented (and M3 also tells you not to put an overflow menu in the app bar in the first place, so this is genuinely optional).
• Toolbar, large-screen treatments — "On web/large screens it can gain rounded corners and use dividers to organize many actions"; "medium+ breakpoints allow centering all elements or centering one key action while pinning others to the edges" (RCB §Toolbars/Behaviour). The toolbar has no breakpoint behaviour at all.

Correctly absent (deprecated in M3 Expressive, do not add): bottom app bar, navigation drawer, baseline medium/large top app bar, baseline navigation bar. theme-toggle mode="picker" is the one place a deprecated design slipped back in — see N-04.

Breakpoint map

M3's classes: Compact <600, Medium 600–839, Expanded 840–1199, Large 1200–1599, Extra-large ≥1600 (RF §Layout/Breakpoints). Tailwind's: sm 640, md 768, lg 1024, xl 1280, 2xl 1536.

Component / behaviour	Library breakpoint used	M3 class it stands in for	Gap
app-shell — bottom navigation bar shown; rail hidden, modal-only	max-sm < 640px (app-shell.blade.php:142, :87-88, :136; navigation.css:190-194, :235-279)	Compact (<600dp)	+40px. 600–639px is M3 Medium but is driven as Compact
navigation-bar — item layout vertical → horizontal	container 600px (navigation.css:123, :465, :519, :525, :555, :562)	Medium (600dp)	exact — and a container query, so it also works in a narrow column
app-shell — collapsed rail appears (96px), bar disappears	sm ≥ 640px	Medium (600–839dp)	+40px late; disagrees with the line above, so the horizontal bar layout only exists in a 40px band
app-shell / navigation-rail mode="adaptive" — rail becomes a standard, in-layout collapsible rail; menu button toggles instead of opening a modal	lg ≥ 1024px (js/navigation.js:16; navigation.css:51, :57, :184)	Expanded (≥840dp)	+184px. 840–1023px gets a collapsed rail whose expansion is modal, scrimmed, focus-trapped and re-closed by every wire:navigate; the remembered "expanded" preference is ignored
app-shell — content region max-lg:overflow-x-clip	lg 1024px (app-shell.blade.php:136)	Expanded (840dp)	+184px (a clipping backstop, no M3 rule attached)
section-nav — menu picker → secondary-tab row	sm 640px (section-nav.blade.php:40, :59)	Compact/Medium boundary (600dp)	+40px
section-nav — 3/4-column grid → single row	xl 1280px (section-nav.blade.php:33-34)	Large (1200dp)	+80px
showcase chrome — theme picker → cycle button	md 768px (showcase/layout.blade.php:148-149)	none (no M3 rule)	n/a — showcase only
app-bar, toolbar, tabs	none	Medium+ adaptive guidance (toolbar centring/rounded corners, app-bar action overflow)	not implemented (see Missing)

What a user actually sees in the three bands the brief asks about

• 600–639px (M3 Medium; e.g. a small tablet in portrait, a resized desktop window): no navigation rail at all — it is width: 0; display: none. The bottom navigation bar is still pinned, but it has already flipped to the Expressive medium configuration (icon beside label in a 40px secondary-container pill, items grouped in the middle at 10 × (count + 3)% of the width, label-large instead of label-medium per N-08). Any destination marked 'bar' => false is reachable only by an application-supplied menu button calling $store.rail.show(). At 640px the bar vanishes outright and a 96px collapsed rail appears — a jump, at the wrong number.
• 840–1023px (M3 Expanded; a landscape tablet, a half-screen desktop browser): a 96px collapsed rail with icon-over-label items. The menu button does not expand it in place — materialNavigationRail.modal is still true, so it opens the 256px rail over the page on a 32% scrim with a focus trap, and livewire:navigating closes it again, so choosing a destination means re-opening the rail every time. $store.rail.collapsed === false (the visitor's remembered choice, applied to <html data-rail> before first paint) has no effect here. M3 lists a standard expanded rail for this whole band.
• 1200–1279px (M3 Large): no mismatch — lg (1024px) is long past, so the rail is already the standard collapsible one, expanded by default and remembered in localStorage, which is what M3 wants at Large. The only thing that changes at 1280px is section-nav's grid → row switch (N-07's xl row above), which is 80px later than M3's 1200dp Large boundary. Nothing in the group does anything different at 1600px (Extra-large), where M3 suggests considering a third pane.