@schandlergarcia/sf-web-components 1.9.50 → 1.9.52

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

@@ -1,46 +1,652 @@
 ---
 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.
+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.
 
-## Documentation Structure
+## STOP — READ BEFORE WRITING ANY CODE
 
-This skill is split into focused sub-files for the command center build workflow:
+**Every time you build a dashboard, you MUST follow these non-negotiable rules. Violations are the #1 cause of rejected dashboards.**
 
-| File | What's Inside | When to Use |
-|------|---------------|-------------|
-| **[getting-started.md](./getting-started.md)** | STOP section, CRITICAL rules, Image requirements, Navigation rules | Read FIRST before building any dashboard |
-| **[page-layout.md](./page-layout.md)** | Where dashboards live, How to wire them, Page structure, Layout grids, Map layouts | Creating new dashboard pages or designing layouts |
-| **[components-styling.md](./components-styling.md)** | Component selection, Data contracts, Metric formatting, Brand/accent colors, Semantic colors, Status values, Dark mode, Icons, Fonts, Filtering utilities | Choosing components, styling, theming, formatting data |
-| **[data-forms-ai.md](./data-forms-ai.md)** | Data mode (sample vs live), Forms & record modals, AI chat & agent, Tables | Working with data sources, forms, AI features |
-| **[charts-visualization.md](./charts-visualization.md)** | Charts & visualizations (MANDATORY rules), Portals, Loading/error/empty states | Building charts, visualizations, data viz |
-| **[completion-checklist.md](./completion-checklist.md)** | Pre-completion checklist, Post-completion verification (REQUIRED), Anti-patterns | Before reporting done — validation steps |
+Before writing any code, read `.a4drules/features/pre-code-checklist.md` and verify all requirements. The most common mistakes are:
+- Creating `.jsx` instead of `.tsx` files
+- Creating files in `src/components/pages/` instead of `src/pages/`
+- Using forbidden colors (`text-white`, `bg-black`)
+- Hand-rolling HTML cards instead of using library components
 
-## Quick Start Workflow
+1. **Actually write files to disk.** Use the file-writing tools to create `.tsx` files (NOT `.jsx`) in `src/pages/` (NOT `src/components/pages/`) and update `CommandCenter.tsx` to import your dashboard. This is a TypeScript project - all React components MUST use `.tsx` extension. If you only describe what you would build without creating the files, the dashboard will not render. Verify the files exist after writing them.
 
-1. **Starting a new dashboard?** → Read [getting-started.md](./getting-started.md) COMPLETELY FIRST
-2. **Creating the page file?** → Check [page-layout.md](./page-layout.md) for wiring and structure
-3. **Adding components?** → Use [components-styling.md](./components-styling.md) + **component-library** skill
-4. **Building charts?** → Follow [charts-visualization.md](./charts-visualization.md) MANDATORY rules
-5. **Before reporting done?** → Run [completion-checklist.md](./completion-checklist.md) verification
+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.
 
-## Critical Rules Summary
+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.
 
-- **ALWAYS read [getting-started.md](./getting-started.md) FIRST** — contains blocking requirements
-- **Never hand-roll HTML cards** — use library components only
-- **Dark mode is MANDATORY** — all color choices must support it
-- **Images are MANDATORY** — every dashboard needs relevant visuals
-- **Charts have strict rules** — D3Chart only, specific templates required
-- **No dashboard-level navigation** — dashboards are nav targets, not nav containers
-- **Validation is REQUIRED** — run post-completion checklist before reporting done
+4. **Max 4 MetricCards per row.** Never 5. Split into two rows if needed.
 
-## Where to Find Component Details
+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`.
 
-This skill covers **when** and **how** to use components in command centers. For **exact props and data shapes**, see:
+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`).
 
-- **component-library** skill → Complete API reference with all prop names and types
-- **when-to-use.md** in component-library → Decision matrix for choosing components
+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/pages/` (e.g. `EngineDashboard.tsx`, `FleetDashboard.tsx`) — **NOT** `src/components/pages/`
+- File format: `.tsx` (MUST be TypeScript) — this is a TypeScript project, all React components use `.tsx`, NEVER `.jsx`.
+- `CommandCenter.tsx` wraps with `AppThemeProvider` + `DataModeProvider` + `Toaster`. **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/pages/` (NOT `src/components/pages/`):
+```tsx
+// src/pages/MyDashboard.tsx (NOTE: .tsx NOT .jsx, in src/pages/ NOT src/components/pages/)
+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/workspace/CommandCenter.tsx
+import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
+import DataModeProvider from "@/components/library/data/DataModeProvider";
+import { Toaster } from "sonner";
+import MyDashboard from "../../pages/MyDashboard";  // ← change this import
+
+export default function CommandCenter() {
+  return (
+    <AppThemeProvider initialMode="light">
+      <DataModeProvider initialMode="sample">
+        <MyDashboard />                   {/* ← change this */}
+        <Toaster position="bottom-right" />
+      </DataModeProvider>
+    </AppThemeProvider>
+  );
+}
+```
+
+**Step 2.5:** Update `Home.tsx` to render `CommandCenter`:
+```tsx
+// src/pages/Home.tsx
+import CommandCenter from "@/components/workspace/CommandCenter";
+
+export default function HomePage() {
+  return <CommandCenter />;
+}
+```
+
+**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 `.tsx` file exists in `src/pages/`
+2. `CommandCenter.tsx` (in `src/components/workspace/`) imports your dashboard (not `BlankDashboard`)
+3. `Home.tsx` (in `src/pages/`) imports and renders `CommandCenter` (not search interface)
+4. `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
+- `.jsx` files where `.tsx` is required (this is a TypeScript project)
+- 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