figma-json-tree 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -60
- package/package.json +9 -1
package/README.md
CHANGED
|
@@ -1,24 +1,21 @@
|
|
|
1
1
|
# figma-json-tree
|
|
2
2
|
|
|
3
|
-
Figma JSON
|
|
3
|
+
A TypeScript library for downloading Figma JSON, querying design trees with CSS-like selectors, and converting subtrees into extensible design IR, Tailwind v4 IR, and HTML fragments.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Getting started
|
|
6
6
|
|
|
7
|
-
Node.js
|
|
7
|
+
Requires **Node.js 22.12 or later**. The package provides ESM modules and TypeScript declarations.
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
|
-
npm install
|
|
11
|
-
npm run check
|
|
10
|
+
npm install figma-json-tree
|
|
12
11
|
```
|
|
13
12
|
|
|
14
|
-
ESM과 TypeScript 선언 파일을 빌드합니다. 코어와 다운로드 클라이언트는 현대 브라우저에서도 사용할 수 있으며, 브라우저에 비밀 토큰을 포함하지 않고 서버에서 다운로드한 JSON을 전달하는 구성을 권장합니다.
|
|
15
|
-
|
|
16
13
|
```ts
|
|
17
14
|
import { FigmaTree } from 'figma-json-tree'
|
|
18
15
|
import { FigmaClient } from 'figma-json-tree/figma-json-fetch'
|
|
19
16
|
|
|
20
17
|
const client = new FigmaClient({ token: process.env.FIGMA_TOKEN! })
|
|
21
|
-
const figmaJson = await client.getFile(
|
|
18
|
+
const figmaJson = await client.getFile('YOUR_FIGMA_FILE_KEY')
|
|
22
19
|
const figma = FigmaTree.fromJson(figmaJson)
|
|
23
20
|
|
|
24
21
|
const searchFilter = figma.query('FRAME[name="SearchFilter"]')
|
|
@@ -31,15 +28,17 @@ const table = figma
|
|
|
31
28
|
|
|
32
29
|
const subtrees = figma
|
|
33
30
|
.queryAll({ name: /^ToBe/ })
|
|
34
|
-
.map(node => node.toJSON()) //
|
|
31
|
+
.map(node => node.toJSON()) // Original node JSON, including all descendants
|
|
35
32
|
|
|
36
33
|
const ir = searchFilter?.toIR()
|
|
37
34
|
const tailwindIR = ir?.toTailwind()
|
|
38
35
|
```
|
|
39
36
|
|
|
40
|
-
`fromJson
|
|
37
|
+
`FigmaTree.fromJson()` accepts a parsed full-file API response, a `/nodes` API response, or a single Figma node. Downloading and parsing are separate, so you can also use local JSON. When nothing matches, `query()` returns `undefined` and `queryAll()` returns an empty array.
|
|
41
38
|
|
|
42
|
-
|
|
39
|
+
The core library and download client also work in modern browsers. Keep private Figma tokens on the server and pass downloaded JSON to browser applications.
|
|
40
|
+
|
|
41
|
+
## Selectors and regular expressions
|
|
43
42
|
|
|
44
43
|
```ts
|
|
45
44
|
figma.queryAll({ name: /^ToBe/i, type: 'FRAME' })
|
|
@@ -48,11 +47,15 @@ figma.queryAll('FRAME > INSTANCE[visible=true]')
|
|
|
48
47
|
figma.queryAll('FRAME[name="ProductPage"] TEXT')
|
|
49
48
|
```
|
|
50
49
|
|
|
51
|
-
|
|
50
|
+
Selectors support node types, attribute existence, exact matches, substring/prefix/suffix matches, multiple conditions, descendants, and direct children. Pass JavaScript `RegExp` values through object selectors for regular expression matching.
|
|
51
|
+
|
|
52
|
+
Search follows `children` in depth-first preorder. Queries on a node search its descendants, excluding the node itself, and cannot reference ancestors outside that subtree.
|
|
52
53
|
|
|
53
|
-
|
|
54
|
+
See the [API documentation](docs/api.md) for selector syntax and return contracts.
|
|
54
55
|
|
|
55
|
-
## IR
|
|
56
|
+
## IR plugins
|
|
57
|
+
|
|
58
|
+
Customize the intermediate representation before converting it to Tailwind IR or HTML.
|
|
56
59
|
|
|
57
60
|
```ts
|
|
58
61
|
import { FigmaTree, type IRPlugin } from 'figma-json-tree'
|
|
@@ -72,101 +75,117 @@ const tree = FigmaTree.fromJson(figmaJson, { irPlugins: [semanticPlugin] })
|
|
|
72
75
|
const result = tree.query('INSTANCE')?.toIR().toTailwind()
|
|
73
76
|
```
|
|
74
77
|
|
|
75
|
-
|
|
78
|
+
Children are converted before their parent. For each node, the pipeline applies the default conversion, registered plugins, and per-call plugins supplied through `toIR({ plugins })`, in that order. Plugins receive read-only IR and return a node with updated standard fields or JSON-compatible `extensions`.
|
|
76
79
|
|
|
77
|
-
[IR
|
|
80
|
+
See [IR, plugins, and Tailwind](docs/ir.md) for supported properties, plugin contracts, and CSS integration.
|
|
78
81
|
|
|
79
|
-
##
|
|
82
|
+
## Download CLI
|
|
80
83
|
|
|
81
|
-
|
|
84
|
+
Set the `FIGMA_TOKEN` environment variable before downloading. The CLI reads the token from the environment.
|
|
82
85
|
|
|
83
86
|
```sh
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
node dist/cli/index.js download --file FILE_KEY --nodes 49:7390 --out nodes.json
|
|
87
|
+
figma-json-tree download --file FILE_KEY --out figma.json
|
|
88
|
+
figma-json-tree download --file FILE_KEY --nodes 49:7390 --out nodes.json
|
|
87
89
|
```
|
|
88
90
|
|
|
89
|
-
|
|
91
|
+
When working from this repository, run `npm run build` and replace `figma-json-tree` with `node dist/cli/index.js`. You can also invoke the installed package with `npx figma-json-tree`.
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
Without `--out`, JSON is written to stdout. Use `--force` to overwrite an existing file. Convert a URL node ID such as `node-id=49-7390` to the API format `49:7390`.
|
|
92
94
|
|
|
93
|
-
|
|
95
|
+
## Query CLI
|
|
96
|
+
|
|
97
|
+
Search local JSON with `query` or `queryAll`. These commands require no token or network access.
|
|
94
98
|
|
|
95
99
|
```sh
|
|
96
|
-
#
|
|
97
|
-
|
|
100
|
+
# Extract the first Hover Card frame and all its descendants
|
|
101
|
+
figma-json-tree query --input figma.json \
|
|
98
102
|
--selector 'FRAME[name="Hover Card"]' --out hover-card.json
|
|
99
103
|
|
|
100
|
-
#
|
|
101
|
-
|
|
104
|
+
# Extract every node named Hover Card
|
|
105
|
+
figma-json-tree queryAll --input figma.json \
|
|
102
106
|
--selector '[name="Hover Card"]'
|
|
103
107
|
|
|
104
|
-
# JavaScript
|
|
105
|
-
|
|
108
|
+
# Match names with a JavaScript regular expression
|
|
109
|
+
figma-json-tree queryAll --input figma.json \
|
|
106
110
|
--name-regex '^ToBe' --regex-flags i
|
|
107
111
|
|
|
108
|
-
#
|
|
109
|
-
|
|
112
|
+
# Query an extracted subtree again
|
|
113
|
+
figma-json-tree queryAll --input hover-card.json --selector TEXT
|
|
110
114
|
```
|
|
111
115
|
|
|
112
|
-
|
|
116
|
+
`query` writes one original node object or `null`. `queryAll` writes an array of original nodes or `[]`. No match is a successful result with exit code 0; errors are written to stderr with exit code 1.
|
|
117
|
+
|
|
118
|
+
Specify exactly one of `--selector` and `--name-regex`. Supply regular expressions without `/…/` delimiters and use `--regex-flags` for flags. `--out` and `--force` behave as they do for downloads.
|
|
113
119
|
|
|
114
|
-
|
|
120
|
+
Input can be a file API response, a nodes API response, or a single subtree. Arrays produced by `queryAll` cannot be passed directly back as input.
|
|
115
121
|
|
|
116
|
-
## HTML
|
|
122
|
+
## HTML output
|
|
117
123
|
|
|
118
|
-
|
|
124
|
+
The separate `figma-html` module renders standard IR or Tailwind IR as HTML fragments.
|
|
119
125
|
|
|
120
126
|
```ts
|
|
121
|
-
import { renderHTML } from 'figma-json-tree/figma-html'
|
|
127
|
+
import { renderHTML, collectTailwindClasses } from 'figma-json-tree/figma-html'
|
|
122
128
|
|
|
123
129
|
const frame = figma.query('FRAME[name="Hover Card"]')!
|
|
124
|
-
const html = renderHTML(frame.toIR()) //
|
|
125
|
-
const
|
|
130
|
+
const html = renderHTML(frame.toIR()) // Inline CSS
|
|
131
|
+
const tailwindIR = frame.toIR().toTailwind()
|
|
132
|
+
const tailwindHTML = renderHTML(tailwindIR) // Classes and residual inline CSS
|
|
133
|
+
const classes = collectTailwindClasses(tailwindIR)
|
|
126
134
|
```
|
|
127
135
|
|
|
128
|
-
|
|
136
|
+
Both the library and CLI output **only the markup to insert inside a body**. They do not generate `doctype`, `html`, `head`, `body`, `style`, or `script` tags. Tailwind output includes classes and residual inline styles; the consuming project must build the corresponding CSS. `collectTailwindClasses()` returns a sorted list of unique rendered classes.
|
|
137
|
+
|
|
138
|
+
When rendering HTML, numeric Tailwind arbitrary values are rounded to at most two decimal places, with trailing zeros removed: `leading-[14.522727012634277px]` becomes `leading-[14.52px]`. Class collection uses the same formatting. The original IR and inline style values remain unchanged.
|
|
129
139
|
|
|
130
140
|
```sh
|
|
131
|
-
|
|
141
|
+
figma-json-tree export --input figma.json \
|
|
132
142
|
--selector 'FRAME[id="41:5868"]' --format html \
|
|
133
|
-
--out
|
|
143
|
+
--out hover-card.inline.html
|
|
134
144
|
|
|
135
|
-
|
|
145
|
+
figma-json-tree export --input figma.json \
|
|
136
146
|
--selector 'FRAME[id="41:5868"]' --format html --styles tailwind \
|
|
137
|
-
--out
|
|
147
|
+
--out hover-card.tailwind.html
|
|
138
148
|
|
|
139
|
-
#
|
|
140
|
-
|
|
141
|
-
--input artifacts/live/hover-card-frame-41-5868.tailwind-ir.json \
|
|
142
|
-
--out artifacts/live/hover-card.from-tailwind-ir.html
|
|
149
|
+
# Saved standard IR and Tailwind IR are also supported
|
|
150
|
+
figma-json-tree export --input design.tailwind-ir.json --out design.html
|
|
143
151
|
```
|
|
144
152
|
|
|
145
|
-
`--out
|
|
153
|
+
Omit `--out` to write HTML to stdout. Use `--force` to overwrite an existing file.
|
|
154
|
+
|
|
155
|
+
Rendering is limited to the properties supported by the current IR. It does not fully reproduce vectors, images, or effects, download fonts, or generate interactions such as hover behavior. See [HTML API, limitations, and verification](docs/html.md).
|
|
156
|
+
|
|
157
|
+
## Development and verification
|
|
158
|
+
|
|
159
|
+
```sh
|
|
160
|
+
git clone https://github.com/dosimpact/figma-json-tree.git
|
|
161
|
+
cd figma-json-tree
|
|
162
|
+
npm install
|
|
163
|
+
npm run check
|
|
164
|
+
```
|
|
146
165
|
|
|
147
|
-
|
|
166
|
+
Individual checks and examples:
|
|
148
167
|
|
|
149
168
|
```sh
|
|
150
|
-
npm run lint
|
|
151
|
-
npm run lint:fix
|
|
152
|
-
npm run format
|
|
169
|
+
npm run lint # Check lint rules, formatting, and import order
|
|
170
|
+
npm run lint:fix # Apply safe lint fixes, formatting, and import sorting
|
|
171
|
+
npm run format # Apply formatting only
|
|
153
172
|
npm run typecheck
|
|
154
173
|
npm test
|
|
155
174
|
npm run build
|
|
156
175
|
npm run test:package
|
|
157
|
-
npm run test:live
|
|
158
|
-
npm run test:html:live #
|
|
176
|
+
npm run test:live # Requires FIGMA_TOKEN; makes real API requests
|
|
177
|
+
npm run test:html:live # Uses downloaded Figma data in artifacts/live
|
|
159
178
|
|
|
160
179
|
npx tsx examples/query.ts artifacts/live/file.json
|
|
161
180
|
npx tsx examples/to-ir.ts artifacts/live/file.json 49:7390
|
|
162
181
|
```
|
|
163
182
|
|
|
164
|
-
`npm run check
|
|
183
|
+
`npm run check` runs Biome, type checking, tests, the build, and package consumption checks. Biome uses two-space indentation, single quotes, semicolons only where needed, and a line width of 100. Generated files covered by `.gitignore` and `package-lock.json` are excluded. See [biome.json](biome.json).
|
|
165
184
|
|
|
166
|
-
|
|
185
|
+
Live API verification defaults to file `vHYqaZykgJgAjgUs1mxjp3` and node `49:7390`. Override them with `FIGMA_FILE_KEY` and `FIGMA_NODE_ID`. JSON, IR, Tailwind CSS, and reports are stored in the Git-ignored `artifacts/live/` directory. If the live response contains no names matching `ToBe`, the report records zero matches; a separate fixture verifies positive matches.
|
|
167
186
|
|
|
168
|
-
|
|
187
|
+
The [verification record](docs/verification.md) documents the initial implementation's live results.
|
|
169
188
|
|
|
170
|
-
`FIGMA_LIVE_REPLAY=1
|
|
189
|
+
Set `FIGMA_LIVE_REPLAY=1` to repeat conversion checks using saved file and node responses. The CLI download check still makes a real request in this mode, and the report identifies replay usage. By default, `test:live` downloads fresh responses.
|
|
171
190
|
|
|
172
|
-
|
|
191
|
+
See the [architecture documentation](docs/architecture.md) for module boundaries and the application of SOLID and SLAP (Single Level of Abstraction Principle). Linked reference documents are currently in Korean.
|
package/package.json
CHANGED
|
@@ -1,7 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "figma-json-tree",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Query Figma JSON trees and convert subtrees to extensible design and Tailwind IR.",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/dosimpact/figma-json-tree.git"
|
|
8
|
+
},
|
|
9
|
+
"homepage": "https://github.com/dosimpact/figma-json-tree#readme",
|
|
10
|
+
"bugs": {
|
|
11
|
+
"url": "https://github.com/dosimpact/figma-json-tree/issues"
|
|
12
|
+
},
|
|
5
13
|
"type": "module",
|
|
6
14
|
"sideEffects": false,
|
|
7
15
|
"engines": {
|