diff --git a/docs/plans/2026-02-28-ui-redesign-design.md b/docs/plans/2026-02-28-ui-redesign-design.md new file mode 100644 index 0000000..c44cb83 --- /dev/null +++ b/docs/plans/2026-02-28-ui-redesign-design.md @@ -0,0 +1,167 @@ +# UI/UX Redesign: Map-First with Modern Chrome + +**Date:** 2026-02-28 +**Status:** Approved +**Approach:** C — Preserve map-first architecture, modernize filter UX, visual polish, URL state + +## Context + +The realestate-crawler frontend is a React 19 + Vite + Tailwind 4 + shadcn/ui SPA with Mapbox GL hexgrid heatmap, Tinder-style swipe review, POI travel times, and real-time WebSocket task progress. Competitive analysis of Rightmove, Zoopla, and ImmobilienScout24 identified best practices to adopt while preserving our unique differentiators. + +## Pain Points Addressed + +1. **Visual polish** — Functional but plain shadcn defaults; needs better typography, spacing, card design +2. **Filter workflow** — Sidebar with collapsible accordions is hard to discover and use +3. **Navigation & URL state** — No deep linking, browser back/forward doesn't work, can't share filtered views +4. **Property cards** — Need richer info display, better image presentation, clearer hierarchy + +## Design Decisions + +### 1. Layout & Navigation Architecture + +**Desktop (>= 768px):** +``` ++------------------------------------------------------------------+ +| Header (h-12): [Logo] [Rent|Buy] [Health] --- [Tasks] [User] | ++------------------------------------------------------------------+ +| Filter Bar (h-10): [Price ▾] [Beds ▾] [Size ▾] [More ▾] | chips | ++------------------------------------------------------------------+ +| Main Content Area | +| Map (default) | Split (map 60% + list 40%) | List | Saved | ++------------------------------------------------------------------+ +| Status Bar (h-8): [1,234 results] [Avg: £2,100] [Map|Split|List] | ++------------------------------------------------------------------+ +``` + +Key changes: +- Sidebar removed entirely — filter bar is horizontal, below header +- Rent/Buy toggle promoted into header +- Active filter chips inline in filter bar +- View mode toggle in status bar +- Full viewport width for map (no sidebar stealing space) + +**Mobile (< 768px):** +``` ++------------------------------------------+ +| Header (h-12): [Logo] ---- [Filter] [≡] | ++------------------------------------------+ +| Full-screen Map + FABs | ++------------------------------------------+ +| Bottom Sheet (draggable) | +| Active filter chips (scrollable row) | +| [Stats] [Horizontal card row] | ++------------------------------------------+ +``` + +Mobile filter opens as full-screen modal (not sidebar sheet). + +**React Router URL structure:** +``` +/ → Map view, default filters +/map?type=rent&minPrice=1000&maxPrice=2500&beds=2 +/split?type=buy&district=hackney +/list?type=rent&sort=price_asc +/saved +/listing/12345678 → Deep link to listing detail +``` + +### 2. Filter System + +**Horizontal filter bar** replaces the sidebar: +- Primary filters always visible as compact dropdowns: Listing type, Price range, Bedrooms, Min size +- "More filters" button opens a popover panel with: Max size, Price/m², Furnishing, District, Available from, Last seen days, POI travel time filters +- Active filter chips render in a second row when filters are applied (removable with ×) +- "Show Listings" / "Scrape New" buttons right-aligned in filter bar +- "Color by" visualization control moves to status bar + +**Mobile:** Full-screen filter modal with stacked fields and sticky "Apply" button. + +### 3. Property Cards + +**Full card (list/split view):** +``` ++---------------------------------------+ +| [Image Carousel - 16:10 ratio] | +| 1/9 [♥] [↗ RM] | ++---------------------------------------+ +| £2,500/mo ● Good Deal | +| 2 bed · 65 m² · £38/m² | +| Shoreditch, London E1 | ++---------------------------------------+ +| 🚶 12min 🚲 8min 🚌 25min | +| Foxtons · Listed 3d ago | ++---------------------------------------+ +``` + +Key improvements: +- Larger image carousel (16:10 aspect ratio) +- Price as dominant element — large, bold +- Deal indicator with colored dot + text +- Key metrics on one line: beds · sqm · price/sqm +- POI travel times as compact badges +- Agency + freshness de-emphasized at bottom +- Heart + external link overlaid on image + +**Compact card (mobile bottom sheet):** +``` ++------------------+ +| [Photo 4:3] | +| £2,500 2bd | +| Shoreditch | ++------------------+ +``` + +### 4. Visual Design System + +**Color palette:** +| Role | Value | Usage | +|------|-------|-------| +| Primary | Slate 900 `#0f172a` | Headers, primary text | +| Accent | Teal 600 `#0d9488` | CTAs, active filters, map | +| Good deal | Emerald 500 `#10b981` | Price indicators | +| Above avg | Amber 500 `#f59e0b` | Warning indicators | +| Background | White / Slate 50 | Card surfaces | +| Muted | Slate 100-200 | Filter bar bg | +| Map dark | Slate 800 | Map overlay controls | + +**Typography:** +- Price: `text-xl font-bold tracking-tight` +- Location: `text-sm font-medium` +- Metrics: `text-sm text-muted-foreground` +- Chips/badges: `text-xs font-medium` + +**Spacing:** 4px base, 16px card padding, 12px card gaps, 8px inline gaps. + +### 5. Listing Detail Sheet + +Larger drawer (60% viewport desktop, 90% mobile) with tabbed sections: +- **Photo gallery** — Full width, swipeable, with photo/floorplan toggle +- **Header** — Price, deal indicator, key metrics, actions +- **Tabs:** Overview (features + description), Travel (POI distances), Price History (timeline), Details (property attributes) + +## What's Preserved (No Changes) + +- Hexgrid heatmap visualization (Web Worker) +- Tinder-style swipe review mode +- POI travel time calculations +- WebSocket real-time task progress +- Streaming NDJSON data loading +- Dual auth (Passkey + SSO) +- Mobile bottom sheet with snap points +- SwipeableCardRow horizontal scroll + +## Technical Approach + +- Add `react-router-dom` for URL-based navigation +- Decompose App.tsx (713 lines) — extract filter state to context provider +- Extract duplicated utilities (formatDuration, formatCurrency, etc.) +- New component: `FilterBar` (replaces `FilterPanel` sidebar layout) +- Refactor `PropertyCard` for new visual hierarchy +- Update `index.css` with new color palette CSS variables +- Add error boundaries + +## Out of Scope + +- Backend API changes (all data already available) +- New features (saved searches, alerts, text search) +- State management library (keep React state, just decompose)