@mtdt/observeops-ds-spec 0.1.5 → 0.1.7

package/conformance/ds-conformance.mjs

@@ -99,6 +99,24 @@ function buildScale() {
 }
 const onScale = (v, scale) => scale.some((s) => Math.abs(s - v) <= 1)
 
+// ── variant/state fidelity: valid values per component, from the registry ─────
+const TAGMAP = { 'obs-button': 'button', 'obs-input': 'input', 'obs-tag': 'tag', 'obs-radio': 'radio', 'obs-select': 'select', 'obs-severity': 'severity', 'obs-checkbox': 'checkbox', 'obs-switch': 'switch', 'obs-link': 'link', 'obs-tags': 'loose-tags', 'obs-date-time-picker': 'date-time-pickers', 'obs-filters': 'filters' }
+const _regCache = {}
+function validValues(tag) {
+  const id = TAGMAP[tag]; if (!id) return null
+  if (_regCache[id] !== undefined) return _regCache[id]
+  const p = path.join(DS, 'components', 'registry', `${id}.json`)
+  if (!fs.existsSync(p)) return (_regCache[id] = null)
+  const r = JSON.parse(fs.readFileSync(p, 'utf8'))
+  const props = r.props || {}
+  const enumOf = (k) => (props[k] && Array.isArray(props[k].enum) && props[k].enum.length ? props[k].enum : null)
+  // Validate ONLY against a declared prop `enum` (the reliable accepted-values source). The registry's
+  // `variants` field is a doc concept whose names don't always match the prop values (e.g. link), so we
+  // do NOT validate against it — that produced false positives. Where a component has no enum, its variant
+  // isn't strictly validated here (a registry gap the ai-readiness/validate-registries pass should close).
+  return (_regCache[id] = { id, variant: enumOf('variant'), size: enumOf('size'), type: enumOf('type') })
+}
+
 // ── 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) {
@@ -124,9 +142,37 @@ const MEASURE = () => {
       const v = parseFloat(c[p]); if (v > 0) spaces.push({ prop: p, val: Math.round(v * 10) / 10 })
     }
   }
-  const ctrlSel = 'button,input,select,textarea,a[href],[role=button],[role=checkbox],[role=switch],[role=radio],[role=tab]'
-  const controls = [...document.querySelectorAll(ctrlSel)].map((el) => ({ tag: el.tagName.toLowerCase(), cls: (el.getAttribute('class') || ''), ce: el.tagName.includes('-') }))
-  return { colors, spaces, controls, bodyBg: getComputedStyle(document.body).backgroundColor }
+  // ── 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))
+  // capture each DS component instance + its variant/size/type/state attrs (validated vs the registry node-side)
+  const dsInstances = [...document.querySelectorAll(DS.join(','))].map((el) => ({
+    tag: el.tagName.toLowerCase(),
+    variant: el.getAttribute('variant'),
+    size: el.getAttribute('size'),
+    type: el.getAttribute('type'),
+    severity: el.getAttribute('severity'),
+    ariaLabel: el.getAttribute('aria-label') || el.getAttribute('aria-labelledby'),
+    hasText: (el.textContent || '').trim().length > 0,
+  }))
+  return { colors, spaces, dsInteractive, rawControls, chips: [...new Set(chips)], dsInstances, bodyBg: getComputedStyle(document.body).backgroundColor }
 }
 
 ;(async () => {
@@ -200,26 +246,47 @@ const MEASURE = () => {
   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 adherence (advisory): interactive controls should carry a DS signature
-  const DS_SIG = /\b(ant-|obs-|m-|floto|tag-|squared-button|sel|trig)/i
-  let cOk = 0
-  for (const ctrl of m.controls) { if (ctrl.ce || DS_SIG.test(ctrl.cls) || ctrl.tag === 'a') cOk++ }
-  const componentScore = m.controls.length ? Math.round((cOk / m.controls.length) * 100) : 100
-  if (m.controls.length && cOk < m.controls.length) violations.component.push({ detail: `${m.controls.length - cOk} of ${m.controls.length} interactive controls have no DS component/class signature (raw element?)` })
+  // 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
+  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(', ')}` })
+
+  // variant/state fidelity — every variant/size/type used must be a REAL registry value (not invented),
+  // and required state must be present (icon-only control needs an aria-label).
+  let checked = 0, invalid = 0
+  for (const inst of (m.dsInstances || [])) {
+    const vv = validValues(inst.tag); if (!vv) continue
+    const bad = (attr, val, allowed) => { if (val == null || !allowed || !allowed.length) return; checked++; if (!allowed.includes(val)) { invalid++; violations.component.push({ detail: `invented ${attr} "${val}" on <${inst.tag}> — valid: ${allowed.slice(0, 8).join(', ')}` }) } }
+    // Validate `size`/`type` against the prop enum (reliable). NOT `variant`: components reflect a default
+    // `variant` attr that often isn't in the registry's variant list (e.g. obs-link reflects "primary"),
+    // and the registry's variant names don't always match the component's accepted values — so validating
+    // it here produces false positives. Enabling variant validation needs a clean per-component variant
+    // enum in the registry (tracked as a spec-hardening TODO; see validate-registries / ai-readiness).
+    bad('size', inst.size, vv.size)
+    bad('type', inst.type, vv.type)
+    // icon-only interactive control (no text) should carry an aria-label
+    if ((inst.tag === 'obs-button' || inst.tag === 'obs-link') && !inst.hasText && !inst.ariaLabel) { checked++; invalid++; violations.component.push({ detail: `icon-only <${inst.tag}> has no aria-label (required state)` }) }
+  }
+  const presence = (m.dsInteractive + rawN) === 0 ? 1 : m.dsInteractive / (m.dsInteractive + rawN)
+  const validity = checked === 0 ? 1 : (checked - invalid) / checked
+  const componentScore = Math.round(presence * validity * 100)
 
-  const overall = Math.round(tokenScore * 0.45 + layoutScore * 0.15 + philosophyScore * 0.25 + componentScore * 0.15)
-  const result = { target, theme, overall, dimensions: { token: tokenScore, layout: layoutScore, philosophy: philosophyScore, component: componentScore },
-    measured: { colors: tTot, spacings: lTot, controls: m.controls.length }, violations }
+  // 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, variantChecks: checked, invalidVariants: invalid }, 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}  layout ${layoutScore}  philosophy ${philosophyScore}  component ${componentScore}`)
-    console.log(`  measured: ${tTot} colours · ${lTot} spacings · ${m.controls.length} controls`)
+    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) · ${checked} variant checks (${invalid} invalid)`)
+    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}`) }
-    if (violations.component.length) { console.log('\n  component:'); for (const v of violations.component) console.log(`    ~ ${v.detail}`) }
     console.log('')
   }
   process.exit(overall >= 80 ? 0 : 1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtdt/observeops-ds-spec",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",

package/spec.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "@mtdt/observeops-ds-spec",
-  "version": "0.1.5",
-  "generated": "2026-07-05T05:55:32.800Z",
+  "version": "0.1.7",
+  "generated": "2026-07-05T06:59:15.142Z",
   "entry": "llms.txt",
   "contract": "AGENTS.md",
   "index": "components/index.json",
@@ -360,8 +360,8 @@
     },
     {
       "path": "conformance/ds-conformance.mjs",
-      "bytes": 14797,
-      "sha256": "6c0ab765d85ffbb63f37bbecb31f4c1d0dc53f95dbce01044d0e6fb9baf5fd03"
+      "bytes": 21201,
+      "sha256": "625ab74a9f0b788a6721432cf8b8688a128c03e832fe001300f8a24ad176f9b2"
     },
     {
       "path": "foundation/README.md",
@@ -411,7 +411,7 @@
     {
       "path": "package.json",
       "bytes": 1072,
-      "sha256": "a498b96846cd6731099d56e25658eedd15b1c3af8ee49bd969b5dcd2de9876f5"
+      "sha256": "19f2e139d6c911d1801219acf6ecbd6f029ed596d8484e8bbf4adc4ae61c78b9"
     },
     {
       "path": "tokens/README.md",