Beam logoBeam

CLI Command

beam mappings

Connect known Figma components to local code imports for better agent handoff.

Mappings help Beam explain that a Figma component already has a local code equivalent. This improves implementation guidance without turning Beam into a code generator.

Mappings are project-local and should contain no secrets. They can be committed when they only reference component names, Figma IDs, import paths, and package-safe metadata.

beam mappings add records a relationship. beam mappings list shows the current registry. beam mappings remove deletes a stale or incorrect relationship.

Core output remains framework-agnostic. A mapping can point to React, Vue, Svelte, or another local component style without Beam hardcoding framework behavior.

bash
1beam mappings add --figma-component-id 123:456 --figma-name "Button / Primary" --import "@/components/button" --export Button2beam mappings list3beam mappings remove 123:456

Run Sequence

  1. Identify the Figma component id and its readable component name.
  2. Identify the local component import path and exported symbol.
  3. Run beam mappings add with those values.
  4. Run beam mappings list and confirm the mapping appears before asking an agent to build.

Expected Output

Beam should confirm the mapping was saved and list the Figma component id, Figma name, import path, export name, and project-local mapping file.

Files And Artifacts

  1. .beam/mappings.json

Next Step

Run beam inspect <figma-url> so the brief can mention known local components.

Recovery Paths

  1. If the import path changes, remove the old mapping and add the new one.
  2. If an agent uses the wrong component, verify the Figma component id matches the design instance.
  3. If mappings should not be shared, keep .beam/mappings.json out of commits.