# Motion Token System

## Objective

Give the app one shared vocabulary of durations and easing curves instead of ad hoc numbers.

A named set of durations and easing curves, each tied to a category of motion, replacing the timing values scattered through the app's components.

## 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. Inventory every duration and easing value currently written into the app and group them by what they do: something entering, something leaving, something being emphasised, and something changing size or position.
2. Name a small set of durations — roughly instant, quick, standard, and deliberate — and a small set of curves, then map each motion category to a pairing. Four or five of each is enough for an entire product.
3. Give entrances and exits different treatment. Something arriving should decelerate into place; something leaving should accelerate away and take less time, because nobody wants to wait for a dismissal.
4. Define a reduced-motion value for every token rather than a single global switch that sets everything to zero. Some motion should shorten, some should become a cross-fade, and some should vanish entirely.
5. Do not use a single easing curve for everything. A curve that suits a panel sliding in makes a hover state feel sluggish, and the same curve on a layout change reads as the interface hesitating.

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

- Every token needs a defined behaviour when the user has asked for reduced motion, and the answer is not always zero — a shortened fade often communicates better than an instant jump.
- One curve applied to every kind of motion is the failure this feature exists to prevent; entrances, exits, emphasis, and layout changes each need their own pairing.
- Motion attached to something a user does many times an hour — a menu opening, a row expanding — must sit at the short end of the scale, because a duration that feels elegant once feels like lag on the fiftieth repetition.
- Interrupting a transition partway through must resolve from the current position rather than snapping to the start, or rapid clicking produces visible jumps.
- This entry owns the values only. Which properties are allowed to animate and where motion is omitted belongs to Transition Consistency, and the mounting and unmounting lifecycle belongs to Enter and Exit Animation Pattern.
- Durations must survive being read from a stylesheet by scripted animation too, so the two do not drift apart.
- Tokens need to be inspectable at runtime, or nobody will be able to tell which one a given element is using when it looks wrong.

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

- [ ] Durations and easing curves are defined once as named tokens and referenced everywhere.
- [ ] No component in the app carries a hardcoded duration or curve.
- [ ] Entrances, exits, emphasis, and layout changes each map to a distinct pairing.
- [ ] Every token has a defined reduced-motion counterpart.
- [ ] Frequently repeated interactions use the shortest durations in the scale.
- [ ] Scripted animation and stylesheet animation read the same token values.
- [ ] 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.