@mtdt/observeops-ds-spec 0.1.6 → 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) {
@@ -144,7 +162,17 @@ const MEASURE = () => {
     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 }
+  // 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 () => {
@@ -222,21 +250,39 @@ const MEASURE = () => {
   //    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(', ')}` })
 
+  // 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)
+
   // 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 }
+    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}  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)`)
+    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})`) }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtdt/observeops-ds-spec",
-  "version": "0.1.6",
+  "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.6",
-  "generated": "2026-07-05T06:45:18.241Z",
+  "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": 17517,
-      "sha256": "2ab84ecc68575abf122b85beb3f9a9d4eccde9ffd629f71ea1cae2af50cfd3ac"
+      "bytes": 21201,
+      "sha256": "625ab74a9f0b788a6721432cf8b8688a128c03e832fe001300f8a24ad176f9b2"
     },
     {
       "path": "foundation/README.md",
@@ -411,7 +411,7 @@
     {
       "path": "package.json",
       "bytes": 1072,
-      "sha256": "3e5a5e13ada2e15ca887ec4d40f280a0fac033f4dbaba8ac601d6efd46011d2f"
+      "sha256": "19f2e139d6c911d1801219acf6ecbd6f029ed596d8484e8bbf4adc4ae61c78b9"
     },
     {
       "path": "tokens/README.md",