Under active development — things may change.

AI Integration

LayoutBlocks is designed to work with AI coding assistants. Every block includes a one-click AI prompt, and you can teach your IDE about the library so it suggests LayoutBlocks when you ask for layout sections.

AI Prompt (Per Block)

Every block detail page has an AI Prompt button in the quick action bar. Click it to generate a prompt that:

  1. Includes the full config.ts and component.tsx code
  2. Instructs your AI assistant to analyse your project structure
  3. Tells it to create, adapt, and register the block using your conventions
  4. Handles dependencies automatically

You can customize the block name and edit the prompt before copying. The prompt auto-detects your project setup, so it works with the Payload Website Template, custom setups, and everything in between.

Design System Prompts

The per-block prompts handle individual blocks. These prompts handle the bigger picture — setting up the fluid design system, converting existing blocks to use it, or creating new blocks from scratch. Copy a prompt and paste it into any AI coding assistant.

Set Up the Foundation

Use this after downloading the foundation files from the Installation & Setup page:

TEXT
1I'm setting up the LayoutBlocks fluid design system in my Payload CMS + Next.js
2project. I've downloaded the foundation files from
3https://layoutblocks.dev/docs/installation-setup and need them integrated.
4
5CSS:
6- tokens.css → src/styles/tokens.css (fluid spacing and type scale via CSS
7  custom properties using clamp() values)
8- Import it in globals.css: add @import './tokens.css'; BEFORE @tailwind base
9- Add the "globals.css additions" content AFTER the @tailwind directives and
10  any shadcn/ui theme variables
11
12Components:
13- Fluid/ directory → src/components/Fluid/ (FluidSection, FluidGrid,
14  FluidStack, FluidCluster, FluidContainer, FluidSubGrid, FluidSurface)
15- Typography/ directory → src/components/Typography/ (SectionHeader,
16  SectionTitle, SectionDescription, Eyebrow)
17
18Payload helpers:
19- blockDesign.ts → src/payload/fields/blockDesign.ts (field generators:
20  spacingPreset(), backgroundTheme(), contentAlignment())
21- blockDesignClasses.ts → src/lib/helpers/blockDesignClasses.ts (maps design
22  field values to CSS classes)
23
24Requirements:
25- All components use cn() from shadcn/ui — verify it exists in the project
26- Update import paths in all files to match my project's aliases (e.g. @/
27  or @/src/)
28
29Analyze my project structure, place these files, fix import paths, and verify
30the CSS imports are in the right order.

Refactor a Block to Use the Fluid System

Use this when you have an existing Payload block with manual breakpoint spacing and want to convert it:

TEXT
1I want to refactor an existing Payload CMS block to use the LayoutBlocks fluid
2design system. Convert my block from manual breakpoint spacing to the fluid
3pattern.
4
5THE PATTERN — every block follows: FluidSection → FluidGrid → content
6
7Component wrapping:
8- Wrap in <FluidSection> (adds max-width container)
9- Inside, use <FluidGrid marginY={...} bgColor={...}> (12-column CSS grid)
10- Content goes in <div className="col-span-12 lg:col-span-6"> etc.
11- Text hierarchy: <SectionHeader eyebrow={...} title={...} description={...}>
12- Horizontal groups (buttons): <FluidCluster>
13- Vertical stacks: <FluidStack>
14
15Replace these patterns:
16- py-16 md:py-24 lg:py-32 → remove; FluidGrid marginY handles it ("sm" | "lg" | "xl")
17- max-w-7xl mx-auto px-4 → remove; FluidSection handles containment
18- grid grid-cols-1 md:grid-cols-2 → FluidGrid + col-span-* classes
19- rounded-2xl → rounded-[var(--surface-radius)]
20- text-4xl md:text-5xl lg:text-6xl → SectionTitle (uses fluid type scale)
21- gap-4, gap-8 → gap-stack (vertical), gap-cluster (horizontal), gap-grid (grid)
22
23Add Design fields to config.ts:
24- Add a "Design" collapsible at the end of the fields array
25- Inside, put a row with: spacingPreset(), backgroundTheme(), contentAlignment()
26- Import from '@/src/payload/fields/blockDesign'
27
28Use design values in component.tsx:
29- Import getFluidGridMarginY, getFluidGridThemeProps from
30  '@/src/lib/helpers/blockDesignClasses'
31- Pass to FluidGrid:
32  marginY={getFluidGridMarginY(spacingPreset)}
33  {...getFluidGridThemeProps(backgroundTheme ?? 'default')}
34
35After refactoring, run: pnpm payload generate:types
36
37Here's my block to refactor:
38[paste your config.ts and component.tsx here]

Create a New Block

Use this to build a new block from scratch following the fluid patterns:

TEXT
1Create a new Payload CMS block using the LayoutBlocks fluid design system.
2
3The block should: [describe what you want]
4
5config.ts structure:
6- Export as [Name]Config, slug as [name]Config, interfaceName as [Name]Type
7- Organize fields in collapsible sections (admin: { initCollapsed: true })
8- Use localized: true on user-facing text fields
9- Add a Design collapsible at the end with spacingPreset(),
10  backgroundTheme(), contentAlignment() from '@/src/payload/fields/blockDesign'
11
12component.tsx structure:
13- Import type from '@/payload-types'
14- Follow the FluidSection → FluidGrid → content pattern:
15
16  <FluidSection>
17    <FluidGrid
18      marginY={getFluidGridMarginY(spacingPreset)}
19      {...getFluidGridThemeProps(backgroundTheme ?? 'default')}
20    >
21      <div className="col-span-12">
22        ...content...
23      </div>
24    </FluidGrid>
25  </FluidSection>
26
27- Use SectionHeader for text hierarchy (eyebrow, title, description)
28- Use FluidCluster for horizontal groups (buttons, links, tags)
29- Use FluidStack for vertical content stacks
30- Use rounded-[var(--surface-radius)] for surface border radius
31- Use fluid gap classes: gap-stack, gap-cluster, gap-grid
32- Never use breakpoints for spacing or typography — only for structural
33  layout changes like column stacking
34
35After creating, register the block:
361. Add config to Payload blocks field
372. Add component mapping in RenderBlocks
383. Run pnpm payload generate:types

Page Builder

The Page Builder showcases curated page templates — pre-composed block combinations for common page types like SaaS landing pages, agency homepages, and product showcases. Browse the templates for inspiration, then add individual blocks using the AI prompt on each block's detail page.

An interactive page builder with drag-and-drop composition and a single combined prompt is coming soon.

CLI Tool

The LayoutBlocks CLI lets you add blocks directly from your terminal without visiting the website.

Commands

List all blocks:

Terminal
1npx layoutblocks list

List blocks in a category:

Terminal
1npx layoutblocks list heros

Add a block to your project:

Terminal
1npx layoutblocks add hero-1

This creates config.ts and component.tsx in ./src/blocks/<category>/<slug>/. Use --dir to specify a custom output directory:

Terminal
1npx layoutblocks add hero-1 --dir ./blocks/heros/hero-1

Show block details:

Terminal
1npx layoutblocks info pricing-1

After adding a block, you'll need to:

  1. Adapt imports in both files to match your project's conventions
  2. Register the block config in your Payload blocks field
  3. Add the component to your frontend renderer (e.g., RenderBlocks)
  4. Run pnpm payload generate:types

Or use the AI prompt on the block's detail page to have your coding assistant handle all of this automatically.

Blocks API

The CLI tool is powered by a public JSON API you can also use directly.

List all blocks:

Code
1GET /api/blocks

Returns an array of block summaries with slug, title, displayName, category, description, and search metadata.

Get a single block with code:

Code
1GET /api/blocks?slug=hero-1

Returns the full block detail including configCode, componentCode, and dependencies.

Cursor Rule

If you use Cursor, download the LayoutBlocks rule file and add it to your project:

  1. Download layoutblocks-cursor-rule.mdc
  2. Place it in your project's .cursor/rules/ directory
  3. Cursor will now know about all available LayoutBlocks when you ask it to add sections

The rule includes the full block inventory, naming conventions, registration steps, and stack compatibility.

CLAUDE.md Snippet

If you use Claude Code, add the LayoutBlocks snippet to your project's CLAUDE.md:

  1. Download layoutblocks-claude-md.md
  2. Copy the contents into your project's CLAUDE.md file
  3. Claude Code will reference LayoutBlocks when you ask for layout sections

How AI Prompts Work

When you paste a LayoutBlocks AI prompt into your coding assistant, it:

  1. Analyses your project — understands your file structure, import aliases, and conventions
  2. Creates the block files — places config.ts and component.tsx in the right directory
  3. Adapts imports — updates import paths to match your project (e.g., @/blocks/ vs @/src/blocks/)
  4. Registers the block — adds it to your Payload config and frontend renderer
  5. Runs type generation — executes pnpm payload generate:types if your project uses it

This works with Cursor, Claude Code, GitHub Copilot, Windsurf, and any AI coding assistant that accepts text prompts.