# Unit Converter

## Objective

Let people convert a value between units without leaving the page they are on.

An inline converter that takes a typed value in one unit and shows the equivalent in another, in place.

## 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. Start from the units the app actually deals in. A shipping tool needs weight and length; a recipe tool needs volume and temperature. Ship those and leave the rest out.
2. Convert as the user types, with the result visible beside the input rather than behind a submit button. Let either side be edited so the conversion runs in both directions.
3. Reuse the app's existing number parsing and display formatting rather than writing new ones. If Locale-Aware Numbers and Dates or Number Formatting Component is already present, the converter must render through it so grouping and decimal marks match the rest of the app.
4. Hold the canonical value in a single base unit internally and convert out to whatever is displayed, so switching units repeatedly does not accumulate error.
5. Do not implement conversion as a flat table of pairwise multipliers. It grows quadratically, and the pairs nobody thought to add will silently return nothing.

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

- Converting a value out and back must return the value the user typed. Rounding the display separately from the stored value produces drift that shows up as 1 becoming 0.99999 after three switches.
- People type decimals with a comma as well as a period depending on their locale. Accept both on input, and do not treat a comma as a thousands separator in a field that expects a single number.
- Do not report more significant figures than the input justifies. Two inches converted to millimetres is not 50.800000 mm, and showing it that way implies a precision the user never gave.
- Temperature and some pressure scales have an offset as well as a ratio. A converter that only multiplies will get Celsius to Fahrenheit wrong for every value except zero.
- A request to convert between incompatible dimensions, such as kilograms to metres, must be refused with a clear message rather than producing a number. Only offer units in the same dimension in the target selector.
- Empty, partial, and non-numeric input must show nothing rather than an error or a zero. A user mid-keystroke has not made a mistake yet.
- Very large and very small magnitudes must stay readable. Decide whether to switch to exponential notation or to a larger unit, and apply the rule consistently.
- The converted value must be announced to screen readers when it changes, not only rendered visually next to the field.

## 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 value converted to another unit and back matches the original exactly.
- [ ] Both comma and period decimal separators are accepted on input.
- [ ] Displayed precision reflects the precision of the input rather than the float behind it.
- [ ] Offset scales such as temperature convert correctly across their whole range, including negatives.
- [ ] Only units in the same dimension are offered, and incompatible conversions are refused with an explanation.
- [ ] Numbers render through the app's existing formatting rather than a second implementation.
- [ ] Result changes are announced accessibly.
- [ ] 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.