20:54
Everyone's still eating: building Notion's design system | Config 2026
Figma
Overview
This video details Notion's journey in establishing and migrating to a design system. Initially, Notion's strong design intuition compensated for the lack of a formal system, but rapid growth led to inconsistencies and developer friction. The presentation outlines the process of defining foundational elements like colors and icons, migrating the codebase using custom scripts and AI agents, and implementing enforcement mechanisms to ensure adoption. It emphasizes that a design system is a set of shared decisions reflecting a product's soul, requiring continuous adaptation and care, much like the intentional imperfections found in Notion's physical spaces.
How was this?
Save this permanently with flashcards, quizzes, and AI chat
Chapters
- Notion, despite its design-led reputation, lacked a formal design system, leading to visual inconsistencies and a poor developer experience as the product grew.
- The codebase, referred to as 'the meatball,' was tangled, making it difficult to reuse components or understand their dependencies.
- Developers created numerous duplicate components, leading to confusion and a lack of clear ownership.
- Styling was primarily done with inline JavaScript objects, eschewing traditional CSS, which limited features like pseudo-classes.
Understanding the 'before' state highlights the critical problems that a design system aims to solve, such as inconsistency, inefficiency, and developer frustration.
Screenshots showing a cut-off focus ring on a tooltip and a confusing array of component options illustrate the visual and usability issues caused by the absence of a design system.
- A design system is fundamentally a set of shared decisions, not just a component library.
- Notion tackled foundational elements first, starting with a complex color system that needed to support light/dark modes, user-generated content, and future theming like high contrast.
- The icon system required standardizing thousands of existing icons and creating a new, unique set with a consistent style and sizing, largely the work of one individual.
- These foundational decisions were defined in Figma, serving as the source of truth for both design and code.
Establishing core design principles and assets is the crucial first step in building a cohesive and scalable product experience.
The creation of a new, unified icon set by a single designer, referred to as 'Paul's icon factory,' demonstrates the effort required to standardize visual elements.
- Migrating Notion's large codebase to use the new design system was likened to changing a tablecloth mid-meal.
- Custom scripts were developed to automate tasks like SVG optimization and color format conversion, syncing Figma decisions into code.
- AI coding agents were used for mechanical migrations, but struggled with more nuanced tasks like visual comparisons or understanding icon aesthetics.
- Tools like Meticulous were essential for automatically detecting visual regressions after code changes, significantly reducing manual verification.
This phase illustrates the technical challenges of integrating a design system into an existing, complex product and the innovative use of tools to manage the process.
Using Meticulous to automatically replay user interactions and detect visual differences (diffs) after an icon change, showing the 'before,' 'after,' and the 'diff' itself.
- With a small design system team and a rapidly growing codebase, enforcing adoption is critical.
- Enforcement strategies exist on a spectrum from easily ignorable (documentation) to unavoidable (blockers).
- Intermediate methods include deprecation tags and lint warnings within the developer's workflow to signal non-compliance.
- Unavoidable methods, like end-to-end tests and a 'ratcheting' system (Doug bot), actively prevent or block non-compliant code from merging.
- Even AI agents can bypass rules, necessitating making the 'right way' the 'easy way' through robust enforcement.
A design system is only effective if it's used consistently; this section explores practical methods for driving adoption and maintaining standards.
The 'Doug' bot, which acts as a mega-linter and can block Pull Requests if certain deprecated patterns are used, exemplifies an unavoidable enforcement mechanism.
- The ultimate goal of a design system is to express a product's 'heart and soul,' not just to systematize everything.
- The process requires continuous adaptation and care, balancing standardization with flexibility.
- Intentional imperfections, like a framed poster placed on the floor in an office, reflect Notion's ability to change while remaining connected.
- Even small, seemingly trivial decisions (like a 1.5-pixel border radius) are part of the ongoing process of refinement and shared ownership.
This concluding section reframes the design system not as a rigid set of rules, but as a living framework that embodies the product's identity and evolves with its users.
A Slack discussion about a one-pixel difference in checkbox border radius, ultimately resolved at 1.5 pixels, illustrates the meticulous attention to detail and the collaborative spirit in refining the design.
Key takeaways
- Rapid growth necessitates a formal design system to maintain consistency and improve developer experience.
- A design system is built upon a foundation of clearly defined and shared design decisions.
- Migrating a large codebase to a new design system is a complex process requiring automation, strategic use of AI, and robust testing tools.
- Effective design system adoption relies on a spectrum of enforcement mechanisms, from gentle nudges to hard blockers.
- The 'soul' of a product is expressed through its design system, which should allow for adaptation and continuous refinement.
- Making the correct design choices the easiest choices is key to successful adoption by both humans and AI.
- Even small, detailed decisions contribute to the overall identity and user experience of a product.
Key terms
Design SystemComponent LibraryCodebaseMeatball (codebase visualization)FigmaSemantic TokensAI Coding AgentsVisual Regression TestingMeticulous (tool)LintingRatcheting (enforcement)Doug BotPull Request (PR)
Test your understanding
- What were the primary challenges Notion faced due to the lack of a formal design system?
- How did Notion approach defining its foundational design elements like colors and icons?
- Describe the 'tablecloth' analogy and how Notion used tools and AI to manage the codebase migration.
- What is the spectrum of enforcement mechanisms for a design system, and why is it important?
- How does Notion view the relationship between its design system and the 'heart and soul' of its product?