Components & Variants

Figma components are the design equivalent of React components or web components in code. They are reusable UI elements defined once and instantiated throughout the design. When the main component updates, every instance updates automatically. Understanding how Figma components work helps you translate designs into well-structured code.

Main Components vs Instances

• Main component — The source of truth. It defines the structure, styling, and default properties. Identified by a purple diamond icon in the layers panel.
• Instance — A copy of the main component used throughout designs. Identified by a hollow diamond icon. Instances can override certain properties (text, colors, visibility) without breaking the link to the main component.

This mirrors the relationship between a React component definition and its usage:

// This is like the "main component" in Figma
function Badge({ label, variant = 'default' }) {
  const colors = {
    default: 'bg-gray-100 text-gray-700',
    success: 'bg-green-100 text-green-700',
    error: 'bg-red-100 text-red-700',
  };

  return (
    <span className={`px-2 py-1 rounded-full text-xs font-medium ${colors[variant]}`}>
      {label}
    </span>
  );
}

// These are like "instances" in Figma — same component, different props
<Badge label="Active" variant="success" />
<Badge label="Expired" variant="error" />
<Badge label="Draft" />

Variant Properties

Variants let a single component represent multiple states and variations. Instead of creating separate components for "Primary Button," "Secondary Button," "Small Button," and "Disabled Button," designers create one Button component with variant properties:

• Variant — primary, secondary, ghost
• Size — sm, md, lg
• State — default, hover, disabled
• Icon — leading, trailing, none

In Figma, these appear as toggles and dropdowns in the properties panel when an instance is selected. For developers, each variant property maps directly to a component prop:

interface ButtonProps {
  variant: 'primary' | 'secondary' | 'ghost';
  size: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  iconPosition?: 'leading' | 'trailing' | 'none';
  children: React.ReactNode;
}

Boolean Properties

Figma boolean properties toggle the visibility of layers within a component. A card component might have a boolean "Show Image" property — when true, the image is visible; when false, it is hidden.

In code, this maps to conditional rendering:

function Card({ title, description, image, showImage = true }) {
  return (
    <div className="rounded-lg border overflow-hidden">
      {showImage && image && (
        <img src={image} alt="" className="w-full h-48 object-cover" />
      )}
      <div className="p-4">
        <h3 className="font-semibold text-lg">{title}</h3>
        <p className="text-gray-600 mt-1">{description}</p>
      </div>
    </div>
  );
}

Instance Swap Properties

Instance swap properties let designers replace a nested component within an instance. For example, a navigation item component might have an "Icon" instance swap property that accepts any icon component.

In React, this is equivalent to passing a component as a prop:

function NavItem({ icon: Icon, label, href }) {
  return (
    <a href={href} className="flex items-center gap-2 px-3 py-2 rounded hover:bg-gray-100">
      <Icon className="w-5 h-5" />
      <span>{label}</span>
    </a>
  );
}

// Usage — swapping the icon is like changing the instance swap in Figma
<NavItem icon={HomeIcon} label="Home" href="/" />
<NavItem icon={SettingsIcon} label="Settings" href="/settings" />

Component Organization

Well-organized Figma component libraries follow naming conventions that mirror code structure:

Components/
├── Actions/
│   ├── Button (variants: primary, secondary, ghost × sm, md, lg)
│   ├── IconButton (variants: sm, md, lg)
│   └── Link (variants: default, subtle)
├── Forms/
│   ├── Input (variants: default, error, disabled)
│   ├── Select (variants: default, error, disabled)
│   └── Checkbox (variants: checked, unchecked, indeterminate)
├── Feedback/
│   ├── Alert (variants: info, success, warning, error)
│   ├── Toast (variants: info, success, warning, error)
│   └── Badge (variants: default, success, error, warning)
└── Layout/
    ├── Card (booleans: showImage, showFooter)
    └── Divider (variants: horizontal, vertical)

This organization helps developers know exactly which code component corresponds to which Figma component.

Reading Component Specs

When inspecting a component instance in Figma, check:

1. Which component is it? — The component name appears at the top of the properties panel.
2. What are the current variant values? — These map to your props.
3. What text was overridden? — These are your content props (labels, titles, descriptions).
4. What layers are hidden? — These tell you which boolean props are false.
5. What instances were swapped? — These tell you which sub-components to render.

Understanding this mapping means you can look at any design and immediately know which component to use, which props to set, and what content to pass.

Detaching Instances

Sometimes designers "detach" an instance from its main component to make one-off modifications. When you see a detached instance during handoff, flag it — it might be:

• A legitimate one-off that does not need to be a shared component
• A sign that the component library is missing a needed variant
• An accidental detach that should be reconnected

Detached instances do not get updates from the main component, which can lead to inconsistency over time.