npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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.

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 Figma

Every 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. roles assigns 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 test

Tests

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.