A block library is a product with its own users: the people who publish content every day. If they struggle with it, the website slowly drifts away from its design.
When I built more than 30 custom blocks for a national service platform, the goal was simple: editors should build a page faster than they could describe it. In practice they built pages up to ten times faster than before.
Start from content, not components
Before writing a block, list the content problems the site needs to solve: introducing a service, comparing plans, proving results, answering questions. Each problem may need one block or a pattern of several.
- What information does this section always contain?
- What is optional, and what must never be empty?
- Who edits it, and how often?
- Does it repeat across pages with the same data?
Fewer blocks, better options
Ten focused blocks with clear options beat forty near-duplicates. When two designs differ only in layout or color, they are usually one block with a style variation.
Name blocks by purpose
Editors look for “Testimonial” or “Pricing table”, not “Two-column card grid”. Purpose-based names make the library self-explanatory.
Constrain what protects the design
Freedom is not the same as flexibility. Good blocks give editors control over content while protecting spacing, typography, and color.
- Limit color and font controls to the design system palette
- Use
theme.jsonto lock spacing scales and disable unused tools - Provide sensible defaults so a new block never looks broken
- Validate required fields before a page can be published
ACF or native blocks?
I use ACF blocks when content is structured and rendered with PHP, and native JavaScript blocks when editors need rich in-canvas editing. Many projects use both. The decision should follow the content model, not habit.
Make the editor match the front end
Editors trust what they can see. Load the same styles in the editor, preview real data, and keep the in-editor layout as close as possible to the published page.
Document and evolve the library
A short guide with screenshots, plus a few ready-made patterns, does more for consistency than any training session. Treat the block library as a living system: review how editors actually use it, and refine it.
Frequently asked questions
How many custom blocks does a site need?
As few as possible. Start with core blocks and patterns, then add custom blocks only for structured or repeated content that core blocks cannot handle well.
Are ACF blocks slower than native blocks?
Not noticeably on the front end when built carefully. The difference is mainly in the editing experience and how the block is rendered.
Should editors be able to change colors?
Only within the brand palette. Restricting choices keeps pages consistent and accessible.