npm package: @quartzds/figma-code-connect-generator
Description: CLI for generating Figma Code Connect mappings from Stencil docs.json
Author: The Quartz Design System Team
Latest version: 1.0.0

# `@quartzds/figma-code-connect-generator`

[![NPM Package][npm-badge]][npm-link] [![License][license-badge]][license]

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:

```bash
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`:

```ts
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`:

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

#### HTML

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

```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:

```json
{
  "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:

```bash
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`:

```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

```tsx
/**
 * 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.

[npm-badge]:
  https://img.shields.io/npm/v/@quartzds/figma-code-connect-generator?logo=npm
[npm-link]: https://www.npmjs.com/package/@quartzds/figma-code-connect-generator
[license-badge]:
  https://img.shields.io/npm/l/@quartzds/figma-code-connect-generator?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCI+PHBhdGggZD0ibTIzLjkgOS43LTMuNTQtNy44OS0uMDA1LS4wMWEuNTQyLjU0MiAwIDAgMC0uMDQxLS4wNzZsLS4wMTQtLjAxOGEuNTMzLjUzMyAwIDAgMC0uMTIyLS4xMjJsLS4wMTUtLjAxMWEuNTI4LjUyOCAwIDAgMC0uMDgtLjA0NGwtLjAyNC0uMDA5YS41MjcuNTI3IDAgMCAwLS4wNjctLjAybC0uMDI4LS4wMDdhLjUyNC41MjQgMCAwIDAtLjA5Ni0uMDFoLTYuODVjLTEuMDItMS41Mi0xLjAyLTEuNTQtMiAwaC02Ljg2YS41NDMuNTQzIDAgMCAwLS4wOTYuMDFsLS4wMjguMDA3YS41MTYuNTE2IDAgMCAwLS4wNjcuMDJsLS4wMjQuMDFhLjUzNy41MzcgMCAwIDAtLjA4LjA0M2wtLjAxNS4wMTFhLjUxLjUxIDAgMCAwLS4wNTcuMDQ3bC0uMDIuMDJhLjU0My41NDMgMCAwIDAtLjA0NS4wNTVsLS4wMTQuMDE4YS41MjIuNTIyIDAgMCAwLS4wNDEuMDc1bC0uMDA1LjAxdi4wMDFMLjExNiA5LjcyYS41MzEuNTMxIDAgMCAwLS4wOTYuMzA0YzAgMi4yOCAxLjg2IDQuMTQgNC4xNCA0LjE0czQuMTQtMS44NiA0LjE0LTQuMTRhLjUzLjUzIDAgMCAwLS4wOTYtLjMwNGwtMy4yNS02LjM3IDYuMDctLjAyM3YxOC4yYy0yLjU1LjI5NC03LjAxLjM4MS03IDIuNWgxNmMwLTIuMDMtNC40OC0yLjI3LTctMi41di0xOC4xbDUuNjktLjAyLTIuOTIgNi40OWMwIC4wMDIgMCAuMDAzLS4wMDIuMDA1bC0uMDA2LjAxOGEuNTQ1LjU0NSAwIDAgMC0uMDIzLjA3NWwtLjAwNS4wMmEuNTI0LjUyNCAwIDAgMC0uMDEuMDkydi4wMDhjMCAyLjI4IDEuODYgNC4xNCA0LjE0IDQuMTQgMi4yOCAwIDQuMTQtMS44NiA0LjE0LTQuMTRhLjUyOC41MjggMCAwIDAtLjEyLS4zMzJ6IiBmaWxsPSIjZmZmIj48L3BhdGg+PC9zdmc+
[license]: ../../LICENSE
[figma code connect]: https://www.figma.com/developers/code-connect
[figma code connect cli]: https://github.com/figma/code-connect