# Breakpoint Token System

## Objective

Name the app's breakpoints once so the same numbers stop appearing everywhere.

A shared set of named breakpoints, available to both stylesheets and runtime code from a single definition.

## 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 every media query threshold in the codebase and count the distinct values. Anything within a few pixels of a neighbour is the same breakpoint written twice and should be merged before tokens are named.
2. Name each breakpoint for the layout change it causes — the point where the sidebar collapses, where the table becomes cards — rather than for a device. Device names date badly and stop describing anything once screen sizes move.
3. Derive the runtime values from the same definition the stylesheets use, so code that decides whether to render a drawer or a dialog agrees with the CSS about which one is on screen.
4. Keep the set small. Four or five thresholds cover almost every layout, and each additional one multiplies the states that have to be designed, built, and checked.
5. Do not reach for a breakpoint when the question is about the component's own container. Viewport breakpoints belong here; a component that must adapt to the space it is given should use a container query, and Responsive Grid Tokens covers the grid case.

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

- CSS and runtime values drifting apart is the classic failure — the stylesheet switches to a mobile layout while the code still believes it is on desktop, and the user gets a desktop drawer inside a mobile shell. One definition must feed both.
- Names taken from devices mislead the next reader, because a tablet in landscape is wider than several laptops and nobody can tell from the name which layout the token actually triggers.
- Every added breakpoint doubles the combinations to verify, so a set that grows past five or six becomes untestable and layouts start breaking in the ranges nobody checked.
- Container queries and viewport breakpoints must have separate territories, or a component will respond twice to a change in width and produce an intermediate layout that was never designed.
- Mixing minimum-width and maximum-width queries in the same system leaves a one-pixel gap or a one-pixel overlap at each threshold, where either both rules apply or neither does.
- Breakpoints expressed in pixels ignore the user's root font size, so a page zoomed for legibility will not switch layout when it should.
- Runtime breakpoint checks must re-evaluate on resize and orientation change, not only on first render, or a rotated device keeps the layout it started with.

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

- [ ] All breakpoints come from one definition consumed by both stylesheets and runtime code.
- [ ] There are no more than six named breakpoints and none are named after devices.
- [ ] No raw pixel threshold appears in a media query outside the token set.
- [ ] Runtime layout decisions and CSS layout always agree about the current breakpoint.
- [ ] Thresholds do not overlap or leave a gap at their boundaries.
- [ ] Container-driven adaptation uses container queries rather than viewport breakpoints.
- [ ] Layout responds correctly to browser zoom and to orientation change.
- [ ] 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.