# Layout Debug Mode

## Objective

Reveal the container, grid, and scroll structure behind a layout that is misbehaving.

A toggleable mode that visualises layout containers, grid and flex tracks, scroll regions, and stacking contexts in the running interface.

## 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. Identify the structures that actually cause layout bugs — grid tracks, flex containers and their direction, scroll containers, positioned ancestors, and overflow clipping — and visualise those specifically rather than outlining every element indiscriminately.
2. Label each visualised region with what it is and, where the app's components are identifiable, which component owns it, so a developer can go from a wrong-looking box to the file that produced it.
3. Let the reviewer filter what is shown, by structure type or by component, because a page with four hundred boxes lit up at once is less legible than the page was without the tool.
4. Draw everything with outlines or overlaid layers that occupy no space in the flow, and confirm by comparison that toggling the mode changes no element's measured position or size.
5. Do not confuse this with CSS Debug Outlines, which owns the blunt everything-gets-a-border switch applied from a single stylesheet. This feature owns the structural, labelled, filterable view; keep one toggle for each and do not have both on by default.

## 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

- Adding borders shifts every box on the page and invents the bug you were hunting. Use outlines or a separate overlay layer so no dimension changes when the mode is on.
- Nested containers three or four deep become an unreadable pile of rectangles; vary treatment by depth and place labels so an inner region's label does not obscure its parent's boundary.
- Filtering by component depends on components being identifiable in the DOM; if the app strips that information in production-like builds, the mode must degrade to structural labels rather than showing nothing.
- The mode must be restricted to development builds or explicitly authorised internal users. A customer who finds the toggle sees the app's internal component names and structure.
- Scroll containers and clipping ancestors are the point of the exercise — mark which element is actually scrolling and which is clipping, because those are rarely the ones people assume.
- The mode must survive navigation within the app rather than switching itself off on every route change.
- Elements rendered outside the main tree, such as portalled dialogs and floating menus, must be visualised too, or the mode is blind to exactly the components that most often break.

## 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

- [ ] Grid tracks, flex containers, scroll regions, and clipping ancestors are each visualised distinctly.
- [ ] Toggling the mode changes no element's measured position or size.
- [ ] Regions are labelled with their structure type and, where available, their owning component.
- [ ] The visualisation can be filtered by structure type or component.
- [ ] The mode is unavailable to unauthorised users and absent from production builds.
- [ ] Portalled and floating content is visualised alongside in-tree content.
- [ ] The mode persists across in-app navigation.
- [ ] 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.