Skip to content

Commit

Permalink
Updates README to include variables2json instructions.
Browse files Browse the repository at this point in the history
  • Loading branch information
@daniel-casado
daniel-casado committed Sep 14, 2023
1 parent c6c5cfe commit edd3cb8
Show file tree
Hide file tree
Showing 2 changed files with 117 additions and 63 deletions.
169 changes: 106 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,24 @@

## 🚛 About Figma Token Engine

The Figma Token Engine is a project dependency that transforms design tokens (either as Figma Styles of from [Token Studio](https://tokens.studio/) into CSS styles using [token-transformer](https://www.npmjs.com/package/token-transformer) and [style-dictionary](https://github.com/amzn/style-dictionary).
The Figma Token Engine is a project dependency that transforms design tokens (either as Figma Styles, from [Token Studio](https://tokens.studio/), or [variables2json](https://www.figma.com/community/plugin/1253571037276959291/variables2json)) into CSS styles using [style-dictionary](https://github.com/amzn/style-dictionary).

<div align="center">
<img src=".docs/engine-diagram.svg" alt="Logo" alt="Logo">
</div>

<details>
<summary><b>Why variables2json plugin?</b></summary>

For all the other input formats, I'm using the [Figma API](https://www.figma.com/developers/api) to fetch the information I need directly from the Figma File. This is very useful to create automatic pipelines that don't require direct access (or even installing) to Figma.

However, at the time of this version, Figma Variables API is only for Enterprise Accounts, and I don't have access to one. That's why I had to rely on Figma plugins to extract and somewhat parse the variables data. Unfortunately, this makes the process more manual, as it requires someone to open the Figma file(s), run the plugin, save the token file and run the token engine.

I chose variables2json because it exports an easy to process format and the process to export it is straightforward enough. Also, because in cases where you're referencing a file's variables in another file, variables2json doesn't try to resolve it and mantains the name of the connection, which I need.

I was working on a version using the Figma Variable API output, from a brief moment I had access to an Enterprise account. The branch is [feature/variables-input](https://github.com/d01000100/figma-token-engine/tree/feature/variables-input) and if you have an enterprise account and are willing to check it out and continue the work, I'd be very grateful.
</details>

<br/>

## 📓 Config Files
Expand All @@ -28,17 +40,34 @@ The Figma Token Engine (FTE) requires two files which can be created using `npx

The two files helps the FTE to access the Figma API and to know where to find and save the files you need.

First, `.tokens.config.json` tells the FTE which approach will use (TokensStudio or FigmaStyles), the output directory and the platforms we need to support.
### .tokens.config.json

First, `.tokens.config.json` has the custom configuration of the FTE pipeline:

- **tokenFormat:** The type of data we're going to read from the Figma file. The current version supports the following formats:
- **FigmaStyles** The Style library published by the Figma file. It read the colors, typographies and shadows and uses the name of the styles as is to name the generated variables.
- **TokensStudio** Reads the tokens from the [Tokens Studio plugin](tokens.studio). The current version combines all tokens sets into the same output and does not support themes or theme groups.
- **variables2json** Reads the export(s) from the [Figma plugin variables2json](https://www.figma.com/community/plugin/1253571037276959291/variables2json). Parses the color and numeric variables. It also includes the Figma Styles.
- **inputFile** The file where the tokens read from Figma will be written to and read by StyleDictionary
- **outputDir** The location where the FTE will output the processed tokens.
- **platforms** *optional* The specified platforms (called [formats on StyleDictionary](https://amzn.github.io/style-dictionary/#/formats)) that the FTE will generate. The current version supports:
- `css`. Using css custom variables. Outputs to `tokens.css`
- `scss`. Outputs to `tokens.scss`
- `scssMap`. Creates a sass map with the tokens names as keys and the tokens values as the map values. Outputs to `tokensMap.scss`
- `less`. Outputs to `tokens.less`
- `jsp`. Outputs js variables to `tokens.js`
- `ts`. Outputs ts variables to `tokens.ts`
- `json`. Outputs a JSON, whose structure is the same as the source. Outputs to `tokens.json`

*Example*

```json
{
"tokenFormat": "TokenStudio",
"figmaFileId": "",
"inputFile": "./tokens-studio.json",
"tokenFormat": "FigmaStyles",
"inputFile": "./raw_styles.json",
"outputDir": "./src/styles/tokens",
"platforms": [
"css",
"cssAutocomplete",
"scss",
"scssMap",
"less",
Expand All @@ -49,6 +78,67 @@ First, `.tokens.config.json` tells the FTE which approach will use (TokensStudio
}
```

#### Specific input format arguments

Some input format may recieve additional arguments that configure how that specific format is processed or what data is logged into additional files

<details>
<summary>Tokens Studio</summary>

- **sets**: Optional string[]. What sets will be included to parse and to resolve alias values. If undefined, all token sets will be parsed.
- **excludes** Optional string[]. What token sets will be excluded from the result. This may be useful to include sets for token resolution but exclude them from the final outputs. If undefined, no token sets will be excluded.
- **transformerOutput**: Optional string. Filename and location, either absolute or relative to the fte process, to write the output of the token-transformer. It has the tokens as they entery StyleDictionary pipeline. Useful for debugging. If undefined, it will be written to a temporary file.

_[See more](https://www.npmjs.com/package/token-transformer)_

```json
{
"tokenFormat": "TokensStudio",
"inputFile": "./raw_tokens.json",
"outputDir": "./src/styles/tokens",
"platforms": [
"css",
"scss",
"scssMap",
"less",
"js",
"ts",
"json"
],
"sets": ["base", "dark", "light"],
"excludes": ["base"],
"transformerOutput": "./tmp/transformed_tokens.json"
}
```
</details>

<details>
<summary>variables2json</summary>

- **variableFiles**. **Required** string | string[]. File or files of exports from variables2json. It receives more than one in the case you are using variables from multiple files. Even if they're alias between files!
- **parsedTokensFile**: Optional string. Filename and location to write the parsed variables into. They're the data just before entering the StyleDictionary pipeline. Useful when debugging. If undefined, it will be written on a temporary file.

```json
{
"tokenFormat": "variables2json",
"variableFiles": ["./global-tokens.json", "./component-tokens.json"],
"outputDir": "./src/styles/tokens",
"platforms": [
"css",
"scss",
"scssMap",
"less",
"js",
"ts",
"json"
],
"parsedTokenFile": "./tmp/parsed-variables.json"
}
```
</details>

### .env

Secondly, the `.env` exposes sensitive data we might not want to have in our repository such as the Figma API Key and the Figma file which we are pulling data from.

```sh
Expand Down Expand Up @@ -92,8 +182,9 @@ Run the token engine using npm scripts:

### CLI params

- **--init**: Create necessary environment files (.env, .tokens.config.json) to run the token engine with example content.
- **--sd-config-file**: Location of a [StyleDictionary configuration file](https://amzn.github.io/style-dictionary/#/config) to merge with the one FTE uses. This can be used to extend platforms, filters, tokens location, etc.
- **`figma-token-engine TOKEN_CONFIG_FILENAME`** A single flagless param will specify a custom `.tokens.config.json` file to read the FTE configuration from.
- **`--init`**: Create necessary environment files (.env, .tokens.config.json) to run the token engine with example content.
- **`--sd-config-file SD_CONFIG_FILENAME`**: Location of a [StyleDictionary configuration file](https://amzn.github.io/style-dictionary/#/config) to merge with the one FTE uses. This can be used to extend platforms, filters, tokens location, etc.

Example of a config file:

Expand Down Expand Up @@ -174,61 +265,11 @@ Run the token engine using npm scripts:

<br/>

## 💻 Commands

### **Default**
## Architecture

Use the default tool configuration with:
*TODO: Complete architecutre documentation of the pipeline*

```sh
npx figma-token-engine
```

> If you don't have the `.tokens.config.js`file and the needed environment secrets in the `.env` you will need to initialize the project with the --init option.
<br/>
### **Initialize project**
```sh
npx figma-token-engine --init
```
This will create or update two files: `.tokens.config.json` and `.env`, which are required for the tool to work.
Update the configuration file and the enviroment variables with your current project needs.
<br/>
### **Custom Configuration file**
You can also pass your custom configuration file:
```sh
npx figma-token-engine --config .dev-tokens.config.json
```
<br/>
### **Multiple custom Configuration file**
Or pass an array for multiple projects:
```sh
npx figma-token-engine --config .angular-tokens.config.json .react-tokens.config.json .android-tokens.config.json
```
<br/>
### **Fetch API Data**
If you want to fetch data from the Figma API, use:
```sh
npx figma-token-engine
```
<br/>
*[Go to architecture](./docs/architecture.md)*

## 📝 Example: Create a React App and install Figma token Engine

Expand All @@ -248,6 +289,8 @@ If you added the FIGMA_PERSONAL_ACCESS_TOKEN and FIGMA_FILE_URL you can fetch th
npx figma-token-engine
```

*More detailed guide: [Quick Guide at Medium](https://medium.com/@jdanielca/figma-token-engine-quick-start-b6e0bc08a388)*

<br/>

## 🧰 Development
Expand Down Expand Up @@ -285,6 +328,6 @@ Contributions will open after the alpha release of this stack. Contact us if you
## 🧑‍💻 Team

- [daniel.casado](mailto:jdanielca@gmail.com) - [GitHub](https://github.com/d01000100) (Sr. Design Technologist at frog)
- [jose.lugo](mailto:me@joselugo.dev) - [GitHub](https://github.com/chepetime) (Associate Technology Director at frog)
- [jose.lugo](mailto:me@joselugo.dev) - [GitHub](https://github.com/chepetime)

<br/>
<br/>
11 changes: 11 additions & 0 deletions docs/architecture.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
> TODO:
> - All parts of FTE
> - Figma API
> - Parsers/Prep (Variables, token-transformer)
> - StyleDictionary
> - Filters
> - Transformers
> - Formats
>
> - Mobile additional loop
> - FigmaVariables modes additional loop

0 comments on commit edd3cb8

Please sign in to comment.