Design System Basics

A design system is not a UI kit --- it is the single source of truth that keeps your SaaS product consistent as your team and codebase scale.

Why This Matters

Without a design system, every developer and designer reinvents the wheel. Buttons look different on every page. Spacing is inconsistent. Colors drift. The product feels stitched together rather than unified.

Role	Why You Should Care
🏢 Owner	Inconsistent UI erodes trust. A design system reduces design/dev time by 30-50% once established.
💻 Dev	A component library means building features, not rebuilding buttons. Fewer bugs, faster shipping.
📋 PM	Consistent patterns let you spec features faster. "Use the standard data table" vs. describing every detail.
🎨 Designer	Frees you from pixel-pushing to focus on solving actual user problems.

The Concept (Simple)

Think of a design system like LEGO bricks. Each brick (component) is well-defined, consistent, and connects to other bricks in predictable ways. You don't redesign the brick every time --- you combine existing bricks to build new things.

A design system has three layers:

┌─────────────────────────────────────┐
│           PATTERNS                  │  ← How components combine
│  (forms, data tables, navigation)   │    into common layouts
├─────────────────────────────────────┤
│           COMPONENTS                │  ← Reusable UI elements
│  (buttons, inputs, cards, modals)   │    built from tokens
├─────────────────────────────────────┤
│           TOKENS                    │  ← Foundational values
│  (colors, spacing, typography)      │    everything inherits from
└─────────────────────────────────────┘

Change a token, and everything built on it updates. Change a component, and every pattern using it updates. That is the power.

How It Works (Detailed)

Design Tokens

Tokens are the atomic values your entire UI inherits from. They are named, not hard-coded.

Color Tokens:

Token Name	Value	Usage
--color-primary	#2563EB	Primary buttons, links, active states
--color-primary-hover	#1D4ED8	Hover state for primary elements
--color-secondary	#64748B	Secondary buttons, muted text
--color-success	#16A34A	Success messages, positive indicators
--color-warning	#D97706	Warnings, caution states
--color-danger	#DC2626	Errors, destructive actions
--color-bg-primary	#FFFFFF	Main background
--color-bg-secondary	#F8FAFC	Card backgrounds, sidebar
--color-bg-tertiary	#F1F5F9	Table row hover, input backgrounds
--color-border	#E2E8F0	Borders, dividers
--color-text-primary	#0F172A	Headings, body text
--color-text-secondary	#64748B	Captions, labels, hints

Spacing Scale:

Token                Value    Usage
──────────────────────────────────────────────
--space-1            4px      Tight internal padding
--space-2            8px      Icon-to-label gap
--space-3           12px      Small component padding
--space-4           16px      Standard component padding
--space-5           20px      Card internal padding
--space-6           24px      Section spacing
--space-8           32px      Major section breaks
--space-10          40px      Page-level padding
--space-12          48px      Large section separators
--space-16          64px      Hero/banner spacing

Typography Scale:

Token	Size	Weight	Line Height	Usage
--text-xs	12px	400	16px	Labels, captions, badges
--text-sm	14px	400	20px	Secondary text, table cells
--text-base	16px	400	24px	Body text, inputs
--text-lg	18px	500	28px	Card titles, sub-headings
--text-xl	20px	600	28px	Section headings
--text-2xl	24px	600	32px	Page titles
--text-3xl	30px	700	36px	Dashboard KPIs

Why tokens, not raw values?

BAD:  .button { background: #2563EB; }     ← Magic number. What is this?
BAD:  .card   { background: #2563EB; }     ← Same color, but is that intentional?

GOOD: .button { background: var(--color-primary); }     ← Clear intent
GOOD: .card   { background: var(--color-bg-secondary); } ← Different token, clear purpose

If you rebrand and your primary color changes from blue to purple, you update ONE token. Every button, link, and active state updates automatically.

Component Library Structure

A well-organized component library follows an atomic design hierarchy.

COMPONENT HIERARCHY
===================

PRIMITIVES (atoms)
├── Button          [primary | secondary | ghost | danger]
├── Input           [text | number | email | password]
├── Checkbox
├── Radio
├── Toggle
├── Badge           [info | success | warning | danger]
├── Avatar          [sm | md | lg | xl]
├── Icon
├── Tooltip
└── Spinner

COMPOSITES (molecules)
├── Form Field      = Label + Input + Help Text + Error
├── Search Bar      = Icon + Input + Clear Button
├── Dropdown        = Button + Menu + Menu Items
├── Breadcrumb      = Links + Separators
├── Pagination      = Buttons + Page Numbers
├── Tab Group       = Tab Items + Active Indicator
├── Alert           = Icon + Text + Dismiss Button
└── Tag Input       = Input + Badge list

PATTERNS (organisms)
├── Data Table      = Table + Pagination + Sort + Filter
├── Form            = Form Fields + Buttons + Validation
├── Modal           = Overlay + Card + Header + Footer
├── Sidebar Nav     = Nav Groups + Nav Items + Collapse
├── Command Palette = Search + Results + Keyboard Nav
├── Card Grid       = Cards + Responsive Layout
├── Settings Panel  = Sections + Form Fields + Save
└── Empty State     = Illustration + Text + CTA

Each component should define:

• [ ] Props/variants --- what configurations are available
• [ ] States --- default, hover, focus, active, disabled, loading, error
• [ ] Accessibility --- ARIA labels, keyboard navigation, focus management
• [ ] Responsive behavior --- how it adapts at breakpoints
• [ ] Usage guidelines --- when to use (and when not to)

Build vs Buy Comparison

Factor	Build Your Own	Use Existing (Radix, Headless UI, shadcn)
Time to start	3-6 months	1-2 weeks
Customization	Total control	Moderate to high (depends on library)
Maintenance	Your team owns it all	Community + your customization layer
Consistency	As good as your discipline	Strong baseline, you extend
Accessibility	Must build from scratch	Often built-in
Cost	High dev hours upfront	Low upfront, possible constraints later
Best for	Large teams (10+ devs), unique needs	Small-to-mid teams, standard SaaS patterns

Recommendation for most SaaS startups:

START HERE ──> Use headless component library (Radix, Headless UI)
                    │
                    ▼
              Add your design tokens (colors, spacing, fonts)
                    │
                    ▼
              Build a thin wrapper layer (your <Button>, your <Input>)
                    │
                    ▼
              Compose into patterns (your <DataTable>, your <FormLayout>)
                    │
                    ▼
              Document in Storybook or similar
                    │
                    ▼
              ONLY build custom primitives when existing ones
              genuinely cannot meet your needs

Documentation and Adoption

A design system nobody uses is just a side project. Adoption requires:

Documentation structure:

docs/design-system/
├── getting-started.md          ← Installation, setup
├── principles.md               ← Design philosophy
├── tokens/
│   ├── colors.md
│   ├── spacing.md
│   └── typography.md
├── components/
│   ├── button.md               ← Props, variants, examples
│   ├── input.md
│   ├── data-table.md
│   └── ...
├── patterns/
│   ├── forms.md                ← How to compose form layouts
│   ├── navigation.md
│   └── empty-states.md
└── changelog.md                ← What changed, migration guides

Adoption checklist:

• [ ] Components are installable via package manager (npm, internal registry)
• [ ] Storybook (or equivalent) is deployed and accessible to the whole team
• [ ] Each component has at least one copy-pasteable usage example
• [ ] Designers use the same token names in Figma as devs use in code
• [ ] New hires get a design system walkthrough in their first week
• [ ] There is a Slack channel or forum for questions and proposals
• [ ] Breaking changes follow semver and include migration guides

Design System Maturity Model

Not every team needs a full design system on day one. Grow it as your product grows.

MATURITY LEVELS
===============

Level 0: AD HOC
├── No shared components
├── Each page styled independently
├── Inconsistency is the norm
└── Every feature takes maximum effort

         │
         ▼

Level 1: SHARED STYLES
├── Common CSS/token file
├── Basic color and font consistency
├── Components duplicated (not shared)
└── "It looks roughly the same"

         │
         ▼

Level 2: COMPONENT LIBRARY
├── Shared, importable components
├── Documented props and variants
├── Storybook or equivalent
└── Devs use components instead of raw HTML

         │
         ▼

Level 3: DESIGN SYSTEM
├── Tokens + Components + Patterns + Docs
├── Figma library mirrors code library
├── Governance: proposal process for changes
├── Used across multiple products or surfaces
└── Dedicated owner (person or team)

         │
         ▼

Level 4: PLATFORM
├── Design system as internal product
├── Versioned, published, consumed by teams
├── Contribution model (teams submit components)
├── Analytics: usage tracking, adoption metrics
└── Only needed for large orgs (50+ devs)

Where you should be based on team size:

Team Size	Target Maturity	Timeline
1-3 devs	Level 1 (Shared Styles)	Immediately
4-8 devs	Level 2 (Component Library)	Within first quarter
9-20 devs	Level 3 (Design System)	Within 6 months
20+ devs	Level 3-4	Ongoing investment

In Practice

Example: Defining a Button Component

Here is what a well-documented button component looks like.

BUTTON COMPONENT
================

Variants:        [primary] [secondary] [ghost] [danger]
Sizes:           [sm]      [md]        [lg]
States:          default | hover | focus | active | disabled | loading

Props:
┌──────────────┬──────────┬───────────┬──────────────────────────┐
│ Prop         │ Type     │ Default   │ Description              │
├──────────────┼──────────┼───────────┼──────────────────────────┤
│ variant      │ string   │ "primary" │ Visual style             │
│ size         │ string   │ "md"      │ Button size              │
│ disabled     │ boolean  │ false     │ Prevents interaction     │
│ loading      │ boolean  │ false     │ Shows spinner, disables  │
│ leftIcon     │ ReactNode│ null      │ Icon before label        │
│ rightIcon    │ ReactNode│ null      │ Icon after label         │
│ fullWidth    │ boolean  │ false     │ Stretches to container   │
│ onClick      │ function │ -         │ Click handler            │
└──────────────┴──────────┴───────────┴──────────────────────────┘

Usage Guidelines:
- Use PRIMARY for the single most important action on the page
- Use SECONDARY for alternative actions alongside a primary
- Use GHOST for low-emphasis actions (cancel, dismiss)
- Use DANGER only for destructive/irreversible actions
- Never place two PRIMARY buttons side by side
- Always include a text label (icon-only buttons need aria-label)

Common Mistakes

Mistake	Why It Happens	Fix
Building too much too soon	Designing for hypothetical future needs	Build components as features need them
No single owner	"Everyone owns it" means nobody does	Assign a maintainer, even part-time
Design-code drift	Figma and code diverge over months	Sync reviews quarterly, automate where possible
Over-engineering tokens	Tokens for every conceivable value	Start with 80/20: the 20 tokens that cover 80% of cases
No versioning	Breaking changes surprise consumers	Use semver from day one
Ignoring accessibility	"We'll add it later"	Bake it into components from the start --- retrofitting is 10x harder

Key Takeaways

• A design system has three layers: tokens (values), components (elements), and patterns (compositions)
• Design tokens replace magic numbers with named, meaningful values that propagate changes automatically
• Start with a headless component library and add your token layer on top --- do not build from scratch unless you must
• Documentation and adoption strategy matter as much as the components themselves
• Grow your system's maturity alongside your team size --- Level 2 is the sweet spot for most early SaaS teams
• Accessibility is not optional and is dramatically cheaper to include from the start

Action Items

Role	Next Step
🏢 Owner	Assess your current maturity level using the model above. Budget time to reach the next level.
💻 Dev	Set up a shared token file (CSS variables or theme object) and migrate the 5 most common colors and spacing values.
📋 PM	Identify the 10 most-used components in your product. These are your priority for standardization.
🎨 Designer	Create a Figma component library that mirrors the token names and component variants your devs use. Align naming conventions.

---

Previous: Chapter 16 --- SaaS UX Principles | Next: Chapter 18 --- Designing for Roles