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

# How-to: Figma to code

> How to turn Figma files into static HTML and CSS bundles.

## Before you begin

### Tools

* `jq` and `curl`

### Security bundle

Download `security-bundle.zip` from the [Sutro Console](https://console.withsutro.com) during onboarding. Extract it and run all commands from that directory. The bundle includes your API client credentials (`apiClient.id`, `mtls.key`, `mtls.crt`), the Sutro CA certificate (`ca.crt`), and a pre-generated Builder JWT (`builder.jwt`) valid for 45 days.

<Warning>
  The test bundle creates a **test builder** for quick API testing, not for
  production. See [How to Secure
  Connections](/docs/getting-started/auth/how-to-secure-connections) for
  production setup.
</Warning>

### Verify your connection

Test that your credentials work by calling the hello endpoint:

```sh theme={null}
curl -H "Authorization: Bearer $(cat builder.jwt)" \
     -H "x-sutro-api-client: $(cat apiClient.id)" \
     --cacert ca.crt \
     --key mtls.key \
     --cert mtls.crt \
     "https://sapi.withsutro.com/hello"
```

You should see a response confirming your API client, Builder, and organization.

## Steps

Ship-ready bundles take a few deliberate moves, and each step keeps you in control of inputs and outputs throughout the journey.

<Steps>
  <Step title="Create a new project">
    ```sh theme={null}
    curl -H "Content-Type: application/json" \
         -H "Authorization: Bearer $(cat builder.jwt)" \
         -H "x-sutro-api-client: $(cat apiClient.id)" \
         --cacert ca.crt \
         --key mtls.key \
         --cert mtls.crt \
         -X POST \
         -o project.json \
         -d '{"name": "My Figma Project"}' \
         "https://sapi.withsutro.com/projects"
    ```

    **Response** (HTTP 201)

    ```json theme={null}
    {
      "id": "abc123",
      "name": "My Figma Project",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
    ```

    The project details are stored in `project.json`; refer to that file in upcoming steps.
  </Step>

  <Step title="Create an application">
    ```sh theme={null}
    curl -H "Content-Type: application/json" \
         -H "Authorization: Bearer $(cat builder.jwt)" \
         -H "x-sutro-api-client: $(cat apiClient.id)" \
         --cacert ca.crt \
         --key mtls.key \
         --cert mtls.crt \
         -X POST \
         -o application.json \
         "https://sapi.withsutro.com/projects/$(jq -r '.id' < project.json)/applications"
    ```

    **Response** (HTTP 201)

    ```json theme={null}
    {
      "id": "def456",
      "projectId": "abc123",
      "scode": {},
      "status": "Initialized",
      "createdAt": "2025-01-15T10:31:00.000Z",
      "updatedAt": "2025-01-15T10:31:00.000Z"
    }
    ```

    The application details are stored in `application.json`; refer to that file in upcoming steps.
  </Step>

  <Step title="List Figma pages and frames">
    Retrieve the structure of your Figma file to locate frame IDs for code generation.

    ```sh theme={null}
    curl -H "Authorization: Bearer $(cat builder.jwt)" \
         -H "x-sutro-api-client: $(cat apiClient.id)" \
         --cacert ca.crt \
         --key mtls.key \
         --cert mtls.crt \
         -X GET \
         "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/figma/structure?projectLink=<FIGMA_URL>&pat=<FIGMA_PAT>" | jq
    ```

    Replace:

    * `<FIGMA_URL>` : your Figma file link (e.g. `https://www.figma.com/design/abc123/MyFile`)
    * `<FIGMA_PAT>` : your Figma personal access token

    **Response**

    Returns a JSON structure of pages and frames with their IDs.

    ```json theme={null}
    {
      "fileName": "My Design File",
      "pages": [
        {
          "id": "0:1",
          "name": "Page 1",
          "frames": [
            {
              "id": "1:15",
              "name": "Landing Page",
              "type": "FRAME"
            }
          ]
        }
      ]
    }
    ```
  </Step>

  <Step title="Generate code from a Figma frame">
    Trigger the code generation for a specific frame in your Figma file.

    ```sh theme={null}
    curl -H "Content-Type: application/json" \
         -H "Authorization: Bearer $(cat builder.jwt)" \
         -H "x-sutro-api-client: $(cat apiClient.id)" \
         --cacert ca.crt \
         --key mtls.key \
         --cert mtls.crt \
         -X POST \
         -d '{
           "fileKey": "<FIGMA_FILE_KEY>",
           "frameId": "<FRAME_ID>",
           "accessToken": "<FIGMA_PAT>"
         }' \
         "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/figma/generate-static-code"
    ```

    Replace:

    * `<FIGMA_FILE_KEY>` : from your Figma URL (`/file/<key>/...`)
    * `<FRAME_ID>` : from step 3
    * `<FIGMA_PAT>` : your Figma personal access token

    **Response**

    ```json theme={null}
    { "success": true }
    ```

    The request creates a background job.
  </Step>

  <Step title="Check generation status">
    Poll the application status endpoint to monitor the generation progress.

    ```sh theme={null}
    curl -H "Content-Type: application/json" \
         -H "Authorization: Bearer $(cat builder.jwt)" \
         -H "x-sutro-api-client: $(cat apiClient.id)" \
         --cacert ca.crt \
         --key mtls.key \
         --cert mtls.crt \
         -s \
         -X GET \
         "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/status" | jq
    ```

    **Possible responses**

    **Status: Generating** (Application generation in progress)

    ```json theme={null}
    {
      "applicationId": "def456",
      "status": "Generating"
    }
    ```

    **Status: Active** (Generation complete)

    ```json theme={null}
    {
      "applicationId": "def456",
      "status": "Active"
    }
    ```

    The application is ready. Proceed to step 6 to download the bundle.

    **Status: Failed** (Generation failed)

    ```json theme={null}
    {
      "applicationId": "def456",
      "status": "Failed"
    }
    ```
  </Step>

  <Step title="Download the web bundle">
    Once the application status is `Active`, download the generated code as a zip file.

    ```sh theme={null}
    curl -H "Authorization: Bearer $(cat builder.jwt)" \
         -H "x-sutro-api-client: $(cat apiClient.id)" \
         --cacert ca.crt \
         --key mtls.key \
         --cert mtls.crt \
         -X GET \
         -o application-bundle.zip \
         "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/webBundle"
    ```

    **Response**

    * **Content-Type**: `application/zip`
    * **Content-Disposition**: `attachment; filename="application-<APPLICATION_ID>-web-bundle.zip"`
    * **Body**: Binary zip file containing the generated HTML, CSS, and assets

    The zip file contains all the static files generated from your Figma design.
  </Step>
</Steps>

<Check>You now have an exportable frontend bundle. Unzip it, drop it into your hosting pipeline, and show it off!</Check>