> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import a Figma Design

> Turn Figma frames into real pages and components in your Hiveku project

If you already have a design in Figma, Hiveku can turn it into real project code. Each Figma frame becomes a React component styled with Tailwind, plus a routed page you can open in the live preview, refine with the AI, and deploy.

## Connect Figma First

Every import needs a connected Figma account (or token). You have two options:

<Tabs>
  <Tab title="Personal access token (recommended)">
    <Steps>
      <Step title="Create a token in Figma">
        In Figma, click your avatar → **Settings** → **Security** tab → **Personal access tokens** → **Generate new token**. Give it a name (e.g. "Hiveku"), pick an expiration, and set **File content** to **Read-only** — we recommend also setting **Current user** to Read-only so Hiveku can display which Figma account is connected. Copy the token immediately — Figma shows it only once.
      </Step>

      <Step title="Paste it in Hiveku">
        In the editor, click the **Figma** button in the chat toolbar (or open your project's **Settings** page → **Figma** panel) and paste the token into the input. Hiveku validates it against Figma before saving, and stores it encrypted.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Connect with Figma (sign-in)">
    In the same Figma dialog or settings panel, click **Connect Figma** to authorize read-only access via your Figma account — the dialog then shows **Connected via Figma OAuth** with your account name.

    <Warning>
      One-click Figma sign-in is awaiting Figma's approval of the Hiveku app and may show an error until that completes. If it does, use a personal access token instead — same result, works today.
    </Warning>

    Hiveku only requests read scopes — it can never modify your Figma files.
  </Tab>
</Tabs>

<Info>
  Once connected, you can import any file your Figma account can open — your own files, files shared with you, and public "anyone with the link" files.
</Info>

## Import from the Editor

<Steps>
  <Step title="Copy the Figma link">
    In Figma, click **Share → Copy link** on the file — or right-click a specific frame and **Copy link to selection** to import just that frame. Both `figma.com/design/...` and `figma.com/file/...` links work, with or without a `node-id`.
  </Step>

  <Step title="Paste and preview">
    Click the **Figma** button in the editor, paste the URL, and hit **Preview Import**. Hiveku fetches the file's structure and shows the file name, pages, frame count, and image count before anything is written.
  </Step>

  <Step title="Choose how to organize the output">
    | Mode                             | What you get                                                     | Where                                                                                        |
    | -------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
    | **Page per Frame** (recommended) | A component and a routed page for each frame                     | `components/figma/Home.tsx` + `app/(site)/figma-import/home/page.tsx` → `/figma-import/home` |
    | **Single Page**                  | One routed page stacking every frame as a section                | `app/(site)/figma-import/page.tsx` → `/figma-import`                                         |
    | **Components Only**              | Components with no routes — compose them yourself or with the AI | `components/figma/*.tsx`                                                                     |

    The **Base Path** field controls the URL prefix (default `figma-import`), so imports never overwrite your existing pages.
  </Step>

  <Step title="Import">
    Click **Import with Configuration**. Progress is shown per stage (fetching frames, exporting images, generating components, saving). Big designs with many images can take about a minute.
  </Step>

  <Step title="Review the results">
    The results screen walks you through what happened: the route your design is now live at, the files it created (click any to open it in the editor), where the images went, and a one-click **Ask AI to finish this page** button. Any warnings (for example an image that failed to export) are listed at the bottom.
  </Step>
</Steps>

## After the Import — Where Everything Is

Nothing is hidden: the import writes normal project files you can see, edit, and deploy.

| What                           | Where                                                       | What it's for                                                                             |
| ------------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Your design as a page**      | `app/(site)/figma-import/<frame-name>/page.tsx`             | The routed page — visit `/figma-import/<frame-name>` in the preview                       |
| **Your design as a component** | `components/figma/<FrameName>.tsx`                          | The design itself, reusable on any page (drop it into your homepage, a section, anywhere) |
| **Images from the design**     | Your project's CDN, listed in the editor's **Assets** panel | Exported from Figma at 2x, already linked in the generated code                           |

**To see it**: open the preview panel (or the results screen's Open link) and add the route to your preview URL — e.g. `.../figma-import/home`. It's live there immediately; deploy when you want it public.

**To find the files later**: they're in the editor's file tree under `components/figma/` and `app/(site)/figma-import/`, and in version history like any other file.

## Tell the AI What to Do With It

The AI already knows about the imported files — just describe the outcome you want:

```
Make the imported Figma page responsive on mobile
```

```
Use the imported design as my homepage
```

```
Swap the imported colors for our brand palette and use our fonts
```

```
Turn the hero section of the imported design into a reusable component and put it on every page
```

The results screen's **Ask AI to finish this page** button sends the first of these for you, pre-filled with the exact file paths.

<Info>
  The import is deliberately literal — it reproduces the design exactly as drawn, including fixed pixel positions on freeform frames. Making it responsive and on-brand is the AI's job, and it's usually one or two requests.
</Info>

## Import from the AI Chat

Paste a Figma link straight into the AI chat with an instruction:

```
Import this Figma design and make it my landing page:
https://www.figma.com/design/AbC123xyz/Homepage?node-id=1-2
```

The AI parses the link, runs the import, and then — this is the part the editor button doesn't do — refines the result: swaps hard-coded colors for your design tokens, makes rigid layouts responsive, and can wire the new pages into your navigation. Follow up naturally:

```
Make the imported page responsive and match our brand fonts
```

If Figma isn't connected yet, the AI will tell you exactly where to connect.

## What Gets Imported

* **One React component per frame** — layout hierarchy preserved, named after your frame (`Hero Section` → `HeroSection.tsx`)
* **Styling as Tailwind classes** with exact values: colors, spacing, typography, borders, shadows, gradients
* **Layout** — Figma auto-layout becomes flexbox; freeform frames keep exact pixel positioning
* **Images** — every image fill is exported from Figma at 2x and uploaded to your project's CDN automatically
* **Text** — real copy from the design, with heading levels inferred from type sizes

## Limits and Behavior

* **20 frames per import** — larger files import the first 20 and list what was skipped; run additional imports for the rest
* **Hidden frames and layers are skipped** (with a note in the warnings)
* **Very large frames** (unusually heavy design data) are skipped with a warning rather than failing the whole import
* **Re-importing** the same frame creates new versions of the same files — your version history keeps the old ones

## Tips for Better Imports

<Steps>
  <Step title="Use auto-layout everywhere">
    Auto-layout frames convert to clean flexbox that adapts to different screens. Freeform frames import pixel-perfect but rigid — ask the AI to make them responsive afterwards.
  </Step>

  <Step title="Name your frames and layers">
    Frame names become component names and page routes. `Pricing` imports as `Pricing.tsx` at `/figma-import/pricing`; `Frame 427` imports as... `Frame427`.
  </Step>

  <Step title="Import a specific frame with node-id">
    Right-click a frame in Figma and **Copy link to selection** — the link carries a `node-id` and Hiveku imports only that frame.
  </Step>

  <Step title="Refine with the AI afterwards">
    The import is a high-fidelity starting point, not a finished site. One or two AI requests ("make it responsive", "use our brand colors") close the gap fast.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Figma is not connected' or 'connection expired'">
    Open the Figma dialog (editor **Figma** button) or the **Figma** panel in project settings — it shows your live connection status. Paste a fresh personal access token, or click **Connect Figma** (or **Reconnect**). OAuth connections refresh themselves automatically; you'll only see this if access was revoked on the Figma side.
  </Accordion>

  <Accordion title="'OAuth app doesn't exist' when clicking Connect Figma">
    Figma is still reviewing the Hiveku app for one-click sign-in, and until approval only the Hiveku team can use it. Paste a personal access token instead (Figma → Settings → Security → Personal access tokens) — imports work identically.
  </Accordion>

  <Accordion title="'Invalid Figma personal access token'">
    The token is checked against Figma the moment you paste it. Generate a new one in Figma under **Settings → Security → Personal access tokens** (with file read access) and paste again.
  </Accordion>

  <Accordion title="Import fails on a private file">
    The connected Figma account (or token) must be able to open that file in Figma. Either connect the account that owns the file, or share the file with the connected account, or set the file to "anyone with the link can view".
  </Accordion>

  <Accordion title="Some images are missing">
    Image fills export automatically, but if Figma fails to render one, the import completes and lists the affected images in the warnings. Re-run the import, or ask the AI to generate a replacement image.
  </Accordion>

  <Accordion title="'No importable frames found'">
    The linked file (or the specific frame in your link) has nothing visible to import — check that the frame isn't hidden and the link points where you think it does.
  </Accordion>

  <Accordion title="The layout looks right but breaks on mobile">
    Expected for freeform (non-auto-layout) designs, which import with fixed pixel positioning. Ask the AI: *"Make the imported figma pages responsive."*
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Figma Integration" icon="figma" href="/integrations/figma">
    Full reference for the Figma integration
  </Card>

  <Card title="Edit Visually" icon="pencil" href="/how-tos/edit-visually">
    Refine imported designs
  </Card>
</CardGroup>