1 of 40

Block Editor Best Practices

For users, designers, and developers

https://iamdani.sh | danishshakeel54@gmail.com

2 of 40

Danish Shakeel

https://iamdani.sh | https://linkedin.com/in/danishshakeel | https://github.com/danish17

Senior Software Engineer @

2

3 of 40

“Gutenberg may be the most hated feature of WordPress”

3

4 of 40

4

5 of 40

“Gutenberg is trying to appeal to both ‘simple’ and ‘advanced’ users, and thus is doing neither one of them fairly well.”

5

6 of 40

6

7 of 40

Pain points during the project

  • No support for CSS Grid
  • No support for viewport-based styles
  • Not possible to add anything but text in list block
  • No support for negative margins
  • No support for custom width for blocks
  • No support for simple animations and interactions
  • Decisions - block or pattern?

7

8 of 40

Outline

  • Using Block Editor
  • Developing Block Themes (and blocks)
  • Improving Site Experience

8

9 of 40

Using Block Editor

9

10 of 40

Blocks

  • Atomic elements
  • Consistent design across posts and pages
  • Can be developed using JavaScript, React, and PHP
  • Core blocks:
    • Paragraph (core/paragraph)
    • Button (core/button)
    • …and more
  • Total core blocks (including experimental) as of Sep 5: 101

10

11 of 40

Patterns

  • Combination of blocks
  • Holistically serves a single purpose (generally)
  • Examples:
    • Call-to-action banners
    • Gallery
    • Hero section

11

12 of 40

Synced vs Unsynced Patterns

  • Synced:
    • Define once
    • Use anywhere
    • Change once
  • Unsynced:
    • Define once
    • Use anywhere
    • Change anywhere

12

13 of 40

How would you create a section showing �business hours?

Demo

13

14 of 40

Templates and Template Parts

  • Section of a page (template part)
  • Or, an entire page (template)
  • Defines site layout
  • Does not serve a single purpose
  • Examples:
    • Header (template part)
    • Single Post

14

15 of 40

Patterns vs Templates

15

​

Template Part

Synced Pattern (Reusable block)

Regular Pattern

Type

Site structure

User content

User content

Syncing Ability

Synced

Synced

Un-synced

Examples

Header

Footer

Sidebar

Business hours

Banner

Call to action button

Gallery

Hero section

16 of 40

The idea of components

  • Requirements of components:
    • control the markup/structure (HTML)
    • control the styling (CSS)
    • add dynamic/editable data
    • add interactivity (JS)
    • load only when used
  • Blocks almost qualify BUT they are atomic
  • Examples:
    • Carousel
    • Card

​

16

17 of 40

So, what can be used as a component?

  • Custom blocks
    • very customizable
    • flexible
    • Time-consuming
  • In future, a combination of:
    • Synced patterns
    • Pattern Overrides/Content Locking (structure)
    • Section Styles (styling)
    • Block Bindings API (data)
    • Interactivity API (scripts)

17

18 of 40

Stylebook

  • Site Editor (formerly Full-Site Editing/FSE) feature
  • Visual representation of theme.json (we’ll learn about it later)
  • Can be used to modify global styles
    • Typography
    • Layouts
    • Colors
  • Can be used to modify core block styles
  • Can be used to add additional CSS

18

19 of 40

Developing block themes

19

20 of 40

Custom blocks: theme or plugin?

  • Almost always, plugins
  • If the blocks are highly coupled with the theme; maybe in theme
  • Blocks should not rely on theme functionality

20

21 of 40

Directory Structure

your-blocks-plugin

├── assets/ // non-php code

│ ├── block-extensions/ // extensions for core blocks

│ ├── block-variations/ // variations for core blocks

│ ├── blocks/ // your custom blocks javascript

│ ├── js/ // other scripts

│ ├── styles/ // css

│ └── lib/ // utilities

├── inc/ // usually php code

│ ├── classes/ // plugin-related functionality

│ ├── helpers/ // helper functions

│ └── traits/ // we use singleton trait

├── tests/

└── your-blocks-plugin.php

​

21

22 of 40

theme.json

  • theme.json is powerful!
  • Understanding the capability is important
  • Helps achieve
    • Consistency
    • Configurability
    • Variability (Style Variations)
    • Templatization
  • Define as many styles to theme.json as possible
  • See WordPress Docs

22

23 of 40

Use Fluid Typography

  • The old approach: media queries
    • hard to account for all screen sizes
    • hard to maintain multiple media queries
  • Fluid Typography
    • Improved UX
    • Easy to maintain
    • Greater design freedom
    • Greater flexibility
    • Improved A11Y

23

24 of 40

Use Fluid Typography [cont’d…]

24

.text {

font-size: clamp(min-value, pref-value, max-value);

}

"settings": {

"typography": {

"fluid": true,

"fontSizes": [

{

"name": "Medium",

"slug": "medium",

"size": "2.375rem", // preferred value

"fluidSize": {

"min": "1.875rem", // used below 768px

"max": "2.375rem" // used above 1600px

}

}

]

}

}

​

25 of 40

Use block.json

  • Standard way to register block types (PHP or JS)
  • Allows code sharing between PHP and JS
  • Simplifies server-side registration of blocks (useful for Block Type Endpoint)
  • Asset enqueuing optimization
    • only be enqueued when the block is present on the page
    • reduced page sizes
  • See WordPress Docs

25

26 of 40

Extending Core Blocks vs Custom Blocks

26

Core Blocks

Custom Blocks

Avoid recreating the wheel by making the most of existing features; saves time

Developers have more control over the final product.

Streamlines the development process for faster production and delivery

Poses less risk for disruption from breaking changes in WordPress core.

Can benefit from future enhancements to the WordPress core block

Developers typically have a lot of experience in developing new blocks.

27 of 40

Adding Video Controls to Cover Video

Case Study

27

28 of 40

Use Internationalization (i18n)

  • Everyone knows why it is important.
  • Jeder weiß, warum es wichtig ist.
  • 每個人都知道為什麼它很重要。
  • ہر کوئی جانتا ہے کہ یہ کیوں ضروری ہے۔
  • हर कोई जानता है कि यह क्यों महत्वपूर्ण है।

28

29 of 40

Use WordPress Components

  • Always try to use @wordpress/components for editor UI
  • Improves Editorial Experience (EX):
    • Consistent with the rest of the admin pages
    • Familiar functionality
    • Saves a ton of time
  • See Storybook

29

30 of 40

Never compromise on code quality

  • For JavaScript:
    • ESLint (@wordpress/eslint-plugin/recommended-with-formatting)
  • For PHP:
    • PHPCS (PHP Coding Standards)
    • PHPCBF (PHP Code Beautifier and Fixer)
  • For CSS or other flavors:
    • Stylelint (@wordpress/stylelint-config/scss)

30

31 of 40

Structure your block code properly

  • Blocks are usually JS/React-heavy
  • Use structure and naming standards in JS ecosystem

31

32 of 40

Documentation is key (and the lock)

  • Developers usually struggle with documentation
  • Use doc-comments and inline-comments
  • Don’t beat around the bush!
  • Good comment:
    • Explain intent
    • Warn of consequences
    • Use identifiers: @todo etc

32

33 of 40

Improving Site Experience

33

34 of 40

Site = Editor + Frontend

34

35 of 40

Keeping Responsiveness in Mind

  • Block editor lacks out-of-box responsive controls
  • It is a double-edged sword:
    • Nice-to-have for editors
    • Nightmare for developers and designers
  • Designers:
    • Keep the layouts intuitive and follow natural flow
    • Define breakpoints (and stick to them)
    • Recommended breakpoints: 1920px, 1470px, 1280px, 768px, 360px*
  • Developers:
    • Hope that the designers do a good job 🤞
    • Always use relative units (rem, %, vh, vw, etc.)
    • Be ready to write media queries
    • May need to use plugins (like Block Visibility)

35

36 of 40

Keeping Responsiveness in Mind [cont’d…]

​

36

>=1280px

<1280px

37 of 40

Accessibility

  • Cross-check the order of headings (use Outline in the editor)
  • Do not miss out on the alt attribute
  • Make sure that your content is keyboard-accessible (for devs: tabindex)
  • Make use of ARIA attributes
  • Ensure that the contrast is WCAG-compliant
  • If you’re overriding element behavior, use role attribute

37

38 of 40

Final Words

  • Plan your website properly
  • Gutenberg is powerful, it is just misunderstood
  • Honest opinion: for certain use-cases, Gutenberg makes no sense
  • Learn about the core functionality; there is usually a WordPress way
  • Follow D.R.Y and K.I.S.S
  • Keep accessibility and performance in mind
  • Contribute to the community!

38

39 of 40

Questions?

39

40 of 40

Thank you!�See you on 23.01.2025

40