@schandlergarcia/sf-web-components 1.9.66 → 1.9.68

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

@@ -1,19 +1,21 @@
 ---
 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.
+  Conventions and patterns for building the Engine Travel Command Center
+  dashboard and other command center pages. Covers layout patterns
+  (visualization-hero, grid), component selection (MetricCard, ChartCard,
+  GeoMap, ListCard, ActivityCard), dark mode, brand colors, styling, and
+  wiring dashboards into the app. Use when scaffolding, building, or editing
+  any dashboard page 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
+## Core Conventions
 
-**Every time you build a dashboard, you MUST follow these non-negotiable rules. Violations are the #1 cause of rejected dashboards.**
+The following conventions apply to all dashboard development in this project.
 
 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
@@ -21,7 +23,7 @@ Before writing any code, read `.a4drules/features/pre-code-checklist.md` and ver
 - Using forbidden colors (`text-white`, `bg-black`)
 - Hand-rolling HTML cards instead of using library components
 
-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. **Write `.tsx` files** in `src/pages/` and update `CommandCenter.tsx` to import the dashboard. This is a TypeScript project — all React components use `.tsx` extension.
 
 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.
 
@@ -33,11 +35,9 @@ Before writing any code, read `.a4drules/features/pre-code-checklist.md` and ver
 
 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.
+## Use Library Components — Not Hand-Rolled HTML Cards
 
-## 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.
+The component library (`@/components/library`) provides pre-built, themed, dark-mode-ready cards for every common dashboard need. Use them instead of writing raw `<div>` cards with custom classes.
 
 ### Before writing ANY card-like UI, check this table:
 
@@ -53,7 +53,7 @@ If your output violates any of these 6 rules, it will be rejected and you will n
 | 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.
+Every visible section of a dashboard should be a library component. If you're writing `<div className="bg-white border rounded-[10px] shadow-sm p-6">` with content inside, that's a hand-rolled card — use a library component instead.
 
 ### Correct example:
 
@@ -81,27 +81,9 @@ import { MetricCard, ListCard, ActivityCard, WidgetCard } from "@/components/lib
 </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)
+## Images
 
-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.).
+The company logo is at `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";
@@ -113,36 +95,9 @@ import engineLogo from "@/assets/images/engine_logo.png";
 - **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?
+## No Dashboard-Level Navigation
 
-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.
+No `<nav>`, header bar, tab bar, or content-swapping via `useState("activeTab")` inside dashboard pages. The app shell handles navigation. Dashboards are single scrollable pages — all content visible by scrolling.
 
 ## Where Dashboards Live & How to Wire Them
 
@@ -152,7 +107,7 @@ Splitting a dashboard into 5 tab "pages" (Overview, Travelers, Spend, Policy, Ev
 
 ### Wiring a new dashboard (REQUIRED STEPS)
 
-You must do ALL of these or the dashboard will not render correctly:
+All three steps are required for the dashboard to render:
 
 **Step 1:** Create the dashboard file in `src/pages/` (NOT `src/components/pages/`):
 ```tsx
@@ -248,46 +203,14 @@ Only these grid patterns — do not invent new ones:
 
 **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
 
-**Default pattern:** GeoMap in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`). This works well for dashboards where the map is one of several equal-weight sections.
-
-**If the PRD specifies a "visualization-hero" layout**, the map is full-width hero with glass overlays. The PRD always overrides this default pattern.
-
-**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>
-```
+**Default:** GeoMap in a wide/narrow grid (`lg:grid-cols-3` with `lg:col-span-2`). **If the PRD specifies "visualization-hero"**, the map is full-width hero — PRD overrides this default.
 
 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+
+- Do NOT wrap GeoMap in ChartCard — GeoMap has its own styling
+- Always pass `arcs` and `overlays`, not just markers
+- Use `initialBounds` to auto-zoom: `{ sw: [lonMin, latMin], ne: [lonMax, latMax], padding: 30 }`
 
 ## Component Selection
 
@@ -346,7 +269,7 @@ Defined in `global.css` (`--color-brand-*` and `--color-engine-*`), available as
 
 Canonical: `"operational"`, `"degraded"`, `"outage"`, `"maintenance"`. Always show color + text label.
 
-## Dark Mode (MANDATORY)
+## Dark Mode
 
 Every visible element needs both light and dark styles. Library components handle this automatically — which is another reason to use them.
 
@@ -429,9 +352,9 @@ Use `ChatBar` (command palette, ⌘K) for dashboards. `ChatPanel` for full-page
 
 `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)
+## Charts & Visualizations
 
-**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`.
+All charts, graphs, maps, and visualizations use the library's charting 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 |
 |--------------|----------|----------|
@@ -496,14 +419,6 @@ const monthlyData = [
   }
 />
 
-// ✅ 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
@@ -515,27 +430,9 @@ function renderDonut(svgEl, data, dims, opts) {
 
 ### 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
-  />
-} />
-```
+Props: `width`, `height`, `projection` (`"naturalEarth"` | `"mercator"` | `"equirectangular"`), `theme` (`"dark"` | `"light"`), `markers`, `arcs`, `overlays`, `zoomable`, `minZoom`, `maxZoom`, `onMarkerClick`.
 
-GeoMap props: `width`, `height`, `projection` (`"naturalEarth"` | `"mercator"` | `"equirectangular"`), `theme` (`"dark"` | `"light"`), `markers`, `arcs`, `overlays`, `zoomable`, `minZoom`, `maxZoom`, `onMarkerClick`.
+Marker shape: `{ id, lon, lat, active?, label? }`. Arc shape: `{ id, from: [lon, lat], to: [lon, lat], progress?, danger? }`. Overlay shape: `{ id, center: [lon, lat], radius }`.
 
 ### Common mistakes
 
@@ -592,37 +489,17 @@ Before finishing a dashboard page, verify ALL of these:
 
 Instead, verify correctness by reviewing the code against the Pre-Completion Checklist above. Confirm that all three wiring files are updated (CommandCenter.tsx, Home.tsx, routes.tsx).
 
-## Anti-Patterns (never do these)
+## Anti-Patterns
 
-- 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}`
+- Importing from `src/components/ui/` (shadcn) or `lucide-react` — use `@/components/library` and `@heroicons/react`
+- Using `cn()` helper — use Tailwind classes directly
+- Hand-rolling HTML cards (`<div className="bg-white border ...">`) — use library components
+- Using Recharts, Chart.js, or any third-party charts — use `D3Chart` + `D3ChartTemplates` or `GeoMap`
+- Using `template` prop on D3Chart — 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`
+- Adding `<nav>` or tab-swapping (`useState("activeTab")`) inside dashboards
+- Recreating providers — `CommandCenter.tsx` already provides them
+- Using `text-black`, `text-white`, `bg-black` — use slate scale
+- Hardcoded data without `useDataSource` — always support sample/live switching
 - `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
+- `Math.random()` in sample data

package/.a4drules/skills/command-center-builder/charts-visualization.md

@@ -1,136 +1 @@
-## Charts & Visualizations
-
-**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.
-
+See SKILL.md — Charts & Visualizations section.

package/.a4drules/skills/command-center-builder/completion-checklist.md

@@ -1,61 +1 @@
-## 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
-
-**DO NOT run `npm run validate:dashboard`, `npm run dev`, `npm run build`, or `tsc` during builds.** These waste time and are not required for phase completion.
-
-Instead, verify correctness by reviewing the code against the Pre-Completion Checklist above. Confirm that all three wiring files are updated (CommandCenter.tsx, Home.tsx, routes.tsx).
-
-## 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
+See SKILL.md — Pre-Completion Checklist and Post-Completion Verification sections.

package/.a4drules/skills/command-center-builder/components-styling.md

@@ -1,97 +1 @@
-## 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
-
-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)
-
+See SKILL.md — Component Selection, Colors, Dark Mode, Icons sections.

package/.a4drules/skills/command-center-builder/data-forms-ai.md

@@ -1,43 +1 @@
-## 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`.
-
+See SKILL.md — Data Mode, Forms, AI Chat, Tables sections.