# 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:
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)

| 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:
```json
{"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:
```json
{"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|spacing|50",...}}}}` on `wp:group` |
| Accent border left | `{"style":{"border":{"left":{"width":"4px","color":"var:preset|color|primary"}}}}` |
| 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:
```json
{"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:
```json
{"gradient":"vivid-cyan-blue-to-vivid-purple"}
```
Or custom in style:
```json
{"style":{"color":{"gradient":"linear-gradient(135deg,#1a1a2e 0%,#16213e 100%)"}}}
```

Shadow presets (WP 6.7+):
```json
{"shadow":"var:preset|shadow|natural"}
```
Common: `natural`, `deep`, `sharp`, `outlined`, `crisp`

## Duotone on Images

Apply duotone filter to images and covers:
```json
{"style":{"color":{"duotone":["#000000","#ffffff"]}}}
```
Or use preset: `{"style":{"color":{"duotone":"var:preset|duotone|dark-grayscale"}}}`