refactor(m3): hardening review — SFC props, CSS-var token grounding, cleanup

A retrospective pass over the M3 surface (which deviated a lot from the
original plan) for more-general implementations, holding the line at "no
regression". Four findings, each strictly ≥ today:

1. Vue/Svelte prop extraction (+ false-TODO safety net). The scanner only
   took a filename baseline for SFCs (propNames []), so the join dumped every
   variant axis into unmatchedProps — a false "extend this component" TODO on
   every reused Vue/Svelte component. Now parse the <script> block: Vue
   defineProps (type/object/array), Vue Options-API props, Svelte export let /
   $props(). ScannedComponent gains propsExtracted so the join can tell
   "genuinely no props" from "unknown" and suppress unmatched/matched when
   unknown. React path unchanged.

2. CSS-variable token grounding (token_map). When no single token config is
   detected (a plain :root custom-property project, or Tailwind whose @theme
   entry wasn't located), aggregate custom properties across the repo's CSS
   and let the join filter them — incidental vars stay unmatched, so this only
   adds real matches, never regresses. Unlocks the large class of non-Tailwind
   design systems that previously got no automatic token grounding.

3. Remove the cut/deferred greenfield skill stubs (figma-audit,
   figma-sync-tokens) per the M3 re-eval — their frontmatter advertised tools
   that will never exist and would mis-trigger Claude. Dropped the README cp
   lines and the figma-codegen handoff mention.

4. Hoist the duplicated IGNORED_DIRS into a shared module (scan / profile /
   the new repo-css aggregator), so a vendor/build dir is added once.

Drive-by: fix a pre-existing plugin typecheck break — newer plugin-typings add
nodes without an index signature, so serializer.ts's `as Record<string,
unknown>` cast no longer type-checks; use a per-property cast (the file's idiom).

546 tests (+9), typecheck + build green.

Author: awdr74100

packages/plugin/src/serializer.ts

@@ -206,7 +206,15 @@ const enrichWithMixins = (node: SceneNode, base: SerializedNode): SerializedNode
         // table row dividers, underline inputs and top-accent rules are all per-side, and
         // collapsing to a single "mixed" loses which edges actually have a stroke.
         out.strokeWeight = MIXED;
-        const n = node as Record<string, unknown>;
+        // Per-property cast (matching this file's idiom) rather than `as Record<string, unknown>`:
+        // newer plugin-typings include nodes (e.g. SlotNode) without an index signature, so the
+        // record cast no longer type-checks.
+        const n = node as {
+          strokeTopWeight?: unknown;
+          strokeRightWeight?: unknown;
+          strokeBottomWeight?: unknown;
+          strokeLeftWeight?: unknown;
+        };
         const sides = {
           top: n.strokeTopWeight,
           right: n.strokeRightWeight,

packages/server/src/ignored-dirs.ts

@@ -0,0 +1,16 @@
+// Directories never worth walking when scanning a repo (components, CSS entries, token sources).
+// Shared so the component scanner, the profile's CSS probe, and the token aggregator stay in lockstep
+// — adding a build/vendor dir here covers every repo walk at once instead of drifting per copy.
+export const IGNORED_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  '.git',
+  'coverage',
+]);
+
+/** True when any path segment is an ignored (vendor/build) directory. */
+export const isIgnoredPath = (relPath: string): boolean =>
+  relPath.split('/').some(seg => IGNORED_DIRS.has(seg));

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

@@ -136,11 +136,17 @@ const statusFor = (confidence: number, threshold: number): MappingStatus => {
  * 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.
+ *
+ * When the component's props couldn't be parsed (propsExtracted === false — a baseline scan that
+ * didn't read props), we can't tell matched from unmatched: return both empty rather than dumping
+ * every axis into unmatchedProps, which would otherwise report a true "extend this component" TODO
+ * for props that very likely already exist (the case for an unparsed Vue/Svelte SFC).
  */
 const partitionAxes = (
   variantAxes: readonly string[],
   component: ScannedComponent,
 ): { matchedProps: string[]; unmatchedProps: string[] } => {
+  if (!component.propsExtracted) return { matchedProps: [], unmatchedProps: [] };
   const codeProps = new Set(component.propNames.map(p => p.toLowerCase()));
   const matchedProps: string[] = [];
   const unmatchedProps: string[] = [];

packages/server/src/profile/profile.ts

@@ -1,6 +1,8 @@
 import { glob, readFile } from 'node:fs/promises';
 import { join, relative, resolve } from 'node:path';
 
+import { isIgnoredPath } from '../ignored-dirs.js';
+
 // Project Profile — the structured "how this project writes code" that the join tools (component_map,
 // token_map) switch their target side on. Detection is split in two: gatherProjectInput does the IO
 // (reads manifests / probes for config files / scans CSS entry points) and detectProfile is a pure
@@ -96,17 +98,6 @@ const TAILWIND_CONFIGS = [
 /** Config files worth probing for at the project root; presence feeds styling detection. */
 const PROBE_CONFIG_FILES = [...TAILWIND_CONFIGS];
 
-/** Directories never worth walking when scanning for CSS entry points. */
-const IGNORED_DIRS = new Set([
-  'node_modules',
-  'dist',
-  'build',
-  '.next',
-  '.nuxt',
-  '.git',
-  'coverage',
-]);
-
 // Tailwind v4 marks its CSS-first config inline: `@import "tailwindcss"` pulls the framework in and
 // `@theme { ... }` declares tokens. Either marker identifies the v4 token source.
 const CSS_TAILWIND_IMPORT = /@import\s+["']tailwindcss["']/;
@@ -138,7 +129,7 @@ const findTailwindCssEntry = async (root: string): Promise<string | undefined> =
   let scanned = 0;
   for await (const entry of glob('**/*.css', { cwd: root })) {
     const rel = typeof entry === 'string' ? entry : String(entry);
-    if (rel.split('/').some(seg => IGNORED_DIRS.has(seg))) continue;
+    if (isIgnoredPath(rel)) continue;
     if (scanned >= 200) break; // safety cap against pathological repos
     scanned += 1;
     let body: string;

packages/server/src/scan/scan.ts

@@ -3,6 +3,8 @@ import { basename, dirname, extname, join } from 'node:path';
 
 import { parseSync } from 'oxc-parser';
 
+import { isIgnoredPath } from '../ignored-dirs.js';
+
 // Component scanner — finds the project's existing components so component_map can join Figma names
 // against them. The guiding principle: never pattern-match the directory layout (feature-based, atomic,
 // flat all differ); identify a component by its *AST signature* (a PascalCase, exported, function-ish
@@ -17,22 +19,19 @@ export interface ScannedComponent {
   /** Repo-relative path. */
   filePath: string;
   exportKind: 'default' | 'named';
-  /** Best-effort destructured prop names from the component's first param; [] when not extractable. */
+  /** The component's prop names; [] when the component has none OR they couldn't be parsed. */
   propNames: string[];
+  /**
+   * Whether propNames is a real parse result (so [] means "genuinely no props") versus a baseline
+   * that couldn't read props (so [] means "unknown"). The component join uses this to avoid
+   * reporting every variant axis as an unmatched prop just because we never parsed the props — a
+   * false "extend this component" TODO. True once we've parsed the source; false only on a parse
+   * failure.
+   */
+  propsExtracted: boolean;
   framework: ComponentFramework;
 }
 
-/** Directories never worth walking. */
-const IGNORED_DIRS = new Set([
-  'node_modules',
-  'dist',
-  'build',
-  '.next',
-  '.nuxt',
-  '.git',
-  'coverage',
-]);
-
 /** React HOCs whose call wraps a component function — the binding is still a component. */
 const COMPONENT_WRAPPERS = new Set(['forwardRef', 'memo', 'observer']);
 
@@ -120,23 +119,188 @@ export const extractReactComponents = (filePath: string, code: string): ScannedC
       filePath,
       exportKind: cand.exportKind,
       propNames: propNamesOf(cand.fn),
+      propsExtracted: true,
       framework: 'react',
     });
   }
   return out;
 };
 
+/* eslint-disable @typescript-eslint/no-explicit-any -- shared oxc AST walker below */
+
+/** Depth-first walk of an oxc/ESTree node, yielding every CallExpression encountered. */
+const collectCalls = (root: any): any[] => {
+  const out: any[] = [];
+  const visit = (node: any): void => {
+    if (node === null || typeof node !== 'object') return;
+    if (node.type === 'CallExpression') out.push(node);
+    for (const key of Object.keys(node)) {
+      const v = (node as Record<string, unknown>)[key];
+      if (Array.isArray(v)) for (const c of v) visit(c);
+      else if (v !== null && typeof v === 'object') visit(v);
+    }
+  };
+  visit(root);
+  return out;
+};
+
+/** Prop names from a `defineProps` call: a type literal, an object, or an array of string keys. */
+const definePropsNames = (call: any): string[] => {
+  // Type form: defineProps<{ size?: string; variant: 'a' | 'b' }>(). oxc exposes the instantiation as
+  // typeArguments (older trees: typeParameters); its first param is a TSTypeLiteral whose members'
+  // keys are the prop names.
+  const typeArgs = call.typeArguments ?? call.typeParameters;
+  const typeLiteral = typeArgs?.params?.[0];
+  if (typeLiteral?.type === 'TSTypeLiteral') {
+    return (typeLiteral.members ?? [])
+      .map((m: any) => m?.key?.name)
+      .filter((n: unknown): n is string => typeof n === 'string');
+  }
+  const arg0 = call.arguments?.[0];
+  // Object form: defineProps({ size: String, variant: { type: String } }) → keys.
+  if (arg0?.type === 'ObjectExpression') {
+    return (arg0.properties ?? [])
+      .map((p: any) => p?.key?.name ?? p?.key?.value)
+      .filter((n: unknown): n is string => typeof n === 'string');
+  }
+  // Array form: defineProps(['size', 'variant']) → the string literals.
+  if (arg0?.type === 'ArrayExpression') {
+    return (arg0.elements ?? [])
+      .map((e: any) => (e?.type === 'Literal' ? e.value : undefined))
+      .filter((n: unknown): n is string => typeof n === 'string');
+  }
+  return [];
+};
+
+/** Names from a `props: { … } | [ … ]` member of an object (Vue Options API props declaration). */
+const propsMemberNames = (obj: any): string[] => {
+  const propsProp = (obj?.properties ?? []).find(
+    (p: any) => (p?.key?.name ?? p?.key?.value) === 'props',
+  );
+  const value = propsProp?.value;
+  if (value?.type === 'ObjectExpression') {
+    return (value.properties ?? [])
+      .map((p: any) => p?.key?.name ?? p?.key?.value)
+      .filter((n: unknown): n is string => typeof n === 'string');
+  }
+  if (value?.type === 'ArrayExpression') {
+    return (value.elements ?? [])
+      .map((e: any) => (e?.type === 'Literal' ? e.value : undefined))
+      .filter((n: unknown): n is string => typeof n === 'string');
+  }
+  return [];
+};
+
+/**
+ * Vue Options API prop names: `export default { props: { … } }` — or wrapped in defineComponent /
+ * defineNuxtComponent. The default export is either an object or a call whose first arg is the
+ * object.
+ */
+const vueOptionsPropsNames = (program: any): string[] => {
+  for (const node of program.body ?? []) {
+    if (node.type !== 'ExportDefaultDeclaration') continue;
+    const d = node.declaration;
+    const obj = d?.type === 'ObjectExpression' ? d : d?.arguments?.[0];
+    if (obj?.type === 'ObjectExpression') return propsMemberNames(obj);
+  }
+  return [];
+};
+
+/** Svelte prop names: `export let foo` (Svelte 4) and `let { a, b } = $props()` (Svelte 5 runes). */
+const sveltePropNames = (program: any): string[] => {
+  const names = new Set<string>();
+  for (const node of program.body ?? []) {
+    if (
+      node.type === 'ExportNamedDeclaration' &&
+      node.declaration?.type === 'VariableDeclaration' &&
+      node.declaration.kind === 'let'
+    ) {
+      for (const d of node.declaration.declarations ?? [])
+        if (d?.id?.type === 'Identifier' && typeof d.id.name === 'string') names.add(d.id.name);
+    }
+  }
+  // Svelte 5 runes: `let { a, b } = $props()` — a destructuring declarator initialized by $props().
+  for (const node of program.body ?? []) {
+    if (node.type !== 'VariableDeclaration') continue;
+    for (const d of node.declarations ?? []) {
+      if (d?.init?.type === 'CallExpression' && d.init.callee?.name === '$props') {
+        for (const p of d.id?.properties ?? [])
+          if (p?.key?.name && typeof p.key.name === 'string') names.add(p.key.name);
+      }
+    }
+  }
+  return [...names];
+};
+
 /* eslint-enable @typescript-eslint/no-explicit-any */
 
 const REACT_EXTS = new Set(['.tsx', '.jsx']);
 
-/** Baseline extractor for SFC frameworks: the file is the component, name derived from the path. */
-const extractSfcComponent = (
+// Pull every <script> / <script setup> body out of an SFC. lang="ts" (or its absence) decides the
+// parser dialect; a .vue/.svelte file with no script block is a genuinely prop-less template.
+const SCRIPT_BLOCK = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+
+interface ScriptBlock {
+  body: string;
+  ts: boolean;
+}
+
+const extractScriptBlocks = (code: string): ScriptBlock[] => {
+  const out: ScriptBlock[] = [];
+  for (const m of code.matchAll(SCRIPT_BLOCK)) {
+    const attrs = m[1] ?? '';
+    out.push({ body: m[2] ?? '', ts: /\blang=["']ts["']/.test(attrs) });
+  }
+  return out;
+};
+
+/**
+ * Extract a single-file component (Vue / Svelte). The file is the component (its name is the file
+ * by convention); props come from the <script> block — Vue's defineProps (type / object / array
+ * forms) and Options-API `props`, Svelte's `export let` / `$props()`.
+ *
+ * PropsExtracted distinguishes "[] = genuinely no props" from "[] = unknown" so the join won't
+ * invent extension TODOs. It's true only when we either found props, or the file is a script-less
+ * (so genuinely prop-less) template. When a script is present but we read no props — a parse error,
+ * or a prop-declaration style we don't recognize — it stays false (conservative: the join then
+ * suppresses matched/unmatched rather than asserting prop gaps we can't actually see). oxc doesn't
+ * throw on bad input, so a parse failure surfaces here simply as "no props found".
+ */
+export const extractSfcComponent = (
   filePath: string,
+  code: string,
   framework: ComponentFramework,
-): ScannedComponent[] => [
-  { name: nameFromFile(filePath), filePath, exportKind: 'default', propNames: [], framework },
-];
+): ScannedComponent[] => {
+  const base = {
+    name: nameFromFile(filePath),
+    filePath,
+    exportKind: 'default' as const,
+    framework,
+  };
+  const scripts = extractScriptBlocks(code);
+  if (scripts.length === 0) return [{ ...base, propNames: [], propsExtracted: true }];
+
+  const names = new Set<string>();
+  for (const script of scripts) {
+    let program: ReturnType<typeof parseSync>['program'];
+    try {
+      // Name the virtual source so oxc picks the right dialect (TS enables defineProps<...>()).
+      program = parseSync(`sfc.${script.ts ? 'ts' : 'js'}`, script.body).program;
+    } catch {
+      continue;
+    }
+    if (framework === 'vue') {
+      for (const call of collectCalls(program))
+        if ((call as { callee?: { name?: string } }).callee?.name === 'defineProps')
+          for (const n of definePropsNames(call)) names.add(n);
+      for (const n of vueOptionsPropsNames(program)) names.add(n);
+    } else {
+      for (const n of sveltePropNames(program)) names.add(n);
+    }
+  }
+  // Found props → confidently extracted. None found despite a script → unknown (don't claim).
+  return [{ ...base, propNames: [...names], propsExtracted: names.size > 0 }];
+};
 
 const frameworkForExt = (ext: string): ComponentFramework | null => {
   if (REACT_EXTS.has(ext)) return 'react';
@@ -164,7 +328,7 @@ export const scanComponents = async (
 
   for await (const entry of glob(patterns, { cwd: rootDir })) {
     const rel = typeof entry === 'string' ? entry : String(entry);
-    if (rel.split('/').some(seg => IGNORED_DIRS.has(seg))) continue;
+    if (isIgnoredPath(rel)) continue;
     const framework = frameworkForExt(extname(rel));
     if (framework === null) continue;
     let code: string;
@@ -175,7 +339,7 @@ export const scanComponents = async (
       continue;
     }
     if (framework === 'react') out.push(...extractReactComponents(rel, code));
-    else out.push(...extractSfcComponent(rel, framework));
+    else out.push(...extractSfcComponent(rel, code, framework));
   }
   return out;
 };

packages/server/src/tokens/repo-css.ts

@@ -0,0 +1,54 @@
+import { glob, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { isIgnoredPath } from '../ignored-dirs.js';
+import { parseCssCustomProperties, type ProjectToken } from './tokens.js';
+
+// The token join's right-hand side when there's no single detected CSS config — i.e. a non-Tailwind
+// project that defines its design tokens as plain CSS custom properties (:root { --primary: … }), or
+// a Tailwind project whose @theme entry wasn't located. Rather than guess *which* CSS file is "the"
+// token source (no reliable marker exists, unlike Tailwind's @import/@theme), aggregate the custom
+// properties from every hand-authored CSS file and let token_map's join filter them: a Figma variable
+// only surfaces a candidate when name- or value-match agrees, so incidental vars (--header-height,
+// reset rules) sit in the pool unmatched and never reach the output. Worst case the pool matches
+// nothing and the result is identical to today's empty join — so the fallback can't regress.
+
+const MAX_CSS_FILES = 200; // safety cap against pathological repos
+
+export interface AggregatedCss {
+  tokens: ProjectToken[];
+  /** Repo-relative CSS files that contributed at least one custom property. */
+  files: string[];
+}
+
+/**
+ * Walk every CSS file in the repo (skipping vendored/build dirs), parse its custom properties, and
+ * pool them. Tokens are kept as-is (no cross-file de-dup): the join prefers an exact value-match,
+ * so a name collision across files resolves to the right-valued token when the Figma side carries a
+ * hex.
+ */
+export const aggregateRepoCssTokens = async (rootDir: string): Promise<AggregatedCss> => {
+  const tokens: ProjectToken[] = [];
+  const files: string[] = [];
+  let scanned = 0;
+
+  for await (const entry of glob('**/*.css', { cwd: rootDir })) {
+    const rel = typeof entry === 'string' ? entry : String(entry);
+    if (isIgnoredPath(rel)) continue;
+    if (scanned >= MAX_CSS_FILES) break;
+    scanned += 1;
+    let body: string;
+    try {
+      // eslint-disable-next-line no-await-in-loop -- sequential repo walk; clarity over batching
+      body = await readFile(join(rootDir, rel), 'utf8');
+    } catch {
+      continue;
+    }
+    const parsed = parseCssCustomProperties(body);
+    if (parsed.length > 0) {
+      tokens.push(...parsed);
+      files.push(rel);
+    }
+  }
+  return { tokens, files };
+};