Create Block Gutenpride Tutorial is out of Sync with Create Block Starter Template

[jessynd]

Describe the bug
The Create Block tutorial walks users through how to create the Gutenpride block using the create-block package starter block template (npx @wordpress/create-block starter-block). The tutorial takes a CSS-first approach to styling a block and provides further instruction for users wanting to integrate Sass into their block. However, the starter template does not contain the CSS files the tutorial refers to. The template is SCSS-first. This is confusing to people following the tutorial since the files the tutorial refers to, do not match the template the tutorial starts with. This inconsistency might cause people to give up on completing the tutorial.

Furthermore, if the user ignores the mismatched files and continues on to complete the block using SCSS, when including the custom font's .otf file, webpack fails to compile the files correctly. The user has to extend the webpack.config.js file from @wordpress/scripts by creating their own file in the block and adding loading rules to compile the font. The process for making the SCSS method work is explained in the edits to the original tutorial suggested here. The edits show one method to extend the webpack config in order for the custom font to work.

An additional issue with the Gutenpride Create Block tutorial is that the colour font used is not accessible in Twenty Twenty or Twenty Twenty One themes due to the varying colour contrasts of the multi-coloured font.

To reproduce
Steps to reproduce the behavior:

1. Go to Create Block tutorial and follow the steps all the way to the CSS portion.
2. Notice that when the starting command npx @wordpress/create-block starter-block is run, the resulting template is set up to run with SCSS, and not plain CSS from the start.
3. Notice that the tutorial is set up to start with CSS files and only provides SCSS as an alternative instead of the default.
4. Notice the error when SCSS is compiled and the otf custom font file does not compile.
5. Compare to the suggested amendment to the tutorial SCSS section.

Expected behavior

1. The create-block block template that npx @wordpress/create-block generates should be CSS-first.
2. The tutorial should expand on the existing instructions for using SCSS in the template and provide information on how to extend the webpack.config.js file in @wordpress/scripts in order to compile otf files or files with other possible formats. Suggested edits here.
3. The tutorial should use a font that is accessible in the latest two core themes: Twenty Twenty and Twenty Twenty One or provide the user a disclaimer that the font should be checked for colour contrast WCAG recommendations when used.
4. Since otf fonts do not work on all browsers, it might be worth exploring a different font format altogether to make it more inclusive.

Editor version :

• WordPress version: 5.5.3
• Does the website has Gutenberg plugin installed, or is it using the block editor that comes by default? Gutenberg Plugin
• If the Gutenberg plugin is installed, which version is it? 9.5.0

Desktop :

• OS: macOS Mojave
• Browser: Firefox
• Version 83.0

[jessynd]

@gziolo, I would appreciate any feedback you might have on this issue.

[gziolo]

@jessynd, thank you for the report. I don't think we ever aligned @wordpress/create-block with the tutorial you referred to. I personally agree that we should at least provide a template option to generate the same project as this tutorial walks you through. The good news is that starting next week, it should be possible to use 3rd party templates with @wordpress/create-block so that would be one option. We should seriously consider using it as a default block scaffolded though. The one that exists at the moment is more like a documentation which has its own benefits as well, but maybe we can combine it together.

Regarding fonts, let's figure out first what type and format of fonts we can use instead, that are both accessible and work with all browsers supported by WordPress Core. The remaining question is whether this font was added to show how to extend webpack config or because handling in @wordpress/scripts is missing. @mkaz is probable the best person to tell 😃

[jessynd]

@gziolo thanks for your feedback! I think creating a 3rd party template that works specifically for this tutorial would be a good solution. That said, since this tutorial is currently the first introduction to the create-block package in the Block Editor Handbook, I wonder whether it would be more beginner-friendly for the default create-block template to contain style.css and editor.css files as defaults, which would work well with the tutorial, and then provide instructions on how to use SCSS files if desired, or direct people to a 3rd-party SCSS-based template/give an scss option like it currently has for es5. Something like npx @wordpress/create-block --template scss What do you think?

Regarding the otf font, I agree that it's helpful that it requires for the webpack config file to be extended as a learning tool but that is currently not explained in the tutorial. I suggested some changes to the tutorial here which I did not submit as a PR officially because my suggested changes only make sense if the original @wordpress/create-block template OR an alternative 3rd party template used in the tutorial is changed to be CSS-first. This is my first time commenting on anything in the gutenberg repo so if it would help you/@mkaz for me to submit my suggested changes as a PR on the original tutorial and discuss there, I'm happy to do so.

[gziolo]

Regarding fonts, it feels like we should consider adding native support regardless of the tutorial changes. We discussed it during the weekly Core JS chat and it's now tracked in #27581. This would greatly simplify the tutorial as well 😄
In the referenced issue, there is another proposal to add handling for images as well which we should consider.

Regarding the @wordpress/create-block template, I'd like to hear from @mkaz first. Both approaches are doable but they also have pros and cons.

[mkaz]

The color font was picked for pride and it was a bit of fun. Yes, it doesn't work in all browsers, but the point of the tutorial is to learn how to build a block in Gutenberg, not necessarily to ship something as a plugin. With that set, the examples should adhere to or at least call out to any usability issues. So I agree, at the least, I think mentioning color contrast consideration.

As far as SCSS first, that probably is best because it is intended as an introductory block.

I think submitting as a PR and commenting there is probably easiest all around.

Thanks for the thoughtful reply and keeping the tutorial up to date 👍

[jessynd]

@mkaz and @gziolo, thank you for your comments and suggestions. I've created a PR to update the tutorial so that it remains accurate while these other issues are addressed. #27749

[mkaz]

Note: PR #30353 just merged that addressed some of these issues. I think we still need a conflict updated on PR #27749 to be able to merge in your changes and wrap up this issue.

[gziolo]

I added all necessary changes to close this issue in #39049.