# Badge Component

## Objective

Use one small label component instead of a dozen coloured pills.

A compact label with fixed tone, shape, and size rules for counts, categories, and short attributes.

## 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. Collect the coloured pills, chips, tags, and counts already scattered across the app and reduce them to one component with a defined set of tones.
2. Give each tone a stated meaning and use it consistently — a neutral tone for categories, and any semantic tone reserved for meaning rather than decoration.
3. Constrain the content: a badge holds a short word, a very short phrase, or a number. Set an upper bound and decide what happens beyond it, including how a count above the bound is rendered.
4. Keep badges non-interactive. If something needs to be clicked, dismissed, or filtered on, it is a chip or a button and belongs to the relevant control, not here.
5. Where a badge is being used to show the state of a record, that meaning is owned by Status Indicator System; this brief owns only the visual container and its constraints. Do not define a status vocabulary here.

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

- Long or translated labels will overflow a badge sized for English. Set a maximum width with predictable truncation and keep the full value available on hover and in the accessible name.
- Small text on a tinted background frequently fails contrast even when the same colours pass at body size. Verify each tone at the badge's actual text size in both light and dark themes.
- A badge that carries an interaction — a remove cross, a click-to-filter — becomes a control and inherits every requirement of one, including focus, keyboard operation, and a hit area. Keeping labels and controls separate avoids that entirely.
- In a dense table cell or a narrow card, a row of badges must wrap or collapse to a count rather than forcing the column wider or clipping at the edge.
- Numeric badges need a defined ceiling, so a count of nine thousand does not stretch a navigation item.
- A badge conveying meaning by colour alone is unreadable to colourblind users; the text inside it must carry the information.
- Badges placed inside a link or button must not be announced as separate interactive elements.

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

- [ ] One badge component covers every compact label in the app.
- [ ] Each tone has a documented meaning and is used only for that meaning.
- [ ] Badge text passes contrast at its actual size in every supported theme.
- [ ] Overlong content truncates predictably with the full value still available.
- [ ] Badges contain no interactive controls.
- [ ] Badge groups in tables and cards wrap or collapse without widening or clipping their container.
- [ ] 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.