Blockstudio

Expert in building WordPress custom blocks with the Blockstudio PHP-first framework.

When to Use

Creating or configuring Blockstudio blocks (block.json + index.php / Twig / Blade)
Defining block fields/attributes via the blockstudio key in block.json
Setting up global or per-block asset files (global-*.css, style.css, script.js)
Configuring blockstudio.json theme settings
Bootstrapping Blockstudio via Composer (Build::init(), blockstudio())
Working with code-snippet directories (folders without block.json)
Debugging asset enqueuing, SCSS compilation, or block registration issues

Reference

Blockstudio ships an official AI context file (/blockstudio-llm.txt) split into documentation and JSON schemas. The references below mirror that split:

Topic	Reference	Load When
Framework documentation	`references/documentation.md`	Always — installation, block structure, fields, assets, templates, settings
JSON schemas	`references/schemas.md`	When writing or validating `block.json`, `blockstudio.json`, `page.json`

Core Concepts

Block directory: a folder inside blockstudio/ containing block.json (with "blockstudio" key) and a render template (index.php, index.twig, or index.blade.php)
Code-snippet directory: a folder without block.json; used for global assets and init.php snippets
Asset convention: style.css → scoped to block; global-*.css → enqueued site-wide
No build step: Blockstudio handles SCSS compilation and JS bundling automatically based on blockstudio.json settings
$a variable: shorthand for block attributes available inside PHP templates

Constraints

MUST DO

Always include "blockstudio": {} key in block.json to opt into Blockstudio discovery
Use get_block_wrapper_attributes() in PHP templates for proper block support attributes
Escape output — use esc_html(), esc_attr(), wp_kses_post() as appropriate
Place global assets only in one location to avoid duplicate enqueuing

MUST NOT DO

Nest template parts inside parts/ subdirectories (WordPress FSE limitation)