Design Systems Documentation Tools

When creating company-wide guidelines for how UX components should look, what sort of tools do you use to keep this documentation up to date and easily accessible?

Our current “standards” are kept in a Word document. There are so many different properties to try and document that this becomes very cumbersome and clunky very quickly, and I know there has to be a better solution out there. Most of our current documentation is for FTV, but we’ve got projects coming up that will be using Ignition, so we’ll be updating/adding to these soon.

I’ve seen tools like Figma and It seems like these are designed specifically for Web and Mobile development, but I’m not sure if these tools would be useful in this field as they may be web/mobile specific.

My question is, has anybody adapted these tools for use with Ignition (or SCADA in general), or found similar tools to help keep everything organized?

1 Like

Shameless plug:
We’re working on a color management module that will allow for managing colors and tokens inside of Ignition’s project structure. It’ll allow for editing stored colors (yes, HSL is supported :wink:), creating themes with unique color palettes, and assigning colors to tokens on a per-theme basis. All the data is stored in a version control compatible format, and based on initial results the client-side performance is much better than existing client tag/script module color storage methods.

Hoping to have a public beta available sometime in the next month.


Commenting to get notifications on any updates in this chain.

I was about to post a similar question. My company just started using Ignition, so we’re still very much in the process of establishing our “standards”. I was wondering if anyone had found any good methods of documenting their Vision or Perspective applications. I’m looking to outline the page structure, tag and property bindings, etc. so that any future modifications/maintenance on the application would be quick and simple.

As it stands, I’m just planning on writing up a Word document summarizing the application, and including details like “X tag corresponds to Y device”, “Z tag is calculated by function A” and so on. Was just curious if anyone had a better way.

This was something when I first started with Ignition that I was concerned with - documenting each window and each component in each window etc.

What I've found and what I think is more important is defining some general guidelines and coding patterns/GUI patterns.

For instance, any window that requires a dataset to populate it's components - this should be done in exactly one spot on the root container, based on a parameter with the record ID. Then each component should have it's won custom property that I call initialValue that reads from the dataset with a fallback default value in the event that there is no record so of the form try({Root Container.ReadData}[0, 'someColumn'], 'myFallBackValue') - and then your components value is bound to this. Knowing that every window is setup the same way (or at least very close to the same way) gives me a lot of knowledge over the structure of the program while knowing very little about each individual component.

Other pattern's I would heavily recommend -
Put all business logic in scripting modules, never on a GUI component itself.
Treat the GUI as just a means of getting parameters to feed to functions in the scripting module - the less I have to click on each component looking for business logic, and the more I can just look at the codebase, the easier debugging is.
Try to come up with naming conventions for your components. Any component that ends up feeding data to the function called on the submit button of a window should have a _out_ prefix to the name - thats what I use, you don't have to use it, but it makes finding where a certain value is coming from in a function from the GUI much easier.
Regarding templates in vision - since providing inputs and getting outputs from a template are both in the template parameters part, this is even more useful - properties that have an _in_ prefix I know must be provided to the template and then that the template will give me values in parameters that have an _out_ prefix.

“X tag corresponds to Y device”,

Stuff like this I think is best handled with proper folder structure of your tags. Everything being on the top level, even with documentation, I think would be harder to manage then well named folders and tags being in the appropriate folders. You could document the fact that you have a folder per PLC, or a folder per Machine, or per Line, or per whatever unit of "stuff" makes sense for the system you are making.

“Z tag is calculated by function A”

Stuff like this I don't think it's necessary to document tbh. If I need to know how Z Tag is calculated, I'm going to open up designer and look at it directly, I'm not going to trust a potentially out of date document.

Just my two cents. The big point I am trying to make - decide on what conventions you want to use in your project and document those.


My company is looking to do the same thing. We are reviewing options for including system documentation inside of Ignition projects. What is the best method of keeping the system documentation in the vision/perspective project?

I'll mention this recent addition to Designer in Ignition 8.1.19 as one potentially valuable resource:

Expanded the concept of 'resource documentation' to apply to all resources. Right click any resource in the project browse tree to edit the Documentation describing that resource. Named query and report resources had a unique documentation field previously. This documentation will be upgraded to the new style once the resource is opened and saved in the designer.


There are dedicated tools for documenting and managing design systems and your components. Check out Supernova's Design System Documentation tool as an example.

This is great!

While supernova is a cool tool, it's difficult to actually do anything with the documentation if you don't have a paid membership. For this reason I'm reverting back to Word, but I really like the stylization of supernova. I will be formatting my docs to match this.

Use Web Layout to get a continuous page, set up headings that are more distinctive, and enable the navigation pane. Also include styles for inline code and property name callouts - all in this word template.
Ignition Word

Use Notepad ++ with the languages feature and the NPP Export plugin to copy formatted code into the doc. (I also use a centered 8" table, hidden borders, and disabled spell check to make them look nice.)

I've created a language for Notepad++ for Ignition's Expression language. - Maybe someone (@PGriffith) at IA can get on GitHub and get a complete version into the source. The one below is a work in progress and may change as I use it and find things I missed.

N++ Expression.txt
(change extension to XML and import into Language/User Defined Language/Define your language)

1 Like

It's not really feasible to generate a "master list" of expression functions, because each module can add new ones.
If N++ supports it, you could just consider "every word character that isn't inside quotes or a curly brace" a function identifier. I think the only non-numeric literal supported is null. Also, for posterity, I'm about 85% sure expressions are case insensitive, at least the functions.

true and false, too. I thinks that's it, though.

1 Like

Of course, modules would not be included. Just the native Ignition expressions.

Is there somewhere in the Ignition folders where the functions are stored? - if so, there's also probably somewhere for the functions included within a module.

And none of those are case-sensitive at that.

No, they are pure code. A module's hook class is handed a function factory during startup and is expected to register its implementations.

But see also the JavaDoc comments here, especially for .getFunctionNames():

Note also that the factory can be retrieved from a module context, like that provided by toolkitCtx() in my Integration Toolkit:

Just a thought,

Could Ignition’s help/manual page framework be offered as a documentation tool?

It could be included as an option for every project, offering sectional topics that we create to document the project.

Might be a pipe dream as you could do the same with Markdown perspective components.

For posterity, since I went ahead and did the legwork for another post:
true, false, None, none, null, xor and like are the only keywords accepted.

Also, for fun, today I learned you can specify exponents in a double literal. So 1.0e5 is (should be) a valid expression.

1 Like