Someone on the engineering team drops a block of JSON into the channel and says, "This is what the API sends back. Does this work for the design?". You look at it for a second, try to make sense of the brackets and quotation marks, and then move on to something that looks a little more familiar.

I did exactly this early in my career. I didn't have much context on the engineering side yet, and it took me a while to see what the question was really asking of me. You don't need to write JSON to work with a design system; you just need to be able to read it.

Once that clicked, the whole thing felt much smaller than the syntax makes it look, and most of what you're looking at is already familiar: things have names, they can contain other things, some values are optional, and some come in lists.

JSON tends to show up in a few places designers already care about: the token files a system is built from, the API responses our screens have to hold, and the pull requests engineers sometimes tag us in. Learning to read the shape gives you a way into all three. And if you've never deliberately opened one of these files, that's fine. You don't need to install anything or learn to code. You just need the file and a little patience.

What you're looking at

JSON is a way to organize information so people and machines can read the same thing, and the structure isn't as strange as it looks. Think about a Figma frame: it contains layers, and those layers can contain other layers, each with properties of their own. Parents and children, with information attached to every part. JSON is the same idea, written out as text.

You can get a long way through this without knowing much about JSON: name is a label, size is a number, and isOnline is a yes or no. image is null, which means there's deliberately nothing there yet. And layers is a list, where each item is its own small object with a name and a type: the parents-and-children nesting again, a thing holding a list of other things.

The curly braces hold an object, the square brackets hold a list, and a colon connects a name to its value. Those few structures, plus the value types already in the example (text in quotes, numbers, true or false, and null), are most of the vocabulary you need to get started.

Reading a response before it breaks your layout

A lot of the screens we design are containers for data that arrives from somewhere else, and when it arrives, it tends to look something like this:

You don't have to follow every technical detail to get something out of this. Reading it lets you ask sharper design questions, so I go looking for the things that might make the design behave differently from the mock-up. display_name is longer than the name I was given, so what happens when it wraps, and how much room does it get? bio is null, which means some people have no bio at all, and the profile card has to hold that state instead of treating it as an odd edge case. badges is an empty array, which is different again: the field exists, but there's nothing in it to show right now. And followers might be 3 for one person and 12,840 for the next.

None of this is exotic. It's the ordinary variation that comes with real data, and seeing it in the response changes the conversation. Instead of wondering whether names might get long, you can say something specific: the display name has no fixed length here, so we should decide how the component handles longer values. That's a more useful conversation, and it comes straight from the data.

The token file is the same shape

This is where I think it really starts to pay off. If your team uses design tokens, you've probably been working with JSON already, even if you've never opened the file. A primitive token can be very simple:

blue/500 maps to a single value, and on its own it doesn't tell you where that color should be used. It's an option in the system. The more interesting part is what happens when another token points at it:

Here, background/brand isn't storing a hex value of its own; it's pointing at color.blue.500. If that underlying blue changes, anything using the semantic token changes with it. If you've ever linked one spreadsheet cell to another, the idea is much the same: change the source, and the things pointing at it follow.

Nathan Curtis has a nice way of putting the two layers: primitives are the options, and semantic tokens are the decisions. You can see that distinction on the page: blue/500 is an option, and background/brand is a decision about where that option gets used. That's what I find most useful about reading tokens as data rather than treating them as something tucked away behind the system. You can see a little of the team's thinking in it.

The semantic layer, sitting between the raw values and the components, is where a lot of the meaning lives. It's also probably my favorite part 😍

Reading a token change

One of the first times this really helped me was reading a token diff. Someone had made what looked like a tiny change, and because I could follow what the reference meant, I could see it would touch far more than the component named in the pull request. The change looked something like this:

It's a small edit, but the effect is easy to follow: the brand background now points from blue/500 to blue/700, so anything using that semantic token picks up the new value. That's a different thing from changing blue/500 itself. Change the primitive and you affect every semantic token pointing at it; change the reference for background/brand and you change the decision that one semantic token is making. The difference matters because the reach is so different.

You don't have to be the person merging the pull request to see that. Reading the diff gives you another way into the review: you can look at a change and ask whether its reach matches what the person intended. That's a good skill to have.

Where the format is heading

The files themselves have been getting more explicit, too. Late in 2025 the Design Tokens Community Group published the first stable version of its format, where each token carries a $value and a $type, while references keep the familiar curly braces:

At first glance the $ looks like one more thing to learn, but the underlying structure hasn't changed at all. It's still an object holding other objects, with names, values, and references between them. The type is just being written down, so tools don't have to guess whether a value is a color, a dimension, a duration, or something else.

I've kept the color value as a plain hex here so the shape stays easy to read. The stable spec asks for a bit more: a color space and the raw components, with the hex kept as a fallback. A hex string on its own can't describe the wider color ranges modern screens can show. The structure is the same; there's more inside the value. That's a whole other post, so I'll leave it there.

There's another reason I think reading these files is becoming a useful habit. Machines read them too. As more tools and agents work directly with design systems, they lean on the same token definitions and component information the rest of us do.

And it isn't only tokens. A whole component can be described as data, in a contract that says what it is, what it accepts, and how it's meant to be used:

There's no code in there. It's a plain description a person can read and a tool can act on. Read down it and you pick up rules that usually live only in someone's head: disabled is for non-interactive states and shouldn't stand in for loading, and a button with only an icon still needs an aria-label. Someone wrote those down instead of leaving the next person to guess, which is roughly what a format like the Custom Elements Manifest sets out to standardize.

I'm not that interested in handing a system over to a machine and walking away. What I care about is what it means for the people looking after it. If a file is clear enough for a teammate to follow, it's usually clear enough for a tool too, so the naming and structure that always mattered now matter in one more place. Reading the file keeps you close to what's being passed around, rather than treating the system as a black box.

How to build the habit

The best way to get comfortable reading JSON is to spend a little time with it. You don't need a course or any JavaScript, just a few small experiments.

• Trace one token in your own system: Open your team's token file, pick a semantic token, and follow its reference back until you reach its underlying value. Start with something from a system you already know, because the connection is much easier to see when you recognize the design decision behind it.

• Watch a site talk: Right-click, choose Inspect, open the Network tab, and look at a Fetch or XHR request. The Response tab shows you the JSON coming back. A weather app or online shop is a good first look, since you'll see nulls sitting next to real values, empty lists, and strings of wildly different lengths, the same variation that trips up a layout.

• Put a messy blob in a viewer: Paste some JSON into a tree viewer such as CodeBeautify's and expand and collapse the branches. It makes the structure far easier to see than a wall of punctuation.

None of this is about memorizing the syntax. Give it a little time and you start to recognize the shape on sight.

Where that leaves you

Reading JSON won't tell you why a token got its name, and it won't make you the person who builds the pipeline that turns the file into a working product. It doesn't need to. It gives you another way of seeing the system you already design with. Read the token file and you can follow some of the decisions your team has made; read an API response and you can design for the data your interface will receive; read a diff and you can tell what a change is likely to touch. Small things on their own, but together they make the line between design and implementation a little less of a mystery.

You don't have to become an engineer for any of this. You just need enough familiarity to open the file and think, I know what I'm looking at here. If you want an easy place to start, open a token file from your own system and follow one semantic token back to its underlying value. That's it, one token is plenty for a first look.

And if you're thinking about how your system is structured, how those decisions travel through the product, or how it all holds together as it grows, that's the kind of work we're always interested in at Baseline.

Thanks for reading. 👋 💛
— Murphy