docs: consolidate exploration & audit reports under docs/ (TEC-3094)
- Move 8 stray .md (+5 .txt) from ~/Desktop into docs/explorations/from-desktop/ - Reorganize 27 .md/.txt at workspace root: - audit reports -> docs/audits/ - exploration reports -> docs/explorations/ - design system -> docs/design-system/ - Keep only README/CHANGELOG/CONTRIBUTING/CLAUDE at repo root - Refresh docs/README.md as canonical index with links to all groups - Note: pre-existing docs/audits/AUDIT_INDEX.md and AUDIT_SUMMARY.md were overwritten by the newer root-level versions during the move Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
680
docs/design-system/DESIGN_SYSTEM_AUDIT_2026_04_21.md
Normal file
680
docs/design-system/DESIGN_SYSTEM_AUDIT_2026_04_21.md
Normal file
@@ -0,0 +1,680 @@
|
||||
# Design System & Analytics API Audit Report
|
||||
**Date:** April 21, 2026
|
||||
**Scope:** Design system primitives, analytics API, charts, and map components for homepage refactor
|
||||
|
||||
---
|
||||
|
||||
## 1. Design System Components
|
||||
|
||||
**Location:** `apps/web/components/design-system/`
|
||||
|
||||
All components are exported from a central index and follow a consistent pattern with TypeScript props interfaces.
|
||||
|
||||
### Component Inventory
|
||||
|
||||
#### **StatCard** (`stat-card.tsx`)
|
||||
- **Purpose:** Compact KPI metric display for market dashboards
|
||||
- **Props:**
|
||||
- `label: string` — metric name (e.g., "Giá TB/m²")
|
||||
- `value: string | number` — formatted main value
|
||||
- `unit?: string` — unit suffix (e.g., "tr/m²")
|
||||
- `delta?: number` — percentage change
|
||||
- `deltaDirection?: PriceDeltaDirection` — forces up/down/neutral
|
||||
- `sublabel?: string` — secondary text (e.g., "24h", "7 ngày")
|
||||
- `icon?: React.ReactNode` — optional prefix icon
|
||||
- **Layout:** Vertical flex, small header (muted sans), large mono value, optional delta + sublabel
|
||||
- **Styling:** Border, elevated background, consistent spacing (gap-1)
|
||||
- **Key Feature:** Integrates PriceDelta component for visual signals
|
||||
|
||||
---
|
||||
|
||||
#### **PriceDelta** (`price-delta.tsx`)
|
||||
- **Purpose:** Display percentage change with directional arrow icon
|
||||
- **Props:**
|
||||
- `value: number` — percentage (positive = up, negative = down)
|
||||
- `unit?: string` — default "%", can override (e.g., "₫")
|
||||
- `precision?: number` — decimal places, default 2
|
||||
- `hideIcon?: boolean` — hide arrow icon if true
|
||||
- `direction?: PriceDeltaDirection` — override direction ('up' | 'down' | 'neutral')
|
||||
- `size?: 'sm' | 'md' | 'lg'` — text size (data-sm, data-md, data-lg)
|
||||
- **Icons:** ArrowUp (green/up), ArrowDown (red/down), Minus (yellow/neutral)
|
||||
- **Styling:** `font-mono`, `tabular-nums`, signal colors from design tokens
|
||||
- **Key Feature:** Smart direction inference; always formats with +/- prefix
|
||||
|
||||
---
|
||||
|
||||
#### **MarketIndex** (`market-index.tsx`)
|
||||
- **Purpose:** Display large market index value with change indicator
|
||||
- **Props:**
|
||||
- `name: string` — index title (e.g., "GGX Market")
|
||||
- `value: string | number` — current index value
|
||||
- `changePercent: number` — percentage change
|
||||
- `change?: string | number` — absolute change (optional)
|
||||
- `window?: string` — timeframe, default "24h"
|
||||
- `direction?: PriceDeltaDirection` — override direction
|
||||
- **Layout:** Horizontal; left: name + large value; right: delta + metadata
|
||||
- **Styling:** `text-3xl` mono, hero-style for dashboards
|
||||
- **Key Feature:** Companion text shows change amount + window frame
|
||||
|
||||
---
|
||||
|
||||
#### **DataTable** (`data-table.tsx`)
|
||||
- **Purpose:** Sortable, sticky-header table for ticker/market data
|
||||
- **Props:**
|
||||
- `columns: DataTableColumn<T>[]` — column definitions
|
||||
- `data: T[]` — row data
|
||||
- `getRowId?: (row, index) => string | number` — row key fn
|
||||
- `onRowClick?: (row) => void` — row click handler
|
||||
- `stickyHeader?: boolean` — sticky headers (default true)
|
||||
- `loading?: boolean` — loading state
|
||||
- `emptyText?: React.ReactNode` — empty state text
|
||||
- `dense?: boolean` — compact rows (default true), 36px (h-row) vs 40px
|
||||
- `defaultSortId?: string` — initial sort column
|
||||
- `defaultSortDir?: 'asc' | 'desc'` — initial sort direction
|
||||
- **Column Definition:**
|
||||
```ts
|
||||
interface DataTableColumn<T> {
|
||||
id: string;
|
||||
header: React.ReactNode;
|
||||
cell: (row: T, index: number) => React.ReactNode;
|
||||
align?: 'left' | 'right' | 'center';
|
||||
sortable?: boolean;
|
||||
sortValue?: (row: T) => number | string;
|
||||
width?: string;
|
||||
numeric?: boolean; // renders with font-mono, tabular-nums
|
||||
}
|
||||
```
|
||||
- **Features:**
|
||||
- Client-side sort (no fetch)
|
||||
- Alternating row backgrounds
|
||||
- Hover highlight
|
||||
- Sort icons (ChevronUp/Down)
|
||||
- Numeric cells use `font-mono` with `tabular-nums`
|
||||
- **Styling:** `h-row` (36px dense, 40px normal), border-b, alternating bg-surface/40
|
||||
|
||||
---
|
||||
|
||||
#### **CompactHeader** (`compact-header.tsx`)
|
||||
- **Purpose:** Terminal-style compact header (h: 48px / h-header-compact)
|
||||
- **Props:**
|
||||
- `logo?: React.ReactNode`
|
||||
- `breadcrumb?: React.ReactNode`
|
||||
- `search?: React.ReactNode` — hidden on mobile
|
||||
- `actions?: React.ReactNode` — right-aligned action buttons
|
||||
- **Layout:** Flex row; logo | breadcrumb | [gap] | search (md:flex) | [auto-grow] | actions
|
||||
- **Styling:** Sticky, border-b, elevated bg, px-4
|
||||
|
||||
---
|
||||
|
||||
#### **TickerStrip** (`ticker-strip.tsx`)
|
||||
- **Purpose:** Horizontal scrolling ticker animation for top districts/indices
|
||||
- **Props:**
|
||||
- `items: TickerItem[]` — array of {id, label, changePercent, direction?}
|
||||
- `paused?: boolean` — disable animation (for tests/reduced motion)
|
||||
- **Animation:** Duplicates items, translates -50% over 60s, pauses on hover
|
||||
- **Styling:** `font-mono text-ticker`, gap-6, monospace numbers
|
||||
- **Key Feature:** Self-contained animation loop without external dependencies
|
||||
|
||||
---
|
||||
|
||||
#### **DashboardLayout** (`dashboard-layout.tsx`)
|
||||
- **Purpose:** Terminal-style dashboard frame with fixed header, sidebar, ticker, status bar
|
||||
- **Props:**
|
||||
- `header?: React.ReactNode`
|
||||
- `sidebar?: React.ReactNode`
|
||||
- `ticker?: React.ReactNode`
|
||||
- `statusBar?: React.ReactNode`
|
||||
- `sidebarWidth?: number` — expanded width (default 200px), collapsed 56px
|
||||
- `sidebarCollapsed?: boolean` — collapse state
|
||||
- `children: React.ReactNode` — main content
|
||||
- **Layout Structure:**
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ TICKER (h-ticker-bar: 32px) │
|
||||
├────────┬──────────────────────────┤
|
||||
│ SIDEBAR│ HEADER (h-header-compact)│
|
||||
│ 56px ├──────────────────────────┤
|
||||
│ (or │ MAIN (overflow-y-auto) │
|
||||
│ expand)│ (flex-1) │
|
||||
├────────┴──────────────────────────┤
|
||||
│ STATUS BAR (h-6: 24px) │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
- **Styling:** `min-h-screen` flex, smooth sidebar transition (duration-200)
|
||||
|
||||
---
|
||||
|
||||
## 2. Design Tokens & Theme System
|
||||
|
||||
**Location:** `apps/web/app/globals.css` + `apps/web/tailwind.config.ts`
|
||||
|
||||
### CSS Custom Properties (Dark + Light Modes)
|
||||
|
||||
#### Core Color Palette
|
||||
```css
|
||||
/* Light Mode */
|
||||
--background: 0 0% 97% /* Off-white */
|
||||
--background-elevated: 0 0% 100% /* Pure white */
|
||||
--background-surface: 220 14% 96% /* Subtle gray */
|
||||
--foreground: 220 20% 12% /* Dark navy */
|
||||
--foreground-muted: 215 12% 45% /* Medium gray */
|
||||
--foreground-dim: 215 12% 60% /* Light gray */
|
||||
|
||||
/* Dark Mode */
|
||||
--background: 220 20% 4% /* Very dark */
|
||||
--background-elevated: 220 18% 7% /* Elevated dark */
|
||||
--background-surface: 220 16% 10% /* Surface dark */
|
||||
--foreground: 210 20% 90% /* Off-white */
|
||||
--foreground-muted: 215 15% 55% /* Muted gray */
|
||||
--foreground-dim: 215 12% 35% /* Dim gray */
|
||||
```
|
||||
|
||||
#### Semantic Colors
|
||||
```css
|
||||
--primary: 142 72% 42% /* Green: market index */
|
||||
--primary-foreground: 0 0% 100%
|
||||
--primary-hover: 142 72% 36%
|
||||
|
||||
--signal-up: 142 72% 38% /* Green for up trend */
|
||||
--signal-down: 0 84% 55% /* Red for down trend */
|
||||
--signal-neutral: 45 93% 45% /* Yellow/orange for neutral */
|
||||
|
||||
--success: 142 72% 42%
|
||||
--warning: 45 93% 47%
|
||||
--destructive: 0 84% 60.2%
|
||||
```
|
||||
|
||||
#### UI Surface Colors
|
||||
```css
|
||||
--border: 220 13% 88% /* Light borders */
|
||||
--border-strong: 220 13% 78%
|
||||
--card: 0 0% 100% /* Card background */
|
||||
--input: 214.3 31.8% 91.4% /* Form input bg */
|
||||
--ring: 142 72% 42% /* Focus ring */
|
||||
```
|
||||
|
||||
### Typography
|
||||
|
||||
**Fonts (Tailwind config):**
|
||||
- `font-sans`: Inter (var(--font-inter)) — UI text
|
||||
- `font-mono`: JetBrains Mono (var(--font-jetbrains-mono)) — numbers, code
|
||||
|
||||
**Data-Specific Font Sizes (Tailwind):**
|
||||
- `text-ticker`: 0.8125rem, line-height 1, letter-spacing 0.01em
|
||||
- `text-data-sm`: 0.75rem, line-height 1.2
|
||||
- `text-data-md`: 0.875rem, line-height 1.3
|
||||
- `text-data-lg`: 1.25rem, line-height 1.2
|
||||
|
||||
### Spacing (Tailwind)
|
||||
|
||||
- `cell`: 0.5rem — compact table cells
|
||||
- `row`: 2.25rem (36px) — table row height (h-row)
|
||||
- `ticker-bar`: 2rem (32px) — ticker strip height
|
||||
- `header-compact`: 3rem (48px) — dashboard header
|
||||
|
||||
### Shadows
|
||||
|
||||
- `elevation-1`: 0 1px 2px rgba(0, 0, 0, 0.3) — subtle
|
||||
- `elevation-2`: 0 4px 12px rgba(0, 0, 0, 0.4) — prominent
|
||||
|
||||
### Animations
|
||||
|
||||
- `animate-ticker`: 60s linear infinite, translateX(-50%), pauses on hover
|
||||
- `flash-up`: 1s ease-out, signal-up-bg background flash
|
||||
- `flash-down`: 1s ease-out, signal-down-bg background flash
|
||||
|
||||
### CSS Utilities
|
||||
|
||||
- `[data-numeric]`: Applied to numeric cells → `font-variant-numeric: tabular-nums`
|
||||
- `.font-mono`: Also gets `tabular-nums` for alignment
|
||||
|
||||
---
|
||||
|
||||
## 3. Analytics API
|
||||
|
||||
**Location:** `apps/web/lib/analytics-api.ts`
|
||||
|
||||
### Core API Client
|
||||
|
||||
Uses a shared `apiClient` (from `api-client.ts`) for HTTP requests.
|
||||
|
||||
### Exported Interfaces & Functions
|
||||
|
||||
#### Market Data Endpoints
|
||||
|
||||
```ts
|
||||
interface MarketReportDistrict {
|
||||
district: string;
|
||||
city: string;
|
||||
propertyType: string;
|
||||
period: string;
|
||||
medianPrice: string;
|
||||
avgPriceM2: number;
|
||||
totalListings: number;
|
||||
daysOnMarket: number;
|
||||
inventoryLevel: number;
|
||||
absorptionRate: number | null;
|
||||
yoyChange: number | null;
|
||||
}
|
||||
|
||||
interface MarketReportResponse {
|
||||
city: string;
|
||||
period: string;
|
||||
districts: MarketReportDistrict[];
|
||||
}
|
||||
|
||||
getMarketReport(city: string, period: string, propertyType?: string)
|
||||
→ Promise<MarketReportResponse>
|
||||
```
|
||||
|
||||
#### Heatmap Data
|
||||
|
||||
```ts
|
||||
interface HeatmapDataPoint {
|
||||
district: string;
|
||||
city: string;
|
||||
avgPriceM2: number;
|
||||
totalListings: number;
|
||||
medianPrice: string;
|
||||
}
|
||||
|
||||
interface HeatmapResponse {
|
||||
city: string;
|
||||
period: string;
|
||||
dataPoints: HeatmapDataPoint[];
|
||||
}
|
||||
|
||||
getHeatmap(city: string, period: string)
|
||||
→ Promise<HeatmapResponse>
|
||||
```
|
||||
|
||||
#### Price Trend Analysis
|
||||
|
||||
```ts
|
||||
interface PriceTrendPoint {
|
||||
period: string;
|
||||
medianPrice: string;
|
||||
avgPriceM2: number;
|
||||
totalListings: number;
|
||||
}
|
||||
|
||||
interface PriceTrendResponse {
|
||||
district: string;
|
||||
city: string;
|
||||
propertyType: string;
|
||||
trend: PriceTrendPoint[];
|
||||
}
|
||||
|
||||
getPriceTrend(district: string, city: string, propertyType: string, periods: string[])
|
||||
→ Promise<PriceTrendResponse>
|
||||
```
|
||||
|
||||
#### District Statistics
|
||||
|
||||
```ts
|
||||
interface DistrictStats {
|
||||
district: string;
|
||||
city: string;
|
||||
propertyType: string;
|
||||
medianPrice: string;
|
||||
avgPriceM2: number;
|
||||
totalListings: number;
|
||||
daysOnMarket: number;
|
||||
inventoryLevel: number;
|
||||
absorptionRate: number | null;
|
||||
yoyChange: number | null;
|
||||
}
|
||||
|
||||
interface DistrictStatsResponse {
|
||||
city: string;
|
||||
period: string;
|
||||
districts: DistrictStats[];
|
||||
}
|
||||
|
||||
getDistrictStats(city: string, period: string)
|
||||
→ Promise<DistrictStatsResponse>
|
||||
```
|
||||
|
||||
#### POI & Nearby Search
|
||||
|
||||
```ts
|
||||
type NearbyPOICategory = 'school' | 'hospital' | 'transit' | 'shopping' | 'restaurant' | 'park';
|
||||
|
||||
interface NearbyPOI {
|
||||
id: string;
|
||||
name: string;
|
||||
type: string;
|
||||
category: NearbyPOICategory;
|
||||
lat: number;
|
||||
lng: number;
|
||||
distance: number;
|
||||
address: string | null;
|
||||
}
|
||||
|
||||
interface NearbyPOIsResponse {
|
||||
pois: NearbyPOI[];
|
||||
center: { lat: number; lng: number };
|
||||
}
|
||||
|
||||
getNearbyPOIs(lat: number, lng: number, radius = 2000, limit = 30)
|
||||
→ Promise<NearbyPOIsResponse>
|
||||
```
|
||||
|
||||
#### AI Valuations & Advice
|
||||
|
||||
```ts
|
||||
type AiConfidence = 'low' | 'medium' | 'high';
|
||||
|
||||
interface ListingAiValuation {
|
||||
estimateVND: number;
|
||||
lowVND: number;
|
||||
highVND: number;
|
||||
confidence: AiConfidence;
|
||||
rationale: string;
|
||||
}
|
||||
|
||||
interface ListingAiAdviceBody {
|
||||
summary: string;
|
||||
pros: string[];
|
||||
cons: string[];
|
||||
suitableFor: string[];
|
||||
}
|
||||
|
||||
interface ListingAiAdvice {
|
||||
valuation: ListingAiValuation;
|
||||
advice: ListingAiAdviceBody;
|
||||
model: string;
|
||||
cacheHit: boolean;
|
||||
cacheUsage?: {
|
||||
input: number;
|
||||
cacheCreation: number;
|
||||
cacheRead: number;
|
||||
output: number;
|
||||
};
|
||||
}
|
||||
|
||||
getListingAiAdvice(listingId: string)
|
||||
→ Promise<ListingAiAdvice>
|
||||
|
||||
// Project AI advice (same advice block, no valuation)
|
||||
interface ProjectAiAdvice {
|
||||
advice: ListingAiAdviceBody;
|
||||
model: string;
|
||||
cacheHit: boolean;
|
||||
cacheUsage?: { /* cache tokens */ };
|
||||
}
|
||||
|
||||
getProjectAiAdvice(projectId: string)
|
||||
→ Promise<ProjectAiAdvice>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. React Query Hooks
|
||||
|
||||
**Location:** `apps/web/lib/hooks/use-analytics.ts`
|
||||
|
||||
### Query Keys Factory
|
||||
|
||||
```ts
|
||||
const analyticsKeys = {
|
||||
all: ['analytics'] as const,
|
||||
marketReport: (city: string, period: string) =>
|
||||
['analytics', 'market-report', city, period] as const,
|
||||
heatmap: (city: string, period: string) =>
|
||||
['analytics', 'heatmap', city, period] as const,
|
||||
districtStats: (city: string, period: string) =>
|
||||
['analytics', 'district-stats', city, period] as const,
|
||||
priceTrend: (district: string, city: string, propertyType: string, periods: string[]) =>
|
||||
['analytics', 'price-trend', district, city, propertyType, periods] as const,
|
||||
};
|
||||
```
|
||||
|
||||
### Hook Functions
|
||||
|
||||
```ts
|
||||
useMarketReport(city: string, period: string)
|
||||
→ UseQueryResult<MarketReportResponse>
|
||||
|
||||
useHeatmap(city: string, period: string)
|
||||
→ UseQueryResult<HeatmapResponse>
|
||||
|
||||
useDistrictStats(city: string, period: string)
|
||||
→ UseQueryResult<DistrictStatsResponse>
|
||||
|
||||
usePriceTrend(district: string, city: string, propertyType: string, periods: string[])
|
||||
→ UseQueryResult<PriceTrendResponse>
|
||||
// Note: enabled only when all params truthy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Chart Components (Recharts)
|
||||
|
||||
**Location:** `apps/web/components/charts/`
|
||||
|
||||
### Chart Dependencies
|
||||
- **recharts** v2.x — all charts import from 'recharts'
|
||||
- Uses HSL CSS variables for theme colors: `hsl(var(--primary))`, `hsl(var(--card))`, etc.
|
||||
|
||||
#### PriceTrendChart (`price-trend-chart.tsx`)
|
||||
- **Type:** Line chart (dual Y-axis)
|
||||
- **Props:**
|
||||
```ts
|
||||
interface PriceTrendChartProps {
|
||||
data: { period: string; 'Gia/m2': number; 'Tin đăng': number }[];
|
||||
height?: number; // default 350
|
||||
}
|
||||
```
|
||||
- **Series:**
|
||||
- Left Y-axis: `Gia/m2` (Price/m²) — solid line, green (primary)
|
||||
- Right Y-axis: `Tin đăng` (Listings) — dashed line, muted
|
||||
- **Features:** Grid, legend, tooltip with custom formatting
|
||||
- **Styling:** CartesianGrid stroke-muted, axis text fill-muted-foreground
|
||||
|
||||
#### DistrictBarChart (`district-bar-chart.tsx`)
|
||||
- **Type:** Bar chart
|
||||
- **Props:**
|
||||
```ts
|
||||
interface DistrictBarChartProps {
|
||||
data: { district: string; price?: number; 'Gia/m2'?: number; listings: number }[];
|
||||
height?: number; // default 300
|
||||
dataKey?: string; // default 'price'
|
||||
tooltipFormatter?: (value, name) => [string, string];
|
||||
}
|
||||
```
|
||||
- **Features:** X-axis rotated -30°, custom tooltip formatter, flexible data key
|
||||
- **Styling:** Bar radius [4, 4, 0, 0], fill primary
|
||||
|
||||
#### AgentPerformance (`agent-performance.tsx`)
|
||||
- **Type:** Mixed (Bar + Pie + Custom Funnel)
|
||||
- **Sections:**
|
||||
1. **KPI Cards** — 4 stat cards (deals, revenue, response time, conversion %)
|
||||
2. **Monthly Deals** — Dual-axis bar chart (deals + revenue)
|
||||
3. **Lead Conversion Funnel** — Horizontal bars + donut pie chart
|
||||
- **Mock Data:** 6-month deals/revenue, 5-stage funnel (contact → close)
|
||||
- **Colors:** Hardcoded palette: `['#94a3b8', '#60a5fa', '#a78bfa', '#fbbf24', '#34d399']`
|
||||
|
||||
---
|
||||
|
||||
## 6. Map Components (Mapbox)
|
||||
|
||||
**Location:** `apps/web/components/map/`
|
||||
|
||||
### Common Map Features
|
||||
- Token: `process.env.NEXT_PUBLIC_MAPBOX_TOKEN`
|
||||
- Style hook: `useMapboxStyle()` → applies theme-aware Mapbox styles
|
||||
- Attribution control included
|
||||
- NavigationControl (zoom + rotate) in top-right
|
||||
|
||||
#### DistrictHeatmap (`district-heatmap.tsx`)
|
||||
- **Purpose:** Display districts as color-coded circles on a map, sized by avg price
|
||||
- **Props:**
|
||||
```ts
|
||||
interface HeatmapPoint {
|
||||
district: string;
|
||||
avgPriceM2: number;
|
||||
totalListings: number;
|
||||
medianPrice: string;
|
||||
}
|
||||
|
||||
interface DistrictHeatmapProps {
|
||||
data: HeatmapPoint[];
|
||||
city: string;
|
||||
className?: string;
|
||||
onDistrictClick?: (district: string) => void;
|
||||
}
|
||||
```
|
||||
- **Features:**
|
||||
- **Markers:** Sized 36–64px, color gradient green (cheap) → red (expensive)
|
||||
- **Hover:** Scale 1 → 1.15, opacity 0.8 → 1
|
||||
- **Click:** Emits district name
|
||||
- **Popup:** Shows district name, price/m², listing count
|
||||
- **Legend:** Color bar (green–red spectrum)
|
||||
- **Presets:** Hard-coded district centroids for Ho Chi Minh, Ha Noi, Da Nang
|
||||
- **Fallback:** Unknown districts spread in ring around city center
|
||||
- **Theme:** Light-v11 (light mode), dark style (dark mode), better marker contrast
|
||||
|
||||
#### ListingMap (`listing-map.tsx`)
|
||||
- **Purpose:** Display individual listings as clickable price markers
|
||||
- **Props:**
|
||||
```ts
|
||||
interface ListingMapProps {
|
||||
listings: ListingDetail[];
|
||||
onMarkerClick?: (listing: ListingDetail) => void;
|
||||
selectedListingId?: string;
|
||||
className?: string;
|
||||
}
|
||||
```
|
||||
- **Features:**
|
||||
- **Markers:** Price bubbles, clickable
|
||||
- **Selected State:** Highlighted/scaled marker
|
||||
- **Popup:** Shows listing title, price, address, link to detail
|
||||
- **Fit Bounds:** Auto-zoom to all listings
|
||||
- **Fallback:** If no lat/lng, pseudo-random position near city center
|
||||
- **City Presets:** HCMC, Ha Noi, Da Nang, Nha Trang, Can Tho
|
||||
|
||||
#### LocationPicker (`location-picker.tsx`)
|
||||
- **Purpose:** Interactive map-based location selection
|
||||
- **Props:**
|
||||
```ts
|
||||
interface LocationPickerProps {
|
||||
lat?: number | null;
|
||||
lng?: number | null;
|
||||
onChange: (coords: { lat: number; lng: number }, resolved?: ResolvedAddress) => void;
|
||||
height?: string; // default '320px'
|
||||
className?: string;
|
||||
}
|
||||
|
||||
interface ResolvedAddress {
|
||||
address?: string;
|
||||
ward?: string;
|
||||
district?: string;
|
||||
city?: string;
|
||||
}
|
||||
```
|
||||
- **Features:**
|
||||
- **Map Click:** Drag or click to set coordinates
|
||||
- **Search Box:** Mapbox Places geocoder (Vietnam-scoped)
|
||||
- **Reverse Geocoding:** Resolves click/search to address components
|
||||
- **Marker:** Draggable, emits updated lat/lng
|
||||
- **Context Parsing:** Extracts ward, district, city from Mapbox feature context
|
||||
- **Default:** HCMC (10.7769, 106.7009)
|
||||
|
||||
---
|
||||
|
||||
## 7. Map Styling
|
||||
|
||||
**Location:** `apps/web/lib/mapbox-style.ts` (imported by map components)
|
||||
|
||||
- **Dark Style:** `MAPBOX_STYLE_DARK` — dark theme style URL
|
||||
- **Light Style:** `mapbox://styles/mapbox/light-v11` — light theme
|
||||
- **Hook:** `useMapboxStyle()` — returns theme-aware style URL
|
||||
- **CSS Overrides:** `globals.css` includes `.mapboxgl-*` selectors for button colors, popup styling
|
||||
|
||||
---
|
||||
|
||||
## 8. Key Patterns & Best Practices
|
||||
|
||||
### Design System Conventions
|
||||
1. **No prop spreading:** Props explicitly defined for clarity
|
||||
2. **Semantic HTML:** Tables use `<table>`, headers use `<th scope="col">`
|
||||
3. **Accessibility:** `aria-hidden` on decorative icons, proper heading hierarchy
|
||||
4. **Numeric alignment:** All numeric cells use `font-mono` + `tabular-nums` via `[data-numeric]` selector
|
||||
5. **Responsive:** Mobile-first, `md:` breakpoint for expanded views (search in header)
|
||||
|
||||
### Color & Theming
|
||||
1. **HSL-based tokens** with dark-first architecture
|
||||
2. **Signal colors** for market data: up (green), down (red), neutral (yellow)
|
||||
3. **Semantic naming:** `foreground-muted`, `background-elevated`, `signal-up`
|
||||
4. **Consistent shadows:** `elevation-1` (subtle), `elevation-2` (prominent)
|
||||
|
||||
### Data Display
|
||||
1. **Tables:** Client-side sort, sticky header, alternating row bg
|
||||
2. **Charts:** Recharts with HSL variables, custom formatters for localization
|
||||
3. **Maps:** Mapbox with fallback centroids, theme sync, clickable markers
|
||||
|
||||
---
|
||||
|
||||
## 9. Files to Integrate with Homepage Refactor
|
||||
|
||||
### Export Paths
|
||||
```ts
|
||||
// Design system
|
||||
import {
|
||||
StatCard,
|
||||
PriceDelta,
|
||||
MarketIndex,
|
||||
DataTable,
|
||||
CompactHeader,
|
||||
DashboardLayout,
|
||||
TickerStrip,
|
||||
} from '@/components/design-system';
|
||||
|
||||
// Analytics
|
||||
import { analyticsApi } from '@/lib/analytics-api';
|
||||
import {
|
||||
useMarketReport,
|
||||
useHeatmap,
|
||||
useDistrictStats,
|
||||
usePriceTrend,
|
||||
analyticsKeys,
|
||||
} from '@/lib/hooks/use-analytics';
|
||||
|
||||
// Charts
|
||||
import { PriceTrendChart } from '@/components/charts/price-trend-chart';
|
||||
import { DistrictBarChart } from '@/components/charts/district-bar-chart';
|
||||
import { AgentPerformance } from '@/components/charts/agent-performance';
|
||||
|
||||
// Maps
|
||||
import { DistrictHeatmap } from '@/components/charts/district-heatmap';
|
||||
import { ListingMap } from '@/components/map/listing-map';
|
||||
import { LocationPicker } from '@/components/map/location-picker';
|
||||
|
||||
// Theme tokens (CSS variables)
|
||||
// See apps/web/app/globals.css for full token reference
|
||||
```
|
||||
|
||||
### Design Token Reference
|
||||
- **Colors:** 30+ CSS variables (light + dark modes)
|
||||
- **Typography:** `font-sans` (Inter), `font-mono` (JetBrains Mono)
|
||||
- **Data Sizes:** `text-data-sm`, `text-data-md`, `text-data-lg`
|
||||
- **Spacing:** `h-row` (table), `h-ticker-bar` (ticker), `h-header-compact` (header)
|
||||
- **Shadows:** `elevation-1`, `elevation-2`
|
||||
- **Animations:** `animate-ticker`, `flash-up`, `flash-down`
|
||||
|
||||
---
|
||||
|
||||
## 10. Notes for Homepage Refactor
|
||||
|
||||
1. **Consistent spacing:** Use `gap-4`, `gap-6` classes; define custom `row` and `cell` spacings
|
||||
2. **Monospace numbers:** Always apply `[data-numeric]` or `font-mono` to numeric content for alignment
|
||||
3. **Signal colors:** Green (up), red (down), yellow (neutral) — use `signal-*` tokens
|
||||
4. **Sticky headers:** Use `sticky top-0 z-10` on table/list headers
|
||||
5. **Dark-first theme:** Light mode is override in `:root`; dark is in `.dark` selector
|
||||
6. **Mapbox token:** Required for heatmaps; graceful fallback shown if missing
|
||||
7. **Recharts styling:** Use `hsl(var(--primary))` pattern for dynamic theming
|
||||
8. **Responsive:** Mobile-first; use `md:`, `lg:` breakpoints
|
||||
9. **Query keys factory:** Use `analyticsKeys` for consistency in useQuery calls
|
||||
10. **No external design tokens file:** Tokens are in Tailwind config + globals.css CSS vars
|
||||
|
||||
241
docs/design-system/DESIGN_SYSTEM_QUICK_REFERENCE.md
Normal file
241
docs/design-system/DESIGN_SYSTEM_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Design System Quick Reference
|
||||
|
||||
## Component Imports
|
||||
|
||||
```typescript
|
||||
import {
|
||||
StatCard,
|
||||
PriceDelta,
|
||||
MarketIndex,
|
||||
DataTable,
|
||||
CompactHeader,
|
||||
DashboardLayout,
|
||||
TickerStrip,
|
||||
} from '@/components/design-system';
|
||||
```
|
||||
|
||||
## Quick Examples
|
||||
|
||||
### StatCard - KPI Display
|
||||
```tsx
|
||||
<StatCard
|
||||
label="Giá TB/m²"
|
||||
value="45.2"
|
||||
unit="tr/m²"
|
||||
delta={+2.5}
|
||||
sublabel="24h"
|
||||
icon={<TrendingUp />}
|
||||
/>
|
||||
```
|
||||
|
||||
### PriceDelta - Change Indicator
|
||||
```tsx
|
||||
<PriceDelta value={5.2} size="md" /> {/* +5.20% ↑ Green */}
|
||||
<PriceDelta value={-2.1} size="sm" /> {/* -2.10% ↓ Red */}
|
||||
<PriceDelta value={0} direction="neutral" /> {/* 0.00% - Yellow */}
|
||||
```
|
||||
|
||||
### MarketIndex - Hero Metric
|
||||
```tsx
|
||||
<MarketIndex
|
||||
name="GGX Market"
|
||||
value="1,240"
|
||||
changePercent={3.5}
|
||||
change={"+35"}
|
||||
window="24h"
|
||||
/>
|
||||
```
|
||||
|
||||
### DataTable - Sortable Data
|
||||
```tsx
|
||||
const columns: DataTableColumn<District>[] = [
|
||||
{
|
||||
id: 'name',
|
||||
header: 'District',
|
||||
cell: (row) => row.name,
|
||||
sortable: true,
|
||||
sortValue: (row) => row.name,
|
||||
},
|
||||
{
|
||||
id: 'price',
|
||||
header: 'Price/m²',
|
||||
cell: (row) => `${row.avgPrice} tr`,
|
||||
align: 'right',
|
||||
numeric: true,
|
||||
sortable: true,
|
||||
sortValue: (row) => row.avgPrice,
|
||||
},
|
||||
];
|
||||
|
||||
<DataTable columns={columns} data={districts} dense defaultSortId="price" />
|
||||
```
|
||||
|
||||
### TickerStrip - Scrolling Ticker
|
||||
```tsx
|
||||
<TickerStrip
|
||||
items={[
|
||||
{ id: 'q1', label: 'Quan 1', changePercent: 2.1 },
|
||||
{ id: 'q2', label: 'Quan 2', changePercent: -1.3 },
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
### DashboardLayout - Full Page Frame
|
||||
```tsx
|
||||
<DashboardLayout
|
||||
header={<CompactHeader breadcrumb="Market" />}
|
||||
sidebar={<Navigation />}
|
||||
ticker={<TickerStrip items={items} />}
|
||||
sidebarCollapsed={collapsed}
|
||||
>
|
||||
<div className="space-y-6">
|
||||
{/* Main content */}
|
||||
</div>
|
||||
</DashboardLayout>
|
||||
```
|
||||
|
||||
## Design Tokens
|
||||
|
||||
### Colors (CSS Variables)
|
||||
|
||||
**Light Mode** (`:root`)
|
||||
- `--foreground: 220 20% 12%` — Dark navy text
|
||||
- `--background: 0 0% 97%` — Off-white background
|
||||
- `--background-elevated: 0 0% 100%` — Pure white cards
|
||||
- `--primary: 142 72% 42%` — Green (up)
|
||||
- `--signal-down: 0 84% 55%` — Red (down)
|
||||
- `--signal-neutral: 45 93% 45%` — Yellow (neutral)
|
||||
|
||||
**Dark Mode** (`.dark`)
|
||||
- `--foreground: 210 20% 90%` — Off-white text
|
||||
- `--background: 220 20% 4%` — Very dark background
|
||||
- Same primary/signal colors (brightness-adjusted)
|
||||
|
||||
### Typography
|
||||
|
||||
```css
|
||||
/* Font families */
|
||||
font-sans /* Inter */
|
||||
font-mono /* JetBrains Mono (tabular-nums) */
|
||||
|
||||
/* Data-specific sizes */
|
||||
text-ticker /* 0.8125rem — ticker animation */
|
||||
text-data-sm /* 0.75rem — compact stats */
|
||||
text-data-md /* 0.875rem — default metric */
|
||||
text-data-lg /* 1.25rem — large KPI values */
|
||||
```
|
||||
|
||||
### Spacing
|
||||
|
||||
```css
|
||||
h-row /* 2.25rem (36px) — table row height */
|
||||
h-ticker-bar /* 2rem (32px) — ticker height */
|
||||
h-header-compact /* 3rem (48px) — dashboard header */
|
||||
```
|
||||
|
||||
### Utilities
|
||||
|
||||
```css
|
||||
[data-numeric] /* Applies font-variant-numeric: tabular-nums */
|
||||
elevation-1 /* Subtle shadow: 0 1px 2px rgba(0,0,0,0.3) */
|
||||
elevation-2 /* Prominent shadow: 0 4px 12px rgba(0,0,0,0.4) */
|
||||
```
|
||||
|
||||
## Analytics API
|
||||
|
||||
```typescript
|
||||
import { analyticsApi } from '@/lib/analytics-api';
|
||||
import {
|
||||
useMarketReport,
|
||||
useHeatmap,
|
||||
usePriceTrend,
|
||||
useDistrictStats,
|
||||
} from '@/lib/hooks/use-analytics';
|
||||
|
||||
// Raw API calls
|
||||
const report = await analyticsApi.getMarketReport('Ho Chi Minh', 'month');
|
||||
const heatmap = await analyticsApi.getHeatmap('Ho Chi Minh', 'month');
|
||||
|
||||
// React Query hooks
|
||||
const { data: districts } = useDistrictStats('Ho Chi Minh', 'month');
|
||||
const { data: trend } = usePriceTrend('Quan 1', 'Ho Chi Minh', 'apartment', ['month-1', 'month']);
|
||||
```
|
||||
|
||||
## Charts (Recharts)
|
||||
|
||||
```typescript
|
||||
import { PriceTrendChart } from '@/components/charts/price-trend-chart';
|
||||
import { DistrictBarChart } from '@/components/charts/district-bar-chart';
|
||||
import { AgentPerformance } from '@/components/charts/agent-performance';
|
||||
|
||||
// Line chart with dual Y-axis
|
||||
<PriceTrendChart
|
||||
data={[{ period: 'Jan', 'Gia/m2': 45, 'Tin đăng': 120 }]}
|
||||
height={350}
|
||||
/>
|
||||
|
||||
// Bar chart
|
||||
<DistrictBarChart
|
||||
data={[{ district: 'Q1', price: 45, listings: 50 }]}
|
||||
dataKey="price"
|
||||
/>
|
||||
|
||||
// Mixed dashboard (with mock data)
|
||||
<AgentPerformance />
|
||||
```
|
||||
|
||||
## Maps (Mapbox)
|
||||
|
||||
```typescript
|
||||
import { DistrictHeatmap } from '@/components/charts/district-heatmap';
|
||||
import { ListingMap } from '@/components/map/listing-map';
|
||||
import { LocationPicker } from '@/components/map/location-picker';
|
||||
|
||||
// Heatmap
|
||||
<DistrictHeatmap
|
||||
data={[
|
||||
{ district: 'Quan 1', avgPriceM2: 150000, totalListings: 25, medianPrice: '7 tỷ' },
|
||||
]}
|
||||
city="Ho Chi Minh"
|
||||
onDistrictClick={(name) => console.log(name)}
|
||||
/>
|
||||
|
||||
// Listing markers
|
||||
<ListingMap
|
||||
listings={listings}
|
||||
selectedListingId={selected?.id}
|
||||
onMarkerClick={(listing) => navigate(`/listing/${listing.id}`)}
|
||||
/>
|
||||
|
||||
// Interactive location picker
|
||||
<LocationPicker
|
||||
lat={currentLat}
|
||||
lng={currentLng}
|
||||
onChange={({ lat, lng }, resolved) => {
|
||||
// resolved.city, resolved.district, resolved.ward available
|
||||
setCoords({ lat, lng });
|
||||
}}
|
||||
height="400px"
|
||||
/>
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always use `[data-numeric]` or `font-mono` for numbers** — ensures proper alignment
|
||||
2. **Signal colors:** Green (up), Red (down), Yellow (neutral)
|
||||
3. **Spacing:** Use Tailwind gap classes; `gap-4` for cards, `gap-6` for sections
|
||||
4. **Sticky headers:** `sticky top-0 z-10` pattern
|
||||
5. **Responsive:** Mobile-first; `md:` for tablet breakpoints
|
||||
6. **Dark mode:** CSS variables handle both modes automatically
|
||||
7. **No hardcoded colors:** Use `hsl(var(--primary))` pattern for dynamic theming
|
||||
|
||||
## Environment Setup
|
||||
|
||||
```bash
|
||||
# Required for maps
|
||||
NEXT_PUBLIC_MAPBOX_TOKEN=your_token_here
|
||||
|
||||
# Optional
|
||||
NEXT_PUBLIC_ANALYTICS_ENDPOINT=...
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user