figma-code-connect

${ label } , // ... } Conditional props const variant = instance . getEnum ( 'Variant' , { 'Primary' : 'primary' , 'Secondary' : 'secondary' } ) const disabled = instance . getBoolean ( 'Disabled' ) export default { example : figma . code <Button variant=" ${ variant } " ${ disabled ? 'disabled' : '' }

${ label } , // ... } Step 6: Validate Read back the .figma.ts file and review it against the following: Property coverage — every Figma property from Step 3 should be accounted for in the template. Flag any that are missing and ask the user if they were intentionally omitted. Rules and Pitfalls — check for the common mistakes listed below (string concatenation of template results, missing hasCodeConnect() guards, missing type === 'INSTANCE' checks, etc.) Interpolation wrapping — strings ( getString , getEnum , textContent ) wrapped in quotes, instance/section values ( executeTemplate().example ) wrapped in braces, booleans using conditionals If anything looks uncertain, consult api.md for API details and advanced-patterns.md for complex nesting. Inline Quick Reference instance.* Methods Method Signature Returns getString (propName: string) string getBoolean (propName: string, mapping?: { true: any, false: any }) boolean | any getEnum (propName: string, mapping: { [figmaVal]: codeVal }) any getInstanceSwap (propName: string) InstanceHandle | null getPropertyValue (propName: string) string | boolean findInstance (layerName: string, opts?: SelectorOptions) InstanceHandle | ErrorHandle findText (layerName: string, opts?: SelectorOptions) TextHandle | ErrorHandle findConnectedInstance (codeConnectId: string, opts?: SelectorOptions) InstanceHandle | ErrorHandle findConnectedInstances (selector: (node) => boolean, opts?: SelectorOptions) InstanceHandle[] findLayers (selector: (node) => boolean, opts?: SelectorOptions) (InstanceHandle | TextHandle)[] InstanceHandle Methods Method Returns hasCodeConnect() boolean executeTemplate() { example: ResultSection[], metadata: Metadata } codeConnectId() string | null TextHandle Properties Property Type .textContent string .name string SelectorOptions { path ? : string [ ] , traverseInstances ? : boolean } Export Structure export default { example : figma . code ... , // Required: ResultSection[] id : 'component-name' , // Required: string imports : [ 'import { X } from "..."' ] , // Optional: string[] metadata : { nestable : true , props : { } } // Optional } Rules and Pitfalls Never string-concatenate template results. executeTemplate().example is a ResultSection[] object, not a string. Using + or .join() produces [object Object] . Always interpolate inside tagged templates: figma.code${snippet1}${snippet2}Always check hasCodeConnect() before executeTemplate() . Calling executeTemplate() on an instance without Code Connect returns an error section. Check type === 'INSTANCE' before calling hasCodeConnect() . findInstance() , findConnectedInstance() , and findText() return an ErrorHandle (truthy, but lacking hasCodeConnect() ) on failure — not null . Add a type check to avoid crashes: if (child && child.type === 'INSTANCE' && child.hasCodeConnect()) { ... } Prefer getInstanceSwap() over findInstance() when a component property exists for the slot. findInstance('Star Icon') breaks when the icon is swapped to a different name; getInstanceSwap('Icon') always works regardless of which instance is in the slot. Property names are case-sensitive and must exactly match what get_context_for_code_connect returns. Handle multiple template arrays correctly. When iterating over children, set each result in a separate variable and interpolate them individually — do not use .map().join() : // Wrong: items . map ( n => n . executeTemplate ( ) . example ) . join ( '\n' ) // Correct — use separate variables: const child1 = items [ 0 ] ?. executeTemplate ( ) . example const child2 = items [ 1 ] ?. executeTemplate ( ) . example export default { example : figma . code ${ child1 } ${ child2 } } Complete Worked Example Given URL: https://figma.com/design/abc123/MyFile?node-id=42-100 Step 1: Parse the URL. fileKey = abc123 nodeId = 42-100 → 42:100 Step 2: Call get_code_connect_suggestions with fileKey: "abc123" , nodeId: "42:100" , excludeMappingPrompt: true . Response returns one component with mainComponentNodeId: "42:100" . If the response were empty, stop and inform the user. If multiple components were returned, repeat Steps 3–6 for each. Step 3: Call get_context_for_code_connect with fileKey: "abc123" , nodeId: "42:100" (from Step 2), clientFrameworks: ["react"] , clientLanguages: ["typescript"] . Response includes properties: Label (TEXT) Variant (VARIANT): Primary, Secondary Size (VARIANT): Small, Medium, Large Disabled (BOOLEAN) Has Icon (BOOLEAN) Icon (INSTANCE_SWAP) Step 4: Search codebase → find Button component. Read its source to confirm props: variant , size , disabled , icon , children . Import path: "primitives" . Step 5: Create src/figma/primitives/Button.figma.ts : // url=https://figma.com/design/abc123/MyFile?node-id=42-100 // source=src/components/Button.tsx // component=Button import figma from 'figma' const instance = figma . selectedInstance const label = instance . getString ( 'Label' ) const variant = instance . getEnum ( 'Variant' , { 'Primary' : 'primary' , 'Secondary' : 'secondary' , } ) const size = instance . getEnum ( 'Size' , { 'Small' : 'sm' , 'Medium' : 'md' , 'Large' : 'lg' , } ) const disabled = instance . getBoolean ( 'Disabled' ) const hasIcon = instance . getBoolean ( 'Has Icon' ) const icon = hasIcon ? instance . getInstanceSwap ( 'Icon' ) : null let iconCode if ( icon && icon . hasCodeConnect ( ) ) { iconCode = icon . executeTemplate ( ) . example } export default { example : figma . code <Button variant=" ${ variant } " size=" ${ size } " ${ disabled ? 'disabled' : '' } ${ iconCode ? figma . code icon={ ${ iconCode } } : '' }

${ label } ` , imports : [ 'import { Button } from "primitives"' ] , id : 'button' , metadata : { nestable : true } } Step 6: Read back file to verify syntax. Additional Reference For advanced patterns (multi-level nested components, findConnectedInstances filtering, metadata prop passing between parent/child templates): api.md — Full Code Connect API reference advanced-patterns.md — Advanced nesting, metadata props, and descendant patterns