Code Connect & Storybook

#What is Code Connect

Code Connect links Figma components to source code files in your repository. When a developer selects a component in Dev Mode, they see not only generated code but also a link to the actual file in the repo — import path, framework, documentation.

#Why it matters

• Developers instantly navigate to the right file in the repository
• See the import path for the component
• Understand which framework is used
• Can open documentation or Storybook

#How to set up

#1. Configure Repository connection

Open the Code tab in the plugin sidebar, click Repository connection at the bottom.

This is a one-time setup saved for all components in the file.

#2. Connect a component

1. Select a component (COMPONENT or COMPONENT_SET) in Figma
2. Go to the Code tab
3. Fill in the Code Connect section:

4. Click Connect to save

After connecting:

• Component appears in the sidebar with a Code Connect icon
• Dev Resources are created in Figma
• A Disconnect button appears; if fields are changed, a Reconnect button is also shown

#3. Add implementation files

Click Add file to attach source code files:

#Storybook Integration

Code Connect includes built-in Storybook Integration via @sxl-studio/storybook-addon. This addon displays Figma design context directly in Storybook.

For addon details (architecture, API, publishing), see Storybook Addon in the Utilities section.

Starting with addon 1.1.0, the preset configures CSP for the Figma embed, serves local composition files under /sxl-tokens/… when a token export folder is present, and does not require one fixed repository layout — see the Preset section in Storybook Addon.

#What Storybook shows

#Step 1. Install the addon

npm i -D @sxl-studio/storybook-addon

#Step 2. Register in Storybook

Add @sxl-studio/storybook-addon to the addons array in .storybook/main.ts. Minimal example:

export default {
  addons: [
    "@storybook/addon-docs",
    "@sxl-studio/storybook-addon",
  ],
};

If main is imported from a shared package (design system), append the addon: addons: [...(sharedMain.addons ?? []), "@sxl-studio/storybook-addon"] — do not replace the whole list. Details: Storybook Addon — registration.

#Step 3. Configure Storybook Integration in the plugin

After connecting a component via Code Connect, expand the Storybook Integration section. It has its own Connect/Disconnect/Reconnect buttons, independent from Code Connect:

• Design Embed — includes the Figma Embed (centered iframe with Dev Mode link)
• Composition JSON — generates composition JSON for Storybook
• Metadata — sends component description to Storybook
• Tokens — toggle True/False, shows in Storybook whether tokens are ready
• Status — dropdown: Complete, Ready for Dev, In Progress, Backlog

Click Connect to save Storybook settings. Settings are saved automatically into the codeConnect registry file — no separate export step is needed.

#Step 4. Import registry in Storybook

The plugin writes settings into diff-code-connect.<fileKey>.json. Load it into parameters.sxl.registry in .storybook/preview.ts. The import path is up to your repo (e.g. a tokens/tokens folder next to the app).

With the converter:

import raw from "../diff-code-connect.abc123.json";
import { fromDiffCodeConnect } from "@sxl-studio/storybook-addon";

export default {
  parameters: {
    sxl: { registry: fromDiffCodeConnect(raw) },
  },
};

A direct JSON import is often enough. If you use a shared preview, merge parameters: { ...sharedPreview, parameters: { ...sharedPreview.parameters, sxl: { registry } } }. Full options: Storybook Addon — registry in preview.

Replace abc123 with your actual Figma file key.

#Step 5. Done

The addon automatically matches each story to a registry entry by comparing displayName and the story title. No story file edits required.

For stories without Figma integration, the panel shows "No Figma integration for this component".

#Alternative: Direct parameters (no registry)

For quick prototypes or a small number of stories:

export const Default = {
  parameters: {
    sxl: {
      figmaUrl: "https://www.figma.com/design/ABC123?node-id=1-2",
      description: "Primary action button",
      tokenStatus: "assigned",
      readiness: "ready-for-dev",
    },
  },
};

#Parameters reference

Storybook matching: the addon does not apply a lone registry entry to every story; matching uses story context or explicit sxl.* parameters.

#Binding storage

#On the node (Plugin Data)

The primary binding is stored in the component's Plugin Data (key codeConnect). For instances, the binding is looked up on the main component or Component Set.

Dev Mode limitation: Plugin Data cannot be written in Figma Dev Mode. If you configure Code Connect in Dev Mode, the binding is saved to a diff file. For full persistence, open the file in Design Mode.

#Registry file

Bindings (including Storybook settings) are saved to diff-code-connect.<fileKey>.json. This file serves as:

• Change tracking and team sharing
• The source of truth for @sxl-studio/storybook-addon
• Git-friendly JSON you can commit to your repository

#Display in Dev Mode

#Built-in Codegen

A Code Connect tab appears alongside Variables and References tabs. It shows:

• Import & Usage — import path and code snippet
• Files — repository file links with framework labels
• Source URL — direct link to the code

#Side Tree indicators

In the Code tab sidebar, linked components show status icons:

• Code Connect icon (blue) — component is connected to a repository
• Storybook icon (pink) — Storybook integration is enabled (at least one toggle active)

#Troubleshooting

#SXL Studio panel missing in Storybook

• Ensure @sxl-studio/storybook-addon is in .storybook/main.ts addons
• Restart Storybook after install

#Panel says "No SXL data for this story"

• parameters.sxl is missing on the story
• Or sxl.registry is not loaded in preview.ts
• Or component/figmaNodeId does not match registry entries

#Embed is not visible

• Ensure valid direct Figma URL (figma.com/design/...)
• In the plugin, verify Design Embed toggle is enabled for this component

#Recommended production flow

1. Designer opens Code tab, configures Repository connection (one-time setup)
2. Selects a component, fills in Code Connect (import path, files), clicks Connect
3. Expands Storybook Integration, enables desired options, sets Tokens / Status, clicks Connect
4. Commits diff-code-connect.<fileKey>.json to Git
5. Developer adds @sxl-studio/storybook-addon to Storybook
6. Imports registry in preview.ts (one-time setup)
7. Addon automatically matches stories to components — no story file edits needed
8. CI runs Storybook with the up-to-date registry

#Related sections

• Storybook Addon — addon details, architecture, API
• Dev Mode Overview — general structure
• Code Generation — all platforms
• Git — Integration — repository connection