fix(design): validate colour sinks and scope source ownership

Author: Bill Leoutsakos

scripts/check-design-conformance-colour-assignments.test.ts

@@ -538,3 +538,13 @@ test('unresolved layout-only aliases are not colour findings', () => {
   expect(report.unchecked.some((n) => n.file === css && n.reason.includes('--layout'))).toBe(true)
   expect(flagged({ [css]: '.label{--ink:var(--missing);color:var(--ink)}' })).toHaveLength(1)
 })
+
+test('HSL channel tokens require a colour function at the visible sink', () => {
+  const global = { [tokens]: ':root{--background:0 0% 100%;--paint:hsl(var(--background))}' }
+  expect(flagged({ ...global, [css]: '.a{color:var(--background)}' })).toHaveLength(1)
+  expect(flagged({ ...global, [css]: '.a{color:hsl(var(--background))}' })).toEqual([])
+  expect(flagged({ ...global, [css]: '.a{color:var(--paint)}' })).toEqual([])
+  expect(
+    flagged({ ...global, [css]: '.a{--alias:var(--background);color:hsl(var(--alias))}' })
+  ).toEqual([])
+})

scripts/check-design-conformance-controls.test.ts

@@ -237,3 +237,25 @@ test('statically resolved ARIA buttons require a name', () => {
   ).toHaveLength(0)
   expect(matching(run('<div role={role}/>'), 'control-accessible-name')).toHaveLength(0)
 })
+
+test('directly referenced hidden text supplies an accessible name', () => {
+  expect(
+    matching(
+      run(
+        '<><span id="name" aria-hidden="true">Run</span><Button aria-labelledby="name"><X/></Button></>'
+      ),
+      'control-accessible-name'
+    )
+  ).toHaveLength(0)
+})
+test('undefined class alternatives cannot exempt visible unnamed buttons', () => {
+  expect(
+    matching(
+      run('<Button className={visible ? undefined : "hidden"}><X/></Button>'),
+      'control-accessible-name'
+    )
+  ).toHaveLength(1)
+  expect(
+    matching(run('<Button className="hidden"><X/></Button>'), 'control-accessible-name')
+  ).toHaveLength(0)
+})

scripts/check-design-conformance-coverage.test.ts

@@ -485,3 +485,21 @@ test.each([
 ])('inspection failures are not unresolved styling: %s', (reason) => {
   expect(inspectionFailure(reason)).toBe(true)
 })
+
+test.each(['button', 'input', 'textarea', 'select', 'section > button.action', 'button + input'])(
+  'bare native CSS controls are reviewable: %s',
+  (selector) => {
+    expect(
+      inspect({
+        'apps/sim/components/native.css': `${selector}{padding:3px}`,
+      }).review.findings.some((f) => f.rule === 'styled-native-control')
+    ).toBe(true)
+  }
+)
+test('similarly named CSS classes are not native-control selectors', () => {
+  expect(
+    inspect({ 'apps/sim/components/native.css': '.buttonish{padding:3px}' }).review.findings.some(
+      (f) => f.rule === 'styled-native-control'
+    )
+  ).toBe(false)
+})

scripts/check-design-conformance-typography.test.ts

@@ -183,3 +183,12 @@ test('uninspected CSS cannot establish global weight token ownership', () => {
   expect(result.classifications).toEqual([])
   expect(result.unchecked.some((n) => n.file === 'apps/sim/components/gap.css')).toBe(true)
 })
+
+test('a runtime text-size writer revokes the loader fallback proof', () => {
+  const result = review({
+    [loader]: writer,
+    [loaderCss]: labels,
+    'apps/sim/components/writer.ts': "node.style.setProperty('--text-sm',runtime)",
+  })
+  expect(result.classifications.some((c) => c.file === loaderCss)).toBe(false)
+})

scripts/check-design-conformance.test.ts

@@ -1004,3 +1004,33 @@ test('central inline artwork deletions retain an explicit artwork removal findin
   )
   expect(findings.some((f) => f.value === '(removed)')).toBe(true)
 })
+
+test('a sibling local variable cannot prove typography provenance', async () => {
+  const report = await diff(
+    '',
+    "const A=()=> <><span style={{'--type':'var(--text-small)'}}/><p style={{fontSize:'var(--type)'}}>Text</p></>"
+  )
+  expect(
+    report.findings.some((f) => f.rule === 'central-typography') ||
+      report.unchecked.some((n) => n.reason.includes('--type'))
+  ).toBe(true)
+})
+test('policy object key order is quiet but array order remains meaningful', async () => {
+  const before = JSON.stringify({
+    version: '2.0.0',
+    limits: { depth: 12, branches: 64 },
+    scopes: ['a', 'b'],
+  })
+  const reordered = JSON.stringify({
+    scopes: ['a', 'b'],
+    limits: { branches: 64, depth: 12 },
+    version: '2.0.0',
+  })
+  const file = 'scripts/design-conformance/contracts.json'
+  expect((await diff(before, reordered, file)).findings).toEqual([])
+  expect(
+    (await diff(before, reordered.replace('["a","b"]', '["b","a"]'), file)).findings.some(
+      (f) => f.context === 'contract-registry'
+    )
+  ).toBe(true)
+})

scripts/design-conformance/conformance.ts

@@ -149,25 +149,23 @@ function expanded(ds: Declaration[], system: DesignSystem): Declaration[] {
 }
 function inspect(facts: Facts, file: string, system: DesignSystem): Checked {
   const out: Checked = { findings: [], unchecked: [...facts.unchecked], governed: 0, ungoverned: 0 }
-  const localVars = new Map(
-    (facts.surfaces ?? []).flatMap((s) =>
-      s.atoms
+  for (const surface of facts.surfaces ?? []) {
+    const localVars = new Map(
+      surface.atoms
         .filter((a) => a.kind === 'token' || a.property.startsWith('--'))
         .map((a) => [a.property, a.value] as const)
     )
-  )
-  const expand = (value: string, seen = new Set<string>()): string =>
-    value.replace(/var\(\s*(--[\w-]+)\s*\)/g, (all, key: string) => {
-      if (
-        system.variableFamilies.has(key) ||
-        !localVars.has(key) ||
-        seen.has(key) ||
-        seen.size >= 12
-      )
-        return all
-      return expand(localVars.get(key) as string, new Set(seen).add(key))
-    })
-  for (const surface of facts.surfaces ?? []) {
+    const expand = (value: string, seen = new Set<string>()): string =>
+      value.replace(/var\(\s*(--[\w-]+)\s*\)/g, (all, key: string) => {
+        if (
+          system.variableFamilies.has(key) ||
+          !localVars.has(key) ||
+          seen.has(key) ||
+          seen.size >= 12
+        )
+          return all
+        return expand(localVars.get(key) as string, new Set(seen).add(key))
+      })
     if (surface.kind === 'integration') continue
     const surfaceFindings = new Set<string>()
     const emit = (
@@ -684,15 +682,27 @@ export class ConformanceLinter {
         if (isRegistry(file)) {
           const b = change.before ? JSON.parse(read(change.before)) : null
           const a = change.after ? JSON.parse(read(change.after)) : null
-          if (canonical(b) !== canonical(a))
+          const stable = (value: unknown): unknown =>
+            Array.isArray(value)
+              ? value.map(stable)
+              : value && typeof value === 'object'
+                ? Object.fromEntries(
+                    Object.entries(value)
+                      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                      .map(([key, value]) => [key, stable(value)])
+                  )
+                : value
+          const beforePolicy = canonical(stable(b))
+          const afterPolicy = canonical(stable(a))
+          if (beforePolicy !== afterPolicy)
             report.findings.push({
               kind: 'system-change',
               contract: 'central-definition',
               rule: 'central-definition',
               category: 'contracts',
               property: 'registry',
-              value: hash(canonical(a)),
-              before: hash(canonical(b)),
+              value: hash(afterPolicy),
+              before: hash(beforePolicy),
               reason: 'Design-system contract registry changed',
               file,
               line: 1,