@mtdt/observeops-ds-spec 0.1.0

package/components/specs/select.md

@@ -0,0 +1,118 @@
+# Select (`MSelect`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom (form control) |
+| **Maturity** | ⚠️ **Low-use** (2×) — the product's standard select is `FlotoDropdownPicker` |
+| **Source** | `@motadata/ui` → `ui/components/Select/Select.vue` (wraps Ant `a-select`) |
+| **Storybook** | `Atoms/Select` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/select.json`](../registry/select.json) |
+| **Family** | select cluster — `FlotoDropdownPicker` (the real select) · `LooseTags` · `MTreeSelect` · this |
+| **Figma** | N/A (low-use; build `DropdownPicker` instead) |
+
+## Usage (product analytics)
+
+- **`<MSelect>` used 2×** — both `mode="tags"` (in `LooseTags` and `object-tag-picker`).
+- **`FlotoDropdownPicker` used 510×** — the de-facto select. **Use that**, not MSelect.
+- `MTreeSelect` 0× · `MSelectOption`/`OptGroup` 0× direct.
+
+## Overview
+
+The kit's raw **Ant `a-select`** wrapper. Full-featured (modes, search, clear, sizes,
+loading), but the product standardized on `FlotoDropdownPicker` instead — so MSelect survives
+only as the low-level primitive behind a couple of tag inputs. Documented for completeness;
+**reach for `FlotoDropdownPicker`** for an actual select. v-model is `value` + `change`.
+
+## Options / API
+
+- **`mode`** — `default` (single) · `multiple` (chips) · `tags` (free-type to create) · combobox.
+- **`options`** — `{ value, text }` (label resolves `text||label||title||name`); or slot options.
+- **`showSearch`** (default false) · **`allowClear`** (default **true**) · **`size`**
+  (small/default/large) · **`loading`** (chevron → spinner) · `disabled` · `maxTagCount` ·
+  `labelInValue` · `filterOption` (default case-insensitive on label) · `tokenSeparators`.
+- **Slots:** default/`option` · `suffixIcon` · `clearIcon` · `removeIcon` ·
+  `menuItemSelectedIcon` · `notFoundContent` (→ `MNoData`) · `dropdownRender`.
+- **Emits:** `change` (model) · `search` · `select` · `deselect` · `blur` · `focus` · more.
+
+## Behaviors
+
+- **Single/multiple/tags** like Ant. **Multiple/tags** render removable chips in the field.
+- **Search** (`show-search`) filters options on the label; empty → `MNoData`.
+- **Loading** swaps the chevron for a spinner.
+
+## Accessibility
+
+- Built on Ant `a-select` → it **IS a real combobox** (`role`, `aria-expanded`,
+  `aria-activedescendant`, listbox/options, keyboard open + type-ahead). **Notably, this
+  low-use component is *more* accessible than the 510×-used `FlotoDropdownPicker`** (which has
+  no combobox semantics — [SF-003](../../findings/SF-003-combobox-a11y.md)). A good reference
+  for what fixing SF-003 should achieve.
+- ⚠️ No visible focus ring system-wide ([SF-001](../../findings/SF-001-focus-visible.md)).
+
+## Findings & Inconsistencies
+
+### F1 — Superseded by `FlotoDropdownPicker` · Medium · Documented
+
+The product chose the custom `FlotoDropdownPicker` (510×) over MSelect (2×) — likely for the
+virtualized menu, custom triggers, and inline-add. So MSelect is effectively legacy/low-level.
+**Solution:** use `FlotoDropdownPicker` for selects (and `LooseTags` for tag inputs); keep
+MSelect only as the Ant primitive. Don't expand its usage.
+
+### F2 — The accessible select is the unused one · Medium · Open *(a11y, ironic)*
+
+MSelect (Ant) has proper combobox a11y; the widely-used `FlotoDropdownPicker` does not
+([SF-003](../../findings/SF-003-combobox-a11y.md)). **Solution:** when fixing SF-003, mirror
+Ant `a-select`'s ARIA — or, longer term, consider consolidating onto an accessible base.
+
+### F3 — No visible focus ring · High · Open *(a11y)* → [SF-001](../../findings/SF-001-focus-visible.md)
+
+System-wide.
+
+### F4 — Clear "×" is invisible (icon prefix mismatch) · Low · Open
+
+`Select.vue` hardcodes the clear icon as **`<MIcon name="times-circle" type="fas">`** (Font
+Awesome **solid**), but the product registers **only `fal` (light)** icons (639 `fal`, 0 `fas`
+in `icons.js`). So `fas times-circle` isn't in the library and the clear control renders
+**empty** (`<i class="ant-select-clear-icon"><!----></i>`, no svg) — the **clear × is blank**.
+The chip **remove** × works (it uses `name="times"`, default `fal`). (`type="fas"` is used 3×:
+`Select.vue`, `TreeSelect.vue`, `navbar.vue` — all latently broken.) **Solution:** drop
+`type="fas"` (use the default `fal`), or register the `fas` solid set.
+
+### F5 — Clear "×" overlaps the dropdown chevron · Low · Open
+
+When `allow-clear` shows the clear control, it sits **on top of** the custom `suffixIcon`
+chevron (both absolutely positioned at the same right edge). Ant's clear masks the *default*
+arrow with a white box, but MSelect's **custom chevron `MIcon` is wider** than that box, so the
+chevron's left edge **pokes out beside the ×** (measured: chevron `left 123`, clear box
+`left 129` — single; same in multiple). Result: the close icon appears *over/beside* the
+dropdown icon. **Solution:** hide `.ant-select-arrow` while the clear is shown, or size the
+clear mask to the custom chevron. **Net (F4+F5): MSelect's clear-all affordance is broken** —
+low impact (MSelect is 2×, both `mode="tags"`, never with `allow-clear`). The catalog stories
+therefore omit `allow-clear` and show removal via the working chip ×; for a clearable select
+use **`FlotoDropdownPicker`**.
+
+## Do / Don't
+
+### Do
+
+- For a real select, use **`FlotoDropdownPicker`** (single/multi/search/virtualized/custom trigger).
+- For a free-form tag input, use **`LooseTags`**.
+- Use MSelect only as the low-level Ant primitive when something specifically needs raw `a-select`.
+
+### Don't
+
+- Don't introduce new `MSelect` usages as "the select" — that's `FlotoDropdownPicker`.
+- Don't reach for `mode="tags"` here — use `LooseTags`.
+
+## Related
+
+`FlotoDropdownPicker` (the product select) · `LooseTags` (tag input) · `MTreeSelect` (tree) ·
+`MSelectOption`/`MSelectOptGroup` · `FlotoFormItem` (wrap it for label + validation).
+
+## Changelog
+
+- **2026-06-07** — Added (badged **low-use**, decision-grade Usage). Deep-dive of `Select.vue`:
+  Ant `a-select` wrapper — modes (default/multiple/tags), `show-search`, `allow-clear` (default
+  true), sizes, loading, rich slots (`notFoundContent` → `MNoData`); v-model `value`/`change`.
+  Verified single/multiple/tags render. Findings F1 (superseded by DropdownPicker, 2× vs 510×),
+  **F2** (ironically the *accessible* combobox vs SF-003), F3 (focus → SF-001).

package/components/specs/switch.md

@@ -0,0 +1,124 @@
+# Switch (`MSwitch`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom |
+| **Maturity** | 🟢 Stable (core) — open a11y findings (F3, F4) |
+| **Source** | `@motadata/ui` kit → `ui/components/Switch/Switch.vue` (wraps Ant `a-switch`). Not overridden; not excluded. |
+| **Storybook** | `Atoms/Switch` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/switch.json`](../registry/switch.json) |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<MSwitch>` used 136× across 88 files.**
+- `size="small"` ~76 (approx, shared prop). checked/unchecked **label slots: 0 files** (unused).
+
+## Overview
+
+An **instant** on/off toggle for a setting (applies immediately — no Save). Wraps Ant
+`a-switch`; **controlled** (bind `v-model` / `:checked`).
+
+## Anatomy
+
+```text
+  off:  ◖○────────◗   gray knob, white track
+  on:   ◖────────●◗   green knob, white track   ← track color unchanged; knob signals state
+```
+
+Track · knob (gray→green) · optional `#checked` / `#unchecked` label slots (unused).
+
+## Options / States
+
+- **Sizes:** `default` (22×44px) · `small`.
+- **States:** off · on · disabled · loading (controlled via `:checked`/`v-model`).
+
+**Context re-check (2026-06-07):** swept all switch styling (kit override, `form.less`,
+`table.less`, `input.less`) for hidden/context variants like Radio's segmented set. Result:
+**none** — no consumer `*-switch` classes exist, and the table/form rules only set the track
+token (`--switch-bg`) + alignment. The track stays static (`--switch-bg`/white) in both states;
+only the knob colors green (verified: track `#fff`, knob `#14b053`) — this is product-accurate
+(F2). The switch surface is complete (no segmented/variant explosion).
+
+## Behaviors
+
+- **Controlled:** always reflects `:checked`; toggling emits `change(value)`.
+- **Loading:** `:loading` shows a spinner in the knob during async persistence.
+- **Track is static color:** only the knob changes (gray off → green on) + slides position.
+
+## Content & writing
+
+Pair with a label naming what turns on ("Enable notifications"). On/off text slots exist
+but the product doesn't use them.
+
+## Accessibility
+
+- **Semantics:** `role="switch"`; Space/Enter toggle. ✅
+- **State:** `aria-checked="true"` when on ✅; **missing when off** (F4).
+- **Target size:** ~22px tall — below the 44–48px touch target (F5).
+- **Focus:** no visible focus ring (F3).
+- **Theming:** track/border theme in dark (`#fff→#172336`); knob colors (`#a5bad0` off,
+  `#14b053` on) are static but read acceptably in both themes.
+
+## Props / API
+
+`checked` (v-model) · `size` (default/small) · `disabled` · `loading` · `defaultChecked`
+(**no-op — F1**) · `autoFocus`. Slots `checked` / `unchecked`. Emits `change`.
+Machine spec: [`../registry/switch.json`](../registry/switch.json).
+
+## Design tokens used
+
+Kit LESS vars (static): `@white` (track) · `@neutral-light` (off knob/border) ·
+`@secondary-green` (on knob). Track/border also pick up CSS-var theming in dark.
+
+## Findings & Inconsistencies
+
+### F1 — `defaultChecked` is a no-op · Medium · Open
+
+`MSwitch` always passes `:checked` (default `false`) to `a-switch`, which overrides
+`:defaultChecked` → the switch never starts on via `defaultChecked`. **Solution:** use
+`:checked`/`v-model`; or in the kit, don't bind `:checked` when uncontrolled. Document
+that `defaultChecked` does nothing.
+
+### F2 — Track color doesn't change; state is knob-color-only · Medium · Open
+
+Off and on share the same (white/dark) track; only the knob color (gray→green) + position
+differ. Subtler than a track-fill switch and leans on color. **Solution:** confirm intent;
+consider a checked **track** fill (e.g. `--severity-clear` tint) for a stronger signal.
+
+### F3 — No visible focus indicator · High · Open *(a11y)* → see SF-001
+
+`outline: none`, no focus shadow (WCAG 2.4.7). **System-wide** — tracked as
+[SF-001](../../findings/SF-001-focus-visible.md); fix once globally.
+
+### F4 — `aria-checked` absent in the OFF state · Medium · Open *(a11y)*
+
+On exposes `aria-checked="true"`; off is null → AT may not announce "off". **Solution:**
+ensure `aria-checked="false"` is set when unchecked.
+
+### F5 — 22px height below touch target · Low · Open *(a11y)*
+
+**Solution:** ensure ≥44px hit area (padding) on touch surfaces.
+
+## Do / Don't
+
+### Do
+
+- Use for **immediate** on/off settings; show `:loading` while persisting.
+- Control via `v-model` / `:checked`.
+
+### Don't
+
+- Don't use a switch in a form that needs explicit Save (use `MCheckbox`).
+- Don't rely on `:defaultChecked` (F1).
+
+## Related components
+
+`MCheckbox` (needs Save) · `MRadio` (mutually exclusive).
+
+## Changelog
+
+- **2026-06-05** — Added (Playground · States · Sizes).
+- **2026-06-06** — Full deep-dive: examples fixed to `:checked` (F1); on/off rendering
+  measured (white track + gray→green knob, light/dark). Enhanced standard + Option B pages;
+  a11y findings F3 (focus ring) + F4 (off-state aria-checked) + F5 (target size).

package/components/specs/table.md

@@ -0,0 +1,115 @@
+# Table / Grid (`MGrid`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Organism |
+| **Maturity** | 🟢 Stable |
+| **Source** | `src/components/crud/_base-grid.vue` (**MGrid**) — wraps the **Kendo Vue Grid** (`@progress/kendo-vue-grid`) + `gridWorker` / `arrayWorker`. Fetch+paginate wrapper: **`FlotoPaginatedCrud`**. |
+| **Storybook** | Organisms/Table |
+| **Registry** | [`registry/table.json`](../registry/table.json) |
+| **Family** | [Data Table](../family-map.md) |
+
+## Usage analytics
+
+- **MGrid 75×** across 69 files · **FlotoPaginatedCrud 76×** (the usual driver). Top modules:
+  settings, apm, ncm, slo, alert — i.e. **every list / inventory / drill-down view**.
+- States in the wild (from the sweep): **expandable** 8× · **selectable** 7× · `hide-selection-info`
+  5× · `disable-pre-selected-item` 4× · grouping (`default-group`). Classes: `hide-expand-column`
+  (6×), `hide-header`, `hide-grouping`, `tabular-content-grid`, `service-grid`, `rum-grid`.
+
+## Overview
+
+The product's **primary data table**. `MGrid` wraps the Kendo grid and offloads sort/filter/group/
+page to web workers; **`FlotoPaginatedCrud`** wraps `MGrid` to own fetch + paging + search + filters
+for list pages. Features: resizable / reorderable / sortable columns, **client + server paging**,
+**grouping**, **selection** (→ bulk-action bar), **expandable detail rows**, and **per-column cell
+slots**. For a few static key/values, use a list/cards instead.
+
+## Anatomy
+
+- **Header** — column titles on `--grid-header-bg`; sortable, resizable, reorderable. Optional
+  select-all checkbox.
+- **Rows** — `--border-color` bottom divider; **hover** highlight; **selected** = `--neutral-lightest`
+  + a `--primary` left accent; optional **detail row** (expand); optional **group header** rows.
+- **Footer** — pager (range + page controls) when `paging`.
+- **Selection tag** — "N items selected" (`MTag`) above the grid unless `hide-selection-info`.
+
+## Options (key props)
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `columns` | — | column defs (field/title/width/cell/sortable) |
+| `data` | — | rows (client mode) |
+| `selectable` | `false` | checkbox column + selection |
+| `expandable` | `false` | chevron + `detailRow` slot |
+| `paging` / `default-page-size` | `false` / `50` | client paging |
+| `external-take` / `external-skip` / `total-count` | — | **server paging** |
+| `default-sort` / `default-group` | — | initial sort / grouping |
+| `filters` / `search-term` / `use-search-term-loading` | — | filtering / search (+ spinner) |
+| `max-allowed-selection` / `pre-selected-items` / `selection-disabled-items` / `disable-pre-selected-item` | — | selection control |
+| `hide-selection-info` | `false` | hide the "N selected" tag |
+| `row-height` | — | virtualization (non-paging) |
+
+## Behaviors
+
+- **Workers:** sort/filter/group/page run in `gridWorker`/`arrayWorker`; the grid shows a
+  `FlotoContentLoader` while `processingData`.
+- **Server vs client:** `external-*` + `total-count` + `@data-state-change` = server-side; otherwise
+  the grid pages/sorts in memory.
+- **Columns:** resizable + reorderable; `@column-change` persists layout. Some columns are
+  sort-disabled (`SORT_DISABLED_COLUMNS`).
+
+## Content & writing
+
+- Column titles short and consistent; empty → **"No records found"**.
+
+## Accessibility
+
+- Verify Kendo grid + **custom cell slots** keep table roles (`row`/`columnheader`/`gridcell`),
+  **`aria-sort`** on sortable headers, **`aria-selected`** on selected rows, an accessible
+  select-all, and **focus rings** on cell controls (SF-001). Announce empty/loading via a live
+  region. See the Accessibility page (**F2**).
+
+## Props / API
+
+See the table above and [`registry/table.json`](../registry/table.json).
+
+## Design tokens used
+
+`--grid-header-bg` · `--border-color` · `--neutral-lightest` (selected) · `--neutral-lighter`
+(group header) · `--primary` (selected accent) · `--neutral-dark` (header text) ·
+`--page-background-color`.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Open | Heavy: Kendo grid + 2 web workers — not trivially renderable outside the app (Storybook shows **reproductions**, not the live grid). |
+| F2 | Medium (a11y) | Open | Verify table roles / `aria-sort` / `aria-selected` / focus survive the Kendo grid + custom cell slots. |
+
+## Recommended solutions
+
+- **F1:** keep the catalog as faithful reproductions; if a live grid is wanted later, sandbox the
+  Kendo grid with mocked workers in a dedicated story.
+- **F2:** audit the rendered grid for ARIA (sort/selected/roles) and adopt the SF-001 focus ring on
+  cell controls.
+
+## Do / Don't
+
+- **Do** use `FlotoPaginatedCrud` for fetched lists; server-page large data; row actions in a kebab;
+  multi-select via the bulk bar; keep the header in empty/loading.
+- **Don't** use a grid for a few static key/values; don't client-load huge datasets; don't
+  hand-roll selection/sorting/paging.
+
+## Related components
+
+`FlotoPaginatedCrud` · `FlotoGridActions` (row kebab) · bulk-action bar · `MStatusTag` / `MTag`
+(cells) · `MCheckbox` (selection) · `FlotoDropdownPicker` (filters).
+
+## Changelog
+
+- **2026-06-12** — Added (decision-grade Usage). `/component-sweep` on `MGrid` (75×) +
+  `FlotoPaginatedCrud` (76×): Kendo grid + workers; states selectable/expandable/grouping/paging;
+  per-column cell slots. 8 reference-reproduction stories (Basic · Selectable · Expandable · Cell
+  types · Grouping · Empty · Loading · Pagination) on the real `table.less` chrome; verified render
+  + the selected-row accent. Findings F1 (heavy/reproductions), F2 (a11y).

package/components/specs/tabs.md

@@ -0,0 +1,136 @@
+# Tabs (`MTab` / `MTabPane`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule |
+| **Maturity** | 🟢 Stable |
+| **Source** | `ui/components/Tabs/Tab.vue` (`MTab` — wraps Ant `a-tabs`) + `ui/components/Tabs/TabPane.vue` (`MTabPane`). Persisted state: `src/components/_base-persisted-tab.vue` (`MPersistedTab` — renderless). |
+| **Storybook** | Molecules/Tabs |
+| **Registry** | [`registry/tabs.json`](../registry/tabs.json) |
+| **Family** | [Navigation / Tabs](../family-map.md) |
+
+## Usage analytics
+
+- **86×** across **70** files. Top areas: `settings` (20), shared `components` (17), `rum` (7),
+  `alert` (5), `log` (4), `apm` (3).
+- **Always line / top / default.** No real `<MTab>` passes `type=`, `position=`, or `size=` — so
+  despite Ant supporting **card / editable-card** types, **vertical** position, **size** variants,
+  and a **`tabBarExtraContent`** slot, the product uses **none** of them.
+- **Variant classes (the real API):** **`no-border`** (21×, dominant) · **`sticky-tab`** (8×) ·
+  `topology-hierarchy-tab` (3×, icon-only) · `metric-picker-tabs` (1×) · `grey-tab` (defined, ~0) ·
+  `flex-tabs` (content flex helper).
+- **Label patterns:** **count appended to the label string** (`Alerts (${count})`,
+  `${tab.title} (${getCounts(tab)})`) — *not* a separate badge; **leading icon** via the pane's
+  `tab` slot; **dynamic** `v-for` over a tabs config array.
+
+## Overview
+
+In-page **tabbed navigation** that switches between **sibling views of one context** (Overview /
+Performance / Logs of a monitor; Attributes / Metric / Style of a widget editor). `MTab` wraps Ant
+`a-tabs` and applies its `variant` prop **as a CSS class**; panes are `MTabPane`. For page-to-page
+navigation use the router/menu, not tabs.
+
+## Anatomy
+
+- **Tab bar** — the strip of tab triggers; bottom border `--border-color` (removed by `no-border`).
+- **Tab trigger** — active = `--primary` text + a `--primary` underline/ink bar; inactive =
+  `--tabs-text-color`; disabled = `--neutral-light`.
+- **Tab pane** (`MTabPane`) — the content for the active key; label via the `tab` prop or `tab` slot.
+
+## Options (props)
+
+### `MTab`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `value` | — | active key; `v-model` via `@change` (41× bind change) |
+| `variant` | `''` | applied as a **class** on `a-tabs` — e.g. `no-border` |
+| `defaultActive` | — | `defaultActiveKey` when uncontrolled |
+| `animated` | `false` | slide animation between panes |
+| `size` | `default` | **unused** in product |
+| `position` | `top` | `tabPosition`; **unused** beyond `top` (no vertical tabs) |
+| `type` | `line` | **unused** beyond `line` (no card/editable-card) |
+| `tabBarGutter` / `tabBarStyle` | — | spacing / inline style of the bar |
+
+### `MTabPane`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `tab` | — | the label **string** (use the `tab` **slot** for icon/count markup) |
+| `key` | — | the pane key — matches `MTab` `value` |
+| `forceRender` | `false` | render content even when the pane is inactive |
+
+### `MPersistedTab` (renderless)
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `moduleKey` | **required** | localStorage key → `${moduleKey}-tab` |
+| `useLocalStorageTab` | `true` | persist the active tab |
+| `defaultValue` / `value` | — | initial tab when nothing is stored |
+
+Exposes a **scoped slot** `{ tab, setTab }` — wire to `<MTab :value="tab" @change="setTab">`.
+
+## Behaviors
+
+- **Controlled** via `value` + `@change` (the dominant pattern) or **uncontrolled** via
+  `defaultActive`.
+- **`no-border`** drops the bar's bottom rule (tabs on a card). **`sticky-tab`** pins the bar to the
+  top of a scroll container (`position:sticky; top:0; background:var(--page-background-color)`).
+- **`MPersistedTab`** remembers the active tab across reloads/navigation in localStorage; its sibling
+  **`MPersistedColumns`** does the same for grid columns.
+
+## Content & writing
+
+- Short noun labels (Overview, Performance, Logs). Append a count as `Label (N)` when it helps the
+  user gauge volume. Don't sentence-case or punctuate labels.
+
+## Accessibility
+
+- **Provided by Ant `a-tabs`:** `role="tablist"` / `role="tab"` / `role="tabpanel"`,
+  **`aria-selected`** on the active tab, and **Left/Right arrow-key** navigation between tabs.
+- **Verify:** keyboard **focus visibility** on the tab triggers (catalog-wide **SF-001**
+  `:focus-visible` ring); and that **icon-only** tabs carry a meaningful accessible name.
+
+## Design tokens used
+
+`--primary` (active text + underline + ink bar) · `--tabs-text-color` (inactive) · `--border-color`
+(bar) · `--page-background-color` (sticky bg) · `--neutral-light` (disabled / prev-next) ·
+`--neutral-lightest` (`grey-tab` bar).
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low (a11y) | Open | Catalog-wide focus-ring removal (**SF-001**) may suppress the tab trigger's `:focus-visible` outline — verify keyboard focus is visible. |
+| N1 | Info | — | Ant offers card/editable-card/vertical/size/`tabBarExtraContent`; the product uses none. Treat any of these as a **new pattern** requiring a deliberate decision, not a default. |
+
+## Recommended solutions
+
+- **F1:** adopt the shared `:focus-visible` ring (SF-001) so tab triggers show a visible focus state.
+- **N1:** keep the line/top/default constraint unless a product need justifies a new tab style; if
+  introduced, add it to this spec + a story so it's a documented variant, not an ad-hoc divergence.
+
+## Do / Don't
+
+- **Do** use tabs for sibling views of one context; use `no-border` on cards; `sticky-tab` on long
+  panes; append `(N)` counts; build data-driven sets with `v-for`; use `MPersistedTab` for
+  remembered tabs.
+- **Don't** use tabs for page navigation; don't introduce card/vertical/closable tabs without a
+  decision; don't build a separate count badge; don't depend on `tabBarExtraContent` to match the
+  product.
+
+## Related components
+
+`FlotoDropdownPicker` (select) · `MGrid` / Table (tabbed detail panes often sit above a grid) ·
+`MRadioGroup` `as-button` (a *segmented* control — a different "pick one" pattern, not view tabs).
+
+## Changelog
+
+- **2026-06-15** — Added (decision-grade). Deep-dive of `MTab`/`MTabPane` (86× / 70 files) + the
+  renderless `MPersistedTab`. Established the **line/top/default-only** fidelity rule (no real usage
+  passes type/position/size) and the class-based variant API (`no-border` 21×, `sticky-tab` 8×).
+  Stories built with the **real** `MTab`/`MTabPane`: Basic · No border · Sticky · With counts ·
+  Dynamic · With icons · Persisted. Verified the active indicator renders **`--primary` navy**
+  (`rgb(17,28,44)`, text + underline + ink bar), interactivity (click switches panes), and no console
+  errors; caught + fixed a blank `map` icon (not in the 543-set → `sitemap`). Finding F1 (focus ring
+  → SF-001).