# Color-Blindness Simulation

## Objective

See the interface the way users with common colour-vision differences see it.

A development-time filter that renders the live interface under the common forms of colour-vision deficiency.

## 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 every place in the app where meaning is carried by colour alone — chart series, status badges, validation states, diff highlighting, calendar categories, heat maps — and put those screens through the simulation before anything else.
2. Apply the simulation to the rendered page, including canvas and image content, rather than to a page of palette swatches. A swatch grid stays legible under filters that make a real stacked chart unreadable.
3. When two elements collapse into the same colour, fix the design rather than the simulator: add a label, a shape, a pattern, a dash style, or a difference in position. Nudging the hue until the filter stops complaining moves the problem to the next viewer.
4. Offer the common deficiency types separately — red-weak, green-weak, blue-weak, and full monochrome — because a pairing that survives one fails another, and a single combined mode hides which one broke.
5. Do not treat a clean simulation pass as accessibility testing. Simulation approximates one axis and says nothing about contrast sensitivity, low vision, glare, or a document printed in greyscale.

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

- Charts, badges, error states, and status indicators are where colour does the most unaided work, so the simulation must cover them explicitly rather than only the marketing surfaces.
- Where two colours collide under a filter, the fix is a persistent label, pattern, or icon that is present for everyone — not a variant shown only while simulation is active.
- The filter must run over rendered output, including images, video posters, and uploaded avatars, because a token audit cannot see colour that arrived from user content.
- A passing simulation is not a completed accessibility review, and the tooling must not report it as one or the team will stop looking further.
- Chart libraries drawing to canvas or WebGL may ignore CSS-level filters entirely, leaving the exact surface that most needs checking untouched — verify the filter reaches them.
- The simulation code must be excluded from production bundles and from any authenticated end-user route, not merely hidden behind a flag.
- Screenshots taken while simulation is active must be identifiable as simulated, or they end up in a bug report as evidence of a colour bug that does not exist.

## 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 screen carrying colour-coded meaning can be viewed under each simulated deficiency type.
- [ ] The filter applies to rendered output, including canvas charts, images, and user-supplied content.
- [ ] No status, chart series, or validation state is distinguishable by hue alone in any simulated mode.
- [ ] Simulation modes are unreachable in production builds.
- [ ] The tooling states plainly that simulation is a screening step and not a full accessibility assessment.
- [ ] Fixes made in response to the simulation are present for all users, not conditional on the filter.
- [ ] 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.