Design systems as knowledge graphs | Chase McCoy About the editor<br>Chase is a design engineer and blogger currently working on design systems for Claude at Anthropic.
Featured<br>Building a private & personal cloud computer<br>We could all be archivists<br>Boku no Natsuyasumi<br>How blogs shaped the web<br>Design systems as knowledge graphs
Elsewhere<br>GitHub<br>Instagram<br>Mastodon<br>Bluesky<br>Spotify<br>Twitter
Now playing
Archives<br>2026<br>2025<br>2024<br>2023<br>2022<br>2021<br>2020<br>2019<br>2018<br>2017<br>2016<br>2013
Linked list<br>Things that caught my eye on the web, updated sporadically.
Blogroll<br>Alexander Obenauer<br>Amy Hupe<br>anhvn<br>Audacious Fox<br>Chen Hui Jing<br>Chris Coyier<br>Frank Chimero<br>Interconnected<br>James Little<br>Jim Nielsen<br>Jonnie Hallman<br>Jules Forrest<br>Justin Duke<br>Kicks Condor<br>Maggie Appleton<br>maya.land<br>Mu-An Chiou<br>Piper Haywood<br>pketh<br>Robin Rendle<br>Robin Sloan<br>Soroush Khanlou<br>thesephist<br>Tom Critchlow<br>Zach Leatherman
Typeset in Source Serif and Brunswick Grotesque. Built with Astro and hosted on Netlify. Thanks for stopping by ♥
Lately I’ve been thinking a lot about design systems documentation, and more importantly how we scale knowledge and best practices across a large team. Looking at most system documentation (including for the design systems I’ve built), you’ll see something that heavily resembles the documentation you might find for a standalone product or software library.
We’re used to writing and reading long, linear documents full of content structured from top-to-bottom. But I think that content is actually far more useful in small chunks that are individually addressable.
Design systems can offer products, and some of those may be software libraries, but a design system is not only a product or a library. Good systems are hyperobjects that capture decisions, language, patterns, history, and all of the things that make and have made your organization’s design what it is. They resemble knowledge graphs far more than products, and I’d like to see some of the emerging patterns around software for managing a knowledge graph applied to design systems.
What is a knowledge graph? The best formal definition I found was this one:
The knowledge graph represents a collection of interlinked descriptions of entities – objects, events or concepts. Knowledge graphs put data in context via linking and semantic metadata and this way provide a framework for data integration, unification, analytics and sharing.
The best way to think about how a knowledge graph can be represented in software form is to look at tools like Roam Research, Obsidian, and to some degree (with their new synced blocks feature) Notion. There are also individuals experimenting with these concepts, such as Andy Matuschak’s personal notes
These tools pull from a long history of ideas that can tie their origins to the creation of hypertext itself. But the original vision of hypertext is not really like the hypertext of today’s web. Pioneers like Ted Nelson imagined a hypertext where links aren’t only one way, and where information can be referenced and embedded across many contexts. (By the way, Devon Zuegel did a wonderful interview with Ted Nelson for Notion.)
A diagram from Ted Nelson's original paper on hypertext, courtesy of the Museum of Media History<br>Unfortunately, we didn’t get Mr. Nelson’s vision for hypertext with the web. Many of the reasons documentation on the web today is so limited is due to the limitations of the medium itself. Despite that, there are tools and sites popping up that give us a look at some of these ideas implemented on the web.
Knowledge graph systems that make specific ideas addressable unlock some interesting ideas that I think could be applied to documentation (not only, but especially, for design systems).
Transclusion
When content is stored in its minimum viable format and can be referenced uniquely, it becomes possible to “transclude” or embed the content directly in whatever context you’d like.
Imagine all of the pieces of a design system that could individually encoded:
Styles
Tokens
Components
Patterns
Guidelines
Frameworks
Properties
Content
Icons
Illustrations
Wherever these concepts are mentioned in our document, they could instead be transcluded. This means that future updates to that information are propagated through our documentation rather than documents slowly becoming out of sync with one another.
Not to mention that linking these concepts rather than simply re-iterating exposes the structure and relationships in our system to the end user—by seeing how things relate, they get better at navigating the system in the future.
I’ve tried to integrate some of these concepts into design system documentation before, and I’ve seen other systems experiment with it as well. When I was working on the Seeds design system, we built embeddable tags for some of the concepts in our system like design tokens, components, and even specific props on components. When the user hovers over the tokens, they can learn get more information about...