Fix/10up block theme readme by pdavies88 · Pull Request #321 · 10up/wp-scaffold

pdavies88 · 2026-03-25T05:01:29Z

Description of the Change

For the 10up-block-theme it performs the following:

Adds in READMEs for context on the theme
Update dependencies to latest versions
Converts JS to TS
Provides Example Custom Block
Fixes naming mismatching in Theme

Closes: N/A

How to test the Change

Can be pulled into a local WP build and run and function as normal

Changelog Entry

Added - README for 10up-Block-Theme and a Example Custom Block
Changed - JS file to TS, theme naming mismatching, and updated dependencies in the theme
Removed - styles folder as it could cause confusion between assets folder

Credits

Props @pdavies88

Checklist:

I agree to follow this project's Code of Conduct.
I have updated the documentation accordingly.
I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
All new and existing tests pass.

pdavies88 · 2026-03-25T05:04:23Z

@fabiankaegy will add some time on our calendar to chat further. But at least wanted to get a draft started of a robust README on the Theme itself as team members may use it on a one off and want to know how it works. Also saw we hadn't updated the dependencies for awhile and the project was still using JS. Anywho feel free to add comments and guidance but wanted to get the wheels turning to get your thoughts.

fabiankaegy

Thanks so much for getting this started @pdavies88 🚀

Left a bunch of notes inline and also pinned @darylldoyle & @claytoncollie for additional thoughts :)

fabiankaegy · 2026-03-25T06:46:52Z

themes/10up-block-theme/assets/js/block-filters/index.ts

Big fan of making this change official in the theme here 👍

Something I always needed to do in projects though is add the following to the .eslintrc file:

{ "parser": "@typescript-eslint/parser", "extends": ["@10up/eslint-config/wordpress"], "plugins": ["@typescript-eslint"], "rules": {} }

fabiankaegy · 2026-03-25T06:49:27Z

themes/10up-block-theme/blocks/README.md

Do you really think there is value in having the example block back in here?

Part of the reason why I removed it was that I ended up seeing it nor removed on client projects. And since we have the scaffold:block command in the theme here I always found it nicer / easier to just have that present.

fabiankaegy · 2026-03-25T06:51:04Z

themes/10up-block-theme/patterns/base-card.php

I'd actually be in favor or removing this because it's also something we always have to remove and folks forget that :/

themes/10up-block-theme/blocks/example-block/index.ts

fabiankaegy · 2026-03-25T06:55:33Z

themes/10up-block-theme/styles/surface-primary.json

I know it goes against what I was saying above, but I would like to keep these here.

Section styles is an under utilized feature in my opinion so I want users of this theme to wonder about it and start to learn more about them.

See https://ignitewp.10uplabs.com/block-styling-and-css/#section-styles-in-ignite

fabiankaegy · 2026-03-25T07:10:01Z

themes/10up-block-theme/README.md

+- `register_theme_blocks()` scans `dist/blocks/*/block.json` and calls `register_block_type_from_metadata()` for each found block.
+- `allowed_block_types_all` filter extends allowed blocks with theme blocks.
+- `enqueue_theme_block_styles()` scans `dist/blocks/autoenqueue/**/*.css` and registers/enqueues style/script for each block with assets info from `GetAssetInfo`.
+- includes block render filter for TenUp navigation block (removes ARIA roles for fallback markup compatibility).


Not sure I understand what's meant by this

fabiankaegy · 2026-03-25T07:10:19Z

themes/10up-block-theme/README.md

+- `enqueue_theme_block_styles()` scans `dist/blocks/autoenqueue/**/*.css` and registers/enqueues style/script for each block with assets info from `GetAssetInfo`.
+- includes block render filter for TenUp navigation block (removes ARIA roles for fallback markup compatibility).
+
+### 6.2 Blocks directory structure


Let's mention the scaffold command here

fabiankaegy · 2026-03-25T07:11:29Z

themes/10up-block-theme/README.md

+
+### 7.2 Theme script inclusion
+
+- `src/ThemeCore::theme_setup()` calls `add_theme_support('editor-styles')` and `add_editor_style('/dist/css/frontend.css')`.


This is only for editor stuff. From the heading I would have expected something about the Asset trait from the framework and how to enqueue things

themes/10up-block-theme/README.md

fabiankaegy · 2026-03-25T07:12:59Z

themes/10up-block-theme/README.md

+
+## 16. Further notes
+
+- This theme is designed around a 10up block theme pattern (colors, spacing, utilities, templates).


Not sure I understand what is meant by this

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

claytoncollie · 2026-04-10T06:14:51Z

themes/10up-block-theme/assets/README.md

@pdavies88 I don't agree with having smaller readme's throughout the codebase that can easily become out of date. I think this either should be a CLAUDE.md file (still run into same out of date issue) or place all of this into the root README/CLAUDE.md files.

claytoncollie · 2026-04-10T06:16:11Z

themes/10up-block-theme/blocks/example-block/block.json

@pdavies88 I agree with @fabiankaegy that we should not provide an example block here as people do not take ownership and make sure it gets deleted. We have so many resources to scaffold this ou either with a cli or the documentation at gutenberg.10up.com

claytoncollie · 2026-04-10T06:16:52Z

themes/10up-block-theme/blocks/README.md

@pdavies88 same thing here. Either a CLAUDE.md file or we consilidate into the main readme

claytoncollie · 2026-04-10T06:18:27Z

themes/10up-block-theme/package.json

 			"blocksDir": "./blocks"
 		}
+	},
+	"optionalDependencies": {


@fabiankaegy Does 10up toolkit already load these?

claytoncollie · 2026-04-10T06:19:53Z

themes/10up-block-theme/README.md

+
+## 2. Requirements
+
+- PHP >= 8.2


@fabiankaegy we should bump this to 8.4 IMO cc @pdavies88

claytoncollie · 2026-04-10T06:20:09Z

themes/10up-block-theme/README.md

+## 2. Requirements
+
+- PHP >= 8.2
+- Node >= 18


@fabiankaegy we should bump this to v24 IMO cc @pdavies88

claytoncollie · 2026-04-10T06:20:27Z

themes/10up-block-theme/README.md

+
+- PHP >= 8.2
+- Node >= 18
+- Composer


@pdavies88 if we are putting versions, this should be Composer 2

claytoncollie · 2026-04-10T06:21:25Z

themes/10up-block-theme/README.md

+npm run build
+```
+
+### 4.2 Local development


@pdavies88 this totally ignore PHP commands in composer.json. we should treat both PHP and JS/CSS as equal partners

claytoncollie · 2026-04-10T06:21:48Z

themes/10up-block-theme/README.md

+### 4.2 Local development
+
+- `npm run watch` (or `npm start`) → 10up-toolkit watch with HMR/hot-refresh
+- `composer exec phpcs -- --standard=WordPress` → PHP lint


@pdavies88 should be composer run lint

claytoncollie · 2026-04-10T06:23:19Z

themes/10up-block-theme/README.md

+### 4.3 Common gotchas
+
+- Always build `dist/` after changing source assets (`assets/`, `blocks/`, `src/`).
+- If using a check-in strategy for `dist/`, ensure CI runs `npm run build` before release.


@pdavies88 this is very nuanced and vague. I think we remove. this assumes too much about deployment which can be varied

claytoncollie · 2026-04-10T06:23:44Z

themes/10up-block-theme/README.md

+- Always build `dist/` after changing source assets (`assets/`, `blocks/`, `src/`).
+- If using a check-in strategy for `dist/`, ensure CI runs `npm run build` before release.
+- `theme.json` is the source of truth for editor styles, palette, and layout. Adjust there for global styles.
+- Some references may still use legacy naming in older helper docs; prefer 10up-block-theme naming in code changes.


@pdavies88 can we remove this? I though we caught all of the instances.

claytoncollie · 2026-04-10T06:24:29Z

themes/10up-block-theme/README.md

+### 4.1 Quick start (repeat for copy/paste)
+
+```bash
+cd /path/to/themes/10up-block-theme


@pdavies88 you should not have to do this operation. Both NPM and Composer work from the wp-content directory to install and build all assets, not just the theme

claytoncollie · 2026-04-10T06:25:39Z

themes/10up-block-theme/README.md

+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url> 10up-block-theme


@pdavies88 I think we are getting too specific here for a theme only setup, and not sticking to the original intent of the repo which covers a large majority of use cases. Most projects use this entire scaffold, not just the theme cc @fabiankaegy

claytoncollie · 2026-04-10T06:28:01Z

themes/10up-block-theme/README.md

@pdavies88 sorry, i am just not seeing this is the theme readme. I think this is going to throw people off the main path. I appreciate that some projects only use the theme, but a vast majority will use the entire scaffold. Fabian has spent a lot of time making things run from the wp-content directory link install and built and scaffold commands and now we are bypassing all of that work. I think it is fine to explain this theme, but then say to reference the main readme for scaffold and install instructions. cc @fabiankaegy

claytoncollie · 2026-04-10T06:30:11Z

themes/10up-block-theme/README.md

+
+---
+
+## 5. Core bootstrapping path


@pdavies88 Similar to what we are finding with AGENTS.md and CLAUDE.md file, this information can go stale over time. I think all of this function reference should be removed from here in favor of docblocks on the class or methods it relates to.

claytoncollie · 2026-04-10T06:30:52Z

themes/10up-block-theme/README.md

+- `npm install`
+- `npm run watch`
+- `npm run build`
+- `composer exec phpcs -- --standard=WordPress`


Suggested change

- `composer exec phpcs -- --standard=WordPress`

- `composer run lint`

claytoncollie · 2026-04-10T06:31:31Z

themes/10up-block-theme/README.md

+
+---
+
+## 16. Further notes


@pdavies88 I think we can remove this section. feels redundant after all that is said eariler

claytoncollie · 2026-04-10T06:32:35Z

themes/10up-block-theme/README.md

+
+---
+
+## 15. Helpful commands summary


@pdavies88 I think we can remove this section. This is the third instance where we are listing the same commands.

claytoncollie · 2026-04-10T06:32:47Z

themes/10up-block-theme/README.md

+
+---
+
+## 14. Key entrypoints quick map


@pdavies88 do we need an entry point for CSS?

claytoncollie · 2026-04-10T06:33:12Z

themes/10up-block-theme/README.md

+
+---
+
+## 13. Maintenance tasks


@pdavies88 can we consolidate these commands into the earlier list at the start of this file?

pdavies88 added 2 commits March 24, 2026 16:37

fix: init README baseline for theme

b8cce98

feat: add example block, updated README, and newest NPM packages

ca12766

pdavies88 self-assigned this Mar 25, 2026

pdavies88 requested a review from fabiankaegy March 25, 2026 05:01

fabiankaegy requested review from claytoncollie and darylldoyle March 25, 2026 06:45

fabiankaegy requested changes Mar 25, 2026

View reviewed changes

pdavies88 and others added 5 commits April 9, 2026 20:44

Update themes/10up-block-theme/blocks/example-block/index.ts

9d5f38c

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/templates/README.md

ede7918

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/templates/README.md

88fda3d

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/parts/README.md

81f246c

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/README.md

965f336

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

claytoncollie reviewed Apr 10, 2026

View reviewed changes


		### 7.2 Theme script inclusion

		- `src/ThemeCore::theme_setup()` calls `add_theme_support('editor-styles')` and `add_editor_style('/dist/css/frontend.css')`.


		## 16. Further notes

		- This theme is designed around a 10up block theme pattern (colors, spacing, utilities, templates).

	- `composer exec phpcs -- --standard=WordPress`
	- `composer run lint`

Conversation

pdavies88 commented Mar 25, 2026

Description of the Change

How to test the Change

Changelog Entry

Credits

Checklist:

Uh oh!

pdavies88 commented Mar 25, 2026

Uh oh!

fabiankaegy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants