> **Accepted and implemented in R019:** optional primary elevation and quieter role-specific pressed feedback now live in the shared Sass. Routine actions remain flat; disabled/busy shadows disappear immediately. See [current rules](actions-usage.md#button-elevation-and-pressed-feedback--accepted-r019) and the [current reference](../actions.html). The review below is historical decision evidence.

# M4 button UX review — elevation and interaction states

R018 responds to the user's request to review button shadows within M4. Card/overlay elevation remains M5. Shared actions.css/Sass and accepted palettes are unchanged in this run. The recommendation is a separate [live review](../button-ux-review.html), with [light](reference/button-ux-light-1200.png) and [dark](reference/button-ux-dark-1200.png) comparisons. Some previews pin a labeled state for inspection; actual pointer/keyboard interactions were checked separately.

## Recommendation

Keep ordinary navigation, secondary, toolbar, icon and destructive actions flat by default. Color, labels, placement and grouping already establish the hierarchy. Use an optional small elevation only when one dominant primary action needs additional separation from its surface. Primary does not automatically mean raised, and an action being destructive does not justify extra elevation. Icons also remain optional by use case.

The source Apply elevation is valid for its stand-alone footer context. It should not become the default for Next, Back, toolbar controls or chips. A tighter neutral contact shadow is proposed for the shared optional variant because the wizard's card already has considerable blur/translucency. This is a context-specific recommendation, not a claim that all colored shadows are wrong.

## Source findings and implementation gap

The measured wizard Next/Back/Import/add-row buttons have no box shadow. Apply uses the source blue at 20% in two layers: 0 10px 15px -3px and 0 4px 6px -4px. [Actual light Apply including its shadow](reference/button-source-shadow-light.png) · [dark](reference/button-source-shadow-dark.png) · [computed source evidence](reference/button-source-shadow.json).

The R014 button thumbnails were cropped to element bounds and clipped exterior shadows. They were adequate for control geometry, not elevation evaluation. R018 recaptures Apply with 40px surrounding padding and does not invoke the action. The shared M4 Apply implementation currently omits its source shadow entirely; that is now explicitly documented rather than silently treated as complete source parity.

## State-by-state assessment

| Area | UX assessment | Proposed rule |
|---|---|---|
| Default | Adding shadows to every button would compete with the primary fill and card grouping | Flat by default; opt-in small elevation only |
| Hover | A small contact-shadow increase can help the optional raised action; movement adds little here | Stronger shadow on that variant only, no translate/scale or hit-target movement |
| Pressed | Current 2px currentColor inset produces a conspicuous extra stroke, especially white on the dark primary | Darker role-appropriate fill and a subtle inset contact shadow; flatten exterior elevation |
| Keyboard focus | Focus and elevation communicate different things | Retain the explicit outline in both themes. A shadow must never be the only keyboard-focus indication |
| Disabled / busy | Hover/pressed/elevation cues would imply availability | Flat, no press/hover elevation; native disabled and aria-busy remain behavioral contracts |
| Selected chips | Selection is persistent; press is momentary | Keep selection in aria-pressed, fill/border/text. No raised shadow on chips or passive badges |
| Dark mode | A saturated glow can blur the distinction between elevation, selection and focus | Prefer subtle neutral occlusion and readable fill/border contrast; do not solve separation with a stronger blue glow |
| Dense toolbars / icon actions | Multiple raised controls create noisy visual competition | Keep flat, maintain spacing and accessible names; evaluate target size separately |

The existing 2px focus outline / 3px offset is intentionally retained in this proposal. It can visually coexist with a small rest shadow; shadows should not obscure its edge. If a consumer clips overflow around a button group, verify that focus is still visible rather than using more shadow to compensate.

## Review-only proposed values

| State | Light | Dark |
|---|---|---|
| Optional raised rest | 0 1px 2px black/16 | 0 2px 4px black/28 |
| Optional raised hover | 0 2px 4px black/18 | 0 3px 6px black/32 |
| Press contact | inset 0 1px 2px black/18 | same |
| Primary pressed fill | #003366 → #004a8f | original primary stops at 75% alpha |
| Disabled elevation | none | none |

These values live only in button-ux-review.css. They are not shared tokens yet. If adopted, introduce explicit button elevation/state roles in Sass and update the current active treatment; do not silently reuse card shadows. Define secondary/destructive/chip pressed colors by their own roles rather than copying the primary gradient into every action.

## Verification and practical limits

[Review browser results](reference/button-ux-verification.json): both themes at 1200/390px, plus 320px reflow. Actual hover increases the proposed raised shadow; held pointer changes to an inset contact shadow and darker primary fill. Dimensions and transform stay stable. Disabled examples remain flat/unfocusable. Keyboard focus remains visible; forced colors removes proposed shadows and retains focus, reduced motion removes transitions. Local clicks announce demo feedback. No page exceptions or attempted write requests were observed.

Source Apply was inspected in both themes with no Apply/Export/Import call. Reference repositories remain clean. This run makes no global conformance claim or cross-browser certification; the new pressed palette still needs contrast sampling across supported surfaces before shared adoption. Touch does not have hover, so the proposal remains understandable at rest/pressed/focus. The compact 34px toolbar from the source is a separate touch-target policy decision; no target-size change is hidden in this shadow review.

## Next bounded action

Review this recommendation within M4. Then adopt the chosen optional elevation and pressed feedback into the shared Sass, measure all affected roles/states and update the action guidance before marking M4 complete. Do not defer button elevation to the later card/shadow milestone.