references/design-with-tokens.md

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

Tone	Color Strategy	Typography	Layout
Bold/energetic	High contrast, accent backgrounds, gradients	XX-large headings, tight letter-spacing, uppercase accents	Full-width, asymmetric columns, large padding
Minimal/refined	Base + contrast only, subtle tertiary sections	Restrained sizes, generous line-height	Constrained width, generous whitespace, centered
Editorial/magazine	Dark sections alternating with light	Mixed font families, varied heading scales	Asymmetric splits (66/33), media-text blocks
Playful/creative	Multiple accent colors, bright backgrounds	Large display sizes, varied weights	Grid layouts, unexpected column ratios, rounded corners
Corporate/professional	Neutral palette, primary for CTAs only	Consistent scale, body font dominant	Equal columns, structured grid, minimal decoration

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:

preset slugs — reference theme.json values by name (preferred)
Style attributes — inline custom values in block JSON (fallback)
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)

Slug	Typical Use	Design Role
`base`	Background	Page/section background
`contrast`	Text on base	Primary text, dark sections
`primary`	Brand accent	CTAs, links, highlights
`secondary`	Supporting accent	Tags, secondary buttons
`tertiary`	Subtle background	Cards, alternating sections

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

Slug	CSS Variable	Typical Use
`small`	`--wp--preset--font-size--small`	Captions, metadata
`medium`	`--wp--preset--font-size--medium`	Body text emphasis
`large`	`--wp--preset--font-size--large`	Subheadings, intro text
`x-large`	`--wp--preset--font-size--x-large`	Section headings
`xx-large`	`--wp--preset--font-size--xx-large`	Hero headings, display

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:

Slug	CSS Variable	Scale Position
`20`	`--wp--preset--spacing--20`	Extra small
`30`	`--wp--preset--spacing--30`	Small
`40`	`--wp--preset--spacing--40`	Medium (default)
`50`	`--wp--preset--spacing--50`	Large
`60`	`--wp--preset--spacing--60`	Extra large
`70`	`--wp--preset--spacing--70`	2X large
`80`	`--wp--preset--spacing--80`	3X large

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

Design-to-Attribute Translation

Design Intent	Block Attribute
Large hero heading	`{"level":1,"fontSize":"xx-large","fontFamily":"heading"}` on `wp:heading`
Muted subtitle	`{"fontSize":"medium","textColor":"secondary"}` on `wp:paragraph`
Section background	`{"backgroundColor":"tertiary"}` on outer `wp:group`
Dark section	`{"backgroundColor":"contrast","textColor":"base"}` on `wp:group`
Card with padding	`{"style":{"spacing":{"padding":{"top":"var:preset
Accent border left	`{"style":{"border":{"left":{"width":"4px","color":"var:preset
Rounded corners	`{"style":{"border":{"radius":"12px"}}}` on `wp:group` or `wp:image`
Primary CTA button	`{"backgroundColor":"primary","textColor":"base"}` on `wp:button`
Outline button	`{"className":"is-style-outline"}` on `wp:button`
Centered section	`{"layout":{"type":"constrained"},"align":"full"}` on `wp:group`

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"}}}

On this page