# Responsive Prop System

## Objective

Let any component take a per-breakpoint value through one predictable, consistent API.

A single convention for passing breakpoint-aware values to components, with defined merge order and bounded output.

## 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. Find where the codebase currently handles responsiveness by hand — duplicated components for mobile and desktop, conditional rendering on a width check, one-off utility classes — and replace those with a single responsive value convention.
2. Define the merge order once and document it: a value given for a breakpoint applies from that breakpoint up until another overrides it, and a bare value is the base that applies everywhere. Ambiguity here produces layouts nobody can predict from reading the call site.
3. Restrict the convention to the props where it earns its keep — layout, spacing, sizing, column counts, visibility — and reject it elsewhere with a clear error rather than silently ignoring it.
4. Resolve responsive values through the app's existing breakpoint definitions rather than inventing a parallel set of widths. Two competing breakpoint scales in one codebase is worse than none.
5. Do not implement the resolution by reading window width in script and re-rendering. That produces a wrong first paint on the server, a visible snap on hydration, and a re-render on every resize; the resolution belongs in the styling layer where the browser can do 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

- The merge order across breakpoints must be stated and enforced. If a value set at a middle breakpoint does or does not carry upward to the largest, and the answer is not written down and applied uniformly, every call site becomes trial and error.
- A responsive value passed to a prop that does not support it must fail loudly at development time rather than being coerced or dropped. Silently rendering the object as a string, or picking its first entry, hides the mistake until it reaches a user.
- Server-rendered output must be deterministic, so nothing may depend on the actual viewport at render time. If the server guesses a breakpoint, the first paint is wrong for half the audience and flickers into place on hydration.
- Generating one style rule per prop per breakpoint per instance grows the stylesheet without bound. Constrain the accepted values to the design scale and reuse generated rules so a page with two hundred components does not ship two hundred near-identical declarations.
- Responsive values must compose with the app's existing style overrides in a defined order, so a breakpoint value does not unexpectedly beat an explicit override at the call site, or lose to one.
- This brief owns only how a value varies across breakpoints. The named set of allowed values for a prop — sizes, tones, emphasis levels — belongs to Component Variant API, and the two must share one vocabulary rather than each defining its own.
- Values that cannot vary meaningfully by breakpoint, such as a semantic element type or an accessible label, must be excluded from the convention outright.

## 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 that accepts responsive values uses the same prop shape and the same merge order.
- [ ] The merge order is documented and holds for every supported prop.
- [ ] A responsive value on an unsupported prop raises a clear development-time error.
- [ ] Server-rendered markup is identical regardless of the requesting device, and hydration produces no visible snap.
- [ ] Breakpoints come from the app's existing definitions, with no second set of widths.
- [ ] Generated style output grows with the number of distinct values used, not with the number of component instances.
- [ ] Duplicate mobile and desktop variants of the same component have been removed.
- [ ] 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.