Improvements

[sneko]

Below you will find improvements or issues that I have detected but that were not mandatory to me to use the library.

If you are interested in contributing, please have a look at the contribution section.

Current issues

• Using --replace-font-pattern will change the text box geometry (selrect, points...), so it will always find differences between the Figma transformation and the hosted Penpot file. It was not an issue in my case because I was replacing a font wrongly named into Figma but it was using the same shape. For this to be solved it probably only depends on Penpot evolutions to set those properties by API.
• Some SVG have defects due to Figma exposing the SVG path and not the original path (it can lead to bigger strokes...)
• Gradient colors seem rotated by 90°
• Strokes may appear differently (4 instead of 1) (limitation of Penpot, see https://tree.taiga.io/project/penpot/us/2372 and feature: Add a stoke on a specific border penpot/penpot#3005)
• Nodes may be invisible despite being in the tree... it appears to be random. And it's not due to hydratation since we tested with --no-hydrate. Maybe a performance Penpot issue? Because focusing on the "disappeared" element from the tree panel shows it (maybe due to local instance... works on SaaS instance by exporting/importing .penpot file)
• Hydratation may have no impact if the file is too big because it wait 30 seconds by default after a successful get-file... but UI init may take longer. The workaround to increase mininumStartupTimeSeconds. We should have it as a CLI parameter
• Stroke caps (on an arrow for example) are not rendered correctly (it uses SVG parsing that does not represent the minimal original information)
• When set step is failing, if we try to rerun just this part with debug set it appears it cannot be replayed. It's like if remaining operations rewritten to the file were breaking it... maybe the file must be deleted first (in case it does not do this by default)

Possible improvements

• Implement "caching" by looking at last command parameters and date, last Figma file modification, if no modification since then, skip except if --force is specified
• Allow not overriding the Penpot file name (useful in case of splitting)
• Allow specifying a custom folder for all steps files
• Provide a sample of automatic synchronizations through a GitHub repository with GitHub Actions. It should also manage the cache between triggers so images are kept (other files can be discarded to not slow down the pipeline)
• Performance: in the compare step, we manage Map for comparaison and a graph. We could try to free some memory by dereferencing those that are processed (hopping the garbage collector would react quickly) (not a priority, depends if bigger files than mine are used)
• Manage instances-components bindings cross files synchronized at the same time (see https://github.com/betagouv/figpot?tab=readme-ov-file#how-to-synchronize-multiple-figma-files-while-keeping-their-components-references-between-each-other for more details)
• Implement "Figma input to Penpot output" tests for each independent piece of logic (nested rotations, instance of instance inside a component defintion...)
• Manage Figma prototypes
• In the code I mention local component defects from Figma but in fact those are components removed but kept by Figma to feed instances with needed information or to be restored (ref: https://forum.figma.com/t/rest-api-issue-local-component-listed-but-not-existing-in-the-document-tree-but-accessible-via-node-endpoint/78294). Maybe this verbiage could be adjusted (note that by exclude nodes it can happens too)
• Using --exclude-node-pattern '- mypattern' will make the CLI parser detecting -my pattern as a parameter. We should clarify when using dashes only using the equal symbol makes it working: --exclude-node-pattern='- mypattern' (ref: Accept negative number values tj/commander.js#61)
• Using npx figpot --version always returns v0.0.0 according to the package.json, not to the pushed version
• For developpers debugging they need to make sure to run debug retrieve before changing Penpot file and directly trying a debug transform, otherwise fonts bindings and so won't be here
• For large files pushing to Penpot into chunks may take time because the backend tries to validate the whole document. It's possible to specify a request parameter skipValidate: true to speed up things but we cannot guarantee the integrity after that. Maybe allow this trough a CLI parameter after months of stable releases to be sure we don't mess with files (but it seems not a big deal, people could just re-sync or delete/recreate the file)
• Have an helper to save/restore mapping.json file like --git-mapping-branch (save after transform, restore before retrieve... like that in case of error in the middle, we will still use the same bindings)
• Skip prompt confirmation for missing mapping.json in case the document is empty (maybe use summary endpoint to have this information?) --> canceled since --ci exists
• Either use --ci to pass command prompts (or use distinct --yes, --yes-mapping)
• Hydratation requires a headless browser, provide a simple command to install those dependencies (npx figpot deps)
• The library requires using at least Node v19 due to the use of fs.openAsBlob(). Try to find a polyfill or so since lot of users stay on old versions?