# Browser Support Matrix

## Objective

State which browsers the app supports and prove it, instead of assuming.

A documented list of supported browsers and versions, the fallbacks for unsupported ones, and automation aligned to that list.

## 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. Derive the supported list from who actually uses the app and what the business has committed to, using real usage data and any contractual or regulatory requirement, rather than copying a default list from somewhere else.
2. For each capability the app depends on, write down what happens when it is missing — the feature degrades, the feature is hidden, or the user is told the browser is unsupported — and make sure something is defined for every case.
3. Make the automation run against the browsers the policy names. A stated support commitment that no test exercises is an unverified claim.
4. Detect an unsupported browser and say so plainly at the point of entry, naming what will not work, rather than letting the user discover it through a blank screen halfway through a flow.
5. Review the list on a fixed schedule against current usage, and remove a browser only after usage has fallen below the agreed threshold. Viewport sizes and zoom levels are the Responsive QA Matrix's concern, not this one's.

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

- A support list chosen from habit rather than from usage data will spend effort on browsers nobody uses while breaking for a version a large customer is standardised on, so the decision has to be evidenced.
- Every unsupported capability needs a defined fallback path — silently doing nothing leaves the user with a control that appears to work and does not, which is worse than an honest refusal.
- Automation that runs in one engine while the policy claims three means two of those claims are untested, and the gap only surfaces as a customer report.
- Support lists go stale quietly; without a scheduled review the app carries workarounds for browsers with no remaining users and misses versions that have since become common.
- Version ranges expressed as latest only are meaningless for locked-down corporate estates and for users who do not update, so the policy must state a minimum version rather than a moving target.
- Embedded and in-app browsers inside social and messaging apps behave differently from their standalone counterparts and must be listed explicitly if any inbound traffic arrives through them.
- Feature detection is the correct basis for a fallback; user-agent sniffing misidentifies new versions and locks out browsers that would have worked.

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

- [ ] The supported browser and version list is written down and traceable to usage data or a stated requirement.
- [ ] Each capability the app depends on has a documented fallback or an explicit unsupported message.
- [ ] Automated tests run against every browser the policy claims to support.
- [ ] An unsupported browser is detected and told what will not work before the user begins a flow.
- [ ] Fallback decisions are made by feature detection, not by parsing the user agent.
- [ ] The list carries a review date and a documented threshold for dropping a browser.
- [ ] 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.