goodgo-platform/docs/design-system/DESIGN_SYSTEM_QUICK_REFERENCE.md

# 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=...
```