# Poll Widget

## Objective

Ask a one-question poll anywhere in the app and show the results as soon as someone votes.

An embeddable single-question poll with a vote control and a results view revealed after voting.

## 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. Keep it to one question with a small set of options. The moment it grows a second question it is a survey and belongs in the survey feature instead.
2. Record the vote on the server and return the updated tallies in the same response, so the results the voter sees are the real counts rather than an optimistic local guess that may disagree after a refresh.
3. Hold voting open to signed-out visitors if the poll is public, and identify them well enough to prevent casual repeat voting without demanding an account for a single click.
4. Show the total response count next to the percentages. A split of sixty and forty means something very different across ten votes and ten thousand.
5. Do not let a vote be silently changeable. Either allow a vote to be changed and say so plainly with the previous choice shown, or lock it after submission, but do not let a second click quietly move the count.

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

- Preventing repeat votes without an account means combining signals such as a persistent cookie and coarse network identification, and accepting that neither is authoritative. Apply the app's existing Rate Limiting per poll so a determined script cannot flood the tallies.
- A poll can close between the moment the page rendered and the moment the vote arrives. Reject the late vote on the server, tell the voter the poll has closed, and show them the final results rather than pretending the vote counted.
- Showing the current results before someone votes anchors their answer toward the leading option. Keep results hidden until a vote is cast or the poll closes, and make that behaviour visible so it does not read as a bug.
- Rounded percentages frequently sum to ninety-nine or a hundred and one. Use a rounding approach that forces the displayed figures to total one hundred, and show raw counts alongside so the arithmetic can be checked.
- Adding an option after voting has started makes earlier results incomparable, because nobody who voted first was offered the new choice. Either forbid it once the first vote lands, or record when each option was added and mark the results as affected.
- A poll with zero votes must render its options and an honest empty state, not percentages derived from a division by zero.
- Results are usually drawn as bars. Give every option its percentage and count as text so the outcome is readable without seeing the bars, and do not rely on colour alone to mark the option the viewer chose.
- A poll is written by one person and rendered to everyone who loads the page, which makes the question and its options a publishing surface rather than a form input. Screen them when the poll is saved and escape them when it renders, or an embedded poll becomes a way to put arbitrary markup in front of every visitor.

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

- [ ] A visitor votes once and sees results immediately, with counts computed on the server.
- [ ] Repeat voting from the same visitor is prevented without requiring an account.
- [ ] Votes arriving after a poll closes are rejected with a clear message and the final results.
- [ ] Results stay hidden until the viewer votes or the poll closes.
- [ ] Displayed percentages always sum to one hundred and raw counts are shown alongside.
- [ ] Options cannot be added mid-poll without the results being marked as affected.
- [ ] Results are readable as text without relying on bar length or colour.
- [ ] 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.