10up / theme-scaffold Goto Github PK

DEPRECATED. Use https://github.com/10up/wp-scaffold

License: MIT License

CSS 13.28% JavaScript 32.92% PHP 53.80%

theme-scaffold's Issues

Confirm and Update Build Process

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

Add PWA Support to the Theme

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

Add a manifest file

Add a blocks.css file

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.

IDE Testing / Setup

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....

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.
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

CSS nano not respecting settings in gulp task

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).

Upgrade to babel-preset-env

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!

Add Theme Thumbnail Image

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.

suggestion: automatic versioning of assets

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.

Update eslint

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

Should we deprecate Gulp and focus on Webpack?

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.

@apply in CSSnext only works once

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

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.

package-lock.json not being tracked?

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

Add webpackbar to terminal build output

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

Lint Warning in `includes/core.php`

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.

Prefers-reduced-motion update

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;
}

Storybook Addition

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.

Feature: ES5 and ES6 Code Bundles

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/

Add feature/prefers-reduced-motion to scaffolding

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

Adding docs for Style Guide Template

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.

Gutenberg block development support

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' ) );

Add linting command for CSS

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.

Feature: Integrate gulp-notify

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?

Show / hide sections in the styleguide

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:

Is this something we want in the theme at all, or is it best left to add per-project?
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.

Localization POT

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

Why does TENUP_SCAFFOLD_URL exist?

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?

Move Search Component from Library into Scaffolding

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

Clean up the <head>

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' );

Feature: replace LiveReload with Browsersync

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.

Add Default WP Files

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.

Add the ability to use async and defer on wp_enqueue_script

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.

Bring PHP unit tests over from the Plugin Scaffold

Add wordpress.css to base folder

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.

Should we include any Gutenberg Theme settings by default?

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' );

composer.lock should not be in .gitignore

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.

Explore HTTP/2 push/prefetch

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.

npm warnings

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!

Add browserlist to NPM packages

https://github.com/browserslist/browserslist

Add normalize via npm to the build

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

Create Backstop and Jest VRT branches

Warning for empty css 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.

JavaScript unit testing

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

Consider updating to Babel 7

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:

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

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>.

Add documentation requirement to ESLint

Feedback from the engineering council.

Add conditional body class for `js` or `no-js` progressive enhancement

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.

Update Best Practice docs with new structure

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

Swap out Pa11y for WP Theme Auditor?

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?

Feature: Implement StyleLint

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

Tidy up Stylelint errors

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.

Add Node Version to the Package file

e.g. npm install node@8

10up / theme-scaffold Goto Github PK

theme-scaffold's Issues

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?

Recommend Projects

Recommend Topics

Recommend Org

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