@mtdt/observeops-ds-spec 0.1.0

package/AGENTS.md

@@ -0,0 +1,102 @@
+# ObserveOps Design System — AI Operating Contract
+
+**Read this first.** Any AI tool building UI for Motadata ObserveOps (pages, layouts, flows,
+prototypes, components) MUST follow this contract. It points you at the machine-readable spec and sets
+the rules. The goal: output that looks and behaves like ObserveOps, built **only** from this design
+system — never guessed.
+
+## How to load the spec (read order)
+
+1. **`components/index.json`** — the entry point. Lists every component (family, `selectHint`,
+   `summary`, `variants`), the token pointers, `recipes`, and `layout`. Start here.
+2. **`components/registry/<name>.json`** — the machine spec for a component: `props` / `events` /
+   `slots` / `apis`, `decisionFlow`, `variants`, `sizes`, `states`, `do` / `dont`, `tokensUsed`,
+   `a11y`, `knownIssues`.
+3. **Tokens** — `tokens/variables.json` (runtime `--vars`, light/dark) + `tokens/structural.json`
+   (LESS `@vars`: spacing/sizing/radius/type) + `tokens/kit-accents.json` (`@primary-color`).
+   For a NEW element, use **`tokens/purpose-map.json`** (purpose → token).
+4. **Composition** — `components/recipes/recipes.json` (7 page templates + 5 flows, region →
+   component) and `layout/layouts.json` (shells, screen regions, content layouts, panel behaviours) +
+   `layout/grid.json` (the 12-col grid).
+5. **Product coverage** — `foundation/*.md` (which product pages/flows use each layout element) when
+   you need real-world grounding.
+
+## Hard rules (MUST)
+
+1. **Components:** use only catalogued components (`index.json`). Pick with `selectHint` /
+   `decisionFlow`. Do not invent a component or pull one from another library.
+2. **Configuration:** configure only with the documented `props` / `events` / `slots` / `apis` in the
+   registry. Do not invent prop names.
+3. **Colour & spacing:** resolve every colour/space from tokens — `variables.json` /
+   `purpose-map.json` / `structural.json`. **Never hardcode a hex, rgb, rgba, or hsl.** Brand / primary
+   action = `--primary` (navy, NOT cyan). The cyan `@primary-color` (#099dd9) is the Ant form-control
+   accent only (radio dot, checkbox check, select).
+4. **Token system:** emit only runtime `--vars` (from `variables.json` / `structural.json` /
+   `kit-accents.json`). **Do NOT emit `mds-*` tokens** — that layer is future/portable and not wired to
+   the running product.
+5. **Composition:** build pages from `recipes` (templates + flows) and `layout` (pick the right shell,
+   screen regions, content layout, panel behaviour). Forms use the 12-col `MRow`/`MCol` grid (6 = half,
+   12 = full, gutter 16). Recipes are **examples**, not an allow-list — if no recipe matches, compose
+   the screen from catalogued components + tokens + layout (see "Compose by default" below).
+6. **Theme:** never branch on light/dark — every token is already theme-aware.
+7. **Accessibility:** honour each component's `a11y` field (keyboard, naming/aria, the known gaps).
+
+## Compose by default — ASK only for a missing building block
+
+The DS gives you **building blocks** (components in `index.json`, tokens, layout primitives) and
+**example recipes** (common compositions). Recipes are EXAMPLES, not an allow-list of permitted
+screens. Two very different situations — don't confuse them:
+
+**1. A screen/flow with no matching recipe → just BUILD it (compose).**
+Signup, change-password, a custom settings page, a new wizard, any page we never documented — build
+it by composing catalogued components + tokens + layout. A missing recipe is **not** a reason to
+stop; composing existing parts into new screens is exactly what the DS is for, and is always allowed.
+You may briefly note your assumptions for transparency ("no documented recipe for signup; composed
+from LoginLayout + input + form-item + button + checkbox + link"), then build. Do not ask permission
+to compose.
+
+**2. You'd need a building block that ISN'T in the DS → STOP and ASK.**
+Only when building would force you to use something **not catalogued** — a component archetype absent
+from `index.json` (e.g. a chart/graph/topology canvas), a colour/token outside the palette
+(`variables.json` / `purpose-map.json`), or any primitive the DS lacks. Then **do not substitute,
+invent, or import from another library.** Ask first, stating:
+
+1. what you are building,
+2. the missing building block you needed,
+3. what you checked in the DS (which `index.json` families / `decisionFlow` / `purpose-map`),
+4. why no catalogued block covers it,
+5. the external thing you propose to use instead.
+
+Then wait for approval. **The line:** never pick a component or colour from OUTSIDE the DS without
+asking — but never ask permission to combine parts already INSIDE it. Silent use of a non-DS building
+block is the contract violation; composing DS parts into an undocumented screen is not.
+
+## Known gaps — missing building blocks (these DO require an ASK)
+
+- **Charts / data-viz / widget tiles / topology graph** — only the *tooltips* are catalogued
+  (`data-viz-tooltips`). The chart/graph components themselves are **not** in the DS yet. A
+  dashboard/chart/topology task → ask before improvising. Recipes self-flag these: any region with a
+  **`$gap`** field (and `recipes.json` → `$knownGaps`) marks a layer not in the DS — treat it as a
+  hard STOP-and-ASK.
+- **Figma library** — not built. Figma-native generation isn't supported yet.
+
+## Output rules
+
+- Real component usage: `@motadata/ui` (`M*`), Floto wrappers (`Floto*`), Ant Design Vue 1.x (`a-*`),
+  `_base-*` globals — Vue 2.6.
+- Colours via `var(--token)`; layout via `MRow`/`MCol`; forms via `FlotoForm` / `FlotoFormItem`.
+- **Cite your sources:** for each part, name the DS component / recipe / token you used (e.g.
+  "list-view recipe · Organisms/Table · `--page-text-color`").
+- **Storybook is the VISUAL reference, not a data source:** the live catalogue (URL in `llms.txt`)
+  shows the pixel-accurate look to match and is for human/visual verification — but take ALL specs from
+  these JSON/MD files. Do NOT scrape the Storybook site for props/tokens (it's a gated JS app; the
+  structured spec here is the source of truth).
+
+## Self-check before you finish
+
+- [ ] Every component is from `index.json` (none invented / from another library).
+- [ ] Every colour/space is a token — zero hardcoded hex/rgba.
+- [ ] No `mds-*` tokens emitted.
+- [ ] The page is composed from a recipe + the right layout shell/regions.
+- [ ] a11y honoured (labels, keyboard, aria).
+- [ ] Any deviation was **asked**, not guessed.

package/README.md

@@ -0,0 +1,73 @@
+# @mtdt/observeops-ds-spec
+
+The **machine-readable spec + AI operating contract** for the Motadata ObserveOps design system.
+Install it so any AI tool (Cursor, Claude Code, Windsurf, Copilot, Cline, …) can build ObserveOps UI
+from the real components, tokens, recipes and layout — instead of guessing.
+
+This package is the **machine-readable truth**. The companion **Storybook** is the **visual truth**
+(see the catalogue link below) — use it to *match* the look; get all specs from the files here.
+
+## Install
+
+```bash
+npm install @mtdt/observeops-ds-spec
+```
+
+## For an AI tool — read in this order
+
+1. [`AGENTS.md`](./AGENTS.md) — the **operating contract** (read first): use only catalogued
+   components, resolve every colour to a token, compose pages from recipes/layout, and STOP-and-ASK
+   before using anything not in this DS.
+2. [`llms.txt`](./llms.txt) — discovery entry point (links every part of the spec).
+3. `components/index.json` — the machine index (all components, families, token pointers).
+4. `components/registry/<id>.json` — per-component props/events/slots/apis, variants, tokens, a11y.
+5. `components/recipes/recipes.json` — page templates + flows (how to compose whole screens).
+6. `layout/` + `tokens/` + `foundation/` — structure, the token crosswalk, and product coverage.
+
+Point your tool's rules file at the contract, e.g. in `.cursor/rules` or your project `AGENTS.md`:
+
+```text
+Follow node_modules/@mtdt/observeops-ds-spec/AGENTS.md when building any ObserveOps UI.
+```
+
+## For code — the thin loader
+
+```js
+const ds = require('@mtdt/observeops-ds-spec')
+
+ds.version                       // spec version
+ds.index                         // components/index.json (parsed)
+ds.getComponent('button')        // index entry + full registry spec
+ds.resolveToken('--primary')     // { light: '#111c2c', dark: '#e3e8f2', ... }
+ds.resolveToken('@btn-radius')   // '4px'
+ds.listRecipes()                 // [{ id, name, whenToUse }, ...]
+ds.specPath('llms.txt')          // absolute path, for tools that read raw files
+```
+
+Deep imports work too: `require('@mtdt/observeops-ds-spec/components/registry/drawer.json')`.
+
+## What's inside
+
+- `components/` — `index.json`, `registry/` (26 components), `recipes/recipes.json`, `specs/` (prose).
+- `tokens/` — the **live** layer (`variables.json` 336 themed CSS vars, `structural.json` LESS vars,
+  `kit-accents.json`, `purpose-map.json`) **+** a **future/portable** DTCG layer
+  (`primitive` / `semantic.*` / `component.json`, `mds-*`) flagged `$status: future` — **do not emit
+  `mds-*` for live output**; use the runtime `--vars`.
+- `layout/` — `grid.json` (12-col MRow/MCol) + `layouts.json` (shells, regions, content layouts, panels).
+- `foundation/` — page-by-page product coverage per layout element.
+- `spec.manifest.json` — file list + sizes + checksums.
+
+## Known gaps (the AI will STOP-and-ASK here)
+
+Charts / data-viz / widget tiles / topology graph are **not** catalogued yet (only the chart
+*tooltips* are). Recipes flag these with a `$gap` marker.
+
+## Live visual catalogue
+
+Storybook: <https://niravbhatt1317.github.io/motadata-design-system/> — the pixel-accurate visual
+reference. It is **not** a data source; do not scrape it. The specs in this package are authoritative.
+
+## Versioning
+
+Semver. Minor = added components/recipes/tokens · patch = fixes/clarifications · major = breaking
+spec-shape change. Pin a version to keep AI output reproducible.