Outlining a JSON structure to centralize data for your Design System

How to use JSON files to create data for designs in Sketch

Many times we don’t put enough attention to the data we use in our designs. We use dummy text because from a design perspective the focus is usually on the visual UI rather than the content, but if we see the UI from an user perspective, actually is the content the most important element, being the interface just the context to show it. So, how can we improve our workflow to guarantee the quality of the content we are using for designing?

Regarding the organization of data, we need to learn more from Developing and seed data, which is used in the product as a replacement of real data the users are going to generate later. This seed data usually is generated inside a .yml file. We can’t use .yml files in our Design Systems given there aren’t plugins that can import this information format — AFAIK. However, we can use JSON files. Through a small exercise I’m going to show and propose a data structure and a workflow that can allows you to manage data in a proper way.

What do you need?

For accomplishing this, I’m going to use the following tools:

• Sketch : As the main tool where the product’s design lives.
• Craft by InVision : The plugin which allow us to use JSON files.
• GitHub : To store and organize all our JSON files.

In order to show this proposed flow, I’m designing a simple product composed by 3 environments; A login, a table and a confirmation modal. The user flow is a simple access to a database, which includes a confirmation when the user tries to delete an entry. The flow looks like this:

Now, translating this user flow to UI, those 3 environment look like this. Notice how I’m not using any data in the texts, each description and value in the database has a placeholder which describes their function:

Login screen, the user inputs their info and enters to the database

Once the user is logged in, it has access to this table with the option to remove each entry

If the user tries to remove an entry, it appears a confirmation modal

It’s also important to be sure that our symbol structure is coherent and well organized. Is not directly related to the success of this exercise, but it’s a good practice. This is the structure in this case:

Hierarchy of symbols. A table is composed by cell symbols, and these include the values

Creating the data structure

The first step is to identify the nature and function of each value we are using in the interface. From a high level, there are 2 type of values: Reusable and Contextual data.

• Reusable data is the one related to elements which are spread among the product. In this case for example: the user’s information. Each user has information as properties, and these properties are going to live in both, the table and the login interface (as access information). In bigger products this information is even more distributed and reused.
• Contextual data is the one that is used for a specific context or environment. In this case, we have an introductory text in the login, explanatory text in the table and a warning text in the modal. Neither of this information is used in other contexts, giving us the opportunity to organize it based on each environment rather than their function.

In order to create the necessary files for our data structure, let’s start a new project in our local and a new repository in GitHub where we are going to upload our JSON files. Why do we need to have this information in a repository? Because this give us the opportunity to work collaboratively in case this information requires to be reviewed and improved by other people.

This is how the structure looks in GitHub (the files are empty yet):

Now we can work in each JSON file. Let’s get started with the users.json. Here we are going to include the information we need per each user, considering our table in the database environment: Username, role, location and joined date. We enter this information creating an ID per each user.

users.json file with 5 users’ data

Then the context.json, in this case we organize the information based on the environment where these descriptions are going to live:

context.json file with texts for the different environments

❗️ Note: I’m just using one file for the contextual data, probably bigger products need more files for a better organization and accessibility.

Inserting data in Sketch

Finally, once we have our data in GitHub, we get each JSON file’s URL — pressing at the “Raw” option. Craft has a functionality that can allows us to pull data from a JSON file, so we paste the URL there and we can see our structure in Sketch, ready to be used:

Pasting the JSON URL in Sketch using Craft

Once we got our data in Sketch, we can go to the table symbol — where we are going to use this data — and select the symbol we want to use. When we select a value from the JSON file, Sketch will ask us what is the value we want to connect with. This is the reason why we need to use placeholders describing the function of the value, otherwise in bigger designs will be really confusing to connect the information.

Adding the data from the JSON to the values in Sketch

I did the same with all the elements of the design. Once the process has been completed, the environments look like this

Login including the description from the context.json file

Database environment with description from context.json and user’s information from users.json

Finally, confirmation modal with the description from context.json file

Conclusions

The big question now. Why is this worth the effort? There are some reasons you should consider to include it in your workflow.

• Opportunity to work collaboratively. There are pieces of information we use in our design which requires constant revision. This revision is hard to do through prototypes or just adding comments on the screens we deliver. So, this centralized structure opens the opportunity to work in data in a separate way, using git as a way to update, mantain and review the data by more than one person.
• The perks of using real data. The problem with dummy text is that doesn’t allow us to test the design properly. Using real data — or at least realistic data— we can be sure that our design is not going to break when the users start to use their data, which in most cases, can be radically different. For example, if for our design we use as test a “user@mail.com” in a box that only allows 15 characters, but then the user uses “alexander.shevchenko@institution.org”, the design is already broken.
• Control over the voice and tone. As I mentioned at the beginning, content is the core of many products. Being this element as important as it is, the construction of this content also requires to fit into a common voice a tone, which will define the communication that the product it’s going to have with the user. Having control over this voice and tone in texts that exist in many screens is a difficult task, there is where centralized data can help us a lot.

As a last note, even when Sketch and Craft are making great advances towards the creation of more versatile and scalable systems, there are still constraints. For example, Craft doesn’t recognize some symbols like “@”. Also, it doesn’t allow to edit data in 2-level nested symbols. These are not necessarily blockers, but we have to consider them for our Design System structure.

If you want to experiment more with JSON data and Sketch, in this repo you will find the structure used in this exercise. Additionally, here the direct access to the users.json and context.json.