Menu
Build and modify WordPress block themes following 10up standards. Covers theme.json configuration, templates, template parts, patterns, style variations, and CSS organization. Use when working on block-based themes or Site Editor customizations.
| name | 10up-block-themes |
| description | Build and modify WordPress block themes following 10up standards. Covers theme.json configuration, templates, template parts, patterns, style variations, and CSS organization. Use when working on block-based themes or Site Editor customizations. |
| license | MIT |
| compatibility | WordPress 6.4+, PHP 8.0+, requires block theme structure |
| globs | ["theme.json","style.css","templates/**/*","parts/**/*","partials/**/*","patterns/**/*.php","styles/**/*.json"] |
| metadata | {"author":"10up","version":"1.0"} |
This skill guides you through block theme development following 10up standards and WordPress Site Editor best practices.
| Aspect | Block Theme | Classic Theme |
|---|---|---|
| Templates | HTML files in /templates/ | PHP files in root |
| Styling | theme.json + CSS | style.css + PHP |
| Editing | Site Editor | Theme Customizer |
| Patterns | PHP files in /patterns/ | Optional |
theme-name/
├── style.css # Theme metadata (required)
├── theme.json # Design tokens and settings
├── templates/ # Full page templates
│ ├── index.html # Required fallback
│ ├── single.html # Single post
│ ├── page.html # Single page
│ ├── archive.html # Archive pages
│ └── 404.html # Not found
├── parts/ # Reusable template parts
│ ├── header.html
│ └── footer.html
├── patterns/ # Block patterns
│ └── card.php
├── styles/ # Style variations
│ └── dark.json
└── assets/
└── css/
└── blocks/ # Per-block CSS
The theme.json file is the design token source for block themes.
Minimal structure:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"palette": []
},
"typography": {
"fontSizes": [],
"fontFamilies": []
},
"spacing": {
"units": ["px", "em", "rem", "%"],
"spacingSizes": []
},
"layout": {
"contentSize": "800px",
"wideSize": "1200px"
}
},
"styles": {
"color": {
"background": "var(--wp--preset--color--base)",
"text": "var(--wp--preset--color--contrast)"
}
}
}
See references/theme-json.md for complete configuration.
See references/template-hierarchy.md for template loading order.
Templates are HTML files containing block markup.
templates/index.html (required):
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
<!-- wp:query {"queryId":1,"query":{"perPage":10,"pages":0,"offset":0,"postType":"post"}} -->
<div class="wp-block-query">
<!-- wp:post-template -->
<!-- wp:post-title {"isLink":true} /-->
<!-- wp:post-excerpt /-->
<!-- /wp:post-template -->
<!-- wp:query-pagination -->
<!-- wp:query-pagination-previous /-->
<!-- wp:query-pagination-numbers /-->
<!-- wp:query-pagination-next /-->
<!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
Key points:
wp:template-parttagNameTemplate parts are reusable sections.
parts/header.html:
<!-- wp:group {"tagName":"header","className":"site-header","layout":{"type":"constrained"}} -->
<header class="wp-block-group site-header">
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
<!-- wp:site-logo /-->
<!-- wp:site-title /-->
<!-- wp:navigation /-->
</div>
<!-- /wp:group -->
</header>
<!-- /wp:group -->
Patterns are PHP files with block markup.
patterns/card.php:
<?php
/**
* Title: Card
* Slug: theme-name/card
* Description: A card component with image and text
* Categories: components
* Keywords: card, box, container
* Viewport Width: 600
*/
?>
<!-- wp:group {"className":"card","style":{"border":{"radius":"8px"}}} -->
<div class="wp-block-group card">
<!-- wp:image {"sizeSlug":"medium"} /-->
<!-- wp:heading {"level":3} -->
<h3>Card Title</h3>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>Card description goes here.</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:group -->
Pattern header fields:
Title - Display name in editorSlug - Unique identifier (theme-name/pattern-name)Description - Shown in pattern browserCategories - Group patterns (can be custom)Keywords - Improve searchabilityViewport Width - Preview width in inserter10up CSS organization pattern:
assets/css/
├── style.css # Main stylesheet
├── editor.css # Editor-specific styles
└── blocks/
├── core/
│ └── group.css # Core block overrides
└── theme-name/
└── hero.css # Custom block styles
Per-block CSS in theme.json:
{
"styles": {
"blocks": {
"core/group": {
"css": "& .custom-class { padding: 2rem; }"
}
}
}
}
10up guideline: Write actual CSS in separate files, use theme.json for design tokens only.
For comprehensive CSS authoring guidelines including specificity management, naming conventions, and accessibility requirements, see 10up-css.
Style variations offer alternative designs.
styles/dark.json:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Dark",
"settings": {},
"styles": {
"color": {
"background": "#1a1a1a",
"text": "#ffffff"
}
}
}
After making theme changes:
Styles not applying:
Template not recognized:
Pattern not showing:
Site Editor not loading:
See references/debugging.md for troubleshooting.
Ask the user when:
Create and modify Gutenberg blocks following 10up engineering standards. Covers block.json metadata, dynamic rendering with PHP, attributes, deprecations, editor components, and the useBlockProps pattern. Use when creating new blocks, fixing block errors, or modifying existing block code.
Extend core WordPress blocks with custom attributes and controls using the 10up block extension pattern. Alternative to block styles when multiple controls are needed. Use when adding functionality to existing blocks rather than creating new ones.
Create reusable block patterns and synced patterns following 10up standards. Covers PHP file-based registration, pattern metadata, categories, and the block bindings API. Use when creating reusable layout components or content templates.
Write clear, consistent commit messages following 10up conventions. Uses conventional commit style with lowercase formatting. Use when creating commits, writing PR descriptions, or generating changelogs.
CSS architecture, best practices, and patterns for WordPress projects. Covers ITCSS methodology, accessibility, specificity management, naming conventions, and modern CSS features.
Implement nested blocks and block composition using InnerBlocks. Covers parent/child relationships, templates, allowed blocks, and template locking. Use when building blocks that contain other blocks like cards, sections, or grid layouts.