= {
+ [-1]: {border: '#f59090', glow: 'rgba(245, 144, 144, 0.15)'},
+ [0]: {border: '#6ee7a0', glow: 'rgba(110, 231, 160, 0.15)'},
+ [1]: {border: '#60b5f5', glow: 'rgba(96, 181, 245, 0.15)'},
+};
+
+const VOTES = [-1, 0, 1] as const;
+
+const CONTAINER_STYLE: React.CSSProperties = {
+ background: 'rgba(212, 175, 55, 0.04)',
+ border: '1px solid rgba(212, 175, 55, 0.12)',
+ borderRadius: 10,
+ padding: '14px 16px',
+ display: 'flex',
+ flexDirection: 'column',
+ gap: SPACING.sm,
+ fontFamily: FONTS.body,
+};
+
+const QUESTION_STYLE: React.CSSProperties = {
+ fontSize: `${FONT_SIZES.base}px`,
+ color: COLORS.textMuted,
+ margin: 0,
+};
+
+const BASE_BUTTON_STYLE: React.CSSProperties = {
+ background: 'rgba(255,255,255,0.03)',
+ border: `1px solid ${COLORS.surfaceBorder}`,
+ borderRadius: RADIUS.lg,
+ minHeight: 44,
+ cursor: 'pointer',
+ fontFamily: 'inherit',
+ fontSize: `${FONT_SIZES.base}px`,
+ color: COLORS.text,
+ padding: `${SPACING.xs}px ${SPACING.md}px`,
+ transition: 'all 0.2s',
+ flex: 1,
+};
+
+const TEASER_STYLE: React.CSSProperties = {
+ fontSize: `${FONT_SIZES.sm}px`,
+ color: COLORS.textDim,
+ background: 'none',
+ border: 'none',
+ padding: 0,
+ cursor: 'not-allowed',
+ fontFamily: 'inherit',
+ textAlign: 'left',
+};
+
+function VoteButtons({
+ disabled,
+ submitting,
+ selectedChoice,
+ onVote,
+ isMobile,
+}: {
+ disabled: boolean;
+ submitting: boolean;
+ selectedChoice: Accuracy | null;
+ onVote: (accuracy: Accuracy) => void;
+ isMobile: boolean;
+}) {
+ return (
+
+ {VOTES.map((vote) => {
+ const isSelected = submitting && selectedChoice === vote;
+ const isDimmed = submitting && selectedChoice !== vote;
+ const colors = CHOICE_COLORS[vote];
+
+ return (
+
+ );
+ })}
+
+ );
+}
+
+function TeaserButton() {
+ return (
+
+ );
+}
+
+export function QuickVoteControl({
+ state,
+ onVote,
+ distribution,
+ userChoice,
+ error,
+}: QuickVoteControlProps) {
+ const {isMobile} = useResponsive();
+
+ if (state === 'hidden') return null;
+
+ if (state === 'result') {
+ const isFirstVoter = distribution?.total === 1;
+
+ return (
+
+
+ ✦ Thanks! You voted:{' '}
+
+ {userChoice !== null ? CHOICE_LABELS[userChoice] : ''}
+
+
+ {isFirstVoter ? (
+
+ ✦
+ First to rate this pair!
+
+ ) : distribution ? (
+
+ ) : (
+
+ Loading community votes…
+
+ )}
+ {distribution && (
+
+ {distribution.total} votes on this pair
+
+ )}
+
+
+
Do you agree with this score?
+
+ {isError && (
+
+ {error === 'rate_limited'
+ ? "You're voting fast! Try again in a bit."
+ : 'Something went wrong, try again'}
+
+ )}
+
+
+
+ {segments.map((key, i) => (
+
1
+ ? '6px 0 0 6px'
+ : i === segments.length - 1 && segments.length > 1
+ ? '0 6px 6px 0'
+ : segments.length === 1
+ ? '6px'
+ : undefined,
+ transition: animate ? 'width 500ms ease-out' : undefined,
+ transitionDelay: animate ? `${i * 50}ms` : undefined,
+ }}>
+ {pct[key]}%
+
+ ))}
+
+
+ {LABELS.lower}
+ {LABELS.right}
+ {LABELS.higher}
+
+
+
+
+ ),
+ ],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Balanced: Story = {
+ args: {lower: 15, right: 68, higher: 17, animate: false},
+};
+
+export const Animated: Story = {
+ args: {lower: 15, right: 68, higher: 17, animate: true},
+};
+
+export const Unanimous: Story = {
+ args: {lower: 0, right: 25, higher: 0, animate: false},
+};
+
+export const Controversial: Story = {
+ args: {lower: 12, right: 5, higher: 13, animate: false},
+};
+
+export const SingleVote: Story = {
+ args: {lower: 0, right: 1, higher: 0, animate: false},
+};
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/web/src/features/voting/components/DistributionBar.tsx \
+ apps/web/src/features/voting/components/__tests__/DistributionBar.test.tsx \
+ apps/web/src/features/voting/components/DistributionBar.stories.tsx
+git commit -m "feat(voting): add DistributionBar component (#212)"
+```
+
+---
+
+### Task 4: useQuickVote hook
+
+**Files:**
+- Create: `apps/web/src/features/voting/hooks/useQuickVote.ts`
+- Create: `apps/web/src/features/voting/hooks/__tests__/useQuickVote.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// useQuickVote.test.ts
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {renderHook, act} from '@testing-library/react';
+import {useQuickVote} from '../useQuickVote';
+import {getSupabase, submitVote, getAccuracyDistribution} from '../../../../shared/lib/supabase';
+
+vi.mock('../../../../shared/lib/supabase', () => ({
+ getSupabase: vi.fn(),
+ submitVote: vi.fn(),
+ getAccuracyDistribution: vi.fn(),
+}));
+
+const CARD_A = 'card-aaa';
+const CARD_B = 'card-bbb';
+// Canonical key: sorted
+const STORAGE_KEY = `inkweave:vote:${CARD_A}:${CARD_B}`;
+
+describe('useQuickVote', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ localStorage.clear();
+ });
+
+ afterEach(() => {
+ localStorage.clear();
+ });
+
+ it('returns hidden state when Supabase is unavailable', () => {
+ vi.mocked(getSupabase).mockReturnValue(null);
+ const {result} = renderHook(() => useQuickVote(CARD_A, CARD_B));
+ expect(result.current.state).toBe('hidden');
+ });
+
+ it('returns ready state when Supabase is available and no prior vote', () => {
+ vi.mocked(getSupabase).mockReturnValue({} as ReturnType);
+ const {result} = renderHook(() => useQuickVote(CARD_A, CARD_B));
+ expect(result.current.state).toBe('ready');
+ });
+
+ it('returns result state when pair found in localStorage', async () => {
+ vi.mocked(getSupabase).mockReturnValue({} as ReturnType);
+ vi.mocked(getAccuracyDistribution).mockResolvedValue({
+ lower: 3, right: 10, higher: 2, total: 15,
+ });
+ localStorage.setItem(STORAGE_KEY, JSON.stringify({accuracy: 0, timestamp: Date.now()}));
+
+ const {result} = renderHook(() => useQuickVote(CARD_A, CARD_B));
+ expect(result.current.state).toBe('result');
+ expect(result.current.userChoice).toBe(0);
+ });
+
+ it('submits vote, stores in localStorage, and fetches distribution', async () => {
+ vi.mocked(getSupabase).mockReturnValue({} as ReturnType);
+ vi.mocked(submitVote).mockResolvedValue({error: null});
+ vi.mocked(getAccuracyDistribution).mockResolvedValue({
+ lower: 1, right: 5, higher: 0, total: 6,
+ });
+
+ const {result} = renderHook(() => useQuickVote(CARD_A, CARD_B));
+ expect(result.current.state).toBe('ready');
+
+ await act(async () => {
+ await result.current.vote(0);
+ });
+
+ expect(submitVote).toHaveBeenCalledWith({
+ cardA: CARD_A,
+ cardB: CARD_B,
+ accuracy: 0,
+ });
+ expect(result.current.state).toBe('result');
+ expect(result.current.userChoice).toBe(0);
+ expect(result.current.distribution).toEqual({
+ lower: 1, right: 5, higher: 0, total: 6,
+ });
+ expect(localStorage.getItem(STORAGE_KEY)).toBeTruthy();
+ });
+
+ it('transitions to error state on submission failure', async () => {
+ vi.mocked(getSupabase).mockReturnValue({} as ReturnType);
+ vi.mocked(submitVote).mockResolvedValue({error: 'Network error'});
+
+ const {result} = renderHook(() => useQuickVote(CARD_A, CARD_B));
+
+ await act(async () => {
+ await result.current.vote(1);
+ });
+
+ expect(result.current.state).toBe('error');
+ expect(result.current.error).toBe('error');
+ expect(localStorage.getItem(STORAGE_KEY)).toBeNull();
+ });
+
+ it('transitions to rate-limited state', async () => {
+ vi.mocked(getSupabase).mockReturnValue({} as ReturnType);
+ vi.mocked(submitVote).mockResolvedValue({error: 'rate_limited'});
+
+ const {result} = renderHook(() => useQuickVote(CARD_A, CARD_B));
+
+ await act(async () => {
+ await result.current.vote(-1);
+ });
+
+ expect(result.current.state).toBe('error');
+ expect(result.current.error).toBe('rate_limited');
+ });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `pnpm --filter inkweave-web vitest run src/features/voting/hooks/__tests__/useQuickVote.test.ts`
+Expected: FAIL — module not found
+
+- [ ] **Step 3: Implement useQuickVote**
+
+```typescript
+// useQuickVote.ts
+import {useState, useEffect, useCallback, useMemo} from 'react';
+import {
+ getSupabase,
+ submitVote,
+ getAccuracyDistribution,
+ type AccuracyDistribution,
+} from '../../../shared/lib/supabase';
+
+export type QuickVoteState = 'hidden' | 'ready' | 'submitting' | 'result' | 'error';
+export type QuickVoteError = 'error' | 'rate_limited' | null;
+type Accuracy = -1 | 0 | 1;
+
+function storageKey(cardA: string, cardB: string): string {
+ const [a, b] = [cardA, cardB].sort();
+ return `inkweave:vote:${a}:${b}`;
+}
+
+function getStoredVote(cardA: string, cardB: string): Accuracy | null {
+ try {
+ const raw = localStorage.getItem(storageKey(cardA, cardB));
+ if (!raw) return null;
+ const parsed = JSON.parse(raw);
+ return parsed.accuracy ?? null;
+ } catch {
+ return null;
+ }
+}
+
+function storeVote(cardA: string, cardB: string, accuracy: Accuracy): void {
+ localStorage.setItem(
+ storageKey(cardA, cardB),
+ JSON.stringify({accuracy, timestamp: Date.now()}),
+ );
+}
+
+export interface UseQuickVoteReturn {
+ state: QuickVoteState;
+ vote: (accuracy: Accuracy) => Promise;
+ distribution: AccuracyDistribution | null;
+ userChoice: Accuracy | null;
+ error: QuickVoteError;
+}
+
+export function useQuickVote(cardA: string, cardB: string): UseQuickVoteReturn {
+ const isAvailable = useMemo(() => getSupabase() !== null, []);
+ const storedChoice = useMemo(() => getStoredVote(cardA, cardB), [cardA, cardB]);
+
+ const [state, setState] = useState(() => {
+ if (!isAvailable) return 'hidden';
+ if (storedChoice !== null) return 'result';
+ return 'ready';
+ });
+ const [userChoice, setUserChoice] = useState(storedChoice);
+ const [distribution, setDistribution] = useState(null);
+ const [error, setError] = useState(null);
+
+ // Fetch distribution for returning voters
+ useEffect(() => {
+ if (state === 'result' && !distribution) {
+ getAccuracyDistribution(cardA, cardB).then((dist) => {
+ if (dist) setDistribution(dist);
+ });
+ }
+ }, [state, distribution, cardA, cardB]);
+
+ const vote = useCallback(
+ async (accuracy: Accuracy) => {
+ if (state !== 'ready' && state !== 'error') return;
+
+ setState('submitting');
+ setError(null);
+
+ const result = await submitVote({cardA, cardB, accuracy});
+
+ if (result.error === null) {
+ storeVote(cardA, cardB, accuracy);
+ setUserChoice(accuracy);
+ setState('result');
+ const dist = await getAccuracyDistribution(cardA, cardB);
+ if (dist) setDistribution(dist);
+ } else if (result.error === 'rate_limited') {
+ setError('rate_limited');
+ setState('error');
+ } else {
+ setError('error');
+ setState('error');
+ }
+ },
+ [cardA, cardB, state],
+ );
+
+ return {state, vote, distribution, userChoice, error};
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pnpm --filter inkweave-web vitest run src/features/voting/hooks/__tests__/useQuickVote.test.ts`
+Expected: PASS (6 tests)
+
+- [ ] **Step 5: Export from hooks index**
+
+Add to `apps/web/src/features/voting/hooks/index.ts`:
+
+```typescript
+export {useQuickVote} from './useQuickVote';
+export type {UseQuickVoteReturn, QuickVoteState, QuickVoteError} from './useQuickVote';
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/web/src/features/voting/hooks/useQuickVote.ts \
+ apps/web/src/features/voting/hooks/__tests__/useQuickVote.test.ts \
+ apps/web/src/features/voting/hooks/index.ts
+git commit -m "feat(voting): add useQuickVote hook (#212)"
+```
+
+---
+
+### Task 5: QuickVoteControl component
+
+**Files:**
+- Create: `apps/web/src/features/voting/components/QuickVoteControl.tsx`
+- Create: `apps/web/src/features/voting/components/__tests__/QuickVoteControl.test.tsx`
+- Create: `apps/web/src/features/voting/components/QuickVoteControl.stories.tsx`
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// QuickVoteControl.test.tsx
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {QuickVoteControl} from '../QuickVoteControl';
+import type {AccuracyDistribution} from '../../../../shared/lib/supabase';
+
+const mockVote = vi.fn();
+
+describe('QuickVoteControl', () => {
+ it('renders nothing when state is hidden', () => {
+ const {container} = render(
+ ,
+ );
+ expect(container.firstChild).toBeNull();
+ });
+
+ it('renders three vote buttons in ready state', () => {
+ render(
+ ,
+ );
+ expect(screen.getByText('Do you agree with this score?')).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Should be lower'})).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'About right'})).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Should be higher'})).toBeInTheDocument();
+ });
+
+ it('calls onVote with -1 when "Should be lower" is clicked', () => {
+ render(
+ ,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Should be lower'}));
+ expect(mockVote).toHaveBeenCalledWith(-1);
+ });
+
+ it('calls onVote with 0 when "About right" is clicked', () => {
+ render(
+ ,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'About right'}));
+ expect(mockVote).toHaveBeenCalledWith(0);
+ });
+
+ it('calls onVote with 1 when "Should be higher" is clicked', () => {
+ render(
+ ,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Should be higher'}));
+ expect(mockVote).toHaveBeenCalledWith(1);
+ });
+
+ it('disables buttons during submitting state', () => {
+ render(
+ ,
+ );
+ const buttons = screen.getAllByRole('button');
+ buttons.forEach((btn) => expect(btn).toBeDisabled());
+ });
+
+ it('shows distribution bar and confirmation in result state', () => {
+ const dist: AccuracyDistribution = {lower: 3, right: 14, higher: 3, total: 20};
+ render(
+ ,
+ );
+ expect(screen.getByText(/You voted:/)).toBeInTheDocument();
+ expect(screen.getByText('About right')).toBeInTheDocument();
+ expect(screen.getByText('20 votes on this pair')).toBeInTheDocument();
+ });
+
+ it('shows first voter badge when total is 1', () => {
+ const dist: AccuracyDistribution = {lower: 0, right: 1, higher: 0, total: 1};
+ render(
+ ,
+ );
+ expect(screen.getByText('First to rate this pair!')).toBeInTheDocument();
+ });
+
+ it('shows error message and re-enables buttons on error', () => {
+ render(
+ ,
+ );
+ expect(screen.getByText('Something went wrong, try again')).toBeInTheDocument();
+ const buttons = screen.getAllByRole('button').filter((b) => !b.textContent?.includes('Rate'));
+ buttons.forEach((btn) => expect(btn).not.toBeDisabled());
+ });
+
+ it('shows rate limit message on rate_limited error', () => {
+ render(
+ ,
+ );
+ expect(screen.getByText("You're voting fast! Try again in a bit.")).toBeInTheDocument();
+ });
+
+ it('shows disabled "Rate in detail" teaser', () => {
+ render(
+ ,
+ );
+ const teaser = screen.getByText(/Rate in detail/);
+ expect(teaser).toBeInTheDocument();
+ });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `pnpm --filter inkweave-web vitest run src/features/voting/components/__tests__/QuickVoteControl.test.tsx`
+Expected: FAIL — module not found
+
+- [ ] **Step 3: Implement QuickVoteControl**
+
+This is a TODO(human) step — see the Learn by Doing request below.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pnpm --filter inkweave-web vitest run src/features/voting/components/__tests__/QuickVoteControl.test.tsx`
+Expected: PASS (10 tests)
+
+- [ ] **Step 5: Write stories**
+
+```typescript
+// QuickVoteControl.stories.tsx
+import type {Meta, StoryObj} from '@storybook/react-vite';
+import {fn} from 'storybook/test';
+import {QuickVoteControl} from './QuickVoteControl';
+
+const meta = {
+ title: 'Voting/QuickVoteControl',
+ component: QuickVoteControl,
+ parameters: {layout: 'centered'},
+ tags: ['autodocs'],
+ decorators: [
+ (Story) => (
+
+
+
+ ),
+ ],
+ args: {onVote: fn()},
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Ready: Story = {
+ args: {state: 'ready', distribution: null, userChoice: null, error: null},
+};
+
+export const Submitting: Story = {
+ args: {state: 'submitting', distribution: null, userChoice: 0, error: null},
+};
+
+export const Result: Story = {
+ args: {
+ state: 'result',
+ distribution: {lower: 15, right: 68, higher: 17, total: 100},
+ userChoice: 0,
+ error: null,
+ },
+};
+
+export const ResultFirstVoter: Story = {
+ args: {
+ state: 'result',
+ distribution: {lower: 0, right: 1, higher: 0, total: 1},
+ userChoice: 0,
+ error: null,
+ },
+};
+
+export const Error: Story = {
+ args: {state: 'error', distribution: null, userChoice: null, error: 'error'},
+};
+
+export const RateLimited: Story = {
+ args: {state: 'error', distribution: null, userChoice: null, error: 'rate_limited'},
+};
+
+export const Mobile: Story = {
+ args: {state: 'ready', distribution: null, userChoice: null, error: null},
+ parameters: {viewport: {defaultViewport: 'mobile1'}},
+};
+
+export const MobileResult: Story = {
+ args: {
+ state: 'result',
+ distribution: {lower: 8, right: 30, higher: 12, total: 50},
+ userChoice: 1,
+ error: null,
+ },
+ parameters: {viewport: {defaultViewport: 'mobile1'}},
+};
+```
+
+- [ ] **Step 6: Export from components index**
+
+Add to `apps/web/src/features/voting/components/index.ts`:
+
+```typescript
+export {QuickVoteControl} from './QuickVoteControl';
+export {DistributionBar} from './DistributionBar';
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add apps/web/src/features/voting/components/QuickVoteControl.tsx \
+ apps/web/src/features/voting/components/__tests__/QuickVoteControl.test.tsx \
+ apps/web/src/features/voting/components/QuickVoteControl.stories.tsx \
+ apps/web/src/features/voting/components/index.ts
+git commit -m "feat(voting): add QuickVoteControl component (#212)"
+```
+
+---
+
+### Task 6: Integrate into SynergyDetailModal
+
+**Files:**
+- Modify: `apps/web/src/features/synergies/components/SynergyDetailModal.tsx`
+- Modify: `apps/web/src/features/synergies/components/__tests__/SynergyDetailModal.test.tsx`
+
+- [ ] **Step 1: Write failing integration test**
+
+Add to the existing `SynergyDetailModal.test.tsx`:
+
+```typescript
+// Add mock at top of file with other mocks
+vi.mock('../../../features/voting/hooks/useQuickVote', () => ({
+ useQuickVote: vi.fn().mockReturnValue({
+ state: 'ready',
+ vote: vi.fn(),
+ distribution: null,
+ userChoice: null,
+ error: null,
+ }),
+}));
+
+// Add test
+it('renders quick vote control below tier label', () => {
+ render(
+ ,
+ );
+ expect(screen.getByText('Do you agree with this score?')).toBeInTheDocument();
+});
+```
+
+- [ ] **Step 2: Run tests to verify it fails**
+
+Run: `pnpm --filter inkweave-web vitest run src/features/synergies/components/__tests__/SynergyDetailModal.test.tsx`
+Expected: FAIL — "Do you agree with this score?" not found
+
+- [ ] **Step 3: Add QuickVoteControl to SynergyDetailModal**
+
+In `SynergyDetailModal.tsx`, add import at top:
+
+```typescript
+import {QuickVoteControl} from '../../voting/components';
+import {useQuickVote} from '../../voting/hooks';
+```
+
+Inside the `SynergyDetailModal` function, after destructuring `pair`, add the hook call:
+
+```typescript
+const quickVote = useQuickVote(cardA.id, cardB.id);
+```
+
+Then insert `QuickVoteControl` between the tier label `` (line 152) and the connections section (line 154):
+
+```tsx
+ {/* Quick vote */}
+
+
+
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pnpm --filter inkweave-web vitest run src/features/synergies/components/__tests__/SynergyDetailModal.test.tsx`
+Expected: PASS
+
+- [ ] **Step 5: Run full test suite**
+
+Run: `pnpm test`
+Expected: All tests pass (engine 195 + web 541+ new tests)
+
+- [ ] **Step 6: Visual verification**
+
+Start dev server (`pnpm dev`), navigate to a card with synergies, click a synergy card to open the modal. Verify:
+- Vote section appears below "Strong Synergy" label
+- Three buttons render correctly
+- Clicking a button submits (check Network tab for Supabase RPC call)
+- Distribution bar appears after voting
+- On mobile viewport, buttons stack vertically
+
+Use Chrome DevTools MCP screenshot to verify.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add apps/web/src/features/synergies/components/SynergyDetailModal.tsx \
+ apps/web/src/features/synergies/components/__tests__/SynergyDetailModal.test.tsx
+git commit -m "feat(voting): integrate quick vote into synergy detail modal (#212)"
+```
+
+---
+
+## Summary
+
+| Task | What | Tests | Commit |
+|------|------|-------|--------|
+| 1 | Supabase migration: accuracy distribution columns | Verified via SQL query | `feat(supabase): add accuracy distribution columns` |
+| 2 | `getAccuracyDistribution()` in supabase.ts | Tested via hook tests | `feat(supabase): add getAccuracyDistribution query` |
+| 3 | DistributionBar component + stories | 4 unit tests | `feat(voting): add DistributionBar component` |
+| 4 | useQuickVote hook | 6 unit tests | `feat(voting): add useQuickVote hook` |
+| 5 | QuickVoteControl component + stories | 10 unit tests | `feat(voting): add QuickVoteControl component` |
+| 6 | Integrate into SynergyDetailModal | 1 integration test + visual | `feat(voting): integrate quick vote into synergy detail modal` |
diff --git a/docs/superpowers/specs/2026-04-06-quick-vote-design.md b/docs/superpowers/specs/2026-04-06-quick-vote-design.md
new file mode 100644
index 0000000..4f08df6
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-06-quick-vote-design.md
@@ -0,0 +1,264 @@
+# Synergy Modal Quick Vote — Design Spec (#212)
+
+**Issue**: [#212](https://github.com/Doberjohn/inkweave/issues/212)
+**Epic**: Community Voting (#205)
+**Date**: 2026-04-06
+
+## Overview
+
+Add a lightweight three-button voting control to the `SynergyDetailModal`. Users give directional feedback on the algorithm's synergy score — "Should be lower" / "About right" / "Should be higher". After voting, an animated distribution bar reveals how the community voted, creating a social feedback loop.
+
+**Scope**: Modal UI component, new hook, Supabase migration (distribution columns), localStorage persistence for voted pairs.
+
+**Out of scope**: "Rate in Detail" navigation (disabled teaser only — enabled by #213), user authentication, vote editing UI.
+
+## UI Layout
+
+### Placement
+
+Below the tier label ("Strong Synergy"), above the connections list. Wrapped in a subtle gold-bordered container (`rgba(212, 175, 55, 0.04)` background, `rgba(212, 175, 55, 0.12)` border).
+
+### Desktop
+
+Three buttons in a horizontal row. Full labels:
+- "Should be lower" → `accuracy: -1`
+- "About right" → `accuracy: 0`
+- "Should be higher" → `accuracy: 1`
+
+Question text above: "Do you agree with this score?"
+
+Disabled "Rate in detail →" teaser below the buttons.
+
+### Mobile
+
+Three buttons in a vertical stack. Same labels, same wording. Full-width, `min-height: 44px` touch targets. To be validated during implementation.
+
+## State Machine
+
+```
+ ┌──────────────────┐
+ │ Hidden │ ← Supabase unavailable
+ └──────────────────┘
+
+ Modal opens ──→ localStorage check
+ │
+ ┌───────┴────────┐
+ │ │
+ not found found
+ │ │
+ ▼ ▼
+ ┌──────────┐ ┌──────────────┐
+ │ Ready │ │ Result │ ← fetch fresh distribution
+ └────┬─────┘ └──────────────┘
+ │ click
+ ▼
+ ┌──────────┐
+ │Submitting│
+ └────┬─────┘
+ │
+ ┌────┴────┐
+ │ │
+ success error
+ │ │
+ ▼ ▼
+┌────────┐ ┌──────┐
+│ Result │ │Error │ → buttons re-enable → Ready
+└────────┘ └──────┘
+```
+
+### State details
+
+| State | Trigger | UI |
+|-------|---------|-----|
+| **Hidden** | `getSupabase() === null` | Vote section not rendered |
+| **Ready** | Modal opens, pair not in localStorage | Question + 3 buttons + disabled "Rate in detail" |
+| **Submitting** | User clicks a vote button | Selected button: scale(1.05) + glow + checkmark. Others: opacity 0.3, disabled |
+| **Result** | Vote succeeds OR pair in localStorage | "Thanks! You voted: {choice}" + distribution bar + vote count + disabled "Rate in detail" |
+| **Error** | Submission fails | Inline "Something went wrong, try again" — buttons re-enable |
+| **Rate Limited** | 30 votes/hour exceeded | Inline "You're voting fast! Try again in a bit." — buttons stay disabled |
+
+## Post-Vote: Distribution Bar
+
+After voting, the three buttons collapse and are replaced by:
+
+1. **Confirmation**: "Thanks! You voted: {choice}" with gold star `✦`
+2. **Distribution bar**: Three colored segments showing community vote percentages
+ - Lower: `#f59090` (red, 25% opacity background)
+ - About right: `#6ee7a0` (green, 20% opacity background)
+ - Higher: `#60b5f5` (blue, 20% opacity background)
+3. **Vote count**: "{N} votes on this pair"
+4. **Disabled "Rate in detail →"** teaser
+
+### First voter
+
+When total votes = 1 (the user is the first), show:
+- Confirmation line (same as above)
+- Gold badge: "First to rate this pair!" with `✦` pulse animation
+- "Distribution will show after more votes"
+
+No minimum vote threshold for showing the distribution bar — it shows at 2+ votes. At exactly 1 vote (the user is the only voter), show the first voter badge instead. On return visits, fetch fresh distribution: if total is now > 1, show the bar; if still 1, show the badge again.
+
+## Animation
+
+### Button press (Ready → Submitting)
+
+- Selected button: `transform: scale(1.05)`, border shifts to distribution color, `box-shadow` glow, checkmark replaces text
+- Other buttons: `opacity: 0.3`, `pointer-events: none`
+- Duration: `200ms ease-out`
+
+### Result reveal (Submitting → Result)
+
+- Container height animates smoothly (no layout jump)
+- "Thanks! You voted:" fades in: `opacity 0→1, 300ms`
+- Distribution bar segments grow from `width: 0` to final percentage: `500ms ease-out`, staggered 50ms per segment
+- Vote count fades in after bar completes
+
+### First voter badge
+
+Gold star `✦` single pulse: `scale 1→1.15→1`, plays once.
+
+### Returning pair (localStorage hit)
+
+Skip to Result immediately — no animation. Distribution bar renders at full width. Fresh distribution fetched in background, updates silently if numbers changed.
+
+### No toast
+
+Unlike the random pair voting page, quick vote uses inline feedback only. A toast on top of a modal is noisy.
+
+## Data Layer
+
+### Submission
+
+Use existing `submitVote()` from `shared/lib/supabase.ts` with `QuickVote` type:
+
+```typescript
+submitVote({ cardA: pair.cardA.id, cardB: pair.cardB.id, accuracy: -1 | 0 | 1 })
+```
+
+No changes needed to the `submit_vote` RPC.
+
+### Supabase migration
+
+Add three columns to the `pair_scores` view for per-bucket accuracy breakdown:
+
+```sql
+count(*) filter (where accuracy = -1) as accuracy_lower,
+count(*) filter (where accuracy = 0) as accuracy_right,
+count(*) filter (where accuracy = 1) as accuracy_higher
+```
+
+### Distribution read
+
+New function in `supabase.ts`:
+
+```typescript
+getAccuracyDistribution(cardA: string, cardB: string): Promise<{
+ lower: number;
+ right: number;
+ higher: number;
+ total: number;
+} | null>
+```
+
+Queries `pair_scores` view for the three counts. Returns null if Supabase unavailable or query fails.
+
+### localStorage
+
+- **Key**: `inkweave:vote:{sortedCardA}:{sortedCardB}` (canonical pair ordering matches Supabase)
+- **Value**: `{ accuracy: -1 | 0 | 1, timestamp: number }`
+- Checked on modal open to determine initial state
+- Written after successful submission
+- No expiry (until user auth lands)
+
+## New Files
+
+### `apps/web/src/features/voting/hooks/useQuickVote.ts`
+
+Custom hook encapsulating the full quick vote lifecycle:
+
+- Check localStorage for existing vote on mount
+- `vote(accuracy)` — submit, store in localStorage, fetch distribution
+- Manage state machine (hidden/ready/submitting/result/error)
+- Expose: `state`, `vote`, `distribution`, `userChoice`, `error`
+
+Separate from `useVoteSession` (which is specific to the random pair page).
+
+### `apps/web/src/features/voting/components/QuickVoteControl.tsx`
+
+Presentational component rendering the vote UI based on state. Props:
+
+- `state`: current state from hook
+- `onVote(accuracy)`: callback
+- `distribution`: vote counts (if available)
+- `userChoice`: the user's vote (for result display)
+- `error`: error type (for message display)
+
+Handles desktop (horizontal) and mobile (vertical) layouts via `useResponsive()`.
+
+### `apps/web/src/features/voting/components/DistributionBar.tsx`
+
+Reusable animated bar component. Props:
+
+- `lower`, `right`, `higher`: vote counts
+- `animate`: boolean (true for fresh votes, false for returning pairs)
+
+### `supabase/migrations/YYYYMMDD_add_accuracy_distribution.sql`
+
+Migration adding accuracy_lower/right/higher to pair_scores view.
+
+## Modified Files
+
+- `SynergyDetailModal.tsx` — import and render `QuickVoteControl` between tier label and connections
+- `supabase.ts` — add `getAccuracyDistribution()` function
+- `database.types.ts` — regenerate after migration (adds new view columns)
+- `features/voting/hooks/index.ts` — export `useQuickVote`
+- `features/voting/components/index.ts` — export `QuickVoteControl`, `DistributionBar`
+
+## Testing
+
+### Unit tests (`useQuickVote`)
+
+- Returns hidden state when Supabase unavailable
+- Returns result state when pair found in localStorage
+- Submits accuracy value and transitions to result on success
+- Handles error and rate-limit states correctly
+- Fetches distribution after successful vote
+- Stores vote in localStorage after success
+
+### Component tests (`QuickVoteControl`)
+
+- Renders three buttons in ready state
+- Hides entirely when state is hidden
+- Disables buttons during submission
+- Shows distribution bar in result state
+- Shows first voter badge when total = 1
+- Shows error message on failure, re-enables buttons
+- Vertical layout on mobile, horizontal on desktop
+
+### Integration (within `SynergyDetailModal`)
+
+- Vote section appears below tier label
+- Opening modal for previously-voted pair shows result state
+
+### Storybook
+
+`QuickVoteControl.stories.tsx` with stories for: ready, submitting, result, result-first-voter, error, rate-limited, hidden.
+
+### E2E
+
+Skipped — quick vote hits real Supabase without test environment isolation. Unit/component tests cover the interaction flow. Voting E2E is covered by the random pair page tests.
+
+## Decisions Log
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Placement | Below tier label | Prominent, gut-reaction before reading details |
+| Button labels | "Should be lower/higher" | Unambiguous, references the score directionally |
+| Mobile layout | Vertical stack | Better touch targets, validate during implementation |
+| Post-vote reveal | Distribution bar | Gamification — community signal drives engagement |
+| First voter | Gold badge | Rewards early participation |
+| Returning pairs | localStorage → result state | Avoids "didn't I already vote?" confusion |
+| Supabase down | Hide section | Per issue spec, no broken UI |
+| "Rate in Detail" | Disabled teaser | Placeholder for #213 |
+| Vote threshold | None | Show distribution from 1 vote |
+| Separate hook | `useQuickVote` | Different lifecycle from `useVoteSession` |
diff --git a/supabase/migrations/20260406000001_add_accuracy_distribution.sql b/supabase/migrations/20260406000001_add_accuracy_distribution.sql
new file mode 100644
index 0000000..bfb0727
--- /dev/null
+++ b/supabase/migrations/20260406000001_add_accuracy_distribution.sql
@@ -0,0 +1,30 @@
+drop view if exists pair_scores;
+
+create view pair_scores with (security_invoker = true) as
+select
+ card_a_id,
+ card_b_id,
+ count(*) as total_votes,
+ count(score) as score_votes,
+ count(accuracy) as accuracy_votes,
+
+ internal.trimmed_mean(
+ array_agg(score::numeric) filter (where score is not null)
+ )::numeric(4,2) as avg_score,
+
+ avg(accuracy)::numeric(3,2) as accuracy_sentiment,
+ count(*) filter (where accuracy = -1) as accuracy_lower,
+ count(*) filter (where accuracy = 0) as accuracy_right,
+ count(*) filter (where accuracy = 1) as accuracy_higher,
+ avg(is_real::int)::numeric(3,2) as pct_real,
+ avg(would_play::int)::numeric(3,2) as pct_would_play,
+ count(*) filter (where who_carries = 'a') as carries_a,
+ count(*) filter (where who_carries = 'b') as carries_b,
+ count(*) filter (where who_carries = 'both') as carries_both,
+ count(*) filter (where who_carries = 'neither') as carries_neither,
+ avg(difficulty)::numeric(3,2) as avg_difficulty
+
+from votes
+group by card_a_id, card_b_id;
+
+grant select on pair_scores to anon;