Theming

Blocks are designed to inherit your project's visual identity rather than imposing their own. Colors come from your existing theme, spacing comes from the fluid design system, and both can be adjusted in one place.

Colors

Blocks use color tokens from shadcn/ui — names like background, foreground, muted, and primary that refer to your project's color palette rather than specific color values. If your project already has a custom shadcn/ui theme, blocks pick it up automatically with no extra work.

To change the color scheme across every block, update the color variables in your globals.css:

1:root {
2  --background: 0 0% 100%;
3  --foreground: 0 0% 3.9%;
4  --primary: 0 0% 9%;
5  --primary-foreground: 0 0% 98%;
6  --muted: 0 0% 96.1%;
7  --muted-foreground: 0 0% 45.1%;
8  /* ... other tokens */
9}

You can generate a complete color theme using the shadcn/ui theme editor, then paste the variables into your project. Every block will adopt the new colors.

Section Backgrounds

Every block includes a Background Theme field in the Payload admin panel. This lets content editors set a section's background color without touching code — useful for creating visual contrast between adjacent sections on a page.

The available themes map to your project's color tokens:

The primary theme automatically switches text to a contrasting color so it remains readable. All other themes inherit the page's default text color.

When a background theme is applied, the block adds padding, rounded corners, and the background color to create a visually contained surface. The padding scales with the screen size (using the same fluid system as section spacing), so backgrounds look proportional on every device.

Dark Mode

Blocks support dark mode out of the box. Because they use semantic color names like background and foreground rather than fixed colors, they respond to your dark mode setup automatically — no changes needed in the block code.

Fonts

Blocks use your project's default font stack. Headings use the font-title class if your project defines one; otherwise they fall back to the default font.

Font sizes are part of the fluid design system. Each heading level maps to a size that scales smoothly between screen widths — headings are smaller on phones and proportionally larger on desktops. If you want to adjust the type scale, you can override the size tokens in tokens.css or regenerate them with the Utopia type calculator.

What Blocks Do Not Control

Blocks intentionally avoid setting:

• Font families — defined in your globals.css or Tailwind config
• Base text colors — inherited from your theme's foreground token
• Page-level backgrounds — set on your layout, not on individual blocks

This keeps blocks portable. They adapt to whatever theme your project defines.