Home › WordPress › WordPress block theme & blocks rules

WordPress block theme & blocks rules

Cursor rules for WordPress block themes and custom blocks: theme.json v3, block.json, patterns, and @wordpress/scripts.

CursorWordPress

Copy wp-blocks.mdc

How to use

Save this as .cursor/rules/wp-blocks.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

---
description: WordPress block theme & blocks conventions
globs: ["**/*.php","**/block.json","theme.json","src/**/*.js","src/**/*.jsx"]
alwaysApply: false
---

# WordPress block themes and custom blocks

## Block themes
- Global styles and settings live in `theme.json` (schema version 3): color palette, typography scale, spacing presets, layout widths. Use presets (`var(--wp--preset--color--primary)`) instead of hard-coded CSS.
- Templates in `templates/*.html` and parts in `parts/*.html` use block markup only. Register reusable layouts as patterns in `patterns/*.php` with the header comment (Title, Slug, Categories).
- Keep `style.css` for the theme header and minimal extras; most styling goes through `theme.json` and block style variations (`styles/*.json`).

## Custom blocks
- Scaffold with `npx @wordpress/create-block` and build with `@wordpress/scripts` (`npm run start` / `npm run build`).
- Metadata in `block.json` (`apiVersion: 3`, `attributes`, `supports`, `textdomain`); register with `register_block_type( __DIR__ . '/build/my-block' )`.
- Use `supports` (color, spacing, typography) instead of custom controls when possible.
- Editor UI with `useBlockProps`, `RichText`, `InspectorControls` and components from `@wordpress/components`.
- Prefer dynamic blocks (`render.php`) for content that depends on data; static `save` output must stay stable or add `deprecated` entries to avoid block validation errors.
- Escape in `render.php` (`esc_html`, `wp_kses_post`) and use `get_block_wrapper_attributes()`.
- Strings via `__()` from `@wordpress/i18n`.

## Done when
`npm run build` and `npm run lint:js` pass, and the block inserts, saves, and reloads without validation warnings.