The Anatomy of a Winning App Design System

What a Production Design System Contains

Design systems are one of the most talked-about and least understood concepts in startup product development. Most articles describe what a mature design system looks like at Atlassian or Shopify. Few describe what a realistic, useful design system looks like for a team of 3–10 working on a startup product.

Here is the structure that actually works.

Layer 1: Design Tokens

Tokens are the source of truth for every visual decision. They are named variables that store values for: color, typography, spacing, shadow, border-radius, and motion.

Color tokens (example):

• color-brand: #D83222
• color-brand-light: #FEF1EE
• color-text-primary: #0a0a0a
• color-text-secondary: rgba(10,10,10,0.7)
• color-background: #ffffff
• color-border: rgba(0,0,0,0.1)

Tokens should have both a Figma equivalent (variables) and a code equivalent (CSS custom properties or Tailwind config). When both reference the same named value, design and code stay in sync automatically.

Typography tokens:

• Scale: xs (11px), sm (13px), base (15px), lg (18px), xl (22px), 2xl (28px), 3xl (36px), display-sm (42px), display (56px)
• Weights: regular (400), medium (500), semibold (600), bold (700)
• Line heights: tight (1.15), snug (1.3), normal (1.5), relaxed (1.65)

Spacing tokens:

• A 4px base scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128

Layer 2: Foundation Components

Foundation components are the smallest reusable UI elements, built directly from tokens.

• Button (primary, secondary, ghost, destructive, each in default, hover, active, disabled, loading states)
• Input (text, email, password, with label, error, and disabled states)
• Checkbox and Radio
• Badge and Tag
• Avatar
• Skeleton (loading placeholder)
• Divider

These components have no business logic. They are pure UI primitives. They live in your component library and are composed by every other screen.

Layer 3: Pattern Components

Pattern components compose foundation components into reusable patterns.

• Form (label + input + error message)
• Dialog / Modal
• Toast / Notification
• Dropdown Menu
• Navigation (Nav bar, Sidebar, Breadcrumb)
• Data Table
• Card
• Empty State

Pattern components handle layout and composition. They still carry no business logic.

Layer 4: Feature Components

Feature components compose pattern components and carry business logic specific to your product. These are not part of the shared design system. They live in your application code and are documented separately.

Examples: InvoiceCard, UserProfileHeader, TransactionRow.

Documentation That Gets Used

Design system documentation only gets used if it answers questions engineers and designers actually ask. The most-used docs are:

• "When do I use X vs Y?" (e.g., button variants)
• "What are the error states for this component?"
• "What does this look like on mobile?"

Skip the philosophy. Write the usage rules and the edge cases.

Governance: How Changes Get Made

A design system without a governance process drifts. Changes need a lightweight process: propose, review, merge, communicate. For a startup team, this can be as simple as:

1. Open a GitHub issue or Figma comment describing the proposed change
2. One design + one engineering sign-off before the change is made
3. A short changelog entry that gets communicated to the team

---

FAQ

Q: Do I need a design system for my MVP?

Not a full design system. You need tokens (colors, type, spacing) and 5–10 foundation components. That's enough to ship consistently.

Q: Should my design system live in Figma or in code?

Both. The Figma library is the design source of truth. The code library (React components) is the production source of truth. Use tokens to keep them in sync.

Q: How do I handle dark mode in a design system?

Use semantic color tokens rather than raw values. color-text-primary is #0a0a0a in light mode and #ffffff in dark mode. Never hardcode #0a0a0a in a component. Always use the semantic token.

Q: What's the most common design system mistake startups make?

Building too much too early. A 200-component library for a 3-screen MVP is over-engineering. Start with the minimum viable component set and grow it with your product.