fix: exempt shared media metadata and orphan component removals

Author: Bill Leoutsakos

design-diff.config.json

@@ -4,9 +4,10 @@
     "(?:^|/)(?:node_modules|__tests__|__fixtures__|fixtures|test-results|\\.source|dist|build)/",
     "\\.(?:test|spec)\\.[cm]?[jt]sx?$",
     "(?:^|/)next-env\\.d\\.ts$",
-    "(?:^|/)public/",
+    "(?:^|/)public/(?!.*\\.(?:woff2?|ttf|otf|eot)$)",
     "(?:^|/)sandbox/bundles/"
   ],
+  "mediaModules": ["lucide-react", "react-icons", "next/image", "next/legacy/image"],
   "renderedMarkdown": ["apps/docs/content/", "apps/sim/content/"],
   "aliases": [
     {
@@ -158,7 +159,7 @@
       {
         "module": "@/components/ui/block-info-card",
         "names": ["BlockInfoCard"],
-        "contentProps": ["type"]
+        "contentProps": ["type", "color"]
       },
       {
         "module": "@/components/ui/command-table",

scripts/design-diff/README.md

@@ -36,11 +36,16 @@ that every rendered pixel is unchanged.
 | Additional dropdown options, rows or controls repeating existing appearance | Exempt |
 | Copy, progress/error labels, pricing/privacy wording, documentation prose | Exempt |
 | Icons, images, screenshots, inline SVG and media element dimensions | Exempt |
+| Font files and font-face changes | Flag |
 | Runtime conditions, functional visibility, option data, unknown component props | Exempt |
 | Coordinates or translation alone | Exempt |
 | Unknown calls, parser/expression limits, plugins and dependency version changes alone | Exempt; retain coverage notes |
 | Comments, erased types, supported formatting/constant hoists/local renames | Exempt |
 
+Deleting a shared control also exempts its standard appearance props. Deleted component modules
+with no resolved references outside other deleted files are treated as unestablished runtime use,
+not designer notifications. Route entry files and active component removals retain normal analysis.
+
 A new `<Button variant="primary" size="sm"/>` uses shared appearance and is exempt.
 Adding `<Button className="rounded-none p-6"/>` introduces a custom override and flags.
 Changing an existing control's supported `variant`, `size`, classes or style values flags.
@@ -89,13 +94,14 @@ matching is approximate. Changes to unused authored styles and inactive variants
 runtime-only effects and unsupported rendering may be missed by this precision-oriented policy.
 
 The scope covers product, landing pages, emails, documentation presentation, desktop and shared
-components/themes under `apps/` and `packages/`. Tests, fixtures, public assets and server sandbox
-bundles are excluded. Media component modules remain available to import resolution so excluding
+components/themes under `apps/` and `packages/`. Tests, fixtures, public image/media assets and server sandbox
+bundles are excluded. Font assets remain in scope. Recognized media import modules and resolved icon origins handle aliases.
+Media component modules remain available to import resolution so excluding
 an Icon does not break resolution of Button through the same barrel.
 
 ## Report contract
 
-Schema **3.0.0**, engine **0.5.0**, policy **5.0.0**. The schema remains compatible; the policy
+Schema **3.0.0**, engine **0.5.1**, policy **5.0.0**. The schema remains compatible; the policy
 meaning changes. Readers must inspect versions when comparing historical qualification rates.
 All decisions and identifiers are deterministic for the same engine/configuration and commits.
 Execution timing and peak memory are recorded separately by the benchmark, never in engine JSON.

scripts/design-diff/analyze.ts

@@ -24,7 +24,7 @@ import type { Change, Config, Definition, Report } from '#design-diff/types'
 export function emptyReport(): Report {
   return {
     schemaVersion: '3.0.0',
-    engineVersion: '0.5.0',
+    engineVersion: '0.5.1',
     policyVersion: '5.0.0',
     commits: null,
     status: 'failed',
@@ -192,6 +192,7 @@ export async function analyze(
     }
     let extracted = 0
     let omittedConsumers = 0
+    let orphanDeletions = 0
     /** Prefer direct consumers before distant opaque application plumbing when retaining one example. */
     const downstream = new Map<string, Set<string>>()
     for (const graph of [before.graph, after.graph])
@@ -221,6 +222,15 @@ export async function analyze(
       if (++extracted % 32 === 0) reclaimMemory()
       if (!scoped(file, config) && !infrastructure(file, config)) continue
       if ([...renames.values()].includes(file) && !after.entries.has(file)) continue
+      if (
+        !after.entries.has(file) &&
+        file.includes('/components/') &&
+        /\.[jt]sx$/.test(file) &&
+        before.graph.usages(file).every((usage) => !after.entries.has(usage.location.file))
+      ) {
+        orphanDeletions++
+        continue
+      }
       if (
         !changed.has(file) &&
         indirectExamples > 0 &&
@@ -283,6 +293,10 @@ export async function analyze(
         ...report.limitations,
         `Indirect analysis omitted for ${omittedConsumers} unchanged files after the PR qualified and a nearby rendering consumer was examined. All in-scope changed files were analyzed; additional indirect effects are not exhaustively catalogued. Categories describe retained evidence; usage counts remain partial resolved references.`,
       ]
+    if (orphanDeletions)
+      report.limitations.push(
+        `${orphanDeletions} deleted component modules had no resolved static references outside deleted files. Runtime use is unestablished; these removals do not qualify on their own.`
+      )
     for (const file of changed) {
       if (file !== 'bun.lock' && !file.endsWith('/package.json') && file !== 'package.json')
         continue

scripts/design-diff/appearance.ts

@@ -148,6 +148,8 @@ function classes(value: Data): Data | undefined {
 /** The notification policy requires concrete authored appearance, independent of render guards. */
 export function appearanceValue(definition: Definition): Data | undefined {
   if (definition.appearance?.media) return undefined
+  if (definition.kind === 'asset' && /\.(?:woff2?|ttf|otf|eot)$/i.test(definition.location.file))
+    return definition.value
   if (definition.kind === 'class') {
     if (!object(definition.value) || !Array.isArray(definition.value.normalized)) return undefined
     const values = definition.value.normalized.flatMap((entry) => {
@@ -164,7 +166,13 @@ export function appearanceValue(definition: Definition): Data | undefined {
     if (!object(definition.value)) return undefined
     const { order: _order, ...value } = definition.value
     if (typeof value.value === 'string' && /url\(/.test(value.value))
-      value.value = cssAppearance(value.value)
+      value.value =
+        definition.property === 'src' &&
+        definition.conditions.some(
+          (condition) => typeof condition === 'string' && condition.startsWith('@font-face')
+        )
+          ? value.value
+          : cssAppearance(value.value)
     return { ...value, context: definition.conditions }
   }
   if (

scripts/design-diff/benchmark.ts

@@ -205,7 +205,7 @@ export async function benchmark(args = process.argv.slice(2)): Promise<void> {
       result.reportSha256 = hash(bytes)
       if (
         report.schemaVersion !== '3.0.0' ||
-        report.engineVersion !== '0.5.0' ||
+        report.engineVersion !== '0.5.1' ||
         report.policyVersion !== '5.0.0'
       )
         throw new Error('Report version mismatch')

scripts/design-diff/compare.ts

@@ -137,15 +137,18 @@ export function compareDefinitions(
         pairs.push([removals[index], additions[index]])
     }
     for (const [a, b] of pairs) {
-      if (!a && b?.kind === 'attribute' && b.appearance?.shared) {
-        const element = b.appearance.element?.replace(/:\d+$/, '')
+      const unpaired = !a ? b : !b ? a : undefined
+      if (unpaired?.kind === 'attribute' && unpaired.appearance?.shared) {
+        const element = unpaired.appearance.element?.replace(/:\d+$/, '')
         const count = (definitions: Definition[]) =>
           definitions.filter(
             (definition) =>
               definition.kind === 'markup' &&
               definition.appearance?.element?.replace(/:\d+$/, '') === element
           ).length
-        if (!count(before) || count(after) > count(before)) continue
+        const existing = !a ? before : after
+        const added = !a ? after : before
+        if (!count(existing) || count(added) > count(existing)) continue
       }
       if (a && b && (signature(a) === signature(b) || sameAppearance(a, b))) continue
       if ((!a || appearance(a) === undefined) && (!b || appearance(b) === undefined)) continue

scripts/design-diff/extract/documents.ts

@@ -5,7 +5,7 @@ import remarkMdx from 'remark-mdx'
 import remarkParse from 'remark-parse'
 import { unified } from 'unified'
 import { appearanceAttributes, mediaElement } from '#design-diff/appearance'
-import { canonical, semanticSource } from '#design-diff/ast'
+import { canonical, parseSource, propertyName, semanticSource } from '#design-diff/ast'
 import { documentPresentation } from '#design-diff/document-content'
 import { cssValue, extractCss } from '#design-diff/extract/css'
 import type { Resolver } from '#design-diff/resolve'
@@ -134,8 +134,46 @@ export function extractDocument(
       .map((node) => ('value' in node ? String(node.value) : ''))
       .join('\n')
     if (appearanceOnly) {
+      const bindings = new Map<string, { module: string; name: string }>()
+      for (const statement of parseSource(imports, `${file}.tsx`).program.body) {
+        if (statement.type !== 'ImportDeclaration') continue
+        for (const specifier of statement.specifiers)
+          bindings.set(specifier.local.name, {
+            module: statement.source.value,
+            name:
+              specifier.type === 'ImportSpecifier'
+                ? propertyName(specifier.imported)
+                : specifier.type === 'ImportNamespaceSpecifier'
+                  ? '*'
+                  : 'default',
+          })
+      }
       const walk = (node: Record<string, Data>) => {
         if (typeof node.name === 'string' && mediaElement.test(node.name)) return
+        const imported =
+          typeof node.name === 'string' ? bindings.get(node.name.split('.')[0]) : undefined
+        if (
+          imported &&
+          resolver?.tree.config.mediaModules?.some(
+            (module) => imported.module === module || imported.module.startsWith(`${module}/`)
+          )
+        )
+          return
+        const content =
+          imported &&
+          resolver?.tree.config.documentationContent?.components.find(
+            (component) =>
+              component.module === imported.module &&
+              component.names.includes(
+                imported.name === '*' && typeof node.name === 'string'
+                  ? node.name.split('.')[1]
+                  : imported.name
+              )
+          )
+        if (typeof node.name === 'string') {
+          emit('markup', null, 1, 1, node.name)
+          result[result.length - 1].appearance = { element: node.name }
+        }
         if (Array.isArray(node.attributes)) {
           const position = node.position as
             | { start?: { line?: number; column?: number } }
@@ -146,6 +184,7 @@ export function extractDocument(
               typeof item !== 'object' ||
               Array.isArray(item) ||
               typeof item.name !== 'string' ||
+              (content && content.contentProps.includes(item.name)) ||
               !appearanceAttributes.test(item.name)
             )
               continue

scripts/design-diff/extract/tsx.ts

@@ -41,11 +41,25 @@ export function extractTsx(resolver: Resolver, file: string, appearanceOnly = fa
       if (mediaElement.test(name)) return true
       const binding = node.scope.getBinding(name.split('.')[0])
       const declaration = binding?.path.parentPath
-      if (
-        declaration?.isImportDeclaration() &&
-        /(?:^|\/)icons?(?:\/|$)/.test(declaration.node.source.value)
-      )
-        return true
+      if (declaration?.isImportDeclaration()) {
+        const module = declaration.node.source.value
+        if (
+          /(?:^|\/)icons?(?:\/|$)/.test(module) ||
+          resolver.tree.config.mediaModules?.some(
+            (prefix) => module === prefix || module.startsWith(`${prefix}/`)
+          )
+        )
+          return true
+        const imported = binding?.path.isImportSpecifier()
+          ? propertyName(binding.path.node.imported)
+          : 'default'
+        const origin = resolver.tree.graph?.imported(file, module, imported)
+        if (
+          origin?.origins.length &&
+          origin.origins.every((item) => /(?:^|\/)icons?(?:\/|\.[cm]?[jt]sx?$)/.test(item.file))
+        )
+          return true
+      }
     }
     return false
   }

scripts/design-diff/policy.ts

@@ -5,6 +5,15 @@ export function category(definition: Definition): Category {
   const property = definition.property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
   if (definition.property === 'infrastructure') return 'infrastructure'
   if (definition.kind === 'review') return 'unresolved'
+  if (
+    (definition.kind === 'asset' && /\.(?:woff2?|ttf|otf|eot)$/i.test(definition.location.file)) ||
+    (definition.kind === 'css' &&
+      definition.property === 'src' &&
+      definition.conditions.some(
+        (condition) => typeof condition === 'string' && condition.startsWith('@font-face')
+      ))
+  )
+    return 'typography'
   if (definition.kind === 'asset' || definition.kind === 'content' || definition.kind === 'markup')
     return 'content'
   if (/^(?:src|src-set|alt|title|placeholder|d|points|view-box)$/.test(property)) return 'content'

scripts/design-diff/tests/appearance-policy.test.ts

@@ -111,4 +111,63 @@ describe('designer notification policy', () => {
       (await compareFiles({ [shared]: source('red') }, { [shared]: source('blue') })).flagged
     ).toBe(true)
   })
+
+  it.each([
+    [
+      'lucide-react',
+      'export const Page=()=> <Glyph className="size-4"/>',
+      'export const Page=()=> <Glyph className="size-8"/>',
+    ],
+    [
+      'next/image',
+      'export const Page=()=> <Glyph width={100}/>',
+      'export const Page=()=> <Glyph width={200}/>',
+    ],
+  ])('recognizes aliased media imports from %s', async (module, a, b) => {
+    const prefix = `import Glyph from '${module}';`
+    expect((await compareFiles({ [file]: prefix + a }, { [file]: prefix + b })).flagged).toBe(false)
+  })
+
+  it('exempts deleting a standard branded documentation card', async () => {
+    const doc = 'apps/docs/content/evernote.mdx'
+    const source =
+      'import {BlockInfoCard} from "@/components/ui/block-info-card"\n\n<BlockInfoCard type="evernote" color="#FFFFFF"/>'
+    expect((await compareFiles({ [doc]: source }, { [doc]: null })).flagged).toBe(false)
+    expect(
+      (await compareFiles({ [doc]: source }, { [doc]: source.replace('#FFFFFF', '#FF0000') }))
+        .flagged
+    ).toBe(false)
+  })
+
+  it('flags an appearance override added to an existing MDX component', async () => {
+    const doc = 'apps/docs/content/page.mdx'
+    expect(
+      (await compareFiles({ [doc]: '<Callout/>' }, { [doc]: '<Callout variant="compact"/>' }))
+        .flagged
+    ).toBe(true)
+  })
+
+  it('exempts deleted orphan component clusters but retains active component removals', async () => {
+    const a = 'apps/sim/components/unused.tsx'
+    const b = 'apps/sim/components/unused-wrapper.tsx'
+    const files = {
+      [a]: 'export const Unused=()=> <div className="p-2"/>',
+      [b]: 'import {Unused} from "./unused";export const Wrapper=()=> <Unused/>',
+    }
+    expect((await compareFiles(files, { [a]: null, [b]: null })).flagged).toBe(false)
+    expect((await compareFiles(files, { [a]: null })).flagged).toBe(true)
+  })
+
+  it('retains font replacements while ignoring binary image replacements', async () => {
+    const font = 'apps/sim/public/brand/font.woff2'
+    const image = 'apps/sim/public/brand/cover.png'
+    expect(
+      (await compareFiles({ [font]: Buffer.from([0, 1, 2]) }, { [font]: Buffer.from([0, 1, 3]) }))
+        .flagged
+    ).toBe(true)
+    expect(
+      (await compareFiles({ [image]: Buffer.from([0, 1, 2]) }, { [image]: Buffer.from([0, 1, 3]) }))
+        .flagged
+    ).toBe(false)
+  })
 })