@mtdt/observeops-ds-spec 0.1.0

package/components/specs/tag.md

@@ -0,0 +1,196 @@
+# Tag (`MTag`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom |
+| **Maturity** | 🟡 Stable-but-flawed (heavily used as a plain tag; the `variant` feature is broken) |
+| **Source** | `@motadata/ui` kit → `ui/components/Tags/Tag.vue` (wraps Ant `a-tag`). Not overridden/excluded. |
+| **Storybook** | `Atoms/Tag` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/tag.json`](../registry/tag.json) |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<MTag>` used 150× across 87 files** — almost always a **plain** tag (no variant).
+- **`variant` used ~3× total** (primary/error/default ×1 each) — effectively unused.
+- `<MStatusTag>` (the separate status component) used 30×.
+
+## Overview
+
+A compact label for categorization, metadata, or removable selections. Wraps `a-tag`;
+maps `variant` → a color via `ColorPalette` (`ui/style/colorPalette.js`) or takes a raw
+`color`. **In practice it's used as a plain or removable label, not a colored variant.**
+
+## Anatomy
+
+```text
+┌───────────────┐
+│  Label    [×] │   ← container (.ant-tag) · label (slot) · remove "×" (when closable)
+└───────────────┘
+```
+
+## Options
+
+- **Colored / status tags → CSS classes (the working mechanism):** apply a class, not the
+  `variant` prop — colored text on a tinted background, legible in both themes:
+  `tag-red` (75×) · `tag-green` (57×) · `tag-yellow` (15×) · `tag-orange` (9×) ·
+  `tag-purple` (1×) · `tag-unknown` (2×). Plus state classes `.new` / `.provision` /
+  `.unprovision` / `.used-count-pill` (48×). Example: `<MTag class="tag-red" :closable="false">`.
+  (`tag-primary` (49×) is actually a neutral chip, not brand-blue.)
+- **`variant` prop (ColorPalette keys) — avoid:** `default · primary · success · error ·
+  warning · orange · neutral-lighter`; **colored ones are broken/illegible (F2)**. Use the
+  classes above instead.
+- **Modifiers:** `closable` (default **true**), `rounded`, `confirmable` (confirm-before-
+  remove), `visible`, custom `color`.
+
+## Behaviors
+
+- **Removable:** with `closable`, a "×" emits `close`. `confirmable` wraps it in a confirm.
+- **`closable` defaults to true** → every tag shows a "×" unless `:closable="false"` (F5).
+
+## Content & writing
+
+Short noun/label; for removable chips the label is the selected value.
+
+## Accessibility
+
+- A plain tag is a `<span>` label — fine.
+- Default tag contrast (neutral text on a neutral chip) is legible in both themes; bg
+  themes (`#e3e8f2` → `#2b394f`).
+- ⚠️ **The remove "×" is not keyboard-accessible** (F4).
+
+## Props / API
+
+`closable` (default true) · `color` · `variant` · `rounded` · `confirmable` · `visible`.
+Emits `close`; slots: default (label), `confirm-title`. No `model`.
+Machine spec: [`../registry/tag.json`](../registry/tag.json).
+
+## Design tokens used
+
+`--tag-bg` / `--tag-color` (themed) for the plain tag. Variant colors come from
+`ColorPalette` **static hex** (not tokens) — see F1/F6.
+
+## Findings & Inconsistencies
+
+### F2 — Colored variants are illegible (effectively broken) · High · Open
+
+Measured: every colored `variant` (primary/success/error/warning) renders the **same
+neutral chip background** (`--tag-bg`) with **white text** → in light theme that's white
+on `#e3e8f2` (contrast ~1.2:1, unreadable). The product forces the tag bg to `--tag-bg`
+regardless of `color`, so the variant only changes text color. This is why `variant` is
+used only ~3×. **Use the `tag-*` CSS classes instead** (see Options — they're legible and
+heavily used: `tag-red` 75×, `tag-green` 57×, …), or `MStatusTag` for status. Longer term,
+either fix the `variant` override to produce a legible bg+text pair (token-based) or remove
+the `variant` color feature in favor of the classes.
+
+### F4 — Remove "×" is not keyboard-accessible · High · Open *(a11y)*
+
+The close control is an `<a @click>` with **no `href`/`role`/`aria-label`/`tabindex`** —
+confirmed not focusable. Keyboard/AT users can't remove tags, and the control is unlabeled.
+**Solution:** use `<button type="button" aria-label="Remove {label}">` + a focus ring
+(see [SF-001](../../findings/SF-001-focus-visible.md)).
+
+### F1 — Variant set is small + static; no info/neutral · Medium · Open
+
+Valid variants = ColorPalette keys only; `info`/`neutral` silently do nothing. Colors are
+static hex (`success #89c540`, `error #f04e3e`, …) that **differ from the product's
+severity tokens** (`#14b053`, `#ec5b5b`). **Solution:** document the real set; align to
+tokens if variants are revived.
+
+### F5 — `closable` defaults to true · Medium · Open
+
+Display tags get an unexpected "×" unless `:closable="false"`. **Solution:** consider
+defaulting `closable` to false; for now, document it loudly.
+
+### F6 — Close "×" optically off (baseline layout, not flex) · Low · Open *(polish)*
+
+`.ant-tag` uses `line-height: 22px` + inline/baseline layout (no flex). The thin Font-
+Awesome `times` glyph (`vertical-align: -1.65px`) aligns by baseline, so the × *reads*
+slightly off the label even though it's geometrically centered (**measured offset ~1px**).
+Product-side, not Storybook. **Solution (optional polish):** `.ant-tag { display:
+inline-flex; align-items: center; gap: 4px; }` in `tags.less` for optically-clean alignment
+and controlled spacing.
+
+### F3 — `neutral-ligher` class typo · Low · Open
+
+`Tag.vue` applies the misspelled class `neutral-ligher` (missing "t") for the
+`neutral-lighter` variant, so the themed `.neutral-lighter` LESS override never matches.
+**Solution:** fix the typo to `neutral-lighter`.
+
+### F7 — `MStatusTag` label inversion + silent fallback · Low · Open
+
+`_base-status-tag.vue` `textMap` flips two labels: `poweredoff` renders **"Up"** and
+`poweredon` renders **"Down"** (colours still follow `TAG_MAP`: poweredoff = red,
+poweredon = green) — surprising for a reader. Also, a `status` not in `TAG_MAP` gets **no
+colour class** and renders as a plain rounded tag (silent). **Solution:** document the
+inversion explicitly; add an `unknown`/default colour mapping so unmapped statuses are
+visibly neutral rather than silently plain.
+
+## Do / Don't
+
+### Do
+
+- Use a plain tag for labels; `:closable="true"` for removable chips; `:rounded` for pills.
+- Use `MStatusTag` for status/severity.
+
+### Don't
+
+- Don't use the color `variant`s (broken/illegible — F2).
+- Don't assume `info`/`neutral` exist (F1); don't forget `closable` defaults to true (F5).
+
+## Tag family (related components & treatments)
+
+"Tag" is a **family**, not just `MTag`. Each member is classified by *what it is*
+(decision [D12](../../decisions/DECISIONS.md) — own entry vs. variant vs. internal part):
+
+| Member | Source | Role | Classification → home |
+| --- | --- | --- | --- |
+| `MTag` | `ui/components/Tags/Tag.vue` | base tag (+ `tag-*` colour classes, state classes) | **base** → this sheet |
+| `tag-*` colour classes | `src/design/tags.less` | colour restyle of MTag | **variant** → Tag (ColoredTags story) |
+| `MStatusTag` | `_base-status-tag.vue` | status/severity tag — maps status→`tag-*` (30×) | **variant** → Tag (Status story + section below) |
+| **`SelectedItemPills`** | `dropdown-trigger/selected-item-pills.vue` | **teal `ant-tag-has-color` pills for picker selections** — truncated, with a **`+N` overflow popover** (default `maxItems: 1`); teal from `--main-tags-*` in `input.less`. | **internal part** → [DropdownPicker](./dropdown-picker.md) ✅ (preview story under Tag) |
+| `MultipleTrigger` / `SingleTrigger` | `dropdown-trigger/` | picker triggers that render `SelectedItemPills` | **internal part** → [DropdownPicker](./dropdown-picker.md) ✅ |
+| `LooseTags` | `loose-tags.vue` | free-form **tag input** (type to create tags) | **own entry** → [Molecules / Forms](./loose-tags.md) ✅ |
+| `TagsList` | `tags-list.vue` | read-only tag overflow (count + popover) — **dead code, 0 usages** | documented **badged unused** → [Molecules / TagsList](./tags-list.md) ✅ (prefer `SelectedItemPills`) |
+
+App-specific tag classes also exist: `filter-alert-tag` (7×), `os-tag`, `nav-beta-tag`,
+plus the `main-tags` teal treatment. The **teal `key:value` + `+N` pills** seen in pickers
+are `SelectedItemPills` — shown live in Storybook as **Atoms / Tag / Examples → "Selected
+pills (picker, +N overflow)"** (rendered with `:tags="true"`, which adds the
+`.loose-tags-input` ancestor that activates the teal `--main-tags-*` styling). Full
+behavioural coverage (triggers, search, clear) comes with the DropdownPicker spec.
+
+### Status / severity tag — `MStatusTag` (variant of Tag)
+
+`_base-status-tag.vue` (registered globally as **`MStatusTag`**, used **30× / 28 files**).
+It is **not a separate component** in the DS — it's a *semantic variant of Tag*: it renders
+`<MTag rounded :closable="false" :class="tag-*">` and maps a **status string** to a
+**colour class plus a capitalized label**. Shown live as **Atoms / Tag / Examples →
+"Status / severity"**.
+
+- **API:** `status` (String|Number) · `forcePrimary` (Boolean). Renders nothing when
+  `status` is falsy.
+- **Mapping (`TAG_MAP`, ~90 keys):** green = `up`/`on`/`active`/`success`/`healthy`/…;
+  red = `down`/`off`/`critical`/`failed`/`disconnected`/…; yellow = `paused`/`queued`/
+  `halted`/`starting`; orange = `suspended`/`fair`; purple = `unreachable`; neutral
+  (`tag-primary`) = `maintenance`/`connected`/`standby`. Verified colours match the
+  severity palette (`up` → `#14b053`, `down` → `#ec5b5b`, …).
+- **`forcePrimary`** overrides any status to the neutral `tag-primary` chip.
+- **Fallback:** a status **not** in the map gets no colour class → renders as a plain
+  rounded tag (silent — easy to miss). Consider a documented default/`unknown` mapping.
+- **Quirk (finding F7, low):** `textMap` inverts two labels — `poweredoff` shows **"Up"**
+  and `poweredon` shows **"Down"** (the *colour* still follows `TAG_MAP`: poweredoff = red,
+  poweredon = green). Intentional domain inversion, but surprising; document loudly.
+- **Alignment:** `MStatusTag` carries `inline-flex items-center`, which is exactly the
+  alignment plain `MTag` lacks (F6). This now renders in Storybook since the Tailwind
+  pipeline was enabled — see [SF-002](../../findings/SF-002-storybook-tailwind.md) (Fixed).
+
+## Changelog
+
+- **2026-06-05** — Added (placeholder variants).
+- **2026-06-06** — Full deep-dive: real variant set (ColorPalette) found; colored variants
+  measured **illegible** (F2); examples refocused on plain/removable usage; findings F1–F5
+  (with the SF-001 link); Option B pages.
+- **2026-06-11** — Back-catalog re-audit (prop-value distribution sweep): added a **State
+  classes** story rendering `used-count-pill` (48×), `new`, `provision`, `unprovision` —
+  previously documented in text but not shown.

package/components/specs/tags-list.md

@@ -0,0 +1,105 @@
+# TagsList — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule (read-only display) |
+| **Maturity** | ⚠️ **Unused (dead code)** — exists but has **0 usages** in the product |
+| **Source** | `src/components/tags-list.vue` (composes `MTag` + `MPopover`) |
+| **Storybook** | `Molecules/TagsList` (Examples · Usage · Changelog) |
+| **Registry** | [`../registry/tags-list.json`](../registry/tags-list.json) |
+| **Family** | Tag family — the read-only "overflow" display (see [`tag.md`](./tag.md); [D12](../../decisions/DECISIONS.md)) |
+| **Figma** | N/A (dead code — do not build) |
+
+> ⚠️ **This component is unused.** Documented at the owner's request for a complete
+> catalog. The **live** equivalent of this pattern is **`SelectedItemPills`** (the picker
+> "+N" pills). Prefer that. See finding **F1**.
+
+## Usage (product analytics)
+
+- **`<TagsList>` used 0× / 0 files.** Not imported anywhere. (`name: 'TagsList'`; the only
+  "TagsList" matches in the codebase are unrelated data fields like `_objectTagsList`.)
+
+## Overview
+
+A read-only **tag overflow** display. Given an array of strings:
+
+- **≤ `maxLength`** (default **2**) → render each tag inline as a neutral `tag-primary`
+  chip (rounded, non-closable).
+- **> `maxLength`** → render a single chip showing the **count**, with a hover **popover**
+  listing every item.
+
+Note it collapses to **just the count** (e.g. "5") — it never shows "first N + remaining",
+unlike `SelectedItemPills` which shows the first item(s) then a `+N`.
+
+## Anatomy
+
+```text
+≤ maxLength:   ⌜web-server⌟ ⌜database⌟          ← inline neutral chips
+> maxLength:   ⌜ 5 ⌟  ──hover──▶  ┌──────────┐  ← count chip + popover list
+                                  │ web-server│
+                                  │ database  │
+                                  │ …         │
+                                  └──────────┘
+```
+
+## Options / API
+
+- **`value`** (Array | Object) — the tags to display.
+- **`maxLength`** (Number, default **2**) — inline threshold before collapsing to a count.
+
+No events, no slots, no v-model. Pure presentational.
+
+## Behaviors
+
+- Renders nothing when `value` is empty.
+- Hover (not click) opens the count popover (`trigger="hover"`, `placement="bottomRight"`).
+
+## Design tokens used
+
+`--tag-bg` / `--tag-color` (the neutral `tag-primary` chip, themed) · `--border-color`
+(popover row dividers). Chip corner is `border-radius: 10px` (local `.application-item`).
+
+## Accessibility
+
+- Read-only text chips (`<span>`) — fine for contrast in both themes.
+- The overflow affordance is **hover-only** — the count chip isn't focusable/click-openable,
+  so keyboard/touch users can't reveal the full list. (Moot while unused; would matter if
+  revived — prefer `SelectedItemPills`, which has the same caveat tracked there.)
+
+## Findings & Inconsistencies
+
+### F1 — Dead code (unused component) · Medium · Open
+
+`tags-list.vue` is **never imported or rendered**. It duplicates a pattern already provided
+(better) by `SelectedItemPills` (first-N + `+N` overflow, used in pickers/`LooseTags`).
+**Solution:** **remove** `src/components/tags-list.vue` (dead-code cleanup), or — if a
+count-only overflow display is genuinely wanted — fold it into `SelectedItemPills` behind a
+prop instead of maintaining a second component.
+
+### F2 — Count-only overflow (pattern inconsistency) · Low · Open
+
+It collapses to **only a count** with no preview of any tag, whereas the product's live
+pattern (`SelectedItemPills`) shows the first item(s) + `+N`. Two different overflow idioms
+for the same concept. **Solution:** standardize on the `SelectedItemPills` idiom.
+
+## Do / Don't
+
+### Do
+
+- For tag overflow in the product, use **`SelectedItemPills`** (live, themed, `+N`), not this.
+
+### Don't
+
+- Don't adopt `TagsList` in new code — it's unused/dead. Don't build it in Figma.
+
+## Related
+
+`SelectedItemPills` (the live overflow equivalent) · `MTag` · `MPopover` · `LooseTags`.
+See the Tag family table in [`tag.md`](./tag.md).
+
+## Changelog
+
+- **2026-06-07** — Added to the catalog (badged **unused**) at the owner's request. Verified
+  render (inline chips ≤ maxLength; count chip + hover popover above it). Logged dead-code
+  finding F1 + pattern inconsistency F2; recommended removal / consolidation onto
+  `SelectedItemPills`.

package/components/specs/toolbars.md

@@ -0,0 +1,108 @@
+# Toolbars — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Organism |
+| **Maturity** | 🟢 Stable |
+| **Source** | `_base-page-header.vue` (`FlotoPageHeader`) · `widgets/views/components/widget-title.vue` (`WidgetTitle`) · `_base-bulk-action-bar.vue` (`BulkActionBar`) · grid toolbar composition · `column-selector.vue`. |
+| **Storybook** | Organisms/Toolbars |
+| **Registry** | [`registry/toolbars.json`](../registry/toolbars.json) |
+| **Family** | [Toolbars](../family-map.md) |
+
+## Why this is one family
+
+A **toolbar** is an organism that *arranges* molecules/atoms (title · search · filters · actions).
+The product has **several** distinct toolbars — catalogued here as **variants** of one family. They
+**compose** the **Filters** molecules; they don't own them.
+
+## The variants
+
+| Variant | Source | Usage | What it is |
+| --- | --- | --- | --- |
+| **App header** | `layout/header.vue` | global | the app-shell **top bar** (logo · search · notifications · user) |
+| **Page header** | `FlotoPageHeader` | **54×** | back + title + right-side actions |
+| **Widget header** | `widget-title` | **58×** | title + time-range pill + kebab of widget actions |
+| **Bulk action bar** | `_base-bulk-action-bar` | — | a floating N-selected toolbar |
+| **Grid toolbar** | composition | — | search + filter + columns + Add over a grid |
+| **Column chooser** | `column-selector` | 174× | the eye-button column show/hide dropdown |
+
+### Page header (54×)
+
+- **Left:** optional `back-button` + **title** (`--primary-alt`, font-500, with an optional count).
+- **Right:** the default slot — actions (search, export, primary **Add**).
+- **Props:** `title` · `back-link` · `main-header` · `use-divider`. **Slots:** `back-button` ·
+  `before/after-title` · `title` · `title-append` · default · `additional-rows`.
+
+### Widget header (58×)
+
+- **Title** (ellipsis, font-500) + a **disabled `TimeRangePicker` pill** (the widget's window) + a
+  **kebab** (`ellipsis-v` → `FlotoGridActions`): **Edit · Clone · Full Screen · Share · Export as CSV**.
+- Slot: `flip-toggle`; emits `exit-fullscreen`.
+
+### Bulk action bar
+
+- A floating `role="toolbar"` shown when `selectedCount >= minSelection`: a **clear checkbox** +
+  **"N items selected"**, inline **primary** actions + **danger** actions (`--secondary-red`), and a
+  **"More"** (`ellipsis-v`) overflow. Emits `clear` / `selected`.
+
+### Grid toolbar / Column chooser
+
+- **Grid toolbar** — search + **filter** (opens the Filters molecules) + **columns** + **Add**.
+- **Column chooser** (174×) — an eye-button dropdown of column checkboxes + Reset. *Product is
+  show/hide only*; reordering is by **dragging grid headers** (Table → Basic). The grip drag here is a
+  **DS enhancement**.
+
+## Checked & scoped out (sweep recheck)
+
+A census of every header / toolbar / action-bar / `role="toolbar"` confirmed the 6 archetypes above.
+The rest are **variants, compositions, or other families** (not missed):
+
+- **`FlotoGridActions`** (**88×**) — the **row action kebab** (Edit/Clone/Delete ⋮). The *action-menu*
+  archetype, catalogued under **Popover** — and it's the kebab **composed into** the Widget header and
+  the Bulk action bar's "More."
+- **Detail headers** (RUM drill-down ×7, `guide-header`) — **Page-header variants** for detail views.
+- **`bulk-provision-toolbar`** — a domain **variant of the Bulk action bar**.
+- **Action footer** (`result-footer`, modal/drawer footers) — covered by **Modal / Drawer**.
+- **`overlay-controls`** (metric-explorer) — a feature-specific control strip, not reusable.
+- **`rule-group-header` / `permission-section-header`** — in-content **section labels**, not toolbars.
+- **`FlotoNavBar` / left menu / breadcrumb / tabs** — **navigation** archetypes (a future *Navigation*
+  family), not toolbars.
+
+## Accessibility
+
+- The **Bulk action bar** uses `role="toolbar"` + `aria-label`. **Verify** focus-visible ring
+  (**SF-001**) and `aria-label`s on icon-only buttons (export, kebab, More, ×).
+
+## Design tokens used
+
+`--primary` · `--primary-alt` (title) · `--border-color` · `--page-background-color` ·
+`--page-text-color` · `--neutral-light` · `--secondary-red` (danger) · `--common-widget-bg` ·
+`--timerange-background-color`.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Noted | Reproductions (the live Page/Widget headers use the router / widget store). |
+| F2 | Low (a11y) | Open | Verify focus-visible ring + icon-button `aria-label`s (SF-001). |
+| N1 | Info | — | **Taxonomy (2026-06-16):** consolidated the product's toolbars into one family; the former "Grid Toolbar" entry was folded in (Grid toolbar + Column chooser variants), and its filter molecules moved to **Filters**. |
+
+## Do / Don't
+
+- **Do** use the Page header for list/detail pages; compose toolbars from **Filters** + search +
+  actions; use the Bulk action bar for multi-select; put destructive bulk actions in `--secondary-red`.
+- **Don't** duplicate a filter inside a toolbar (compose the molecule); don't make a per-screen toolbar
+  component; don't rely on the column chooser to reorder columns (that's grid-header drag).
+
+## Related components
+
+**Filters** (composed into toolbars) · **Table** (grid toolbar sits above it) · `FlotoDropdownPicker` ·
+`MPopover` (kebab menus) · **Date & Time Pickers** (the widget time-range pill).
+
+## Changelog
+
+- **2026-06-16** — Added — the **Toolbars** family (organisms, by variant): **Page header** (54×),
+  **Widget header** (58×), **Bulk action bar**, **Grid toolbar**, **Column chooser**. Surfaced the two
+  **missing** big toolbars (Page header, Widget header) during the taxonomy reorg, and **folded in** the
+  former "Grid Toolbar" entry (its filter molecules moved to **Filters**). Reproductions; verified
+  render + the Widget-header kebab opens, no console errors. Findings F1 (reproduction), F2 (a11y).

package/components/specs/tooltip.md

@@ -0,0 +1,112 @@
+# Tooltip (`MTooltip`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule |
+| **Maturity** | 🟢 Stable |
+| **Source** | `src/components/_base-tooltip.vue` (Floto override — the kit `MTooltip` is **excluded** in the preview/app and this ships instead). Renders via **VTippy** (vue-tippy). |
+| **Storybook** | Molecules/Tooltip |
+| **Registry** | [`registry/tooltip.json`](../registry/tooltip.json) |
+| **Family** | [Popover / Tooltip](../family-map.md) |
+
+## Usage analytics
+
+- **94×** across the app. The dominant pattern is an **info-circle icon trigger + a short text
+  hint**.
+- **Placement (VTippy names):** `top-start` (default) **73×** · `top` 11× · `left` 6× ·
+  `bottomRight` 2× · `topLeft`/`right` 1×. The default dominates.
+- Overlay-class variants: `chart-like-tooltip` (2×, chart-surface background), `noc-dashboard-tooltip` (1×).
+- **Sibling tooltip mechanisms (intentional):** native **`title=""`** attribute (~59× — browser
+  tooltip for plain/truncated text), the **`v-tooltip` directive** (1×, negligible), the **data-viz
+  tooltips** (Highcharts `TooltipBuilder` chart tooltip + sparkline + `heatmap-tooltip.vue` — see
+  **Molecules/Data-Viz Tooltips**), and **graph/topology tooltips** (vis-network/d3 edge & node).
+  **The product has 7 distinct tooltip kinds** — full taxonomy on the Data-Viz Tooltips Usage page.
+
+## Overview
+
+A **transient, non-interactive label** revealed on **hover/focus**, anchored to a trigger. Note
+the project **overrides the kit tooltip**: `main.js`/preview exclude `MTooltip` from the kit and
+register the Floto `_base-tooltip.vue`, which renders through **VTippy** (vue-tippy) rather than
+Ant `a-tooltip`. Use it for brief hints; for anything the user clicks or types into, use
+**`MPopover`**.
+
+## Anatomy
+
+- **Trigger** (`trigger` slot) — the anchored element (commonly an `info-circle` `MIcon`).
+- **Bubble** — the floating content (default slot), **no arrow** (`:arrow="false"`), animation
+  `shift-toward`, appended to the closest `.__panel` or `document.body`.
+
+## Options (props)
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `placement` | `top-start` | VTippy placement (`top`/`bottom`/`left`/`right` + `-start`/`-end`) |
+| `disabled` | `false` | short-circuits — renders the trigger inline, no tooltip |
+| `trigger` | `hover focus` | **declared but not wired to VTippy (F1)** |
+| `overlayClassName` | — | e.g. `chart-like-tooltip` |
+| `getPopupContainer` | — | defaults to closest `.__panel` or `document.body` |
+
+## Behaviors
+
+- Shows on **hover/focus**; `interactive:true` lets the pointer move onto the bubble without it
+  closing. `lazy:true` defers creation until first trigger.
+- `disabled` is the supported on/off switch (not the `trigger` prop).
+
+## Content & writing
+
+- Brief, plain hints — a phrase or one sentence. No interactive controls.
+
+## Accessibility
+
+- **Keyboard/SR:** the bubble content is **not** associated with the trigger via
+  `aria-describedby`, and icon-only triggers have **no accessible name** — screen-reader users
+  may miss the hint (**F3**). Recommended: add `aria-label` to icon triggers and wire
+  `aria-describedby` to the bubble id.
+- **Focus ring:** removed on the overlay (`:focus { outline:none }` in `_base-popper.less`) — see
+  [SF-001](../../findings/SF-001-focus-visible.md) (**F2**).
+- Tooltips appear on **focus** too (good), but the missing aria wiring limits SR value.
+
+## Props / API
+
+See the table above and [`registry/tooltip.json`](../registry/tooltip.json).
+
+## Design tokens used
+
+`--tooltip-background-color` · `--tooltip-text-color` · `--tooltip-box-shadow` · `--border-color`
+· `--chart-tooltip-background` (chart variant).
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Open | `trigger` prop declared (default `hover focus`) but **not passed to VTippy** — changing it does nothing. |
+| F2 | Medium (a11y) | Open | No focus ring on the overlay — links to **SF-001**. |
+| F3 | Medium (a11y) | Open | Tooltip content not linked via `aria-describedby`; icon-only triggers lack an accessible name. |
+
+## Recommended solutions
+
+- **F1:** either bind `:trigger="trigger"` on `<VTippy>` or remove the dead prop.
+- **F2:** adopt the `:focus-visible` ring from SF-001.
+- **F3:** add `aria-label` to icon triggers; generate a bubble id and set `aria-describedby` on the
+  trigger when the tooltip is open.
+
+## Do / Don't
+
+- **Do** keep content brief and non-interactive; use the info-circle idiom; use `:disabled` when
+  the hint is redundant.
+- **Don't** put buttons/links/inputs in a tooltip (it dismisses on mouse-out) — use **Popover**;
+  don't rely on the `trigger` prop to change activation (F1).
+
+## Related components
+
+`MPopover` (interactive panel) · `FlotoDropdownPicker` (select) · `MModal` (dialog).
+
+## Changelog
+
+- **2026-06-11 (nth-level audit)** — Documented the **three intentional tooltip kinds** (native
+  `title=` ~59×, `MTooltip` 94×, graph/canvas tooltips), the real placement distribution
+  (`top-start` 73× default · `top` 11× · `left` 6×), and the VTippy-vs-Ant placement-name split.
+- **2026-06-11** — Added (decision-grade Usage). Deep-dive of `_base-tooltip.vue` (94×, VTippy
+  override). Stories: Basic (info idiom) · Placements · Disabled · Rich content · Playground —
+  verified the bubble shows on hover with the hint text, no console errors. Findings F1 (dead
+  `trigger` prop), F2 (focus → SF-001), F3 (aria wiring).

package/foundation/README.md

@@ -0,0 +1,39 @@
+# Foundations — product coverage sweep
+
+A page-by-page sweep of the ObserveOps product (2026-06-18) validating the four **Foundations/Layout**
+elements against what the product actually does. Six parallel passes covered: inventory/monitors ·
+alert/dashboard/NOC · the explorers (log/apm/rum/flow/trap/metric) · topology/ncm/netroute/slo/reports/audit ·
+all ~23 settings submodules · auth/public/system pages + global chrome + the layout switcher.
+
+Each file lists the **variants**, **where they're used in the product** (modules / pages / flows, with
+files), a **coverage verdict**, **notable findings** (including things we'd missed or mis-filed), and
+**best practices**.
+
+| File | Element | Storybook |
+| --- | --- | --- |
+| [layout-shells.md](./layout-shells.md) | The outer page frame (route shells) + content layouts | Foundations/Layout/Layout shells · App shell |
+| [page-templates.md](./page-templates.md) | The canonical page types | Foundations/Layout/Page templates |
+| [panel-behaviours.md](./panel-behaviours.md) | How panels open / move / resize | Foundations/Layout/Panel behaviours |
+| [screen-regions.md](./screen-regions.md) | Regions inside the content panel + content layouts | Foundations/Layout/Screen regions |
+
+> **Status (2026-06-18):** every addition below has been **folded into the live Storybook** —
+> Layout shells reclassified (4 route + 2 content), the **Graph / Canvas** page template added, **Modal /
+> Expandable rows / Bulk-action bar / Popover / Full-screen** added to Panel behaviours, and **three-pane /
+> chart-over-grid** added to Screen regions. Machine spec `layout/layouts.json` updated to match.
+
+## Headline findings
+
+1. **Route shells are 4, not 5.** The switcher in `src/app.vue` resolves **Layout** (default) /
+   **LoginLayout** / **EmptyLayout** / **PublicLayout** from `route.meta.layout`. **`MonitorHierarchyLayout`
+   has 0 route overrides** — it's a two-pane *content layout component* used inside `Layout`, not a route
+   shell. Re-filed accordingly.
+2. **A 7th page archetype exists — the Topology graph canvas** (Cytoscape: pan/zoom/minimap/keyboard/node-drag).
+   It isn't a Dashboard or an Explorer; document it as **Graph / Canvas view**.
+3. **Panel behaviours are broader than the catalogued 5.** Beyond Drawer/Collapsible/Resizable/Affix/Dashboard-tiles,
+   the product leans heavily on **Modal** (37 files), **Expandable rows** (9), **Popover** (20+), a fixed
+   **Bulk-action bar**, **resizable table columns**, and the full-screen **OmniBox** overlay.
+4. **More content layouts than four** — add **three-pane** (metric-explorer: saved-views + picker + chart)
+   and **chart-over-grid** (trap-viewer, log dashboard) to single / two-pane / master-detail / dashboard-grid.
+5. **Two wizard shapes** — multi-route stateful (report builder, network discovery) vs single-view stepped
+   (integration setup). Plus a **stateless utility-tool form** family (settings/utility) and **system/status
+   message** pages.

package/foundation/layout-shells.md

@@ -0,0 +1,67 @@
+# Layout shells — product coverage
+
+The outer page frame. Source: `src/views/layouts/`. The shell is chosen by the switcher in
+`src/app.vue` (watch on `$route`): if not logged in → **LoginLayout**; otherwise default **Layout**;
+then the first `route.matched[].meta.layout` override wins.
+
+## The variants
+
+### Route shells (4 — selected by `meta.layout`)
+
+| Shell | File | Chrome | Selected when |
+| --- | --- | --- | --- |
+| **Layout** (default) | `views/layouts/main.vue` | NavBar (left) + Header (top) + scrolling content + overlay layer (OmniBox, notifications, portals, DB/socket) | every authenticated route with no override |
+| **LoginLayout** | `views/layouts/login-layout.vue` | bare — centered, no chrome, no socket | `meta.layout: 'LoginLayout'` **and** the not-logged-in fallback |
+| **EmptyLayout** | `views/layouts/empty-layout.vue` | no nav/header, padded; keeps socket + local DB | `meta.layout: 'EmptyLayout'` |
+| **PublicLayout** | `views/layouts/public-layout.vue` | no chrome; socket with `isMotadataUpdatingOrRestoring` | `meta.layout: 'PublicLayout'`, `public: true` |
+
+Observed route overrides (excluding chart-layout props): **LoginLayout ×3 · PublicLayout ×2 · EmptyLayout ×1**;
+everything else inherits the default **Layout**.
+
+### Content layouts (rendered *inside* `Layout` — not route shells)
+
+| Layout | File | What |
+| --- | --- | --- |
+| **MonitorHierarchyLayout** | `views/layouts/monitor-hierarchy-layout.vue` | two-pane: collapsible/affixable left **hierarchy tree** + right content. **0 route overrides; used as a component in 4 files.** |
+| **Settings two-pane** | `modules/settings/views/main.vue` | `splitpanes` (library) draggable split: left **menu** (15%, `MCollapse`+`MMenu`) + right `RouterView` (85%); hidden via `meta.hideSettingsMenu` |
+
+## Where it's used in the product
+
+| Shell | Pages / flows (files) |
+| --- | --- |
+| **Layout** | All of inventory, alert, dashboard, topology, ncm, netroute, slo, reports, audit, the explorers, and settings. The product's default. |
+| **LoginLayout** | `auth/views/login.vue`, `auth/views/reset-password.vue`, the forgot-password modal (in login), and the `views/errors/_disk-space-full.vue` page. |
+| **EmptyLayout** | `/reports/export/:id` — the print-safe report renderer (`views/print/report-renderer.vue`). Chrome-free so PDF/print output is clean. |
+| **PublicLayout** | `/upgrade` and `/restore` system pages (`views/upgrade-restore/upgrade-restore-progress.vue`) — full-screen maintenance progress. |
+| **MonitorHierarchyLayout** (content) | `modules/log/views/main.vue` (log explorer tree), inventory monitor hierarchy, topology (tree + graph), + 1 more. |
+| **Settings two-pane** (content) | `modules/settings/views/main.vue` — wraps every settings submodule. |
+
+## Coverage verdict
+
+- **All four route shells are catalogued and fully covered.** No 5th/6th route shell exists.
+- **Correction:** the Storybook "Layout shells" page and `layout/layouts.json` list **MonitorHierarchyLayout**
+  among the five shells. It is **not** a route shell (0 `meta.layout` overrides) — it's a two-pane **content
+  layout** component. The doc should present **4 route shells + 2 content layouts** (MonitorHierarchyLayout,
+  Settings two-pane). Functionally still covered; the *classification* is the fix.
+
+## Notable / different findings
+
+- **The switcher is auth-aware**, not purely meta-driven: unauthenticated always forces LoginLayout
+  regardless of the target route's meta (`app.vue` lines ~63–76).
+- **Settings two-pane uses the `splitpanes` library** (genuinely drag-resizable), distinct from the
+  CSS/transition sidebars elsewhere — the only first-class resizable split in product chrome besides topology.
+- **`MonitorHierarchyLayout` sidebar can be affix + collapsible simultaneously** (`affixed-sidebar` →
+  absolutely-positioned overlay that doesn't reflow the grid) — a hybrid not captured by "sticky" or
+  "collapsible" alone.
+- **`hideSettingsMenu` route meta** full-screens settings create/edit forms by collapsing the left menu —
+  a per-route content-layout toggle.
+
+## Best practices
+
+- Don't override the shell unless required — **Layout** is right for almost every authenticated page.
+- **Auth screens must use LoginLayout** (no socket/DB boot). **Print/export → EmptyLayout.** **System
+  maintenance → PublicLayout.**
+- Reach for **MonitorHierarchyLayout** when a module needs a persistent left tree + detail; use the provided
+  context (`hideHierarchy()` / `showHierarchy()`) to toggle it.
+- For configuration modules, follow the **Settings two-pane** pattern (left menu + content, `hideSettingsMenu`
+  on full-screen forms) rather than inventing a new sidebar.