Figma → Code Translation

Translates Figma component selections into correct cf-* Lit HTML using the
documented mappings in *.figma.ts files.

Workflow

1. Get the Figma component

Use the Figma MCP tools to inspect the selected or specified node:

mcp__figma-desktop__get_metadata  → structure, variant props, layer names
mcp__figma-desktop__get_screenshot → visual reference

Extract from the metadata:

• Component name (e.g. "button", "badge", "input")
• Variant properties and their current values (e.g. Style=Primary,
  State=Disabled)
• Child instances and slots
• Layer names that hint at content structure

2. Find matching cf-* component

Search for a .figma.ts mapping file that matches the Figma component:

Glob: packages/ui/src/v2/components/**/*.figma.ts

Read matching files to get the prop mapping. The .figma.ts files export a
figmaMapping object with this structure:

export const figmaMapping = {
  figmaUrl: "https://www.figma.com/design/...",
  element: "cf-button",
  props: {
    // Figma prop name → code mapping
    "FigmaPropName": {
      codeProp: "code-attribute-name",
      values: { "FigmaValue": "code-value", ... },
    },
  },
  unmapped: ["FigmaFeature1", "FigmaFeature2"],
  example: `<cf-button variant="primary">Label</cf-button>`,
};

If no .figma.ts file exists, fall back to searching for a component whose name
matches the Figma component name:

Glob: packages/ui/src/v2/components/cf-{name}/cf-{name}.ts

Read the component source to understand its props, variants, and slots.

3. Translate properties

For each Figma property on the selected node:

1. Look up the Figma prop name in the .figma.ts mapping
2. Map the Figma value to the code value
3. If the prop maps to "slot", it becomes child content
4. If the prop maps to a boolean extracted from an enum (e.g. State=Disabled →
   disabled), render it as a boolean attribute
5. If unmapped, note it in a comment

4. Generate code

Output Lit HTML that a pattern developer can use directly:

<cf-button variant="primary" disabled>Click me</cf-button>

For composite designs (multiple components), generate the full tree:

<cf-vstack gap="md">
  <cf-heading level="2">Title</cf-heading>
  <cf-button variant="primary">Action</cf-button>
</cf-vstack>

5. Report gaps

After generating code, report:

• Mapped: Properties that translated cleanly
• Unmapped: Figma features with no code equivalent (potential enhancement
  opportunities)
• Missing mapping file: If no .figma.ts exists for a component that should
  have one, suggest creating it

When no mapping file exists

If implementing a Figma component that has no .figma.ts file:

1. Read the component source to understand available props
2. Make best-effort mapping based on naming similarity
3. Flag uncertain mappings
4. Suggest creating a .figma.ts file with the discovered mapping

Creating new mapping files

When asked to create a mapping for a component, use this template:

/**
 * Figma ↔ Code mapping for cf-{name}
 *
 * Figma component: "{figma-name}"
 * @see {figma-url}
 */
export const figmaMapping = {
  figmaUrl: "{figma-url}",
  element: "cf-{name}",
  props: {
    // For each Figma property, document the code equivalent
    "FigmaPropName": {
      codeProp: "attribute-name",
      values: {
        "FigmaValue1": "code-value-1",
        "FigmaValue2": "code-value-2",
      },
    },
  },
  unmapped: [
    // Figma features not yet implemented in code
  ],
  example: `<cf-{name} prop="value">Content</cf-{name}>`,
};

Place the file at: packages/ui/src/v2/components/cf-{name}/cf-{name}.figma.ts

Key files

• Mapping files: packages/ui/src/v2/components/**/*.figma.ts
• Component source: packages/ui/src/v2/components/cf-*/cf-*.ts
• Component catalog: packages/patterns/catalog/catalog.tsx
• UI component docs: docs/common/components/COMPONENTS.md