# Tooltip System

## Objective

Give every control the same short, reachable explanation on hover and on focus.

One tooltip component with consistent timing, placement, accessible naming, and dismissal across the app.

## 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 every ad-hoc hint in the app — native title attributes, hand-rolled bubbles, help text hidden behind an icon — and replace them with one component so timing and styling stop varying by screen.
2. Show tooltips on pointer hover and on keyboard focus alike. A tooltip only a mouse can reach is invisible to a portion of your users.
3. Use a short opening delay and a shorter closing one, and share the delay across the group so moving along a row of icon buttons does not replay the opening delay for each.
4. Decide per tooltip whether its text names the control or describes it, and associate it accordingly — an icon-only button usually needs a name, a labelled field usually needs a description.
5. Placement, flipping, and viewport clamping belong to the Popover Positioning Engine. Consume it rather than writing a second set of offset calculations here.

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

- Anything the user must read to complete the task — a validation rule, a required format, a warning about a destructive action — does not belong in a tooltip. Tooltips are unreachable on touch, invisible when printed, and gone the moment the pointer moves; put essential instructions in persistent text.
- Touch devices have no hover state, so a tooltip bound to hover either never appears or appears on tap and then sticks until the user taps elsewhere. Decide explicitly: suppress it on touch, or bind it to a deliberate long-press that dismisses on the next tap anywhere.
- A tooltip near the edge of the window must flip or shift to stay fully visible, and must never be clipped by an overflow-hidden ancestor such as a table cell or a card.
- Escape must dismiss a visible tooltip without closing the surrounding dialog or menu, and the tooltip must never take focus, since a tooltip the user can tab into is a menu wearing the wrong clothes.
- A tooltip must not obscure the control it describes, nor the next control the user is heading for.
- The tooltip must disappear when its trigger is disabled, removed, or scrolled out of view, rather than lingering over unrelated content.
- A control that already has a visible text label rarely needs a tooltip repeating it; duplicating the label makes screen readers announce the same words twice.

## 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 hint in the app is rendered by the one tooltip component, with no native title attributes left behind.
- [ ] Tooltips appear on keyboard focus as well as pointer hover.
- [ ] No essential instruction or validation rule exists only inside a tooltip.
- [ ] Touch interaction has a defined behaviour that leaves no bubble stuck on screen.
- [ ] Tooltips stay within the viewport and are never clipped by an ancestor.
- [ ] Escape dismisses the tooltip only, and the tooltip never receives focus.
- [ ] Positioning is delegated to the shared positioning engine.
- [ ] 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.