# Core/Drawer - Design

## Behavior

### Modality

A contextual sheet can be **modal** or **non-modal**.

**Modal** sheets use a scrim to block interaction with the main page.

**Non-modal** sheets allow simultaneous interaction with the sheet and main page surfaces.
Non-modal sheets are best used for experiences that require a persistent but dismissible sheet that benefits from
interacting with the main page, like viewing location details on a map.

### Navigation

Navigating within a context sheet should be avoided where possible. If navigating is necessary, keep it shallow –
no more than 1 level deep.

When presenting a secondary view in a context sheet, the primary view content is replaced. The secondary view is
dismissed by making a selection or pressing a backward navigation button.

### Dismissing

Context sheets are dismissed by:

1. Pressing the close button
2. Confirming or cancelling the drawer
3. Interacting with the scrim (when present)
4. Pressing the escape key when the general sheet container is focused

In code, wire footer actions and other dismiss paths to `onClose`. A scrim is shown when the drawer
is **modal** (`modal`).

## Screen size

### Small screens

On small screens, the vertical height of a context sheet defaults up to 50% of the screen height. Scrolling the
sheet first slides it to full height before the content area scrolls.

### Medium and large screens

On larger screens, drawers are fixed to the **trailing** edge of the screen. Content that extends beyond the
vertical bounds of the drawer scrolls. Do not scroll horizontally. The drawer header and footer are pinned above the
scrolled content. Drawers have a min-width of 400px and max-width of 80% of the parent viewport.

## Best practices

### Stacking

**Do**

Keep interactions within context sheets on the sheet surface. Use inline progressive disclosure to reveal
additional or optional content.

**Don't**

Launch other context sheets over a context sheet.

### In-sheet navigation

**Do**

Keep navigation to a minimum within context sheets. Keep the navigation stack shallow when necessary, no more than
1 level.

**Don't**

Add deep or multi-level navigation stacks inside a single context sheet; prefer replacing content or using shallow
steps instead.

## Accessibility

### Keyboard interaction

| Key                 | Function                                                                                                                                       |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tab` / `Shift+Tab` | In **modal** mode, focus stays within the drawer while open. In **non-modal** mode, focus can move freely between the sheet and the main page. |
| `Escape`            | Closes the drawer whether focus is on the dialog surface or inside it (capture-phase listener).                                                |

### Roles and properties

* The panel uses `role="dialog"` with `aria-labelledby` (title) or `aria-label` as needed. While open, `aria-modal` is `true` for modal drawers and `false` for non-modal drawers.
* **Modal** mode: focus is trapped; `usePreventScroll` locks page scrolling. **Non-modal** mode: no focus containment or scroll lock on the document.
* The close control exposes an accessible name (“Close drawer”).
* When you add `Breadcrumbs` in the title, the trail is an ordered list with an `aria-label` of “Breadcrumb” by default; the last crumb should represent the current page (typically without an `href`).