JSON demystified: A field guide for designers

How understanding data structure improves your design process

JSON is one of the most valuable things you can learn if you design digital products – it powers APIs. It defines design tokens. It sits at the heart of systems thinking, dynamic UI, and every meaningful collaboration between designers and developers.

Understanding JSON gives you a clearer view of how your designs actually function in the real world. It connects what happens in your design tools with what users experience in the browser. And it gives you a shared language with the developers who are implementing your work.

Once you understand how JSON works – even just a little – you start to see your work differently. You design with more context. You collaborate more effectively. And you unlock parts of the product development process that previously seemed off-limits.

Beyond the curly braces: JSON as structured design data

JSON (JavaScript Object Notation) is essentially a way to organise information in a structured, readable format that both humans and computers can understand. Think of it as a sophisticated version of a spreadsheet or a nested list.

Here's what a simple JSON file might look like:

This might look like code, but it's really just organised data. The structure is actually quite similar to how we organise layers in Figma – parent elements containing child elements, with properties assigned to each. It's a structured way to describe things, which is basically what design is all about.

As designers, we care about JSON for three primary reasons:

1. It's how we get data from APIs – the lifeblood of modern products

2. It powers design systems and tokens – the foundation of consistent design

3. It bridges communication with developers – essential for effective collaboration

Let's dig into each of these.

The data-design connection: Where interfaces meet information

Modern interfaces are increasingly dynamic, personalised, and data-driven. When we design dashboards, product listings, or user profiles, we're creating containers for data that comes from somewhere – usually an API.

APIs typically send and receive data in JSON format, which means the content populating your carefully crafted interfaces is likely structured as JSON. Here's a real-world example of what an API might return for a user profile:

Understanding this structure helps you anticipate how real data will behave in your designs. Will some users have extremely long names? What happens if the bio is empty? Are all skills short phrases, or might some be unexpectedly long?

The reality is that APIs often return messy, incomplete data – and your designs need to accommodate these edge cases. When you understand JSON, you can ask better questions during the design process:

• "How is the data structured in the API response?"

• "What fields might be empty or missing?"

• "How long could this text potentially be?"

• "Is this always going to be a list of three items, or could it be fifty?"

These questions lead to more resilient designs that work in real-world conditions, not just with idealised content.

Tokens in translation: How JSON powers design systems

If you're working with design tokens (and you should be!), you're already working with JSON – whether you realise it or not.

Design tokens are typically stored and exchanged in JSON format because it's structured, portable, and easy to transform. Here's what a design token file might look like:

This isn't just a technical file – it's a contract, a source of truth between design and development. Understanding this format means you can:

• Contribute meaningfully to your design system

• Review token changes with confidence

• Create token structures that scale with your product

• Better integrate design decisions across platforms

Tools like Tokens Studio allow you to manage design tokens directly within Figma, using JSON structures that sync with version control systems like GitHub. These tokens can be pushed into development environments, ensuring design consistency across every touchpoint.

The real power of JSON-based tokens becomes evident when you start thinking about design decisions as data rather than just visual choices. When colour schemes, spacing systems, and typography rules become structured data points, they can be:

• Versioned and tracked over time

• Transformed for different platforms and contexts

• Updated systematically across entire product suites

• Documented and shared more effectively

This structured approach to design creates a foundation for scaling consistent experiences, even as teams and products grow.

Putting JSON to work: Practical applications for designers

Understanding JSON isn't just theoretical – it can transform your design process in practical ways:

Spotting edge cases before they become problems

When you understand the data structure your designs will work with, you can anticipate edge cases like:

• Missing data (null values)

• Extremely long content

• Lists with varying numbers of items

• Nested information that might be hard to display

This awareness helps you create more resilient designs from the start, rather than patching problems after launch.

Creating more realistic prototypes

Tools like Framer allow you to prototype with structured, JSON-based data – either from a CMS, mock API or manually imported JSON. Instead of relying on idealised placholders or lorem ipsum, you can design with realistic content that mirrors what users will actually see in the product.

This approach allows you to confront the messy reality of data early in your process, leading to more robust designs that stand up to real-world conditions. You'll quickly discover how different data patterns impact your layout – whether it's text that wraps unexpectedly, lists with varying numbers of items, or missing content that breaks your components.

The workflow typically looks something like this:

1. Get a sample JSON response from your development team

2. Import it into your prototyping tool

3. Map the JSON fields to your design elements

4. Test how your design responds to different data scenarios

This type of data-driven prototyping can help catch issues early, preventing situations where developers need to implement last-minute workarounds for design patterns that don't accommodate real data.

When designers understand data constraints from the start, they can create more flexible solutions that don't require emergency fixes (or potential rework) during implementation.

Speaking the same language as developers

When a developer says "this is what the API returns", and shares a JSON structure with you, being able to read and understand it immediately improves your collaboration. You can have informed conversations about:

• What data is available to display

• How the data is structured

• Whether the structure meets your design needs

• What changes might be needed to support your design vision

This mutual understanding prevents miscommunication and reduces back-and-forth during implementation.

I've found that when designers understand JSON, collaboration with development teams becomes remarkably smoother. Rather than having abstract conversations about how data might work, you can have concrete discussions about exactly how your designs will interact with real information. It's the difference between "I think we'll need to handle long usernames" and "I've looked at the JSON response, and we need to account for usernames up to 50 characters".

Getting started: JSON fundamentals for designers

The good news is that you don't need to become a developer to understand JSON. The basics are straightforward:

1. Key-value pairs: "name": "value" This is the fundamental building block – a property name and its value.

2. Objects: { "key1": "value1", "key2": "value2" } A collection of key-value pairs enclosed in curly braces.

3. Nested objects: "parent": { "child": "value" } Objects can contain other objects, creating hierarchy.

4. Arrays: "items": ["one", "two", "three"] Lists of values, enclosed in square brackets.

5. Types: Values can be strings ("text"), numbers (42), booleans (true/false), or null (null).

That's really it! With these basics, you can read and understand most JSON you'll encounter as a designer.

Don't worry about memorising all the syntax details – the more you interact with JSON, the more familiar it becomes. Like learning any language, exposure and practice are key. Start by simply examining JSON files and trying to follow their structure – you'll be surprised how quickly it begins to make sense.

Hands-on learning: Ways to explore JSON in your daily work

Reading about JSON is one thing, but actually working with it is where the real understanding happens. Here are a few ways to get your hands dirty with JSON without diving into code:

Inspect real API data in your browser

When using websites, you can see the actual data being transferred:

• Open your browser's developer tools (right-click → Inspect)

• Go to the Network tab

• Refresh the page and look for requests ending in .json

• Click one and examine the data structure

Hint: Switch to the Response tab if you want to see the raw JSON format – especially useful for checking syntax, null values, or deeply nested data

This gives you a behind-the-scenes look at how data powers the interfaces you use every day. I’ll sometimes do this on e-commerce sites to see how they structure their product data, or on social media to understand how their content feeds are put together.

Try it on your favourite weather app – you'll likely find a treasure trove of JSON data showing current conditions, forecasts, and maybe even location information. Look at how they handle edge cases like "no precipitation expected" versus detailed rain forecasts.

What's particularly valuable here is seeing how production systems handle missing or optional data. You might notice many API responses include fields with null values or empty arrays ([]). This reveals how real applications plan for incomplete data – something we should mirror in our designs.

Many modern websites use fetch or XHR requests that don't necessarily end in .json. Filter the Network tab by "XHR" or "Fetch" to see these requests, which often contain JSON responses. Also look for requests to endpoints containing "api" or "data" in their URLs.

Use visual tools to explore JSON

Tools like CodeBeautify's JSON Viewer make it easier to explore and understand complex JSON structures, especially if you're more visually inclined. You can:

• Paste in any raw JSON and instantly format it

• Switch between a structured tree view and raw text

• Expand and collapse nested sections to see how data is grouped

• Edit values in real time to see how changes affect the structure

It's perfect for designers who want to peek under the hood without getting overwhelmed by syntax. Whether you're reviewing design tokens, checking an API response, or just learning the ropes, tools like JSON Viewer can help demystify the data that drives your product.

These visual tools bridge the gap between technical understanding and design thinking, making it much easier to navigate complex JSON structures without getting lost in the syntax.

Dive into your team's design tokens

If your team already uses design tokens, you have a perfect learning opportunity right at your fingertips:

• Ask where your tokens are stored (often in a GitHub repository or design system documentation)

• Open the token files and examine their structure

• Notice how different token types (colours, spacing, typography) are organised

• Compare the token structure to how those same tokens appear in your design tool

What I find most interesting is seeing how different teams structure their tokens. The organisation choices reveal a lot about team priorities and technical considerations.

For example, some teams organise primarily by design property (color.brand.primary):

While others might organise by component or context first (button.color.primary.hover):

The token structure used will reflect the team’s own needs and workflow – the best structure is the one that works for your team’s specific context. Some teams benefit from simpler systems with direct values, especially when first establishing their design language.

Others might use reference tokens (color.button.primary.default):

These reference tokens create networks of relationships that support greater scalability and maintainability when design changes occur.

Pay special attention to naming conventions. Good token systems follow consistent patterns that make them predictable and easy to use.

Semantic naming makes it easy to swap colour values while maintaining meaning, while scale-based systems often provide more granular control and clearer relationships between related colours.

If you're involved in design system work, studying token structure can significantly improve how you think about design decisions. Well-structured tokens convert abstract design concepts into concrete, programmable entities. The goal isn’t to determine what’s universally "right" or "wrong", but to find what’s appropriate, scalable, and effective for your team. As Dan Mall puts it, "it doesn’t matter what you agree on, it matters that you agree". I’ve summarised some key takeaways from a workshop I took with Dan a few years back in this thread – there are plenty more insightful quotes I use in my day-to-day!

If your team doesn't use tokens yet, look at examples like Atlassian’s Design System or Adobe's Spectrum to see how established design systems structure their tokens. These examples can provide inspiration, though remember that what works for one team will need adaptation for your specific context.

Build your own mini token system

Creating your own token system is one of the best ways to understand JSON in a design context. Start small:

• Create a JSON file with basic colour tokens

• Add typography tokens

• Try nesting related tokens into logical groups

• Share it with a developer colleague and ask for feedback

Here's a simple structure to get you started, ommitting any references for easy exploration:

Copy the JSON from GitHub

As you build this, consider how your tokens might need to be used:

• How would a developer access the primary brand colour?

• Does your structure allow for easy theme switching (light/dark mode)?

• Could you add platform-specific variations without restructuring everything?

The true value of this exercise emerges when you start thinking about relationships between tokens. When design properties are expressed as structured data, you might even start to question traditional component boundaries – it thisThing a component, or just a collection of properties working together? This perspective can change how you approach both design and implementation.

These ideas connect closely to utility-first frameworks like Tailwind CSS. In Tailwind, design choices like colours, spacing, and typography are abstracted into small, atomic utility classes – all generated from a token-like configuration file. Rather than building large, monolithic components, you compose interfaces by combining these simple, consistent pieces. It's the same mental model: breaking design down into systematic, reusable parts that can be combined in countless ways. Working with JSON tokens helps reinforce this modular thinking, which has become increasingly valuable in modern interface design.

Bridging design and development through structured thinking

We often talk about systems thinking and bridging the design-development gap. Understanding JSON is a concrete step toward that goal – it helps you see beyond static mockups to the dynamic reality of modern interfaces.

When you understand JSON, you:

• Design with data reality in mind, not just idealised content

• Create more resilient interfaces that handle edge cases gracefully

• Communicate more effectively with development teams

• Contribute more meaningfully to design system evolution

• Make more informed decisions about design architecture

As the lines between design and development disciplines continue to blur, designers who understand the technical context of their work will always have an advantage. JSON is just one example of a technical skill that's becoming increasingly relevant to design work.

I've found that taking the time to learn these adjacent skills has paid dividends throughout my career – from more efficient collaboration to more effective advocacy for design decisions. Understanding JSON won't replace your core design skills, but it will help you apply them more effectively in today's complex product landscape.

If you're interested in exploring more about the intersection of design and technical implementation, check out my other articles: Simplifying APIs for designers and Designing with APIs, where I dive deeper into how technical understanding can enhance your design practice.

---

Thanks for reading! This article is also available on Medium, where I share more posts like this. If you're active there, feel free to follow me for updates.

I'd love to stay connected – join the conversation on X, or connect with me on LinkedIn to talk design, digital products, and everything in between.