@mtdt/observeops-ds-spec 0.1.3 → 0.1.5

package/AGENTS.md

@@ -106,3 +106,6 @@ block is the contract violation; composing DS parts into an undocumented screen
 - [ ] The page is composed from a recipe + the right layout shell/regions.
 - [ ] a11y honoured (labels, keyboard, aria).
 - [ ] Any deviation was **asked**, not guessed.
+- [ ] **Verified the RENDER**, not just the rules — run the conformance checker
+  (`conformance/ds-conformance.mjs <page>` in the spec package, or the MCP `validate_render`); fix every
+  off-token colour (brand must be navy, not blue/cyan), off-scale spacing, and `mds-*`. Aim for ≥ 90.

package/components/index.json

@@ -27,15 +27,15 @@
     "$note": "The structural layer — the 12-col grid (MRow/MCol) + app shell, layout shells, screen regions & panel behaviours (layout/layouts.json; Storybook: Foundations/Layout/*). foundation/*.md = a page-by-page PRODUCT coverage sweep per element (which pages/flows use each variant + findings + best practices)."
   },
   "counts": {
-    "components": 26,
-    "families": 15,
+    "components": 27,
+    "families": 16,
     "coverage": {
-      "props": 19,
+      "props": 20,
       "apis": 8,
-      "states": 26,
+      "states": 27,
       "sizes": 8,
-      "variants": 23,
-      "a11y": 26
+      "variants": 24,
+      "a11y": 27
     }
   },
   "families": {
@@ -45,6 +45,9 @@
     "Date & Time Pickers": [
       "date-time-pickers"
     ],
+    "Divider": [
+      "divider"
+    ],
     "Filters": [
       "filters"
     ],
@@ -315,6 +318,45 @@
         "a11y": true
       }
     },
+    {
+      "id": "divider",
+      "display": "Divider",
+      "tier": "atom",
+      "family": "Divider",
+      "category": null,
+      "status": "core",
+      "summary": "A thin rule that marks a semantic break — horizontal between stacked sections, vertical between inline items.",
+      "selectHint": "Separate sections (horizontal) or inline items (vertical). If you only need space, use margin, not a divider.",
+      "variants": [
+        "horizontal",
+        "vertical",
+        "dashed",
+        "with-text",
+        "darkVariant"
+      ],
+      "registry": "components/registry/divider.json",
+      "spec": "components/specs/divider.md",
+      "storybook": "Atoms/Divider",
+      "related": [
+        "table",
+        "toolbars",
+        "form-item"
+      ],
+      "knownIssueCount": 1,
+      "tokenCount": 5,
+      "has": {
+        "props": true,
+        "states": true,
+        "sizes": false,
+        "variants": true,
+        "decisionFlow": true,
+        "do": true,
+        "dont": true,
+        "tokensUsed": true,
+        "apis": false,
+        "a11y": true
+      }
+    },
     {
       "id": "drawer",
       "display": "Drawer",

package/components/registry/button.json

@@ -347,7 +347,13 @@
   "changelog": [
     "2026-06-05: added; variants corrected to distinct set + primary-alt; navy-fallback flagged (F1); light/dark verified.",
     "2026-06-06: enhanced doc standard — anatomy/behaviors/content/accessibility (F3/F4/F5), related, changelog.",
-    "2026-06-07: thorough button audit — added icon buttons (shape=circle 218x + squared-button 365x) story + section; findings F6 (inverted shadow) + F7 (circle not circular); noted FlotoLink + segmented-control relatives."
+    "2026-06-07: thorough button audit — added icon buttons (shape=circle 218x + squared-button 365x) story + section; findings F6 (inverted shadow) + F7 (circle not circular); noted FlotoLink + segmented-control relatives.",
+    "2026-06-30: fixed the `block` (full-width) modifier — the custom-element host defaulted to inline so width:100% had nothing to fill; added :host([block]){display:block;width:100%} (+ the showcase stage now expands for any [block] element). Block buttons now span their container.",
+    "2026-07-01: fixed font-weight 500→400 (owner) — the product/Storybook button is Ant's default 400 (@btn-font-weight override is commented out; no LESS sets a weight). Button had never been diff-gated, so the wrong weight was never caught.",
+    "2026-07-01: fixed the large size (owner) — it was inheriting the default 0.8rem font. The product large button keeps the DEFAULT height/padding but bumps the font to --font-size-lg (1rem) (@font-size-lg: @text-regular; @btn-font-size-lg: @font-size-lg) — bigger text, same box height. .s-large now sets font-size: var(--font-size-lg, 1rem).",
+    "2026-07-01: built specs/button.spec.mjs and diff-gated the button for the first time (13 scenarios, light+dark) — the gate caught the small-button padding (12px→7px, now Ant's 7px) and confirms weight 400 / radius 4px / Poppins / large-1rem. Two intentional divergences declared: ghost (navy vs Ant dark-bg white) and primary-hover (DS token 0.7 vs product render 0.89).",
+    "2026-07-01: added the icon+text button example (owner asked) — the product has 83× leading-icon+label buttons (MIcon in the slot) and 538× icon-only (circle/squared). obs-button already supports both via the default slot (.btn is inline-flex gap:6px); showcased both in the Elements gallery. Note: the Storybook button story only shows icon-ONLY.",
+    "2026-07-01: replaced the placeholder button-example icons with the REAL product icons (from src/assets/icons/icons.js); also added a dedicated Icons page (542 Font Awesome Light glyphs) with search + copy SVG/PNG + download."
   ],
   "storybook": "Atoms/Button",
   "figma": {
@@ -365,4 +371,4 @@
   "slots": {
     "default": "button label / content (text and/or an icon)"
   }
-}
+}

package/components/registry/data-viz-tooltips.json

@@ -5,6 +5,18 @@
   "family": "Popover & Tooltip",
   "status": "stable",
   "summary": "The product's chart & widget hover tooltips — a distinct family from MTooltip, owned by the chart layer (Highcharts TooltipBuilder, graph canvases, widget Vue components), not DS components. ~28 reference reproductions cover every mechanism.",
+  "props": {
+    "kind": {
+      "type": "string",
+      "default": "bar",
+      "description": "which chart/widget or live-graph tooltip to reproduce (28 kinds — bar, donut, heatmap, …, graph-node, graph-edge, …)"
+    },
+    "block": {
+      "type": "boolean",
+      "default": false,
+      "description": "stretch the card to its container width instead of its intrinsic per-kind width (preview how a tooltip fills a wide surface)"
+    }
+  },
   "variants": [
     {
       "name": "bar-series",
@@ -405,5 +417,9 @@
     ],
     "doc": "Molecules/Data-Viz Tooltips/Accessibility",
     "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
-  }
-}
+  },
+  "changelog": [
+    "2026-06-29: added to the Elements site — obs-dataviz-tooltip: all 28 chart/widget + live-graph tooltip reference reproductions (kind prop), real tokens (--chart-tooltip-background, --topology-graph-tooltip-bg, --severity-*).",
+    "2026-06-30: added a `block` prop (Full width) — the card stretches to its container instead of its intrinsic per-kind width; exposed as a Playground toggle + a Full-width Examples group, and documented kind/block in Details."
+  ]
+}

package/components/registry/date-time-pickers.json

@@ -5,6 +5,38 @@
   "family": "Date & Time Pickers",
   "status": "stable",
   "summary": "The product's date/time selection family. The hero is TimeRangePicker (42×) — the observability time-range control (relative presets + absolute custom range). MDatePicker (10×, wraps a-date-picker) is the form date-time field, in practice ALWAYS used with show-time. MTimePicker wraps a-time-picker (12-hour) but is rarely used standalone. DateTimePopover is a lighter custom-range-only popover.",
+  "props": {
+    "kind": {
+      "type": "string",
+      "default": "range",
+      "description": "which family member to render — range (the 42× hero TimeRangePicker), range-presets (hide-custom, 24×), field-datetime / field-date / field-time (MDatePicker/MTimePicker fields), slider (TimeRangeSlider scrubber)"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false,
+      "description": "non-interactive (greyed field / inert trigger)"
+    },
+    "bordered": {
+      "type": "boolean",
+      "default": false,
+      "description": "range trigger gets a --border-color frame (1×)"
+    },
+    "allowClear": {
+      "type": "boolean",
+      "default": false,
+      "description": "attr allow-clear — a times-circle × on the range pill that resets the selection (7×)"
+    },
+    "empty": {
+      "type": "boolean",
+      "default": false,
+      "description": "start with no selection — shows the calendar icon + “Select Time” placeholder"
+    },
+    "placeholder": {
+      "type": "string",
+      "default": "",
+      "description": "field placeholder text (defaults per kind)"
+    }
+  },
   "variants": [
     {
       "name": "TimeRangePicker",
@@ -292,5 +324,12 @@
     ],
     "doc": "Molecules/Date & Time Pickers/Accessibility",
     "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
-  }
-}
+  },
+  "changelog": [
+    "2026-06-30: added to the Elements site — obs-date-time-picker, the date/time family as one element via a `kind` prop: range (the 42× TimeRangePicker hero — interactive pill → presets → Custom dual-month calendar with From/To time menus), range-presets (hide-custom 24×), field-datetime/field-date/field-time (MDatePicker/MTimePicker fields + disabled), slider (draggable TimeRangeSlider). Reference reproductions with real tokens (--timerange-*, --calendar-selected-day-background-color, --slider-tracker, --dropdown-*); gated by cross-render token check (light+dark) + driven open/custom/disabled states.",
+    "2026-06-30: made the MDatePicker/MTimePicker FIELD kinds interactive (owner caught they were static, non-functional) — field-date/field-datetime open a single-month calendar (today ringed, allow-clear ×), field-datetime adds a 12h time field, field-time opens a 12h time menu; reset popups on kind-change. Playground fixes: slider now fills the stage width; tall picker panels no longer clip (stage top-aligns + overflow visible + min-height).",
+    "2026-06-30: reworked the MDatePicker/MTimePicker field popovers to match the real Ant render (owner compared to Storybook) — a connected card with the value input on top, the calendar (today navy-filled), a footer (Now · select time/select date · Ok), and a proper 3-COLUMN time spinner (HH · MM · AM/PM, selected row banded + scrolled to top) instead of a flat time dropdown. field-date = Now·Ok, field-time = the spinner alone.",
+    "2026-06-30: matched the per-variant footer pattern (owner) — date-only shows a single centered \"Today\" link (not Now·Ok); time-only keeps Now·Ok; date-time keeps Now·select-time/date·Ok with the time spinner opening in the same popover.",
+    "2026-06-30: fixed field-calendar day states (owner) — selected (filled navy) and today (navy RING) were rendering identically; now distinct, plus a hover background on days. Applies to field-date and field-datetime (refactored day cells from inline styles to CSS classes so :hover works)."
+  ]
+}

package/components/registry/divider.json

@@ -0,0 +1,106 @@
+{
+  "name": "divider",
+  "component": "MDivider",
+  "display": "Divider",
+  "tier": "atom",
+  "family": "Divider",
+  "source": "mkit",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "A thin rule that marks a semantic break between content — horizontal between stacked sections, vertical between inline items.",
+  "selectHint": "Use to separate sections (horizontal) or inline items (vertical). If you only need space, use margin instead.",
+  "whenToUse": "A real boundary between two groups of content — not merely spacing.",
+  "insteadOf": ["a hardcoded 1px border div", "extra margin used as a fake separator"],
+  "variants": [
+    { "name": "horizontal", "what": "Full-width rule between stacked sections (default).", "usage": "126×" },
+    { "name": "vertical", "what": "Inline separator between items in a row (type=\"vertical\").", "usage": "7×" },
+    { "name": "dashed", "what": "Dashed prop — but renders SOLID (no-op, F1) due to the DS background override.", "usage": "0× (kit-supported; no visible effect — F1)" },
+    { "name": "with-text", "what": "Labelled section rule (slot text + orientation).", "usage": "0× (kit-supported, unused)" },
+    { "name": "darkVariant", "what": "Tuned for a dark background.", "usage": "rare" }
+  ],
+  "sizes": [
+    { "name": "default", "value": "1px", "note": "1px hairline; not size-configurable." }
+  ],
+  "states": [
+    { "name": "default", "what": "Static decorative rule; no interactive states." }
+  ],
+  "props": {
+    "type": { "type": "string", "default": "horizontal", "enum": ["horizontal", "vertical"], "note": "Vertical is an inline separator." },
+    "dashed": { "type": "boolean", "default": false, "note": "Dashed instead of solid." },
+    "orientation": { "type": "string", "default": "", "enum": ["", "start", "end"], "note": "Label position when a with-text divider is used (default center); start→left, end→right." },
+    "darkVariant": { "type": "boolean", "default": false, "note": "Tuned for a dark background." }
+  },
+  "events": [],
+  "slots": { "default": "Optional label text — renders a with-text divider." },
+  "decisionFlow": [
+    "Just want space between elements (no real boundary)? -> use margin/spacing, NOT a divider (don't overuse dividers).",
+    "Separating items sitting in a row (inline metadata, toolbar actions, compare columns)? -> type=\"vertical\".",
+    "Does the section below need a label (a titled group)? -> a with-text divider (slot text + orientation).",
+    "Otherwise separating stacked blocks/sections? -> the default horizontal rule.",
+    "Modifiers: darkVariant = tuned for a dark background. (dashed is a no-op today, F1 — it renders solid.)"
+  ],
+  "usageRules": {
+    "horizontal": {
+      "useWhen": "two vertically-stacked groups need a clear boundary — form sections, card regions, header above body",
+      "dontUse": "you only need spacing (use margin), or the groups are already separate cards",
+      "example": "the rule between Connection details and Advanced options in a settings form",
+      "asSeenIn": "settings log-parser forms, NCM device-template-form, integration lama-profile-form"
+    },
+    "vertical": {
+      "useWhen": "items sit in a row and need a light separator — inline metadata, compare columns, a small action group",
+      "dontUse": "the items are stacked (use horizontal), or a gap reads clearly enough",
+      "example": "separating status · version · updated-time on one line",
+      "asSeenIn": "NCM backup-compare-form / device-policy-breakdown, alert ncm-compare-diff, flow-analytics-card"
+    },
+    "dashed": {
+      "useWhen": "don't rely on it today — the dashed prop renders SOLID (F1)",
+      "dontUse": "any case needing a visible dashed line, until F1 is fixed",
+      "example": "no visible effect: the DS .ant-divider background override paints over Ant's dashed border"
+    },
+    "with-text": {
+      "useWhen": "the rule also titles the group below it and a full heading is too heavy",
+      "dontUse": "the section already has a heading (the label would duplicate it)",
+      "example": "supported; not currently used in the product. orientation=start|end moves the label"
+    },
+    "darkVariant": {
+      "useWhen": "the divider sits on a dark background and the default line is too faint",
+      "dontUse": "on the normal page surface (the default already resolves per theme)",
+      "example": "a divider inside a dark-surfaced panel"
+    }
+  },
+  "usage": {
+    "total": 133,
+    "files": 93,
+    "byType": { "horizontal": 126, "vertical": 7 },
+    "byModule": { "settings": 31, "components (shared)": 14, "alert": 10, "ncm-approval": 6, "ncm": 6, "topology": 5, "apm": 4 },
+    "note": "byType is exact from the sweep (type=\"vertical\" appears 7×; the rest default to horizontal). dashed and with-text/orientation have zero product uses."
+  },
+  "do": [
+    "Use one rule per boundary — never stack two dividers.",
+    "Try whitespace/margin first; a divider is a semantic break, not a spacer.",
+    "Let the line inherit the theme (var(--border-color)); don't hardcode a colour.",
+    "Use type=\"vertical\" for inline separators, horizontal for stacked sections."
+  ],
+  "dont": [
+    "Don't use a divider just to add space (use margin).",
+    "Don't stack dividers or box every section — it reads noisy.",
+    "Don't rely on a divider alone to communicate meaning (pair it with text/state)."
+  ],
+  "a11y": {
+    "summary": "Decorative separator — Ant renders role=\"separator\"; conveys a thematic break without interactive noise.",
+    "issues": [],
+    "doc": "Atoms/Divider/Accessibility",
+    "notes": "A rule is a visual break, not a landmark/heading — give navigable sections a real heading. Line is a low-contrast hairline by design; never rely on it alone to convey meaning."
+  },
+  "knownIssues": [
+    "F1 (low): `dashed` renders SOLID — no visible effect. The DS override `.ant-divider { background: var(--border-color) }` (general.less:213, form.less:448) paints a solid 1px line over Ant's dashed `border-top`, so `:dashed=\"true\"` does nothing. Verified by computed style: dashed element has borderTopStyle=dashed AND background=--border-color on a 1px-high box → the solid fill wins. Fix: drop the background fill so the dashed border shows, or paint a dashed line explicitly. 0× product use."
+  ],
+  "tokensUsed": ["--border-color", "--page-text-color", "--neutral-lightest", "--action-dropdown-divider", "--nav-divider-bg"],
+  "related": ["table", "toolbars", "form-item"],
+  "changelog": [
+    "2026-07-04 — Added to the DS (first catalogue). Swept 133×/93 files: 126 horizontal + 7 vertical; with-text kit-supported but unused. Base line verified as background: var(--border-color) (light + dark). Decision-grade Usage authored + mirrored here.",
+    "2026-07-04 — F1 (owner-caught): `dashed` is a no-op — it renders solid because the DS `.ant-divider { background: var(--border-color) }` override paints over Ant's dashed border. Flagged in the Dashed story + Usage + here; measured by computed style."
+  ],
+  "storybook": "Atoms/Divider",
+  "figma": { "status": "not-started", "component": "Divider" }
+}

package/components/registry/filters.json

@@ -51,7 +51,13 @@
       "what": "not interactive"
     }
   ],
-  "props": "Filters is MULTI-ARCHETYPE — there is no single component prop list. Per-archetype prop/event contracts are in `apis` (e.g. apis.FilterBar = value/fieldSchema/defaultChips + change) and the `archetypes` block.",
+  "props": {
+    "kind": {
+      "type": "string",
+      "default": "bar",
+      "description": "which filter archetype to render — bar (FlotoFilterBar ~50×), expression (FiltersContainer 32×), quick (preset menu), row (multi-selects + Reset/Apply), vertical (faceted sidebar). Filters is MULTI-ARCHETYPE: per-archetype prop/event contracts live in the apis block below, not as element props."
+    }
+  },
   "renders": "REFERENCE REPRODUCTIONS — the live filters are store-bound (FilterCondition is 500+ lines). The Filter bar reproduction is fully interactive.",
   "archetypes": {
     "ExpressionBuilder": {
@@ -151,5 +157,11 @@
     ],
     "doc": "Molecules/Filters/Accessibility",
     "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
-  }
-}
+  },
+  "changelog": [
+    "2026-07-01: added to the Elements site — obs-filters, the filtering family as one element via a `kind` prop: bar (FlotoFilterBar ~50× — interactive field·operator·value chips + Match All/Any + Clear All), expression (FiltersContainer 32× — nested AND/OR query builder popover with Pre/Post tabs, groups, conditions, Reset/Clear/Apply), quick (preset menu), row (multi-selects + Reset/Apply), vertical (faceted sidebar — search + collapsible checkbox+count groups). Reference reproductions with real tokens; gated by cross-render token check (light+dark) + driven chip/expression/vertical interaction.",
+    "2026-07-01: made the row variant full-width (owner) — it was shrink-wrapping to a narrow box; now the host is block width:100% (like bar) and .frow fills the container in both the playground and examples.",
+    "2026-07-01: fixed buttons to match the product Button (border-radius 6px→4px via --btn-radius, primary weight 600→500) and added a native-control font-family reset — the <select>/<input> were rendering in the UA font (Arial), now Poppins.",
+    "2026-07-01: button font-weight 500→400 to match the real product Button (Ant default 400)."
+  ]
+}

package/components/registry/layout-app-shell.json

@@ -0,0 +1,84 @@
+{
+  "name": "layout-app-shell",
+  "component": "Layout (views/layouts/main.vue)",
+  "display": "App shell",
+  "tier": "foundation",
+  "section": "Foundations",
+  "family": "Layout",
+  "status": "stable",
+  "summary": "The authenticated app frame — NavBar (left rail, 50px, --nav-panel-bg) + Header (top, 55px) + the one scrolling content panel + a shell-level overlay layer (toasts, OmniBox, portals). The default shell for every in-app page. Toggle the chrome to see how the other shells (EmptyLayout, LoginLayout) drop regions.",
+  "props": {
+    "sidebar": {
+      "type": "boolean",
+      "default": "false",
+      "note": "show the left NavBar rail"
+    },
+    "header": {
+      "type": "boolean",
+      "default": "false",
+      "note": "show the top Header"
+    },
+    "overlay": {
+      "type": "boolean",
+      "default": "false",
+      "note": "show the shell-level overlay (a toast)"
+    },
+    "empty": {
+      "type": "boolean",
+      "default": "false",
+      "note": "swap the page body for an empty-state prompt"
+    },
+    "anatomy": {
+      "type": "boolean",
+      "default": "false",
+      "note": "render the annotated region-callout diagram instead of the interactive shell"
+    }
+  },
+  "regions": [
+    "NavBar — left rail, @nav-icon-width 50px, --nav-panel-bg; the module icons (active = --primary pill)",
+    "Header — top, @header-height 55px; brand logo · global search · notifications · user menu",
+    "Content panel — MLayoutContent in FlotoScrollView; the routed page slot, the only scrolling region",
+    "Overlay layer — OmniBox, notifications, PortalTargets; shell-level, above the content"
+  ],
+  "do": [
+    "Use the Layout shell for every authenticated app page (the default — no route override needed).",
+    "Keep the content panel the only scrolling region.",
+    "Mount global/portal UI (toasts, OmniBox) at the overlay layer, above the content."
+  ],
+  "dont": [
+    "Don't put the breadcrumb/back in the Header — that lives in the page header.",
+    "Don't add a second scrolling container inside the content panel."
+  ],
+  "tokensUsed": [
+    "--nav-panel-bg",
+    "--border-color",
+    "--page-background-color",
+    "--primary",
+    "--code-tag-background-color",
+    "--secondary-green"
+  ],
+  "related": [
+    "layout-screen-regions",
+    "layout-grid"
+  ],
+  "storybook": "Foundations/Layout/App shell",
+  "a11y": {
+    "summary": "Structural reference, not interactive. In the product the regions map to landmarks — NavBar = <nav>, Header = <header>, content = <main>; the content panel is the only scroll container, so focus order is nav → header → content.",
+    "issues": [
+      "The overlay layer (toasts/OmniBox) must manage focus + ESC at the product level."
+    ]
+  },
+  "knownIssues": [
+    "Documentation diagram, not the live shell — the product Layout (src/views/layouts/main.vue) is the source of truth."
+  ],
+  "changelog": [
+    "2026-06-29: added to the Elements site (Foundations › Layout) — Anatomy diagram + interactive chrome toggles; render-first from the Storybook story.",
+    "2026-06-29: playground + examples widths fixed to fill the stage.",
+    "2026-06-29: Usage enriched — when-to-use + where-it's-used."
+  ],
+  "whenToUse": "Every signed-in page renders into this frame — you don't opt in. Switch to another shell only for login, print/export, or system pages.",
+  "usedIn": [
+    "Every authenticated in-app page — the default for ~all routes.",
+    "Drop the chrome via a different shell: login, report export, upgrade/restore."
+  ]
+}

package/components/registry/layout-grid.json

@@ -0,0 +1,77 @@
+{
+  "name": "layout-grid",
+  "component": "MRow / MCol",
+  "display": "Grid",
+  "tier": "foundation",
+  "section": "Foundations",
+  "family": "Layout",
+  "status": "stable",
+  "summary": "The product's 12-column layout grid — MRow / MCol (wrappers over Ant a-row/a-col), ~540/~522 files. MCol :size is a span out of 12: 6 = half (the default form field), 12 = full, 3 = quarter, 4 = third, 2 = sixth. :gutter=\"16\" for form rows; :gutter=\"0\" only for structural wrappers; auto-size shrinks a column to its content.",
+  "props": {
+    "size": {
+      "type": "number",
+      "default": "6",
+      "enum": [
+        "12",
+        "6",
+        "4",
+        "3",
+        "2"
+      ],
+      "note": "column span (out of 12); the row fills with 12/size equal columns"
+    },
+    "gutter": {
+      "type": "boolean",
+      "default": "false",
+      "note": "16px gutter between columns (the form-row default)"
+    },
+    "auto-size": {
+      "type": "boolean",
+      "default": "false",
+      "note": "show the 'filling field + content-width action buttons' row"
+    }
+  },
+  "do": [
+    "Use MRow/MCol for all form field layouts.",
+    "Sizes: 6 = half, 12 = full, 3 = quarter, 4 = third.",
+    "gutter 16 for form rows; gutter 0 only for structural wrappers.",
+    "auto-size for action/compact cells; align inside a cell with flex utilities."
+  ],
+  "dont": [
+    "Don't hand-roll a flex grid for form layouts.",
+    "Don't put a gutter on full-height structural wrappers (use gutter 0).",
+    "Don't nest deep grids where a single MRow of sized MCols works."
+  ],
+  "tokensUsed": [
+    "@padding-md",
+    "--border-color",
+    "--code-tag-background-color",
+    "--page-background-color",
+    "--primary"
+  ],
+  "related": [
+    "layout-app-shell",
+    "layout-screen-regions"
+  ],
+  "storybook": "Foundations/Layout/Grid",
+  "a11y": {
+    "summary": "Layout primitive — no semantics of its own; MRow/MCol are presentational wrappers. The fields/controls placed inside carry the semantics and tab order.",
+    "issues": []
+  },
+  "knownIssues": [
+    "Diagram reproduces the visual grid with CSS; the product uses MRow/MCol (wrappers over Ant a-row/a-col)."
+  ],
+  "changelog": [
+    "2026-06-29: added — the 12-column splits + interactive size/gutter/auto-size; render-first from the story.",
+    "2026-06-29: examples width fixed (cells were collapsing to content width).",
+    "2026-06-29: Usage enriched — when-to-use + where-it's-used.",
+    "2026-07-01: primary button weight 600→500 to match the product Button; native-control font reset.",
+    "2026-07-01: button font-weight 500→400 (product Button is 400)."
+  ],
+  "whenToUse": "The default way to lay out form fields and any content needing predictable column proportions — 6 = half a row, 12 = full, with a 16px gutter.",
+  "usedIn": [
+    "Every form field layout (MRow ~540 files · MCol ~522 files).",
+    "Cards, summary rows, split panels — anywhere needing column proportions.",
+    "Default form layout is 6 / 6 (two-up); size 12 for textareas / full-width fields."
+  ]
+}

package/components/registry/layout-page-templates.json

@@ -0,0 +1,70 @@
+{
+  "name": "layout-page-templates",
+  "component": "recipes.json",
+  "display": "Page templates",
+  "tier": "foundation",
+  "section": "Foundations",
+  "family": "Layout",
+  "status": "stable",
+  "summary": "The canonical page types ObserveOps repeats, as annotated wireframes inside the app frame — built from the composition recipes. List view (header + toolbar + table + pager) · Form view (field grid) · Detail view (header + tabs + panels) · Dashboard view (picker + time range + widget grid) · Explorer view (left tree/filter + query + results) · Wizard flow (stepper + step + Back/Next) · Graph / Canvas (tree + interactive node graph).",
+  "props": {
+    "template": {
+      "type": "string",
+      "default": "list",
+      "enum": [
+        "list",
+        "form",
+        "detail",
+        "dashboard",
+        "explorer",
+        "wizard",
+        "graph"
+      ],
+      "note": "which page template wireframe to show"
+    }
+  },
+  "do": [
+    "Assemble pages from these archetypes + the per-region component mapping (recipes.json).",
+    "Use the List view for the most common index pages; Form/Detail for records.",
+    "Graph/Canvas (topology) is its own archetype — not a Dashboard or Explorer."
+  ],
+  "dont": [
+    "Don't invent a new page shape where one of these seven fits.",
+    "Don't put a second scrolling region inside the body."
+  ],
+  "tokensUsed": [
+    "--nav-panel-bg",
+    "--border-color",
+    "--page-background-color",
+    "--primary",
+    "--code-tag-background-color",
+    "--severity-critical",
+    "--severity-clear",
+    "--severity-warning"
+  ],
+  "related": [
+    "layout-app-shell",
+    "layout-screen-regions",
+    "layout-shells"
+  ],
+  "storybook": "Foundations/Layout/Page templates",
+  "a11y": {
+    "summary": "Composition references — each template names the component per region; those components carry the semantics, headings and tab order.",
+    "issues": []
+  },
+  "knownIssues": [
+    "Wireframes, not live pages — assemble from the per-region components (recipes.json)."
+  ],
+  "changelog": [
+    "2026-06-29: added — the 7 canonical page-template wireframes.",
+    "2026-06-29: fixed Detail/Explorer/Graph body panes collapsing to zero height (align-items).",
+    "2026-06-29: Usage enriched — when-to-use + where-it's-used."
+  ],
+  "whenToUse": "Pick the page archetype that matches the task, then assemble it from the per-region components (recipes).",
+  "usedIn": [
+    "List view — inventory / alert / policy lists.",
+    "Form view — monitor / policy / credential forms · Detail view — monitor / alert detail.",
+    "Dashboard view — dashboards / NOC · Explorer view — log / metric explorers.",
+    "Wizard flow — discovery / report setup / 2FA · Graph / Canvas — topology."
+  ]
+}

package/components/registry/layout-panels.json

@@ -0,0 +1,70 @@
+{
+  "name": "layout-panels",
+  "component": "panels",
+  "display": "Panel behaviours",
+  "tier": "foundation",
+  "section": "Foundations",
+  "family": "Layout",
+  "status": "stable",
+  "summary": "How panels & overlays open, move and resize. Drawer (slide-over, FlotoDrawer · 146) · Modal (a-modal · 37) · Collapsible (MCollapse · 19) · Expandable rows (9) · Resizable / split (splitpanes · ~3) · Affix / sticky · Dashboard tiles (vue-grid-layout · 5) · Bulk-action bar (fixed bottom · 2) · Popover (20+) · Full-screen / OmniBox overlay.",
+  "props": {
+    "behaviour": {
+      "type": "string",
+      "default": "drawer",
+      "enum": [
+        "drawer",
+        "modal",
+        "collapse",
+        "expand",
+        "split",
+        "affix",
+        "dash",
+        "bulkbar",
+        "popover",
+        "fullscreen"
+      ],
+      "note": "which panel/overlay behaviour to show"
+    }
+  },
+  "do": [
+    "Drawer is the default record surface (forms + deep drill-downs); ESC to close.",
+    "Modal for small confirm/collect; Drawer for panel-sized records.",
+    "Bulk-action bar appears on selection; Popover for contextual, light content."
+  ],
+  "dont": [
+    "Don't use resizable splits casually (rare — only settings/topology/apm trace).",
+    "Don't confuse table column-resize (a grid feature) with a panel behaviour."
+  ],
+  "tokensUsed": [
+    "--border-color",
+    "--page-background-color",
+    "--primary",
+    "--code-tag-background-color",
+    "--overlay-bg",
+    "--neutral-shadow-light",
+    "--neutral-light"
+  ],
+  "related": [
+    "layout-screen-regions",
+    "layout-app-shell"
+  ],
+  "storybook": "Foundations/Layout/Panel behaviours",
+  "a11y": {
+    "summary": "Behaviour references. In the product: Drawer/Modal trap focus + close on ESC; Popover is aria-described from its anchor; the Bulk-action bar announces the selection count.",
+    "issues": []
+  },
+  "knownIssues": [
+    "Behaviour diagrams, not live overlays — the real components own focus-trap / ESC / aria."
+  ],
+  "changelog": [
+    "2026-06-29: added — the 10 panel/overlay behaviours.",
+    "2026-06-29: fixed Expandable-rows expanded header/body collapsing to content width.",
+    "2026-06-29: Usage enriched — when-to-use + where-it's-used."
+  ],
+  "whenToUse": "How a surface shows up — editing a record → Drawer; a quick confirm → Modal; optional detail → Collapsible / Expandable rows; the rest are for specific jobs.",
+  "usedIn": [
+    "Drawer 146 files · Modal 37 · Collapsible 19 · Popover 20+ · Expandable rows 9.",
+    "Dashboard tiles 5 · Bulk-action bar 2 · Resizable splits ~3 (settings / topology / apm trace).",
+    "Drawer is the default record surface; Modal for small confirms; Bulk-bar appears on selection."
+  ]
+}