@saotesi/figma-bridge
v0.1.0
Published
Builds a Figma plugin from an app's design tokens: variables, text styles and components, plus Compose and Export for designing with the library.
Maintainers
Readme
figma-bridge
A local Figma development plugin, built per app. It turns an app's design tokens and component builders into a Figma library (variables, text styles, components), lets you compose designs from library components only, and exports a frame or the whole library as JSON so code can be generated from it. It needs no Figma API quota and no paid plan.
Panel tabs: one list per builder group (tick items, press Import), Compose and Export.
| Tab | What it does |
|---|---|
| Lists (Variables, Molecules, ...) | Import the ticked items as Figma components. Variables and text styles are always created or updated first and everything else binds to them. |
| Compose | Builds a frame from a JSON spec using only library components and tokens. A raw colour, a loose shape or an unknown component, text style or radius is rejected with the path of the node. Check validates without building. |
| Export → selection | Writes the selected frame in the spec grammar, plus warnings: raw colours, loose shapes, overridden fills, instances of non-library components. |
| Export → library | Writes every library component (id, variants, text layers, size, source files) and every token value, so a spec can be written and checked without opening Figma. |
How it works
Figma's plugin sandbox has no module system and manifest.json allows no network, so the build concatenates the
sources into one code.js and bakes the tokens in. Every app builds its own plugin.
tokens --adapter--> token model (validated) --+
config ---------------------------------------+--> build --> code.js, ui.html, spec-check.cjs, manifest.json
engine sources + preset sources + app builders -+The output is deterministic: no timestamps, no machine paths.
Use
pnpm add -D @saotesi/figma-bridge
figma-bridge init # config, stub files, role map guessed from your token names
figma-bridge doctor # config, token model, roles, text styles, catalogue
figma-bridge build # writes .figma-bridge/ (code.js, ui.html, spec-check.cjs, manifest.json)
figma-bridge check design/specs/home.json # the Compose rules, without opening FigmaEvery command reads ./figma-bridge.config.mjs unless --config <file> is given; build takes --out <dir>.
init writes figma-bridge.config.mjs, design/figma/catalogue.mjs and components.js (where the app's own builders
go), design/{specs,exports,proposals}/, a .gitignore line for the build folder and a figma:build script. It uses the
design-md adapter when DESIGN.md exists, or --adapter ts-module --entry <built token module>. It leaves out the
shadcn molecules whose component files the app does not have, and never overwrites a file without --force.
doctor exits 1 on: an invalid config or token model; a role the preset draws with that the model lacks; a text style
a builder uses that the model lacks; a failing build (orphan builder, missing icon, bad logo). It warns about catalogue
entries whose source file moved and entries with no builder.
In the Figma desktop app: Plugins → Development → Import plugin from manifest…, pick .figma-bridge/manifest.json.
Rebuild after the tokens or any builder changes, then run the plugin again.
The config (figma-bridge.config.mjs)
Default export, validated at start; every problem is reported at once with its path.
| Key | |
|---|---|
| name, label, manifestId? | Panel and plugin name; the app's name in messages; optional Figma plugin id |
| root? | App root (default: the config's folder). Relative paths below resolve against it |
| tokens | A token adapter (below) |
| framePrefix, pluginDataNamespace, textStylePrefix, settingsKey | Names written into the Figma file. Never rename them once a file exists: components and styles are found by them |
| library | { kind, file, selectionFilePrefix, dir }: the export's kind, its file name, the prefix of a selection export, and where exports live (default of the spec check) |
| componentsDir | Folder of the app's UI primitives; a file there that no catalogue entry covers is listed as "no builder yet" |
| icons | { package, from?, snapshot? }. Icons are read from the package by module resolution (lucide-react 0.x and 1.x) |
| logo | { size, svg({ root, model, read }) }: the logo's viewBox size and a function returning its SVG |
| presets | Builder presets, e.g. shadcnPreset(...) |
| sourceFiles | Source files in concatenation order: names inside the package's plugin/src, or absolute paths (a preset's sourceFile, the app's builders) |
| catalogue | The app's modules exporting GROUPS and CATALOGUE, merged after the presets' |
| groupOrder? | Order of the panel groups and their entries |
| prelude? | Raw code inserted where a source has @@prelude@@ (shared constants for the app's builders) |
| srcDir?, outDir? | Engine sources folder; output folder (default <root>/.figma-bridge) |
Sources hold @@name@@ placeholders where a name or number belongs (see src/template.mjs for the list and the
escaping). The build fills them from the config and fails on an unknown one.
Token adapters
An adapter has load({ root }) and returns a token model (src/model.mjs, a Zod schema): name, generatedFrom,
primitives, semantic roles per light and dark mode, textStyles, radius, spacing, and optional presentation
settings colourGroups, accentRole, fontFallback, sampleText.
designMdAdapter({ file, roles, ... }): tokens from a DESIGN.md front matter.rolesassigns each role to a colour name or{ hex }.tsModuleAdapter({ entry, palettes, groups, aliases, textStyles, ... }): tokens from the built ESM entry of a TypeScript token package.
Add a new source of tokens by writing a new adapter; nothing else changes.
Builders
A builder registers itself with reg('<group>/<name>', async () => { ... }); its id must have a catalogue entry
(id, group, label, desc, covers, optional needs) and ids are stable because specs and exports refer to them.
Builders are plain source files concatenated into the plugin, so they share one scope. Helpers:
| Helper | Draws |
|---|---|
| F(opts, kids) | A frame (auto layout): name dir gap pad w h fillW fillH fill stroke radius shadow clip align justify wrap ... |
| T(text, opts) | Text: s (a text style), c (colour), size weight lh w fillW align |
| Rect(opts), Dot, Line, Path, Logo | Shapes and the logo |
| I(name, size, colour) | An icon from the icon package (a typo fails the build) |
| variantSet(id, label, props, make) | A component set from the cross product of props |
| masterize(id, node) | Marks a node as the library component id |
| use(id, vals, opts) | An instance of a library component (builds it first when missing) |
| place(node), wrapper(...) | Puts a result on the page in a titled frame |
Colours are role names bound to the Figma variables, so recolouring a variable restyles every component.
Presets
preset-shadcn provides builders for the common primitives (button, badge, input, checkbox, switch, tabs, card, table,
select, dropdown, dialog, sheet, tooltip, toast, calendar, command ...). It uses shadcn roles only; an app maps those to
its own palette in its adapter, and may override through the preset's options: roles (onPrimary, linkText,
secondaryFill, switchOff), style.buttonShadow, colours.success (a #rrggbb or a role name), copy (all the sample
text; an empty pillTabs drops the pill tabs) and exclude (builder ids to leave out of the panel). All have neutral
defaults. The equivalence test shows the options can reproduce two apps' own molecules exactly. A preset is a source file, so the app's builders
can call its helpers (makeButton, makeBadge, makeInput, cap, row, deliver ...).
Behaviour worth knowing
- Safe to re-run. Collections, variables and text styles are matched by name and updated. An item imported before is replaced in place. A failed item is removed so no half-built layers stay.
- Replacing a component deletes the old main component, so instances elsewhere detach. Re-import what uses it.
- Free plan. One mode per variable collection: if a Dark mode is refused, dark values go into a second
Colors (Dark)collection. If a page cannot be added, items go on the current page. - Fonts. A missing weight falls back to the nearest one; a missing family falls back to the model's
fontFallback, if set. - Not carried over. Tabular figures, hover and focus states, animations, anything driven by live data.
Spec grammar
A spec is a frame tree of kinds frame, text and instance:
{ "schema": 1, "kind": "frame", "name": "Page", "dir": "V", "w": 1440, "gap": 24, "pad": [64, 80], "fill": "background",
"children": [
{ "kind": "text", "text": "Title", "style": "h1" },
{ "kind": "instance", "component": "molecules/button", "variant": { "variant": "default", "size": "lg" }, "texts": { "label": "Go" } }
] }Frame keys: name dir gap pad w h fillW fillH fill stroke sw dashed sides radius shadow clip align justify wrap abs opacity children.
Text keys: text style color align w fillW size weight lh. Instance keys: component variant texts name w fillW fillH.
Colours are variable names, { "role": name, "a": 0.5 } or { "mix": [a, percent, b] }.
Develop
Everything is strict TypeScript (noUncheckedIndexedAccess, no any), in two programs:
| Program | Sources | Output |
|---|---|---|
| tsconfig.json (Node) | src/, bin/, preset-shadcn/index.ts, catalogue.ts, data.ts | dist/src, dist/bin, dist/preset-shadcn |
| tsconfig.plugin.json (Figma sandbox, @figma/plugin-typings) | plugin/src/*.ts, preset-shadcn/molecules.ts | dist/plugin/src, dist/preset-shadcn/molecules.js |
The plugin sources are scripts, not modules: they share one global scope (types in plugin/src/globals.d.ts) and are
concatenated into code.js after type-checking, so the emitted JavaScript is the same file the sandbox runs. A
placeholder that must survive the TypeScript emit is written as /*@@name@@*/ {} (or a number) and filled by the build.
pnpm build # clean, compile both programs, copy the panel into dist/
pnpm typecheck # both programs, no output
pnpm test # build, then every testTests
The golden test rebuilds a reference app from frozen fixtures and compares code.js, ui.html, spec-check.cjs and
manifest.json with the committed golden files (line endings normalised). test/golden-phase*/ keep the earlier
goldens next to the reviewed diffs that explain each change. The equivalence test runs each app's molecules outside
Figma and compares everything they draw. test/live-check.mjs repeats the golden build against a real checkout with
its own icon package. The neutrality test fails on domain words, app paths or brand colours in the package source.
