# Design System & Analytics Audit Summary **Date:** April 21, 2026 **Files Analyzed:** 20+ component/config files **Status:** ✅ Complete comprehensive audit --- ## Executive Summary This audit comprehensively catalogs the design system primitives, analytics API, and existing visualization components available for the homepage refactor. The platform has a mature, well-organized design system built on: - **7 core design system components** with TypeScript interfaces - **30+ CSS design tokens** in HSL-based light/dark theme - **Complete analytics API** with market data, heatmaps, trends, and AI advice - **3 chart types** using Recharts with theme-aware styling - **3 map implementations** using Mapbox with fallbacks and interactive features All components follow consistent patterns: explicit props, semantic HTML, accessibility-first, and responsive design. --- ## Quick Stats | Category | Count | Status | |----------|-------|--------| | **Design System Components** | 7 | ✅ Exported + typed | | **Design Tokens** | 30+ | ✅ CSS variables + Tailwind | | **Analytics Endpoints** | 6+ | ✅ Full API coverage | | **Query Hooks** | 4 | ✅ React Query integrated | | **Chart Types** | 3 | ✅ Recharts v2 | | **Map Components** | 3 | ✅ Mapbox GL JS | | **Fonts** | 2 | ✅ Inter + JetBrains Mono | | **Color Variables** | 30 | ✅ Light + dark modes | --- ## File Structure ``` apps/web/ ├── components/ │ ├── design-system/ │ │ ├── stat-card.tsx — KPI metric display │ │ ├── price-delta.tsx — % change with arrows │ │ ├── market-index.tsx — Hero index value │ │ ├── data-table.tsx — Sortable tables │ │ ├── compact-header.tsx — Terminal-style header │ │ ├── dashboard-layout.tsx — Full-page frame │ │ ├── ticker-strip.tsx — Scrolling ticker │ │ └── index.ts — Barrel export │ ├── charts/ │ │ ├── price-trend-chart.tsx — Dual-axis line chart │ │ ├── district-bar-chart.tsx — Bar chart │ │ ├── agent-performance.tsx — Mixed dashboard │ │ └── district-heatmap.tsx — Mapbox heatmap │ └── map/ │ ├── listing-map.tsx — Listing markers │ └── location-picker.tsx — Interactive location ├── lib/ │ ├── analytics-api.ts — Core API endpoints │ ├── tailwind.config.ts — Design tokens │ └── hooks/ │ └── use-analytics.ts — React Query wrappers └── app/ └── globals.css — CSS vars + animations ``` --- ## Component Catalog ### Design System (7 components) 1. **StatCard** — Compact metric with delta indicator 2. **PriceDelta** — Directional % change badge 3. **MarketIndex** — Large hero index value 4. **DataTable** — Sortable, sticky-header table 5. **CompactHeader** — Fixed navbar (48px) 6. **DashboardLayout** — Terminal-style page frame 7. **TickerStrip** — Auto-scrolling ticker animation ### Charts (3 types) 1. **PriceTrendChart** — Line with dual Y-axis 2. **DistrictBarChart** — Rotated axis bar chart 3. **AgentPerformance** — Mixed KPI + funnel dashboard ### Maps (3 implementations) 1. **DistrictHeatmap** — Sized + colored district circles 2. **ListingMap** — Clickable price bubbles 3. **LocationPicker** — Interactive map selection + geocoding --- ## Design Tokens ### Colors (30+) **Semantic Groups:** - **Background:** default, elevated, surface - **Foreground:** default, muted, dim - **Signal:** up (green), down (red), neutral (yellow) - **UI:** border, input, ring, card - **Semantic:** primary, success, warning, destructive **Dark + Light modes** — CSS variables handle both `:root` and `.dark` selector ### Typography - **Fonts:** Inter (UI), JetBrains Mono (data, code) - **Scales:** data-sm (0.75rem), data-md (0.875rem), data-lg (1.25rem), ticker (0.8125rem) - **Alignment:** `tabular-nums` applied via `[data-numeric]` selector ### Spacing - **Rows:** `h-row` (36px) for table rows - **Header:** `h-header-compact` (48px) - **Ticker:** `h-ticker-bar` (32px) ### Animations - **Ticker scroll:** 60s loop, pauses on hover - **Signal flash:** 1s flash on price update --- ## Analytics API ### 6 Main Endpoints | Endpoint | Purpose | Returns | |----------|---------|---------| | `getMarketReport()` | District breakdown by city/period | Array of district stats | | `getHeatmap()` | Heat map data for districts | Array of heatmap points | | `getPriceTrend()` | Historical price trend | Array of period points | | `getDistrictStats()` | Current district KPIs | Array of district stats | | `getNearbyPOIs()` | Points of interest search | Array of POI markers | | `getListingAiAdvice()` | AI valuation + advice | Valuation + advice blocks | ### Data Structures **Market Data:** - `medianPrice: string` — Formatted price (e.g., "7.2 tỷ") - `avgPriceM2: number` — Price per m² (numeric) - `totalListings: number` — Listing count - `daysOnMarket: number` — Average time - `absorptionRate: number | null` — Market velocity - `yoyChange: number | null` — Year-over-year % **AI Data:** - `valuation: { estimateVND, lowVND, highVND, confidence, rationale }` - `advice: { summary, pros[], cons[], suitableFor[] }` - `cacheHit: boolean` — Claude API cache status ### React Query Integration Query keys factory for cache management: ```ts analyticsKeys = { all: ['analytics'], marketReport: (city, period) => [...], heatmap: (city, period) => [...], districtStats: (city, period) => [...], priceTrend: (district, city, propertyType, periods) => [...], } ``` --- ## Key Patterns ### 1. Explicit Props (No Spreading) Every component has typed, documented props. No `{...rest}` patterns for clarity. ### 2. Semantic HTML - Tables use ``, `
` - Headers use `
`, `