Plugin concept: Scenegraph info to JSON

Hi all,

So my team is working on our design system and we have an idea for a plugin that will create our design tokens by pulling the colour palette and type scale (size + font) values into a JSON document for our developers to utilise in their dev environments. This would be pulling from a “master assets” file living in the cloud documents.

We’ve been reading over the documentation for the plug-ins and it seems like it might be a possibility, but we feel like we’re not getting a very clear picture from the documentation of what all is possible. We’re only trying to pull information out of a file and a lot of what I’ve read in the documentation is about how you get your plugin to interact with a document.

If anyone’s seen anything like this or might be able to point me in a direction in the documentation that would discuss how this might be possible, that would be super helpful as we’re running out of ideas.

I have a diagram of our concept here. Thank you in advance!


This sounds more like a use-case for the Cloud Content APIs where you can get information about each artboard from a cloud document. Unfortunately, you can’t yet get node-level information from the cloud API. I’m not sure when/if that’s coming. @ashryan, any thoughts here?

Plugins, however, are considered “in application” – that is, they only run inside an open document. For your use case, you could have the master document open in a running XD instance, with the plugin running, but that requires an instance of XD to be running (there’s no headless option here). With an open document, however, the plugin can certainly traverse the entire scenegraph and export the results. Take a look at @cpryland’s Layers for Developers plugin for an example.

While it may be tempting to try and use the file format itself when stored locally, this is not a good idea. The file format can change at any time between XD versions, and is not considered stable. As such, you could end up with a lot more work as XD versions change. Furthermore, the cloud document may not always be stored locally (since it is a cloud document; a local version isn’t always required unless you’re going to work on it, or have worked on it recently.)

@fuchs definitely has thoughts around design systems concepts – maybe he can jump in.

1 Like

This is great Kerri, thank you!!!

Yeah I think we were trying to cover all options in our concept when it came to who was running the plugin. I’m the only Visual Designer on our digital team, so management of our master assets file would likely be handled by me to start. We’re looking for that single source of truth so right now, this would work for us. If it’s one person outputting an updated JSON file for the dev team, that’s a fairly well controlled environment (fully open to arguments against that of course).

I’ll check out the Layers for Developers plugin to see how that works and await any other replies on this thread.

Thank you again! is a starting point for L4D.


Just installed and digging through your site and the info. Thanks so much for this!

IIUC when an XD document is opened your plugin global scope and environment variables are setup.

So if you add a log statement in main.js like this anywhere outside of a function:

And then open the developer console, you’ll see:

Hello World

You could probably get document (artboard and scenenode) information at this initialization stage or send out a request to the could api and then store the results in an object for later. Or you could get this information when the user invokes your plugin dialog or panel.

There’s been discussion about getting the document before. I’d like to propose the option to at least retrieve that information in JSON or a JSON string, knowing ahead of time that it could change. If your plugin relies on it and it changes then you knew ahead of time or if it’s possible you can update your plugin to adjust to those changes. It would be tremendously helpful to get the scenegraph even if that structure changes later.

Something like this:

var scenegraph = require("application").scenegraph;
var scenegraph = JSON.parsify(require("application").scenegraph);

I don’t believe it’s on the roadmap yet but we’ve certainly heard from developers already that they want it. I’ll make sure the Cloud Content API team sees this thread.

@Carlos_CRUK it would be great to chat more with you about the use case and what you’d need from an API standpoint. Do you have any time for a quick meeting over the next couple of weeks?

My email is if you want to drop me a note and we can coordinate.


1 Like

@Velara, you can already read the scenegraph at any time by starting your traversal from require("scenegraph").root.

However, in general it is an antipattern to do work like exporting the whole document the moment the plugin loads, at startup. This slows down XD and doesn’t usually align with user workflows (and XD might not support it in the future). In this case, an explicit “Export” or “Sync” command is probably best, so the user can control when changes are published to their design system artifacts.

@Carlos_CRUK, for an overview of what information you can extract out of an XD document using a plugin, check out the scenegraph, interactions, and assets modules for starters. Feel free to ask questions here if you run into anything that needs clarification!

1 Like

Thank you very much everyone for all the help. One question on the Nov 2019 updates. Regarding the component states, our dev noted that the change log says that component states aren’t available in the plugin API yet, but will be in the future. Is there any information anyone can provide on how that’s likely going to function? If that’s fully TBD, no problem.

the change log says that component states aren’t available in the plugin API yet, but will be in the future

No ETA yet, but we are actively working on it. The way it will likely work is read-only access for now, via an API that will generate you an isolated scenegraph tree showing what a given Component instance would look if it were switched to a different state. We should have more details when this is closer to being released.

In the past it was possible to open the XD file, I think it was a zip, and you could see the document in JSON format. It was mentioned that this information could change and not depend on it.

What I was saying is can we get this string? It already was in a nice formatted structure and contained a bit more information.

var jsonString = require("application").scenegraph.toJSONString();
var rootObject = require("application").scenegraph.toObject();

Just thought I’d loop back on this and see if any updates had been made. I haven’t dug into the API recently and I hadn’t seen updates around it.

Thanks XD team!