Release notes for [0.1.0] - 2023-03-09.
0.5.0 brings two major improvements
Also in 0.5.0 is improved bootstrap 5.2 support, a simple tailwind color integration, and a cluster of bugfixes.
Exportable schemas allows Handoff to connect to any component sets in Figma and generate tokens. In simple json, developers can define the structure of a Figma component and what tokens to extract from each element. This allows Handoff to adapt to the component set of any Figma file, and define semantic meaning for the Figma component. This will enable many features going forward, including -
Exportables are stored in ./exportables. In 0.5.0 we only support exportable
components, so put component definitions in ./exportables/components.
An exportable consists of 3 components -
Using exportables will allow quick tokenization of new components. For example,
here is an annotated exportable for badges, a component not currently supported
by handoff. https://www.handoff.com/docs/customization/exportables/#badgejson
If you add this file to exportables/components and add components/badge
to the figma.definitions in your config.js, Handoff will start looking for a
Badges component set, and generate tokens, css, scss, and types for you.
With no other changes, handoff will create a set of badge token files for you. For example, it will render something like this for css variables - https://gist.github.com/bradmering/020429c30f11d95bfb2577ea57809878. You can see that creates a comprehensive list of all the tokens you would need to render badges in a css frontend framework.
If you want badges to work in the Handoff component preview as well, you would
need to add a badge template to integration/templates/badge/default.html.
That file would look like this for Bootstrap 5.2 -
https://www.handoff.com/docs/customization/exportables/#adding-a-template-to-preview-the-new-exportable.
You would also want to map these tokens to the framework. This is how you might
do that in Bootstrap 5.2, adding this file to integration/sass/extended/badge.scss
https://www.handoff.com/docs/customization/exportables/#mapping-the-new-exportable-to-scss
Handoff allows users to integrate with particular frontend frameworks. We call these integrations. We currently support bootstrap 5.2 out of the box.
0.5.0 now allows these integrations to hook into the data extraction pipeline and modify the output, and optionally write files to the exported directory. This will allow developers to tailor the Figma data pipeline to their needs.
To use this feature, create a plugin.js in the integration folder of your
project. This plugin will have access to any of the core node.js libraries
you need. Export a sandbox module like this -
1sandbox.exports = { 2 postCssTransformer: (documentationObject, css) => { 3 // Modify the css variables prior to save 4 return css; 5 }, 6};
In this example, the plugin has the full documentation object available, allowing it to query the object and then modify the css variables as needed.
Here's a simple plugin example that will read the tokens and write a simple json file with an array of colors in it. - https://www.handoff.com/docs/customization/plugins/#simple-example
Here is a comprehensive plugin.js showing all the options in 0.5.0 - https://www.handoff.com/docs/customization/plugins/#full-example
In 0.5.0 the Bootstrap 5.2 integration was rewritten to simplify and rationalize the way that tokens are being used. Since Bootstrap 5.2 is the first end to end Handoff integration, these improvements will form the template for other integrations.
This release has a simple version of a Tailwind integration. It only supports colors and typography right now. Its in this release to start testing with simple tailwind projects.
To test it out, change the integration in the config.js to this -
1integration: { 2 name: 'tailwind', 3 version: '3.3', 4 }, 5}