Usage Guide

Basic Component Usage

Importing Components

Generated components can be imported like any other React component:

import ProfileCard from "./components/ProfileCard";

Using Components

Components accept props that correspond to the text and image elements in your Figma design:

function App() {
  return (
    <ProfileCard
      name="John Doe"
      description="Software Engineer passionate about building great products."
      Image={<img src="/profile.jpg" alt="Profile" />}
    />
  );
}

Default Props

Components use the useProps hook internally to provide default values. You can override any prop:

// Uses default values
<ProfileCard />

// Overrides specific props
<ProfileCard name="Jane Smith" />

Element Props

The elementProps feature allows you to customize individual elements within a component by targeting their reference IDs.

Understanding Reference IDs

Each element in a generated component has a reference ID that can be used to target it. Reference IDs are semantic identifiers (e.g., "button", "name", "description").

Using Element Props

Pass an elementProps object to customize specific elements:

<ProfileCard
  name="Sarah Martinez"
  description="Creative Director"
  elementProps={{
    // Target by reference ID
    name: {
      className: "hover:text-blue-600 transition-colors",
      onClick: () => alert("Name clicked!"),
    },
    // Change element tag
    description: {
      as: "h3",
      className: "text-lg font-bold",
    },
  }}
/>

Element Props API

Each element in elementProps accepts:

Merging Behavior

• • className: Merged with existing classes
• • style: Merged with existing styles (your styles take precedence)
• • Other props: Replace existing props

Example: Interactive Element

<ProfileCard
  name="Click me!"
  elementProps={{
    name: {
      as: "button",
      onClick: () => console.log("Clicked!"),
      className: "cursor-pointer hover:underline",
      "aria-label": "Profile name",
    },
  }}
/>

Component Variants

Components with variants (created using Figma's variant system) are automatically handled.

Using Variant Components

Variant components accept props that correspond to variant properties:

<VariantComponent
  label="Click Me"
  actionType="Danger" // Variant property
  AnotherDimension="Second" // Another variant property
  hasIcon={true}
/>

Variant Props

• • Props match the variant property names in your Figma component
• • The component automatically renders the correct variant based on prop values
• • If a variant combination doesn't exist, it falls back to the first variant

Example: Button Variants

// Renders the "Danger" + "Second" variant
<VariantComponent
  actionType="Danger"
  AnotherDimension="Second"
  label="Delete"
/>

// Renders the "Normal" + "Second" variant
<VariantComponent
  actionType="Normal"
  AnotherDimension="Second"
  label="Submit"
/>

Variant Interactions

Components with interaction variants (hover, click) automatically handle interactions:

// Hover interactions are automatically handled
<VariantComponent
  actionType="Normal"
  AnotherDimension="Second"
  label="Hover me"
/>

Examples

Example 1: Basic Component

import ProfileCard from "./components/ProfileCard";

function App() {
  return (
    <ProfileCard
      name="Alice Johnson"
      description="Product Designer at Acme Inc."
      Image={
        <img
          src="https://example.com/avatar.jpg"
          alt="Alice"
          className="w-full h-full object-cover"
        />
      }
    />
  );
}

Example 2: Customizing Elements

<ProfileCard
  name="Bob Smith"
  description="Full-stack Developer"
  elementProps={{
    name: {
      as: "h2",
      className: "text-2xl font-bold text-blue-600",
      onClick: () => navigate("/profile"),
    },
    description: {
      className: "text-gray-600 italic",
    },
    box: {
      style: { border: "1px solid #ccc", borderRadius: "8px" },
    },
  }}
/>

Example 3: Variant Component

import VariantComponent from "./components/VariantComponent";

function ButtonExample() {
  return (
    <div>
      <VariantComponent
        label="Delete"
        actionType="Danger"
        AnotherDimension="Second"
        hasIcon={true}
      />
      <VariantComponent
        label="Save"
        actionType="Normal"
        AnotherDimension="First"
        hasIcon={false}
      />
    </div>
  );
}

Example 4: With Event Handlers

<ProfileCard
  name="Charlie Brown"
  description="UX Researcher"
  elementProps={{
    name: {
      onClick: () => {
        console.log("Name clicked");
        // Handle click
      },
      onMouseEnter: () => console.log("Hovered"),
      className: "cursor-pointer hover:underline",
    },
    image: {
      onClick: () => openImageModal(),
      className: "cursor-zoom-in",
    },
  }}
/>

Example 5: Changing Element Types

<ProfileCard
  name="Diana Prince"
  description="Frontend Engineer"
  elementProps={{
    name: {
      as: "a",
      href="/profile/diana",
      className: "text-blue-600 hover:underline",
    },
    description: {
      as: "blockquote",
      className: "border-l-4 border-gray-300 pl-4",
    },
  }}
/>

Best Practices

1. Use Reference IDs: Use semantic reference IDs for more maintainable code
2. Type Safety: Define TypeScript interfaces for your component props
3. Default Values: Always provide sensible defaults in your components
4. Styling: Use Tailwind classes when possible, inline styles for dynamic values
5. Accessibility: Add ARIA attributes via elementProps when changing element types

Additional Resources

• • See component examples in the demo-target/src/components directory
• • Check Storybook stories for interactive examples
• • Review the generated component code to understand the structure