fix: Modal appearance props now apply to the dialog card

[adrienzheng-cb]

What changed? Why?

Closes CDS-2213.

Modal inherits the full Box prop surface, but every extra prop was spread onto ModalWrapper's full-viewport backdrop container rather than the visible dialog. As a result, appearance props such as borderRadius, background, padding, elevation, and borders were applied to an invisible full-screen element and had no visual effect.

This PR does two things:

1. Bugfix — route appearance/sizing props to the dialog. A curated set of card-appearance props (borderRadius + corners, background, color, borderColor/borderWidth + sides, bordered*, elevation, padding*) now forwards to the visible dialog card (the inner VStack), and card-sizing props (minWidth/minHeight/maxHeight) forward to the sizing shell — extending the pattern already used for width/maxWidth. Container/positioning/behavior props (alignItems, justifyContent, position, pin, hideOverlay, role, zIndex, className, style, …) still target the backdrop container, so those remain unchanged. The previously hardcoded borderRadius={200} and elevation={2} become defaults. The same class of bug exists on mobile (props were swallowed by React Native's Modal); those props now forward to the modal surface.

2. New styles/classNames slot API. Web adds modalClassNames and StylesAndClassNames with selectors root (backdrop container) and surface (card). Mobile adds a styles slot with surface and content (safe-area region). This gives consumers explicit, unambiguous control going forward.

Root cause (required for bugfixes)

Modal has two boxes: the full-viewport backdrop/positioning container (ModalWrapper) and the visible rounded dialog card (the inner VStack, whose radius was hardcoded to 200). All non-explicitly-destructured props were spread onto the backdrop container via {...props}, so appearance props like borderRadius landed on the wrong (and invisible) element instead of the card.

UI changes

No change to default appearance. Behavior change only affects consumers who pass appearance props (e.g. borderRadius) — those now visibly apply to the dialog instead of silently doing nothing.

Web Old	Web New
borderRadius was a no-op	borderRadius applies to the dialog card

Follow-up

This PR is intentionally non-breaking: ModalProps still inherits the full BoxProps surface, so props that aren't meaningful on the backdrop container remain accepted (and mostly inert). Tightening that surface to an intentional Pick (and routing the few real-world escape-hatch props — visibility, display, overflow — through styles.root via a migrator codemod) is tracked as a v10 breaking change in CDS-2216.

Testing

How has it been tested?

• Unit tests
• Interaction tests
• Pseudo State tests
• Manual - Web
• Manual - Android (Emulator / Device)
• Manual - iOS (Emulator / Device)

Testing instructions

• Web: yarn nx run web:test --testPathPattern="overlays/modal/__tests__/Modal.test.tsx" (added tests for static class names, classNames slot, styles slot, and that appearance styles land on the dialog and not the root).
• Mobile: yarn nx run mobile:test --testPathPattern="overlays/modal/__tests__/Modal.test.tsx" (added a test that the surface styles slot reaches the surface).
• Typecheck: yarn nx run web:typecheck and yarn nx run mobile:typecheck.

Note: the mobile Modal is full-screen, so borderRadius on the surface is not visually meaningful there — the prop now applies rather than being dropped, and background/padding/styles are the useful knobs.

Change management

type=routine
risk=low
impact=sev5

automerge=false

Made with Cursor

[linear]

CDS-2213

CDS-2216

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 1 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1
CODEOWNERS	🟡 See below

🟡 CODEOWNERS

Code Owner	Status	Calculation
ui-systems-eng-team	🟡 0/1	Denominator calculation Additional CODEOWNERS Requirement Show calculation Sum 0 0 From CODEOWNERS 1 Sum 1

[github-actions]

https://percy.io/d424b72f/web/cds-mobile-visreg-03c97426/builds/50831399