# Pointer Modality Styles

## Objective

Make hover, focus, and hit targets behave correctly for mouse, touch, pen, and keyboard.

Input-aware styling and interaction rules so each pointer type gets the affordances it can actually use.

## 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. Audit the app for interactions that assume a mouse: hover-revealed row actions, tooltips that carry information available nowhere else, tiny icon buttons, and drag handles that only appear on hover.
2. Gate hover styling on the device genuinely supporting hover, rather than on screen width. A touchscreen laptop is wide and cannot hover reliably; a stylus tablet is narrow and can.
3. Raise the hit area for coarse pointers without changing the visual size of the control. The user should get a larger target, not a bigger-looking button that breaks the layout.
4. Keep the focus indicator visible for anyone navigating by keyboard, and suppress it only for pointer-initiated focus. Removing focus rings outright to tidy up mouse interaction makes the app unusable without one.
5. Do not resolve pointer type once at load and cache it for the session. Users plug in a mouse, pick up a pen, and switch to the keyboard mid-task, and a cached answer is wrong from that moment on.

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

- Hybrid devices have more than one pointer at once — a laptop with a touchscreen, a tablet with a keyboard and trackpad case — so any rule that treats input as a single fixed capability will be wrong for one of them. Style from the capability being used now, and let the coarse-pointer accommodations remain available even when a mouse is attached.
- The keyboard focus indicator must never be hidden. It is the only way a keyboard user can tell where they are, and suppressing it to clean up mouse clicks removes the app's navigability rather than its clutter.
- Any action available only on hover is unreachable on touch. Row actions, delete buttons, and drag handles revealed by hover need a persistent or explicitly summoned equivalent — a visible control, a long press, or an overflow menu — and hover may only be an accelerator on top of it.
- Modality must be re-evaluated continuously during a session. A user who starts with touch and then attaches a keyboard should get focus rings from the next keypress, without reloading the page.
- A single interaction can produce both touch and mouse events, so logic keyed to a pointer type must not fire twice or leave a control stuck in a hover state after a tap.
- Tooltips that carry information found nowhere else are inaccessible to touch and to screen readers alike, so the underlying content must exist in the accessible name or visible copy, with the tooltip as a convenience.
- A stylus is a fine pointer with no hover on some devices and hover on others, so it must not be lumped in with touch and given oversized targets it does not need.

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

- [ ] Hover styling is applied only where the device actually supports hover, not inferred from viewport width.
- [ ] No action exists that can be reached by hover alone.
- [ ] Keyboard focus is always visible, and focus styling is suppressed only for pointer-initiated focus.
- [ ] Coarse pointers get an enlarged hit area without a change in the control's visual size.
- [ ] Switching input method mid-session changes the affordances without a reload.
- [ ] A single tap produces one interaction, with no lingering hover state left behind.
- [ ] 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.