UI/UX Design Systems and Component Libraries
Imagine building a house where every carpenter made their own version of a door. Some doors are 70cm wide, some are 90cm, some open left, some open right, and none of the door handles match. The house would look chaotic and unprofessional. This is exactly what happens when design teams work without a design system.
A design system is the single source of truth that keeps every part of your product looking, feeling, and behaving consistently. This page explains what a design system is, what goes inside it, and how to build and use one effectively.
What Is a Design System?
A design system is a collection of reusable components, guidelines, and standards that teams use to build products consistently at scale. It is not just a style guide, and it is not just a component library. It combines both into one living document that both designers and developers use.
DESIGN SYSTEM OVERVIEW: A Design System Contains Three Layers: Layer 1 — DESIGN TOKENS (The raw materials) Colors, typography sizes, spacing values, border radius, shadow values, animation durations Layer 2 — COMPONENTS (The building blocks) Buttons, forms, cards, modals, tooltips, navigation bars, tables, badges, alerts — all pre-built and documented Layer 3 — PATTERNS (The assembled rooms) Login flows, empty states, error pages, onboarding steps, data tables with sorting — combinations of components that solve common UX problems Think of it like LEGO: Tokens = The plastic material that makes LEGO bricks Components = Individual LEGO bricks Patterns = Built structures made of multiple bricks
Design Tokens: The Building Blocks of Consistency
Design tokens are the smallest, most basic values in your design system. They are named values that store colors, sizes, and other properties. Instead of hardcoding a specific hex color in 200 different places, you define a token once and use the token name everywhere.
Color Tokens
COLOR TOKEN SYSTEM: Step 1 — Raw Values (Primitive tokens): blue-100: #EBF5FF blue-200: #BFDBFE blue-300: #93C5FD blue-400: #60A5FA blue-500: #3B82F6 ← Your main brand blue blue-600: #2563EB blue-700: #1D4ED8 Step 2 — Semantic Tokens (Meaning-based tokens): color-primary: blue-500 color-primary-hover: blue-600 color-primary-disabled: blue-200 color-text-default: gray-900 color-text-subtle: gray-500 color-background: white color-surface: gray-50 color-error: red-500 color-success: green-500 WHY SEMANTIC TOKENS MATTER: If you later decide to change your brand from blue to purple, you change ONE token (color-primary) and every button, link, and highlight in your product updates automatically. Without tokens, you would search and replace hundreds of specific hex values manually — and miss some.
Spacing Tokens
SPACING SCALE (Based on a 4px or 8px base unit): space-1: 4px (tight spacing — icon to label) space-2: 8px (small — between form elements) space-3: 12px space-4: 16px (default — standard padding) space-5: 20px space-6: 24px (section padding — internal) space-8: 32px space-10: 40px space-12: 48px (section padding — generous) space-16: 64px (large section gaps) space-20: 80px (hero section padding) Using a scale means all spacing in your product is harmonious — nothing looks accidentally off.
Typography Tokens
TYPOGRAPHY TOKEN EXAMPLE: Font Families: font-sans: "Inter", sans-serif font-mono: "JetBrains Mono", monospace Font Sizes: text-xs: 12px text-sm: 14px text-base: 16px ← Body text default text-lg: 18px text-xl: 20px text-2xl: 24px text-3xl: 30px text-4xl: 36px text-5xl: 48px Font Weights: weight-regular: 400 weight-medium: 500 weight-semibold: 600 weight-bold: 700 Line Heights: leading-tight: 1.25 (headings) leading-normal: 1.5 (body text) leading-relaxed: 1.75 (long-form reading)
Component Library: The Heart of a Design System
A component library is the collection of pre-built UI pieces that designers and developers use to assemble screens. Each component is designed once, tested once, and then reused everywhere. This creates speed and consistency across the entire product.
Anatomy of a Component
A well-documented component has several parts that ensure everyone uses it correctly:
COMPONENT DOCUMENTATION STRUCTURE: BUTTON COMPONENT — Documentation Example: 1. OVERVIEW What it is: An interactive element that triggers an action. When to use: For the primary action on a screen. 2. VARIANTS Primary → [ Save Changes ] Filled background Secondary → [ Save Changes ] Outlined Ghost → [ Save Changes ] No border, text only Danger → [ Delete ] Red color, destructive action 3. SIZES Large → 48px height (hero sections, landing pages) Medium → 40px height (standard usage) Small → 32px height (tables, compact UIs) 4. STATES Default | Hover | Active | Disabled | Loading 5. DO's AND DON'Ts ✓ DO: Use one primary button per screen section ✗ DON'T: Use primary style for destructive actions ✗ DON'T: Place two primary buttons side by side 6. ACCESSIBILITY Role: button Keyboard: Enter and Space activate it Disabled: aria-disabled="true"
Core Components Every Design System Needs
ESSENTIAL COMPONENT LIST: INPUTS AND FORMS: ■ Text Input ■ Textarea ■ Select / Dropdown ■ Checkbox ■ Radio Button ■ Toggle / Switch ■ Date Picker ■ File Upload ■ Search Field ■ Form Group + Label + Error BUTTONS AND ACTIONS: ■ Button (all variants and sizes) ■ Icon Button ■ Button Group ■ Link FEEDBACK AND STATUS: ■ Alert / Banner ■ Toast / Snackbar ■ Progress Bar ■ Spinner / Loading indicator ■ Badge ■ Skeleton Loader ■ Empty State ■ Error State NAVIGATION: ■ Top Navigation Bar ■ Sidebar ■ Tabs ■ Breadcrumbs ■ Pagination ■ Stepper LAYOUT: ■ Card ■ Modal / Dialog ■ Drawer ■ Tooltip ■ Popover ■ Divider ■ Avatar ■ Table ■ List ■ Tag / Chip
Atomic Design: How to Structure Your Components
Brad Frost created the Atomic Design methodology — a way of thinking about UI components in layers, from the smallest to the largest. It gives teams a shared mental model for building and organizing components.
ATOMIC DESIGN HIERARCHY: ATOMS (Smallest elements — cannot be broken down further): → Color swatch → Typography style → Icon → Button → Input field → Label MOLECULES (Groups of atoms working together): → Search bar = Input field + Icon button → Form field = Label + Input + Error message → Card header = Avatar + Name + Date ORGANISMS (Complex sections made of molecules): → Navigation bar = Logo + Nav links + Search bar + Auth button → Article card = Image + Category badge + Title + Author + CTA → Data table = Table header + Rows + Pagination TEMPLATES (Page layouts without real content): → Dashboard layout = Sidebar + Header + Main content area → Blog post layout = Nav + Hero + Body + Sidebar + Footer PAGES (Templates filled with real content): → The actual dashboard a user sees with their real data → The actual blog post with real title, author, and text VISUAL MODEL: Atom → Molecule → Organism → Template → Page (Lego brick) → (Small structure) → (Room) → (Floor plan) → (House)
Building a Design System: Step-by-Step
Step 1: Audit Your Existing Product
Before building anything new, take a screenshot of every unique button, form field, card, and navigation element in your existing product. You will almost certainly find 15 slightly different shades of blue, 8 different button sizes, and 4 different heading styles that are supposed to be the same.
DESIGN AUDIT DISCOVERY EXAMPLE: You think you have: 1 primary button style You actually find: Button A: Blue #3B82F6, 40px height, 16px padding, 6px radius Button B: Blue #2563EB, 38px height, 14px padding, 4px radius Button C: Blue #3B82F6, 44px height, 20px padding, 8px radius Button D: Navy #1E40AF, 40px height, 16px padding, 0px radius Action: Choose ONE standard. Update all four to match it.
Step 2: Establish Your Token System
Define colors, spacing, and typography first. These tokens become the DNA of every component. Without tokens defined first, components end up with hardcoded values that are impossible to update globally.
Step 3: Build the Most-Used Components First
Do not try to build every component before your team starts using the system. Start with the 10-15 components that appear most frequently in your product. A button, input field, card, and navigation bar will be used on virtually every screen.
Step 4: Document Everything
A component without documentation is not a design system — it is just a set of files. Documentation must explain what the component is for, when to use it, when not to use it, and how to use it correctly.
Step 5: Connect Design and Code
The design system must exist in two places simultaneously: in the design tool (Figma, Sketch) and in code (React components, CSS variables). When the two are in sync, designers can update the Figma component and developers update the code component, and the product stays consistent.
DESIGN TO CODE SYNC:
Figma Design System:
Component: Button/Primary/Large
Color: $color-primary
Padding: $space-4 $space-6
Border-radius: $radius-md
↓ Token names match exactly ↓
Code Component Library:
.button--primary-large {
background: var(--color-primary);
padding: var(--space-4) var(--space-6);
border-radius: var(--radius-md);
}
When color-primary changes → Both design and code update
Versioning and Governance
A design system is a living product, not a one-time project. It needs the same care and attention as any software product — including versioning, a contribution process, and governance rules.
DESIGN SYSTEM VERSIONING:
Semantic Versioning (Major.Minor.Patch):
1.0.0 → Initial release of the design system
1.0.1 → Patch: Fixed a bug (button border on Safari)
1.1.0 → Minor: Added a new component (DatePicker)
2.0.0 → Major: Breaking change (renamed color tokens,
teams must update their code)
CHANGELOG EXAMPLE:
v1.3.0 (Released June 2024)
─────────────────────────────────
✚ Added: Skeleton Loader component
✚ Added: New color-warning token (amber-500)
✏ Updated: Button now supports "loading" prop
🔧 Fixed: Dropdown z-index issue in modals
HOW TEAMS CONTRIBUTE NEW COMPONENTS:
1. Designer proposes component in shared channel
2. Team checks if existing components can solve the problem
3. If new component is needed, it is designed and reviewed
4. Developer builds the code version
5. Both are documented and added to the system
6. Version is bumped and changelog is updated
Popular Open Source Design Systems
You do not have to build a design system from scratch. Many large companies have published their design systems openly, and you can use them as a starting point or as a reference for best practices.
NOTABLE DESIGN SYSTEMS: Google Material Design (material.io) → Used across all Google products → Components for web, Android, iOS, Flutter → Very detailed documentation and accessibility guidance Apple Human Interface Guidelines (HIG) → Design standards for iOS, macOS, watchOS, tvOS → Essential reading for any iOS app designer IBM Carbon Design System (carbondesignsystem.com) → Designed for enterprise and data-heavy applications → Open source React, Angular, Vue, and Web Components → Very strong accessibility documentation Shopify Polaris → Designed specifically for e-commerce admin interfaces → React components and clear content guidelines → Strong UX writing (microcopy) guidance Atlassian Design System (atlassian.design) → Used in Jira, Confluence, Trello → Strong patterns for complex productivity tools Microsoft Fluent Design → Used across Windows, Office, and Microsoft apps → Very detailed motion and depth guidelines
Design System Pitfalls to Avoid
COMMON DESIGN SYSTEM MISTAKES:
MISTAKE 1: Building in isolation
Problem: Design system team builds components no one uses.
Fix: Involve product teams early. Ask what THEY need most.
MISTAKE 2: Never updating it
Problem: System becomes stale. Teams stop trusting it.
They build their own one-off components instead.
Fix: Assign at least one person to own and maintain it.
Establish a clear process for updates.
MISTAKE 3: Designing without considering code
Problem: Designer creates components that are beautiful
but impossible to build efficiently in code.
Fix: Include developers in component design reviews
from the very beginning.
MISTAKE 4: No documentation
Problem: Team builds components but does not write how
to use them. New teammates use them wrong.
Fix: Write documentation as you build, not after.
MISTAKE 5: Too rigid
Problem: System has a component for everything, but
they do not allow any customization.
Product teams work around the system.
Fix: Build in flexibility. Document when customization
is acceptable vs when the standard must be followed.
Key Points
- A design system has three layers: design tokens (raw values), components (building blocks), and patterns (assembled solutions).
- Design tokens store named values for colors, spacing, and typography — change a token once and every component updates automatically.
- Semantic color tokens give meaning to colors (color-primary, color-error) rather than naming them by their appearance (blue-500, red-500).
- Atomic Design organizes components from atoms to molecules to organisms to templates to pages.
- Every component needs documentation: when to use it, variants, states, dos and don'ts, and accessibility requirements.
- Start with a design audit to find all the inconsistencies in your existing product before building the system.
- The design system must live in both the design tool and in code — with matching token names to stay in sync.
- Use semantic versioning (Major.Minor.Patch) and publish a changelog when the system is updated.
- Assign ownership. A design system without an owner becomes outdated and teams stop using it.