> **R021 follow-up:** shared surface CSS and native-dialog examples are implemented locally. [Current usage](surfaces-usage.md) records the explicit semantics and contrast refinements. The audit below remains source evidence; M5 visual acceptance is pending.

# M5 — wizard cards, dialogs and elevation audit

R020: source inspection and live verification complete. Shared card/dialog CSS is not implemented in this run. [Actual source gallery](reference/wizard-cards.html) · [measured styles and behavior](reference/cards/wizard-cards.json) · [dark dialog family comparison](reference/card-dialog-comparison-dark.png) · [light comparison](reference/card-dialog-comparison-light.png).

Reference commit: eab1a9a72ea8ca036be292420b8e5c95f19fd7f7. Actual Network/Devices panels, Add Device and Template Library dialogs were measured in both themes at 1200/768/390px. Review summaries are source-traced only in this run. No configuration was saved, exported, applied or submitted; zero page exceptions and attempted non-GET requests were recorded.

## Import/implementation trace

ConfigWizard and its step components use inline div/motion.div surfaces and utility classes. They do not import generic ui/card.tsx. AddDeviceModal portals its dialog/backdrop; TemplateLibraryModal renders a separate motion overlay family. Generic Card/CardHeader defaults are supporting references, not the measured wizard implementation.

- [ConfigWizard main card/content](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/ConfigWizard.tsx#L535), [action footer](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/ConfigWizard.tsx#L589)
- [NetworkStep inset DHCP panel](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/wizard-steps/NetworkStep.tsx#L120)
- [DevicesStep table surface](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/wizard-steps/DevicesStep.tsx#L88)
- [ReviewStep summary panels — source-only here](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/wizard-steps/ReviewStep.tsx#L59)
- [AddDeviceModal scrim/dialog/header](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/AddDeviceModal.tsx#L165), [choice cards](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/AddDeviceModal.tsx#L232)
- [TemplateLibraryModal overlay/dialog](https://github.com/SebastianTamayo/Wsdmmcentral/blob/eab1a9a72ea8ca036be292420b8e5c95f19fd7f7/src/app/components/TemplateLibraryModal.tsx#L143)

## Verified surface families

| Family | Geometry and spacing | Light | Dark |
|---|---|---|---|
| Main wizard card | Radius 16px mobile / 24px at ≥640px; content padding 16px / 24px at ≥640 / 32px at ≥1024; 1px border | White, gray-200 border, no shadow/blur | White/10, white/20 border, 40px blur, no shadow |
| DHCP inset panel | Radius 14px, padding 16px, 1px border | Gray-50, gray-200 border | White/5, white/10 border; no blur/shadow |
| Device table panel | Radius 14px, outer padding 0; header/body supply their own spacing | White, gray-200 border | White/5, white/20 border; no blur/shadow |
| Add Device dialog | Max width 672px; radius 16px all measured widths; max height 90vh with internal vertical scrolling | White, gray-200 border | Gray-900/95, white/20 border, 24px blur |
| Add Device header | Padding 16px mobile / 20px block and 24px inline at ≥640; sticky top | White, gray-200 divider | Gray-900/95, white/10 divider, 24px blur |
| Template Library dialog | Max width 896px; radius 14px mobile / 16px at ≥640; outer padding 0; flex body scrolls | White, gray-200 border, dialog shadow | White/10, white/20 border, 40px blur, no shadow |
| Template header | Padding 16px mobile / 24px at ≥640 | Transparent over white dialog | Transparent over glass dialog |

Add Device has the source shadow-2xl in both themes: 0 25px 50px -12px black/25. Template Library uses that shadow only in light mode. Add Device scrim is black/60; Template scrim black/50; both use 8px backdrop blur. Do not flatten translucent colors into sampled hex swatches: the actual page/scrim layers determine appearance.

At 390px the main card measures 366px wide, Add Device 358px and Template 374px, reflecting different outer gutters. At 1200px they measure 1088px, 672px and 896px. Do not turn one observed fluid width into a universal fixed card width.

## Interaction and source conflicts

- Main/inset/table surfaces are static containers. They have no source hover elevation. The old control skill suggests hover lifting interactive cards by 2px and a universal glass shadow; those are not verified rules for these wizard cards. Keep static cards flat.
- Add Device type choices are actual buttons with 14px radius, 16px padding and a 2px contour. Hover/selection changes border/fill; selection was verified locally for DAU. Their single-choice interaction needs a separate semantic contract (prefer native radio choices/group naming), not a click handler on every card div. No device was added or saved.
- Dark dialog families conflict: Add Device is nearly opaque gray; Template Library is glass over the dimmed blue page. Retain explicit roles/variants rather than claiming one universal source modal fill.
- Both measured overlays lack explicit role=dialog, aria-modal and aria-labelledby on their surface elements. Escape did not close either dialog, and focus remained outside immediately after opening in the measured mobile sessions. This probe did not exhaustively test every Tab sequence or screen reader; do not infer a fully verified source focus trap. The shared standard must fix semantics, initial focus, Escape, focus containment and return-to-trigger behavior.
- Template header uses a white-alpha divider in both themes, which is nearly invisible over the light white surface. Use an explicit theme-appropriate separator in the standard when separation is meaningful; do not silently treat this utility as universal.
- The supplied guide's rounded blue usage example does not define dialog blur/elevation rules. The old skill and generic Card wrapper also cannot override these actual measured families. Earlier generated previews remain non-authoritative.

## Proposed tokens and implementation plan

Reuse existing page/card surface roles. Add only the missing semantic geometry/elevation roles, keeping their purpose explicit:

| Proposed role | Source-backed starting value |
|---|---|
| card-radius / card-padding | 16px and 16px mobile; 24px/24px at ≥640; padding 32px at ≥1024 |
| panel-radius / panel-body-padding | 14px / 24px, with inset padding 16px separate |
| dialog-radius / dialog-max-width | Dense Add Device 16px / 672px |
| dialog-glass-radius / dialog-glass-max-width | 14px mobile, 16px desktop / 896px |
| surface-dialog / dialog-blur | White light; dark gray-900/95 and 24px blur |
| surface-dialog-glass / dialog-glass-blur | White light; dark white/10 and 40px blur |
| dialog-scrim / dialog-glass-scrim / scrim-blur | Black/60, black/50, 8px |
| shadow-card / shadow-panel | none |
| shadow-dialog / shadow-dialog-glass | Dense: source 2xl both themes; glass: 2xl light, none dark |

Names are proposed API, not implemented CSS custom properties. Preserve Tailwind 4 OKLCH values for source gray roles, rather than older palette approximations. Keep button elevation independent; M4 optional button shadows do not become card shadows.

Next bounded implementation:

1. Add an opt-in Sass/CSS surface component layer with static card, inset/panel, and explicit dense/glass dialog roles. Theme remains variables/scopes only. Keep header/body/footer structure and spacing distinct.
2. Build a local reference reusing accepted typography, fields and actions. Compare actual source captures with live components in both themes, desktop/tablet/mobile. Demonstrate long content and narrow-screen scrolling.
3. Use native modal dialog behavior where possible, with a named heading, accessible close button, initial focus, Escape and focus restoration. Do not copy source numeric z-index 9999 as the modal interaction model. Make scrim-dismiss behavior explicit; protect unsaved state where applicable.
4. Keep cards flat; no automatic clickable surface or hover lift. Demonstrate single-choice cards with native radio semantics if included, labeled as an explicit standard refinement.
5. Verify rendered geometry, card/body/help text contrast over real translucent backgrounds, focus clipping and modal behavior. Note source-adaptation conflicts before adjusting shared colors. No broad palette changes or reference-app edits.

This audit does not certify source accessibility, contrast, all card families, every browser/OS, or unrendered confirmation/template-content states. Confirmation/success overlays and populated library item cards remain source-only/unverified in this run. M5 remains active.