feat(grounding): get_variable_defs emits hex for COLOR values

A tool-layer eval (3 clean subagents answering grounding questions over a live
design file) surfaced a systematic friction: get_variable_defs returned COLOR
values as 0–1 float RGBA only, while get_design_context's globalVars already
emit hex — so every runner had to hand-convert RGBA and reconcile two color
formats. All three hit it; n=1 had mis-located the fix at get_design_context.

Add a `hex` (#RRGGBB / #RRGGBBAA, alpha only when < 1) alongside the RGBA
channels on COLOR variable values, mirroring globalVars exactly (shared toHex).
Pure addition: RGBA channels stay, so token_map and other consumers are
untouched. Scoped via SerializedRGBASchema.extend so fills/strokes RGBA is not
affected.

Verified live against a real design file's color variables.

Author: awdr74100

packages/plugin/src/handlers/get-variable-defs.ts

@@ -1,4 +1,8 @@
-import type { GetVariableDefsResult, SerializedVariableValue } from '@figma-mcp-relay/shared';
+import {
+  type GetVariableDefsResult,
+  type SerializedVariableValue,
+  toHex,
+} from '@figma-mcp-relay/shared';
 
 import type { SandboxToolHandler } from '../dispatcher.js';
 
@@ -8,7 +12,10 @@ const serializeVariableValue = (value: VariableValue): SerializedVariableValue =
       return { type: 'VARIABLE_ALIAS', id: value.id };
     }
     const color = value as RGB | RGBA;
-    return { r: color.r, g: color.g, b: color.b, a: 'a' in color ? color.a : 1 };
+    const a = 'a' in color ? color.a : 1;
+    // hex mirrors get_design_context's globalVars (#RRGGBB / #RRGGBBAA) so a bound color resolves in
+    // one tool, without hand-converting normalised RGBA. RGBA channels stay for back-compat.
+    return { r: color.r, g: color.g, b: color.b, a, hex: toHex(color, a) };
   }
   return value;
 };

packages/plugin/test/handlers/get-variable-defs.test.ts

@@ -59,13 +59,62 @@ describe('get_variable_defs handler', () => {
       variableIds: ['V:1', 'V:2'],
     });
     expect(result.collections[0]?.modes).toHaveLength(2);
-    // RGB (no alpha) is normalised to a=1
-    expect(result.variables[0]?.valuesByMode.m2).toEqual({ r: 0, g: 0, b: 0, a: 1 });
-    expect(result.variables[0]?.valuesByMode.m1).toEqual({ r: 1, g: 1, b: 1, a: 1 });
+    // RGB (no alpha) is normalised to a=1, with a hex mirror
+    expect(result.variables[0]?.valuesByMode.m2).toEqual({
+      r: 0,
+      g: 0,
+      b: 0,
+      a: 1,
+      hex: '#000000',
+    });
+    expect(result.variables[0]?.valuesByMode.m1).toEqual({
+      r: 1,
+      g: 1,
+      b: 1,
+      a: 1,
+      hex: '#FFFFFF',
+    });
     // alias passthrough
     expect(result.variables[1]?.valuesByMode.m1).toEqual({ type: 'VARIABLE_ALIAS', id: 'V:1' });
   });
 
+  it('adds a hex mirror to COLOR values, 8-digit when alpha < 1', async () => {
+    const handler = createGetVariableDefsHandler(
+      fakeFigma(
+        [],
+        [
+          {
+            id: 'V:4',
+            name: 'color/scrim',
+            key: 'vk4',
+            resolvedType: 'COLOR',
+            variableCollectionId: 'VC:1',
+            valuesByMode: {
+              opaque: { r: 1, g: 1, b: 1, a: 1 },
+              scrim: { r: 1, g: 1, b: 1, a: 0.6 },
+            },
+          },
+        ],
+      ),
+    );
+    const result = (await handler(undefined)) as GetVariableDefsResult;
+    expect(result.variables[0]?.valuesByMode.opaque).toEqual({
+      r: 1,
+      g: 1,
+      b: 1,
+      a: 1,
+      hex: '#FFFFFF',
+    });
+    // alpha < 1 → 8-digit hex (0.6 × 255 = 153 = 0x99), matching globalVars
+    expect(result.variables[0]?.valuesByMode.scrim).toEqual({
+      r: 1,
+      g: 1,
+      b: 1,
+      a: 0.6,
+      hex: '#FFFFFF99',
+    });
+  });
+
   it('passes primitive values through unchanged', async () => {
     const handler = createGetVariableDefsHandler(
       fakeFigma(

packages/shared/src/variables.ts

@@ -9,14 +9,24 @@ export const SerializedVariableAliasSchema = z.object({
 export type SerializedVariableAlias = z.infer<typeof SerializedVariableAliasSchema>;
 
 /**
- * A resolved value for one mode: primitive, color (RGB normalised to RGBA), or an alias to another
- * variable.
+ * A COLOR variable value: RGBA plus a convenience `hex` (#RRGGBB / #RRGGBBAA, alpha only when < 1)
+ * mirroring the hex that get_design_context's globalVars already emits — so an agent reading a
+ * bound variable's color needn't convert normalised RGBA by hand or cross to a second tool. RGBA
+ * stays for back-compat (token_map and other consumers read the channels directly).
+ */
+export const SerializedVariableColorSchema = SerializedRGBASchema.extend({
+  hex: z.string().optional(),
+});
+
+/**
+ * A resolved value for one mode: primitive, color (RGB normalised to RGBA + hex), or an alias to
+ * another variable.
  */
 export const SerializedVariableValueSchema = z.union([
   z.boolean(),
   z.number(),
   z.string(),
-  SerializedRGBASchema,
+  SerializedVariableColorSchema,
   SerializedVariableAliasSchema,
 ]);
 export type SerializedVariableValue = z.infer<typeof SerializedVariableValueSchema>;