@mtdt/observeops-ds-spec 0.1.0

package/components/recipes/recipes.json

@@ -0,0 +1,922 @@
+{
+  "$description": "Page & flow composition recipes for the ObserveOps design system. Each recipe is a product-faithful blueprint for assembling catalogued components into a whole screen/flow. `id`s + `variant`s reference components/index.json + the registries. This is the layer above per-component docs — it tells an AI HOW to lay out a page, not just which parts exist.",
+  "$howToUse": [
+    "1. Match the user's screen to a recipe by `whenToUse` / `examples`.",
+    "2. Build the `regions` top-to-bottom / outer-to-inner: each region names component `id`s + `variant`s — open those in components/registry/ for props.",
+    "3. Apply `layout.shell` + `layout.tokens` (resolve via tokens/variables.json + tokens/structural.json) for spacing/sizing.",
+    "4. Honour `gotchas` (known traps) and `a11y`.",
+    "5. The product content (which columns/fields/options) is domain data the DS does not own — fill from the user's spec.",
+    "6. A region marked `$gap` references a layer NOT catalogued in the DS yet — do NOT improvise it. STOP and ASK the user (see ../AGENTS.md deviation rule)."
+  ],
+  "$knownGaps": {
+    "$note": "Catalogued only as `data-viz-tooltips` (the hover tooltips). The actual VISUALISATION layer is NOT in the DS yet — wherever a recipe needs one, the region carries a `$gap` and you must STOP and ASK.",
+    "charts": "Charts / widget tiles (line/bar/donut/gauge/heatmap/sankey/etc.) — no chart component in index.json; only data-viz-tooltips covers their tooltips.",
+    "topologyGraph": "The Cytoscape topology / node-graph canvas — referenced in recipes as `data-viz/topology-graph` but NOT a catalogued component."
+  },
+  "layout": {
+    "appShell": "Every authenticated page sits inside the app shell: the Primary nav (navigation/primary-nav, left, 65px collapsed) + the App header (toolbars/app-header, top, @header-height 55px) come from the layout, not the page. A page renders inside the main content area (--common-main-bg).",
+    "tokens": {
+      "pageBackground": "--page-background-color",
+      "contentBackground": "--common-main-bg",
+      "navWidth": "@nav-icon-width (50px) collapsed / 170px expanded",
+      "headerHeight": "@header-height (55px)",
+      "gutter": "@padding-md (16px)",
+      "sectionPad": "@padding-lg (24px)"
+    }
+  },
+  "recipes": [
+    {
+      "id": "list-view",
+      "name": "List view (CRUD list)",
+      "whenToUse": "A paginated list/grid of records with create/edit, filtering, row + bulk actions (Monitors, Alerts, Users, Policies, most Settings lists).",
+      "examples": [
+        "inventory monitors list",
+        "alert list",
+        "users-settings users list"
+      ],
+      "regions": [
+        {
+          "region": "page-header",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "page-header"
+            }
+          ],
+          "contains": [
+            {
+              "title": "the FlotoPageHeader title (+ optional count via title-append)"
+            },
+            {
+              "search": {
+                "id": "input",
+                "variant": "search"
+              }
+            },
+            {
+              "export": {
+                "id": "button",
+                "variant": "transparent",
+                "icon": "export"
+              }
+            },
+            {
+              "add": {
+                "id": "button",
+                "variant": "primary",
+                "label": "Add <Noun>"
+              }
+            }
+          ]
+        },
+        {
+          "region": "filter (optional, above the grid)",
+          "use": [
+            {
+              "id": "filters",
+              "variant": "filter-bar"
+            }
+          ],
+          "alt": [
+            {
+              "id": "filters",
+              "variant": "expression-builder",
+              "note": "for nested AND/OR query"
+            },
+            {
+              "id": "filters",
+              "variant": "vertical-filter",
+              "note": "a left faceted sidebar instead, for explorer-style lists"
+            }
+          ]
+        },
+        {
+          "region": "table",
+          "use": [
+            {
+              "id": "table",
+              "variant": "selectable"
+            }
+          ],
+          "cells": [
+            {
+              "status": {
+                "id": "tag",
+                "variant": "MStatusTag",
+                "note": "status string -> colour + label"
+              }
+            },
+            {
+              "name": "plain text / link (id: link, variant: text-link)"
+            },
+            {
+              "actions": {
+                "id": "menu",
+                "variant": "context-menu",
+                "note": "the row ⋯ kebab = FlotoGridActions"
+              }
+            }
+          ]
+        },
+        {
+          "region": "bulk actions (conditional)",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "bulk-action-bar"
+            }
+          ],
+          "trigger": "appears when >= minSelection rows are checked"
+        },
+        {
+          "region": "pagination",
+          "use": [
+            {
+              "id": "table",
+              "variant": "pagination"
+            }
+          ]
+        },
+        {
+          "region": "create / edit",
+          "use": [
+            {
+              "id": "drawer",
+              "variant": "FlotoDrawerForm"
+            }
+          ],
+          "contains": "a form (see the form-view recipe) opened from the Add button / a row action"
+        }
+      ],
+      "layout": {
+        "shell": "page-header (top) -> filter (optional) -> table (fills) -> pagination (bottom); drawer slides from the right over all",
+        "tokens": {
+          "rowHover": "--neutral-lighter (do NOT hardcode; the live Kendo grid paints rgba(165,186,208,.4) internally, but emit the token)",
+          "rowSelected": "--neutral-lightest + inset 2px var(--primary)",
+          "headerBg": "--grid-header-bg"
+        }
+      },
+      "gotchas": [
+        "Row actions are the Menu/context-menu (FlotoGridActions) — its prop/event contract is in menu.json apis.ContextMenu; NOT a Dropdown picker.",
+        "Status cell: tag/MStatusTag — the status->colour+label map is in tag.json statusMap.",
+        "Drawer footer: Cancel (mr-2) + Save right; mind the footer-gap (drawer F3).",
+        "The live grid is Kendo + web workers — search/sort/page run there.",
+        "Bulk bar action[] shape + events: toolbars.json apis.BulkActionBar."
+      ],
+      "a11y": [
+        "Grid roles/aria-sort/aria-selected survive custom cells",
+        "bulk bar role=toolbar + aria-label"
+      ]
+    },
+    {
+      "id": "form-view",
+      "name": "Form view (create / edit)",
+      "whenToUse": "A create or edit form for one record (Settings policy/profile forms, Add Monitor, drawer/modal forms).",
+      "examples": [
+        "notification policy form",
+        "monitor template form",
+        "user create/edit"
+      ],
+      "regions": [
+        {
+          "region": "header",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "page-header"
+            }
+          ],
+          "contains": [
+            {
+              "back": {
+                "id": "navigation",
+                "variant": "back-button",
+                "note": "in the page-header back-button slot"
+              }
+            },
+            {
+              "title": "form title"
+            },
+            {
+              "actions": "Save (button/primary) + Cancel (button/default), OR a bottom footer"
+            }
+          ]
+        },
+        {
+          "region": "form body",
+          "use": [
+            {
+              "id": "form-item",
+              "variant": "vertical"
+            }
+          ],
+          "wrap": "FlotoForm + MValidationObserver; each field is a FlotoFormItem with rules",
+          "fields": [
+            {
+              "text": {
+                "id": "input",
+                "variant": "text"
+              }
+            },
+            {
+              "number": {
+                "id": "input",
+                "variant": "number"
+              }
+            },
+            {
+              "textarea": {
+                "id": "form-item",
+                "note": "type=textarea"
+              }
+            },
+            {
+              "single-select": {
+                "id": "dropdown-picker",
+                "variant": "single"
+              }
+            },
+            {
+              "multi-select": {
+                "id": "dropdown-picker",
+                "variant": "multiple"
+              }
+            },
+            {
+              "toggle": {
+                "id": "switch",
+                "note": "for Enabled; product uses Switch even on Save-gated forms"
+              }
+            },
+            {
+              "one-of-few": {
+                "id": "radio",
+                "variant": "list"
+              }
+            },
+            {
+              "tags": {
+                "id": "loose-tags",
+                "variant": "editable"
+              }
+            }
+          ]
+        },
+        {
+          "region": "delete confirm (if editable)",
+          "use": [
+            {
+              "id": "modal",
+              "variant": "FlotoConfirmModal",
+              "note": "variant=error for destructive"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "header -> MRow/MCol grid of FlotoFormItems (size 6 = 50%, 12 = full) -> footer Save/Cancel",
+        "tokens": {
+          "fieldHeight": "@input-height-base (32px)",
+          "gutter": "16 (MRow :gutter)",
+          "labelColour": "--page-text-color",
+          "errorBorder": "--secondary-red"
+        }
+      },
+      "gotchas": [
+        "Wrap EVERY field in FlotoFormItem inside FlotoForm (its api — validate()/@submit/@reset/showNotification — is in form-item.json apis.FlotoForm).",
+        "Put non-text controls (Select/Radio/Switch) in the FlotoFormItem slot.",
+        "`required` goes in the `rules` string, not a prop (form-item F1).",
+        "Input v-model is @update not @input; Switch model is `checked` not `value`.",
+        "Multi-select cap = maxValues, not the dead maxAllowedSelection.",
+        "Select-vs-DropdownPicker: use FlotoDropdownPicker (the product standard), not MSelect."
+      ],
+      "a11y": [
+        "required via aria + asterisk",
+        "error text linked to field",
+        "SF-001 focus ring is removed system-wide"
+      ]
+    },
+    {
+      "id": "detail-view",
+      "name": "Detail view (record detail with tabs)",
+      "whenToUse": "Viewing one record's details across related sections (monitor detail, alert detail, NCM device detail).",
+      "examples": [
+        "monitor detail",
+        "alert detail drawer",
+        "ncm view-detail-drawer"
+      ],
+      "regions": [
+        {
+          "region": "header",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "page-header"
+            }
+          ],
+          "contains": [
+            "back-button",
+            "title + status indicator: MStatusTag (tag) for a STATUS string, OR `severity` (Severity dot) for an alert/monitor SEVERITY level (critical/major/warning/clear — MStatusTag does NOT cover these)",
+            "actions (button + menu/context-menu for ⋯)"
+          ]
+        },
+        {
+          "region": "section nav",
+          "use": [
+            {
+              "id": "tabs",
+              "variant": "line"
+            }
+          ],
+          "note": "Hardware / Metrics / Alerts / Config tabs"
+        },
+        {
+          "region": "section content",
+          "$gap": "If a tab needs a CHART, the chart component is NOT catalogued (only its tooltips) — STOP and ASK. Tables + key-value grids ARE in the DS. See $knownGaps.charts.",
+          "use": [
+            {
+              "id": "table",
+              "variant": "basic"
+            },
+            {
+              "id": "data-viz-tooltips",
+              "note": "chart tooltips only — the chart body itself is the $gap"
+            }
+          ],
+          "note": "per-tab: tables, charts, key-value grids"
+        },
+        {
+          "region": "edit",
+          "use": [
+            {
+              "id": "drawer",
+              "variant": "FlotoDrawerForm"
+            },
+            {
+              "id": "modal",
+              "variant": "MModal"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "header -> tabs -> active tab content; OR the whole detail in a Drawer (ncm view-detail-drawer = Drawer + Tabs)",
+        "tokens": {
+          "tabActive": "--primary + ink bar",
+          "sectionPad": "@padding-lg (24px)"
+        }
+      },
+      "gotchas": [
+        "Tabs-in-a-Drawer is a real pattern (Drawer + Tabs), not a new component.",
+        "Status next to title = MStatusTag."
+      ],
+      "a11y": [
+        "tablist/tab/tabpanel roles",
+        "aria-current on active tab"
+      ]
+    },
+    {
+      "id": "dashboard-view",
+      "name": "Dashboard view",
+      "whenToUse": "A grid of widgets/charts for a monitoring overview, with a dashboard picker and a global time range.",
+      "examples": [
+        "dashboard module",
+        "NOC view"
+      ],
+      "regions": [
+        {
+          "region": "dashboard picker (left)",
+          "use": [
+            {
+              "id": "navigation",
+              "variant": "side-menu-categories",
+              "note": "Dashboard/NOC tabs + categories + counts (dashboard-dropdown)"
+            }
+          ]
+        },
+        {
+          "region": "global time range",
+          "use": [
+            {
+              "id": "date-time-pickers",
+              "variant": "TimeRangePicker"
+            }
+          ]
+        },
+        {
+          "region": "widgets",
+          "$gap": "The widget CHART/tile itself is NOT catalogued (only its tooltips are) — STOP and ASK before implementing the chart. The widget chrome (toolbars/widget-header) + tooltips ARE in the DS. See $knownGaps.charts.",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "widget-header",
+              "note": "title + time pill + ⋯ kebab per widget"
+            },
+            {
+              "id": "data-viz-tooltips",
+              "note": "the chart tooltips (the chart body itself is the $gap)"
+            }
+          ],
+          "note": "a GridLayout of widget cards (--common-widget-bg)"
+        },
+        {
+          "region": "widget actions",
+          "use": [
+            {
+              "id": "menu",
+              "variant": "context-menu",
+              "note": "Edit/Clone/Full Screen/Share/Export via FlotoGridActions"
+            }
+          ]
+        },
+        {
+          "region": "wallboard mode (optional)",
+          "use": [
+            {
+              "id": "navigation",
+              "variant": "noc-player"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "left dashboard picker (size 3) + main widget grid (size 9); time range top-right",
+        "tokens": {
+          "widgetBg": "--common-widget-bg",
+          "canvasBg": "--dashboard-background"
+        }
+      },
+      "gotchas": [
+        "Widget chrome = toolbars/widget-header; its kebab = Menu/context-menu.",
+        "Chart tooltips are owned by the chart layer (data-viz-tooltips), not MTooltip."
+      ],
+      "a11y": [
+        "NOC rotator must be pausable + respect reduced-motion"
+      ]
+    },
+    {
+      "id": "explorer-view",
+      "name": "Explorer view (left panel + results + time range)",
+      "whenToUse": "An explorer that browses a tree/saved-views/facets on the left and shows results (grid/chart) on the right (Log, Metric, APM, RUM, NCM explorers).",
+      "examples": [
+        "log explorer",
+        "metric explorer",
+        "apm explorer",
+        "ncm explorer"
+      ],
+      "regions": [
+        {
+          "region": "left panel",
+          "use": [
+            {
+              "id": "navigation",
+              "variant": "side-menu-tree",
+              "note": "Log/Topology hierarchy"
+            }
+          ],
+          "alt": [
+            {
+              "id": "navigation",
+              "variant": "metric-picker",
+              "note": "Metric Explorer ⊕-add + drag (a picker)"
+            },
+            {
+              "id": "filters",
+              "variant": "vertical-filter",
+              "note": "APM/RUM/NCM faceted checkbox sidebar"
+            },
+            {
+              "id": "navigation",
+              "variant": "side-menu-list",
+              "note": "saved-views list (APM/RUM)"
+            }
+          ]
+        },
+        {
+          "region": "toolbar",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "grid-toolbar"
+            }
+          ],
+          "contains": [
+            "search (input/search)",
+            "filter",
+            "time range (date-time-pickers/TimeRangePicker)"
+          ]
+        },
+        {
+          "region": "results",
+          "$gap": "If results render as a CHART, the chart component is NOT catalogued (only its tooltips) — STOP and ASK. The table result IS in the DS. See $knownGaps.charts.",
+          "use": [
+            {
+              "id": "table",
+              "variant": "basic"
+            },
+            {
+              "id": "data-viz-tooltips",
+              "note": "chart tooltips only — the chart body itself is the $gap"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "left panel (size 2-3, class left-side-list-view-panel) + results (fills)",
+        "tokens": {
+          "panelBorder": "--border-color",
+          "countBadge": "--code-tag-background-color"
+        }
+      },
+      "gotchas": [
+        "Pick the right left-panel: tree (nav) vs faceted filter (Filters/vertical-filter) vs picker (navigation/metric-picker) vs saved-views (nav/side-menu-list) — they LOOK alike but differ in archetype.",
+        "The faceted checkbox sidebar FILTERS (Filters), it does not navigate."
+      ]
+    },
+    {
+      "id": "wizard-flow",
+      "name": "Multi-step create / setup flow",
+      "whenToUse": "An ordered, multi-step create or onboarding flow (report builder, product setup, 2FA).",
+      "examples": [
+        "report builder",
+        "product setup guide",
+        "two-factor setup"
+      ],
+      "regions": [
+        {
+          "region": "stepper",
+          "use": [
+            {
+              "id": "navigation",
+              "variant": "steps",
+              "note": "bespoke — report (horizontal) / setup-guide (vertical) / 2FA"
+            }
+          ]
+        },
+        {
+          "region": "step body",
+          "use": [
+            {
+              "id": "form-item",
+              "variant": "vertical"
+            }
+          ],
+          "note": "the form-view fields for the current step"
+        },
+        {
+          "region": "footer",
+          "use": [
+            {
+              "id": "button",
+              "variant": "primary",
+              "label": "Next/Finish"
+            },
+            {
+              "id": "button",
+              "variant": "default",
+              "label": "Back"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "stepper (top or left) -> current step content -> Back/Next footer",
+        "tokens": {
+          "stepDone": "--primary + ✓",
+          "stepCurrent": "--primary + ring",
+          "stepRemaining": "--neutral-lightest"
+        }
+      },
+      "gotchas": [
+        "No MSteps in the product — steppers are bespoke (report-steps / guide-section-step / 2FA).",
+        "Validate the current step before advancing."
+      ]
+    },
+    {
+      "id": "graph-canvas",
+      "name": "Graph / Canvas view (tree + interactive node graph)",
+      "whenToUse": "Relationships/topology matter more than rows or tiles — an interactive node graph the user pans, zooms and rearranges (Topology). Neither a Dashboard nor an Explorer.",
+      "examples": [
+        "topology map"
+      ],
+      "regions": [
+        {
+          "region": "left panel",
+          "use": [
+            {
+              "id": "navigation",
+              "variant": "side-menu-tree",
+              "note": "hierarchy tree"
+            }
+          ]
+        },
+        {
+          "region": "canvas",
+          "$gap": "NOT IN DS YET — the Cytoscape topology graph is not a catalogued component (`data-viz/topology-graph` is a placeholder id with no registry). STOP and ASK before implementing the canvas. See $knownGaps.topologyGraph.",
+          "use": [
+            {
+              "id": "data-viz",
+              "variant": "topology-graph",
+              "note": "Cytoscape: pan/zoom, node-drag (saved positions), Full-View vs Tree-View, keyboard nav — describes the product behaviour; no DS component exists for it yet"
+            }
+          ],
+          "contains": [
+            "minimap (cytoscape-navigator)",
+            "zoom / fit controls"
+          ]
+        },
+        {
+          "region": "node state",
+          "use": [
+            {
+              "id": "severity",
+              "variant": "dot",
+              "note": "node colour by severity level"
+            },
+            {
+              "id": "tag",
+              "variant": "status",
+              "note": "status string"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "two-pane: hierarchy tree (size 2-3) + Cytoscape canvas (fills) inside Layout",
+        "tokens": {
+          "canvasBg": "--common-main-bg",
+          "nodeColour": "--severity-<level>",
+          "edge": "--border-color"
+        }
+      },
+      "gotchas": [
+        "Persist node positions per target + view mode.",
+        "Severity colour alone isn't accessible — keep tooltips/labels.",
+        "Heavy graph layout runs in a web worker (D3 force)."
+      ]
+    },
+    {
+      "id": "bulk-action-flow",
+      "name": "Bulk action (multi-select → act on many)",
+      "whenToUse": "Act on multiple list rows at once (delete, sync, enable/disable, export).",
+      "examples": [
+        "inventory bulk ops",
+        "alert bulk suppress",
+        "ncm bulk backup/sync"
+      ],
+      "regions": [
+        {
+          "region": "select",
+          "use": [
+            {
+              "id": "table",
+              "variant": "selectable",
+              "note": "row checkboxes + header select-all"
+            }
+          ]
+        },
+        {
+          "region": "action bar",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "bulk-action-bar",
+              "note": "fixed-bottom; appears on selection; shows count + actions"
+            }
+          ]
+        },
+        {
+          "region": "confirm (destructive)",
+          "use": [
+            {
+              "id": "modal",
+              "variant": "FlotoConfirmModal",
+              "note": "variant=error for bulk delete"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "list view + a fixed bottom bar that animates in on selection",
+        "tokens": {
+          "bar": "--primary",
+          "barText": "--white-regular"
+        }
+      },
+      "gotchas": [
+        "Announce the bar's appearance to AT (role=toolbar).",
+        "Clear the selection after the action.",
+        "Hide/disable actions the user lacks permission for."
+      ]
+    },
+    {
+      "id": "inline-edit-flow",
+      "name": "Inline edit (edit a row/cell in place)",
+      "whenToUse": "Quick edits to a table row without opening a form or drawer.",
+      "examples": [
+        "metric-collection tables",
+        "mapping tables (flow/log settings)"
+      ],
+      "regions": [
+        {
+          "region": "trigger",
+          "use": [
+            {
+              "id": "table",
+              "variant": "inline-editing",
+              "note": "click a cell / row edit icon → the cell becomes a control"
+            }
+          ]
+        },
+        {
+          "region": "controls",
+          "use": [
+            {
+              "id": "input"
+            },
+            {
+              "id": "select"
+            },
+            {
+              "id": "dropdown-picker"
+            }
+          ]
+        },
+        {
+          "region": "commit",
+          "use": [
+            {
+              "id": "button",
+              "variant": "icon-circle",
+              "note": "save (✓) / cancel (×) per row"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "the row swaps display cells for inline controls",
+        "tokens": {
+          "editingRow": "--neutral-lightest"
+        }
+      },
+      "gotchas": [
+        "Validate inline (error on the cell).",
+        "Esc cancels, Enter commits.",
+        "Keep focus within the editing row."
+      ]
+    },
+    {
+      "id": "search-filter-flow",
+      "name": "Search & filter a list",
+      "whenToUse": "Narrow a list by free-text search + structured filters.",
+      "examples": [
+        "every list view",
+        "log / metric explorers",
+        "ncm explorer"
+      ],
+      "regions": [
+        {
+          "region": "search",
+          "use": [
+            {
+              "id": "input",
+              "variant": "search",
+              "note": "debounced free-text"
+            }
+          ]
+        },
+        {
+          "region": "filters",
+          "use": [
+            {
+              "id": "filters",
+              "variant": "filter-bar",
+              "note": "field/operator/value conditions, groups, Apply/Reset"
+            }
+          ],
+          "alt": [
+            {
+              "id": "toolbars",
+              "variant": "grid-toolbar",
+              "note": "quick filters + column chooser"
+            }
+          ]
+        },
+        {
+          "region": "results",
+          "use": [
+            {
+              "id": "table"
+            }
+          ],
+          "contains": [
+            "empty state (MNoData) when nothing matches"
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "toolbar (search + filters) above the table",
+        "tokens": {}
+      },
+      "gotchas": [
+        "Always show a no-results/empty state.",
+        "Reflect active filters as removable chips.",
+        "Persist filters where useful."
+      ]
+    },
+    {
+      "id": "export-flow",
+      "name": "Export a list / report (PDF / CSV)",
+      "whenToUse": "Download the current grid or render a report.",
+      "examples": [
+        "inventory / alerts / audit grids (exportGrid)",
+        "report render (EmptyLayout)"
+      ],
+      "regions": [
+        {
+          "region": "trigger",
+          "use": [
+            {
+              "id": "toolbars",
+              "variant": "page-header",
+              "note": "export button (transparent + export icon)"
+            }
+          ],
+          "alt": [
+            {
+              "id": "menu",
+              "variant": "context-menu",
+              "note": "format dropdown: PDF / CSV"
+            }
+          ]
+        },
+        {
+          "region": "output",
+          "use": [
+            {
+              "id": "table",
+              "note": "exportGrid(columns, items, 'pdf'|'csv'); honour per-column exportType"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "export action in the page header; the print-safe report render uses the EmptyLayout shell",
+        "tokens": {}
+      },
+      "gotchas": [
+        "Respect column exportType (datetime/duration).",
+        "Large exports → progress / async.",
+        "Print/PDF render via EmptyLayout (no chrome)."
+      ]
+    },
+    {
+      "id": "confirm-delete-flow",
+      "name": "Confirm a destructive action",
+      "whenToUse": "Any delete / irreversible action triggered from a row, detail, or bulk bar.",
+      "examples": [
+        "delete monitor",
+        "remove user",
+        "bulk delete"
+      ],
+      "regions": [
+        {
+          "region": "trigger",
+          "use": [
+            {
+              "id": "menu",
+              "variant": "context-menu",
+              "note": "row ⋯ Delete (danger=red)"
+            },
+            {
+              "id": "toolbars",
+              "variant": "bulk-action-bar",
+              "note": "bulk Delete"
+            }
+          ]
+        },
+        {
+          "region": "confirm",
+          "use": [
+            {
+              "id": "modal",
+              "variant": "FlotoConfirmModal",
+              "note": "variant=error; name the verb (Delete), not Yes/OK"
+            }
+          ]
+        }
+      ],
+      "layout": {
+        "shell": "trigger opens FlotoConfirmModal(error) centered over a dimmed/blurred backdrop",
+        "tokens": {
+          "danger": "--secondary-red",
+          "backdrop": "blur(3px)"
+        }
+      },
+      "gotchas": [
+        "Use variant=error + a named verb button (Delete), never 'Yes'/'OK'.",
+        "Danger actions in menus use --secondary-red + an icon (not colour-only)."
+      ]
+    }
+  ]
+}