@schandlergarcia/sf-web-components 1.9.50 → 1.9.54

package/.a4drules/features/command-center-dashboard-rule.md

@@ -1,21 +1,27 @@
 ---
 paths:
-  - "**/components/pages/*.jsx"
-  - "**/components/pages/*.tsx"
-  - "**/components/pages/CommandCenter.tsx"
+  - "**/pages/*.jsx"
+  - "**/pages/*.tsx"
+  - "**/components/workspace/CommandCenter.tsx"
 ---
 
 # Command Center Dashboard Rules (MANDATORY)
 
-These rules are non-negotiable for all files in `src/components/pages/`.
+These rules are non-negotiable for all dashboard files in `src/pages/` and workspace files in `src/components/workspace/`.
+
+**For the Engine Travel Command Center specifically:** Also read `.a4drules/features/engine-dashboard-rule.md` and `engine-command-center-prd.md` at the project root.
 
 ## Before writing ANY code, load these skills
 
 You MUST load the **command-center-builder** and **component-library** skills before writing or editing dashboard pages. These skills contain the full component API reference and builder rules. Do not proceed without them.
 
+**For Engine dashboard:** Also load **command-center-project** and **outer-app** skills, and read `engine-command-center-prd.md`.
+
+**For Phase 2 (sample data):** Read `.a4drules/features/phase2-data-pattern.md`. The sample data file already exists at `src/data/engine-sample-data.js` — do NOT create it, just import from it.
+
 ## Critical constraints
 
-1. **File extension must be `.jsx`** — not `.tsx`. Rename if needed.
+1. **File extension MUST be `.tsx`** — This is a TypeScript project. All React components MUST use `.tsx` extension, never `.jsx`. Dashboard files go in `src/pages/` (NOT `src/components/pages/`). All type definitions are available from the component library.
 
 2. **Use ONLY library components** from `@/components/library` for cards, charts, tables, lists. Never hand-roll HTML cards (`<div className="bg-white border rounded...">`).
 
@@ -37,10 +43,17 @@ You MUST load the **command-center-builder** and **component-library** skills be
 
 11. **`useDataSource`** is required — wire all data through `useDataSource({ sample, live })` for sample/live mode.
 
-12. **Run `npm run validate:dashboard`** before reporting done — fix ALL errors, zero tolerance. Never dismiss errors as "justified".
+12. **Run `npm run validate:dashboard`** before reporting done — fix ALL errors, zero tolerance. Never dismiss errors as "justified". The validator MUST show zero errors before the dashboard is considered complete.
+
+```bash
+cd force-app/main/default/webapplications/reactapp4
+npm run validate:dashboard
+```
+
+If errors are reported, you MUST fix them by switching to library components, correct colors, or proper imports. Do not proceed until the validator shows zero errors.
 
 13. **Do NOT `npm install` any packages** for dashboard work. The component library and existing dependencies have everything needed.
 
 14. **Heroicon names** — common correct names: `PaperAirplaneIcon` (not PlaneIcon), `BuildingOfficeIcon` (not HotelIcon), `BanknotesIcon` (not MoneyIcon), `ExclamationTriangleIcon` (not AlertIcon), `UserIcon` (not PersonIcon).
 
-15. **Wire the dashboard as the home page.** After creating your dashboard and updating `CommandCenter.tsx`, also update `src/routes.tsx`: set `Home` as the index route (it renders CommandCenter which renders your dashboard) and move `Search` to `/search`. The dashboard must be the first thing users see at `/`.
+15. **Wire the dashboard as the home page.** After creating your dashboard and updating `CommandCenter.tsx`, you MUST also update `src/pages/Home.tsx` to render `CommandCenter` (replace any search interface with `import CommandCenter from "@/components/workspace/CommandCenter"; export default function HomePage() { return <CommandCenter />; }`), and update `src/routes.tsx` to set `Home` as the index route and move `Search` to `/search`. The dashboard must be the first thing users see at `/`.

package/.a4drules/features/engine-dashboard-rule.md

@@ -0,0 +1,302 @@
+---
+paths:
+  - "**/pages/EngineDashboard.tsx"
+  - "**/pages/Engine*.tsx"
+---
+
+# Engine Travel Command Center Dashboard Rules
+
+These rules apply ONLY when building the Engine Travel Command Center dashboard from `engine-command-center-prd.md`.
+
+## Source of Truth
+
+**The PRD is law:** `engine-command-center-prd.md` at the project root is the complete specification. Follow it exactly. If the PRD conflicts with your assumptions, the PRD wins.
+
+## Phase Discipline (MANDATORY)
+
+The Engine dashboard uses a **strict 4-phase build process.** You MUST complete each phase fully before starting the next:
+
+1. **Phase 1: Layout** — Structure only, placeholders, no real components
+2. **Phase 2: Components + Sample Data** — Full UI with hardcoded realistic data
+   - **CRITICAL:** Sample data file already exists at `src/data/engine-sample-data.js`
+   - **DO NOT create a new data file** — just import from the existing one
+   - Import dashboard-ready derivatives (MAP_MARKERS, TRAVELER_CARDS, etc.)
+   - DO NOT define sample data inline in the dashboard — causes file truncation
+3. **Phase 3: Real Data** — Connect to Salesforce, keep UI identical to Phase 2
+4. **Phase 4: Agent** — Add Eva ChatBar integration
+
+### Phase 1 Placeholder Format
+
+**Data panels** use `BaseCard` with centered placeholder text. NO titles on placeholders:
+
+```tsx
+<BaseCard>
+  <div className="h-48 flex items-center justify-center text-slate-400">
+    Disruptions Panel
+  </div>
+</BaseCard>
+```
+
+**Hero map** renders the actual GeoMap component (empty, no data):
+
+```tsx
+import { GeoMap, useAppTheme } from "@/components/library";
+
+export default function EngineDashboard() {
+  const { mode } = useAppTheme();
+  
+  return (
+    <div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+      <GeoMap
+        width={960}
+        height={520}
+        theme={mode === "dark" ? "dark" : "light"}
+        className="h-full w-full"
+      />
+    </div>
+  );
+}
+```
+
+All data panel placeholders: BaseCard, no title, centered text, `h-48`, `text-slate-400`.
+
+Hero map in Phase 1: actual GeoMap component (no markers/arcs/overlays yet), NOT wrapped in BaseCard.
+
+**DO NOT:**
+- Mix phases (don't add sample data in Phase 1, don't add Eva in Phase 2, etc.)
+- Skip validation between phases
+- Proceed to the next phase with validator errors
+- Use BaseCard titles in Phase 1 placeholders (causes text to run together)
+
+### Phase 3: Real Data Integration
+
+**CRITICAL:** You MUST explicitly use the Salesforce GraphQL skills by name. Declarative listing doesn't work - use imperative commands.
+
+**Goal:** Connect dashboard to live Salesforce data. No toggle needed - dashboard shows live data only.
+
+**Key insight:** The sample data file (`src/data/engine-sample-data.js`) already uses real Salesforce field names (Trip__c, Flight__c, Contact, etc.). Read the file header comment to understand the object schema.
+
+**Custom objects used:**
+- Contact (travelers, with custom fields: Home_Airport__c, Travel_Policy_Tier__c, etc.)
+- Trip__c (origin, destination, dates, cost, policy status)
+- Flight__c (flight number, airports, status, delay, traveler lookup)
+- Booking__c (upcoming reservations)
+- Disruption__c (delays, cancellations, severity)
+- Rebooking_Action__c (Eva activity log)
+- Travel_Policy__c (policy rules and status)
+
+**Implementation steps (FOLLOW EXACTLY):**
+
+1. **Read sample data file** (`src/data/engine-sample-data.js`) to understand which Salesforce fields are needed (e.g., Trip__c has Origin_City__c, Contact has FirstName, etc.)
+
+2. **Use the Salesforce GraphQL skills** to implement queries and hooks:
+   
+   - Use `exploring-webapp-graphql-schema` skill to look up each object
+     - Say: "Use the exploring-webapp-graphql-schema skill to look up Trip__c"
+     - The skill reads from schema.graphql (already checked into the repo)
+   
+   - Use `generating-webapp-graphql-read-query` skill to create queries
+     - Say: "Use the generating-webapp-graphql-read-query skill to create a query for Trip__c"
+     - The skill generates properly typed GraphQL code with @optional directives
+   
+   - Use `using-webapp-graphql` skill to implement hooks
+     - Say: "Use the using-webapp-graphql skill to create a useTravelers hook"
+     - The skill creates hooks that return { data, loading, error }
+
+3. **Update useDataSource calls** to use live data:
+   - Change: `useDataSource({ sample: TRAVELER_CARDS })`
+   - To: `useDataSource({ sample: TRAVELER_CARDS, live: liveTravelers ?? [] })`
+
+4. **No data mode toggle** - dashboard always shows live data (or falls back to sample on error)
+
+**Key insight:** The schema.graphql file is pre-built and checked into the repo. GraphQL skills and tooling work out of the box without any schema generation.
+
+**Example pattern:**
+
+```tsx
+// Phase 2 (sample data only)
+const travelers = useDataSource({ sample: TRAVELER_CARDS, live: [] });
+
+// Phase 3 (live data with sample fallback on error)
+const { data: liveTravelers, loading, error } = useTravelers();
+const travelers = useDataSource({ 
+  sample: TRAVELER_CARDS,  // Used as fallback if live data fails
+  live: liveTravelers ?? []  // Primary data source
+});
+```
+
+The `useDataSource` hook automatically uses `live` data when available, falling back to `sample` only on error. No toggle UI needed.
+
+**DO NOT:**
+- Ask the user about object names - they're in the sample data file
+- Create object metadata - objects already exist in org  
+- Change field names in queries - use exact names from sample data
+- Modify UI components - only change data sources
+- Add DataModeToggle - Phase 3 uses live data only (sample data is fallback for errors)
+- Panic if schema introspection fails - queries still work fine (see troubleshooting guide below)
+- List skills declaratively - use imperative commands ("Use the X skill to...")
+
+**Troubleshooting:** If you encounter GraphQL schema introspection failures, see `.a4drules/troubleshooting/graphql-introspection-failure.md` for the complete workaround pattern.
+
+## Validation Checkpoints (ZERO ERRORS REQUIRED)
+
+After EVERY change, run the validator from the webapp directory:
+
+```bash
+cd force-app/main/default/webapplications/reactapp4
+npm run validate:dashboard
+```
+
+**Zero errors required.** If the validator reports ANY errors:
+1. Read the error message carefully
+2. Identify which rule was violated
+3. Fix it by switching to the correct library component
+4. Re-run the validator
+5. Repeat until zero errors
+
+**Common fixes:**
+- "Hand-rolled card detected" → Wrap in `WidgetCard`, `ListCard`, `BaseCard`, etc.
+- "Forbidden color: text-white" → Change to `text-slate-50` or `text-slate-900`
+- "shadcn import detected" → Replace with library equivalent from `@/components/library`
+- "Missing useDataSource" → Add `useDataSource({ sample, live })` pattern
+
+Do NOT report the phase as complete until the validator shows zero errors.
+
+## File Requirements
+
+- **Extension:** `.tsx` (TypeScript) — NEVER `.jsx`
+- **Location:** `src/pages/EngineDashboard.tsx` (NOT `src/components/pages/`)
+- **Imports:** ONLY from `@/components/library` — never shadcn, never Lucide, never Recharts
+
+## Layout Pattern: Visualization-Hero
+
+The Engine dashboard uses the **visualization-hero** layout (see PRD section 5). This means:
+
+1. **Hero map:** Full-width, large (`flex: 1.15 1 0`), GeoMap with glass overlays and flight status strip
+2. **Data panels below:** Standard grid sections (`flex: 1 1 0`)
+
+**DO NOT:**
+- Put the map in a 1/3 or 1/2 grid column (it's hero, not sidebar)
+- Wrap GeoMap in ChartCard (render directly)
+- Skip the glass KPI overlays or flight status strip
+- Make the map too small (minimum 400px height)
+
+## Component Selection
+
+Every section of the dashboard MUST use a library component. No hand-rolled HTML cards:
+
+| Content | Use | NOT |
+|---------|-----|-----|
+| KPI number | `MetricCard` | `<div className="bg-white ...">` |
+| Data table | `TableCard` | `<table>` HTML |
+| Item list | `ListCard` | Custom `.map()` divs |
+| Activity log | `ActivityCard` | Custom feed markup |
+| Chart | `ChartCard` + `D3Chart` | Recharts/Chart.js/custom SVG |
+| Map | `GeoMap` (direct) | react-simple-maps |
+| Status items | `StatusCard` | Custom status badges |
+| Multi-section panel | `WidgetCard` | Nested divs |
+| Expandable content | `WidgetCard` (single section) | Hand-rolled collapse logic |
+
+## Engine Brand Colors
+
+Update `src/styles/global.css` with Engine teal palette (PRD section 3). Use `engine-*` and `brand-*` Tailwind classes, never hardcoded hex values.
+
+## Dark Mode (MANDATORY)
+
+Every visible element MUST work in both light and dark mode. Test both before reporting complete.
+
+- GeoMap: pass `theme={mode === "dark" ? "dark" : "light"}`
+- Glass overlays: `bg-black/40 backdrop-blur-md` (works in both modes)
+- Text: use slate scale, never `text-black` or `text-white`
+- All custom elements: add `dark:` variants
+
+## Eva Integration (Phase 4 Only)
+
+Eva is a `ChatBar` in the header. NOT a FAB. NOT a ChatPanel in the grid. NOT a sliding panel.
+
+```tsx
+<ChatBar
+  title="Eva"
+  placeholder="Ask Eva..."
+  suggestions={CHAT_SUGGESTIONS}
+  onSend={handleChat}
+/>
+```
+
+## Data Mode (Sample vs Live)
+
+Every component must work in both data modes:
+
+```typescript
+// ✅ Correct
+const SAMPLE_TRAVELERS = [...];  // module scope
+const travelers = useDataSource({ sample: SAMPLE_TRAVELERS, live: liveTravelers });
+
+// ❌ Wrong — no mode switching
+const travelers = [...];  // always uses same data
+```
+
+## Wiring Steps (REQUIRED)
+
+After creating `EngineDashboard.tsx`, you MUST:
+
+1. Update `src/components/workspace/CommandCenter.tsx`:
+   ```tsx
+   import EngineDashboard from "../../pages/EngineDashboard";
+   // ... render <EngineDashboard />
+   ```
+
+2. Update `src/pages/Home.tsx`:
+   ```tsx
+   import CommandCenter from "@/components/workspace/CommandCenter";
+   export default function HomePage() { return <CommandCenter />; }
+   ```
+
+3. Update `src/routes.tsx`:
+   ```tsx
+   { index: true, element: <Home />, handle: { showInNavigation: true, label: 'Dashboard' } }
+   ```
+
+Verify all three files are updated before reporting complete.
+
+## Pre-Completion Checklist
+
+Before reporting ANY phase complete, verify ALL of these:
+
+- [ ] Validator shows zero errors (`npm run validate:dashboard`)
+- [ ] File is `.tsx` not `.jsx`
+- [ ] All cards are library components (MetricCard, ListCard, etc.)
+- [ ] No hand-rolled HTML cards (`<div className="bg-white border ...">`)
+- [ ] No shadcn imports (`@/components/ui/`)
+- [ ] No Lucide icons (use Heroicons)
+- [ ] No chart libraries (use D3Chart/GeoMap)
+- [ ] GeoMap rendered directly, not wrapped in ChartCard
+- [ ] Dark mode works on all elements
+- [ ] `useDataSource` used for all data
+- [ ] Sample data is module-scope constants
+- [ ] CommandCenter.tsx, Home.tsx, and routes.tsx are updated
+- [ ] Dev server starts without errors (`npm run dev`)
+
+## What Makes This Dashboard Unique
+
+The Engine dashboard's signature elements (must be present):
+
+1. **Hero map** — Full-width GeoMap with animated flight arcs, weather overlays, glass KPI pills, and flight status strip
+2. **Glass overlays** — Floating KPIs and flight chips with `bg-black/40 backdrop-blur-md`
+3. **Engine brand** — Teal color palette throughout
+4. **Eva integration** — ChatBar in header for AI queries
+5. **Disruptions panel** — Custom inline component showing severity dots and Eva actions
+
+These elements distinguish the Engine dashboard from generic dashboards. They must all be present and functional.
+
+## Anti-Patterns (NEVER DO THESE)
+
+- Creating BlankDashboard.tsx or GenericDashboard.tsx (name is EngineDashboard.tsx)
+- Multi-tab layout with content swapping (build one scrollable page)
+- `<nav>` or header bar inside the dashboard (AppLayout handles navigation)
+- Map in a sidebar grid (it's hero — full width)
+- More than 4 KPIs in a row
+- Using `Math.random()` in sample data
+- Skipping validator errors
+- Reporting phase complete before wiring the dashboard into the app
+- Mixing phases (adding sample data in Phase 1, adding Eva in Phase 2, etc.)

package/.a4drules/features/phase2-data-pattern.md

@@ -0,0 +1,166 @@
+---
+paths:
+  - "**/pages/*.tsx"
+  - "**/data/*.ts"
+---
+
+# Phase 2: Sample Data Pattern (MANDATORY)
+
+When building Phase 2 (Components & Sample Data), you MUST use the pre-existing sample data file to avoid file truncation.
+
+**Important:** The sample data file uses real Salesforce field names (Trip__c, Flight__c, Contact, etc.) so Phase 3 can connect to live data without field name changes.
+
+## The Problem
+
+**❌ WRONG:** Defining all sample data inline in the dashboard file causes:
+- Dashboard file becomes 500+ lines
+- File gets truncated during writing
+- Unclosed JSX tags and syntax errors
+- Agent has to retry multiple times
+
+## The Solution
+
+**✅ CORRECT:** The sample data file already exists at `src/data/engine-sample-data.js` — just import and use it.
+
+### Data File Already Exists
+
+The file `src/data/engine-sample-data.js` contains all sample data as exported constants:
+
+```javascript
+// src/data/engine-sample-data.js
+// THIS FILE ALREADY EXISTS - DO NOT CREATE IT
+
+// Sample data exports (already defined):
+export const TRAVELERS = [...];            // 8 travelers with Contact fields
+export const TRIPS = [...];                // 8 trips with Trip__c fields
+export const FLIGHTS = [...];              // 8 flights with Flight__c fields
+export const HOTELS = [...];               // 8 hotels with Reservation fields
+export const DISRUPTIONS = [...];          // 4 disruptions
+export const BOOKINGS = [...];             // 8 upcoming bookings
+export const REBOOKING_ACTIONS = [...];    // 8 Eva actions
+export const TRAVEL_POLICIES = [...];      // 5 policy items
+export const MONTHLY_SPEND = [...];        // 6 months of spend
+export const ACCOUNT = {...};              // Account stats
+
+// Dashboard-ready derivatives (already computed):
+export const MAP_MARKERS = [...];          // For GeoMap markers prop
+export const MAP_ARCS = [...];             // For GeoMap arcs prop
+export const MAP_OVERLAYS = [...];         // For GeoMap overlays prop
+export const FLIGHT_STATUS_LIST = [...];   // For flight status strip
+export const TRAVELER_CARDS = [...];       // For traveler ListCard
+export const DISRUPTION_CARDS = [...];     // For disruptions panel
+export const EVA_ACTIONS = [...];          // For ActivityCard
+export const BOOKING_ROWS = [...];         // For TableCard
+export const POLICY_ITEMS = [...];         // For StatusCard
+export const DESTINATION_CHART_DATA = [...]; // For destination chart
+export const SPEND_CHART_DATA = [...];     // For spend chart
+export const METRICS = {...};              // Computed KPIs
+```
+
+This file is ~370 lines and contains all sample data you need.
+
+### Import Into Dashboard
+
+In `src/pages/EngineDashboard.tsx`, import the pre-existing data:
+
+```typescript
+// src/pages/EngineDashboard.tsx
+import React from "react";
+import { BaseCard, ListCard, ActivityCard, ChartCard, TableCard, StatusCard, D3Chart, GeoMap } from "@/components/library";
+import {
+  MAP_MARKERS,
+  MAP_ARCS,
+  MAP_OVERLAYS,
+  FLIGHT_STATUS_LIST,
+  TRAVELER_CARDS,
+  DISRUPTION_CARDS,
+  EVA_ACTIONS,
+  BOOKING_ROWS,
+  POLICY_ITEMS,
+  DESTINATION_CHART_DATA,
+  SPEND_CHART_DATA,
+  METRICS
+} from "@/data/engine-sample-data";
+
+export default function EngineDashboard() {
+  return (
+    <div className="flex h-screen flex-col bg-slate-50 dark:bg-slate-950">
+      {/* Header - use METRICS for KPIs */}
+      
+      {/* Hero Map - use MAP_MARKERS, MAP_ARCS, MAP_OVERLAYS */}
+      <GeoMap markers={MAP_MARKERS} arcs={MAP_ARCS} overlays={MAP_OVERLAYS} />
+      
+      {/* Data Panels */}
+      <div className="px-4 py-5 space-y-6">
+        {/* Disruptions - use DISRUPTION_CARDS */}
+        {/* Active Travelers - use TRAVELER_CARDS */}
+        {/* Eva Activity - use EVA_ACTIONS */}
+        <ActivityCard title="Eva Activity" actions={EVA_ACTIONS} />
+        
+        {/* Charts - use DESTINATION_CHART_DATA, SPEND_CHART_DATA */}
+        {/* Bookings - use BOOKING_ROWS */}
+        <TableCard items={BOOKING_ROWS} />
+        
+        {/* Policy - use POLICY_ITEMS */}
+        <StatusCard items={POLICY_ITEMS} />
+      </div>
+    </div>
+  );
+}
+```
+
+Dashboard file stays ~150-200 lines because data is imported.
+
+## Phase 2 Workflow
+
+**DO NOT create the data file** — it already exists. Just:
+
+1. Read `src/data/engine-sample-data.js` to understand available exports
+2. Import the dashboard-ready derivatives into `src/pages/EngineDashboard.tsx`
+3. Replace BaseCard placeholders with library components using imported data
+
+## Benefits
+
+- ✅ Dashboard file stays small (no truncation)
+- ✅ Data file already prepared and tested
+- ✅ Clean separation of concerns
+- ✅ Easy to switch to live data in Phase 3 (just change imports)
+- ✅ Faster Phase 2 completion (no data creation needed)
+
+## Common Mistakes
+
+❌ **Creating a new data file:**
+```bash
+# WRONG - file already exists
+Write src/data/engine-sample-data.ts
+```
+
+❌ **Defining data inline in dashboard:**
+```typescript
+export default function EngineDashboard() {
+  const travelers = [
+    { id: "1", name: "Maya Rodriguez", ... }, // 500 more lines
+  ];
+  // File gets truncated here!
+```
+
+✅ **Importing from existing file:**
+```typescript
+import { TRAVELER_CARDS, EVA_ACTIONS } from "@/data/engine-sample-data";
+
+export default function EngineDashboard() {
+  // Use imported data
+  <ListCard items={TRAVELER_CARDS} />
+  <ActivityCard actions={EVA_ACTIONS} />
+}
+```
+
+## Complete Phase 2 Workflow
+
+1. **Read** `src/data/engine-sample-data.js` (understand exports)
+2. **Import** dashboard-ready derivatives into `src/pages/EngineDashboard.tsx`
+3. **Replace** BaseCard placeholders with library components using imported data
+4. **Run** validator (`npm run validate:dashboard`)
+5. **Test** in browser
+
+This pattern prevents truncation and keeps code clean.

package/.a4drules/features/pre-code-checklist.md

@@ -0,0 +1,72 @@
+---
+paths:
+  - "**/pages/*.tsx"
+  - "**/components/pages/*.tsx"
+---
+
+# Pre-Code Checklist (MANDATORY)
+
+Before writing any code for command center dashboards, verify these requirements from the PRD and skills.
+
+## File Creation Checklist
+
+When creating a new dashboard file, confirm:
+
+1. **File path:** `src/pages/DashboardName.tsx` (NOT `src/components/pages/`)
+2. **File extension:** `.tsx` (NOT `.jsx`) — this is a TypeScript project
+3. **Imports:** `@/components/library` ONLY (NOT `@/components/ui/`, NOT `lucide-react`, NOT `recharts`)
+4. **Colors:** Slate scale ONLY (NOT `text-white`, NOT `text-black`, NOT `bg-black`)
+
+## During Code Generation Checklist
+
+As you write the dashboard code:
+
+1. **Every card** is a library component (MetricCard, ListCard, WidgetCard, etc.) — NO hand-rolled `<div className="bg-white border rounded...">`
+2. **Every chart** uses `ChartCard` + `D3Chart` or `GeoMap` — NO Recharts, NO Chart.js, NO custom SVG
+3. **Every color** uses semantic classes or slate scale — NO `text-white`, NO `bg-black`, NO hardcoded hex
+4. **Dark mode** on every element — `dark:` variants on all custom styling
+5. **Phase 1 placeholders:**
+   - Data panels: use BaseCard with NO title prop, centered text
+   - Hero map: render actual GeoMap component (empty, no markers/arcs/overlays), NOT wrapped in BaseCard
+
+## After Code Generation Checklist
+
+After writing the dashboard code:
+
+1. **Wiring:**
+   - [ ] `CommandCenter.tsx` imports your dashboard
+   - [ ] `Home.tsx` renders `CommandCenter`
+   - [ ] `routes.tsx` has correct routes
+
+2. **Validation:**
+   ```bash
+   cd force-app/main/default/webapplications/reactapp4
+   npm run validate:dashboard
+   ```
+   - [ ] Zero errors required
+   - [ ] Fix all errors before proceeding
+
+## Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| File path? | `src/pages/EngineDashboard.tsx` |
+| Extension? | `.tsx` (TypeScript) |
+| Import from? | `@/components/library` |
+| Colors? | Slate scale (`text-slate-50`, `bg-slate-900`) |
+| Cards? | Library components (MetricCard, ListCard, etc.) |
+| Charts? | `ChartCard` + `D3Chart` or `GeoMap` |
+| Validate? | `npm run validate:dashboard` → zero errors |
+
+## Common Mistakes to Avoid
+
+❌ `src/pages/EngineDashboard.tsx` → ✅ `src/pages/EngineDashboard.tsx`
+❌ `EngineDashboard.jsx` → ✅ `EngineDashboard.tsx`
+❌ `text-white` → ✅ `text-slate-50`
+❌ `bg-black` → ✅ `bg-slate-900`
+❌ `<div className="bg-white border rounded-lg p-4">` → ✅ `<BaseCard>` or `<WidgetCard>`
+❌ `import { Button } from '@/components/ui/button'` → ✅ `import { UIButton } from '@/components/library'`
+
+## Enforcement
+
+This checklist is MANDATORY. Do not skip any step. Verify each item before moving to the next phase.