# CSS Debug Outlines

## Objective

Outline every box on the page from one switch, without touching component code.

A single development-only stylesheet that outlines and labels elements across the whole interface from one toggle.

## 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. Implement the whole thing as one stylesheet activated by an attribute or class on the document root, so nothing has to be added to individual components and the switch can be flipped anywhere in the app.
2. Use outlines, which are painted outside the box and take no space, rather than borders. Confirm the change by measuring a known element with the mode on and off.
3. Vary the outline treatment by nesting depth so a deeply nested tree remains readable rather than collapsing into one grey mass of coincident lines.
4. Allow the set of outlined elements to be narrowed by selector, so a developer chasing one region is not shown the entire document.
5. Do not use this as the app's structural debugging tool. Labelled grid tracks, scroll containers, and component-level filtering belong to Layout Debug Mode; this feature is deliberately the crude, zero-dependency switch, and the two must not be active at once.

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

- Borders and any change to padding or box sizing move the layout and manufacture new bugs; only outlines, box shadows, or an overlay layer are acceptable.
- Deeply nested markup produces overlapping outlines that read as a single thick line — cycle colour or opacity by depth so structure remains visible ten levels down.
- Selector filtering must be genuinely scoped, so restricting to one region does not still paint its ancestors and every sibling on the way down.
- The stylesheet must be excluded from production bundles entirely, not merely left inert behind an unset class. Verify against a built artefact.
- Elements with their own outline or focus ring must not have it overwritten, or keyboard focus becomes invisible while the mode is on.
- Replaced content such as images, canvases, and embedded frames will not show inner structure; outline the element itself and do not imply there is nothing inside.
- The toggle state should survive a reload during a debugging session rather than being lost on every refresh.

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

- [ ] One toggle outlines elements across the entire app with no per-component changes.
- [ ] Measured element dimensions are identical with the mode on and off.
- [ ] Nesting depth is distinguishable in the outline treatment.
- [ ] Outlining can be narrowed to a selector or region.
- [ ] Focus indicators remain visible while the mode is active.
- [ ] The stylesheet is absent from the production bundle, verified in the built output.
- [ ] 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.