Maintain Figma Object Embeds Using Embed Kit

Maintain Components that Embed Figma Objects using Embed Kit

ℹ️

⚡ Quick Start: Use this syntax in your markdown files:

markdown

:figma-embed{src="YOUR_FIGMA_URL" width="800" height="600"}

Note the single colon (:) - this is the working syntax.

Overview

This guide explains how to embed Figma objects in custom components using the Figma Embed Kit. The Figma Embed Kit allows you to display Figma files, frames, and prototypes directly in your application, offering an interactive experience.

Example

Option 1: Text Directive - CURRENTLY WORKING ✅

markdown

:figma-embed{src="https://www.figma.com/design/splN6L6DgSf61khdyfpybl/Go-Lossless?node-id=2459-9610" auth-user="mpstaton" width="800" height="600"}

Option 2: Leaf Directive (Single-line)

markdown

::figma-embed{src="https://www.figma.com/design/splN6L6DgSf61khdyfpybl/Go-Lossless?node-id=2459-9610" auth-user="mpstaton" width="800" height="600"}

Option 3: Container Directive (Multi-line)

markdown

:::figma-embed
src="https://www.figma.com/design/splN6L6DgSf61khdyfpybl/Go-Lossless?node-id=2459-9610"
auth-user="mpstaton"
width="800"
height="600"
:::

Figma API

Base URL:: https://api.figma.com

Getting a Figma API Key

To embed Figma content, construct your URL with the following base format:

zsh

$ curl -sH 'X-Figma-Token: 29-206...'
    'https://api.figma.com/v1/files/...'
    | python -m json.tool
{
  "components": {},
  "document": {
    "children": [
      {
        "backgroundColor": {
          "a": 1,
          "b": 0.8980392156862745,
          "g": 0.8980392156862745,
          "r": 0.8980392156862745
        },
        "children": [],
        "exportSettings": [],
        "id": "0:1",
        "name": "Page 1",
        "type": "CANVAS",
      }
    ],
    "id": "0:0",
    "name": "Document",
    "type": "DOCUMENT",
  },
  "schemaVersion": 0
}

Embed URL Format

text

https://www.figma.com/embed?embed_host={host}&url={figma-url}

Required Parameters

embed_host: Specifies the host application. Use your domain or app name to identify the host.
url: The URL of the Figma file, frame, or node you want to embed.

Optional Query Parameters

initial_view: Determines the initial view ('design' or 'prototype')
pageId: ID of the page to display
nodeId: ID of the specific node to display
hide_ui: Hides Figma UI elements (true/false)
hotspot-hints: Shows prototype hotspot hints (0 or 1)
scaling: Controls how content is scaled ('min-zoom', 'contain', or 'fill')
allow-fullscreen: Allows fullscreen mode (true/false)
chrome: Controls UI chrome visibility ('DOCUMENTATION' hides most UI)

Implementing in Custom Components

Create a Figma Embed Component
Develop a component in Astro that receives the Figma URL and optional parameters:
astro
```
---
```

// Component script export let figmaUrl: string; export let embedHost: string = 'your-domain.com'; export let initialView?: string; export let pageId?: string; export let nodeId?: string; export let hideUi?: boolean;

```

Primary Usage: Remark Directive in Markdown

Our primary intention is to use this component through remark-directives in Markdown files. This allows for seamless embedding without importing components.

✅ WORKING SYNTAX (Use this):

markdown

:figma-embed{src="https://www.figma.com/file/bm4kr9lQAVhvllVk7hsDuD/Parslee?node-id=3212-21097" initial-view="design" hide-ui="true" width="800" height="600"}

Alternative syntax (container directive - may need testing):

markdown

:::figma-embed
src="https://www.figma.com/file/bm4kr9lQAVhvllVk7hsDuD/Parslee?node-id=3212-21097"
initial-view="design"
hide-ui="true"
width="800"
height="600"
:::

Direct Raw HTML Iframe (for testing only)
Avoid using backticks or extra quotes around the src URL. Use the official Figma embed endpoint (https://www.figma.com/embed) and pass your file/design URL via the url parameter.
html
```
<iframe
  style="border: 1px solid rgba(0, 0, 0, 0.1);"
  width="800"
  height="450"
  src="https://www.figma.com/embed?embed_host=lossless.group&url=https%3A%2F%2Fwww.figma.com%2Fdesign%2Fbm4kr9lQAVhvllVk7hsDuD%2FParslee%3Fnode-id%3D3212-21097"
  allowfullscreen>
</iframe>
```
Notes:
- Do not use `...` around URLs; those backticks break embeds and routing.
- Prefer https://www.figma.com/embed?url=... over https://embed.figma.com/design/... to match our pipeline and avoid CORS or parsing issues.
Simple usage with minimal parameters:
markdown
```
:figma-embed{src="https://www.figma.com/file/abc123/Your-Figma-File"}
```

Alternative Usage: Direct Component Import

You can also use the component directly in Astro files:

astro

---
import FigmaEmbed from '../components/FigmaEmbed.astro';
---

<FigmaEmbed
  figmaUrl="https://www.figma.com/file/abc123/Your-Figma-File"
  initialView="design"
  hideUi={true}
/>

Usage in MDX Files

For MDX files, you can either use the remark directive (preferred) or import the component:

Preferred: Using remark directive

mdx

# My Document

Here's an embedded Figma file:

:figma-embed{src="https://www.figma.com/file/abc123/Your-Figma-File" initial-view="prototype"}

Alternative: Direct import

mdx

---
import FigmaEmbed from '../components/FigmaEmbed.astro';
---

# My Document

<FigmaEmbed figmaUrl="https://www.figma.com/file/abc123/Your-Figma-File" />

Security Considerations

Ensure the Figma URL is sanitized to prevent injection attacks.
Restrict embedding to trusted domains if applicable.

Testing and Validation

Verify embed functionality in various browsers and devices.
Test optional parameters to ensure proper handling and fallback.

Live Example

Here's a live example using the Go-Lossless Figma design:

This example demonstrates:

Specific node targeting using node-id=2459-9610
Custom dimensions with width and height parameters
Initial view set to design mode
Clean embed URL that will render the Go-Lossless design

Implementation Findings

Directive Syntax Resolution

During implementation, we discovered that remark-directive supports three distinct syntax formats:

Text Directives (Single-colon - CURRENTLY WORKING):
markdown
```
:figma-embed{src="..." width="800" height="600"}
```
- Uses single colon :
- Attributes parsed directly from node.attributes
- Most reliable for inline embeds
Leaf Directives (Double-colon):
markdown
```
::figma-embed{src="..." width="800" height="600"}
```
- Uses double colon ::
- Self-closing directive style
- Currently functional
Container Directives (Triple-colon):
markdown
```
:::figma-embed
src="..."
width="800"
height="600"
:::
```
- Uses triple colon :::
- Multi-line block style
- Parser may need debugging for attribute extraction

AstroMarkdown Integration

The implementation required updating AstroMarkdown.astro to handle all three directive node types:

Text directives (textDirective) - Line 1339-1487: Attributes directly available in node.attributes, renders block-level embed
Leaf directives (leafDirective) - Line 1511+: Attributes in node.attributes, single-line syntax
Container directives (containerDirective) - Line 1511+: Require parsing child nodes to extract key-value pairs from text content

All three formats render the same full-featured Figma embed with modal expansion and accessibility features.

Enhanced Features Implemented

Breakout Layout: Full-width container that breaks out of normal content padding, similar to Mermaid charts
Modal Expansion: Click-to-expand functionality for fullscreen viewing with proper focus management
Node-Specific Embedding: Proper URL construction to focus on specific Figma nodes using node-id parameters
Accessibility: ARIA labels, keyboard navigation, and focus trapping in modal view

URL Construction

The final embed URL format includes:

text

https://www.figma.com/embed?embed_host=lossless.group&url=ENCODED_URL&node-id=NODE_ID&viewer=1&scaling=min-zoom

This ensures proper node focusing and optimal viewing experience.

Future Work

Consider extending the component to handle additional parameters or support themes and other customization.