HubSpot Figma-to-Code Pipeline

• Build a dedicated Style Guide page — define colour tokens, spacing scale, typography, radius, and shadows as Figma local variables
• Name every top-level section frame using kebab-case module names (e.g. hero-banner, service-cards, image-text-list)
• Annotate layers with type hints in square brackets: [text], [richtext], [image], [link], [boolean], [number], [choice]
• Mark repeater groups with an asterisk: cards* [group]
• Use Figma auto-layout consistently — it maps directly to CSS flexbox
• Group reusable elements (buttons, cards, badges) as Figma components
• Each website page lives on its own Figma page, with sections stacked vertically in a single parent frame

1. Clone the HubSpot CMS boilerplate:

   git clone https://github.com/HubSpot/cms-theme-boilerplate.git ProjectName
   cd ProjectName
   git init && git remote set-url origin <client-repo-url>

2. Authenticate the HubSpot CLI against the client's portal:

   hs account auth --account=<portal-id>

3. Start hs cms watch in a separate terminal window and keep it running for the entire project:

   hs cms watch src ProjectName --account=<portal-id>

   Run this alongside Claude Code — split your terminal so you can see both. Every file change Claude makes syncs to HubSpot automatically. You'll never run hs cms upload manually.
4. Verify the ProjectName/ folder is live in HubSpot → Marketing → Files and Templates → Design Tools
5. Confirm the HubSpot Private App token has content and files scopes

1. Copy figma-sync-images.js from the BFJ pipeline repo into the project's scripts/ folder
2. Create figma-sync.config.json at the project root with figmaFileKey and defaultFolder
3. Commit an empty .figma-hubspot-manifest.json (or let the script create it on first run)
4. Set environment variables:

   export FIGMA_TOKEN="figd_..."
   export HUBSPOT_TOKEN="pat-ap1-..."

5. Smoke test: node scripts/figma-sync-images.js help
6. Commit all three files to Git — yes, including the manifest

For every top-level Figma frame, four files are produced:

• fields.json — editable fields with defaults pulled from the Figma content
• module.html — HubL template rendering the section
• module.css — scoped styles
• meta.json — with content_types array so the module is available on pages

Local Module Standard — Two-Tab Structure

Every Local Module must follow this structure. Global modules (header, footer, nav) are exempt — they have their own field shapes.

Content Tab:

• Layout dropdown as the first field — only if the design has layout variations
• Section-specific fields extracted from the Figma frame
• section_id text field as the last field — drives anchor / jump links

Style Tab (mandatory, identical on every Local Module):

• heading_tag — H1 / H2 / H3 / H4
• background_type — Color / Image
• background_color — dynamic choices from Style Guide colour tokens
• background_image — visible only when type = Image
• padding_top / padding_bottom — dynamic choices from Style Guide spacing scale

1. Claude builds a sync plan listing every image node and its target module folder
2. Run the batch sync:

   node scripts/figma-sync-images.js batch sync-plan.json

3. The script exports from Figma → uploads to HubSpot File Manager → returns permanent CDN URLs → writes to the manifest
4. Permanent HubSpot URLs are patched into each module's fields.json as src defaults

3-Tier Asset Strategy

1. Claude calls the HubSpot Pages API (POST /cms/v3/pages/site-pages)
2. Each module is placed in layoutSections.dnd_area.rows with default field values
3. The page is created as a draft — never auto-published
4. Claude returns the draft preview URL

Step 1 — Automated QA Parity Check

Run the dedicated QA skill on every draft page. It catches the obvious deviations so human review can focus on judgment calls.

Step 2 — Manual Review

• Review the QA report and fix any critical deviations
• Check responsive breakpoints manually — edge cases the diff might miss
• Verify content defaults look right in the HubSpot page editor
• Review copy, alt text, SEO meta tags, accessibility (keyboard nav, contrast)
• Test interactive elements: dropdowns, forms, toggles, play buttons

Step 3 — Client Approval

• Share the draft URL with the client
• Collect feedback and apply revisions
• Re-run the QA skill after any significant change

Step 4 — Publish

• Move pages from draft to published in HubSpot
• Monitor the first 24 hours for any issues
• Short training session with the client on editing modules