# Spacing Overlay

## Objective

Measure the real gaps and padding between elements without leaving the running app.

A development overlay that draws the measured padding, margins, and gaps around and between elements, annotated with their values.

## 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. Measure from the rendered geometry rather than from the stylesheet, so what is drawn is what the browser actually produced after collapsing, flexing, and rounding.
2. Annotate each measurement with its value and, where the value matches an entry in the app's spacing scale, the token name — an unmatched value should read as a number alone so the discrepancy is visible.
3. Distinguish padding, margin, and container gap in the drawing, because the fix for each is different and a single undifferentiated band tells a developer nothing about where to edit.
4. Draw the overlay in a layer that ignores the pointer entirely, so hover states, tooltips, and drag interactions behave exactly as they do with the overlay off.
5. Do not implement your own grid rendering here. Typographic baselines and vertical rhythm belong to Baseline Grid Overlay, and container outlines belong to Layout Debug Mode; this feature owns measured distances between boxes and nothing else.

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

- Grid and flex containers distribute space through gap rather than margins, and adjacent vertical margins collapse into one — the overlay must report the resulting space once, correctly attributed, not the sum of two declarations that never both applied.
- A measurement that matches the spacing scale and one that does not must be drawn differently, because finding arbitrary values is most of the reason to run the overlay at all.
- Browser zoom and non-integer device pixel ratios produce fractional geometry; round for display but never round a 15px gap into a 16px token match.
- The overlay must never intercept pointer events. An overlay that swallows a click makes the interface it is measuring untestable and gets switched off.
- Elements that are transformed, rotated, or inside a scroll container need their measurements taken in the same coordinate space as the drawing, or the labels will float away from what they describe.
- Dense layouts will overlap their own labels; suppress or defer labels below a legible size rather than stacking unreadable text.
- The overlay must reposition on scroll, resize, and layout change, or it silently starts describing where things used to be.

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

- [ ] Padding, margin, and gap are drawn distinctly and labelled with measured values.
- [ ] Values matching the spacing scale are visually distinguished from arbitrary ones.
- [ ] Collapsed margins and flex or grid gaps are reported once, attributed to the property that produced them.
- [ ] The overlay intercepts no pointer events and changes no hover or focus behaviour.
- [ ] Measurements stay aligned to their elements under browser zoom, scrolling, and resize.
- [ ] Baseline grid and container outlining are delegated to their own features rather than duplicated here.
- [ ] 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.