Add base-styles package

[simison]

Description

Moves Gutenberg base styles to a package.

These are all variables and mixins so these files are not producing any CSS on their own.

They can be used when building custom editor implementations as well when building custom styles for components or blocks that should look visually similar to other components in the block editor.

I've found out to be copying these styles quite a few times to different projects over the year (example) so I figured out it would be good time to have them shared via NPM module.

I also thought this could be part of wp-scripts but honestly I personally wouldn't want to force so big package (in MBs and features) on anyone just needing some sass variables. ;-)

Thoughts?

How has this been tested?

These commands still work:

• npm run build
• playground:dev
• playground:build

Types of changes

No visible functional changes; basically just moving code around.

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.

[simison]

Not entirely sure what's up with Native mobile tests... 😁

[gziolo]

Not entirely sure what's up with Native mobile tests... 😁

They were failing before. However, we should still ping some folks as this is going to be a breaking change for the mobile project. @hypest, @pinarol, @koke or @Tug - does it require PR in https://github.com/wordpress-mobile/gutenberg-mobile as well?

[simison]

An idea for a test in this package: compile everything to a CSS file and confirm there is no visible output?

[gziolo]

An idea for a test in this package: compile everything to a CSS file and confirm there is no visible output?

That's one part. It would be nice to have also a test that consumes at least one item from each file and generates output which is tested with snapshots.

[gziolo]

This package could also contain the config with WordPress colors:

gutenberg/bin/packages/post-css-config.js

Lines 3 to 61 in 401ed23

	defaults: {
	primary: '#0085ba',
	secondary: '#11a0d2',
	toggle: '#11a0d2',
	button: '#007cba',
	outlines: '#007cba',
	},
	themes: {
	'admin-color-light': {
	primary: '#0085ba',
	secondary: '#c75726',
	toggle: '#11a0d2',
	button: '#0085ba',
	outlines: '#007cba',
	},
	'admin-color-blue': {
	primary: '#82b4cb',
	secondary: '#d9ab59',
	toggle: '#82b4cb',
	button: '#d9ab59',
	outlines: '#417e9B',
	},
	'admin-color-coffee': {
	primary: '#c2a68c',
	secondary: '#9fa47b',
	toggle: '#c2a68c',
	button: '#c2a68c',
	outlines: '#59524c',
	},
	'admin-color-ectoplasm': {
	primary: '#a7b656',
	secondary: '#c77430',
	toggle: '#a7b656',
	button: '#a7b656',
	outlines: '#523f6d',
	},
	'admin-color-midnight': {
	primary: '#e14d43',
	secondary: '#77a6b9',
	toggle: '#77a6b9',
	button: '#e14d43',
	outlines: '#497b8d',
	},
	'admin-color-ocean': {
	primary: '#a3b9a2',
	secondary: '#a89d8a',
	toggle: '#a3b9a2',
	button: '#a3b9a2',
	outlines: '#5e7d5e',
	},
	'admin-color-sunrise': {
	primary: '#d1864a',
	secondary: '#c8b03c',
	toggle: '#c8b03c',
	button: '#d1864a',
	outlines: '#837425',
	},
	},
	} ),

[koke]

does it require PR in https://github.com/wordpress-mobile/gutenberg-mobile as well?

Yes, our SASS transformer imports those directly.

[koke]

Update for gutenberg-mobile ready in wordpress-mobile/gutenberg-mobile#1435. That one can be merged safely before this.

[simison]

I don't want to keep the source files in the root of the package but putting js files to src will get the built automatically — and we don't need that here. Any other existing folder patterns in the repo that I could follow?

This package could also contain the config with WordPress colors

Done! f7ac217

[gziolo]

I don't want to keep the source files in the root of the package but putting js files to src will get the built automatically — and we don't need that here. Any other existing folder patterns in the repo that I could follow?

it's fine to put them in the top folder. We do it in other packages which are used with Node.js.

[simison]

Added some snapshot tests for scss files in 186582c

[gziolo]

This looks solid, major props for addressing all my comments. I would appreciate final feedback from @youknowriad as he might have better insights on how all that could work together. I don't have any more to add. He might also have some ideas about what would be the best name for the package.

[simison]

Thanks @gziolo, I appreciate your help here!

A few things that might be interesting to consider;

• How to go about generic styles (think color variables) vs things that are tied to implementation very closely (think z-indexes).
• including this "globally" in build step vs making sure different components that actually depend on this would import the package directly — in that case some monolithic things like reset() would need a rethink.
  • Ideally-ideally all bits (including the global CSS reset) would be applied only to their individual components so that for example importing just "button" wouldn't depend on a full suite of CSS resets for unrelated components.

I think nudges things in the right direction tho so those big questions could be good to solve in the future?

[simison]

Needed for ~@wordpress/base-styles/colors -style imports to work in the playground.

See parcel-bundler/parcel#39

[jameslnewell]

Does a similar setup work for people consuming the package via webpack/sass-loader?

How do people consume the package using something like create-react-app? @import "../node_modules/@wordpress/base-styles/colors?

[simison]

~ is a Webpack thing and Playground in Gutenberg uses Parcel. If ~ in consumer's build pipeline doesn't resolve to node_modules, they'd have to import using node_modules/@wordpress/base-styles/colors directly indeed. I'll mention that in docs.

Thanks for asking!

[jameslnewell]

Great!

The reason I ask is because from memory the default setup for ~ in webpack/sass-loader is that webpack resolves and compiles any imports which means any variables/mixins defined in the imported file aren't accessible in the consuming file.

e.g.
./node_modules/abc/stuff.scss

$foo: 'bar';

./test.scss

@import "~abc/stuff";
// $foo isn't defined because webpack resolved the module and compiled it to CSS
@import "./node_modules/abc/stuff";
// $foo is defined because SASS resolved the module and imported it

[simison]

The reason I ask is because from memory the default setup for ~ in webpack/sass-loader is that webpack resolves and compiles any imports which means any variables/mixins defined in the imported file aren't accessible in the consuming file.

No, they do work. :-) I guess it could depend on your Webpack config tho?

I also updated README.md about ~, wanna check if it's clear now @jameslnewell?

[simison]

Just to elaborate — I think the next steps after this PR could be for example to:

• add @wordpress/base-styles as a dependency to everywhere where there are *.scss files
• import styles in each style.scss via ~@wordpress/base-styles/*. That would make it easier to import @wordpress/*/src/*.scss files from packages into build-pipelines in environments outside WordPress and applying build-time optimizations instead of relying on compiled CSS files.
• The above can potentially make compiling slow since dependencies would be imported multiple times during the build. Therefore consider using Sass modules, unless that's too new API to use here. That would not only make things faster but also make it easier to re-use in external codebases since things wouldn't live in a global context anymore. We would have e.g. @include wordpress.dropdown-arrow() and wordpress.$blue-wordpress-700 etc instead of @include dropdown-arrow()...
• Not entirely sure what to do with CSS reset but at least it could be documented that consumers might need to do this at their end before using visual components:

  :root {
      @include wordpress.reset;
  }

• Could the package be released with alpha/beta tag? Styles in Gutenberg seem to be under some discussion these months so it might be smart to not commit too stable "API" yet.

[youknowriad]

I like these being extracted as a package 👍

I think it will become less important if we introduce theming into WordPress components... but since this is just a dev only package, breaking changes are allowed here.

[simison]

@gziolo I addressed some minor feedback and updated docs (please review!).

One open question is about testing; #17883 (comment)

[youknowriad]

I didn't test deeply but this is looking good for me

[simison]

Not entirely sure what's up with tests and if they're related (mobile & E2E) but other than those, this should be good. 🚀

[gziolo]

I re-triggered Travis jobs which failed.

[gziolo]

@simison, next time you can open a branch directly in the Gutenberg repository, given that you are in a member role :) Nice work on this PR 💯

We will need to wait until WordPress 5.3 is out before we publish this new package to npm. See https://github.com/WordPress/gutenberg/blob/master/docs/contributors/release.md#packages-releases-and-wordpress-core-updates.

WordPress 5.3 is scheduled for November 12th:
https://make.wordpress.org/core/5-3/

We will wait until the next plugin release after this date, to publish all the changes to npm.