Every web project reaches a point where things start to drift. The button in the header is 12px and blue. The one in the footer is 14px and a slightly different shade of blue. The modal was built by one developer three months ago, the notification banner by someone else last week, and now nothing quite matches. New developers join and build one-off components because they cannot find the existing ones. Sprint velocity slows as the visual inconsistencies multiply.
Design systems exist to solve this problem. Teams that build them consistently ship fewer visual bugs, onboard new developers faster, and spend less time in alignment meetings about what a card component should look like. But "build a design system" can sound like a multi-quarter undertaking. It does not have to be. This guide covers how to approach it practically, starting from exactly where you are right now.
What a Design System Actually Is (and Is Not)
A design system is not a Figma file, a pattern library, or a style guide. Those things can be components of a design system, but the system itself is the combination of reusable components, the documented rules for how they behave, and the shared language that keeps designers and developers building consistently.
The three parts that make a working design system:
Design Tokens
Tokens are the foundation. They are named variables that store your visual decisions: colors, spacing scales, typography sizes, border radii, shadows. Instead of hardcoding #2563EB across 40 CSS files, you have a token named color-primary-600 that every component references. When the brand color changes, you update one value.
Tokens live in a format consumable by multiple tools. A JSON file of tokens can feed Figma variables, CSS custom properties, and a Tailwind config simultaneously. This is where design and engineering actually share a source of truth.
Reusable Components
Components are the building blocks: buttons, form inputs, cards, modals, navigation elements. Each is built once, tested, documented, and then reused. In a React or Vue codebase, this means a <Button> component with defined variants (primary, secondary, destructive) instead of custom-styled buttons scattered across dozens of files.
The goal is not to anticipate every possible variant you will ever need. It is to establish a clear pattern so that when a new variant is required, there is a documented process for adding it rather than creating another one-off.
Documentation
A design system without documentation is a repo that someone else will rebuild from scratch. Documentation does not need to be elaborate. A clear README, a component reference, and a changelog are enough to start. The important thing is that documentation lives next to the code, gets updated when components change, and is the first place anyone looks before building something new.
Photo by Negative Space on Pexels
How to Build One Without Starting Over
The most common mistake is treating "build a design system" as a separate project that happens before the real work begins. That approach stalls. The better strategy is to extract the system incrementally from what you already have.
Step 1: Audit What Exists
Before writing any code, spend an hour cataloging what your project already contains. Open every major screen or page and list every button, card, form input, and color in use. Most teams are surprised to find seven or eight slightly different button styles when they believed they had two.
This audit gives you a prioritized backlog. Start with the elements that appear on the most pages: buttons, typography, form inputs, and navigation. Fix those first. The rest follows naturally once you have established the pattern.
Step 2: Define Your Design Tokens
Before touching any component code, extract your design decisions into tokens. This can start as a simple CSS file with custom properties:
:root {
--color-primary: #2563eb;
--color-primary-dark: #1d4ed8;
--color-text-primary: #111827;
--color-text-muted: #6b7280;
--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 16px;
--spacing-lg: 24px;
--spacing-xl: 40px;
--radius-sm: 4px;
--radius-md: 8px;
--font-size-sm: 14px;
--font-size-base: 16px;
--font-size-lg: 18px;
--font-weight-normal: 400;
--font-weight-semibold: 600;
}If you are using Tailwind, define your tokens in tailwind.config.js under the theme.extend key. If you are using a component library like Radix UI or shadcn/ui, configure the theme variables they expose. The exact format matters less than the habit of centralizing these decisions so that they can be changed in one place.
Step 3: Build One Component at a Time
Pick the component that appears most frequently across your application. Rebuild it as a documented, reusable component with explicit variants. For most projects, this means starting with the primary button.
Define the variants your button actually needs - not the ones you might need someday. Document the props. Replace every hardcoded button in the codebase with the new component. Then move to the next most common element. After six to eight components, you have a working foundation.
Photo by Bibek ghosh on Pexels
Step 4: Set Up Storybook or an Equivalent
Storybook is the industry standard for component documentation and visual testing. It lets you develop components in isolation, document every variant, and run visual regression tests to catch unintended style changes between deploys.
Set it up early, even with just one or two components. A visible component catalog makes the design system feel real and gives designers a living reference when creating new screens. It also gives new developers somewhere to look before they build a one-off.
For smaller projects where Storybook's setup overhead feels heavy, a simple component demo page within the app itself works as a starting point. The goal is visibility, not a specific tool.
Step 5: Write the Rules, Not Just the Components
A design system is a decision-making framework, not just a collection of UI pieces. Write down the rules that components embody:
- "Use the
destructivebutton variant only for irreversible actions, not for general errors." - "All form labels appear above the input field, never inline or to the left."
- "Card components use a border on mobile and a drop shadow on desktop."
These rules prevent the same debates from recurring every sprint. They also make onboarding faster: a new developer reads the documentation, understands the reasoning behind the patterns, and can contribute consistently from the first week.
Common Mistakes Teams Make
Building for hypothetical scale before solving the current problem. A system built to handle 5,000 components is unnecessary when you have 50 screens. Build for what exists now, with patterns that can extend. Over-engineering early creates maintenance overhead and slows adoption.
Treating it as a design-only deliverable. Design systems that are created by designers and thrown over the wall to developers do not get adopted. Developers know where the implementation pain points are. Build the system collaboratively. The result will be more practical and more used.
Letting it drift out of sync with production. A design system that no longer reflects what is in the actual codebase is worse than no system, because it creates confusion about what the standard actually is. Assign explicit ownership. Make updating the system part of the same pull request that changes any component.
Skipping documentation on the first version. The first version does not need polished docs. It needs enough documentation that someone new can understand the patterns without asking. A short README and clearly named component props are a workable starting point.
Photo by Kampus Production on Pexels
Related Resources
These tools and references are worth bookmarking if you are building or improving a design system:
- Storybook Documentation - the standard for building component libraries with visual documentation and testing
- Style Dictionary by Amazon - a system for defining and transforming design tokens across platforms and output formats
- Radix UI Primitives - unstyled, accessible component primitives that pair well with a custom token layer
- Material Design 3 Guidelines - Google's design system documentation is one of the best references for component patterns, usage rules, and documentation structure
- Tailwind CSS Theme Configuration - useful reference for structuring a token-based design system within utility-first CSS
For teams building custom web applications where front-end architecture decisions like component libraries and design systems need to be right from the start, 137Foundry works with engineering teams on exactly this kind of setup. Their web development services include front-end architecture planning, component library implementation, and design system integration across modern React and TypeScript stacks. The 137Foundry front-end team also covers practical UI architecture topics in the blog.
For teams evaluating their broader approach to design and technical SEO alongside UI consistency, 137Foundry's design and SEO services address how visual consistency and structured markup work together for search performance.
Where to Start This Week
If you have an existing project with UI drift, the fastest starting point is the audit. Set aside one hour, open every major screen, and list every place where you have made a hardcoded visual decision that should be a variable. That list is your design system backlog, prioritized by frequency.
For new projects, establishing a token file and two or three documented components before building screens pays off within the first two to three sprints. The initial investment is real. So is the time recovered when the fifth developer joins and does not have to ask what a primary button looks like.
A design system does not need to be comprehensive to be valuable. It needs to be consistent, documented, and actually used by the team building the product.
Photo by Ofspace LLC, Culture on Pexels
