		@@ -5,2 +5,220 @@ # figma-transformer

		## Which problems does this solve?

		Break free from the file structure
		The Figma API response is very strict in terms of the file structure. To get to a specific node you have to navigate through the entire tree of nodes and it's really easy for your code to break if there's a change in the design file that changes the initial hierarchy.

		We break from that rigid structure by creating shortcuts that are grouped by node type, making it a lot easier to access the nodes that we want irrespective of their placement in the file.

		```json
		{
		"children": [{...}, {...}],
		"shortcuts": {
		"CANVAS": [...],
		"INSTANCE": [...],
		"RECTANGLE": [...],
		"STYLE": [...],
		"TEXT": [...],
		"FRAME": [...],
		"COMPONENT": [...],
		"GROUP": [...]
		}
		}
		```

		We can see that even though this node just has two direct children, it actually contains a lot more elements down the tree, which are surfaced in the shortcuts.

		Each node of the document tree contains the shortcuts to all their respective child nodes, which reduces the amount of work needed to get to the information we need.

		Missing information from nodes
		From the API we can get the information about the styles and components that are present in the file, which is great, but it doesn't contain all the information so we need to parse the entire file to get the additional information that we usuallly need.

		Let's look at how the Figma API describes the styles in a document:

		```json
		styles: {
		"1:12": {
		key: "ea017aed6616af00f3c4d59e3d945c8c3e47adca",
		name: "Green",
		styleType: "FILL",
		description: "",
		},
		"1:11": {
		key: "e234400b962ffafce654af9b3220ce88857523ec",
		name: "Red",
		styleType: "FILL",
		description: "",
		},
		"97:6": {
		key: "cc806814e1b9b7d20ce0b6bed8adf52099899c01",
		name: "Body",
		styleType: "TEXT",
		description: "",
		},
		},
		```

		and this is how it's represented after being processed (note the populated styles from the associated nodes)

		```json
		[
		{
		"id": "1:12",
		"key": "ea017aed6616af00f3c4d59e3d945c8c3e47adca",
		"name": "Green",
		"styleType": "FILL",
		"description": "",
		"styles": [
		{
		"blendMode": "NORMAL",
		"type": "SOLID",
		"color": {
		"r": 0.047774821519851685,
		"g": 0.9563318490982056,
		"b": 0.02923285961151123,
		"a": 1
		}
		}
		],
		"type": "STYLE"
		},
		{
		"id": "1:11",
		"key": "e234400b962ffafce654af9b3220ce88857523ec",
		"name": "Red",
		"styleType": "FILL",
		"description": "",
		"styles": [
		{
		"blendMode": "NORMAL",
		"type": "SOLID",
		"color": {
		"r": 0.8515284061431885,
		"g": 0.11155396699905396,
		"b": 0.11155396699905396,
		"a": 1
		}
		}
		],
		"typeStyles": {
		"fontFamily": "Roboto",
		"fontPostScriptName": null,
		"fontWeight": 400,
		"fontSize": 12,
		"textAlignHorizontal": "LEFT",
		"textAlignVertical": "TOP",
		"letterSpacing": 0,
		"lineHeightPx": 14.0625,
		"lineHeightPercent": 100,
		"lineHeightUnit": "INTRINSIC_%"
		},
		"type": "STYLE"
		},
		{
		"id": "97:6",
		"key": "cc806814e1b9b7d20ce0b6bed8adf52099899c01",
		"name": "Body",
		"styleType": "TEXT",
		"description": "",
		"typeStyles": {
		"fontFamily": "Roboto",
		"fontPostScriptName": null,
		"fontWeight": 400,
		"fontSize": 12,
		"textAlignHorizontal": "LEFT",
		"textAlignVertical": "TOP",
		"letterSpacing": 0,
		"lineHeightPx": 14.0625,
		"lineHeightPercent": 100,
		"lineHeightUnit": "INTRINSIC_%"
		},
		"type": "STYLE"
		}
		]
		```

		The same happens with the components, this is what we get from the API:

		```json
		components: {
		"1:5": { key: "", name: "Rectangle", description: "" },
		},
		```

		and this is the processed data:

		```json
		{
		"id": "1:5",
		"parentId": "7:0",
		"fileId": "cLp23bR627jcuNSoBGkhL04E",
		"name": "Rectangle",
		"type": "COMPONENT",
		"blendMode": "PASS_THROUGH",
		"absoluteBoundingBox": {
		"x": -232,
		"y": -208,
		"width": 201,
		"height": 109
		},
		"constraints": {
		"vertical": "TOP",
		"horizontal": "LEFT"
		},
		"clipsContent": false,
		"background": [
		{
		"blendMode": "NORMAL",
		"visible": false,
		"type": "SOLID",
		"color": {
		"r": 1,
		"g": 1,
		"b": 1,
		"a": 1
		}
		}
		],
		"backgroundColor": {
		"r": 0,
		"g": 0,
		"b": 0,
		"a": 0
		},
		"effects": [],
		"children": [...],
		"shortcuts": {...}
		}
		```

		Not only we have the complete node definition but we also have its child nodes and shortcuts so we can easily navigate through the component tree if needed.

		Let's see more specific examples where the benefits of the library really stand out.

		## Examples

		Getting all text used in a document

		```js
		const text = data.shortcuts.TEXT.map(node => node.characters);
		```

		Finding the styles applied to a specific component

		```js
		const styles = data.shortcuts.COMPONENT.filter(
		component => component.name === "Test"
		).map(component => component.shortcuts.STYLE);
		```

		Getting the fill colours for all the rectangles in the first page

		```js
		const fills = data.shortcuts.CANVAS.filter(page => page.name === "Page 1").map(
		page => page.shortcuts.RECTANGLE.fills
		);
		```

		---

		_This project was bootstrapped with [TSDX](https://github.com/jaredpalmer/tsdx)._
		@@ -7,0 +225,0 @@

figma-transformer - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics