feat(m3): component_map reports unmatchedProps (component-extension TODOs)

Add candidate.unmatchedProps — the actionable inverse of matchedProps:
Figma component-property axes (variant / boolean / text) with no matching
prop on the candidate code component. Codegen surfaces these as
extension TODOs instead of silently dropping design intent (a leading
icon, a `required` flag, an active state).

Also diff props on the override (map-file) path, which previously never
resolved the scanned component: resolveOverrideComponent looks it up by
repo-relative path then name, so map-file mappings now report both
matchedProps and unmatchedProps.

Driven by a hard-screen codegen A/B (Design A 15131:1478 案件管理) where
"reuse (high)" was lossy — Button lacked Show icon_L/R, Input lacked the
date/select/required axes, Sidebar lacked the active item. Live-verified:
those axes now land in unmatchedProps with zero join regression.
494 tests green (vitest).

Author: awdr74100

packages/server/src/join/component-map.ts

@@ -49,6 +49,13 @@ export interface ComponentMapping {
     confidence: number;
     /** Variant axes that also exist as props on the matched component. */
     matchedProps: string[];
+    /**
+     * Figma component-property axes (variant / boolean / text) with no matching prop on the
+     * candidate — the actionable inverse of matchedProps. The component must be extended to carry
+     * them (e.g. a leading-icon toggle, a `required` flag, an active/selected state). Codegen
+     * surfaces these as component-extension TODOs instead of silently dropping the design intent.
+     */
+    unmatchedProps: string[];
   };
   status: MappingStatus;
   /** Which path produced the mapping. */
@@ -122,6 +129,35 @@ const statusFor = (confidence: number, threshold: number): MappingStatus => {
   return 'unmapped';
 };
 
+/**
+ * Split a usage's Figma axes into those the candidate already has as props (matchedProps) and those
+ * it lacks (unmatchedProps — the component-extension TODOs). Same casefold predicate for both, so
+ * matched ∪ unmatched == variantAxes.
+ */
+const partitionAxes = (
+  variantAxes: readonly string[],
+  component: ScannedComponent,
+): { matchedProps: string[]; unmatchedProps: string[] } => {
+  const codeProps = new Set(component.propNames.map(p => p.toLowerCase()));
+  const matchedProps: string[] = [];
+  const unmatchedProps: string[] = [];
+  for (const axis of variantAxes) {
+    (codeProps.has(axis.toLowerCase()) ? matchedProps : unmatchedProps).push(axis);
+  }
+  return { matchedProps, unmatchedProps };
+};
+
+/**
+ * The scanned component an override points to, so its props can be diffed against the Figma axes
+ * even on the map-file path. Match by repo-relative path first, then by component name.
+ */
+const resolveOverrideComponent = (
+  override: { name: string; filePath: string },
+  scanned: readonly ScannedComponent[],
+): ScannedComponent | undefined =>
+  scanned.find(c => c.filePath === override.filePath) ??
+  scanned.find(c => norm(c.name) === norm(override.name));
+
 export interface JoinOptions {
   threshold: number;
   /** Explicit figmaName → code target overrides (highest authority). */
@@ -144,13 +180,18 @@ const joinOne = (
 
   const override = opts.overrides?.get(usage.name) ?? opts.overrides?.get(norm(usage.name));
   if (override !== undefined) {
+    const component = resolveOverrideComponent(override, scanned);
+    const { matchedProps, unmatchedProps } = component
+      ? partitionAxes(usage.variantAxes, component)
+      : { matchedProps: [], unmatchedProps: [] };
     return {
       ...shared,
       candidate: {
         name: override.name,
         filePath: override.filePath,
         confidence: 1,
-        matchedProps: [],
+        matchedProps,
+        unmatchedProps,
       },
       status: 'high',
       source: 'map-file',
@@ -164,8 +205,7 @@ const joinOne = (
 
   // Variant bonus: reward code props that cover the instance's variant axes, but only once the name
   // already plausibly matches, so an unrelated component can't be promoted on prop overlap alone.
-  const codeProps = new Set(match.component.propNames.map(p => p.toLowerCase()));
-  const matchedProps = usage.variantAxes.filter(axis => codeProps.has(axis.toLowerCase()));
+  const { matchedProps, unmatchedProps } = partitionAxes(usage.variantAxes, match.component);
   const bonus = Math.min(MAX_VARIANT_BONUS, matchedProps.length * VARIANT_BONUS_PER_PROP);
   const confidence = Math.min(1, Number((match.score + bonus).toFixed(3)));
 
@@ -176,6 +216,7 @@ const joinOne = (
       filePath: match.component.filePath,
       confidence,
       matchedProps,
+      unmatchedProps,
     },
     status: statusFor(confidence, opts.threshold),
     source: 'scan',

packages/server/src/tools/component-map.ts

@@ -48,6 +48,8 @@ export const componentMapToolDefinition: Tool = {
     'they can be reused instead of regenerated. Joins the grounded Figma component names (and their ' +
     'variant axes) against an AST scan of the project; an explicit docs/figma-component-map.md row ' +
     'overrides the fuzzy match. Each distinct component is mapped once with all its instance ids. ' +
+    'A mapped candidate also reports matchedProps (Figma axes the component already has) and ' +
+    'unmatchedProps (axes it lacks → component-extension TODOs). ' +
     'Returns { mappings (candidate + confidence + status high/medium/low/unmapped), unmapped, profile }.',
   inputSchema: {
     type: 'object',

packages/server/test/join/component-map.test.ts

@@ -62,6 +62,28 @@ describe('joinComponents', () => {
     expect(m?.candidate?.matchedProps).toEqual(['Size', 'Variant']);
   });
 
+  it('reports Figma axes the candidate lacks as unmatchedProps (extension TODOs)', () => {
+    const [m] = joinComponents(
+      [usage({ name: 'Button', variantAxes: ['Size', 'Variant', 'Show icon_L', 'State'] })],
+      scanned, // Button props: size, variant
+      { threshold: 0.7 },
+    );
+    expect(m?.candidate?.matchedProps).toEqual(['Size', 'Variant']);
+    expect(m?.candidate?.unmatchedProps).toEqual(['Show icon_L', 'State']);
+  });
+
+  it('diffs props on the override path too, resolving the scanned component', () => {
+    const overrides = new Map([['btn', { name: 'Button', filePath: 'src/components/Button.tsx' }]]);
+    const [m] = joinComponents(
+      [usage({ name: 'btn', variantAxes: ['Size', 'Show icon_L'] })],
+      scanned, // Button at src/components/Button.tsx, props: size, variant
+      { threshold: 0.7, overrides },
+    );
+    expect(m?.source).toBe('map-file');
+    expect(m?.candidate?.matchedProps).toEqual(['Size']);
+    expect(m?.candidate?.unmatchedProps).toEqual(['Show icon_L']);
+  });
+
   it('flags unmapped when nothing is close', () => {
     const [m] = joinComponents([usage({ name: 'Tooltip' })], scanned, { threshold: 0.7 });
     expect(m?.status).toBe('unmapped');

packages/skills/figma-codegen/SKILL.md

@@ -31,6 +31,9 @@ the rendered image.
    - Each entry's `instances[]` carries the per-instance `props` (resolved variant / boolean / text
      values, e.g. `{ Size: "Medium", Type: "Primary", "show 必填": true }`). Wire those onto the reused
      component — one element per instance, with its own props — instead of a single generic element.
+   - `candidate.unmatchedProps`: Figma axes the reused component has **no prop for** (e.g. a leading
+     icon, a `required` flag, an active state). Reuse the component, but surface these as
+     component-extension TODOs — don't silently drop them or fake them with ad-hoc markup.
 3. **`token_map`** → every Figma variable joined to a project token with `status` + `ref` (the Tailwind
    utility base or `var(--…)`) + `matchedBy` (`name` / `value`).
    - mapped: reference `candidate.ref` (e.g. `bg-primary-500`, `var(--color-primary-500)`) — never the
@@ -53,3 +56,4 @@ token references for color/spacing/radius/typography.
 - Never write a config file or wizard prompt; everything is inferred from the project + the three tools.
 - If a reused component lacks a prop the design needs (e.g. a `required` field, a password toggle), say
   so — that's a real extension the component needs, not something to fake with ad-hoc markup.
+  `component_map` reports these directly as `candidate.unmatchedProps`; turn them into TODOs.