ui-conventions

name	ui-conventions
description	UI rules for the Kerala elections app. Use when: modifying components, adding status indicators, changing how candidates or constituencies display, or touching motion.

UI Conventions

When to Use

• Modifying any component in src/components/ or src/pages/
• Adding visual indicators for coverage, review state, or seat trust
• Changing constituency, candidate, district, or motion behavior
• Changing browse flow or surface hierarchy

Readability Baseline

• Favor higher-contrast supporting text on both light and dark themes
• Keep recurring small UI text and chips around 0.78rem or larger unless space is truly constrained
• Disabled cards and chips should stay visibly greyed out without becoming hard to read
• Put reusable colors in src/index.css theme tokens, not hardcoded component values
• Give published named party/front lanes first-class chips; do not leave NTK or other live named lanes on generic default styling that can read like missing data

Grey-Out Rules

State Browse (src/pages/StatePage.jsx)

• A district row is active only if every constituency in that district has at least one candidate
• Check is per-constituency existence, not aggregate count
• Incomplete districts stay greyed out and non-clickable in the state list
• Keep state browse list-first; do not reintroduce district map cards or zoom controls

Candidate Cards (src/components/CandidateCard.jsx)

• Cards with no public detail (!candidate.hasDetail) render as non-clickable <div> not <Link>
• Disabled cards use opacity: 0.55, filter: grayscale(0.35), and cursor: not-allowed
• Show profile updating when disabled
• Multi-candidate seats sort by LDF -> UDF -> NDA -> independent -> other
• On constituency pages, keep the card face comparison-first: name, front chip, party badge, verification state, reviewed date, and one-line latest public update
• Latest update previews must come only from voter-useful non-statewide_admin timeline events and should prefer non-scaffold chronology over candidate_facts / district_packet filler

District Candidate Chips (src/pages/DistrictPage.jsx)

• Keep a small visible gap between the party badge and candidate name
• Disabled chips stay greyed out with profile updating
• Enabled chips open based on public detail availability, not timeline length alone
• Keep the district surface minimal: quiet header, restrained metadata, and a seat-list feel rather than badge-heavy mosaics
• Use the compact representation pill to surface already-published NTK or other extra-party lanes instead of leaving them implicit in raw row counts alone
• On phones, keep seat-row metadata docked alongside the seat title or immediately under it; do not introduce tall dead space by stacking the whole row with space-between

Surface Rules

ConstituencyPage (src/pages/ConstituencyPage.jsx)

• Treat this as the compact comparison surface
• Keep the breadcrumb and existing route structure
• Show one seat-summary row with field state, exact reviewed date, and conservative copy
• If a public-safe constituency outcome row exists, render one quiet possible-outcome module below that seat-summary row, not above it
• Keep that module compact: public-safe label, confidence, exact reviewed date, short summary, and source links only
• withheld must stay visible, stale must be explicit, and unavailable should hide the module instead of rendering placeholder chrome
• When a live seat already carries an NTK lane, surface that explicitly in the representation pill instead of folding it into a generic count
• On Tamil Nadu pilot seats with only three published rows, surface field expanding so missing-party gaps do not read like a final field
• Use verified field, mixed field, or field under review
• Do not imply the seat is final before post-withdrawal admin evidence exists

CandidatePage (src/pages/CandidatePage.jsx)

• Keep the shared app header and back button, with the breadcrumb just below the header
• Keep the breadcrumb and page shell mounted while candidate detail loads; use an in-place skeleton instead of swapping the whole route
• Do not add a constituency-page breadcrumb link back into the candidate-route header chrome
• Add one quiet metadata row below the breadcrumb for verification, last reviewed, and chronology depth
• On phones, keep the portrait, quiet metadata row, filing/confidence context, and current-read/evidence control inside one compact summary card; do not split them into tall sparse helper sections
• Render one merged candidate-focused chronology in latest-to-oldest order (top-down) while preserving full historical depth; do not split current-cycle and historical events into separate blocks
• Expose filing-status and confidence context plus an expandable evidence panel (current read, known gaps, and source anchors) on candidate pages
• When source-backed disclosure or legal watchouts exist, surface one compact snapshot in that same top card using the existing timeline watchout derivation; when a case-bearing or legal watchout exists, prefer it over weaker non-case caution copy, and do not add a second manual summary field or a declaration-only widget
• Any track-record summary strip must be deterministic, derived only from already-reviewed dossier data and the visible chronology, must not add a handwritten per-candidate summary field, should prefer concrete sourced history highlights over generic milestone counts, and must not invent absent-day, attendance-rate, or discussions-started numbers unless the dossier text explicitly states them
• Open the full latest-to-oldest chronology by default; a lightweight toggle may still expose a condensed short route, and both modes must preserve latest-to-oldest ordering
• Keep candidate_facts / district_packet items out of the main feed when real candidate milestones exist; use them only as quiet fallback context for thin dossiers
• Keep generic current-cycle seat-tracking cards such as "reported", "fielded", "kept live", or district-packet/list summaries out of the main feed when stronger candidate-specific milestones exist, even if those cards were manually curated
• Suppress statewide-admin schedule items when enough candidate-focused material exists; allow them only as last-resort fallback when the route would otherwise drop below the shipped 20-event floor
• Prioritize candidate-specific public-record and political-career milestones over seat-context filler
• Keep the chronology shell visually flat and minimal; avoid stacked helper boxes, pill clutter, or heavy card shadows around the feed
• Keep source links inline when they exist

Empty States

• Use <div className="empty-state"> with <div className="empty-icon">
• Copy should be voter-facing and avoid dev jargon
• Reference the election timeline when relevant
• Do not replace an already-loaded route with a hard unavailable / not found empty state just because a later background runtime refresh failed; keep the last good content mounted and use one quiet stale-data signal instead

Motion

• Prefer runViewTransition and TransitionLink for route changes
• Keep motion quiet: short lift/crossfade, restrained stagger, no blur-heavy transitions
• Route transitions own route-enter animation; do not stack page-shell fade/stagger or item-level enter animations on the same route change
• Avoid stacking container-level and item-level entrance animations on the same surface
• Preserve prefers-reduced-motion

Shared Helpers

• Use src/utils/candidates.js for sort order and constituency field-summary / verification-label helpers
• Keep candidate chronology visibility, preview, and timelineMeta derivation centralized in src/utils/candidateTimeline.js

CSS Organization

• src/styles/cards.css: cards, chips, disabled states, constituency comparison layout
• src/styles/timeline.css: merged candidate chronology layout and empty state
• src/styles/readme.css: /about explainer typography
• src/index.css: tokens, layout, route transitions, shared UI primitives