@mtdt/observeops-ds-spec 0.1.4 → 0.1.6

package/conformance/README.md

@@ -0,0 +1,23 @@
+# DS conformance checker
+
+Verify that a page you built with the ObserveOps design system actually **renders** like the DS — not just that
+you cited the right rules. It renders the page and scores it 0–100 on four dimensions, with a violations list:
+
+- **Token adherence** — every rendered colour maps to a DS token (`tokens/variables.json`). Off-token colours are
+  reported with the nearest DS token, so `#4F6EF5`-instead-of-navy is caught.
+- **Layout adherence** — paddings / radii land on the DS structural scale (`tokens/structural.json`).
+- **Philosophy** — brand = `--primary` navy (not blue/cyan), no future `mds-*` tokens, theme-aware (surfaces flip
+  light↔dark).
+- **Component adherence** — interactive controls carry a DS component/class signature (advisory).
+
+## Run it
+
+```bash
+# from a tool that has Playwright installed (npm i -D playwright-core, or use `playwright`)
+node conformance/ds-conformance.mjs ./your-page.html            # or a URL
+node conformance/ds-conformance.mjs ./your-page.html --json out.json --quiet
+```
+
+Exit code `0` when the overall score ≥ 80, else `1`. Reads the token/scale sets from the sibling `tokens/`
+directory shipped in this package. This is the render-time counterpart to the MCP `validate_usage` /
+`validate_render` static checks — run it as the last step of the AI build workflow (`AGENTS.md` self-check).

package/conformance/ds-conformance.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * ds-conformance.mjs — score how well a rendered page conforms to the ObserveOps design system.
+ *
+ * Unlike match-component/diff.mjs (a 1:1 A/B comparator driven by hand-authored selectors), this is a
+ * SPEC-FREE membership checker: it renders ANY page (a URL or an HTML file), auto-enumerates every element,
+ * and measures conformance against the DS reference sets — the token palette (tokens/variables.json), the
+ * structural scale (tokens/structural.json), and the philosophy rules (tokens/purpose-map.json $rules).
+ *
+ * Four dimensions → a 0–100 score + a violations list:
+ *   1. Token adherence     — every rendered colour maps to a DS token (else: off-token + nearest token).
+ *   2. Layout adherence    — paddings / radii land on the structural scale.
+ *   3. Philosophy adherence — theme-aware (surfaces flip light↔dark), no `mds-*`, brand not blue/cyan.
+ *   4. Component adherence  — interactive controls carry a DS component/class signature (advisory).
+ *
+ * Usage:  node ds-conformance.mjs <url-or-file.html> [--theme light|dark] [--json <out>] [--quiet]
+ *   env:  CHROME (Chrome executable), UI_ROOT
+ *
+ * Reuses the diff.mjs engine idea: a tiny static server + Chromium + getComputedStyle extraction.
+ * Shipped in the spec package (conformance/) so external AI tools can self-verify their render.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import http from 'node:http'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const UI_ROOT = process.env.UI_ROOT || path.resolve(HERE, '..', '..')
+const DS = path.resolve(HERE, '..')
+const CHROME = process.env.CHROME || '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+
+const args = process.argv.slice(2)
+const target = args.find((a) => !a.startsWith('--'))
+const theme = (args[args.indexOf('--theme') + 1] && args.includes('--theme')) ? args[args.indexOf('--theme') + 1] : 'light'
+const jsonOut = args.includes('--json') ? args[args.indexOf('--json') + 1] : null
+const QUIET = args.includes('--quiet')
+if (!target) { console.error('usage: node ds-conformance.mjs <url-or-file.html> [--theme light|dark] [--json out] [--quiet]'); process.exit(2) }
+
+// ── colour parsing / palette ─────────────────────────────────────────────────
+const NAMED = { white: [255, 255, 255, 1], black: [0, 0, 0, 1], red: [255, 0, 0, 1], transparent: [0, 0, 0, 0] }
+function parseColor(s) {
+  if (!s) return null
+  s = String(s).trim().toLowerCase()
+  if (NAMED[s]) return NAMED[s]
+  let m = s.match(/^#([0-9a-f]{3,8})$/)
+  if (m) {
+    let h = m[1]
+    if (h.length === 3) h = h.split('').map((c) => c + c).join('')
+    if (h.length === 4) h = h.split('').map((c) => c + c).join('')
+    const r = parseInt(h.slice(0, 2), 16), g = parseInt(h.slice(2, 4), 16), b = parseInt(h.slice(4, 6), 16)
+    const a = h.length >= 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1
+    return [r, g, b, a]
+  }
+  m = s.match(/^rgba?\(([^)]+)\)/)
+  if (m) {
+    const p = m[1].split(',').map((x) => parseFloat(x.trim()))
+    return [p[0] | 0, p[1] | 0, p[2] | 0, p[3] == null ? 1 : p[3]]
+  }
+  return null // gradients, fade(), none, shadows, non-colours
+}
+function buildPalette() {
+  const V = JSON.parse(fs.readFileSync(path.join(DS, 'tokens', 'variables.json'), 'utf8'))
+  const pal = []
+  for (const [name, v] of Object.entries(V)) {
+    if (name.startsWith('$')) continue
+    for (const k of ['light', 'dark']) {
+      const c = parseColor(v[k])
+      if (c) pal.push({ name, theme: k, c })
+    }
+  }
+  // kit-accents.json — the sanctioned Ant form-control accent (cyan @primary-color #099dd9, radio dot /
+  // checkbox check / select). These are legitimate DS colours; without them the cyan false-flags as off-token.
+  try {
+    const K = JSON.parse(fs.readFileSync(path.join(DS, 'tokens', 'kit-accents.json'), 'utf8'))
+    const walk = (o, name) => { for (const [k, v] of Object.entries(o)) { if (v && typeof v === 'object') walk(v, k); else { const c = parseColor(v); if (c) pal.push({ name: name || k, theme: 'kit', c }) } } }
+    walk(K, null)
+  } catch { /* optional */ }
+  return pal
+}
+const CYAN = [9, 157, 217] // @primary-color — the ONLY sanctioned accent-blue; not a brand-navy breach
+const dist = (a, b) => Math.max(Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]), Math.abs(a[2] - b[2]))
+const TOL = 5
+function nearest(c, pal) {
+  let best = null
+  for (const p of pal) {
+    const d = dist(c, p.c) + Math.abs((c[3] ?? 1) - (p.c[3] ?? 1)) * 40
+    if (!best || d < best.d) best = { d, name: p.name, val: p.c, alphaOk: Math.abs((c[3] ?? 1) - (p.c[3] ?? 1)) <= 0.1 }
+  }
+  return best
+}
+
+// ── structural scale ─────────────────────────────────────────────────────────
+function buildScale() {
+  const S = JSON.parse(fs.readFileSync(path.join(DS, 'tokens', 'structural.json'), 'utf8'))
+  const set = new Set([0])
+  const walk = (o) => { for (const v of Object.values(o)) { if (v && typeof v === 'object') walk(v); else if (typeof v === 'string') for (const m of v.matchAll(/(\d+(?:\.\d+)?)px/g)) set.add(parseFloat(m[1])) } }
+  walk(S)
+  return [...set]
+}
+const onScale = (v, scale) => scale.some((s) => Math.abs(s - v) <= 1)
+
+// ── static server (reused from diff.mjs) ─────────────────────────────────────
+const MIME = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff': 'font/woff', '.woff2': 'font/woff2' }
+function serve(root) {
+  return http.createServer((q, r) => {
+    let u = decodeURIComponent(q.url.split('?')[0]); if (u === '/') u = '/index.html'
+    fs.readFile(path.join(root, u), (e, b) => { if (e) { r.writeHead(404); r.end() } else { r.writeHead(200, { 'Content-Type': MIME[path.extname(u).toLowerCase()] || 'application/octet-stream' }); r.end(b) } })
+  })
+}
+
+// browser-side measurement — auto-enumerate every element
+const MEASURE = () => {
+  const colors = [], spaces = []
+  for (const el of document.querySelectorAll('*')) {
+    const c = getComputedStyle(el)
+    const tag = el.tagName.toLowerCase()
+    const add = (prop, val) => { if (val && val !== 'none' && val !== 'rgba(0, 0, 0, 0)') colors.push({ prop, val, tag }) }
+    add('background', c.backgroundColor)
+    add('color', c.color)
+    for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
+      if (parseFloat(c['border' + side + 'Width']) > 0 && c['border' + side + 'Style'] !== 'none') add('border', c['border' + side + 'Color'])
+    }
+    for (const p of ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft', 'borderTopLeftRadius', 'borderTopRightRadius', 'borderBottomLeftRadius', 'borderBottomRightRadius']) {
+      const v = parseFloat(c[p]); if (v > 0) spaces.push({ prop: p, val: Math.round(v * 10) / 10 })
+    }
+  }
+  // ── component fidelity ─────────────────────────────────────────────────────
+  // A DS component (obs-*) renders its real control in SHADOW DOM, so any RAW interactive element in the
+  // light DOM is a non-DS control that should be a DS component. And a styled <span>/<div> chip that isn't
+  // a DS component is a fabricated look-alike (should be obs-tag / obs-severity).
+  const DS = ['obs-button','obs-input','obs-select','obs-switch','obs-checkbox','obs-radio','obs-link','obs-tag','obs-severity','obs-tags','obs-tooltip','obs-date-time-picker','obs-filters','obs-selected-pills']
+  const SUGGEST = { button:'obs-button', input:'obs-input', textarea:'obs-input', select:'obs-select', a:'obs-link' }
+  const insideCE = (el) => { let n = el.parentElement; while (n) { if (n.tagName.includes('-')) return true; n = n.parentElement } return false }
+  const dsInteractive = document.querySelectorAll('obs-button,obs-input,obs-select,obs-switch,obs-checkbox,obs-radio,obs-link').length
+  const rawControls = [...document.querySelectorAll('button,input:not([type=hidden]),select,textarea,a[href],[role=button],[role=switch],[role=checkbox],[role=radio],[role=tab]')]
+    .filter((el) => !el.tagName.includes('-') && !insideCE(el))
+    .map((el) => { const t = el.tagName.toLowerCase(); const role = el.getAttribute('role'); return { tag: t, role, suggest: SUGGEST[t] || (role ? 'obs-' + role.replace('checkbox','checkbox').replace('button','button') : 'a DS component'), text: (el.textContent || el.getAttribute('placeholder') || '').trim().slice(0, 30) } })
+  // fabricated chips: light-DOM, non-custom element with a bg tint + radius + short text (a Tag/Badge look-alike)
+  const chips = [...document.querySelectorAll('span,div,i')].filter((el) => {
+    if (el.tagName.includes('-') || insideCE(el)) return false
+    const c = getComputedStyle(el); const r = el.getBoundingClientRect()
+    const bg = c.backgroundColor; const hasBg = bg && bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent'
+    const rad = parseFloat(c.borderTopLeftRadius) || 0
+    const txt = (el.textContent || '').trim()
+    return hasBg && rad >= 4 && r.width > 0 && r.width < 160 && r.height < 40 && txt.length >= 1 && txt.length <= 24 && el.children.length <= 1
+  }).map((el) => (el.textContent || '').trim().slice(0, 24))
+  return { colors, spaces, dsInteractive, rawControls, chips: [...new Set(chips)], bodyBg: getComputedStyle(document.body).backgroundColor }
+}
+
+;(async () => {
+  const pal = buildPalette()
+  const scale = buildScale()
+  // Portable Playwright resolution: repo path first, then the consumer's own playwright(-core).
+  let chromium
+  for (const spec of [path.join(UI_ROOT, 'node_modules', 'playwright-core', 'index.js'), 'playwright-core', 'playwright']) {
+    try { const pw = await import(spec); chromium = pw.chromium || (pw.default && pw.default.chromium); if (chromium) break } catch { /* try next */ }
+  }
+  if (!chromium) { console.error('playwright-core/playwright not found — install it to run the conformance check'); process.exit(2) }
+  const launchOpts = fs.existsSync(CHROME) ? { executablePath: CHROME } : {} // else Playwright's bundled Chromium
+
+  // resolve target → URL (serve the file's dir if it's a local file)
+  let url = target, srv = null
+  if (!/^https?:\/\//.test(target)) {
+    const abs = path.resolve(target)
+    const dir = path.dirname(abs)
+    srv = serve(dir); await new Promise((r) => srv.listen(0, '127.0.0.1', r))
+    url = `http://127.0.0.1:${srv.address().port}/${path.basename(abs)}`
+  }
+  const html = (!/^https?:\/\//.test(target)) ? fs.readFileSync(path.resolve(target), 'utf8') : ''
+
+  const browser = await chromium.launch(launchOpts)
+  const page = await browser.newPage({ viewport: { width: 1280, height: 900 }, deviceScaleFactor: 2 })
+  const setTheme = async (t) => { await page.evaluate((th) => { if (th === 'dark') { document.documentElement.setAttribute('data-theme', 'dark-theme'); document.body && document.body.setAttribute('data-theme', 'dark-theme') } else { document.documentElement.removeAttribute('data-theme'); document.body && document.body.removeAttribute('data-theme') } }, t); await page.waitForTimeout(400) }
+  await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 }).catch(() => page.goto(url, { waitUntil: 'domcontentloaded' }))
+  await page.waitForTimeout(800)
+  await setTheme(theme)
+  const m = await page.evaluate(MEASURE)
+  // theme-awareness: does the body background flip when we toggle the other theme?
+  const bodyA = m.bodyBg
+  await setTheme(theme === 'light' ? 'dark' : 'light')
+  const bodyB = (await page.evaluate(() => getComputedStyle(document.body).backgroundColor))
+  await browser.close(); if (srv) srv.close()
+
+  // ── score ────────────────────────────────────────────────────────────────
+  const violations = { token: [], layout: [], philosophy: [], component: [] }
+
+  // 1. token adherence
+  let tOk = 0, tTot = 0
+  const offAgg = {}
+  for (const { prop, val, tag } of m.colors) {
+    const c = parseColor(val); if (!c) continue
+    if ((c[3] ?? 1) < 0.04) continue // fully transparent
+    tTot++
+    const n = nearest(c, pal)
+    if (n && n.d <= TOL) tOk++
+    else { const key = val; offAgg[key] = offAgg[key] || { val, count: 0, nearest: n, prop, tag }; offAgg[key].count++ }
+  }
+  const tokenScore = tTot ? Math.round((tOk / tTot) * 100) : 100
+  violations.token = Object.values(offAgg).sort((a, b) => b.count - a.count).slice(0, 15)
+    .map((o) => ({ value: o.val, prop: o.prop, count: o.count, nearestToken: o.nearest ? o.nearest.name : null, nearestVal: o.nearest ? `rgb(${o.nearest.val.slice(0, 3).join(',')})` : null, delta: o.nearest ? o.nearest.d : null }))
+
+  // 2. layout adherence
+  let lOk = 0, lTot = 0
+  const offScale = {}
+  for (const { prop, val } of m.spaces) { lTot++; if (onScale(val, scale)) lOk++; else { const k = val + 'px'; offScale[k] = (offScale[k] || 0) + 1 } }
+  const layoutScore = lTot ? Math.round((lOk / lTot) * 100) : 100
+  violations.layout = Object.entries(offScale).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([v, count]) => ({ value: v, count }))
+
+  // 3. philosophy: theme-aware + no mds-* + brand-not-blue
+  const bA = parseColor(bodyA), bB = parseColor(bodyB)
+  const themeAware = !(bA && bB && dist(bA, bB) <= TOL && (bA[3] ?? 1) > 0.5) // bg must change across themes (unless transparent)
+  const usesMds = /\bmds-[a-z-]+/.test(html)
+  // brand misuse: a saturated blue that isn't a DS token (blue-dominant, off-token)
+  const brandMisuse = violations.token.filter((v) => { const c = parseColor(v.value); return c && c[2] > c[0] + 40 && c[2] > 150 && c[1] < c[2] - 20 && dist(c, CYAN) > 12 })
+  let philosophyScore = 100
+  if (!themeAware) { philosophyScore -= 45; violations.philosophy.push({ rule: 'theme-aware', detail: `body background did not change light↔dark (${bodyA} vs ${bodyB}) — likely a hardcoded surface, not a DS token` }) }
+  if (usesMds) { philosophyScore -= 45; violations.philosophy.push({ rule: 'no-mds', detail: 'page references future `mds-*` tokens — must emit only runtime --vars' }) }
+  if (brandMisuse.length) { philosophyScore -= 20; violations.philosophy.push({ rule: 'brand-navy', detail: `off-token saturated blue used (${brandMisuse.map((b) => b.value).join(', ')}) — brand must be --primary navy, not blue/cyan` }) }
+  philosophyScore = Math.max(0, philosophyScore)
+
+  // 4. COMPONENT FIDELITY — every interactive control must be a real DS component (not a raw element),
+  //    and no fabricated Tag/Badge look-alikes. A DS page renders controls via obs-* (shadow DOM), so any
+  //    raw light-DOM control is a non-DS element. This is the "use DS components, not look-alikes" check.
+  const rawN = m.rawControls.length
+  const denom = m.dsInteractive + rawN
+  const componentScore = denom === 0 ? 100 : Math.round((m.dsInteractive / denom) * 100)
+  for (const rc of m.rawControls) violations.component.push({ detail: `raw <${rc.tag}${rc.role ? ' role=' + rc.role : ''}>${rc.text ? ` "${rc.text}"` : ''} — use ${rc.suggest}, not a raw element` })
+  if (m.chips.length) violations.component.push({ advisory: true, detail: `possible fabricated chip(s) — use obs-tag / obs-severity: ${m.chips.slice(0, 6).join(', ')}` })
+
+  // Component fidelity is weighted heavily — the point of the check is DS components, not just DS colours.
+  const overall = Math.round(tokenScore * 0.35 + componentScore * 0.30 + philosophyScore * 0.20 + layoutScore * 0.15)
+  const result = { target, theme, overall, dimensions: { token: tokenScore, component: componentScore, philosophy: philosophyScore, layout: layoutScore },
+    measured: { colors: tTot, spacings: lTot, dsComponents: m.dsInteractive, rawControls: rawN, fabricatedChips: m.chips.length }, violations }
+
+  if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify(result, null, 2))
+  if (!QUIET) {
+    console.log(`\n=== DS conformance — ${target} (theme=${theme}) ===`)
+    console.log(`  OVERALL: ${overall}/100   ·  token ${tokenScore}  component ${componentScore}  philosophy ${philosophyScore}  layout ${layoutScore}`)
+    console.log(`  measured: ${tTot} colours · ${lTot} spacings · ${m.dsInteractive} DS components · ${rawN} raw controls · ${m.chips.length} fabricated chip(s)`)
+    if (violations.component.length) { console.log('\n  COMPONENT fidelity (use DS components, not raw/look-alikes):'); for (const v of violations.component.slice(0, 10)) console.log(`    ✗ ${v.detail}`) }
+    if (violations.token.length) { console.log('\n  off-token colours (top):'); for (const v of violations.token.slice(0, 8)) console.log(`    ✗ ${v.value} (${v.prop}, ×${v.count}) → nearest DS token ${v.nearestToken} (${v.nearestVal}, Δ${v.delta})`) }
+    if (violations.layout.length) { console.log('\n  off-scale spacing/radii:'); for (const v of violations.layout.slice(0, 6)) console.log(`    ~ ${v.value} (×${v.count})`) }
+    if (violations.philosophy.length) { console.log('\n  philosophy:'); for (const v of violations.philosophy) console.log(`    ✗ [${v.rule}] ${v.detail}`) }
+    console.log('')
+  }
+  process.exit(overall >= 80 ? 0 : 1)
+})().catch((e) => { console.error('ds-conformance ERROR', e.stack || e.message); process.exit(2) })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtdt/observeops-ds-spec",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Machine-readable spec and AI operating contract for the Motadata ObserveOps design system \u2014 components, tokens, page recipes, layout structure, and the rules an AI tool follows to build ObserveOps UI faithfully.",
   "license": "UNLICENSED",
   "main": "index.js",
@@ -13,6 +13,7 @@
     "tokens/",
     "layout/",
     "foundation/",
+    "conformance/",
     "README.md"
   ],
   "exports": {

package/spec.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "@mtdt/observeops-ds-spec",
-  "version": "0.1.4",
-  "generated": "2026-07-05T05:26:44.368Z",
+  "version": "0.1.6",
+  "generated": "2026-07-05T06:45:18.241Z",
   "entry": "llms.txt",
   "contract": "AGENTS.md",
   "index": "components/index.json",
@@ -360,8 +360,8 @@
     },
     {
       "path": "conformance/ds-conformance.mjs",
-      "bytes": 14797,
-      "sha256": "6c0ab765d85ffbb63f37bbecb31f4c1d0dc53f95dbce01044d0e6fb9baf5fd03"
+      "bytes": 17517,
+      "sha256": "2ab84ecc68575abf122b85beb3f9a9d4eccde9ffd629f71ea1cae2af50cfd3ac"
     },
     {
       "path": "foundation/README.md",
@@ -410,8 +410,8 @@
     },
     {
       "path": "package.json",
-      "bytes": 1052,
-      "sha256": "2532a62d6b53789f2b85f8352aa55160808022b5ad68fe46994ccff5e14376a7"
+      "bytes": 1072,
+      "sha256": "3e5a5e13ada2e15ca887ec4d40f280a0fac033f4dbaba8ac601d6efd46011d2f"
     },
     {
       "path": "tokens/README.md",