[laughter] >> Hello. >> Hello. Hello. >> Hello. >> Hi, we just did planks backstage, so I think we're we're ready.

>> Ready. >> My name is Tamara. >> And I'm Shauna. >> And we are part of Notion's design system team established officially in July 2025.

So, it wasn't that long ago that our CEO Ivan tweeted that Notion doesn't have a design system.

We're here to tell you the story of how we got from here to here. A year-long journey full of meatballs and icon factories and slapping agents on the wrist.

>> Mhm. We'll get into the weeds of not only what it took to establish a design system, but also what it took to migrate a huge code base over to use it, which is a feat that we >> liken to whipping off a tablecloth at a dinner party while everyone is still eating and also putting a new tablecloth on at the same time.

>> So, let's start with the dinner party. How did Notion make it this far without a design system?

For some, Ivan's claim was surprising. Notion has a reputation for being a design-led company with a mission to help you build beautiful tools for your life's work.

We're reminded of this every day in a very physical way, whether it's our obsession with designer chairs or the textures and colors of our shared spaces or the books that populate our shelves.

Remember Remember that last one. That one will come later.

All of this reinforces our shared intuition and the idea that good design is part of Notion's DNA. In other words, we don't need a traditional design system because pixel perfect is in our bones.

Growth happens, and pixel perfect becomes this. And this. What is the tool tip doing? And this. >> Focus ring is cut off.

>> Yikes. So, the problems of not having a design system started to compound in multiple ways. One of them, of course, being visual.

And the other being an increasingly bad developer experience. The components we had were confusing to use. How do these work together? What if is orange and is blue or true at the same time?

And what is this? This? What is this? >> Existed. >> This is real.

>> to pause and let you soak that in. >> That was real, guys. >> It was also hard to know which components to use in the first place.

This is a visualization of Notion's entire code base, or what we call the meatball.

Zooming in a bit, each of these colored dots is a bit of code, and each colored line is a bit of code depending on another bit of code.

We had no isolated home for design system components, which meant many developers making reusable components that all do the same thing with no direction on which one to use, or sometimes some direction in the form of new new new new final version five final.

>> And because everything lived in that big tangled meatball, we started to be really limited in what we could share with new projects that lived outside of the meatball.

Wanting to import one thing from the design system meant importing everything. >> It's kind of like trying to take off a tablecloth and everything on the table has been sewed to it.

>> Yikes. So, teams gave up and made their own little component libraries and mini design systems, and we had lots and lots of meatballs.

And finally, a quick bit of trivia. This particular bit of code, use styles, is how we did styling in our app. Hint, it's just plain JavaScript objects set as inline styles everywhere.

That's right. We don't really use CSS. Mhm.

Like we really don't use CSS. Did you want a pseudo class? Because you can't have one. What's a colon hover? Never heard of her.

Yikes. So, this is what we were up against when we set off to introduce a design system at Notion.

And what was really key to our understanding of how to approach this huge bit of work is knowing what a design system really is at its core, which is just a set of shared decisions.

It doesn't have to just be a component library or commandments from on high or a bunch of buttons.

It's a set of decisions that you've all agreed on over years of mess and refinement.

It's what gives your product a soul. It's what makes it feel like it's yours.

The hard part, of course, is actually making those decisions. We needed to define who is responsible for them, communicate about them, have a clear process for changing them in addition to actually acting on them.

So, we started on Oh, nope. In other words, what even is the tablecloth?

We started with our most foundational decisions, like our colors, type, icons, and more.

Our color system was the first we tackled and one of the most complicated. In addition to light mode and dark mode, we have full color palettes for user-controlled content where users can combine colors in very unpredictable ways.

That means sometimes colors should be transparent and layered so you can always see them no matter what order they're in.

If you can't see what's happening here, those two pinks should be the same pink in that white part definitely shouldn't be there.

Oops. We had multiple generations of color systems cohabitating in our codebase from hard-coded colors to the introduction of light and dark mode values to new semantic tokens that generalize the roles of text primary, text secondary, but didn't necessarily have the same roles for every color.

So, you might have blue tertiary, but not yellow tertiary. And new new semantic tokens that we landed on for our color system today, which is based on the idea that there should be the same tokens in every palette, translucent versions for every opaque color, allowing us to never worry about reaching for something that isn't there.

And allows us in Figma and code to very easily change the theme of our UI in one fell swoop.

In defining this new color system, we did have some mishaps, like trying a bold new yellow that we had to revert a bit, but in the end, we were able to come up with a system that can handle the same UI we know and love, but also support much more advanced theming in the future, including accessibility features like high contrast mode, which is now just mapping some new values.

>> Yeah. Coming to a Notion near you. >> Working on it earlier today.

>> [laughter] >> Now, on the icon side of things, we had the tremendous task of standardizing and replacing thousands of icons, many of which were duplicative, but had different opinions on stroke weights, how they were sized in their view box, or generally just who they wanted to be.

Yikes. We decided this was an opportunity to really define what Notion feels like at the atomic level. And drew our own icon set totally unique to Notion with consistent sizing system and, if I may, a distinctly elegant art style.

I say we, but this was the handy work of literally one person, the goat, Paul Verlu.

>> [laughter] >> He's right there in the second row.

>> Who drew thousands, thousands of icons in the roaring furnaces of the now infamous Figma file, Paul's icon factory.

>> [laughter] >> We just have to appreciate Paul's beautiful icons. Aren't they gorgeous? >> Amazing.

>> Wow. >> This is one person doing their life's work. >> Life's work. Yeah, I could never. Could never.

Okay, so now we had our foundations defined in Figma and it was time to bring it all into the code base. We did this by writing custom scripts that anyone could run whenever there were changes that needed to be synced.

And we're able automate things we previously did manually, ad hoc, and sometimes not at all, like optimizing SVGs, converting RGBA to OKLCH, transforming text into rems, new system-wide capabilities with a single command.

So much code being dumped into our lovely code base. Great. We like it.

Oh, no. Shauna, what about this meatball? >> What about that meatball? >> Oh, gosh. Well, now that we have these new foundations, these sources of truth, we needed to start untangling what we already had and decide what belonged in the design system and what did not.

So, we needed to make a declaration of which components we as a team owned and were responsible for, as well as a declaration of what a good reusable component actually looks like.

No is red here. And find a new home in the meatball where we could start cornering off components that we deemed worthy.

And then we have to start doing mass migrations, which we did not only for colors, icons, and type, but for layout components, buttons, selects, all those things.

And that large-scale work could easily be a candidate for letting AI just run in the background and deal with the whole thing.

And sometimes it was. For these more mechanical migrations, we'd prompt coding agents to write plans in Notion like this one.

This is a real one. And then, after sharing the plan with the team and incorporating feedback, we can send an agent off to execute and easily verify the output by type checking or unit testing or whatever.

But we found the agents struggled with more delicate work like comparing our old colors to new colors, even when we tried fancy formulas proclaiming to match human perception.

And they also struggled to detect the difference between this and this, which you think is a matter of having some numbers match, but is really about how an icon was drawn in its view box.

So, more art than science, and something that even humans might not be able to catch.

All that said, where agents struggled to do certain types of work, they were able to help us in other ways. We ended up using a combination of Claude code and Notion MCP to introspect the code base, create deprecation trackers in Notion, which gave us metadata on what we were trying to migrate, and help us strategize what to tackle first.

In the case of icons, for example, we had 529 icons that were only used once somewhere in the app, and sometimes in obscure features that we didn't know how to reproduce.

We knew we could use agents to do these low-risk replacements, but we needed an automated way to be able to visually test their work.

So, this is where a tool called Meticulous came in. We love Meticulous. This isn't sponsored. It's not sponsored.

We just love Meticulous. It's not sponsored by them. We're just going to say their name a lot.

It's fine. Meticulous runs the background of all of our developers uh local environments, and quietly records their clicks, scrolls, and user activity in general.

They then replay that activity based on our changes, and alert us on our pull requests of any visual regressions.

That means if I remove and change or change a single icon, I can view diffs in flows that I didn't trigger myself.

So, this is the before, the after, and the diff. >> Wow. >> Nice. Now, back to this table. We could then create a pipeline where Claude auto creates a PR for all of these rows, and we wait for Meticulous to check each of them.

We can review the diffs, approve differences, and then make informed decisions about whether we actually need to manually verify ourselves. That's amazing.

Wow, so cool. But Meticulous didn't always have a diff for us. It helped us cut down really significantly on the amount of manual verification we needed to do though as we were replacing hundreds and hundreds, I did say thousands of icons.

But slowly and surely all the hard work paid off. We replaced every single icon in the Notion web app. And we established one text component, one way to do layout, one proper button, and so much more.

And finally, over the course of an epic 56-part run, we finally made migrated all of our colors to use CSS variables.

Wow! We're in the future. We're in the future. >> [laughter] >> Amazing.

So, what did we learn on this grand journey? Design system migration work seems like a perfect candidate to be done with AI, so it's tempting to just throw the whole problem at it.

But then when it doesn't do it quite right, it fails, you feel like AI is the failure and you're the failure because everybody says it should have been easy.

But a lot of the work is actually a long chain of small steps that is implicit, not just how the work gets done, but which work should get done and in what order and at what level of risk.

If you make that thinking explicit, you break down those steps, tackle them independently, and you get to decide if AI takes it on, your teammate takes it on, or if you believe it's important enough for you to invest your own blood and sweat in.

If you think that you should draw a bazillion icons. And honestly, I think that the effort shows in the result.

It does. >> [sighs] >> So, we were able to get a lot done as a team, but there's only so much that we can do on our own and with our coding agents.

So, at one point we need to start teaching humans and robots some table manners.

This is a chart showing mainly the number of front-end commits being made to our codebase starting from 2022 until now.

As you can see, it's going up and up and up, and with AI and a ton of agents now in the mix, it's growing exponentially in the past year.

Meanwhile, >> [clears throat] >> excuse me, that little blue line is how many engineers we have working on the design system.

So, somewhere in there is me and Shauna and a weird half engineer that we're not going to explain, but is actually Irat who was working with us part-time, but is now full-time.

>> [laughter] >> So, as a small team, what's our loudspeaker? How can we communicate to the people sitting at the table that they should please stop using the tablecloth as a napkin?

How do we enforce the patterns that we built without slowing people down?

Well, there's a lot of ways to do that, and we realize they tend to kind of fall on this spectrum of easily ignorable to completely unavoidable.

So, at the most ignorable end of the spectrum, you have things like documentation, JSDoc comments, and announcement posts.

I love silly ones. You can tell people, you can be whimsical about it, and people might read it, or they might not.

So, you move closer to the middle. Instead of hoping that someone comes across our docs or check Slack, we can intervene via the work service they interact with every day.

So, we can add things like deprecate tags that trigger strike-throughs or add lint warnings that show little yellow squiggles and hints in the code, which slowly raise awareness that maybe what you're doing isn't officially recommended and you should go talk to someone.

Or then, you have the final category, the unavoidable things, the blockers.

These could be end-to-end tests, unit tests, but our favorite is called ratcheting. It's like mega linting. If there's a pattern we want to deprecate, we can add it to a file where all usages of the pattern are tracked and that number can only go down like a ratchet strap.

If the number of lint errors goes up, you get loud warnings and you can even block PRs from merging with our friendly bot named Doug.

This system was actually built long before the design system team was born, but it fits right into design system migration work.

Everyone's still eating: building Notion's design system | Config 2026

Scripts