Codex

How every dashboard / board page in this repo is built. The kit is DashboardBoard (+ GridBoard / useGridBoard / DashboardToolbar / StatTile underneath it) in src/components/gridstack/; the living examples are the reference board (/labs/layout/dashboard), the CRM dashboard (/labs/apps/crm) and the twelve Industries screens. Same contract as data-view.md: the kit enforces what it can with defaults, this file records the rest.

A dashboard is a composition of independent features, so the one-feature-one-card law applies with full force: every widget is exactly one standard Card, and the board itself owns no chrome at all — cells are transparent, spacing comes from the grid margin, and the page never writes grid CSS or GridStack init code. Everything a user can do to a widget (drag, resize, show/hide) belongs to the board layer; everything inside the card belongs to the widget's own feature.

const WIDGETS: GridBoardWidget[] = [
  { id: "revenue", label: "Revenue", w: 6, h: 3, minW: 4, minH: 2, node: <StatRevenueCard /> },
  …
];

<DashboardBoard title="Grid control room" icon="icon-[solar--bolt-bold-duotone]" widgets={WIDGETS} />

That is the whole page. A dashboard writes a widget list and nothing else — no visibility reducer, no re-key expression, no grid options.

• One widget, one Card. The cell is chrome-less; the Card owns the surface, elevation and radius. A widget whose interior has functional regions uses the same separator grammar as everywhere else: solid edge = the card, dashed hairlines inside. Gallery cards keep their own rounded-3xl surface — that IS their card — and take fill to drop the standalone max-width and stretch to the cell.
• A KPI strip is not a widget — its tiles are. Four figures in a row is four independent readings, so they are four StatTile widgets a user can hide one at a time, not one card containing a grid.
• Screen furniture is a widget too. A run header, a changes log, a cost-by-agent table: if it renders on the board it is a card in the widget list, not a band floating above it. The only things outside the board are the PageHeader and the ComposedOf traceability footnote.
• Interactivity is opt-out, not re-implemented. Whole-card drag comes from the kit; anything clickable inside a widget must not start a drag — the GRID_DRAG_CANCEL list already covers links, buttons, form controls, menus and recharts; add data-no-drag (or the .no-drag class) for anything exotic instead of touching the drag options.
• Visibility goes through Customize. All widgets shown by default; hiding filters the widget list and re-keys the board on the visible set — GridStack owns the DOM after init, so React must never remove items from under it. Reset restores the all-shown default.
• Sizes are content-derived. Default w/h fit the widget's natural content at cellHeight 80 so nothing clips before the user ever resizes; minW/minH stop a resize from making the widget unreadable.
• The board is not a data view. A widget may contain a small table or list, but toolbars, scope tabs and pagination belong to data-view pages — a widget that needs them has outgrown the dashboard and should become (or link to) its own page. A board-level scope filter is the same mistake by another name: Customize already answers "show me only these", so a second filter over the same widgets is the duplicate control the data-view migration deleted everywhere else.
• Boards other than the reference one pass their own title / icon to the toolbar; the bar's shape never changes. A board-level control (Refresh, Export) goes in the toolbar's actions slot, left of Customize — never in a second bar.
• Below md the board is a plain stack. The kit's CSS hands positions and heights back to normal flow there, because a card is always taller at 350px than at 600px and a height tuned wide clips its own content narrow. Don't fight it with per-page breakpoints.

1. Build each widget as a self-contained <Card> feature (mock data deterministic, per the house rules).
2. Declare the WIDGETS list: stable ids, human labels, content-derived w/h + minW/minH.
3. Render <DashboardBoard widgets={WIDGETS} title=… icon=… /> — that is the entire page body; there is nothing else to write.
4. Register the route in nav-data.ts and add/extend the feature-ledger entry.

• Hand-rolled GridStack init, grid CSS, or drag/resize options in a page.
• A widget surface that is not a standard Card, or a Card wrapped in extra cell chrome.
• Hiding widgets by conditional render without re-keying the board.
• A second toolbar, or visibility state stored inside the toolbar.
• Reusing a widget id for a different widget (Customize state keys on it).
• Nesting a board inside a widget.