Skip to main content

Figma Design Capture Script

A Node.js script to automatically capture Figma designs and generate comprehensive documentation for the Juniro platform.

🎯 Purpose​

This script automates the process of:

  • Capturing screenshots from all Figma portals (Parents, Providers, Public, Mobile)
  • Extracting metadata (node IDs, URLs, component information)
  • Generating documentation in Markdown format
  • Creating thumbnails for easy browsing
  • Organizing assets in a structured file system

📁 File Structure​

scripts/
├── figma-capture.js      # Main capture script
├── figma-utils.js        # Figma API utilities
├── package.json          # Dependencies
└── README.md            # This file

docs/design-system/
├── screenshots/          # High-resolution screenshots by portal
│   ├── parents/
│   ├── providers/
│   ├── public/
│   └── mobile/
├── thumbnails/          # Thumbnail images
├── metadata.json        # Complete screen metadata
└── documentation.md     # Generated documentation

🚀 Setup​

1. Install Dependencies​

cd scripts
npm install

2. Get Figma Access Token​

  1. Go to Figma Settings
  2. Navigate to "Personal access tokens"
  3. Create a new token with read permissions
  4. Copy the token

3. Set Environment Variable​

export FIGMA_ACCESS_TOKEN="your_token_here"

Or add to your .bashrc or .zshrc:

echo 'export FIGMA_ACCESS_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc

4. Configure File Keys​

Edit figma-capture.js and update the CONFIG.files object with your Figma file keys:

files: {
  parents: 'YOUR_FIGMA_FILE_KEY',      // Parents Portal
  providers: 'YOUR_FIGMA_FILE_KEY',    // Providers Portal
  public: 'your_public_file_key',          // Public Website
  mobile: 'your_mobile_file_key'           // Mobile Application
}

📖 Usage​

Capture All Portals​

npm run figma:all
# or
node figma-capture.js --all

Capture Specific Portal​

# Parents portal only
npm run figma:parents
# or
node figma-capture.js --portal parents

# Providers portal only
npm run figma:providers
# or
node figma-capture.js --portal providers

# Public website only
npm run figma:public
# or
node figma-capture.js --portal public

# Mobile app only
npm run figma:mobile
# or
node figma-capture.js --portal mobile

📊 Output​

Generated Files​

  1. Screenshots (docs/design-system/screenshots/)

    • High-resolution PNG images (2x scale)
    • Organized by portal
    • Named by node ID

  2. Thumbnails (docs/design-system/thumbnails/)

    • JPEG thumbnails (300px width)
    • Optimized for documentation
    • Same organization as screenshots

  3. Metadata (docs/design-system/metadata.json)

    • Complete screen information
    • Node IDs, names, types, paths
    • Figma URLs for direct access
    • File relationships

  4. Documentation (docs/design-system/documentation.md)

    • Auto-generated Markdown
    • Organized by portal
    • Links to Figma and screenshots
    • Usage instructions

Example Output Structure​

docs/design-system/
├── screenshots/
│   ├── parents/
│   │   ├── 0:1.png
│   │   ├── 0:2.png
│   │   └── ...
│   ├── providers/
│   │   ├── 2:4074.png
│   │   ├── 2:4075.png
│   │   └── ...
│   └── ...
├── thumbnails/
│   ├── parents/
│   │   ├── 0:1.jpg
│   │   ├── 0:2.jpg
│   │   └── ...
│   └── ...
├── metadata.json
└── documentation.md

🔧 Configuration​

Image Settings​

Edit the CONFIG.image object in figma-capture.js:

image: {
  format: 'png',        // Image format (png, jpg, svg, pdf)
  scale: 2,            // Image scale (1, 2, 4)
  thumbnailWidth: 300  // Thumbnail width in pixels
}

Output Directories​

Edit the CONFIG.output object:

output: {
  base: '../docs/design-system',
  screenshots: '../docs/design-system/screenshots',
  thumbnails: '../docs/design-system/thumbnails',
  metadata: '../docs/design-system/metadata.json',
  documentation: '../docs/design-system/documentation.md'
}

🎨 Integration with Documentation​

Docusaurus Integration​

The generated documentation can be integrated into your Docusaurus site:

  1. Add to sidebar (sidebars.js):
{
  type: 'category',
  label: '🎨 Design System',
  items: [
    'design-system/documentation',
    'design-system/metadata'
  ],
}
  1. Create design system page (docs/design-system/index.md):
---
id: design-system
title: Design System
sidebar_label: Design System
---

# Juniro Design System

This section contains all design screens and components captured from Figma.

## Quick Access

- [All Screens](documentation.md)
- [Screenshots Gallery](../design-system/screenshots/)
- [Metadata](../design-system/metadata.json)

## Portals

- [Parents Portal](documentation.md#parents-portal)
- [Providers Portal](documentation.md#providers-portal)
- [Public Website](documentation.md#public-portal)
- [Mobile Application](documentation.md#mobile-portal)

🔄 Automation​

GitHub Actions​

Create .github/workflows/figma-capture.yml:

name: Figma Design Capture

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM
  workflow_dispatch:     # Manual trigger

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: |
          cd scripts
          npm install
      - run: |
          export FIGMA_ACCESS_TOKEN=${{ secrets.FIGMA_ACCESS_TOKEN }}
          npm run figma:all
      - uses: actions/upload-artifact@v3
        with:
          name: design-system
          path: docs/design-system/

Cron Job​

Add to your system crontab:

# Capture designs every Monday at 9 AM
0 9 * * 1 cd /path/to/juniro-docs/scripts && npm run figma:all

🐛 Troubleshooting​

Common Issues​

  1. "FIGMA_ACCESS_TOKEN environment variable is required"

    • Set the environment variable: export FIGMA_ACCESS_TOKEN="your_token"
    • Check token permissions in Figma settings

  2. "No file key configured for [portal] portal"

    • Add the file key to CONFIG.files in figma-capture.js
    • Verify the file key is correct

  3. "Error fetching Figma file"

    • Check file permissions in Figma
    • Verify the file key is valid
    • Ensure your token has access to the file

  4. "Error downloading image"

    • Check network connection
    • Verify image URLs are accessible
    • Check disk space for downloads

Debug Mode​

Run with verbose logging:

DEBUG=* node figma-capture.js --all

📝 Contributing​

  1. Add new portals: Update CONFIG.files with new file keys
  2. Enhance documentation: Modify generateMarkdown() in figma-utils.js
  3. Add new features: Extend FigmaUtils class with new methods
  4. Improve error handling: Add more specific error messages

📄 License​

MIT License - see LICENSE file for details.

🤝 Support​

For issues or questions:

  1. Check the troubleshooting section
  2. Review Figma API documentation
  3. Create an issue in the repository