# Modal — Figma Assembly Rules

<!-- figma-assembly.v2
{ "schemaVersion":"figma-assembly.v2", "id":"component.modal", "level":"organism", "kind":"local-composition", "aliases":["Modal","wbl-modal"], "uxSpec":"specs/ux/components/organisms/modal.md", "inventoryTarget":"modal", "componentKeys":[], "dependencies":[], "optionalDependencies":["component.button","component.divider","component.icon"], "coveredBy":["modal"] }
-->

Status: active Figma assembly contract.

## Scope

Use this sidecar when authoring or revising a `Modal` instance in Figma. It governs the editable Figma composition only; it does not define Angular/runtime API.

## Source Evidence

- [Content fits](https://www.figma.com/design/UdMX1VlLN9K7mdGcSoRCCv/%D0%A0%D0%B5%D1%84%D0%B5%D1%80%D0%B5%D0%BD%D1%81%D1%8B---%D0%A7%D0%B5%D1%80%D0%BD%D0%BE%D0%B2%D0%B8%D0%BA?node-id=2936-16918)
- [Body scrolls](https://www.figma.com/design/UdMX1VlLN9K7mdGcSoRCCv/%D0%A0%D0%B5%D1%84%D0%B5%D1%80%D0%B5%D0%BD%D1%81%D1%8B---%D0%A7%D0%B5%D1%80%D0%BD%D0%BE%D0%B2%D0%B8%D0%BA?node-id=2944-17304)

## Required Assembly

- Rule ID: `modal.instance` — use the published remote `Modal` instance. Never detach it or rename it.
- Use Auto Layout for the backdrop/root, every authored frame, Slot wrapper, and injected content wrapper. Do not manually position normal-flow content.
- Size the backdrop/root to the target screen. The desktop reference is `1440×900`; it is a fixed vertical Auto Layout frame that centers the Modal.
- Set root `paddingTop` and `paddingBottom` to `32px`. This is the viewport-safe gap for the panel, not body-content padding.
- Bind the backdrop fill to the exact `primitive/alpha-dark-50` token. Do not approximate it with a raw translucent paint.

## Height Modes

### Content Fits

- Rule ID: `modal.content-fits` — keep the Modal vertically `Hug`.
- Keep `Modal-content` and its body `Slot` vertically `Hug`.
- The backdrop centers the resulting panel inside its `32px` vertical safe area.

### Content Overflows

- Use this mode whenever the natural panel height exceeds the available safe area.
- Rule ID: `modal.content-overflows` — set the outer Modal, `Modal-content`, body `Slot`, and injected scroll-body frame to vertical `Fill`.
- Keep every parent in this Fill chain vertically `Fixed`; Figma cannot give a Fill child usable height under a Hug parent.
- Keep the body scroll-body clipped with vertical overflow. Its content grid stays Hug so it can exceed the viewport.
- Keep the header and footer fixed. Enable their scroll state so the header bottom stroke and footer top stroke are visible while the body scrolls.
- The underlying screen/backdrop does not become the scroll container.

## Slot And Content Rules

- Rule ID: `modal.slot-surface` — a body Slot must render without the `level-1` background and without a `level-1` fill binding.
- Prefer an explicit no-fill Slot override. If Figma treats an empty fill list as "restore the remote default", use an unbound transparent or hidden fill override instead; the visible result must still have no Slot background.
- Validate the Slot both structurally and in a screenshot. A hidden or transparent override is acceptable only when it removes the rendered `level-1` surface.
- Insert content through the real Slot. For repair-request details, use remote `Record` instances inside an Auto Layout wrapping grid; do not detach or rename the Record instances.

## Verification Checklist

- Root and all authored content frames use Auto Layout.
- Root has `32px` top and bottom padding and the exact alpha-dark backdrop token.
- The normal state uses the Hug height chain.
- The overflow state uses the Fill chain: Modal → `Modal-content` → Slot → scroll body.
- The scroll body is clipped, has vertical overflow, and its content is taller than the body.
- Header and footer stay fixed in the overflow state.
- No Slot renders or remains bound to `level-1`.
- Inspect screenshots for clipping, overlap, and an unintended page-level scroll.

## Maintenance

- Update this file in the same task after a user-confirmed reusable Modal correction affecting anatomy, sizing, Slot behavior, token binding, scroll, or state.
- Put one-off screen copy and data in the screen spec or run trace, not here.
- Replace stale or duplicate guidance instead of appending it. Keep this file at or below 300 lines.