# Duplicate Component Detector

## Objective

Find the components that solve the same problem twice before a third one appears.

An analysis that groups components with near-identical structure, styling, or usage and reports them as consolidation candidates.

## 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. Compare components on both what they render and how they are used. Structural similarity alone groups every small wrapper together, and usage similarity alone misses two implementations of the same card that happen to sit in different areas.
2. Read the component list produced by Component Inventory rather than walking the source again. Inventory owns enumeration and usage counts; this feature owns similarity and the consolidation decision.
3. Report candidates with the evidence attached — which parts matched, how many usages each has, and which is older — so a human can judge rather than being handed a verdict.
4. Treat domain differences as real. Two dialogs that look alike but one confirms a destructive action and the other collects payment details are not duplicates, and the report must have a way to record that permanently.
5. Do not consolidate by deleting the loser and rewriting its call sites in one change. Migrate call sites incrementally behind the deprecation route already defined, checking behaviour and accessibility at each site, because the differences that matter are usually the ones not visible in the markup.

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

- Detection needs both structural and usage similarity. Either signal on its own produces a list dominated by false matches, and a report that is mostly noise stops being read after the second run.
- Legitimate domain differences must be respected and recordable. Components that look identical but carry different consequences, permissions, or copy obligations are not candidates, and marking them as such must persist across runs.
- Usage counts must be shown before any consolidation is proposed, because the component with the better implementation and the component with two hundred call sites are frequently not the same one.
- Behaviour and accessibility must be preserved when a call site is switched over. The surviving component often lacks a focus behaviour, a keyboard shortcut, or an announcement that the retired one had, and none of that shows up in a structural diff.
- Components that differ only in an inline style value or a single class are the most common duplicates and the easiest to miss, so normalise trivial formatting differences before comparing.
- A pair flagged as duplicates but deliberately kept must be suppressible with a recorded reason, or the same pair reappears at the top of every report.
- Consolidation must not silently change a component's rendered element or its default variant, since callers depend on both even when they never pass them.

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

- [ ] Candidates are identified using both structural and usage similarity, not either alone.
- [ ] The component list is read from the inventory rather than re-derived.
- [ ] Each candidate is reported with matched regions, usage counts, and age.
- [ ] Pairs kept apart for domain reasons can be suppressed with a recorded reason that persists across runs.
- [ ] Call sites are migrated incrementally through the existing deprecation route, not replaced in a single change.
- [ ] Focus behaviour, keyboard handling, and announcements are verified at each migrated call site.
- [ ] 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.