feat(token_map): font-weight framework-builtin (weight/* → font-bold etc.)

Extend the framework-builtin recognizer to the font-weight named scale.
Projects almost never declare font weights in @theme (you just write
font-bold), yet designs routinely tokenize them — so weight/* otherwise
reads as a false 'unmapped' gap. The step is a font-style name mapped to
Tailwind's font-weight utility (the one rename is Regular → normal; also
absorbs Semi Bold / ExtraLight / Heavy spelling variants). builtin.scale is
'font-weight' → the model emits font-{step}.

Recognizer is now two-kind: open-ended numeric stems (spacing, line-height)
and the fixed font-weight name map. Still fallback-only and conservative —
an unknown weight name (e.g. Condensed) stays unmapped, gated on
profile.styling.system === 'tailwind'.

Live-verified against 客戶 X: weight/Bold→font-bold, weight/Regular→font-normal,
weight/Medium→font-medium; token_map unmapped now 6, all genuine. 531 tests.

Author: awdr74100

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

@@ -27,7 +27,8 @@ export interface TokenMapping {
   /**
    * Set only when status is 'framework-builtin': the Tailwind built-in scale this variable belongs
    * to. There is no project token to reuse — for scale "spacing", compose the step with the bound
-   * property (p-4 / gap-4 / m-4); for "line-height", use leading-{step} (e.g. leading-7).
+   * property (p-4 / gap-4 / m-4); for "line-height", use leading-{step} (leading-7); for
+   * "font-weight", use font-{step} (font-bold).
    */
   builtin?: { scale: string; step: string };
   status: MappingStatus;
@@ -206,8 +207,33 @@ const BUILTIN_NUMERIC_STEMS: ReadonlyMap<string, string> = new Map([
   ['lineheight', 'line-height'],
 ]);
 
-/** Parse a Tailwind step: an integer, a Figma dash-written half-step (1-5 → 1.5), or px. Else null. */
-const parseBuiltinStep = (raw: string): string | null => {
+// Named built-in scale: font-weight. Projects almost never declare it in @theme (you just write
+// font-bold), yet designs routinely tokenize it — so weight/* otherwise reads as a false gap. The step
+// is a font-style name; map it to Tailwind's font-weight utility name (the one rename is Regular →
+// normal). Keys are normalized (lowercased, separators stripped) to absorb "Semi Bold" / "ExtraLight".
+const FONT_WEIGHT_STEPS: ReadonlyMap<string, string> = new Map([
+  ['thin', 'thin'],
+  ['hairline', 'thin'],
+  ['extralight', 'extralight'],
+  ['ultralight', 'extralight'],
+  ['light', 'light'],
+  ['regular', 'normal'],
+  ['normal', 'normal'],
+  ['book', 'normal'],
+  ['medium', 'medium'],
+  ['semibold', 'semibold'],
+  ['demibold', 'semibold'],
+  ['bold', 'bold'],
+  ['extrabold', 'extrabold'],
+  ['ultrabold', 'extrabold'],
+  ['black', 'black'],
+  ['heavy', 'black'],
+]);
+
+const normSeg = (raw: string): string => raw.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** Parse a numeric Tailwind step: an integer, a Figma dash-written half-step (1-5 → 1.5), or px. */
+const parseNumericStep = (raw: string): string | null => {
   const r = raw.trim().toLowerCase();
   if (r === 'px') return 'px';
   // Figma can't put a dot in a name segment, so 1.5 is authored as "1-5" (value confirms: spacing/1-5
@@ -217,26 +243,30 @@ const parseBuiltinStep = (raw: string): string | null => {
 };
 
 /**
- * Recognize a Figma variable as a Tailwind built-in numeric scale step, by name only. Deliberately
- * conservative — it fires only for the stems in the table above (notably NOT size/*, which is a
- * dimension or a font size depending on collection), and only as a fallback after the project-token
- * join declined, so it can never override a real reuse. The Figma group separator is "/", so split
- * on it: the last segment is the step (its own dash is a half-step), the earlier segments are the
- * stem (whose own dashes, e.g. line-height, are part of the name). Returns the scale + step, or
- * null.
+ * Recognize a Figma variable as a Tailwind built-in scale step, by name only. Deliberately
+ * conservative — it fires only for the stems below (notably NOT size/*, a dimension or a font size
+ * depending on collection), and only as a fallback after the project-token join declined, so it can
+ * never override a real reuse. The Figma group separator is "/", so split on it: the last segment
+ * is the step, the earlier segments are the stem (whose own dashes, e.g. line-height, are part of
+ * the name). Numeric scales (spacing, line-height) are open-ended; font-weight is a fixed name map.
+ * Returns the scale + step to compose into a utility (p-4 / leading-7 / font-bold), or null.
  */
 const tailwindBuiltinScale = (figmaName: string): { scale: string; step: string } | null => {
   const segs = figmaName.trim().split('/');
   if (segs.length < 2) return null;
-  const stem = segs
-    .slice(0, -1)
-    .join('')
-    .toLowerCase()
-    .replace(/[^a-z0-9]/g, '');
-  const scale = BUILTIN_NUMERIC_STEMS.get(stem);
-  if (scale === undefined) return null;
-  const step = parseBuiltinStep(segs[segs.length - 1] as string);
-  return step === null ? null : { scale, step };
+  const stem = normSeg(segs.slice(0, -1).join(''));
+  const stepRaw = segs[segs.length - 1] as string;
+
+  const numericScale = BUILTIN_NUMERIC_STEMS.get(stem);
+  if (numericScale !== undefined) {
+    const step = parseNumericStep(stepRaw);
+    return step === null ? null : { scale: numericScale, step };
+  }
+  if (stem === 'weight' || stem === 'fontweight') {
+    const step = FONT_WEIGHT_STEPS.get(normSeg(stepRaw));
+    return step === undefined ? null : { scale: 'font-weight', step };
+  }
+  return null;
 };
 
 const joinOne = (

packages/server/src/prompts/figma-to-code.ts

@@ -24,7 +24,7 @@ const promptText = (nodeId: string | undefined): string => {
    - candidate.unmatchedProps are props the design needs but the component lacks → surface them as component-extension TODOs, never fake them with ad-hoc markup.
    - unmapped: build it new in the project's style. For a repeated unmapped component (instanceCount > 1, e.g. a table row), build from its first instance's subtree; drill instances[0].nodeId if it was scoped away.
 
-3. token_map — every Figma variable joined to a project token. Reference candidate.ref (e.g. bg-primary-500 or var(--color-primary-500)), never the raw hex/px. A 'framework-builtin' status (Tailwind built-in scale, e.g. spacing/4, line-height/7) carries builtin.{scale,step}: for spacing compose the step with the bound property (p-4 / gap-4 / m-4), for line-height use leading-{step} (leading-7) — use the utility, not an arbitrary p-[16px], and don't report it as a gap. Only a genuinely 'unmapped' variable is a gap — use the value but call it out, don't hardcode it silently.
+3. token_map — every Figma variable joined to a project token. Reference candidate.ref (e.g. bg-primary-500 or var(--color-primary-500)), never the raw hex/px. A 'framework-builtin' status (Tailwind built-in scale, e.g. spacing/4, line-height/7, weight/Bold) carries builtin.{scale,step}: for spacing compose the step with the bound property (p-4 / gap-4 / m-4), for line-height use leading-{step} (leading-7), for font-weight use font-{step} (font-bold) — use the utility, not an arbitrary p-[16px], and don't report it as a gap. Only a genuinely 'unmapped' variable is a gap — use the value but call it out, don't hardcode it silently.
 
 4. get_screenshot (or save_screenshots to write straight to disk) — export the assets grounding can't encode. Logos, photos, and icons have no pixels in the layout tree and otherwise render as grey blocks, often half the visible surface. For each visual-only leaf — a node with an IMAGE fill (a photo), a VECTOR / boolean-op, or an icon instance (e.g. mainComponent.name under Icons/…) — export it (SVG for vector/icon, PNG scale 2 for photos) into the project's asset dir and import the real file. Logos and brand marks are always exported, never typed by hand.
 

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

@@ -48,9 +48,10 @@ export const tokenMapTool: ToolSpec = {
     'existing tokens instead of hard-coded values. Joins the grounded Figma variable names + values ' +
     'against tokens parsed from the project CSS (Tailwind v4 @theme or :root custom properties); the ' +
     'match is name-based with an exact color value-match as confirmation. On a Tailwind project a ' +
-    'variable that hits a framework built-in numeric scale (spacing/N, line-height/N) is reported as ' +
+    'variable that hits a framework built-in scale (spacing/N, line-height/N, weight/*) is reported as ' +
     "status 'framework-builtin' with { builtin: { scale, step } } rather than unmapped — it has no " +
-    '@theme token but the utility (p-4 / gap-4, leading-7) is still usable. tokenSource overrides the ' +
+    '@theme token but the utility (p-4 / gap-4, leading-7, font-bold) is still usable. tokenSource ' +
+    'overrides the ' +
     'detected styling config; rootDir defaults to the server cwd. Tailwind v3 JS configs are not yet ' +
     'parsed (pass tokenSource to a CSS file). Returns { mappings (candidate + confidence + status + ' +
     'matchedBy + builtin), unmapped, tokenSource, profile }.',

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

@@ -180,6 +180,36 @@ describe('joinTokens', () => {
       expect(m?.builtin).toEqual({ scale: 'line-height', step: '7' });
     });
 
+    it('maps weight/* to a font-weight built-in, renaming Regular → normal', () => {
+      const bold = joinTokens([fig('weight/Bold', 'Bold', 'STRING')], tokens, {
+        threshold: 0.7,
+        tailwind: true,
+      })[0];
+      expect(bold?.status).toBe('framework-builtin');
+      expect(bold?.builtin).toEqual({ scale: 'font-weight', step: 'bold' });
+
+      const regular = joinTokens([fig('weight/Regular', 'Regular', 'STRING')], tokens, {
+        threshold: 0.7,
+        tailwind: true,
+      })[0];
+      expect(regular?.builtin).toEqual({ scale: 'font-weight', step: 'normal' });
+
+      // Tolerates spacing/casing variants of the style name.
+      const semi = joinTokens([fig('weight/Semi Bold', 'Semi Bold', 'STRING')], tokens, {
+        threshold: 0.7,
+        tailwind: true,
+      })[0];
+      expect(semi?.builtin?.step).toBe('semibold');
+    });
+
+    it('leaves an unknown weight name unmapped (conservative)', () => {
+      const [m] = joinTokens([fig('weight/Condensed', 'Condensed', 'STRING')], tokens, {
+        threshold: 0.7,
+        tailwind: true,
+      });
+      expect(m?.status).toBe('unmapped');
+    });
+
     it('does not fire on a non-Tailwind project (flag off) — stays unmapped', () => {
       const [m] = joinTokens([fig('spacing/4', 16, 'FLOAT')], tokens, { threshold: 0.7 });
       expect(m?.status).toBe('unmapped');

packages/skills/figma-codegen/SKILL.md

@@ -56,12 +56,12 @@ the rendered image.
    - mapped: reference `candidate.ref` (e.g. `bg-primary-500`, `var(--color-primary-500)`) — never the
      raw hex/px that `get_design_context` resolved.
    - `matchedBy: ['name']` on a color (value drifted): use it, but flag the value mismatch to the user.
-   - `framework-builtin` (Tailwind projects): the variable is a built-in numeric scale step the project
-     never redeclares in `@theme` — e.g. `spacing/4`, `line-height/7`. It carries `builtin: { scale,
-step }`: for `spacing`, compose the step with the property `get_design_context` bound it to (`p-4`
-     / `gap-4` / `m-4`); for `line-height`, use `leading-{step}` (e.g. `leading-7`). Use the utility,
-     **not** an arbitrary value like `p-[16px]`. This is **not** a gap — never report it as a missing
-     token.
+   - `framework-builtin` (Tailwind projects): the variable is a built-in scale step the project never
+     redeclares in `@theme` — e.g. `spacing/4`, `line-height/7`, `weight/Bold`. It carries `builtin: {
+scale, step }`: for `spacing`, compose the step with the property `get_design_context` bound it to
+     (`p-4` / `gap-4` / `m-4`); for `line-height`, use `leading-{step}` (`leading-7`); for `font-weight`,
+     use `font-{step}` (`font-bold`). Use the utility, **not** an arbitrary value like `p-[16px]`. This
+     is **not** a gap — never report it as a missing token.
    - in `unmapped`: the design uses a token the project hasn't defined. Don't hardcode silently — use the
      value but call out the gap (and offer to add it, or hand off to **figma-sync-tokens**).
 4. **`get_screenshot` — export the assets the structural tools can't carry.** Geometry + text grounding