# Component Changelog

## Objective

Record what changed in the shared components so consumers are not surprised by a release.

A dated, per-component record of additions, visual changes, deprecations, and breaking interface changes, with migration notes.

## 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. Keep one changelog for the shared component layer and identify every entry by the component it affects, so a consumer can scan for the three components they use rather than reading the whole release.
2. Classify each entry by what it costs the consumer: a new component, a visual change that needs a look, a behavioural change that needs a test, a deprecation with a replacement, or a breaking interface change that needs work.
3. Write every deprecation with its replacement, the reason, and the release in which the old form stops working. A deprecation with no removal date is ignored indefinitely.
4. Generate the entries from work as it merges rather than assembling them before a release. A changelog written from memory at the end of a cycle omits precisely the small visual changes that break someone's layout.
5. Do not let the changelog become the specification. What a component must do lives in Component Acceptance Criteria; this record says only what changed and what the consumer has to do about it.

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

- Visual and behavioural changes need separating, because they are read by different people for different reasons — a designer scans for the first, an engineer for the second, and merging them means both skim.
- A breaking change is not documented until it links to migration guidance concrete enough to follow, showing the old shape, the new shape, and what to do with anything in between.
- Theme and accessibility impact must be called out explicitly: a token that changed value, a contrast ratio that moved, an altered focus order, or a changed accessible name will not be noticed from a diff of the component.
- Entries assembled by hand at release time go stale or go missing, so derive them from merged work and treat a merged change with no entry as an incomplete change.
- A change that only affects one theme or one breakpoint must say so, or every consumer assumes it affects them and re-checks work that was never at risk.
- Internal refactors with no consumer-visible effect should be left out entirely; a changelog padded with them stops being read.
- An entry has to be tied to a version or a date that a consumer can compare against the version they are running, otherwise it cannot be acted on.

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

- [ ] Every consumer-visible change to a shared component appears in the changelog against that component's name.
- [ ] Entries are classified as new, visual, behavioural, deprecated, or breaking.
- [ ] Each breaking change links to migration guidance showing the old and new shape.
- [ ] Each deprecation names its replacement and the release in which the old form is removed.
- [ ] Theme and accessibility impact are stated explicitly where they exist.
- [ ] Entries are produced from merged work, and a merged change without one is treated as unfinished.
- [ ] Every entry carries a version or date a consumer can compare against their own.
- [ ] 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.