# Component Usage Documentation

## Objective

Put the rules for using a component next to the component, where they get read.

Usage documentation attached to each shared component covering intended use, variants, accessibility obligations, and the patterns to avoid.

## 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 the shared components the app already has and write documentation for the ones that are used in more than one place. A component used once does not need a page; a component used forty times does.
2. For each component, state what it is for, which variants exist and when each applies, what the consumer is responsible for accessibility-wise, and which props or slots are load-bearing.
3. Include at least one realistic example per variant, using the app's own copy and data rather than lorem text. An example showing a three-character label hides the wrapping problem that every real usage hits.
4. Keep the documentation in the same directory as the component and update it in the same change that alters behaviour, so a reviewer sees a variant added and its documentation missing in one diff.
5. Do not write a separate documentation site maintained by hand. A second source of truth drifts within weeks and then actively misleads the people who trust 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

- Examples that are only prose go stale silently. Render the examples from the same code the documentation shows, or run them in the test suite, so a broken example fails a build rather than misleading a reader.
- Every component needs an explicit section on when not to use it and what to reach for instead — a dialog documented without the note that a destructive confirmation belongs to the confirmation pattern will be used for both.
- Documentation must be versioned alongside the implementation, so a consumer pinned to an older release reads the rules that actually applied then.
- Realistic examples must include the awkward states: long labels, missing optional data, right-to-left text, and the loading and error variants, not just the happy path.
- A component that has been deprecated must say so at the top with its replacement named, rather than quietly remaining as valid-looking guidance.
- Accessibility notes must say who owns what — if the component renders the control but the consumer supplies the label, the documentation must state that the label is not optional.
- Screenshots go out of date faster than anything else. Prefer live rendered examples, and if a screenshot is unavoidable, note what it is showing so a stale one is obvious.

## 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 component used in more than one place has usage documentation beside its implementation.
- [ ] Each documented component names its variants, its intended use, and at least one case where it is the wrong choice.
- [ ] Examples render from real code and fail the build when the component's interface changes.
- [ ] Accessibility responsibilities are split explicitly between the component and its consumer.
- [ ] Documentation ships in the same change as the behaviour it describes.
- [ ] Deprecated components carry a visible notice naming their replacement.
- [ ] 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.