Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Templates, patterns, `theme.json` and CSS are served as they are in the tree. Th
Read only what your task needs, when it needs it:

- **Styling, or building pages, patterns or templates**: read [DESIGN.md](DESIGN.md) first. It covers the color roles, the type and spacing scales, the style variations, and which pattern fills each template and part.
- **Adding or changing a pattern**: read [Pattern creation guidelines](https://github.com/WordPress/ipsum/blob/trunk/CONTRIBUTING.md#pattern-creation-guidelines) first. It covers categories, hiding from the inserter, which i18n function to use, images, and removing `id`, `queryId`, `theme`, `area`, `patternName` and `metadata.categories` from copied markup.
- **Adding or changing a pattern**: read [Writing patterns](DESIGN.md#writing-patterns) in DESIGN.md first. It covers categories, hiding from the inserter, which i18n function to use, images, and removing `id`, `queryId`, `theme`, `area`, `patternName` and `metadata.categories` from copied markup.
- **Adding CSS or PHP**: read [Development guidelines](https://github.com/WordPress/ipsum/blob/trunk/CONTRIBUTING.md#development-guidelines). Prefer `theme.json` and Global Styles; add CSS or PHP only when the editor cannot express the design, and keep it commented.

## Markdown files
Expand Down
115 changes: 1 addition & 114 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,120 +88,7 @@ Don't edit `style.min.css` by hand. CI rebuilds it and fails the pull request if

### Pattern creation guidelines

[Reference guide for patterns in the handbook](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/).
A few things to have in mind when building patterns for the default theme:

- **Category selection**

When creating WordPress block patterns, it's important to carefully choose the appropriate category for your pattern. WordPress provides a set of default categories, each serving a specific purpose. Let's stick to using the default categories, with two exceptions registered in `functions.php`: full page layouts go in the theme's own `ipsum_page` category (labeled "Pages"), and post format patterns in `ipsum_post-format` (labeled "Post formats"). We can add multiple of them separating them by commas. The list of the slug is [here](https://github.com/WordPress/gutenberg/blob/c20350c1d246163201375f090b0b7b4ab49b1dad/packages/block-editor/src/components/inserter/block-patterns-tab.js#L35).

- **Hiding patterns from the inserter**

You can control the visibility of your block pattern in the inserter by adding the following line of code when registering the pattern:

We do this for patterns we don't want the user to access via the inserter or the pattern library. This is usually the case for utility patterns that we create for translation purposes such as the 404 pattern.

We do this by adding the following line:

` * Inserter: no`

Let's prefix hidden patterns using `hidden-` when we name the pattern file.

Hidden patterns still need a `Title` and a `Description`, since agents read them through the REST API (`/wp/v2/block-patterns/patterns`). Say which template or template part the pattern fills and what it holds. As in every description, use full sentences instead of dashes: what the pattern is, then a second sentence saying what's in it. Template patterns take `Template Types:`, and header, footer and navigation overlay patterns take `Block Types: core/template-part/<area>`. Patterns for General parts, like the sidebar and the search bar, leave out `Block Types`, or the Site Editor offers each one as a design for every other General part.

- **Different translation functions and when to use them**

WordPress block patterns should be [internationalized](https://developer.wordpress.org/apis/internationalization/internationalization-guidelines/) to make them accessible to a global audience.

`esc_html_x()`: Employ this function when you need to translate and escape text for display within HTML. It's useful for multilingual websites as it provides translation support while also ensuring HTML safety.

`esc_html__()`: Similar to `esc_html_x()`, use this function for translating and escaping HTML-embedded text. It's a simpler version when context-specific translations are not needed.

`esc_attr__()` and `esc_attr_x()`: Use this function to escape and sanitize text meant for HTML attributes, such as image source URLs or link targets. It helps prevent security vulnerabilities by ensuring that user inputs are safe for use in attributes.

`esc_html_e`: works just like `esc_html__()` but you don't need to use `echo` to output the string

When we have simple HTML tags in our translatable strings we would use `echo wp_kses_post( __( 'Lorem ipsum <em>Hello</em> dolor sit amet.', 'textdomain' ) );`. This syntax is clearer for translators than using `sprintf()` and it allows them to remove the markup if it doesn't work on their own language.

These functions enhance security and support localization efforts in WordPress block patterns, ensuring that text is safe and can be easily translated.

- **Patterns with images**

To create dynamic image links in your block patterns, pass the image's path within the theme to the `get_parent_theme_file_uri()` function. It returns the URL of that file in Ipsum's directory, ensuring that the image links work correctly even if the website's directory structure changes or if we are using a child theme. The URL can also be filtered with `parent_theme_file_uri`, such as to serve the images from a CDN.

Don't add a `?ver=` query argument to image URLs. The images won't change after release, and once a pattern is inserted, its image URL is saved in the post, so the version would never update there anyway.

Make sure to add alt text to your images and to make sure to remove the IDs from them. An example would be:

```
<!-- wp:image {"id":125,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="http://wp-stable.test/wp-content/themes/twentytwentyfive/assets/images/project.webp" alt="" class="wp-image-125"/></figure>
<!-- /wp:image -->
```

would turn into

```
<!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="<?php echo esc_url( get_parent_theme_file_uri( 'assets/images/project.webp' ) ); ?>" alt="<?php echo esc_attr_x( 'Picture of a building', 'Alt text for project picture', 'ipsum' ); ?>"/></figure>
<!-- /wp:image -->
```

- **Image license attribution**

When adding images to the theme, we need to add the license attribution to the readme.txt file.

- **Use of Post Types, Block Types and Template Types**

We use Block Types when the pattern uses custom markup for a specific block or one of the default template parts (footer and header). Using this will suggest the pattern when someone inserts said block or template part. This is commonly used for query, post-content block, template or footer.

Template Types is used when we want our pattern as a suggestion for a specific template. In this case we provide the template slug (404, home, single...)

Post Types is used to restrict the post type we want the pattern to be used for. commonly used for full page patterns.

- **Spacing, colors and font sizes**

Using presets for spacing, font sizes, and colors in WordPress block patterns is preferred over hardcoded values for three key reasons:

Consistency: Presets ensure a uniform design across the theme, promoting a cohesive visual identity.

Scalability: They make global design changes easier during development, saving time and effort.

Accessibility: Presets facilitate adherence to accessibility standards, making your patterns more usable and readable for a wider audience.

- **Other tips**

In the same way we remove IDs from image blocks, we need to remove queryId from query blocks too. Also, if any of our template parts have a theme or an area attribute, those need to be removed too. The area comes from `templateParts` in `theme.json`, so the slug is enough.

`<!-- wp:query {"queryId":18,"query":{"perPage":8,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->`

turns into

`<!-- wp:query {"query":{"perPage":8,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->`

and

`<!-- wp:template-part {"slug":"header-portfolio","theme":"ipsum","area":"header","tagName":"header"} /-->`

turns into

`<!-- wp:template-part {"slug":"header-portfolio","tagName":"header"} /-->`

The editor also writes `patternName` and `categories` into the metadata of blocks inserted from a pattern, and exports such as Create Block Theme keep them. The editor adds them back on insertion, so remove those two and keep the rest of the metadata, such as `name` or `bindings`:

`<!-- wp:group {"metadata":{"name":"Footer","patternName":"ipsum/footer","categories":["footer"]},"layout":{"type":"constrained"}} -->`

turns into

`<!-- wp:group {"metadata":{"name":"Footer"},"layout":{"type":"constrained"}} -->`

Block names (`metadata.name`) show in the List View and are what an agent reads to tell blocks apart, so name a block by what it does, not what it prints: a paragraph holding the `·` separator is `Meta Separator`, not `·`. Translate names like other strings: `esc_html_x( 'Meta Separator', 'Name of the paragraph separating post meta items', 'ipsum' )`.

If we are constantly assigning properties to the same block over and over again (ie: border radius to images), consider moving those properties to the theme.json.

When building full page patterns, let's prefix them by using page-

One way to control the order in which patterns are displayed in the inserter is by changing the name of the file (they are sorted alphabetically)
What a pattern needs ships with the theme, in [Writing patterns](DESIGN.md#writing-patterns) in DESIGN.md: file names, categories and headers, translatable strings, images, presets, cleaning up copied markup, and block names.

### Tips for Contributors

Expand Down
64 changes: 63 additions & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# DESIGN.md

How to design with Ipsum: what each preset is for, how the theme uses it, and what the style variations, templates, parts and block styles give you. [AGENTS.md](AGENTS.md) covers working on the theme's files.
How to design with Ipsum: what each preset is for, how the theme uses it, and what the style variations, templates, parts and block styles give you. [Writing patterns](#writing-patterns) covers what a new pattern needs. [AGENTS.md](AGENTS.md) covers working on the theme's files.

## Ipsum

Expand Down Expand Up @@ -251,3 +251,65 @@ The separator between meta items is built three ways, on purpose:
- **Where both neighbours always render** (post date · categories), it's a Paragraph named Meta Separator: small, weight 600, with the dot hidden from screen readers. The row's block gap (`spacing|20`) spaces it. To add one, copy it from an archive pattern.
- **Where the whole row can go** (comments link · call to action), it's the same Paragraph, and the `comments-meta` class hides the row when comments are closed.
- **Where a neighbour may not render**, it's the Dot Separator style. The Edit link only renders for people who can edit the comment, and the Reply link only when threading allows it, so a Paragraph would be left behind as a stray dot. Use the Paragraph wherever it's safe: unlike the style's dot, it can be translated.

## Writing patterns

What a pattern in Ipsum needs, on top of the [block patterns reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/).

### Files and headers

- **File names:** full page layouts take the `page-` prefix, and patterns that only fill a template or part take `hidden-`. The inserter sorts patterns by file name, so the name also sets their order.
- **Categories:** use the [default categories](https://github.com/WordPress/gutenberg/blob/c20350c1d246163201375f090b0b7b4ab49b1dad/packages/block-editor/src/components/inserter/block-patterns-tab.js#L35), separated by commas, plus the two that `functions.php` registers: `ipsum_page` (Pages) for full page layouts and `ipsum_post-format` (Post formats) for post format patterns.
- **Hiding from the inserter:** a pattern people shouldn't insert on its own, such as one that only fills a template or part, or one that exists to make a template's text translatable, like the 404 pattern, carries ` * Inserter: no`.
- **Title and Description:** every pattern needs both, hidden ones too, since agents read them through the REST API (`/wp/v2/block-patterns/patterns`). Write full sentences, not dashes: what the pattern is, then a second sentence on what's in it. A hidden pattern says which template or template part it fills.
- **Block Types:** suggests the pattern when someone inserts that block or template part, such as a Query, Post Content, header or footer. Header, footer and navigation overlay patterns take `Block Types: core/template-part/<area>`. Patterns for General parts, like the sidebar and the search bar, leave it out, or the Site Editor offers each one as a design for every other General part.
- **Template Types:** suggests the pattern for a template, by slug (`404`, `home`, `single` and so on). Every template pattern takes it.
- **Post Types:** limits the pattern to those post types, usually for full page patterns.

### Strings

Every user-visible string goes through an [i18n function](https://developer.wordpress.org/apis/internationalization/internationalization-guidelines/) with the `ipsum` text domain, so it's translatable and escaped:

- `esc_html__()` translates and escapes text shown in HTML, and `esc_html_x()` does the same with a context for translators. `esc_html_e()` echoes it as well.
- `esc_attr__()` and `esc_attr_x()` translate and escape text that goes in an HTML attribute, such as alt text.
- For simple HTML inside a string, use `echo wp_kses_post( __( 'Lorem ipsum <em>Hello</em> dolor sit amet.', 'ipsum' ) );`. It's clearer for translators than `sprintf()`, and they can drop the markup where it doesn't work in their language.

### Images

- Build image URLs with `get_parent_theme_file_uri()` and the image's path in the theme. The URL then works wherever the site lives and from a child theme, and it can be filtered with `parent_theme_file_uri`, for example to serve the images from a CDN.
- Don't add a `?ver=` query argument. The images won't change after release, and once a pattern is inserted, its image URL is saved in the post, so the version would never update there anyway.
- Give every image translated alt text, and remove its ID, both the `id` attribute and the `wp-image-<id>` class.
- Credit every image's license under `== Images ==` in `readme.txt`.

An image copied from the editor:

```html
<!-- wp:image {"id":125,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="http://wp-stable.test/wp-content/themes/ipsum/assets/images/project.webp" alt="" class="wp-image-125"/></figure>
<!-- /wp:image -->
```

becomes:

```html
<!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="<?php echo esc_url( get_parent_theme_file_uri( 'assets/images/project.webp' ) ); ?>" alt="<?php echo esc_attr_x( 'Picture of a building', 'Alt text for project picture', 'ipsum' ); ?>"/></figure>
<!-- /wp:image -->
```

### Presets

- Use the spacing, font size and color presets, never fixed values. They keep the design consistent, let a style variation or Global Styles change it in one place, and keep patterns readable for more people. The sections above say what each preset is for.
- If you keep setting the same property on the same block, such as a border radius on images, move it to `theme.json`.

### Cleaning up copied markup

Markup built in the editor, or exported with a tool like Create Block Theme, carries attributes that don't belong in a pattern. Remove them; the editor adds back what it needs when the pattern is inserted.

- **`queryId` on Query blocks**, like the image IDs above: `<!-- wp:query {"queryId":18,"query":{"perPage":8,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->` becomes `<!-- wp:query {"query":{"perPage":8,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->`.
- **`theme` and `area` on template part blocks.** The area comes from `templateParts` in `theme.json`, so the slug is enough: `<!-- wp:template-part {"slug":"header-portfolio","theme":"ipsum","area":"header","tagName":"header"} /-->` becomes `<!-- wp:template-part {"slug":"header-portfolio","tagName":"header"} /-->`.
- **`patternName` and `categories` in block metadata.** The editor writes them into blocks inserted from a pattern. Keep the rest of the metadata, such as `name` or `bindings`: `<!-- wp:group {"metadata":{"name":"Footer","patternName":"ipsum/footer","categories":["footer"]},"layout":{"type":"constrained"}} -->` becomes `<!-- wp:group {"metadata":{"name":"Footer"},"layout":{"type":"constrained"}} -->`.

### Block names

Block names (`metadata.name`) show in the List View, and they're what an agent reads to tell blocks apart. Name a block by what it does, not what it prints: the paragraph holding the `·` separator is `Meta Separator`, not `·`. Translate names like other strings: `esc_html_x( 'Meta Separator', 'Name of the paragraph separating post meta items', 'ipsum' )`.
Loading