@quartzds/figma-code-connect-generator

CLI tool to generate Figma Code Connect mapping files from Stencil docs.json metadata. It reads component and prop documentation tags and produces React and HTML mappings for Figma.

💿 Installation

Add this package to your dev dependencies:

npm install -D @quartzds/figma-code-connect-generator

📦 Usage

1. Annotate your Stencil components with the tags described below, to map your Stencil components to their Figma counterparts.
2. Build your library to let Stencil generate the docs.json file
3. Use this CLI to generate the Figma Code Connect mapping files
4. use Figma Code Connect CLI to deploy the generated mappings to the Figma servers

CLI options

• <docs-json>: path to Stencil docs.json file (required)
• -h, --html-out-dir [dir]: output directory for HTML mappings (default: ./generated/figma-code-connect/html)
• -r, --react-out-dir [dir]: output directory for React mappings (default: ./generated/figma-code-connect/react)
• -v, --verbose: enable verbose logging output
• -V, --version: display version
• --help: display help

🛠️ Setup guide

1. Configure Stencil to generate the docs.json metadata

In your stencil.config.json:

import type { Config } from '@stencil/core'

export const config: Config = {
  outputTargets: [
    {
      type: 'docs-json',
      file: './docs.json',
    },
  ],
}

2. Configure Code Connect for each target platform

Manually create the folders where mappings will be generated, then add a Figma Code Connect configuration file in each:

React

In generated/figma-code-connect/react/figma.config.json:

{
  "codeConnect": {
    "include": ["*.figma.js"],
    "label": "Angular / HTML / Vue",
    "language": "html",
    "parser": "react"
  }
}

HTML

In generated/figma-code-connect/html/figma.config.json:

{
  "codeConnect": {
    "include": ["*.figma.js"],
    "label": "Angular / HTML / Vue",
    "parser": "react"
  }
}

3. Add generation to your build pipeline

Add a script to your package.json file that will execute after building your components with Stencil:

{
  "scripts": {
    "build:figma-mappings": "figma-code-connect-generator ./dist/docs.json"
  }
}

Note: it's recommended to commit the generated files to version control. You will be able to check the output before deploying to Figma, and it will ease reviewing future updates to those mappings.

4. Deploy mappings when releasing

When releasing your library in CI, use Figma Code Connect CLI to deploy the mappings to Figma servers:

npx @figma/code-connect connect publish --dir ./generated/figma-code-connect/react
npx @figma/code-connect connect publish --dir ./generated/figma-code-connect/html

Alternatively, you can add @figma/code-connect to your devDependencies and run it from a script in your package.json:

{
  "scripts": {
    "release:code-connect-html": "figma connect publish --dir ./generated/figma-code-connect/html",
    "release:code-connect-react": "figma connect publish --dir ./generated/figma-code-connect/react"
  },
  "devDependencies": {
    "@figma/code-connect": "^1.4.1"
  }
}

📖 Annotations reference

Component-level annotations

• @figmaComponentUrl: URL to the Figma master component.
• @figmaSlotProperty: name of the Figma property that provides content for the default slot.

Property-level annotations

By default, Figma properties are assumed to have same name (hyphen-cased) as the Stencil property (camlCase).

Common case

@figmaProperty maps a simple property (boolean, enum, number, string). If the Figma property name is different, provide it in the tag value.

Icon properties

@figmaIconProperty maps an icon property (Figma instance Swap). If the Figma property name is different, provide it in the tag value.

Nested Figma components

When a property is provided by a nested component in Figma, use the following annotations:

• @figmaNestedComponent: name of the nested component layer in Figma.
• @figmaNestedComponentProperty: name of the Figma property to read from that nested component.

Example

/**
 * The URL to the master component node in Figma
 * @figmaComponentUrl https://www.figma.com/design/...?node-id=00000-00000
 *
 * The Figma property name that provides content for the default slot
 * @figmaSlotProperty title
 */
@Component({
  tag: 'qds-my-component',
})
export class MyComponent implements ComponentInterface {
  /**
   * A simple property with the same name in Figma
   * @figmaProperty
   */
  @Prop() public readonly someProp?: string = 'start'

  /**
   * An icon property (e.g., instance swap), with a different name in Figma
   * @figmaIconProperty action-icon
   */
  @Prop() public readonly action?: string

  /**
   * The name of the nested component layer in Figma
   * @figmaNestedComponent qds-badge-counter
   *
   * The name of the Figma property to read from that nested component
   * @figmaNestedComponentProperty Value
   */
  @Prop() public readonly badge?: number | string | true
}

⚖️ License

See the LICENSE file for license rights and limitations.