Setting the file. One moment.
Subchapter 10.3
references/design-with-tokens.mdMarkdown8 KBView on GitHub
How to translate design intent into WordPress block attributes using theme.json presets.
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 | 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 |
Primary layout strategies:
Plan your type scale before writing markup:
fontSize:"xx-large" + fontFamily:"heading" + tight lineHeightfontSize:"x-large" + fontFamily:"heading"fontSize:"large" + textColor:"secondary" or fontFamily:"body"fontSize:"medium" or defaultfontSize:"small" + textColor:"secondary"Add at least one typographic accent:
{"style":{"typography":{"textTransform":"uppercase","letterSpacing":"0.1em"}}}{"style":{"typography":{"lineHeight":"1.1"}}}{"style":{"typography":{"lineHeight":"1.8"}}}Plan section-by-section color flow:
base background, contrast text (default)contrast background, base text (inverted)primary or tertiary backgroundA pattern with multiple sections should vary backgrounds — don’t use the same background for every section.
In block patterns, all visual design is expressed through:
preset slugs — reference theme.json values by name (preferred)Never use inline <style> tags, custom CSS classes not generated by blocks, or arbitrary HTML outside block wrappers.
| 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.
| 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)"}}}Common theme slugs:
"fontFamily":"heading" — display/heading typeface"fontFamily":"body" — body text typeface"fontFamily":"system-sans-serif" — system fallback"fontFamily":"monospace" — code/technicalDefault 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 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 |
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:
"blockGap":"var:preset|spacing|20""blockGap":"var:preset|spacing|40""blockGap":"var:preset|spacing|60"{"width":"66.66%"} + {"width":"33.33%"} — avoid always using equal splitscontentSize narrower than wideSizecolumnCount and child columnSpanpreset spacing, not arbitrary pixel valuesGradients 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
Apply duotone filter to images and covers:
{"style":{"color":{"duotone":["#000000","#ffffff"]}}}Or use preset: {"style":{"color":{"duotone":"var:preset|duotone|dark-grayscale"}}}