# Dialog Size Rules

## Objective

Fix a small set of dialog widths so every modal in the app looks deliberate.

A defined set of dialog sizes with agreed maximum widths, scroll behaviour, and responsive treatment.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Inventory every dialog in the app and record its current width. The list will contain a spread of arbitrary values, and collapsing them onto four named sizes is most of the work.
2. Define the sizes by intent, not by pixel value in the calling code: a confirmation size, a standard form size, a wide size for tables and comparisons, and a full-screen size for genuinely large tasks.
3. Give every size the same internal structure — a header that stays, a body that scrolls, a footer that stays — so the action buttons never scroll out of reach in a long dialog.
4. Cap the dialog's height against the real viewport height rather than a fixed value, and put the overflow on the body region.
5. Do not let callers pass arbitrary widths as an escape hatch. The moment one screen can specify its own, the scale stops being a scale and the inventory you just consolidated grows back.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- The scroll must live in the body region only. If the whole dialog scrolls, the header and footer leave the screen; if the page behind scrolls instead, the user loses their place entirely.
- A confirmation with one sentence and two buttons stretched to a wide dialog reads as a mistake and makes the destructive button look far from the text it refers to. Match size to content, and keep confirmations small.
- Sticky headers and footers must survive at every size and at every content length, including when the body is short enough not to scroll, without leaving a gap or a doubled border.
- Below the mobile breakpoint, small and standard dialogs should become full-width sheets and the wide size should become full-screen, rather than a shrunken desktop dialog with cramped margins.
- A dialog containing a table wider than the dialog needs that table to scroll horizontally inside its own region, not to force the dialog wider or spill past its edge.
- The on-screen keyboard on mobile reduces the usable height sharply, and a dialog sized against the full screen height will push its footer under the keyboard.
- Long unbroken content — a pasted identifier, a URL, a stack trace — must wrap or scroll rather than widening the dialog past its declared size.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Every dialog in the app uses one of the named sizes, with no arbitrary widths remaining.
- [ ] Each size has a documented intent and a maximum width.
- [ ] Scrolling happens in the dialog body while the header and footer stay in place.
- [ ] Dialog height is capped against the real viewport, including when the on-screen keyboard is open.
- [ ] Confirmations use the small size and are never stretched.
- [ ] Small and standard dialogs become full-width sheets on mobile, and wide dialogs become full-screen.
- [ ] No dialog exceeds its declared size because of its content.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.