DOCSEARCHbyAlgolia
Submit Docs

Figmagic Documentation

repository·main·Indexed 21 days ago

https://github.com/mikaelvesavuori/figmagic

A design-to-code automation tool (v4.6.0) that extracts design tokens, graphics, and React components directly from Figma documents. It generates platform-agnostic JSON or JavaScript tokens, exports graphics as PNG, SVG, or React components, and scaffolds React components based on a formal Figma structure to facilitate a structured design system workflow.

Tokens
23.5K
Snippets
60
Records
88
Agent score
72%

What's inside figmagic

  1. What is Figmagic?

    main

    Figmagic is a command-line tool designed to bridge the gap between design and development by automating the extraction of design assets from Figma. It performs three primary functions:

    1. Output Design Tokens: Generates platform-agnostic JSON or JavaScript (TS, JS, MJS) tokens (e.g., colors, spacing) to decouple design choices from hard-coded implementation.
    2. Output Graphics: Automatically exports graphics as PNG, SVG, or React components with inlined SVGs.
    3. Generate React Components: Creates React components from Figma components that follow a specific formal structure, reducing boilerplate for low-level UI elements.

    Figmagic is lightweight (~45kb compressed), has no external dependencies, and is designer-driven, treating Figma as the single source of truth.

  2. Understand file deletion behavior

    main

    As of version 4.3.2, Figmagic uses the Node native fs module to permanently destroy deleted files.

    Important Note on Delete Modes: Versions 4.3.0 and 4.3.1 previously supported a dual-mode configuration allowing for "soft" deletes (moving files to a local trash folder). This mode is no longer supported and has been removed from version 4.3.2 and forward due to instability. All file deletions are now permanent.

  3. How Figmagic handles Unidimensional vs Multidimensional tokens

    main

    Understanding the difference between Figma Styles and Figmagic tokens is key to designing a compatible system.

    Figma Styles (Multidimensional)

    A Figma Style is often "multidimensional"—it acts as a package containing multiple properties (e.g., a Text Style containing font size, weight, and line height).

    Figmagic Tokens (Unidimensional)

    Figmagic treats tokens as unidimensional instances. It extracts each individual value (e.g., just the font size, or just the line height) as a separate token. This allows developers to mix and match these values in different contexts without being tied to a specific "style package."

    Best Practices for Designers

    • Link to Styles: You should still use Figma Styles to make your design workflow easier.
    • Ensure Visibility: Even if you use styles, ensure the individual values are represented on the Design tokens page, as this is where Figmagic performs its extraction.
    • Composition: When creating complex tokens (like a "Heading L" font), they should be composed of individual values that are also represented as their own unidimensional tokens (e.g., a specific Line Height S token, an H1 size token, and a Font Bold token).

  4. How Figmagic syncs Tokens, Graphics, and Elements

    main

    Figmagic uses three primary synchronization modes to bridge Figma designs to code. Each mode requires specific organization within your Figma file:

    1. Token Sync (Enabled by default):

      • Requirement: A Figma page named Design tokens containing named frames.
      • Purpose: Extracts the core design values (colors, spacing, etc.) used to build elements.
      • Exclusions: Add a leading underscore to a frame name (e.g., _HiddenFrame) to skip it, or name items ignore to skip them.

    2. Graphics Sync (Disabled by default):

      • Requirement: A Figma page named Graphics where components lay directly on the artboard.
      • Purpose: Exports graphics in multiple formats (e.g., SVG, PNG) to avoid manual hand-overs.
      • Note: Since v4.5.11, Figmagic accepts both main components and their instances. Since v4.4.6, graphics can be nested into frames.

    3. Element Sync (Disabled by default):

      • Requirement: Structured Figma components.
      • Purpose: Scaffolds code (like HTML elements: buttons, inputs) by parsing components and deriving values from your Tokens.
      • Critical Dependency: Elements cannot be generated without tokens, as elements rely on tokens for properties like height and color.

    To enable these, use the corresponding CLI flags or configuration settings.

    # Example of enabling all sync modes via CLI
figmagic --syncTokens --syncGraphics --syncElements

  5. Understand Figmagic configuration priority

    main

    Figmagic resolves configuration settings using a specific hierarchy. If a setting is defined in multiple places, the higher priority source wins:

    1. Command Line Arguments and Flags (Highest priority)
    2. Development Variables (e.g., values loaded from a .env file)
    3. Configuration Files (figmagic.json or .initConfig - Lowest priority)

  6. Understand the Figmagic design-to-code workflow

    main

    Figmagic is designed to bridge the gap between design (Figma) and code (Web standards). It focuses on a design tokens workflow, allowing developers to reliably and quickly extract design values from Figma into standard formats used in web development.

    Core Mental Model

    • For Developers: Figmagic acts as a predictable tool in the frontend toolbox (similar to TypeScript or ESLint) to automate the transfer of design values, making day-to-day work effortless and reducing manual CSS updates.
    • For Designers: The goal is for designers to remain largely oblivious to the tool, following minimal conventions so their workflow remains uninterrupted. The tool aims to minimize the need for manual sync meetings by automating the 'design as DevOps' process.

    Key Capabilities

    1. Design Tokens (Primary Priority): The core mission is supporting the extraction of design tokens from Figma to web-standard formats.
    2. Code Generation (Bonus Feature): Provides scaffolding for components in a precise and modern fashion, though it is not intended to be a full 'no-code' component generator.
    3. Graphics Export: Supports exporting design assets as part of the design-to-code transfer.

  7. Core capabilities of Figmagic

    main

    Figmagic focuses on three primary outputs:

    1. Design Tokens: Produces platform-agnostic JSON or web-friendly Javascript (TS, JS, MJS) tokens. This allows you to decouple data from implementation.
    2. Graphics: Automatically exports graphics from Figma as PNG, SVG, inline SVG React components, or objects containing all graphics from a single file.
    3. React Components: Generates React components from Figma elements that follow a formal structure. It supports using your own tokens to ensure the generated code integrates seamlessly with your existing codebase.

  8. Understand Figmagic Elements and Code Generation

    main

    An Element is a Figmagic-compliant component designed to map to standard HTML elements (e.g., input, button, h1). Elements are used to scaffold code that is structured for continued development rather than being a final, hardcoded output.

    By composing larger components from simple Elements, you can automate the generation of code that binds values to tokens rather than hardcoded pixel values. This approach respects standard CSS and HTML principles.

  9. Use nested elements for states and subclasses

    main

    Figmagic supports both flat and nested elements.

    • Flat elements: Best for simple, non-complex elements like hr or headings (h1).
    • Nested elements: Use these for advanced or "stateful" behavior, such as disabled or error states, or for creating subclasses (e.g., a "Warning" button).

    Nesting Limits & Rules:

    • Figmagic currently only generates code based on the first two nested layers (depth-wise). This supports the common pattern: Component > Option/Style/Type > State.
    • You can use subclasses (by using a group or frame) or pseudo-selectors (by prefixing a group or frame with a colon, e.g., :disabled).
    • You can mix these patterns (e.g., Component > State > State).
    • The React component name is taken from the component name; subclasses and pseudo-selectors are named by their group/frame name.

  10. Configure Figmagic synchronization modes

    main

    Figmagic supports three main synchronization modes to bridge Figma designs with code. Note that Tokens are the foundation; without them, Elements cannot be generated.

    • Sync Tokens: (Enabled by default) Requires a Figma page named Design tokens containing named frames for your tokens. You can skip specific items by naming them with ignore or using a specific prefix.
    • Sync Graphics: (Disabled by default) Requires a Figma page named Graphics. Exports components directly. Use the --syncGraphics flag or enable it in your config. Supports multiple export formats.
    • Sync Elements: (Disabled by default) Requires a Figma page named Elements. Generates code for components (e.g., mapping to HTML tags like button, input, h1). Elements rely on tokens for values like height or color to ensure consistency.
    # Example CLI commands to enable sync modes
figmagic --syncGraphics
figmagic --syncElements

  11. What Figmagic is NOT (Non-goals)

    main

    To manage expectations, it is important to note that Figmagic is not a "no-code style component generator" or a "Dreamweaver for React."

    While it supports code generation, this is intended as a scaffolding tool to help developers create components precisely, rather than a tool that replaces the developer's role. Because Figma is primarily a visual tool rather than a behavior-oriented one, Figmagic cannot perform a wholesale translation of complex design behaviors into code without manual developer intervention.

  12. How design tokens and Figma styles work with Figmagic

    main

    Unidimensional vs. Multidimensional Values

    Figma styles are often multidimensional (e.g., a single text style containing size, weight, and line height).

    Figmagic, however, treats tokens as unidimensional. It extracts individual values from each design item. To ensure successful extraction, structure your Figma frames so that each item/token represents only one key property that changes between items (e.g., one frame for Font sizes where each text element has a different size).

    Using Figma Styles

    You can still use Figma styles in your design workflow to maintain a single source of truth. Figmagic will fetch the underlying unidimensional values from the design items, even if they are applied via a Figma style. This allows designers to use styles while developers receive clean, individual tokens.