Following the tips and examples in this article:
https://matthewhorne.me/defer-async-wordpress-scripts/

It would be great to add a lib that would provide the functionality to add async or defer on to generated script tags that may be render blocking in order to optimize page performance.

With Webpack, it should be possible to split up our JS code into two separate files, one ES5 and one ES6. Assuming the majority of 10up will write their code in ES6 anyways to take advantage of the new features it brings, we can make it so we deliver an appropriate package and more performant JS to ES6 capable browsers. ES6 browsers will benefit by having both smaller payload (and hence load time), as well as faster execution. ES5 browsers will continue to get the experience they do now.

This approach was shared in our Slack chat some time ago (https://10up.slack.com/archives/G11CA43FW/p1534367275000100), but the article that outlines the approach is: https://philipwalton.com/articles/deploying-es2015-code-in-production-today/

FILE: ...fault\public_html\wp-content\themes\eats-theme\includes\core.php

FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE

121 | WARNING | This comment is 75% valid code; is this commented
| | out code?

There is a _doing_it_wrong()? comment in the script_loader_tag function.

Solutions:
Not necessarily a big issue, but can be annoying. The comment could either ignore the rule for this particular line. Alternatively revising the comment text, or removing it completely would also work. It is not fully clear what the comments are indicating.

update this and use it: https://github.com/10up/eslint-config

Is there any reason why the package-lock.json is not being tracked in this repo?

Make sure the build process will function in the current asset-based structure and also a component-based structure: https://codepen.io/timwright12/pen/vagYrE

We don't need this component in the library now that we have scaffolding: https://10up.github.io/wp-component-library/component/search-action/index.html

Same for the search results:
https://10up.github.io/wp-component-library/component/search-results/index.html

We can probably safely add basic stuff like: front-page.php, page.php, and single.php into the scaffolding. Thoughts? @daveross @magnificode

I'd also like to add a default template for a styleguide in /templates/page-styleguide.php with a default layout and initial HTML/hooks. We have some functions that will automatically pull in the colors and such to semi-automate the barebones styleguide for a project.

e.g. npm install node@8

With Vue and React becoming more prominent in our workflow.
Could we perhaps incorporate storybooks into our theme scaffolding?

There are quite a few benefits having it:

• A visual library of all UI components that are available on the project.
• ( Helps any on coming engineers to know what components are pre-built and what the possible restraint of each component might have )
• Will help give LOE to existing components.
• Will force Engineers to build components as pure stand-alone components. Forcing the correct use of props.
• There are useful Addons, one being Accessablity Testing among others.

The current theme doesn't have a default thumbnail and it's weird. Create a PNG image that’s 880 pixels wide x 660 pixels tall. Save that image as screenshot.png. Probably use the 10up logo with a white background.

Thoughts on including wordpress.css within base folder to include standard WordPress generated classes? Few that I can think of that every project should include are alignments(.alignleft, .alignright, .aligncenter, etc) and images(.wp-caption, .wp-caption-text). I find my self adding this on just about every project and I usually see this file in just about all other project.

I can work on a PR for this.

gulp-notify

Send messages to Mac Notification Center, Linux notifications (using notify-send) or Windows >= 8 (using native toaster) or Growl as fallback, using the node-notifier module. Can also specify custom notifier.

Use case: how many times have you been dev’ing (npm run watch) along only to realize there are errors in the console and things stopped compiling? Why not get a friendly and helpful notification instead?

https://github.com/browserslist/browserslist

Browsersync

Browsersync has more features, like:

• Interaction Sync - Your scroll, click, refresh and form actions are mirrored between browsers while you test.
• Network Throttle - Test your website against a slower connection. Even when devices are connected to wifi.
• File Sync - Browsers are automatically updated as you change HTML, CSS, images and other project files.

style.css is importing empty files and postcss-import warning shows up when running npm commands:

postcss-import: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/style.css:15:1: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/base/index.css isempty
postcss-import: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/style.css:18:1: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/layout/index.css is empty
postcss-import: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/style.css:21:1: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/templates/index.css is empty
postcss-import: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/style.css:24:1: /Users/SangMinYoon/Websites/playground/wordpress/wp-content/themes/theme-scaffold/assets/css/frontend/components/index.css is empty

I recommend commenting out imports and not removing them just like frontend.js (// import foo from './components/bar';). I especially recommend this for plugin-scaffold. Current project I'm on, we have the imports commented out since CSS for the plugin has not been added to the project.

Let me know if you want me to create a PR for this.

composer.lock file should be committed to our projects so that when we deploy them, we can run composer install and get a very specific set of package versions installed.

I could see maybe not wanting a composer.lock file in the scaffold repo, but we definitely want it in the repos that are generated as part of the scaffolding.

https://10up.github.io/Engineering-Best-Practices/structure/#file-organization

There is an issue in where the @apply feature only works once. See these tickets:

• MoOx/postcss-cssnext#397
• pascalduez/postcss-apply#34

In addition, the @apply rule sounds like it is no longer going to be included in future CSS spec at this time. From the plugin github:

The @apply rule and custom property sets most likely won't get any more support from browser vendors as the spec is yet considered deprecated and alternative solutions are being discussed.
Refer to following links for more infos:

https://discourse.wicg.io/t/needed-new-champion-for-css-apply-rule/2012
WICG/webcomponents#300 (comment)
http://www.xanthir.com/b4o00
w3c/csswg-drafts#1047

In both cases, the solution has been to use the "postcss-mixins" plugin instead: https://github.com/postcss/postcss-mixins

I think it may be a good idea to integrate this so we can retain the use of mixins. Additionally, in practice @apply acts more like an @extends versus a mixin, with no arguments. This should hold us over until a new standard is proposed and adopted.

In the <head>

<head>
    document.body.classList.remove('no-js'); // if it's there
    document.body.classList.add('js');
</head>

In the component:

document.getElementById('the-component').setAttribute('aria-hidden', 'true');

In the CSS (assuming you need this):

.js the-component[aria-hidden="true] {
    display: none;
}

This could potentially help progressively enhance and prevent content flashing for elements getting aria-hidden from JavaScript.

One potential method to implement this is adding add_filter( 'body_class', $n( 'body_classes' ) ); here: https://github.com/10up/theme-scaffold/blob/master/includes/core.php#L24

And then something like this at the bottom of includes/core.php

/**
 * Adds custom classes to the array of body classes.
 *
 * @link https://developer.wordpress.org/reference/functions/body_class/
 * @param array $classes Classes for the body element.
 * @return array
 */
function body_classes( $classes ) {
    // Adds "no-js" class. If JS is enabled, this will be replaced (by javascript) to "js".
    $classes[] = 'no-js';

    return $classes;
}

Then add this document.body.className = document.body.className.replace( 'no-js', 'js' ); in: https://github.com/10up/theme-scaffold/blob/master/assets/js/frontend/frontend.js

Or, method two:

Just update <body <?php body_class( 'no-js' ); ?>> in Theme Scaffold's header.php

This would still require adding the JavaScript to frontend.js

There are probably other ways to implement this.

Right now if you set any additional optimization options as part of the task runner in cssnano.js, those options are ignored. Our extra options currently line up with the tasks' default options.

Example
Create a style in the assets CSS like:

:root {
	--color-red: #f00;
}
.foo {
	appearance: none;
	border-color: var(--color-red);
	border-radius: 0;
	border-style: solid;
	border-width: 1px;
	display: block;
	height: 100px;
	padding-bottom: 1em;
	padding-left: 2em;
	padding-right: 2em;
	padding-top: 1em;
	transition: color 500ms ease-in-out;
	width: 100px;
}

Add mergeLonghand: false to the CSS nano task options and run npm run build. CSS nano should not be combining the border or padding rules. You will get output like:

:root {
	--c-black: #000;
	--c-white: #fff;
	--color-red: red
}

.foo {
	-webkit-appearance: none;
	-moz-appearance: none;
	appearance: none;
	border-color: red;
	border: 1px solid var(--color-red);
	border-radius: 0;
	display: block;
	height: 100px;
	padding: 1em 2em;
	transition: color .5s ease-in-out;
	width: 100px
}

As shown, the option is not respected. This actually causes a bug in IE11 where it will attempt to read all of the border property and fail to apply any of it. (Additional color vars are our defaults from variables.css).

Style Guide Template is a great feature. There could be short note on readme what does it mean:

• Create a new page and set the template “style guide”.
• Perhaps noting that this template can be extended for project needs. Adding Typography details and so on.

When I npm install on a freshly generated theme:

npm WARN deprecated [email protected]: gulp-util is deprecated - replace it, following the guidelines at https://medium.com/gulpjs/gulp-util-ca3b1f9f9ac5
npm WARN deprecated [email protected]: please upgrade to graceful-fs 4 for compatibility with current and future versions of Node.js
npm WARN deprecated [email protected]: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
npm WARN deprecated [email protected]: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
npm WARN deprecated [email protected]: please upgrade to graceful-fs 4 for compatibility with current and future versions of
Node.js

...

npm WARN deprecated [email protected]: Package no longer supported. Contact [email protected] for more info.
npm WARN deprecated [email protected]: 🙌  Thanks for using Babel: we recommend using babel-preset-env now: please r
ead babeljs.io/env to update!

We have linting command for JS and PHP: npm run lint-js and npm run lint-php. I don't see a reason why we shouldn't have check for npm run lint-css.

CSS lint should also be added to lint-staged. I can do PR if this is supported idea.

Doesn't seem like much of a reason to have them both hanging around at this point if we can get Webpack to do everything we need. Would love to hear some thoughts about it.

Currently, a Stylelint error is presented like so:

[20:41:24] 

assets/css/frontend/style.css
 29:14  ✖  Unexpected named color "red"   color-named



[20:41:24] 'lint-css' errored after 342 ms
[20:41:24] Error in plugin "gulp-stylelint"
Message:
    Failed with 1 error
Details:
    domainEmitter: [object Object]
    domain: [object Object]
    domainThrown: false

I think we should suppress most of this information, at least while watching the files. The only actual useful information is:

assets/css/frontend/style.css
 29:14  ✖  Unexpected named color "red"   color-named

The rest is pure noise.

Since our 10up best practices say we should localize string and we are already loading the text domain. It might be worth adding something like gulp-wp-pot for generating pot files
https://10up.github.io/Engineering-Best-Practices/php/#internationalization

@dainemawer Just making a note here about this for whenever you have the the time. No rush.

Feedback from the engineering council.

With WordPress 5.0 set for release, we should begin preparation for updating the scaffold to include support for Gutenberg block development within themes.

I'm proposing that we introduce a folder at the root of the theme, which would contain a list of block folders. Each block folder would contain all code pertaining to that block including PHP, JS and CSS.

|- components/
|    |- blocks.php________________________ # Include all PHP block files
|- components/block-name/
|    |- block.php_________________________ # If this requires PHP for dynamic block or whitelisting 
|    |- block.css_________________________ # Block CSS 
|    |- block.js__________________________ # Block code

Optionally, other components can live in the components/ folder, which can contain all reusable custom components which are included in the block JS.

|- components/
|    |- component-name.css______________ # Component CSS 
|    |- component-name.js_______________ # React Component

The block JS code can be enqueued using:

/**
 * Enqueue Gutenberg's blocks.js
 */
function enqueue_block_assets() {
	wp_register_script(
		'block-editor-js',
		PROJECT_TEMPLATE_URL . '/dist/js/blocks.min.js',
		[ 'wp-i18n', 'wp-element', 'wp-blocks', 'wp-components' ],
		filemtime( PROJECT_PATH . 'dist/js/blocks.min.js' )
	);
}
add_action( 'enqueue_block_editor_assets',      $n( 'enqueue_block_assets' ) );

Two questions:

This may not be the right place to document IDE settings / best practices, but I think these questions are worth pondering. Also, perhaps IDE settings / best practices should be owned by the engineer and not relevant. That being said....

1. Do we need / want to add setup instructions or recommendations for IDE settings for engineers ramping up with the new scaffolding to potentially avoid a time suck? We could just to Sublime, VS Code, and PHP Storm.

2. Are we testing different IDEs with scaffolding updates to make sure all works as expected? I have not kicked the tires on the scaffolding in a while, but I've heard there has been time suck on setup (particularly relating to file structure and code formatting challenges - which may have been resolved elsewhere) and I'd like to avoid that if possible.

CC: @timwright12

This feature intends to implement PostCSS linting using stylelint and gulp-stylelint in order to better control the standardization of CSS development within 10up.

Stylelint: Website
Gulp Stylelint: Website

Hey all,

We've been using the styleguide quite a bit in a current project and it's been great.

One issue I keep running into though is finding the component I'm currently working on on a long page of other components. Often when you resize your screen, for example, the component you're working on gets pushed down the page and you need to go hunt for it.

I've written a quick show / hide script and have been using it locally. I can collapse sections I don't want to see and it persists those settings with localStorage. You just click the section heading to collapse / expand it.

Questions:

1. Is this something we want in the theme at all, or is it best left to add per-project?
2. If we want to add it, how should we do so? There's no scripts currently in use in the styleguide, so lets decide how this should get added ( if we add it).

In the screenshot, I've collapsed all the sections before the Hero so I can easily see and work on that.

We currently have "babel-core": "^6.26.0" and "babel-preset-env": "^1.6.1". In the long run I feel that we should move using more recent version of Babel. Here are couple of docs:

• Upgrade to Babel 7
• Babel 7 released

For the theme itself I don't see much issues when upgrading. For existing projects it might take more work.

If this is supported idea I can do PR.

Skip to content link is missing from the header.php. Ideally it should actually be inside landmark region because all content should be inside a landmark.

But that's not a hard rule, as long as it's the first focusable element inside <body>.

More info about skip links.

In short:

Skip link(s) main target group are keyboard users who probably don't use any AT devices. So they don't have shortcuts to <main> or other landmark regions.

From the screen reader survey:

It is important to note that while usage has decreased among screen reader users, "skip" links still provide notable benefit for other keyboard users.

When running npm run build or npm run watch the output of webpack is really ugly.
https://github.com/nuxt/webpackbar was implemented on Google Site Kit for the build process and looks so much better! Would be great to have this integrated into the Theme and Plugin Scaffolds

Do we want to add a framework for JavaScript unit tests?

Depreciation Warning:

npm WARN deprecated [email protected]: 🙌  Thanks for using Babel: we recommend using
babel-preset-env now: please read babeljs.io/env to update!

The following filters and actions pollute the <head> that is generated from a default WordPress theme, most of the features are either a security risk, legacy, or redundant for most projects:

add_filter( 'emoji_svg_url', '__return_false' );

remove_action( 'wp_head', 'print_emoji_detection_script', 7 );
remove_action( 'wp_head', 'wp_generator' );
remove_action( 'wp_head', 'wlwmanifest_link' );
remove_action( 'wp_head', 'rsd_link' );
remove_action( 'wp_head', 'wp_shortlink_wp_head' );
remove_action( 'wp_head', 'feed_links', 2 );
remove_action( 'wp_head', 'feed_links_extra', 3 );
remove_action( 'wp_head', 'rest_output_link_wp_head', 10 );
remove_action( 'wp_head', 'wp_oembed_add_discovery_links', 10 );
remove_action( 'template_redirect', 'rest_output_link_header', 11 );
remove_action( 'wp_print_styles', 'print_emoji_styles' );
remove_action( 'admin_print_styles', 'print_emoji_styles' );

remove_filter( 'wp_mail', 'wp_staticize_emoji_for_email' );
remove_filter( 'the_content_feed', 'wp_staticize_emoji' );
remove_filter( 'comment_text_rss', 'wp_staticize_emoji' );

Per @smy315's point here: #78 (comment)

We should probably include a blocks.css file to compliment the wordpress.css file we have now.

This looks like Automattic's. I haven't had a chance to even look that over yet, so no endorsement on that particular one. https://github.com/WordPress/gutenberg-starter-theme/blob/master/css/blocks.css

The biggest pain point on my last project with lots of Gutenberg blocks was input fields and labels. Some inputs are actual inputs, while others were div-based faux-inputs for richtext with no labels.

Initially referenced on slack here:
https://10up.slack.com/archives/C10CPMBD2/p1547741052016500

Let's talk about what this means, so far we have:

• Add a manifest file

With the WordPress Accessibility Team publishing a new tool called WP Theme Auditor that runs Axe tests against a theme for automated accessibility feedback, should we consider swapping to that instead of the current Pa11y automated accessibility testing?

There are many potential Gutenberg-specific feature opt-ins that we can use: https://wordpress.org/gutenberg/handbook/extensibility/theme-support/

These should probably be revised on a project-by-project basis. That said, some of them seem like useful defaults:

Disabling custom font sizes
add_theme_support('disable-custom-font-sizes');

Disabling custom colors
add_theme_support( 'disable-custom-colors' );

Use editor styles in the WYSIWYG
add_theme_support('editor-styles');

Use responsive embeds
add_theme_support( 'responsive-embeds' );

• have gulp or grunt write a file w/ a timestamp
• have functions.php consume the contents of that file and store a global variable
• have all calls to wp_enqueue_script and wp_enqueue_style use that global for version number

this would ensure a fresh version every time assets are re-generated, regardless of whether that's locally (eases testing) or on deploy.

Per this comment on twitter:
https://twitter.com/scottjehl/status/1086287082031583232?s=11

.. we should change the style to be the following (more stable / reliable):
`@media (prefers-reduced-motion: reduce) {

*,
*::before,
*::after {
	animation-duration: 0.1s !important;
            transition-duration: 0.1s !important;
}

}`

Although it is defined in functions.php, I am not seeing any instance of TENUP_SCAFFOLD_URL used within the theme. Is there a reason this needs to exist by default?

This issue is to remind myself to look into using HTTP/2 server push and/or prefetch to load CSS & JS assets now that HTTP/2 is specified in our systems best practices.

cc @timwright12 for visibility.