@schandlergarcia/sf-web-components 1.0.0 → 1.0.2

package/.a4drules/skills/command-center-builder/SKILL.md

@@ -0,0 +1,637 @@
+---
+name: command-center-builder
+description: >-
+  Strict rules for building command center pages, dashboards, components, and
+  layouts. Use when creating or editing dashboard pages, choosing components,
+  designing layouts, styling with dark mode, or working with charts, tables,
+  forms, filters, chat, or navigation in this project.
+---
+
+# Command Center Builder Rules
+
+These rules apply when building dashboards rendered by `CommandCenter.tsx`. For full component API details, read the **component-library** skill.
+
+## STOP — READ BEFORE WRITING ANY CODE
+
+**Every time you build a dashboard, you MUST follow these non-negotiable rules. Violations are the #1 cause of rejected dashboards.**
+
+1. **Actually write files to disk.** Use the file-writing tools to create `.jsx` files in `src/components/pages/` and update `CommandCenter.tsx` to import your dashboard. If you only describe what you would build without creating the files, the dashboard will not render. Verify the files exist after writing them.
+
+2. **Use ONLY library components** from `@/components/library` for all cards, charts, tables, lists, and feeds. The library has 30+ components — there is no reason to hand-roll HTML. See the component table below.
+
+3. **No navigation inside the dashboard.** No `<nav>`, no header bar, no tab bar acting as page-level navigation. The app shell handles navigation. Your dashboard starts with content.
+
+4. **Max 4 MetricCards per row.** Never 5. Split into two rows if needed.
+
+5. **All charts use `ChartCard` + `D3Chart` or `GeoMap`.** No Recharts, no Chart.js, no custom SVG, no canvas, no hand-drawn paths. The only charting tools allowed are `D3Chart` (with `D3ChartTemplates` or a custom `renderChart` function) and `GeoMap`.
+
+6. **Never `npm install` Salesforce packages.** The `@salesforce/*` packages are platform-provided via broken symlinks. They are stubbed in `src/stubs/` and aliased in `vite.config.ts`. Do not try to install them — they don't exist on npm. If you see a TypeScript error about `@salesforce/vite-plugin-webapp-experimental`, ignore it — the build still succeeds via `vite build` (the `tsc` error is in `vite.config.ts` which is handled separately by `tsconfig.node.json`).
+
+If your output violates any of these 6 rules, it will be rejected and you will need to redo the work.
+
+## CRITICAL: Use Library Components — Never Hand-Roll HTML Cards
+
+**This is the #1 mistake.** The component library (`@/components/library`) provides pre-built, themed, dark-mode-ready cards for every common dashboard need. You MUST use them instead of writing raw `<div>` cards with custom classes.
+
+### Before writing ANY card-like UI, check this table:
+
+| Need | MUST use | NEVER do |
+|------|----------|----------|
+| KPI / stat | `MetricCard` | `<div className="bg-white border ..."><h3>Total Spend</h3><span>$4,903</span></div>` |
+| List of items | `ListCard` | `<div className="bg-white ..."><div className="space-y-3">` with custom item rows |
+| Activity feed | `ActivityCard` or `FeedPanel` | `<div>` with hand-rolled interaction rows |
+| Data table | `TableCard` | `<table>` or custom grid of rows |
+| Stats panel | `WidgetCard` or `SectionCard` | `<div className="bg-white ... p-6">` with label/value pairs |
+| Custom interactive content (expand/collapse, inline details) | `WidgetCard` (sections accept arbitrary JSX) or `ListCard` (with `onItemClick` + `itemActions`) | Hand-rolled `<div>` card with custom expand/collapse logic |
+| Status items | `StatusCard` | `<div>` with custom status badges |
+| Text summary | `NarrativeSummary` / `SectionCard` | `<div>` with headings and paragraphs |
+| Alert / callout | `CalloutCard` | Custom banner div |
+
+**Every visible section of a dashboard should be a library component.** If you find yourself writing `<div className="bg-white border rounded-[10px] shadow-sm p-6">` with content inside, STOP — you are hand-rolling a card. Find the library component that fits.
+
+### Correct example:
+
+```jsx
+import { MetricCard, ListCard, ActivityCard, WidgetCard } from "@/components/library";
+
+// KPIs — use MetricCard
+<MetricCard title="Active Travelers" value={6} subtitle="Currently traveling" />
+
+// List — use ListCard with items array
+<ListCard title="Trip Activity" items={trips.map(t => ({
+  id: t.id, title: t.hotel, description: `${t.city} · ${t.dates}`,
+  status: t.status, avatar: t.travelerInitials
+}))} />
+
+// Activity feed — use ActivityCard
+<ActivityCard title="Eva — Recent Interactions" items={interactions.map(i => ({
+  id: i.id, title: i.traveler, description: i.query,
+  status: i.status, timestamp: i.time
+}))} />
+
+// Stats panel — use WidgetCard
+<WidgetCard title="Company Activity">
+  {/* structured content */}
+</WidgetCard>
+```
+
+### Wrong example (hand-rolled HTML):
+
+```jsx
+// ❌ NEVER DO THIS — this is a hand-rolled card
+<div className="bg-white border border-engine-border rounded-[10px] shadow-sm">
+  <div className="p-6 border-b border-engine-border">
+    <h2 className="text-lg font-semibold">Trip Activity</h2>
+  </div>
+  <div className="p-6 space-y-4">
+    {trips.map(trip => (
+      <div key={trip.id} className="flex gap-4 p-4 rounded-lg border ...">
+        ...
+      </div>
+    ))}
+  </div>
+</div>
+```
+
+## Images (MANDATORY)
+
+The only image allowed in dashboards is the **company logo**: `src/assets/images/engine_logo.png`. Import it as a module and use it where a logo is needed (nav header, branding, etc.).
+
+```jsx
+import engineLogo from "@/assets/images/engine_logo.png";
+
+<img src={engineLogo} alt="Engine" className="h-8 w-auto" />
+```
+
+- **Do not use external image URLs** (Unsplash, placeholder services, etc.) unless the user explicitly requests images.
+- **Do not use other asset images** (codey-*.png, etc.) unless the user asks for them.
+- **Preserve aspect ratio** — always use `w-auto` with a fixed height, or `h-auto` with a fixed width. Never set both `w-*` and `h-*` to fixed values on the logo or any image, as this distorts the aspect ratio.
+
+```jsx
+// ✅ Correct — aspect ratio preserved
+<img src={engineLogo} alt="Engine" className="h-8 w-auto" />
+<img src={engineLogo} alt="Engine" className="w-24 h-auto" />
+
+// ❌ Wrong — aspect ratio distorted
+<img src={engineLogo} alt="Engine" className="w-8 h-8" />
+<div className="w-8 h-8 bg-black rounded" />  // placeholder box instead of logo
+```
+
+## No Dashboard-Level Navigation (MANDATORY)
+
+Dashboard pages must NOT include their own `<nav>`, header bar, or top navigation of any kind. Navigation is handled by `appLayout.tsx`. The dashboard renders inside the app shell — adding a nav inside the dashboard creates a duplicate header, which is the most visually obvious mistake.
+
+- ❌ `<nav className="bg-white border-b ...">` inside a dashboard page
+- ❌ A header bar with logo + nav links + user avatar inside the dashboard
+- ❌ Tab bars that act as top-level navigation (Overview, Travelers, Spend, etc.)
+- ❌ `useState("overview")` / `useState("travelers")` to toggle between views — this IS tab navigation even without a `<nav>` element
+- ❌ `{activeView === "overview" && (...)}` / `{activeView === "travelers" && (...)}` — content-swapping IS multi-tab navigation
+- ✅ Dashboard starts directly with content (metrics, then primary content)
+- ✅ If you need sub-sections, use the library `Tabs` component **inside a card** — not as a full-width page-level switcher
+- ✅ Build a single-page dashboard — all content visible by scrolling. Do NOT split into multiple tab "pages" that swap content.
+
+**Self-check:** If your dashboard has `useState` for an "active tab" or "active view" that conditionally renders different page sections, you are building multi-tab navigation. Delete it and put all content on one scrollable page.
+
+**Self-check:** If your dashboard JSX starts with `<nav>`, a sticky tab bar, or a `<div>` that spans the full width with nav links, you are violating this rule. Delete it.
+
+### Why no multi-tab dashboards?
+
+Splitting a dashboard into 5 tab "pages" (Overview, Travelers, Spend, Policy, Eva) means each tab is a separate mini-app. This violates the single-page dashboard pattern. Instead, put **all sections on one scrollable page** using the vertical page structure (metrics → primary content → secondary content). If content is too long, prioritize the most important sections and use cards with `maxBodyHeight` to constrain tall sections.
+
+## Where Dashboards Live & How to Wire Them
+
+- Dashboard page files: `src/components/pages/` (e.g. `HelloWorld.jsx`, `FleetDashboard.jsx`)
+- File format: `.jsx` (not `.tsx`) — matches the vendored library convention.
+- `CommandCenter.tsx` wraps with `heroui-scope` + `AppThemeProvider` + `DataModeProvider` + `Toast.Provider`. **Never recreate these providers in dashboard pages.**
+
+### Wiring a new dashboard (REQUIRED STEPS)
+
+You must do ALL of these or the dashboard will not render correctly:
+
+**Step 1:** Create the dashboard file in `src/components/pages/`:
+```jsx
+// src/components/pages/MyDashboard.jsx
+import React from "react";
+import { MetricCard, ListCard, ChartCard, D3Chart } from "@/components/library";
+
+export default function MyDashboard() {
+  return (
+    <div className="space-y-6 p-6">
+      {/* dashboard content using library components */}
+    </div>
+  );
+}
+```
+
+**Step 2:** Update `CommandCenter.tsx` to import and render it:
+```tsx
+// src/components/pages/CommandCenter.tsx
+import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
+import DataModeProvider from "@/components/library/data/DataModeProvider";
+import { Toast } from "@heroui/react";
+import MyDashboard from "./MyDashboard";  // ← change this import
+
+export default function CommandCenter() {
+  return (
+    <div className="heroui-scope">
+      <AppThemeProvider initialMode="light">
+        <DataModeProvider initialMode="sample">
+          <MyDashboard />                   {/* ← change this */}
+          <Toast.Provider placement="bottom end" />
+        </DataModeProvider>
+      </AppThemeProvider>
+    </div>
+  );
+}
+```
+
+**Step 3:** Update `src/routes.tsx` to make the dashboard the home page. Replace the Search page index route with the Home/CommandCenter route:
+```tsx
+// src/routes.tsx — change the index route
+{
+  index: true,
+  element: <SuspenseWrap><Home /></SuspenseWrap>,
+  handle: { showInNavigation: true, label: 'Dashboard' }
+},
+{
+  path: "search",
+  element: <SuspenseWrap><Search /></SuspenseWrap>,
+  handle: { showInNavigation: true, label: 'Search' }
+},
+```
+
+The `Home` page renders `CommandCenter`, which renders your dashboard. The Search page moves to `/search`.
+
+**Verify:** After writing all files, confirm:
+1. Your dashboard `.jsx` file exists in `src/components/pages/`
+2. `CommandCenter.tsx` imports your dashboard (not `BlankDashboard`)
+3. `src/routes.tsx` has `Home` as the index route and `Search` at `/search`
+
+## Page Structure
+
+Every page follows this vertical order — never rearrange:
+1. Context (NarrativeSummary or heading) — optional
+2. KPI metrics (MetricsStrip or MetricCard grid) — required for dashboards
+3. Primary content (tables, charts, status)
+4. Secondary content (lists, logs, supporting data) — optional
+5. Actions — optional
+
+Wrap all page content in `<div className="space-y-6">`. Do NOT use `mb-6` between sections — the wrapper handles spacing.
+
+## Layout Grids
+
+Only these grid patterns — do not invent new ones:
+
+- **4 metrics (MAXIMUM per row — never 5 or more):** `grid grid-cols-2 gap-3 lg:grid-cols-4`
+- **3 metrics:** `grid grid-cols-1 gap-3 sm:grid-cols-3`
+- **Wide/narrow split:** `grid grid-cols-1 items-start gap-4 lg:grid-cols-3` with `lg:col-span-2` on the wide side
+- **3-col balanced:** `grid grid-cols-1 items-start gap-4 lg:grid-cols-3`
+- **Equal two-col:** `grid grid-cols-1 items-start gap-4 lg:grid-cols-2`
+- **Full-width:** `<div className="w-full">` — charts with 24+ data points
+
+`gap-4` for content grids, `gap-3` for metric rows. Start `grid-cols-1` (or `grid-cols-2` for metrics) for mobile. Only `sm:` and `lg:` breakpoints unless justified.
+
+**Max 4 KPIs per row — NEVER 5 or more.** If you have 5+ metrics, split into two rows (e.g. 4 + 1, or 3 + 2). Always `items-start` on grids pairing different-height cards. Use `maxBodyHeight={px}` for long card bodies. Actions go in card `actions` slot. Place `FilterBar` near the data it controls.
+
+## Layout Differentiation
+
+Every dashboard needs a unique layout structure and at least one domain-specific "signature element" that couldn't exist in another dashboard. Vary section ordering, grid proportions, density, and visual rhythm.
+
+## Map Layout
+
+GeoMap should be placed in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`), not full-width hero. Full-width maps dominate the page and waste space.
+
+**Pattern: Map + sidebar at matched height**
+
+```jsx
+<div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+  <div className="lg:col-span-2 relative overflow-hidden rounded-xl h-[300px]">
+    <GeoMap
+      markers={locations}
+      arcs={arcs}
+      overlays={overlays}
+      initialBounds={{ sw: [-130, 24], ne: [-65, 50], padding: 30 }}
+      theme="dark"
+      width={960}
+      height={480}
+      zoomable
+      className="h-full w-full"
+    />
+  </div>
+  {/* Sidebar card — use maxBodyHeight to match map height */}
+  {/* Map h-[300px] ≈ ListCard maxBodyHeight={236} + ~64px header */}
+  <ListCard title="Activity" items={items} maxBodyHeight={236} showStatus />
+</div>
+```
+
+Key rules:
+- **Do NOT wrap GeoMap in ChartCard** — GeoMap has its own background/borders
+- **Match heights** — set map `h-[Xpx]` and sidebar `maxBodyHeight` so they align. Account for ~64px card header padding.
+- **Use `initialBounds`** to auto-zoom to the region with data: `{ sw: [lonMin, latMin], ne: [lonMax, latMax], padding: 30 }`
+- **Always pass `arcs`** for flight routes and `overlays` for disruption zones — not just markers
+- **Use ListCard** (not ActivityCard) for the sidebar — ListCard supports `maxBodyHeight` for scroll, ActivityCard does not
+- Keep map height at 280–320px — not 400+
+
+## Component Selection
+
+| Need | Component |
+|------|-----------|
+| Single KPI | `MetricCard` |
+| Row of 2–4 KPIs | `MetricsStrip` (schema) / `MetricCard` grid |
+| Tabular data | `TableCard` |
+| Time series / distribution | `ChartCard` + `D3Chart` |
+| Geographic / flight map | `GeoMap` |
+| System health | `StatusCard` |
+| Feed / item list | `ListCard` |
+| Scrollable side panel | `FeedPanel` |
+| Activity feed | `ActivityCard` |
+| User avatar | `Avatar` |
+| Text summary | `NarrativeSummary` (schema) / `SectionCard` |
+| Actions | `ActionList` (schema) / `UIButton` group |
+| Alert / callout | `CalloutCard` |
+| Multi-section panel | `WidgetCard` |
+
+## Component Data Contract
+
+Common card props: `title`, `subtitle`, `actions`, `loading`, `error`, `emptyMessage`, `...cardProps`.
+
+Item shape (StatusCard, ListCard, ItemList): `{ id?, title, description?, status?, timestamp?, value?, unit?, avatar? }`. `title` is primary; `name` is alias.
+
+Never use hardcoded `indigo-*` — use `brand-*` classes.
+
+## Metric Formatting
+
+Use `fmtK()` helper — never manually append K/M/B:
+
+```js
+function fmtK(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return n.toLocaleString();
+}
+```
+
+## Brand & Accent Colors
+
+Defined in `global.css` (`--color-brand-*` and `--color-engine-*`), available as Tailwind classes.
+
+- `engine-*` for the Engine brand: `engine-teal`, `engine-coral`, `engine-orange`, `engine-savings`, `engine-text`, `engine-muted`, `engine-label`, `engine-border`, `engine-bg`
+- `brand-*` for the legacy command center palette (indigo-based)
+- Tailwind built-in colors for status (green/amber/red). Never use brand for status.
+
+## Semantic Colors
+
+- `"default"` — neutral | `"primary"` — brand | `"success"` — healthy | `"warning"` — attention | `"danger"` — critical
+
+`changeType` reflects good/bad, not direction. Revenue down = `"negative"`. Incidents down = `"positive"`.
+
+## Status Values
+
+Canonical: `"operational"`, `"degraded"`, `"outage"`, `"maintenance"`. Always show color + text label.
+
+## Dark Mode (MANDATORY)
+
+Every visible element needs both light and dark styles. Library components handle this automatically — which is another reason to use them.
+
+For any custom markup you do write:
+
+| Role | Light | Dark |
+|------|-------|------|
+| Background | `bg-white` | `dark:bg-slate-900` |
+| Surface | `bg-slate-50` | `dark:bg-slate-950/30` |
+| Border | `border-slate-200` | `dark:border-slate-800` |
+| Text primary | `text-slate-900` | `dark:text-slate-50` |
+| Text secondary | `text-slate-600` | `dark:text-slate-300` |
+| Text muted | `text-slate-500` | `dark:text-slate-400` |
+| Brand tint | `brand-50` | `brand-950` |
+
+**Never use `text-black` or `text-white`.** Use the slate scale. Never use `bg-black` for surfaces — use `bg-slate-900` / `dark:bg-slate-950`.
+
+## Icons (Command Center)
+
+**Heroicons 2** (`@heroicons/react`) exclusively inside command center pages. No Lucide, no Font Awesome, no inline SVGs.
+
+- `24/outline` — default | `24/solid` — status/active | `20/solid` — chips/badges
+- Sizes: `h-4 w-4` compact, `h-5 w-5` default, `h-6 w-6` emphasis, `h-8 w-8` hero only
+- Always set a color class. Pass rendered elements: `icon={<UsersIcon className="h-5 w-5 text-brand-500" />}`
+- ❌ Never use inline `<svg>` when a Heroicon exists for the same purpose
+- ❌ Never guess icon names — Heroicons uses specific names that don't always match what you'd expect. Common mistakes: `PlaneIcon` (doesn't exist → use `PaperAirplaneIcon`), `FlightIcon` (doesn't exist → use `PaperAirplaneIcon`), `HotelIcon` (doesn't exist → use `BuildingOfficeIcon`), `MoneyIcon` (doesn't exist → use `BanknotesIcon`), `AlertIcon` (doesn't exist → use `ExclamationTriangleIcon`), `PersonIcon` (doesn't exist → use `UserIcon`)
+
+## Fonts
+
+Fonts are set in `global.css` via `@theme` block (`--font-sans`, `--font-mono`). No `next/font` in this project (that's the starter). No Google Fonts `<link>` tags.
+
+## Filtering & Data Utilities
+
+Three layers: `filterUtils.js` (pure) → `usePageFilters` hook (state) → `FilterBar` + components (UI).
+
+- Pass `sortedData` (not `filteredData`) to components
+- Disable `TableCard.searchable` when `FilterBar` provides search
+- Declare filter definitions outside component body (or memoize)
+
+## Data Mode (Sample vs Live)
+
+`useDataMode()` returns `{ mode, isSample, isLive, toggle, setMode }`. `useDataSource({ sample, live })` picks based on mode.
+
+- Every page works in both modes. Default to `"sample"`.
+- Same layout for both modes — only data changes.
+- Sample data: 10–50 items, realistic, deterministic (no `Math.random()`).
+- Define sample data as constants outside the component body.
+
+```jsx
+// ✅ Correct: data defined outside, selected by mode
+const SAMPLE_TRIPS = [ ... ];
+
+export default function Dashboard() {
+  const trips = useDataSource({ sample: SAMPLE_TRIPS, live: liveTrips });
+  ...
+}
+
+// ❌ Wrong: hardcoded data inside the component with no mode switching
+export default function Dashboard() {
+  const trips = [ ... ]; // no useDataSource, no mode awareness
+}
+```
+
+## Forms & Record Modals
+
+Schema-driven: `sections[] → fields[]`. Use `FormModal` (modal) or `FormRenderer` (inline). `useFormState` for state.
+
+Define schemas outside component body. Always `required: true` on mandatory fields. Submissions enforce 4s minimum spinner.
+
+## AI Chat & Agent
+
+Use `ChatBar` (command palette, ⌘K) for dashboards. `ChatPanel` for full-page chat.
+
+- Always provide 3–5 `suggestions` for starter prompts
+- Return `components` for structured data — never markdown tables in text
+- Always set height on `ChatPanel`
+- Extract `onSend` handlers to module scope when shared
+
+## Tables
+
+`searchable` when 10+ rows (unless `FilterBar` handles search). `sortable` on comparable columns. `paginated` when 10+ rows. Use built-in column `type` before custom `render`.
+
+## Charts & Visualizations (MANDATORY)
+
+**All charts, graphs, maps, and visualizations MUST use library components.** Never use Recharts, Chart.js, Nivo, or any third-party charting library. Never hand-roll SVG, canvas, or custom chart markup. The ONLY charting tools allowed are `D3Chart` (via `D3ChartTemplates` or a custom `renderChart` function) and `GeoMap`.
+
+| Visualization | MUST use | NEVER do |
+|--------------|----------|----------|
+| Line chart | `ChartCard` + `D3Chart` with `D3ChartTemplates.lineChart` | Custom `<svg>` with hand-drawn paths/circles |
+| Grouped bar chart | `ChartCard` + `D3Chart` with `D3ChartTemplates.groupedBarChart` | Custom `<svg>` bar elements |
+| Map / geographic | `GeoMap` | Custom SVG map or embedded iframe |
+| Custom visualization | `ChartCard` + `D3Chart` with a custom `renderChart` function | Inline SVG/canvas |
+
+### D3Chart API (CRITICAL — read carefully)
+
+`D3Chart` does NOT use a `template` prop. It uses a `renderChart` callback function:
+
+```jsx
+<D3Chart
+  data={array}                              // data array
+  renderChart={D3ChartTemplates.lineChart}  // function reference, NOT a string
+  responsive={true}                         // enables ResizeObserver
+  height={280}                              // height in px
+/>
+```
+
+### ChartCard + D3Chart usage
+
+`ChartCard` takes a `chart` prop (a React element). Pass the `D3Chart` as the `chart` value:
+
+```jsx
+import { ChartCard, D3Chart, D3ChartTemplates } from "@/components/library";
+
+// ✅ Line chart — data must have { x, y } shape (numeric x)
+const spendData = [
+  { x: 1, y: 2400 }, { x: 2, y: 3100 }, { x: 3, y: 2800 }, ...
+];
+<ChartCard
+  title="30-Day Spend"
+  subtitle="Engine savings"
+  chart={
+    <D3Chart
+      data={spendData}
+      renderChart={D3ChartTemplates.lineChart}
+      options={{ stroke: "#5BC8C8", xKey: "x", yKey: "y" }}
+      responsive
+      height={280}
+    />
+  }
+/>
+
+// ✅ Grouped bar chart — data must have { x, group1, group2 } shape
+const monthlyData = [
+  { x: "Jan", Hotels: 12000, Flights: 8000 },
+  { x: "Feb", Hotels: 14000, Flights: 9000 }, ...
+];
+<ChartCard
+  title="Monthly Spend"
+  chart={
+    <D3Chart
+      data={monthlyData}
+      renderChart={D3ChartTemplates.groupedBarChart}
+      options={{ xKey: "x", groups: ["Hotels", "Flights"], colors: ["#5BC8C8", "#6366F1"] }}
+      responsive
+      height={280}
+    />
+  }
+/>
+
+// ✅ Custom renderChart function (for donut, horizontal bar, etc.)
+function renderDonut(svgEl, data, dims, opts) {
+  // Use d3 to draw into svgEl
+  const d3svg = d3.select(svgEl);
+  d3svg.selectAll("*").remove();
+  // ... d3 drawing code
+}
+<ChartCard title="By Department" chart={<D3Chart data={deptData} renderChart={renderDonut} responsive height={280} />} />
+```
+
+### Available D3ChartTemplates
+
+- `D3ChartTemplates.lineChart` — options: `{ xKey, yKey, stroke, strokeWidth, margin, showAxes, showGrid }`
+- `D3ChartTemplates.groupedBarChart` — options: `{ xKey, groups, colors, barRadius, margin, yFormat, showGrid }`
+
+**There is NO `D3ChartTemplates.LINE`, `.BAR`, `.DONUT`, `.AREA`.** Only `lineChart` and `groupedBarChart`. For donut/pie/horizontal bar, write a custom `renderChart` function using d3.
+
+### GeoMap API
+
+```jsx
+import { GeoMap } from "@/components/library";
+
+// markers: array of { id, lon, lat, active?, label? }
+const markers = [
+  { id: "sf", lon: -122.4, lat: 37.8, active: true, label: "San Francisco" },
+  { id: "nyc", lon: -74.0, lat: 40.7, active: true, label: "New York" },
+];
+
+<ChartCard title="Active Locations" chart={
+  <GeoMap
+    markers={markers}
+    theme="dark"
+    height={400}
+    width={800}
+    zoomable
+  />
+} />
+```
+
+GeoMap props: `width`, `height`, `projection` (`"naturalEarth"` | `"mercator"` | `"equirectangular"`), `theme` (`"dark"` | `"light"`), `markers`, `arcs`, `overlays`, `zoomable`, `minZoom`, `maxZoom`, `onMarkerClick`.
+
+### Common mistakes
+
+```jsx
+// ❌ WRONG — third-party chart libraries are forbidden
+import { BarChart, Bar } from "recharts";
+<BarChart data={data}><Bar dataKey="count" /></BarChart>
+
+// ❌ WRONG — template prop doesn't exist
+<D3Chart template={D3ChartTemplates.LINE} data={data} />
+
+// ❌ WRONG — passing as children instead of chart prop
+<ChartCard title="Spend"><D3Chart ... /></ChartCard>
+
+// ❌ WRONG — non-numeric x values with lineChart (use groupedBarChart for categorical x)
+<D3Chart data={[{x: "Jan", y: 100}]} renderChart={D3ChartTemplates.lineChart} />
+
+// ✅ CORRECT
+<ChartCard title="Spend" chart={<D3Chart data={data} renderChart={D3ChartTemplates.lineChart} responsive height={280} />} />
+```
+
+## Portals
+
+Any `position: fixed` component **must** use `createPortal(... , document.body)`.
+
+## Loading / Error / Empty States
+
+Every data component handles loading. Error messages are human-readable. Empty states explain what would appear.
+
+## Pre-Completion Checklist
+
+Before finishing a dashboard page, verify ALL of these:
+
+- [ ] **Every card/panel is a library component** (MetricCard, ListCard, ActivityCard, WidgetCard, TableCard, etc.) — no hand-rolled `<div className="bg-white border ...">` cards
+- [ ] **Every chart/visualization is a library component** (ChartCard + D3Chart, GeoMap) — no hand-rolled SVG/canvas
+- [ ] **No `<nav>`, header bar, or sticky tab bar** — navigation is handled by appLayout.tsx
+- [ ] **Single scrollable page** — no multi-tab layout that swaps content
+- [ ] **Max 4 KPIs per row** — if 5+, split across rows
+- [ ] **Charts render** — using `renderChart` callback (not `template` prop), data format matches (numeric x for lineChart)
+- [ ] **`<div className="space-y-6">` wraps all content** — no `mb-*` for section spacing
+- [ ] **Dark mode works** — every custom element has `dark:` variants; no `text-black`, `text-white`, or `bg-black`
+- [ ] **No inline `style={{}}` or `<style>` tags** — use Tailwind classes or CSS in global.css
+- [ ] **No inline `<svg>`** — use Heroicons from `@heroicons/react`
+- [ ] **`position: fixed` uses `createPortal`** — FABs, modals, toasts
+- [ ] **Data uses `useDataSource`** — sample data defined outside the component
+- [ ] **Only uses company logo** (`@/assets/images/engine_logo.png`) — no external URLs, no placeholder boxes
+- [ ] **Images preserve aspect ratio** — one dimension auto, never both fixed
+- [ ] **Imports only from `@/components/library`** — no shadcn, no Lucide, no `cn()`
+- [ ] **Grid patterns match the approved list** — no custom grid layouts
+
+## Post-Completion Verification (REQUIRED — MUST RUN BEFORE REPORTING DONE)
+
+After building the dashboard, you MUST run the validator and fix ALL errors before reporting the dashboard as complete:
+
+```bash
+# Run from the web app directory
+npm run validate:dashboard
+```
+
+**Do NOT run `npm run build` or `tsc`.** The TypeScript build has known issues with platform-only Salesforce packages that are not relevant to dashboard development. Only run the validator.
+
+The validator (`scripts/validate-dashboard.sh`) automatically checks for:
+- Hand-rolled HTML cards, tables, and SVGs (must use library components)
+- Forbidden colors (`text-black`, `text-white`, `bg-black`)
+- Inline `style={{}}` and `<style>` tags
+- Missing `useDataSource` for sample/live mode
+- Grid layouts with 5+ columns
+- `position: fixed` without `createPortal`
+- shadcn/Lucide imports in command center code
+- Missing `space-y-6` wrappers
+- `.tsx` files where `.jsx` is required
+- Dashboard navigation (`<nav>` elements)
+
+**If the validator reports errors, you MUST fix them ALL — zero errors required.** Do not report the dashboard as complete with any errors. Do not dismiss errors as "acceptable", "justified", or "expected". Every error has a fix — usually by switching to the correct library component. The validator exits with code 1 on errors — treat this like a failing test.
+
+**Common validator errors and their fixes:**
+- **Hand-rolled card** → Wrap content in `WidgetCard`, `ListCard`, `BaseCard`, or another library card component. `WidgetCard` with a single section can wrap any arbitrary JSX content.
+- **Forbidden colors** (`text-white`, `bg-black`) → Use slate scale (`text-slate-50`, `bg-slate-900`)
+- **shadcn/Lucide imports** → Replace with library components and Heroicons
+
+**Do not skip or ignore the validator.** Do not run `npm run build` or `tsc` — only run `npm run validate:dashboard`.
+
+## Anti-Patterns (never do these)
+
+- Hand-rolling HTML cards instead of using library components (MetricCard, ListCard, etc.)
+- Using Recharts, Chart.js, Nivo, or any chart library other than D3Chart/GeoMap
+- Hand-rolling SVG/canvas charts instead of using ChartCard + D3Chart or GeoMap
+- Adding a `<nav>`, header bar, sticky tab bar, or top navigation inside a dashboard page
+- Multi-tab layouts that swap content (Overview/Travelers/Spend/etc tabs) — build one scrollable page
+- More than 4 KPIs in a single row (max is `lg:grid-cols-4`)
+- Using `template` prop on D3Chart (doesn't exist) — use `renderChart={D3ChartTemplates.lineChart}`
+- Passing D3Chart as children to ChartCard — use `chart={<D3Chart ... />}` prop
+- CSS Modules, styled-components, or inline `style={{}}` for layout
+- `<style>` tags with keyframes or custom CSS inside components
+- Inline `<svg>` elements when a Heroicon exists
+- Importing shadcn components (`src/components/ui/`) into command center pages — `Button`, `Card`, `Input`, `Select`, `Alert`, `Skeleton`, `Label`, `Spinner`, etc. are ALL forbidden. Use the library equivalents from `@/components/library` (`UIButton`, `BaseCard`/`WidgetCard`, `UIInput`, `Select`, `Alert`, `Skeleton`, etc.)
+- Importing Lucide icons (`lucide-react`) into command center pages — use Heroicons (`@heroicons/react`) instead
+- Using `cn()` helper in command center pages (that's shadcn's utility — use Tailwind classes directly)
+- `useEffect` for data in schema components
+- `bg-indigo-*` or raw colors for brand — use `brand-*` or `engine-*`
+- Recreating providers (`AppThemeProvider`, `DataModeProvider`) in dashboard pages — `CommandCenter.tsx` already provides them
+- Tables without search on 10+ rows, charts without tooltips, empty states without messages
+- Hard-coded pixel widths or skipping dark mode
+- `text-black`, `text-white`, `bg-black` — use slate scale
+- `lg:grid-cols-6` for metrics (max 4), manually appending K/M/B
+- `mb-6` between sections instead of `space-y-6` wrapper
+- Same layout across dashboards, no signature element
+- `ChatPanel` in dashboard grid — use `ChatBar`
+- `position: fixed` without `createPortal`
+- `Math.random()` in sample data, different layouts based on data mode
+- Re-declaring filter/form definitions inside component render
+- Dismissing validator errors as "acceptable" or "justified" instead of fixing them — every error has a library component fix
+- Hardcoded data without `useDataSource` for sample/live mode switching
+- External image URLs (Unsplash, placeholders) unless user explicitly requests them
+- Placeholder boxes (`<div className="w-8 h-8 bg-black rounded" />`) instead of the actual logo
+- Fixed width AND height on images — always let one dimension be `auto` to preserve aspect ratio