feat(phase-16d): normalization layer + demo surface docs

Phase 16D — Cross-Surface Drift Normalization:
- normalize.ts: deterministic pre-comparison normalization (filter design-only
  fields, alias prop names, deduplicate)
- analyze.ts: wire normalization into cross-surface drift pipeline
- crossSurfaceDrift.ts (shared): export NormalizationConfig type
- normalize.test.ts + analyze.test.ts: test coverage for normalization layer

Docs:
- architecture-reference.md: Phase 16D entry, normalization layer section
- adapter-model.md: normalization layer summary
- README.md: update demo-app project structure (SDS-aligned Button/Input/Card,
  markers consolidated in App.tsx only)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ryandmonk

README.md

@@ -216,8 +216,13 @@ aesthetic-function/
 │   ├── server/          # WebSocket/HTTP relay, audit logging
 │   ├── figma-plugin/    # Figma sandbox plugin (mutation executor)
 │   └── cli/             # `af` CLI control surface
-├── demo-app/            # Sample React app with @figma markers + Storybook
-│   └── .storybook/      # Storybook config (addon-mcp enabled)
+├── demo-app/            # Demo React app for AF reconciliation and drift demos
+│   ├── src/
+│   │   ├── App.tsx      # Sign-in composition panel — sole source of @figma markers
+│   │   ├── Button.tsx   # SDS-faithful Button (Primary variant, no markers)
+│   │   ├── Input.tsx    # SDS-faithful Input Field (no markers)
+│   │   └── Card.tsx     # SDS-faithful Card container (no markers)
+│   └── .storybook/      # Storybook config (addon-mcp enabled, Components/Button|Input|Card)
 ├── docs/
 │   └── architecture-reference.md  # Full internal reference
 ├── .github/

docs/adapter-model.md

@@ -91,6 +91,16 @@ The `af design drift` command compares component data across available surfaces:
 
 Drift findings use **corroboration rules** to filter noise: a story-derived variant is only reported if (1) the variant axis maps to a real prop, (2) the value appears in the prop's type definition. Findings carry `confidence: 'high'` (constrained union match) or `'low'` (unconstrained type like `string`).
 
+#### Normalization Layer (Phase 16D)
+
+Before comparison, surface snapshots pass through a **deterministic normalization layer** (`crossSurfaceDrift/normalize.ts`) that:
+
+1. **Filters design-only fields** from Figma (e.g., `fills`, `cornerRadius`, `width`, `height`) that have no API-level counterpart
+2. **Normalizes prop aliases** across surfaces (e.g., Figma `State` → canonical `variant`, Figma `text` → canonical `label`)
+3. **Deduplicates** props that collide after renaming
+
+This eliminates false-positive drift caused by naming differences between surfaces. The normalization config is deterministic and configurable via `NormalizationConfig` — see [architecture-reference.md](architecture-reference.md) for full details.
+
 ## Detailed Reference
 
 The full adapter model, including MCP transport configuration, tool policies, and Phase 16A/16B/16C implementation details, is documented in [architecture-reference.md](architecture-reference.md).

docs/architecture-reference.md

@@ -535,6 +535,7 @@ The system follows a **three-legged stool** design with strict runtime boundarie
 | **Phase 16A.1** | Surface Classification Metadata (adapter taxonomy) | ✅ |
 | **Phase 16B** | Figma Console MCP Adapter (read-only) | ✅ |
 | **Phase 16C** | Storybook MCP Adapter + Cross-Surface Drift Analysis | ✅ |
+| **Phase 16D** | Cross-Surface Drift Normalization Layer | ✅ |
 
 ### Not Implemented Yet
 
@@ -558,7 +559,7 @@ The reconciliation system is **feature-complete through Phase 14F**. Key capabil
 - **Unified Reconcile CLI (14A–14F)**: `figma:reconcile` entry point, profiles (local/record/ci), bundle artifacts, GitHub Actions matrix workflow, multi-source discovery
 - **Configuration & Profiles (15A–15B)**: `af.config.json`, named policy profiles (designer-first, code-first, balanced, strict-review)
 - **CLI & Inspector (15C–15D)**: Unified `af` CLI (control surface, not runtime), artifact listing/inspection/trace
-- **Design Adapters (16A–16C)**: Read-only design adapter interface, Figma Console MCP adapter, Storybook MCP adapter, surface classification metadata, cross-surface drift analysis
+- **Design Adapters (16A–16D)**: Read-only design adapter interface, Figma Console MCP adapter, Storybook MCP adapter, surface classification metadata, cross-surface drift analysis, drift normalization layer
 
 Echo suppression prevents feedback loops when AST writes trigger file save events.
 
@@ -5589,6 +5590,62 @@ Props are extracted from `reactDocgen` metadata via `extractProps()` in `storybo
 
 `demo-app/src/DemoButton.tsx` and `demo-app/src/stories/DemoButton.stories.tsx` provide a minimal component with typed props and matching Storybook stories for verifying drift analysis end-to-end.
 
+### Cross-Surface Drift: Normalization Layer (Phase 16D)
+
+Different surfaces use different names for the same concepts, causing false-positive drift findings. Phase 16D adds a **deterministic, configurable normalization layer** that aligns equivalent concepts before comparison.
+
+#### Problem
+
+| Surface | Variant Axis | Text Prop | Layout Props |
+|---------|-------------|-----------|-------------|
+| Figma | `State` (VARIANT) | `text` (TEXT) | `fills`, `cornerRadius`, `width`, `height` |
+| Storybook | `variant` | `label` | (none) |
+| Code | `variant` | `label` | (none) |
+
+Without normalization, `State` vs `variant` and `text` vs `label` appear as false drift, and Figma-only layout properties generate noise.
+
+#### Solution
+
+`normalize.ts` in `crossSurfaceDrift/` applies three passes to each surface snapshot **before** comparison:
+
+1. **Design-only filtering** (Figma only): Removes layout/visual properties (`fills`, `cornerRadius`, `width`, `height`, `padding`, `gap`, `fontSize`, `fontWeight`, `textContent`) that have no API-level counterpart
+2. **Alias normalization** (all surfaces): Renames equivalent prop names to a canonical form using a configurable alias map
+3. **Deduplication**: Merges props that collide after renaming
+
+Default alias rules:
+
+| Canonical | Aliases |
+|-----------|---------|
+| `variant` | `state`, `variant` |
+| `label` | `text`, `label` |
+
+#### Configuration
+
+Normalization is configured via `NormalizationConfig` (defined in `@aesthetic-function/shared/crossSurfaceDrift`):
+
+```typescript
+interface NormalizationConfig {
+  propAliases: Array<{ canonical: string; aliases: string[] }>;
+  designOnlyFields: { names: string[]; strategy: 'exclude' | 'tag' };
+}
+```
+
+The default config (`DEFAULT_NORMALIZATION_CONFIG` in `normalize.ts`) handles the DemoButton demo. Custom configs can be passed via `DriftAnalysisOptions.normalizationConfig` for per-project overrides.
+
+#### Traceability
+
+Normalization is fully explainable:
+
+- **`SurfaceProp.normalizedFrom`**: When a prop is renamed (e.g., `State` → `variant`), the original name is preserved in `normalizedFrom`
+- **`CrossSurfaceDriftReport.normalization`**: The report includes metadata listing all applied alias rules and excluded design-only props, with surface attribution
+
+#### Design Decisions
+
+- Normalization runs **before** comparison, transforming snapshots rather than patching findings. The existing `comparePropInventory` and `compareVariantCoverage` functions require zero changes.
+- Design-only filtering applies only to the Figma surface — if Code/Storybook happens to have a prop named `fills`, it is not filtered.
+- Alias matching is case-insensitive but the canonical name is always lowercase.
+- The `strategy: 'tag'` option (alternative to `'exclude'`) is defined but not yet implemented — it would keep design-only props but mark them for separate "visual drift" reporting.
+
 ---
 
 ## Protocol Version

packages/shared/src/crossSurfaceDrift.ts

@@ -41,6 +41,9 @@ export interface CrossSurfaceDriftReport {
 
   /** When the analysis was performed */
   analyzedAt: string;
+
+  /** Normalization metadata showing what was renamed/excluded before comparison */
+  normalization?: NormalizationMetadata;
 }
 
 // =============================================================================
@@ -74,6 +77,8 @@ export interface SurfaceProp {
   name: string;
   type?: string;
   values?: string[];
+  /** Original name before alias normalization (set only when name was changed) */
+  normalizedFrom?: string;
 }
 
 // =============================================================================
@@ -144,4 +149,53 @@ export interface DriftAnalysisOptions {
 
   /** Surfaces that were queried by the caller (used to distinguish "not checked" from "checked, not found") */
   queriedSurfaces?: ('figma' | 'storybook' | 'code')[];
+
+  /** Override the default normalization config (alias mappings + design-only filters) */
+  normalizationConfig?: NormalizationConfig;
+}
+
+// =============================================================================
+// NORMALIZATION
+// =============================================================================
+
+/**
+ * Configuration for the pre-comparison normalization layer.
+ * Deterministic and configurable — no LLM or fuzzy matching.
+ */
+export interface NormalizationConfig {
+  /** Alias groups: equivalent prop names across surfaces mapped to a canonical name */
+  propAliases: Array<{
+    /** The canonical name all surfaces will be normalized TO */
+    canonical: string;
+    /** Surface-specific names that map to this canonical name (matched case-insensitively) */
+    aliases: string[];
+  }>;
+
+  /** Figma-only layout/visual properties to filter from drift comparison */
+  designOnlyFields: {
+    /** Property names to treat as design-only (matched case-insensitively) */
+    names: string[];
+    /** 'exclude' removes from snapshot; 'tag' keeps but marks (future use) */
+    strategy: 'exclude' | 'tag';
+  };
+}
+
+/**
+ * Metadata about what normalization was applied before comparison.
+ * Provides explainability/traceability for the drift report.
+ */
+export interface NormalizationMetadata {
+  /** Prop names that were renamed via alias rules */
+  appliedRules: Array<{
+    originalName: string;
+    canonicalName: string;
+    surface: 'figma' | 'storybook' | 'code';
+  }>;
+
+  /** Props excluded from comparison as design-only */
+  excludedProps: Array<{
+    name: string;
+    surface: 'figma' | 'storybook' | 'code';
+    reason: 'design-only';
+  }>;
 }

packages/watcher/src/crossSurfaceDrift/__tests__/analyze.test.ts

@@ -365,10 +365,12 @@ describe('figma componentPropertyDefinitions', () => {
     expect(report.surfaces.figma).toBeDefined();
     expect(report.surfaces.figma!.variants).toContain('Default');
     expect(report.surfaces.figma!.variants).toContain('Hover');
-    const stateProp = report.surfaces.figma!.props.find(p => p.name === 'State');
-    expect(stateProp).toBeDefined();
-    expect(stateProp!.type).toBe('VARIANT');
-    expect(stateProp!.values).toEqual(['Default', 'Hover']);
+    // After normalization, "State" is renamed to canonical "variant"
+    const variantProp = report.surfaces.figma!.props.find(p => p.name === 'variant');
+    expect(variantProp).toBeDefined();
+    expect(variantProp!.type).toBe('VARIANT');
+    expect(variantProp!.values).toEqual(['Default', 'Hover']);
+    expect(variantProp!.normalizedFrom).toBe('State');
   });
 
   it('extracts TEXT property definitions into props', () => {
@@ -471,6 +473,170 @@ describe('storybook story name fallback', () => {
   });
 });
 
+// =============================================================================
+// NORMALIZATION — FALSE POSITIVE ELIMINATION (Phase 16D)
+// =============================================================================
+
+describe('normalization — DemoButton false positive elimination', () => {
+  it('eliminates State/variant false positive (Figma "State" ↔ Code/Storybook "variant")', () => {
+    const report = analyzeCrossSurfaceDrift(
+      'DemoButton',
+      makeFigmaComponent({
+        name: 'DemoButton',
+        type: 'component-set',
+        variants: [],
+        componentPropertyDefinitions: {
+          State: {
+            type: 'VARIANT',
+            defaultValue: 'Default',
+            variantOptions: ['Default', 'Hover'],
+          },
+        },
+      }),
+      makeStorybookComponent({
+        name: 'DemoButton',
+        props: [
+          { name: 'variant', type: "'Default' | 'Hover'", required: false },
+        ],
+        stories: [
+          { id: 'demobutton--default', name: 'Default', variantAxes: { variant: 'Default' } },
+          { id: 'demobutton--hover', name: 'Hover', variantAxes: { variant: 'Hover' } },
+        ],
+      }),
+      { props: ['variant'], variants: ['Default', 'Hover'] },
+      { queriedSurfaces: ['figma', 'storybook', 'code'] },
+    );
+
+    // Should NOT have findings about "state" missing in Storybook/Code
+    // or "variant" missing in Figma — they're the same concept
+    const propFindings = report.findings.filter(f => f.field.startsWith('prop:'));
+    const stateFindings = propFindings.filter(f => f.field.includes('state'));
+    const variantFindings = propFindings.filter(f => f.field.includes('variant'));
+    expect(stateFindings).toHaveLength(0);
+    expect(variantFindings).toHaveLength(0);
+
+    // Figma snapshot should show "variant" (normalized from "State")
+    const figmaVariantProp = report.surfaces.figma!.props.find(p => p.name === 'variant');
+    expect(figmaVariantProp).toBeDefined();
+    expect(figmaVariantProp!.normalizedFrom).toBe('State');
+  });
+
+  it('eliminates text/label false positive (Figma "text" ↔ Code/Storybook "label")', () => {
+    const report = analyzeCrossSurfaceDrift(
+      'DemoButton',
+      makeFigmaComponent({
+        name: 'DemoButton',
+        type: 'component-set',
+        variants: [],
+        componentPropertyDefinitions: {
+          'text#12:34': {
+            type: 'TEXT',
+            defaultValue: 'Click me',
+          },
+        },
+      }),
+      makeStorybookComponent({
+        name: 'DemoButton',
+        props: [
+          { name: 'label', type: 'string', required: false },
+        ],
+        stories: [],
+      }),
+      { props: ['label'], variants: [] },
+      { queriedSurfaces: ['figma', 'storybook', 'code'] },
+    );
+
+    // "text" cleaned to "text" by CPD handler, then normalized to "label"
+    // Should NOT have findings about text/label mismatch
+    const propFindings = report.findings.filter(f => f.field.startsWith('prop:'));
+    const textFindings = propFindings.filter(f => f.field.includes('text'));
+    const labelFindings = propFindings.filter(f =>
+      f.field.includes('label') && (f.type === 'missing-in-figma' || f.type === 'missing-in-storybook'),
+    );
+    expect(textFindings).toHaveLength(0);
+    expect(labelFindings).toHaveLength(0);
+  });
+
+  it('suppresses design-only properties from Figma (fills, cornerRadius, width, height)', () => {
+    const report = analyzeCrossSurfaceDrift(
+      'DemoButton',
+      makeFigmaComponent({
+        name: 'DemoButton',
+        type: 'component-set',
+        variants: [],
+        properties: {
+          fills: ['#3B82F6'],
+          cornerRadius: 8,
+          width: 200,
+          height: 48,
+        },
+      }),
+      makeStorybookComponent({
+        name: 'DemoButton',
+        props: [
+          { name: 'variant', type: "'Default' | 'Hover'", required: false },
+        ],
+        stories: [],
+      }),
+      { props: ['variant'], variants: [] },
+      { queriedSurfaces: ['figma', 'storybook', 'code'] },
+    );
+
+    // Should NOT have findings about fills, cornerRadius, width, height
+    const layoutFindings = report.findings.filter(f =>
+      f.field.includes('fills') ||
+      f.field.includes('cornerradius') ||
+      f.field.includes('width') ||
+      f.field.includes('height'),
+    );
+    expect(layoutFindings).toHaveLength(0);
+
+    // Figma snapshot should not contain these props
+    const figmaProps = report.surfaces.figma!.props.map(p => p.name.toLowerCase());
+    expect(figmaProps).not.toContain('fills');
+    expect(figmaProps).not.toContain('cornerradius');
+    expect(figmaProps).not.toContain('width');
+    expect(figmaProps).not.toContain('height');
+  });
+
+  it('includes normalization metadata in the report', () => {
+    const report = analyzeCrossSurfaceDrift(
+      'DemoButton',
+      makeFigmaComponent({
+        name: 'DemoButton',
+        type: 'component-set',
+        variants: [],
+        componentPropertyDefinitions: {
+          State: {
+            type: 'VARIANT',
+            defaultValue: 'Default',
+            variantOptions: ['Default', 'Hover'],
+          },
+        },
+        properties: {
+          fills: ['#3B82F6'],
+          cornerRadius: 8,
+        },
+      }),
+      null,
+      null,
+    );
+
+    expect(report.normalization).toBeDefined();
+
+    // "State" → "variant" should be in appliedRules
+    const stateRule = report.normalization!.appliedRules.find(r => r.originalName === 'State');
+    expect(stateRule).toBeDefined();
+    expect(stateRule!.canonicalName).toBe('variant');
+    expect(stateRule!.surface).toBe('figma');
+
+    // fills and cornerRadius should be in excludedProps
+    const excluded = report.normalization!.excludedProps.map(e => e.name);
+    expect(excluded).toContain('fills');
+    expect(excluded).toContain('cornerRadius');
+  });
+});
+
 // =============================================================================
 // CROSS-SURFACE DRIFT WITH RICH METADATA
 // =============================================================================