All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
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 -
sandbox.exports = {
postCssTransformer: (documentationObject, css) => {
// Modify the css variables prior to save
return css;
},
}
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 -
integration: {
name: 'tailwind',
version: '3.3',
},
}
Continuing incremental improvement over the 0.4.0 release. This release fixes a couple of small build inconsistencies, improves debug mode when running the build and fetch, and allows a fast run mode.
-- --debug will now send the error trace from the
webpack when building a preview. This is especially useful when there is an error
either in the template or scss maps.-- --fast will execute the script but if there is
already a built temp directory, it will use the built dir rather than recreating
it. This speeds up runtime significantly. If this option is supplied but the
temp dir does not yet exist, it will be created.npm run transform:preview or
node node_modules/handoff-app/scripts/fetch.js preview will properly execute
just a single portion of the pipeline rather than the whole pipeline.<ul> wrapper for the
subsequent lists.When 0.4.0 was released, we found a structural problem with the way integrations were published into projects. 0.4.1 resolved a couple of issues, but a couple of significant new pieces of code were required to fully resolve the issue.
The resolution is fixing paths so that they work properly when running the handoff source as well as running handoff in a project.
This release introduces two major new features - framework integrations and much better color support. The color support is straightforward - Handoff now supports much broader color options from Figma including gradients (linear and radial), as well as layered colors, alpha channels and blend modes.
Framework integrations is Handoff's new plugin architecture for integrating tokens with popular web and application frameworks. Previous versions of Handoff were tightly coupled with Boostrap 5.2 as a proof of concept.
To integrate tokens into applications, the tokens need to be mapped to the the files you'll need. In web applications, this means mapping css and sass variables to existing variables, or extending classes with the tokens.
When fetch is run, any files added to the integration folder will be merged
with the selected integration. The sass files will be published to
/exported/{integration}-tokens
Integrations also move the templates into integrations so each framework integration can define the markup for each component, type, and state. This allows handoff to include default markup for common frontend frameworks.
exported/variables file was renamed to exported/tokensexported/{integration}-tokens containing the
maps and extended sass integration files./integration folder that will be merged with
the configured integration sass and templates.integration is an object that contains two properties name and
version. If you set integration.name to custom and version to null
the project will expect a fully defined integration in the /integration dir.figma is an object that allows customization of how components are fetched.
figma.components contains a list of the componentsfigma.components.button will
define how buttons are fetched from figma.search property determines the library component and name of the frame
to look in for the component. Setting figma.components.button.search to
Unicorn will try to find a button structure in a library object called
Unicorn.size property of each component will define a size map allowing projects
to map figma sizes to token names.hex, type, and rgb properties were dropped from the ColorObjectvalue contains the CSS set of color values, either as hex, rgb, rgba, or
gradientsblend contains a set of blend modes as CSS values that map against the
colors/integration in the root of the project to hold integration
configuration./integration/templates
directory./integration/sass and modified to match the new structure.This release fixes two small bugs, one that throws an error on builds because of a missing type declaration in the config.
This release creates base foundation tokens in the /exported directory. This is a major step forward allowing projects to use color, typography and effects as named tokens in projects in addition to component tokens.
This release fixes a small typo in the installer. The version in the installed package version was set to ^0.1.0 rather than ^0.2.0. This release fixes that.
```{type} to define the syntax. For example ```js.