/wp-patterns

Design with Tokens

How to translate design intent into WordPress block attributes using theme.json presets.

Design Decisions

Purpose

What does this pattern achieve for the end user? A hero converts visitors. A testimonial grid builds trust. A pricing table drives comparison. Let purpose drive every subsequent choice.

Tone

Spatial Composition

Primary layout strategies:

• Constrained centered — classic content width with wide breakouts
• Full-width sections — alternating background bands
• Asymmetric split — 60/40 or 70/30 columns with content + media
• Grid — block-native grid or columns layouts for cards, team members, portfolio items
• Stacked vertical — flex column with varied spacing for editorial feel

Typography Hierarchy

Plan your type scale before writing markup:

• Hero heading: fontSize:"xx-large" + fontFamily:"heading" + tight lineHeight
• Section heading: fontSize:"x-large" + fontFamily:"heading"
• Subtitle/lead: fontSize:"large" + textColor:"secondary" or fontFamily:"body"
• Body: fontSize:"medium" or default
• Caption/meta: fontSize:"small" + textColor:"secondary"

Add at least one typographic accent:

• Uppercase + letter-spacing for labels: {"style":{"typography":{"textTransform":"uppercase","letterSpacing":"0.1em"}}}
• Tight letter-spacing on display headings: {"style":{"typography":{"lineHeight":"1.1"}}}
• Italic for pull quotes
• Monospace for technical/code content
• Generous leading on body: {"style":{"typography":{"lineHeight":"1.8"}}}

Color Strategy

Plan section-by-section color flow:

• Light section: base background, contrast text (default)
• Dark section: contrast background, base text (inverted)
• Accent section: primary or tertiary background
• Gradient section: cover block with gradient overlay

A pattern with multiple sections should vary backgrounds — don't use the same background for every section.

Core Principle

In block patterns, all visual design is expressed through:

1. preset slugs — reference theme.json values by name (preferred)
2. Style attributes — inline custom values in block JSON (fallback)
3. Block nesting — layout and composition via container blocks

Never use inline <style> tags, custom CSS classes not generated by blocks, or arbitrary HTML outside block wrappers.

theme.json Preset Mapping

Color Palette (Default WP 6.7+ Presets)

Usage in block attributes:

{"backgroundColor":"tertiary","textColor":"contrast"}

Custom themes define their own slugs. Patterns for distribution should use generic slugs above or provide fallback hex values.

Font Size Presets

Usage: {"fontSize":"xx-large"} on heading/paragraph blocks.

For custom fluid sizes in style attribute:

{"style":{"typography":{"fontSize":"clamp(2rem, 4vw, 4.5rem)"}}}

Font Family Presets

Common theme slugs:

• "fontFamily":"heading" — display/heading typeface
• "fontFamily":"body" — body text typeface
• "fontFamily":"system-sans-serif" — system fallback
• "fontFamily":"monospace" — code/technical

Spacing Scale

Default spacing presets use numeric slugs 20 through 80:

Reference in style attributes: "var:preset|spacing|50"

Design-to-Attribute Translation

Spatial Rhythm Techniques

Vertical Rhythm

Use consistent spacing presets on section groups:

{"style":{"spacing":{"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}}

Vary blockGap between inner elements for hierarchy:

• Tight grouping (related items): "blockGap":"var:preset|spacing|20"
• Standard flow: "blockGap":"var:preset|spacing|40"
• Generous breathing room: "blockGap":"var:preset|spacing|60"

Horizontal Composition

• Asymmetric columns: {"width":"66.66%"} + {"width":"33.33%"} — avoid always using equal splits
• Offset content: Use constrained layout with custom contentSize narrower than wideSize
• Grid with varied spans: CSS grid on Group with columnCount and child columnSpan

Creating Visual Weight

• Large padding on groups creates breathing room and perceived importance
• Contrast inversion (dark bg + light text) draws attention to sections
• Border accents (left border, bottom border) create hierarchy without heaviness
• Spacer blocks between sections: use preset spacing, not arbitrary pixel values

Gradient and Shadow Presets

Gradients in attributes:

{"gradient":"vivid-cyan-blue-to-vivid-purple"}

Or custom in style:

{"style":{"color":{"gradient":"linear-gradient(135deg,#1a1a2e 0%,#16213e 100%)"}}}

Shadow presets (WP 6.7+):

{"shadow":"var:preset|shadow|natural"}

Common: natural, deep, sharp, outlined, crisp

Duotone on Images

Apply duotone filter to images and covers:

{"style":{"color":{"duotone":["#000000","#ffffff"]}}}

Or use preset: {"style":{"color":{"duotone":"var:preset|duotone|dark-grayscale"}}}