figmint2 v0.8.2
🍃 Figmint2
Figmint2 is an updated iteration on Figmint with some added flexibility and some initial support for composable functions to allow you to design your own conversion scripts.
Figmint can sync styles and exports from a file in figma to json that can be used in a javascript project.
It comes with a snazzy CLI:
It also comes with functions to easily compose your own scripts to extract and generate code from Figma nodes fetched via the Figma API - see the Scripts section
This example site shows a figma file above html and css generated using the JSON that figmint outputs. This example can be found and run in the example
folder in this repo.
👩🏽🏫Recommendations:
- Figma lets you name two styles the same thing. This will cause overwrite issues in your exports.
🚨Notes:
- Currently only Fill styles, Text styles, and exports are supported. PR's welcome for Grid and Effect styles!
- Figmint will only pick up a style if it is used in the file you pass it. If you are finding a style isn't syncing make sure an element in the file is using that style.
- PNG and JPG exports work only with with scale values (2x for example) and not with width or height values (512w). This is a limitation of the figma API.
- Color styles with multiple properties are available as part of the raw export. The simpler named exports will only display the final property.
Install and Config
1. Add figmint to your project:
yarn add figmint --dev
2. Setup your figma file
Setup a file that includes elements that use all the figma styles you want to export. These can either be local or from libraries, but every style you want to export needs to be used in the file you point figmint
at.
Figmint will also pick up exports for the file in qustion. This can be useful for icons, illustrations, etc. For this to work make sure you have an export setup on the image you want to export.
Figmint is able to pick up the file type and scale, as long as you use something like 2x
and not 512w
or 512h
(figma's API is limited in this regard.)
Currently figmint is setup to read the name of the parent to decide what directory to put the export in. For example you can group all your icons together in a layer named icons
to make sure all icons end up in a icons
folder when synced to your project.
3. Setup your config:
Add a .figmintrc.json
file to your project.
The required options are a token
and a file id
.
.figmintrc.json
{
"token": "18898-296d0094-cd7e-4ce3-b9f7-663640190108",
"file": "tid5SFlwk8AqMGBP6dDJvw"
}
4. Run Figmint
You can now run figmint via the CLI:
yarn run figmint
5. 💰Profit!
At this point if everything went as planned you should have a new folder called figmaStyles
in your project. Check the index
file in this folder to see the styles exported from figma.
6. Extra Credit
See Config format and Config options below for more info on how to configure figmint including typescript support and chaging the output folder.
Example Project
An example is included in this repo under the example
directory. This project connects to the example figma file. To sync with the example figma file and run it:
> cd example
> yarn
> yarn figmint
> yarn start
Then visit the example page at http://localhost:1234.
Using your own figma file with the example
You can connect the example to your own figma file by editing .figmintrc.json
in the example
directory. Just add your own token
and file
before running yarn figmint
.
Scripts
fetchData
fetchData
fetches figma data from a library via a Figma.ClientInterface
and stores the results to an output
file destination as one or more files.
export interface FetchData {
client: Figma.ClientInterface,
file: string,
output: string,
setFileName: (fileName: string) => void,
setLoading: (loading: boolean) => void,
setFills: (fills: FigmintFillStyleType[]) => void,
setTypography: (typography: FigmintTypeStyleType[]) => void,
setExports: (exports: FigmintExportType) => void,
typescript?: boolean,
}
export const fetchData = async ({
client,
file,
output,
setFileName,
setLoading,
// set our local state
setFills,
setTypography,
setExports,
typescript,
}: FetchData): Promise<void>
Sample usage as script
import { fetchData } from 'figmint2'
const typescript = true
const output = './figma-data'
const file = process.env.FIGMA_FILE
export const data = await fetchData({
client,
file,
output,
typescript,
})
Sample output to ìndex.ts
file in output
dir of choice
const styles = {
colors: [
// ...
],
gradients: [
// ...
],
imageFills: [
// ...
],
textStyles: [
// ...
],
effectStyles: [
// ...
],
raw: [
// ...
],
}
export type ColorValues = keyof typeof styles.colors
export type GradientValues = keyof typeof styles.gradients
export type TextValues = keyof typeof styles.textStyles
export type EffectValues = keyof typeof styles.effectStyles
export default styles
Colors
See Using the Figma API to get colors
Retrieve and store colors from figma file (by default get from fills with ELLIPSE
style as per the matchLeaf
function which will default to use the isEllipse
function)
You can pass a custom matchLeaf
function in the options object.
You can pass a token
as argument or set process.env.FIGMA_API_TOKEN
as Figma API token value
import { getColors } from 'figmint2'
const opts = {token, genFiles, matchLeaf}
getColors(fileKey, opts): Promise<string[]>
By default it saves colors to a build
folder as follows.
/build
colors.scss
colors.ts
colors.json
You can pass in a custom genFiles
function in the options
argument to customize how and where colors are stored.
Illustrations
Return illustration names from figma file
fetchIllustrationsFromFigmaFile(fileKey, token): Promise<string[]>
Icon SVGs
See Figma tokens automatically turned into code: how we kickstarted our design system
Get SVGs from components in Figma file. getSVGsFromComponents
is a factory function which returns an async function that can be called with a list of components to return a list of SVG results with SVG data that can be stored somewhere, either locally or in the cloud.
getSVGsFromComponents(key: string, token: string): (components: any[]): Promise<SVGResult[]>
Use getComponentsFromNode
to retrieve components to extract SVGs for
[
{
id: '2:3',
name: 'name=page',
type: 'COMPONENT',
blendMode: 'PASS_THROUGH',
children
…
}, {
name: 'name=person-chating',
…
}, {
name: 'name=build',
…
}
]
SVG results are saved as a list of SVGResult
interface SVGResult {
name: {
size: string
name: string
}
fileName: string
svg: string
}
Sample usage of getSVGsFromComponents
import { getComponentsFromNode, getSVGsFromComponents, getSVGs } from 'figmint2'
const components = getComponentsFromNode(node)
const getSVGs = getSVGsFromComponents(key, token)
const results: SVGResult[] = await getSVGs(components)
It’s now up to you to upload each image as a separate file to your servers.
CLI
The CLI for figmint is pretty simple, just run yarn figmint
or npm run figmint
in your project after it is installed.
Watch Mode (alpha)
It is also possible to run the CLI in watch mode. This will update your json as things change on figma without you needing to re-run the command.
Watch interval
Currently watch mode will check Figma every minute (60000
ms by default) and write to the output
destination if any changes were detected. This interval can be customized by setting the FIGMINT_INTERVAL_SECS
env variable or passing intervalSecs
as a prop to the Output
Component.
Writing changes
Figmint only writes a new index
at the destination if the file content has changed, simply by comparing old file content with new content and ensuring they are not identical.
Config format
To connect to your own figma file you'll need to add both an access token and the file ID. See Config Options for details.
Figmint uses cosmiconfig for configuration file support. This means you can configure figmint via:
- A
.figmintrc
file, written in YAML or JSON, with optional extensions: .yaml/.yml/.json. - A
.figmintrc.toml
file, written in TOML (the .toml extension is required). - A
figmint.config.js
or.figmintrc.js
file that exports an object. - A "figmint" key in your package.json file.
The configuration file will be resolved starting from the location of the file being formatted, and searching up the file tree until a config file is (or isn't) found.
Config options
token
Your figma token
file
The file ID you want to sync. In your figma file click Share
and the copy the link. It'll look something like:
https://www.figma.com/file/P2X8Apme93sfEN8wACKziOxq/FileName
in this case the file ID is P2X8Apme93sfEN8wACKziOxq
output (default: figmaStyles
)
Figmint writes any styles it finds to a js file. By default this file is written to a ./figmaStyles/
directory. If you would like to use a different location you can add an output
to your config.
Output supports nested directories, so some/directory/figma
as output would result in a new file ./some/directory/figma/
being created.
typescript (default: true
)
If set to true this will generate typescript types in your export.
Contributing
make sure to add #!/usr/bin/env node
to the top of bin/figma.js
after building as parcel 1 does not do this by default.
1 year ago