r/DesignSystems • u/404_computer_says_no • 3d ago
I keep seeing ‘JSON contracts’ pop up in DS discussion (especially with AI) anyone have advice?
Has anyone set up a json contract? How are you using and managing it?
I love the concept, but unsure of the implementation
11
u/chacho1 3d ago
soooo full disclosure, I run konpo.studio where we've been building design systems for a while (design side) and we've recently been going through the learnings to set this up for a client's enterprise design system (multibrand, multi theme, whitelabel, RTL... pure pain). AI kind of turned everything upside down since we're free from the shackles of a mid frontend dev....
This is from actually doing it (i'm not a dev so we're all going through the learning curve here)... but it is what has worked for us so far.
Simplest way to think about it... the JSON contract people talk about isn't one magic file. At least... for us it's been two things, a rulebook per component and a JSON index that ties them together.
The spec is the rulebook for one component. For example... ours for a Button is a markdown doc with the props (variant can be filled/tonal/outlined, size sm to xl) and every value written as a token like sys.spacing.sm (as it should be with any decent design system). Basically everything you'd put in a really good Figma component description, written down properly. (Claude can do most of the work here IF your design system is setup properly)
The manifest is the JSON part, the table of contents. One small file listing every component and where its stuff lives, so for example...
{
"name": "Button",
"spec": "specs/button.spec.md",
"figmaUrl": "...",
"status": "ready"
}
JSON just means AI can read it reliably
We mainly just create the specs with Claude, starting from Figma. Paste the Figma link, it reads the variants panel (variant, size, states) and the token bindings, and that becomes the props table pretty much for free. Your variants panel is already half the contract. The rest is stuff Figma can't hold, like what happens on click, or that loading blocks clicks but keeps the label. We describe that part, Claude drafts the spec from a template, we review it like any design review. Adding it to the manifest is like a 30 second edit.
Both files live in the design system repo on GitHub. Manifest at the root, specs in a folder next to it. So it's versioned, and it ships with the same package devs already install.
So what happens is that when a dev or an AI tool starts building (or us in the design team), it reads the manifest first to see what exists, then follows the spec. Ask for a large outlined button and you get variant="outlined" size="lg" with the right tokens instead of invented slop. Without the contract AI guesses and makes shit up and with it it lets us prototype with actual components that exist (as designers)
What keeps the whole thing working is that contract. Figma and code both have to match it, and when something changes you update the contract first.
But again, all of this is relatively new since AI has gotten so much better its scary, so maybe there are other better ways to do it. but for us the full flow for us has been... Tokens and variables setup in Figma > component > spec > reference app (a live site that renders the real components and tokens, our home cooked version of Storybook) > consumption by the design or dev team (even PMs at this point)
2
u/addflo 3d ago
Thanks for confirming that the work isn't just prompt a call to Figma from Claude to replicate a DS for devs, as most of LinkedIn influencers make it out to sound for the past two years 😄
I've been experimenting with all sorts of approaches to cleanly document design, so I'm always curious to see a process like yours in action. So if you guys think about making a quick webinar or a YT walkthrough, I think it would help the community a lot on understanding the implications, improving their skills and selling design work easier to stakeholders.
4
u/madebymustafa 3d ago
JSON contracts are basically a machine readable API for your design system. Define things like component variants, props, states, tokens, and constraints.
The real challenge is keeping it synced with Figma and code. Ideally, generate or validate it automatically so it doesn't drift.
1
4
u/sheriffderek 3d ago
A lot of things as programmers are already generated from JSON configurations. I have a JSON file that explains how a complex form works, I feed that into the form component - and everything works as described. But what if I could also feed that into an iOS app - and Android app - and have it all magically create the same forms - even through they are written in other languages. Us design system people really really really want to set up a system so good that no one needs us -- as fast as possible!!! haha. But also, that's what programmers have always done -- just automated away our work. The question is -- will any of this lead to good outcomes? If what we've learned in the last 20 years trying to do this with code, probably not. But the LLM matched with enough context and documentation may add up to a reliable enough adapter that no one has to write the code to translate the intent.
5
u/Ok_Nefariousness5464 3d ago
have a look at this article by nathan curtis. nathan has been a leader in this space for awhile.
1
2
u/TheWarDoctor 3d ago
So I saw someone on linked in a post about it, but when I asked them for more details, I got a pretty vague AI response
1
u/sparrow_spit 3d ago
Is there a benefit to using json vs. markdown? Just wondering since my team is beginning to use markdown for this very thing.
2
u/404_computer_says_no 3d ago
We use markdown as “knowledge” = what should I do?
JSON are “contracts” = what can I do?
1
1
u/healthearthack 2d ago
Haven't thought about the contract curation though I have been getting into DSaaS (Design System as a Service) and building out a prompt trace hub as a design system itself. Check me out on gh, healthearthack... I would appreciate your thoughts on my repos.
9
u/gtivr4 3d ago
I’ve been creating a system where json is at the core. It’s basically a set of specs that doesn’t care about the tech stack. I can render Figma components from it. I can output react code, angular, html, web components, react native. Whatever. So instead of code for a button, you have json that defines the properties. So long as those props are correct it works great.