# Signature Pad

## Objective

Let someone sign with a finger, stylus, or mouse and attach it to a document.

A drawing surface that captures a handwritten signature and stores it against the record being signed.

## 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. Place the pad where the signing actually happens, inside the existing form or document view, so the user is not sent to a separate screen and back.
2. Store the captured signature through the app's existing file storage and access rules, and treat it as private. A signature image readable by anyone with the URL is a forgery kit.
3. Record who signed, when, on what record, and from what session alongside the image. The picture alone proves nothing.
4. Offer a typed-name alternative next to the drawing surface and give it equal standing, since drawing with a mouse is unpleasant and impossible with a keyboard or screen reader.
5. Do not present this as a legally binding electronic signature workflow. If the app already integrates a signature provider, route contracts there and keep this for in-app acknowledgements.

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

- Drawing at logical pixel size on a high-density screen produces a signature that looks soft when displayed and worse when printed. Scale the drawing surface to the device pixel ratio and capture strokes at that resolution.
- A clear control that resets the surrounding form as well as the signature will lose the user's work. Scope clear to the signature only, and provide an undo that removes the last stroke rather than everything.
- On touch devices a drag across the pad scrolls the page instead of drawing. Suppress scrolling and pull-to-refresh over the pad while a stroke is in progress, and restore normal behaviour the moment the finger lifts.
- A signature stored without a timestamp, signer identity, and the version of what was signed is unusable as evidence. Persist that context in the same write as the image, and prevent it being edited afterwards.
- A typed-name alternative must produce the same signed record as a drawn one, with the same context stored, so assistive technology users are not pushed into a lesser path.
- An empty or accidental single-dot signature must be rejected before submission rather than saved as a valid mark.
- Losing connection during submission must not clear the drawn signature. Keep it on screen and allow a retry.
- The stored signature needs a stated retention period and a defined answer for what happens to it when the signer's account is deleted.

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

- [ ] A signature can be drawn with finger, stylus, or mouse and saved against the record.
- [ ] Captured strokes render sharply on high-density screens and in print.
- [ ] Clear resets only the signature, and undo removes a single stroke.
- [ ] Drawing on a touch device does not scroll or refresh the page.
- [ ] Each signature is stored with signer identity, timestamp, and the version of what was signed.
- [ ] A typed-name alternative produces an equivalent signed record.
- [ ] Stored signatures are private, with a stated retention period.
- [ ] 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.