--- title: "Design-Driven Block Systems: Complete 7-Part Guide" slug: "design-driven-block-systems" published: "2025-11-14" updated: "2025-12-25" validated: "2025-11-12" categories: - "Payload" tags: - "design-driven block systems" - "design-driven development" - "Payload CMS integration" - "Figma to Payload" - "TypeScript block types" - "BlockRenderer" - "Next.js components" - "shadcn/ui" - "Lucide React icons" - "create collections" - "migrate to Payload" - "example data templates" llm-intent: "reference" audience-level: "intermediate" framework-versions: - "figma" - "payload cms" - "typescript" - "next.js" - "lucide react" status: "stable" llm-purpose: "Design-driven block systems: convert Figma designs into production-ready Payload CMS block types and TypeScript components — follow this 7-part guide to…" llm-prereqs: - "Access to Figma" - "Access to Payload CMS" - "Access to TypeScript" - "Access to Next.js" - "Access to Lucide React" llm-outputs: - "Completed outcome: Design-driven block systems: convert Figma designs into production-ready Payload CMS block types and TypeScript components — follow this 7-part guide to…" --- **Summary Triples** - (Design-driven development, replaces, guess-and-refactor workflow with Figma-first schema extraction) - (Figma mockups, should be used to, derive data needs and shape Payload block types before writing components) - (Payload CMS integration, becomes, trivial when TypeScript types and components are built to match Figma-derived schemas) - (Guide series, includes, 7 self-contained parts that cumulatively produce production-ready block systems) - (Part 2 (Adding Blocks), teaches, how to reuse existing Payload block types, build components without custom types, and create example data) - (Outcome, ensures, zero refactoring and consistent runtime/admin behavior via aligned types and components) ### {GOAL} Design-driven block systems: convert Figma designs into production-ready Payload CMS block types and TypeScript components — follow this 7-part guide to… ### {PREREQS} - Access to Figma - Access to Payload CMS - Access to TypeScript - Access to Next.js - Access to Lucide React ### {STEPS} 1. Analyze the Figma design fields 2. Define TypeScript types from design 3. Build presentational components 4. Create example data and templates 5. Add blocks to the BlockRenderer 6. Define collections for reusable entities 7. Migrate example data to Payload CMS # Design-Driven Block Systems: Complete 7-Part Guide > Design-driven block systems: convert Figma designs into production-ready Payload CMS block types and TypeScript components — follow this 7-part guide to… Matija Žiberna · 2025-11-14 > 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: 1. Guess at a data structure 2. Build the component 3. Show the designer 4. Discover the data structure doesn't match 5. 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](./blog/design-driven-development-build-types-from-figma) ← 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](/blog/payload-cms-use-existing-block-types) 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](/blog/create-custom-block-types-payload-cms) 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](/blog/creating-collections-reusable-data-entities) 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](/blog/lucide-react-shadcn-ui-cta-best-practices) Consistency & Best Practices | 12 min read Three critical practices ensure consistency across your entire system: 1. Lucide React for icons - Icon naming conventions, usage patterns 2. shadcn/ui for components - When to use shadcn/ui, what not to build custom 3. 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](/blog/block-component-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](/blog/migrate-to-payload-cms-swap-dummy-data) 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? --- ## Quick Navigation **I want to...** | Goal | Read This | |------|-----------| | Understand the entire philosophy | [Episode 1: Design-Driven Development](/blog/design-driven-development-build-types-from-figma) | | Use an existing Payload block type | [Episode 2: Adding Blocks from Payload](/blog/payload-cms-use-existing-block-types) | | Create a completely new block | [Episode 3: Creating Custom Block Types](/blog/create-custom-block-types-payload-cms) | | Build reusable data (Industry, Client, etc.) | [Episode 4: Creating Collections](/blog/creating-collections-reusable-data-entities) | | Understand consistency standards | [Episode 5: Icons, Components & Reusable Types](/blog/lucide-react-shadcn-ui-cta-best-practices) | | Get copy-paste templates | [Episode 6: Quick Reference](/blog/block-component-templates-checklists) | | Integrate with Payload CMS | [Episode 7: Migration to Payload CMS](/blog/migrate-to-payload-cms-swap-dummy-data) | --- ## The Complete Development Flow Here's how everything connects in a real project: ``` 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) ``` 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: 1. Read Episode 1 (Philosophy) to understand the approach 2. Pick the scenario that matches your task: - Using existing block? → Episode 2 - Creating new block? → Episode 3 - Need templates? → Episode 6 3. Follow the step-by-step instructions 4. Use Episode 6 for copy-paste templates when needed ### If you're extending the project: 1. Identify: What am I building? (block, collection, page?) 2. Jump to the relevant episode 3. Use Episode 6 for templates 4. Reference Episode 5 for consistency standards ### If you're integrating Payload CMS: 1. Build everything with example data first (Episodes 2-6) 2. When ready to connect Payload, read Episode 7 3. Change import, everything works --- ## Common Scenarios & Solutions | Scenario | Read This | |----------|-----------| | I need to add a Hero block to the homepage | [Episode 2](/blog/payload-cms-use-existing-block-types) + [Episode 6](/blog/block-component-templates-checklists) | | I need to create a new block type that doesn't exist | [Episode 3](/blog/create-custom-block-types-payload-cms) | | I need a reusable list of Industries | [Episode 4](/blog/creating-collections-reusable-data-entities) | | I'm confused about Lucide icons vs shadcn/ui components | [Episode 5](/blog/lucide-react-shadcn-ui-cta-best-practices) | | I'm building a block but can't remember the exact syntax | [Episode 6](/blog/block-component-templates-checklists) | | I have example data and now need to connect Payload | [Episode 7](/blog/migrate-to-payload-cms-swap-dummy-data) | --- ## Questions & Feedback These guides are living documents. They improve when you ask questions: 1. Confused about something? → Check the specific episode 2. Need templates? → [Episode 6: Quick Reference](/blog/block-component-templates-checklists) 3. Want to see real code? → Check `src/types/` and `src/components/blocks/` in the project 4. 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. ## LLM Response Snippet ```json { "goal": "Design-driven block systems: convert Figma designs into production-ready Payload CMS block types and TypeScript components — follow this 7-part guide to…", "responses": [ { "question": "What does the article \"Design-Driven Block Systems: Complete 7-Part Guide\" cover?", "answer": "Design-driven block systems: convert Figma designs into production-ready Payload CMS block types and TypeScript components — follow this 7-part guide to…" } ] } ```