WordPress Full Site Editing (FSE) theme architecture. Use when generating theme.json, block templates, template parts, patterns, and functions.php for WordPress block themes.
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/wordpress-block-theming
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
WordPress Full Site Editing (FSE) theme architecture. Use when generating theme.json, block templates, template parts, patterns, and functions.php for WordPress block themes.
- Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
- **Font size scale**: Keep sizes grounded and usable. Body: 1rem. Headings: scale modestly (h1 ≤ 2.5–3rem). Use `clamp()` for responsive display text, but cap at ~3.5rem max. Avoid "massive"/"gigantic" sizes above 4rem—they rarely improve design and often degrade it. A good 6-step scale: 0.875rem / 1rem / 1.25rem / 1.75rem / 2.25rem / clamp(2.5rem, 4vw, 3.5rem).
- **Line height**: Body text: 1.5–1.65. Headings: 1.1–1.3. Never go below 1.0 for any text. Apply via `styles.typography.lineHeight` and `styles.elements.heading.typography.lineHeight` in theme.json.
## Block Templates
Templates use WordPress block markup (HTML comments with JSON attributes).
- When `functions.php` outputs any user-derived value, use WordPress escaping functions:
- HTML context: `esc_html()`
- Attribute context: `esc_attr()`
- URL context: `esc_url()`
- Never use `eval()`, `create_function()`, `shell_exec()`, `exec()`, or `system()` in generated theme code
- Static block themes with hardcoded content (the default) do not need escaping — WordPress core blocks handle this. Escaping matters only if generating PHP that renders dynamic data.
## style.css
The style.css file contains theme metadata and custom CSS.
** Important ** Always bring across custom CSS from the design into style.css that is not achievable via theme.json, especially for layout and composition techniques that are critical to the design's aesthetics such as animation/motion.
box-shadow: 0 0 20px rgba(var(--wp--preset--color--accent-rgb, 0,0,0), 0.3);
}
```
**Continuous ambient motion:**
```css
.float {
animation: float 3s ease-in-out infinite;
}
@keyframes float {
0%, 100% { transform: translateY(0); }
50% { transform: translateY(-10px); }
}
.pulse-subtle {
animation: pulse 2s ease-in-out infinite;
}
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.7; }
}
```
### Scroll-Triggered Reveals via functions.php
The most impactful animation pattern — sections revealing as the user scrolls — requires a small IntersectionObserver script. Add this to `functions.php`:
**Note:** `wp_add_inline_script` requires an existing registered script handle. Since block themes may not always have a script registered, a more reliable approach is to output the script directly:
**Width rule**: All cards in a row MUST have equal width. Calculate each column's width as `100% / number_of_cards` (e.g., 3 cards = 33.33% each). The sum of all column widths must equal exactly 100% - never exceed the parent element width.
*Images in cards: `style="height:200px;object-fit:cover;width:100%"`
If present, ensure bottom-aligned CTAs unless otherwise specified:
```css
.equal-cards .cta-bottom {
margin-top: auto;
justify-content: center;
}
```
Always add the following CSS to reset the footer top margin:
```css
.wp-site-blocks > footer {
margin-block-start: 0;
}
```
## Landing Page Composition
When generating homepage block markup, think like a landing page designer, not a template assembler. Every section should be a visually distinct, full-width band that creates rhythm and visual impact as the user scrolls.
### Section Architecture
- **Section margin reset**: Add `"style":{"spacing":{"margin":{"top":"0"}}}` to every top-level Group block that wraps a landing page section. This overrides WordPress's default top margin on direct children of `.wp-site-blocks` and can be easily adjusted by users in the editor.
- **Section layout widths**: Hero sections, header groups, cover blocks, and feature grids should use `"align":"wide"` or `"align":"full"` rather than defaulting to narrow content width. Only use default (content) alignment for text-heavy reading sections.
- Do **not** use `<inner-blocks>`; output the full expanded markup inside each block.
- **Columns alignment**: ALWAYS set `"align":"wide"` on `wp:columns` blocks (and add the `alignwide` class on the wrapper div) unless specifically instructed otherwise.
- **No decorative HTML comments**: Never insert section-labeling comments like `<!-- Hero Section -->` or `<!-- Services Section -->` in templates, template parts, or patterns. Only WordPress block comments (`<!-- wp:block-name -->`) are allowed.
**Every major homepage section must be `alignfull`** — edge-to-edge across the viewport. Content inside can be constrained, but the section wrapper fills the screen width. This is the **full-bleed wrapper, constrained content** pattern:
**Never use bare `{"layout":{"type":"constrained"}}` without `"align":"full"` for homepage sections.** Without `alignfull`, sections render at `contentSize` (800px) and the page looks narrow and lifeless.
**YOU DECIDE** which sections best serve this specific site. Do not follow a rigid template. Consider the site type, audience, and primary goal:
- A portfolio needs a full-bleed project gallery
- A SaaS needs feature grids with clear value props
- A restaurant needs appetizing imagery and menu sections
- An agency needs case study cards and social proof
- An escape room needs atmosphere and immersion
### Visual Rhythm
Alternate between visual treatments to create rhythm as the user scrolls:
| Technique | WordPress Implementation |
|-----------|------------------------|
| Alternating backgrounds | Alternate `backgroundColor` between `background` and `surface` (or `primary`/`secondary` for bold sections) |
| Full-bleed imagery | Cover blocks with `"align":"full"` and `overlayColor` from the brand palette |
| Edge-to-edge media-text | `wp:media-text` with `"align":"full"` for alternating image/content sides |
| Bold CTA bands | Full-width group with `primary` or `accent` background, centered text |
| Spacer breaks | `wp:spacer` between sections for breathing room |
Every section should feel visually distinct from its neighbors. If two adjacent sections have the same background color and layout pattern, the page feels monotonous — change the background, flip the image side, switch from grid to single-column, or add a cover block break.
## Image Handling
ONLY add user provided images/image URLs to the initial site build. Stock image urls often fail to load in the block editor and break the design.
Look at any user supplies images carefully and include them in the design if appropriate, but do not force them in if they do not fit the design.
### Creating Visual Richness Without Images
Since only user provided images/image URLs can be used, if none are available convey atmosphere and visual interest through:
- **CSS Gradients**: Linear, radial, and conic gradients for depth and color
- **Color Blocks**: Bold use of background colors to create visual hierarchy
- **Typography as Design**: Large, distinctive headings; creative font pairing; varied text sizes and weights
