Design-Driven Block Systems: Complete 7-Part Guide

From Figma mockup to production Payload CMS integration—without refactoring

Welcome to a systematic approach for building block systems and collections where design drives your data structure rather than the other way around. Whether you're new to your project or extending it with new blocks, this guide series will walk you through every scenario.

Why This Matters

Most developers build components like this:

Guess at a data structure
Build the component
Show the designer
Discover the data structure doesn't match
Refactor everything (repeat steps 1-4)

Design-driven development flips the process. You look at Figma, extract the data needs directly, build components that match from day one, and when Payload CMS integration comes, your types already align perfectly.

The result? Zero refactoring. Zero mismatches. Total confidence.

The Guide Series

This is a 7-part journey that builds on itself. Each guide is self-contained, but they connect logically:

1. Design-Driven Development ← Start Here

Philosophy & Mindset | 5 min read

Understand why design comes first. Learn the 5 concrete benefits of this approach. See why Payload integration becomes trivial when you build this way.

Key question answered: Why should I care about design-driven development?

2. Adding Blocks from Payload

Using Existing Types | 10 min read

Payload already has Hero, Services, FeaturedProjects, and other block types. This guide shows you how to:

Use Payload types directly in components
Build components without creating custom types
Create example data for those blocks
Integrate blocks into pages

Best for: When you're working with existing Payload block definitions.

Key question answered: How do I use a block that Payload already defined?

3. Creating Custom Block Types

Building From Scratch | 15 min read

Building a new block type from Figma design to component to page integration. This guide walks through:

Analyzing Figma design to extract data fields
Defining your custom block type
Building the component
Creating example data
Updating BlockRenderer
Adding to pages

Best for: When Payload doesn't have the block you need yet.

Real example: Building a "Featured Industries" block from design mockup to rendered page.

Key question answered: How do I build a completely new block?

4. Creating Collections

Data Entities & Reusable Data | 10 min read

Collections are reusable data entities (Industry, Client, Product, Team Member) that appear across multiple blocks. This guide shows:

Defining collection types from design
Creating example collections
Using collections in multiple blocks
Structure for Payload CMS integration

Best for: When you have data that multiple blocks need to reference.

Real example: Industry collection used by FeaturedIndustries block, IndustryGrid block, and other places.

Key question answered: How do I create reusable data that multiple blocks share?

5. Icons, Components & Reusable Types

Consistency & Best Practices | 12 min read

Three critical practices ensure consistency across your entire system:

Lucide React for icons - Icon naming conventions, usage patterns
shadcn/ui for components - When to use shadcn/ui, what not to build custom
Global CTA type - Using the same CTA structure everywhere

Best for: Understanding standards and consistency practices.

Key question answered: How do I keep all blocks consistent and maintainable?

6. Quick Reference: Templates & Checklists

Copy-Paste Resources | Reference

Tired of remembering syntax? This section contains:

Type definition template - Copy-paste structure for new types
Component template - Component boilerplate
Example data template - How to structure examples
Page data template - Adding blocks to pages
BlockRenderer addition template - How to add block routing
Pre-flight checklists - Don't forget anything

Best for: When you're actively building and need quick templates.

Key question answered: What's the exact format I should use for [type/component/data]?

7. Migration to Payload CMS

From Manual Types to Real CMS | 8 min read

The magical moment: you built everything with manual example data, and now you're ready for Payload CMS. This guide shows:

How to generate Payload config from your types
Changing data sources without touching components
Query patterns for fetching from Payload
Handling draft vs published states
Migrating existing example data

The magic reveal: Your components don't change. Your types don't change. Only the import source changes. That's it.

Best for: When you're ready to integrate with a real Payload CMS instance.

Key question answered: How do I move from example data to real Payload CMS data?

I want to...

Goal	Read This
Understand the entire philosophy	Episode 1: Design-Driven Development
Use an existing Payload block type	Episode 2: Adding Blocks from Payload
Create a completely new block	Episode 3: Creating Custom Block Types
Build reusable data (Industry, Client, etc.)	Episode 4: Creating Collections
Understand consistency standards	Episode 5: Icons, Components & Reusable Types
Get copy-paste templates	Episode 6: Quick Reference
Integrate with Payload CMS	Episode 7: Migration to Payload CMS

The Complete Development Flow

Here's how everything connects in a real project:

code

DESIGN PHASE
   ↓
   Designer creates Figma mockup for new feature
   ↓
ANALYZE PHASE
   ↓
   You open Figma and identify data fields
   ↓
   Question: "Does Payload already have this block type?"
   ├─ YES → Read Episode 2 (Using Existing Types)
   └─ NO  → Read Episode 3 (Creating Custom Types)
   ↓
IMPLEMENT PHASE
   ↓
   You create types, components, example data
   ├─ Need icons? → Episode 5
   ├─ Need templates? → Episode 6
   └─ Need components? → Episode 5
   ↓
EXAMPLE DATA PHASE
   ↓
   Add data to app/data.ts, render with BlockRenderer
   Feature is complete and looks exactly like design
   ↓
PAYLOAD INTEGRATION PHASE (Later)
   ↓
   Ready to connect to real CMS?
   → Read Episode 7 (Migration to Payload CMS)
   Change import source, everything works
   ↓
COMPLETE ✓
   Feature is live from Payload CMS
   No refactoring needed
   Zero mismatch with design

Key Principles

These principles run through every guide:

1. Design is Your Specification

Don't guess. Look at Figma. The design shows you exactly what data you need.

2. Types Mirror Design

Your TypeScript types should directly reflect what Figma shows. One-to-one mapping.

3. Components Are Dumb

Components don't decide what data exists. They display what types tell them to display.

4. Reuse Global Types

CTA, Image, Button—use them everywhere. One type change fixes the entire app.

5. Example Data is Your Documentation

Before Payload, example data IS your spec. Later, Payload replaces it (components stay the same).

6. No Refactoring on CMS Integration

Your component code doesn't change when you switch from example data to Payload. Only the import source changes.

Project Structure (What You'll Be Building)

code

project-root/
├── payload-types.ts                    ← Source of truth
│
├── app/
│   ├── page.tsx                        ← Homepage
│   ├── data.ts                         ← All page data lives here
│   ├── about/
│   │   ├── page.tsx
│   │   └── data.ts
│   └── [other pages]/
│
└── src/components/
    ├── block-renderer.tsx              ← Routes blocks to components
    └── blocks/
        ├── hero/
        │   ├── hero-template-1.tsx
        │   └── index.ts
        ├── featured-industries/
        │   ├── featured-industries-template-1.tsx
        │   └── index.ts
        ├── services/
        │   ├── services-template-1.tsx
        │   └── index.ts
        └── [your new blocks]/

Before You Start

Make sure you have:

Familiarity with Next.js and TypeScript
Access to your project codebase
Figma design for what you're building
Understanding of your data structure (what fields do you need?)

Not comfortable with one of these? No problem. Start with Episode 1, work through the real examples, and you'll pick it up fast.

How to Use These Guides

If you're new to the project:

Read Episode 1 (Philosophy) to understand the approach
Pick the scenario that matches your task:
- Using existing block? → Episode 2
- Creating new block? → Episode 3
- Need templates? → Episode 6
Follow the step-by-step instructions
Use Episode 6 for copy-paste templates when needed

If you're extending the project:

Identify: What am I building? (block, collection, page?)
Jump to the relevant episode
Use Episode 6 for templates
Reference Episode 5 for consistency standards

If you're integrating Payload CMS:

Build everything with example data first (Episodes 2-6)
When ready to connect Payload, read Episode 7
Change import, everything works

Common Scenarios & Solutions

Scenario	Read This
I need to add a Hero block to the homepage	Episode 2 + Episode 6
I need to create a new block type that doesn't exist	Episode 3
I need a reusable list of Industries	Episode 4
I'm confused about Lucide icons vs shadcn/ui components	Episode 5
I'm building a block but can't remember the exact syntax	Episode 6
I have example data and now need to connect Payload	Episode 7

Questions & Feedback

These guides are living documents. They improve when you ask questions:

Confused about something? → Check the specific episode
Need templates? → Episode 6: Quick Reference
Want to see real code? → Check src/types/ and src/components/blocks/ in the project
Want clarification? → Ask the team—these guides improve with your feedback

The Big Picture

You're learning a systematic approach that:

Prevents refactoring
Keeps design and code aligned
Makes CMS integration trivial
Ensures consistency across your entire codebase
Lets you ship faster

This isn't theoretical. It's a proven pattern used in production systems that scale.

From Figma mockup to production Payload CMS integration—without refactoring

Why This Matters

Most developers build components like this:

Guess at a data structure
Build the component
Show the designer
Discover the data structure doesn't match
Refactor everything (repeat steps 1-4)

The result? Zero refactoring. Zero mismatches. Total confidence.

The Guide Series

This is a 7-part journey that builds on itself. Each guide is self-contained, but they connect logically:

1. Design-Driven Development ← Start Here

Philosophy & Mindset | 5 min read

Understand why design comes first. Learn the 5 concrete benefits of this approach. See why Payload integration becomes trivial when you build this way.

Key question answered: Why should I care about design-driven development?

2. Adding Blocks from Payload

Using Existing Types | 10 min read

Payload already has Hero, Services, FeaturedProjects, and other block types. This guide shows you how to:

Use Payload types directly in components
Build components without creating custom types
Create example data for those blocks
Integrate blocks into pages

Best for: When you're working with existing Payload block definitions.

Key question answered: How do I use a block that Payload already defined?

3. Creating Custom Block Types

Building From Scratch | 15 min read

Building a new block type from Figma design to component to page integration. This guide walks through:

Analyzing Figma design to extract data fields
Defining your custom block type
Building the component
Creating example data
Updating BlockRenderer
Adding to pages

Best for: When Payload doesn't have the block you need yet.

Real example: Building a "Featured Industries" block from design mockup to rendered page.

Key question answered: How do I build a completely new block?

4. Creating Collections

Data Entities & Reusable Data | 10 min read

Collections are reusable data entities (Industry, Client, Product, Team Member) that appear across multiple blocks. This guide shows:

Defining collection types from design
Creating example collections
Using collections in multiple blocks
Structure for Payload CMS integration

Best for: When you have data that multiple blocks need to reference.

Real example: Industry collection used by FeaturedIndustries block, IndustryGrid block, and other places.

Key question answered: How do I create reusable data that multiple blocks share?

5. Icons, Components & Reusable Types

Consistency & Best Practices | 12 min read

Three critical practices ensure consistency across your entire system:

Lucide React for icons - Icon naming conventions, usage patterns
shadcn/ui for components - When to use shadcn/ui, what not to build custom
Global CTA type - Using the same CTA structure everywhere

Best for: Understanding standards and consistency practices.

Key question answered: How do I keep all blocks consistent and maintainable?

6. Quick Reference: Templates & Checklists

Copy-Paste Resources | Reference

Tired of remembering syntax? This section contains:

Type definition template - Copy-paste structure for new types
Component template - Component boilerplate
Example data template - How to structure examples
Page data template - Adding blocks to pages
BlockRenderer addition template - How to add block routing
Pre-flight checklists - Don't forget anything

Best for: When you're actively building and need quick templates.

Key question answered: What's the exact format I should use for [type/component/data]?

7. Migration to Payload CMS

From Manual Types to Real CMS | 8 min read

The magical moment: you built everything with manual example data, and now you're ready for Payload CMS. This guide shows:

How to generate Payload config from your types
Changing data sources without touching components
Query patterns for fetching from Payload
Handling draft vs published states
Migrating existing example data

The magic reveal: Your components don't change. Your types don't change. Only the import source changes. That's it.

Best for: When you're ready to integrate with a real Payload CMS instance.

Key question answered: How do I move from example data to real Payload CMS data?

I want to...

Goal	Read This
Understand the entire philosophy	Episode 1: Design-Driven Development
Use an existing Payload block type	Episode 2: Adding Blocks from Payload
Create a completely new block	Episode 3: Creating Custom Block Types
Build reusable data (Industry, Client, etc.)	Episode 4: Creating Collections
Understand consistency standards	Episode 5: Icons, Components & Reusable Types
Get copy-paste templates	Episode 6: Quick Reference
Integrate with Payload CMS	Episode 7: Migration to Payload CMS

The Complete Development Flow

Here's how everything connects in a real project:

code

DESIGN PHASE
   ↓
   Designer creates Figma mockup for new feature
   ↓
ANALYZE PHASE
   ↓
   You open Figma and identify data fields
   ↓
   Question: "Does Payload already have this block type?"
   ├─ YES → Read Episode 2 (Using Existing Types)
   └─ NO  → Read Episode 3 (Creating Custom Types)
   ↓
IMPLEMENT PHASE
   ↓
   You create types, components, example data
   ├─ Need icons? → Episode 5
   ├─ Need templates? → Episode 6
   └─ Need components? → Episode 5
   ↓
EXAMPLE DATA PHASE
   ↓
   Add data to app/data.ts, render with BlockRenderer
   Feature is complete and looks exactly like design
   ↓
PAYLOAD INTEGRATION PHASE (Later)
   ↓
   Ready to connect to real CMS?
   → Read Episode 7 (Migration to Payload CMS)
   Change import source, everything works
   ↓
COMPLETE ✓
   Feature is live from Payload CMS
   No refactoring needed
   Zero mismatch with design

Key Principles

These principles run through every guide:

1. Design is Your Specification

Don't guess. Look at Figma. The design shows you exactly what data you need.

2. Types Mirror Design

Your TypeScript types should directly reflect what Figma shows. One-to-one mapping.

3. Components Are Dumb

Components don't decide what data exists. They display what types tell them to display.

4. Reuse Global Types

CTA, Image, Button—use them everywhere. One type change fixes the entire app.

5. Example Data is Your Documentation

Before Payload, example data IS your spec. Later, Payload replaces it (components stay the same).

6. No Refactoring on CMS Integration

Your component code doesn't change when you switch from example data to Payload. Only the import source changes.

Project Structure (What You'll Be Building)

code

project-root/
├── payload-types.ts                    ← Source of truth
│
├── app/
│   ├── page.tsx                        ← Homepage
│   ├── data.ts                         ← All page data lives here
│   ├── about/
│   │   ├── page.tsx
│   │   └── data.ts
│   └── [other pages]/
│
└── src/components/
    ├── block-renderer.tsx              ← Routes blocks to components
    └── blocks/
        ├── hero/
        │   ├── hero-template-1.tsx
        │   └── index.ts
        ├── featured-industries/
        │   ├── featured-industries-template-1.tsx
        │   └── index.ts
        ├── services/
        │   ├── services-template-1.tsx
        │   └── index.ts
        └── [your new blocks]/

Before You Start

Make sure you have:

Familiarity with Next.js and TypeScript
Access to your project codebase
Figma design for what you're building
Understanding of your data structure (what fields do you need?)

Not comfortable with one of these? No problem. Start with Episode 1, work through the real examples, and you'll pick it up fast.

How to Use These Guides

If you're new to the project:

Read Episode 1 (Philosophy) to understand the approach
Pick the scenario that matches your task:
- Using existing block? → Episode 2
- Creating new block? → Episode 3
- Need templates? → Episode 6
Follow the step-by-step instructions
Use Episode 6 for copy-paste templates when needed

If you're extending the project:

Identify: What am I building? (block, collection, page?)
Jump to the relevant episode
Use Episode 6 for templates
Reference Episode 5 for consistency standards

If you're integrating Payload CMS:

Build everything with example data first (Episodes 2-6)
When ready to connect Payload, read Episode 7
Change import, everything works

Common Scenarios & Solutions

Scenario	Read This
I need to add a Hero block to the homepage	Episode 2 + Episode 6
I need to create a new block type that doesn't exist	Episode 3
I need a reusable list of Industries	Episode 4
I'm confused about Lucide icons vs shadcn/ui components	Episode 5
I'm building a block but can't remember the exact syntax	Episode 6
I have example data and now need to connect Payload	Episode 7

Questions & Feedback

These guides are living documents. They improve when you ask questions:

Confused about something? → Check the specific episode
Need templates? → Episode 6: Quick Reference
Want to see real code? → Check src/types/ and src/components/blocks/ in the project
Want clarification? → Ask the team—these guides improve with your feedback

The Big Picture

You're learning a systematic approach that:

Prevents refactoring
Keeps design and code aligned
Makes CMS integration trivial
Ensures consistency across your entire codebase
Lets you ship faster

This isn't theoretical. It's a proven pattern used in production systems that scale.

Why This Matters

The Guide Series

1. Design-Driven Development ← Start Here

Quick Navigation

The Complete Development Flow

Key Principles

1. Design is Your Specification

2. Types Mirror Design

3. Components Are Dumb

4. Reuse Global Types

5. Example Data is Your Documentation

6. No Refactoring on CMS Integration

Project Structure (What You'll Be Building)

Before You Start

How to Use These Guides

If you're new to the project:

If you're extending the project:

If you're integrating Payload CMS:

Common Scenarios & Solutions

Questions & Feedback

The Big Picture

Design-Driven Development: Build Types from Figma Quickly

Need Help Making the Switch?

📚 Comprehensive Payload CMS Guides

Related Posts:

Want to learn more?

Frequently Asked Questions

What is a design-driven block system?

Do I need Payload CMS to use this approach?

What skills are required to follow these guides?

You might be interested in

Why This Matters

The Guide Series

1. Design-Driven Development ← Start Here

Quick Navigation

The Complete Development Flow

Key Principles

1. Design is Your Specification

2. Types Mirror Design

3. Components Are Dumb

4. Reuse Global Types

5. Example Data is Your Documentation

6. No Refactoring on CMS Integration

Project Structure (What You'll Be Building)

Before You Start

How to Use These Guides

If you're new to the project:

If you're extending the project:

If you're integrating Payload CMS:

Common Scenarios & Solutions

Questions & Feedback

The Big Picture