Notion had no design system until 2025: the year-long rebuild, and how they taught the agents table manners
Everyone's still eating: building Notion's design system | Config 2026 · Tamara
21 min total·Actually worth watching closely: ~7 min·3 must-watch clips
- 0:16 – 2:40Skim
A company with pixel perfect in its bones, and why it broke
Notion got this far without a design system, holding consistency together on a shared instinct for design at a company known for being design-led. Then growth happens, and pixel perfect becomes this. The cost showed up on two fronts at once: on screen, and in components that were confusing to use and hard to choose between.
Shared instinct holds up to a certain scale; past that, consistency breaking down is inevitable rather than accidental.
Mostly spoken setup, with a few screenshots of the UI going wrong dropped in. A glance at the screenshots is enough — you don't need every sentence.▶ Jump to 0:16Speaker · Tamara - 2:40 – 5:30Listen
The meatball: import one component and the whole tangle comes with it
The speaker shows a visualization of Notion's entire codebase — what they call the meatball — where each colored dot is a bit of code and each colored line is one bit depending on another. There was no isolated home for design system components, so many developers built reusable components that all do the same thing, with no direction on which to use, or direction in the form of new, new, new, new final, version 5 final. Wanting to import one thing meant importing everything — like trying to take off a tablecloth when everything on the table has been sewn to it. So teams gave up and built their own little component libraries and mini design systems.
When components have no isolated home, rebuilding the same thing isn't a discipline problem — it's structurally inevitable.
The point is the metaphor and the chain of consequences it explains; there's just one diagram on screen, so you can follow it by ear.▶ Jump to 2:40Speaker · Tamara - 5:30 – 7:17Skim
Starting with the hardest bone: color
Color came first and was one of the most complicated, since Notion carries full color palettes for user-controlled content, which means both translucent and opaque versions. Multiple generations of color systems were cohabitating in the codebase: hardcoded colors, then light and dark mode values, then semantic tokens that generalize roles like text primary and text secondary but didn't have the same roles for every color — you might have blue tertiary but not yellow tertiary. The new rule: the same tokens in every palette, and a translucent version for every opaque color.
Make every palette structurally identical and theme switching — plus accessibility themes — becomes a one-shot change.
The color matrices and before/after tables look dense but are simple in structure; scan the shape of the tables and catch that one symmetry rule.▶ Jump to 5:30Speaker · Tamara - 7:17 – 9:20Watch
Changing the tablecloth: hand-drawn icons and a one-command sync
Thousands of icons, drawn by hand by one person on a consistent sizing system. Getting the assets into the codebase ran on custom scripts that anyone could run whenever something needed syncing, automating what used to be done manually, ad hoc, and sometimes not at all: optimizing SVGs, converting RGB to OKLCH, transforming text into REMs.
Push the handmade part as far as it goes; turn the mechanical part into a single command anyone can run.
Both the wall of icons and the script run are visual — the sizing rhythm across the set, and how much a single command converts, only land if you watch.▶ Jump to 7:17Speaker · Shauna - 9:20 – 11:00Watch
What AI can do here, and what it can't
Hand the mechanical work to agents: Claude Code plus Notion MCP to introspect the codebase, deprecation trackers whose metadata sets the priorities (529 icons were used exactly once somewhere in the app), the agent writing the migration plan first, the team reviewing it and incorporating feedback, then sending the agent off to execute with type checking or unit tests to verify. But the delicate work went badly: comparing old colors to new ones failed even with fancy formulas proclaiming to match human perception, and agents couldn't detect the difference in how an icon was drawn in its viewbox.
Break the migration into what, in what order, at what risk first, then decide who does each piece; the closer the work gets to an art judgment, the more it belongs to a human.
The failed color comparisons and the icon-drawing differences have to be seen — the two versions side by side show a mismatch that simply saying it can't match colors never will.▶ Jump to 9:20Speaker · Tamara - 11:00 – 14:18Watch
Auto-created PRs plus visual regression, to drive verification cost down
Every row of the tracker gets its own PR, auto-created by Claude, and Meticulous — which replays recorded real user activity — checks each one and reports any visual regressions on the PR. You review the diffs, approve differences, and then make informed decisions about what actually needs to be verified manually. Strung together as a pipeline, this cut manual checking across thousands of icon swaps way down.
Before you let AI change code in bulk, automate the part that proves it didn't break anything.
The recording and replay, and the diff report on the PR, are demoed live on screen — the densest stretch of visual information in the talk.▶ Jump to 11:00Speaker · Tamara - 14:18 – 18:20Listen
Teaching humans and robots table manners: from ignorable to unavoidable
The ways of spreading the system line up on a spectrum from easily ignorable to completely unavoidable: documentation and announcement posts are the easiest to ignore; deprecate tags that trigger strike-throughs and lint warnings with little yellow squiggles keep nudging; end-to-end tests and PR blockers can't be dodged at all. The key insight is that coding agents don't read the docs, don't see the squiggle, and will get around the rules — lint against style props and the agent does it with a ref instead.
An agent just takes the path of least resistance, so the team's job is to make the right way the easy way; the system has to enforce itself.
The spectrum and the real example of AI routing around a rule are carried entirely by the talking; the slides are a few bullet lines, so listening beats watching.▶ Jump to 14:18Speaker · Shauna - 18:20 – 20:48Listen
Ratcheting, and the decisions that give a product its soul
The favorite tool is ratcheting: usages of a deprecated pattern can only go down, and if the number goes up you get loud warnings and a bot can block the PR from merging. The close comes back to the definition — a design system isn't a component library or a top-down spec, it's a set of decisions you've all agreed on over years of mess and refinement, and the hard part is who is responsible for them, how you communicate about them, and how you change them.
A design system is continual care, not a one-off deliverable — you want to be able to mess around with it and progressively change it into an adapted state with yourself and the people around you.
The ending is the argument tying itself off, plus a story about the team's shared spaces and a quote from Christopher Alexander; just listen for the conclusion.▶ Jump to 18:20Speaker · Shauna