# VOTD — Terminology & Voice Guide

Canonical word choices for UI copy, onboarding, prompts, emails, and marketing.
When in doubt, refer here first. Add new decisions at the bottom with a date.

---

## Authentication vs. Verification

| Term | Use | Never use in UI |
|---|---|---|
| **Authentication** | Internal / technical only — the act of proving you're the returning user (OTP login, session token) | Yes — too technical |
| **Verification** | User-facing — the civic act of confirming you're a real, registered voter | — |

**Rule:** Users never see the word "authentication." They verify their number, and eventually become Voter Verified. Authentication is what the system does behind the scenes.

**Examples:**
- ✅ "Verify your number to get started"
- ✅ "Voter Verified"
- ❌ "Authenticate your account"
- ❌ "Two-factor authentication"

---

## Account vs. Profile vs. Registration

| Term | Meaning | When to use |
|---|---|---|
| **Profile** | Your civic identity — name, photo, address, verification badge | The tab, the card, editing your info |
| **Registration** | The act of completing verification steps (phone + name + address) | All nudges, re-engagement prompts, CTAs |
| **Account** | Avoid in UI — implies a subscription or service relationship | Internal only if needed |

**Rule:** You don't "create an account" — you "set up your profile" and "complete registration." Account can appear in legal/settings contexts where users expect it, but not in onboarding or prompts.

**Examples:**
- ✅ "Set up your profile"
- ✅ "Complete registration"
- ✅ "My Profile" (tab label)
- ❌ "Create your account"
- ❌ "Account settings"

---

## Set up vs. Complete vs. Finish

| Term | When to use |
|---|---|
| **Set up** | First entry into the profile flow — initiating something new |
| **Complete** | Re-engagement nudges and prompts — something already started |
| **Finish** | Avoid in UI generally — exception: "Finish Signing Up" for `phone_verified` CTA (see note below) |

**Rule:** "Set up your profile" on the name screen (first time). "Complete registration" on every subsequent prompt and nudge. Never "Finish" in UI copy.

**Examples:**
- ✅ "Set up your profile 👤" — name screen heading
- ✅ "Complete Registration" — all nudge CTAs
- ✅ "Complete Sign Up" — post-OTP SkipOverlay primary button
- ✅ "Finish Signing Up" — `phone_verified` profile card and post-vote nudge CTA
- ❌ "Finish later"

---

## Votes — counting language

How to describe what happens to a vote at each verification stage.

| State | Correct framing | Avoid |
|---|---|---|
| Guest / unverified | "Your votes won't count towards the results" | "Your votes don't count" (too blunt) |
| Phone verified | "Your votes are saved — complete registration to have them counted" | "Your votes are recorded but meaningless" |
| Verifying | "Your votes are queued — they'll be counted once residency is confirmed" | "Your votes are pending" (vague) |
| Verified | "Your votes count" | — |

**Rule:** Always frame the absence of counting as a solvable state, not a permanent condition. The vote was heard — it just hasn't been counted yet.

---

## Residency vs. Address vs. Voter registration

| Term | When to use |
|---|---|
| **Primary address** | The field label and form copy — neutral, familiar |
| **Residency** | When describing the confirmation step — "once residency is confirmed" |
| **Voter registration** | When describing the matching step — "matching your voter registration" |
| **Address verification** | Avoid — too technical, sounds like a bank |

**Examples:**
- ✅ "Add your name and primary address"
- ✅ "Your votes can count once residency is confirmed"
- ✅ "Matching your voter registration — votes are queued"
- ❌ "Address verification required"
- ❌ "Verify your address"

---

## Verification badge labels (UI only)

These are the exact strings used in the profile badge. Do not vary them.

| `verificationLevel` | Badge label |
|---|---|
| `unverified` | Guest |
| `phone_verified` | Phone Confirmed |
| `verifying` | Verifying |
| `verified` | Voter Verified |
| `rejected` | Not Matched |

---

## Set up vs. Complete vs. Finish

**Update (March 2026):** "Finish Signing Up" is now the canonical CTA for `phone_verified` users on the profile card and post-vote nudge. This is an exception to the "avoid Finish" rule — it was chosen because "Complete Registration" implies a formality that doesn't match the lightweight phone-only state. The rule below still applies to all other surfaces.

---

## Prompt copy — canonical strings

Exact copy locked for each prompt surface. Change here first, then propagate to code.

| Surface | Message | Primary CTA | Secondary |
|---|---|---|---|
| Feed — guest 1st tap | "Verify your number to get started" | Verify | Skip for now |
| Feed — guest 2nd+ tap | "Voting requires phone verification." | Verify | Skip for now |
| Profile setup — skip overlay (post-OTP) | "Make your vote count. See live results. Propose your own votes." | Complete Sign Up | Skip for now |
| Profile — phone_verified card | — | Finish Signing Up | Preview verified profile → *(tester only)* |
| Profile — verifying note | "Matching your voter registration — votes are queued" | — (no CTA) | — |
| Vote-item — phone_verified post-vote nudge | "Your vote is recorded. Finish signing up for it to count toward the results." | Finish Signing Up | Skip for now |
| Vote-item — guest gate (1st tap) | "Confirm your number to continue" | Add My Number | Skip for now |

---

---

## Screen Names

Canonical labels used in feedback submissions, analytics, and internal tooling. These are the values written to `feedback.screen` and must match the lookup table in `FeedbackWidget.tsx`.

| Route path | Screen label |
|---|---|
| `/` | `Vote Index` |
| `/votd` | `Feed` |
| `/feed` | `Feed` |
| `/vote-item` | `Vote Item` |
| `/profile` | `Profile` |
| `/my-votes` | `My Votes` |
| `/onboarding` | `Onboarding` |
| `/signup` | `Account` |
| `/verify-otp` | `Account` |
| `/address-setup` | `Account` |
| `/photo-setup` | `Account` |
| `/profile-setup` | `Account` |
| `/propose` | `Propose` |

**Rule:** All signup sub-screens roll up to `Account` — they are one journey. If a new route is added, add its label here and to the lookup table in `FeedbackWidget.tsx` before shipping.

---

## Nav Tabs

There are three tabs in the bottom nav bar. No labels are shown — icon only.

| Position | Icon | Screen | Code name | What it shows |
|---|---|---|---|---|
| Left | Ballot box | Vote Index | `VoteIndexScreen` | List of all open and closed votes |
| Middle | Feed lines | Feed | `FeedScreen` | App activity updates relevant to the user |
| Right | Person | Profile | `ProfileScreen` | User profile and verification status |

The Vote of the Day experience (`VOTDOverlayCard`) is associated with the Index tab. On open, repeat visitors land directly on it — dismissing it reveals the Index behind it. It is mounted at the root layout level so it can appear before tab navigation resolves.

---

## Component & Panel Names

Canonical names for UI components and panels used in code, design, and internal discussion. Use these names consistently across Figma, code comments, and PR descriptions.

| Component | Canonical name | Notes |
|---|---|---|
| The full-screen overlay for the Vote of the Day | **VOTDOverlayCard** | Associated with Index tab — on open it appears over Index; dismissing returns to Index. Contains reading → choosing → voted states |
| The bar that shows yes/no split and lets you cast a vote | **StickyVoteBar** | Appears at the bottom of Vote Item and VOTD overlay |
| The panel with platform icons for sharing | **SharePanel** | Single-tap model — one tap sends to that platform |
| The poster image shown in the share panel | **SharePosterPreview** | Variant-aware: Vote, Yes, No, Brand |
| The persistent flag icon in the top-right corner | **GlobalFeedbackFlag** | Lives in `_layout.tsx` only — never inline |
| The card in the feed for a regular vote item | **VoteCard** | Tapping navigates to Vote Item screen |
| The signup prompt that slides up during a guest action | **SkipOverlay** | "Guest nudge" in conversation; `SkipOverlay` in code |
| The propose a vote modal | **ProposeVoteModal** | Accessible via + button in confirmation header |

---

## Feed Card Types

Canonical component names for Daily Feed card types. These are the full identity — no generic suffixes like `Card` or `Widget`. See DESIGN_DECISIONS.md §"Feed order" for slot positions and card tiers.

| Component | Card tier | Action button | Notes |
|---|---|---|---|
| `ClosingSoon` | cardFeat | — | Slot 1, hero countdown |
| `TopVoteArea` | cardFeat | — | Top Votes scoped to geographic area (Country, State, Local) |
| `TopVoteTopic` | cardFeat | — | Top Votes scoped to topic category. Distinct from `TopIssuesByTopic` |
| `YourSideIsLosing` | cardFeat | Share This Vote | Voted + currently losing |
| `NeighborProposal` | cardStd | — | Most recent neighbor-submitted proposal |
| `Breaker` | brkComp | — | Data-insight module with interchangeable content |
| `CommunityVoted` | cardStd | — | Most recently closed vote in user's community |
| `AddResearch` | cardFeat | Add Research | Open votes 5–12 days old with fewest sources |
| `JustClosed` | cardStd | — | Recently closed vote |
| `YourMilestones` | cardStd | — | Personal stats |
| `StandAndBeCounted` | cardFeat | — | Aggregate counts |
| `YourBacklog` | compactCard | — | Open votes user hasn't voted on yet |
| `PushToTheFinish` | cardFeat | Share This Vote | Open votes near deadline, voted + winning |
| `TopIssuesByTopic` | cardStd | — | Ranked topic-category list (slot 23) |

**Naming rules:**
- No generic suffixes — the component name is the full identity.
- `TopVoteArea` ≠ `TopVoteTopic` ≠ `TopIssuesByTopic` — three distinct components.
- `Breaker` is the one exception where the visual type IS the name.

---

*Last updated: April 2026*