Building a Shopify Design System: Components, Tokens & Documentation

Why Shopify Stores Need Design Systems (And Why Most Don't Have Them)

You're managing a Shopify store. Design team builds a homepage. Dev team codes it. Merchant requests a change to buttons. Designer updates Figma. Dev team isn't notified. Buttons look different across pages. This is chaos.

A design system stops the chaos. It's a shared language between design and engineering. One source of truth for how buttons, forms, cards, and layouts work. Designers build in the system. Devs implement using the system. Changes propagate everywhere.

Here's the problem: design systems are expensive to build. They require 4-6 weeks of engineering time, ongoing maintenance, and a commitment to enforce them. Most Shopify stores skip it.

Most successful stores (especially over $2M revenue) have one, either formally or informally. The difference between the two: formal systems (documented, enforced) prevent technical debt. Informal ones (loose agreements between design and dev) lead to inconsistency and rework.

This article shows you how to build one without spending 6 months. A minimum viable design system.

What a Design System Actually Is

Design systems are often confused with design tooling. They're not the same.

• Design system: A collection of reusable components, patterns, and guidelines that define how your product looks and works
• Design tool: Software where you build the system (Figma, Sketch, Adobe XD)
• Component library: Code implementation of the system (React components, Web components, CSS classes)

A complete system has all three. But you can start with just one tool (Figma) and one deliverable (a component library) and expand later.

The Three Layers of a Shopify Design System

Layer 1: Design tokens

Design tokens are the atomic units of design. Colors, spacing, typography, shadows. Instead of saying "blue," you say "primary-500." Instead of "16px margin," you say "spacing-2."

Example token library:

Colors:
  primary-50: #F0F9FF
  primary-500: #0EA5E9
  primary-900: #0C2340

  neutral-50: #FAFAFA
  neutral-900: #111111

Spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px

Typography:
  h1: 32px, 700 weight, -0.5px letter-spacing
  h2: 24px, 700 weight, -0.25px letter-spacing
  body: 16px, 400 weight, 0px letter-spacing

Shadows:
  sm: 0 1px 2px rgba(0,0,0,0.05)
  md: 0 4px 6px rgba(0,0,0,0.1)
  lg: 0 10px 15px rgba(0,0,0,0.1)

Tokens live in a JSON file that both designers and developers can access. When you need to change the primary color, you update the token once. It propagates everywhere.

Layer 2: Components

Components are reusable UI elements built from tokens. Button, card, form input, navigation.

A button component includes: - Visual styles (background color, padding, typography) - States (default, hover, active, disabled, loading) - Variations (primary, secondary, ghost) - Accessibility (ARIA labels, keyboard support) - Usage guidelines (when to use each variant)

Components are defined in Figma (for designers) and code (React, Liquid, Vue—depending on your implementation).

Layer 3: Documentation

Documentation explains: - When to use each component - How to use it (code examples) - Accessibility considerations - Design rationale

Live documentation (a website showing all components in action) is better than a PDF. Tools like Storybook make this automatic.

Implementing a Design System on Shopify: Two Approaches

Approach 1: Theme-based system (Shopify theme using CSS + Liquid)

You're building your system inside your Shopify theme. Components are Liquid snippets. Styles are CSS. Tokens are CSS variables.

Pros: - Everything lives in one place (Shopify theme) - No integration needed - Easy to deploy (push to Shopify and it's live)

Cons: - Limited to Liquid and CSS - Can't use advanced JS frameworks - Harder to maintain as complexity grows - Tied to Shopify's theme structure

Best for: Stores using Shopify's theme builder or simple custom themes. Brands under $2M revenue with straightforward design needs.

Approach 2: Headless system (React components + Hydrogen)

You're building components in React and using them in a Hydrogen storefront. Components are JS/React. Styles are CSS-in-JS or Tailwind. Tokens are JS objects.

Pros: - More powerful (access to full JS capabilities) - Reusable across projects - Can target multiple platforms (web, mobile app) - Better tooling (Storybook, TypeScript, testing libraries)

Cons: - More complex to set up - Requires engineering resources - Separate from Shopify admin - Maintenance burden higher

Best for: Brands building custom storefronts (Hydrogen, Next.js) or planning to go omnichannel (native mobile app, iOS/Android).

Building Your Design System in 4 Weeks (Minimal Approach)

Week 1: Define tokens

1. Create a Figma file with all colors, spacing, typography, shadows used across your store
2. Export tokens as JSON (tools like Tokens Studio make this automatic)
3. Share JSON with engineering team
4. Test tokens in your codebase (CSS variables or JS objects, depending on your stack)

Week 2: Document core components

Choose your top 5-10 components based on usage frequency: - Button - Input field - Card - Navigation - Modal - Badge - Toast notification

For each component, document: - Visual spec (size, color, padding) - Variants (primary, secondary, disabled) - Accessibility (ARIA, keyboard, screen reader) - Code example

Use a simple Google Doc or Notion to start. You can migrate to Storybook later.

Week 3: Build component library

Implement components in code using your tokens. If you're using a theme:

<!-- components/button.liquid -->
{% liquid
  assign variant = variant | default: 'primary'
  assign size = size | default: 'md'
%}

<button class="btn btn--{{ variant }} btn--{{ size }}">
  {{ label }}
</button>

<style>
  .btn {
    padding: var(--spacing-md);
    border-radius: var(--radius-md);
    font-size: var(--font-body);
    font-weight: 600;
  }

  .btn--primary {
    background-color: var(--color-primary-500);
    color: white;
  }

  .btn--primary:hover {
    background-color: var(--color-primary-600);
  }

  .btn--md {
    padding: var(--spacing-md) var(--spacing-lg);
  }
</style>

Week 4: Enforce and iterate

1. Checklist for PRs: "Does this use design system components? Are tokens used instead of hardcoded values?"
2. Find inconsistencies in your live site and document them
3. Plan phase 2 components based on actual usage

Tooling: What to Use at Each Stage

Stage	Figma	Code Documentation	Component Implementation
Month 1-2 (MVP)	Figma (tokens + components)	Google Doc or Notion	CSS + Liquid snippets
Month 3-6 (Growth)	Figma + Tokens Studio	Storybook or Zeroheight	React or Liquid with testing
Month 6+ (Scale)	Figma + Tokens Studio + design tokens API	Storybook + auto-generated docs	React/TypeScript + Chromatic

Tools mentioned:

• Tokens Studio ($10/month): Manage design tokens in Figma, export as JSON
• Storybook (free/open-source): Document and test components interactively
• Zeroheight ($250+/month): Beautiful design system documentation
• Chromatic (free-$99/month): Automated visual testing for components

The Design System Governance: Preventing Chaos

A design system without governance is just a collection of components. You need rules.

Rule 1: One source of truth - Figma is the source of truth for design - Component library (code) is the source of truth for implementation - Documentation should reference both

Rule 2: Approval workflow - Designer reviews component spec in Figma - Developer implements in code - Designer reviews implementation - PR is merged only if both agree

Rule 3: No exceptions - Every component must use tokens - Every page must use components - Hardcoded colors, spacing, fonts are not allowed

Rule 4: Version control - When you make breaking changes, bump the version - Document migration path for old components - Support two major versions simultaneously

Design Tokens for Personalization and Theming

One powerful use of tokens: support multiple themes (dark mode, high contrast mode, brand variants).

Example:

{
  "light": {
    "color-primary": "#0EA5E9",
    "color-background": "#FFFFFF",
    "color-text": "#111111"
  },
  "dark": {
    "color-primary": "#38BDF8",
    "color-background": "#111111",
    "color-text": "#FFFFFF"
  },
  "high-contrast": {
    "color-primary": "#0000EE",
    "color-background": "#FFFFFF",
    "color-text": "#000000"
  }
}

Your components use the tokens, not the theme-specific values. When the user switches themes, tokens update, and all components reflect the change instantly.

This is powerful for accessibility (high contrast mode) and user preference (dark mode).

Common Pitfalls (And How to Avoid Them)

Pitfall 1: Too many tokens - Don't create a token for every variation. Use a subset. - If you have 10 different blue shades, something's wrong. You probably need 3-4. - Fewer tokens = easier to maintain

Pitfall 2: Documentation that's never updated - Documentation rots if it's not automated. Use Storybook, not PDFs. - Storybook is live code. It's always current.

Pitfall 3: Components that don't work across contexts - Test components in different contexts (light/dark, mobile/desktop, different content lengths). - A button component that works on your homepage might break on product pages.

Pitfall 4: Design system as legacy project - Many teams build a design system and then move on. - Design systems require ongoing maintenance (1 engineer, 25% time). - Budget for this or it dies.

From Design System to Competitive Advantage

A mature design system lets you:

1. Move faster: New pages built in days, not weeks (you're using existing components)
2. Maintain consistency: Every customer sees the same experience
3. Reduce bugs: Tested components are more reliable than bespoke implementations
4. Onboard team members faster: New designers/devs learn the system, not recreating wheels
5. Experiment faster: A/B testing new buttons or forms is trivial (change one component)

At $5M+ revenue, a design system is table stakes. At $1M-$5M, it's a competitive advantage. Below $1M, it's a nice-to-have.

FAQ

Q: Can Shopify's theme builder components serve as a design system? A: Partially. Shopify's theme builder has built-in components (product card, testimonial, etc.). But they're not customizable enough for most brands. Better to build your own.

Q: How do we transition from no system to a system? A: Painful but necessary. Audit your current site. Document all components (even if inconsistent). Create a "new system" version of each. Migrate pages one at a time. Phase 1: 4-6 weeks. Full migration: 3 months.

Q: What if our designers and devs can't agree on the design system? A: Common problem. The solution: a shared tool (Figma + Tokens Studio). Both see the same truth. Conflicts get resolved by comparing to Figma source.

Q: Is dark mode support worth building into our design system? A: Yes, but only if your audience needs it. B2B and professional products: yes. Fashion/lifestyle: probably not. If 5% of visitors are using dark mode, it's worth it.

Q: How do we measure the ROI of a design system? A: Track: time to launch new pages, number of bugs in production, engineering time spent on custom styling. A good system cuts page launch time by 40% and styling bugs by 60%.

Q: Should we open-source our design system? A: Only if you have 1 FTE dedicated to maintaining it and supporting external contributions. Most companies should not do this until they reach $50M+ scale.

CTA

A design system scales your design team's impact. But it requires engineering investment and ongoing maintenance.

Ready to build your first design system? Tenten has helped Shopify Plus merchants define tokens, build component libraries, and migrate existing sites to design systems. We work with your designers and engineers to build a system that fits your stage. Contact us to discuss your design system strategy.

Or explore our guide to Shopify theme customization and the Storefront API to understand the technical foundations of custom Shopify experiences.

---

Editorial Note: Many brands build design systems and then abandon them. The success rate is low because people underestimate the maintenance burden. A design system is not a project. It's a product that your engineering and design teams maintain forever. Commit only if you have the resources.

---

Frequently Asked Questions