# Scroll Shadow Indicator

## Objective

Show people that a panel or table has more content past its edge.

Edge shading on scrollable containers that appears only on the sides where content continues.

## 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 containers that scroll independently of the page — tables, side panels, dialog bodies, tab strips, code blocks — and give each an edge treatment that appears only where content continues past that edge.
2. Recompute the indicators whenever the scroll position moves, the container resizes, or the content changes. A shadow that was correct at first render is wrong the moment a row is filtered out.
3. Handle both axes. A wide table needs left and right indicators far more urgently than top and bottom, because horizontal overflow is the kind users are least likely to guess at.
4. Draw the indicator so it never sits on top of a sticky header, a frozen first column, or a pinned action row. Those elements own their edge, and a shadow over them reads as a rendering fault — take the offsets from Safe Sticky Positioning rather than guessing at heights.
5. Do not leave a permanent shadow on every scrollable container. An indicator that shows when there is nothing more to see teaches users to ignore it, which defeats the whole point.

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

- Content that loads late, a filter that removes rows, or a section that expands all change whether overflow exists, so the indicators must be driven by live measurement rather than computed once when the container mounts.
- A container that scrolls on both axes needs four independent indicators, and the corner where two of them meet must not double up into a dark blot.
- A shadow drawn over a sticky header or a frozen column looks like a smudge rather than an affordance; the indicator has to sit beneath the pinned content or begin below it.
- Containers whose content fits must show nothing at all, including during the moment they briefly overflow while a resize is in progress.
- The indicator is decoration and must be invisible to assistive technology and transparent to pointer events. A shadow that swallows a click on the first row is worse than no shadow.
- Forced-colours and high contrast modes drop shadows entirely, so a container relying on one alone gives no hint of overflow — pair it with a border or accept the loss deliberately.
- Measuring on every scroll event in a long table is expensive; sample the position rather than forcing a layout calculation on each frame.

## 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 independently scrolling container indicates its edges only where content continues.
- [ ] Indicators update on scroll, on container resize, and when the content changes.
- [ ] Horizontal and vertical overflow are both indicated, including in containers that scroll on both axes.
- [ ] No indicator overlaps a sticky header, frozen column, or pinned row.
- [ ] Containers with no overflow show no indicator at all.
- [ ] Indicators receive no pointer events and are not announced to screen readers.
- [ ] Overflow remains discoverable in forced-colours mode.
- [ ] 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.