# Drawer Layout Pattern ## Objective Use one side panel pattern for secondary work so the page underneath is never lost. A side panel with agreed widths, its own scroll region, its own URL, and defined behaviour on narrow screens. ## 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. Find the places the app currently pushes the user to a separate page for secondary work — editing a record from a list, viewing details, filters, a settings sub-section — and decide which of those belong in a drawer beside the context rather than instead of it. 2. Give the drawer its own address so the state can be linked, refreshed, and reached from a notification, and so the browser's back button closes it rather than leaving the page altogether. 3. Keep the drawer's scroll region separate from the page's, and preserve the page's scroll position so closing the drawer returns the user to exactly the row they opened it from. 4. Define two or three widths and a side, and apply them consistently. A drawer that is 400 pixels on one screen and 640 on the next reads as two different components. 5. Background scroll locking belongs to the Scroll Containment Utility and focus handling belongs to the Focus Containment Primitive. Consume both here rather than writing panel-specific versions. ## 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 - Below the mobile breakpoint a side drawer leaves a useless sliver of page behind it. Switch to a full-screen or bottom-sheet presentation at a defined width, and make the close control obvious in that mode. - The drawer and the page must scroll independently, and reaching the end of the drawer's content must not start scrolling the list behind it. - A drawer opened directly from a link must render correctly with no page state behind it, and the back button must close the drawer and reveal the underlying view rather than navigating out of the app. - Drawers that open further drawers quickly leave nothing of the original context visible and no clear way back. Either forbid nesting and replace the drawer's content in place with a back control, or cap it at one level. - Unsaved edits in a drawer must be guarded before it closes, including when it is closed by the backdrop, by Escape, or by the back button. - Opening a drawer must not resize or reflow the page behind it, or every row the user was reading moves at the moment they click. - The record the drawer is showing may be deleted or edited by someone else while it is open; the drawer needs its own error and removed states rather than closing without explanation. ## 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 side panel in the app uses the one pattern, with a defined side and one of the agreed widths. - [ ] The drawer has its own URL and restores correctly when that URL is opened directly. - [ ] The back button closes the drawer and leaves the user on the underlying page. - [ ] Drawer and page scroll independently, and the page's scroll position is unchanged on close. - [ ] Narrow screens present the drawer full-screen with an obvious close control. - [ ] Nesting is either prevented or capped, with a clear route back to the previous content. - [ ] Scroll locking and focus handling are delegated to the shared primitives. - [ ] 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.