Tools to build CSS from Sass

[grappler]

We have previously discussed build tools for the CSS from Sass. In 2014 we decided against as we wanted to keep _s tool agnostic. #585, #1097, #1002, #661

we will probably revisit once Automattic/underscores.me#31 got resolved

As it has been 2.5 years since that discussion I would like to propose a different solution.

Before merging pull requests related to CSS we need to be able to test that the Sass to CSS conversion is working properly. To be able to this properly every maintainer would need to have create a build tasks locally. Which is related to a previous discussion #615

What I propose we document the following command which does that without needing grunt or gulp or any other build system.

node-sass --include-path scss sass/style.scss style.css --output-style=expanded --indent-type=tab --indent-width=1

The only requirements for this is node and npm install node-sass which most developers are already using.

After running this command I got the following changes. I have removed some of the code style changes that have not been factored in. I think adding another check to travis for CSS code styling is another issue that we should look at in another issue. Partially mentioned in #1146 and previously discussed in #936

--- style.css
+++ style.css
@@ -49,7 +49,7 @@ Nicolas Gallagher and Jonathan Neal http://necolas.github.io/normalize.css/
 html {
        font-family: sans-serif;
        -webkit-text-size-adjust: 100%;
-       -ms-text-size-adjust:     100%;
+       -ms-text-size-adjust: 100%;
 }

 body {
@@ -426,7 +426,7 @@ input[type="submit"] {
        border-color: #ccc #ccc #bbb;
        border-radius: 3px;
        background: #e6e6e6;
-       color: rgba(0, 0, 0, .8);
+       color: rgba(0, 0, 0, 0.8);
        font-size: 12px;
        font-size: 0.75rem;
        line-height: 1;
@@ -473,10 +473,6 @@ textarea {
        padding: 3px;
 }

-select {
-       border: 1px solid #ccc;
-}
-
 input[type="text"]:focus,
 input[type="email"]:focus,
 input[type="url"]:focus,
@@ -496,6 +492,10 @@ textarea:focus {
        color: #111;
 }

+select {
+       border: 1px solid #ccc;
+}
+
 textarea {
        width: 100%;
 }
@@ -546,16 +546,6 @@ a:active {
        padding-left: 0;
 }

-.main-navigation li {
-       float: left;
-       position: relative;
-}
-
-.main-navigation a {
-       display: block;
-       text-decoration: none;
-}
-
 .main-navigation ul ul {
        box-shadow: 0 3px 3px rgba(0, 0, 0, 0.2);
        float: left;
@@ -570,24 +560,13 @@ a:active {
        top: 0;
 }

-.main-navigation ul ul a {
-       width: 200px;
-}
-
-.main-navigation ul ul li {
-
-}
-
-.main-navigation li:hover > a,
-.main-navigation li.focus > a {
-}
-
-.main-navigation ul ul :hover > a,
-.main-navigation ul ul .focus > a {
+.main-navigation ul ul li:hover > ul,
+.main-navigation ul ul li.focus > ul {
+       left: 100%;
 }

-.main-navigation ul ul a:hover,
-.main-navigation ul ul a.focus {
+.main-navigation ul ul a {
+       width: 200px;
 }

 .main-navigation ul li:hover > ul,
@@ -595,15 +574,14 @@ a:active {
        left: auto;
 }

-.main-navigation ul ul li:hover > ul,
-.main-navigation ul ul li.focus > ul {
-       left: 100%;
+.main-navigation li {
+       float: left;
+       position: relative;
 }

-.main-navigation .current_page_item > a,
-.main-navigation .current-menu-item > a,
-.main-navigation .current_page_ancestor > a,
-.main-navigation .current-menu-ancestor > a {
+.main-navigation a {
+       display: block;
+       text-decoration: none;
 }

 /* Small menu. */
@@ -818,7 +796,7 @@ object {
 }

 /* Make sure logo link wraps around logo image. */
-.custom-logo-link{
+.custom-logo-link {
        display: inline-block;
 }

[m-e-h]

The addition of a single package.json could be a solution here.
Just put something like this in it:

"devDependencies": {
    "node-sass": "^4.5.3"
}

"scripts": {
   "scss":  "node-sass --include-path scss sass/style.scss style.css --output-style=expanded --indent-type=tab --indent-width=1"
}

Then, in the cmd line, devs can just run npm install (or yarn) and then npm run scss will compile. You could also easily add other things like autoprefixer and stylelint / stylefmt. https://css-tricks.com/why-npm-scripts/

This could also be a way to properly manage things like normalize #1144

[m-e-h]

Here's a working example if anyone wants to paste it into a package.json in the _s root folder and try it out.

1. from the command line: npm install
2. from the command line: npm run scss
   You can replace scss with any of the "scripts" listed. "stylefix" doesn't fix everything but it handles tabs and a couple others.

{
	"name": "_s",
	"version": "1.0.0",
	"scripts": {
		"scss": "node-sass --include-path scss sass/style.scss style.css --output-style=expanded --indent-type=tab --indent-width=1",
		"autoprefixer": "postcss style.css -u autoprefixer -o style.css --no-map",
		"stylelint": "stylelint 'style.css'",
		"stylefix": "stylelint 'style.css' --fix"
	},
	"devDependencies": {
		"autoprefixer": "^7.1.1",
		"browserslist": "^2.1.5",
		"node-sass": "^4.5.3",
		"postcss-cli": "^4.1.0",
		"stylelint": "^7.12.0",
		"stylelint-config-wordpress": "^11.0.0"
	},
	"stylelint": {
		"defaultSeverity": "warning",
		"extends": "stylelint-config-wordpress"
	},
	"browserslist": [
		"> 1%",
		"last 2 versions"
	]
}

[grappler]

#893 and #932 are open pull requests which update the Sass and CSS files so that they match.

[ghost]

Not entirely sure if now would be the best time to implement this or to handle this afterwards, but I'd love to see _s including normalize.css again (and not just being based on).

[davidakennedy]

Thanks for the issue @grappler! This is a good thing to talk about since it's been awhile.

I'm up for talking through possible solutions here. Here's some context:

• We have shied away from including a build process in _s for two main reasons: 1. It raises the barrier to entry for everyone. Beginner or not, you now have more dependencies. 2. It forces opinions on people. The great thing about _s is its balance of just enough opinion, but not so much that you can't do your thing.
• Most of us on the Theme Team at Automattic don't use Sass in the final themes we launch. Some of us start with Sass as we're designing, but yank it out once things are more solidified. If we do use Sass all the way through, it's compiled on the server. Most of our themes don't use it because we find shifting from Sass to vanilla CSS across hundreds of themes harder to do when maintaining the themes and fixing bugs. That said, many of us are fans of Sass.

I do like the approach mentioned by @grappler since it's very low key. I'm going to try it out and see how it feels.

I'll also take a look at #1159 from @m-e-h. My first questions there is: Do we need all those dependencies? What are they all for? Can it be simpler?

Some goals I would have for this:

1. As few dependencies as possible.
2. Automate compiling and have it still meet WordPress coding standards.
3. Not have to require a ton of docs to explain the build process.
4. Make the build process easy to remove if someone doesn't want to use it, or use something else.
5. Leverage it elsewhere, like the POT file, and RTL.

I'm wondering if we can use Travis and/or another service to compile for us on commit? I don't know if that's possible, but it would be cool to just compile and test locally however people want, and just submit PRs to Sass files. Just an idea. 😄

[grappler]

Thank you @davidakennedy for your comments. You have put together a good summary.

I would like to add a few points to clarify and not push my idea.

1. It raises the barrier to entry for everyone.

It would be good to make a distinction between contributor and user. I imagine for a contributor it could be easier if we had some standard process instead of needing to having to setup your tool for _s. In this case we could always leave out a package.json in the generated version of the theme so that user does not have an extra dependency.

I'm going to try it out and see how it feels.

Am interested how you find it 😄

Do we need all those dependencies? What are they all for?

• To compile the CSS we only need node-sass.
• If we wanted to make sure all browsers and their prefixed versions are supported we would use autoprefixer.
• To check that the CSS is following the WordPress coding standards we would use stylelint. This would not need to installed locally but could be run in travis when making a PR.
• Currently are running jscs for the JS WordPress coding standards which is now merged with ESLint. Like we are running jscs in travis we would use eslint instead. If we create a package.json then we can remove .jshintignore and .jscsrc.

Can it be simpler?

We could remove some of the scripts but that would mean typing out the whole commands. Coding Standards are important and we should not exclude them. We currently do not add any extra browser prefixing support so we could exclude autoprefixer intially.

I'm wondering if we can use Travis and/or another service to compile for us on commit?

Travis could compile the CSS for us but we would need to figure out how to commit those changes. Potentially we could have underscores.me generate the CSS for us when generating a theme and exclude the CSS from the git repo.

As there are number of moving parts we should do it step by step. This is the order that I see it being done.

1. Update Normalize Update Normalize.css to v7.0.0 #1155 maintainable-ize normalize #1144
2. Create a package.json and only add node-sass. We would synchronize Sass and CSS. CSS: Add package.json for linting and compiling #1159
3. Lint the CSS and SCSS files for coding standards with stylelint and phpcs Add new line at the end of file and missing white space #1153
4. Switch from jscs to eslint and delete .jshintignore and .jscsrc. Run JS files through phpcs files too. Add new line at the end of file and missing white space #1153
5. Add other tools like MakePOT and RTLCSS Support RTL the right way #1154
6. Discuss using autoprefixer

[davidakennedy]

Those are some good thoughts @grappler!

It would be good to make a distinction between contributor and user.

Yes, we have some flexibility here, but if we introduce tools, it adds barriers even if it's a "standard."

Am interested how you find it

I really liked it. It was simple, and the generated file looks really solid.

As there are number of moving parts we should do it step by step.

These steps look good.

Ultimately, what I'm after here is a way for the stylesheets to not get out of sync, and for _s to have a sensible build process, if we go that route. Sensible means still easy to get started with, without needing to know a lot of tools. Honestly, I would also be fine with removing Sass altogether. I'd like to do what's best for the majority of our users though, while still making it easy to do what you want.

I think the MVP of this could be to have all the maintainers run node-sass for testing PRs. Also, a line in the docs about that being the preferred way to compile, and leave the style.css file for now. Next step could be actually adding a package.json file if the first step goes well.

Also, I'd be interested in using underscores.me to compile the Sass, and potentially build other files, like RTL and POT.

All that said, I'd like to wait to see if we get more voices on this before going in a direction.

[karmatosed]

Thanks for kicking this off @grappler again. I say again as it's something that as a team we have tried to approach before and not managed to find a path through. Lets find a path!

I will be upfront, my initial concern is really that this all is very very dependent on dev tools. In my ideal world the person using _s would not have to do anything node or any other developer tool. We have to be really aware this is not just for developers that are using those tools in the workflow.

That said, I think a balance can be reached. My real desire is for as much automation before the user even gets _s. I say user as that is the mindset we should frame thinking about _s in - the one where people are using it as not developers but users.

I would therefore strong -1 anything that uses yarn/tweed (joke) /npm or anything at all that requires users to compile.

I think it's worth adding how much of a nightmare compiling and being up to date with things like node-sass can be if you are not used to it. I for one have myself fallen down that rabbit hole. I am very keen we don't add these type of hurdles. I have had battles with Travis for example I never want anyone to do - yes I voted against adding that to.

I am not super keen on the approach that means any maintainer has to run node-sass to test PRS either. Sorry @davidalankennedy. In the past we have tried to add things like this and it's really hard to regulate. As you point out a lot of the team even at Automattic don't use Sass, or run node anything or even compile any code. I am against at this point .json files because of similar reasons.

My vote would be if it could be done without maintainers doing anything or users. That may be an impossible thing to desire. But, I think it's worth exploring. Could it be part of the packaging somehow?

I also wouldn't be against removing Sass completely.. if that is an option. Yes I was one of the ones that introduced it, but I don't think it works for this project anymore.

[grappler]

Thank you @karmatosed for your comments. In relation to your comments I would be interested if you use Sass and if you do what tool you use to compile it.

I would therefore strong -1 anything that uses yarn/tweed (joke) /npm or anything at all that requires users to compile.

Don't see npm as requirement but as a way of generating the necessary files in the least opinionated way. A bit like having the sass files. You don't need to use them but they are there if you need them. At the most it would be a package.json in the theme.

I am not super keen on the approach that means any maintainer has to run node-sass to test PRS either.

We would not need to require contributors to run node-sass. We could run it in travis and compare the file result with the style.css.

Could it be part of the packaging somehow?

Like I mentioned above this is possible to be included in generation process of the theme but would mean we would remove style.css from the repo. #1149 (comment)

I also wouldn't be against removing Sass completely.. if that is an option. Yes I was the one that introduced it, but I don't think it works for this project anymore.

Maybe we should start a new discussion to discuss this.

[karmatosed]

In relation to your comments I would be interested if you use Sass and if you do what tool you use to compile it.

Now I use it less and less (no pun intended). To backstory, I adore what Sass gives and have in the past used on all themes I created when theming at Automattic, including _s. However, I see Sass as usable nowadays if you:

• Entire team has a build process
• Automation means you don’t have to have a build process

There are also other options to Sass and I think letting people have whatever works for them with _s works. I also think there are a lot of better options than Sass right now for different situations. This though isn't about my process, it's not about anyone's, this at this point is about what works for _s. Sass I would say doesn't at all right now.

If it was happening today I wouldn't be making the PR I did to get Sass into _s. Sass in _s is used incredibly lightly and more as a simple variable manager. We aren't using more than a little of its power and this in itself is a good reason to review. Countless issues of maintaining and complicating our processes to accommodate it, these all add up to me strongly suggesting we remove.

[joshmcrty]

Yeah I kinda feel like Sass isn't needed for _s. It's not even 900 lines of CSS with Normalize. Variables and mixins aren't used a lot, and it'd be easy to break into partials from the CSS file as-is. I don't see the big value-add that Sass brings to _s and it goes against the un-opinionated philosophy of _s.

Doing Sass right also means bringing some complexity (and therefore pain) to _s. We should have a standard Sass build process for maintainers/contributors, but I'm sure many of them use a Git GUI and are unfamiliar with or intimidated by the command line like I was when I started dabbling in Sass. They might be OK using a GUI like Codekit for Sass, but that could generate slightly different compiled CSS than this PR. So maybe Sass isn't worth the trouble of adding a build process or the current process of manually checking and keeping the CSS/Sass in sync.

Side note: it would be cool if we had some data about underscores.me downloads using CSS vs. Sass. Is that tracked?

Setting that aside, I think @grappler your original suggestion is actually the best approach right now, if we also test for it in Travis. Instead of adding a build process via package.json, we update Travis to run your node-sass build and compare that to the styles.css file in the PR. That way contributors could see if they "de-synced" the Sass with the CSS file if the build fails. Then we could suggest that they compile the Sass using the build process you documented (or they could sync up the CSS file manually).

That to me seems like a good first step before we tackle more controversial changes like adding a package.json or removing Sass altogether.

[David-Brown]

If I may offer an opinion as a long-time WordPress custom-themer :)

I think that removing Sass from _s would be a step backward. While I understand (and agree with) the philosophy that _s should remain as non-opinionated as possible, I don't think that including Sass is opinionated for a couple of reasons:

1. In the teams I've worked with, Sass is really the standard for pre-processing (especially now that we know a certain popular framework is dropping Less in favor of Sass in their next version). I'm not advocating for any framework here...just noting that I saw that as Less' official demotion.
2. Another part of WordPress' philosophy, as I understand it, is to make it easy for new users/developers to learn from using it. When I was originally experimenting with Sass, having a starting point within _s was extremely useful to me. It was exactly the right balance to see it "in action" before launching into the process of deciding what tooling was right for me.

What I see being discussed here is just the minimum level of tooling to get Sass working. Left on it's own, someone could run with it, which is perfect. Those of us who want something more advanced can quickly base our workflow on it (or likely already have).

The bottom line, I think, is that front-end workflows are just complex, and becoming increasingly more complex. Having a pre-processor in place is just the minimum expectation, and, based on my experience, Sass is the most widely used.

[m-e-h]

So this issue and the many issues related to it are all basically trying figure out how to best handle the baggage that comes with maintaining SASS and it's compiled CSS.

Any methods to manage SASS are of course going to be opinionated and require extra tooling, build processes and dependencies because SASS itself is, more or less, all of those things.
This discussion has naturally gone where it should, imo. Is SASS the right fit for this project? I think probably not.

The only benefit I see in _s's SASS is the modularity of files. But I think the headings and TOC in the style.css do a pretty good job of separating things.

The variables in _s aren't really that helpful. Most of them are used once in the project. This kind of adds complexity rather than removing it. Mixins that are only used once or twice just add complexity also. And, for me anyway, I'd rather edit the gallery-columns in any modern text editor with multiple cursors than touch that current function. And the nesting done on the menu is borderline abusive. Sorry if all that sounds harsh. I got fed up with SASS in general a while ago..

The package.json idea is more of a dependency and process management solution that can be managed as a single file and adaptable to current( .jshintignore, .jscsrc) and future processes for linting or whatever.

I think the question, "What can we remove?" might be more appropriate here than, "What can we add?".

[tiagonoronha]

We use Grunt in Storefront to help us with several tasks: https://github.com/woocommerce/storefront/blob/master/Gruntfile.js

Some of my favourite tasks:

• Sass compiling
• Watch (watches for changes to files and auto compiles in the background)
• JS linting / minification
• Autogenerated RTL styles

I don't think adding building tools to _s is a bad thing, specially considering that these tools are optional. You can still use Codekit or other apps to compile.

I'm also in favour of removing .css files from the repo, to avoid issues with PRs as highlighted above.

[sterndata]

I'm not really interesting in giant dev stack to get a working _s theme. I don't use SASS/LESS/etc and therefore need the .css files.

[grappler]

@sterndata You would still get a CSS file if you used underscores.me to generate the theme if we removed the style.css from the repo.

[sterndata]

OK, I can live with that. :-) Thanks.

[allancole]

I’m definitely on the side of continuing to use SASS in _s but I know that won’t be the case for all theme devs and contributors to _s. I don’t want to jump too far ahead here but, if the future of WordPress continues to move toward Gutenberg, I think SASS lends itself to a more modular approach to theme development which would play more nicely with Gutenberg (in theory). This means getting to know SASS now (even in simple terms) could make for a more seamless transition to theming in the future. I think we could leverage this as an opportunity to define how SASS should be used in themes structurally so that we’re defining what works.

I know this way could probably come across as too opinionated for some, but for devs or contributors who haven’t made the jump into SASS yet, it’d be a learning opportunity.

As far as implementation goes, I’d be curious to compare the potential for technical debt created by @grappler’s original idea with that of @tiagonoronha’s Grunt idea used in Storefront. Although, I’m not sure how to go about digging up that information.

[msroberts]

I would favor keeping SASS. A non-SASS user can download the theme from underscores.me with only CSS, but a SASS user would have to pick apart the stylesheet every time they created a new theme if scss files were removed (I use SASS in all my _s-based themes). SASS may also help encourage theme developers to minify all their CSS files, because no additional minify tools would be needed, only --output-style=compressed.

Because _s currently only has one stylesheet, it would be easiest to implement using just NPM scripts, although Grunt does have the advantage of supporting grunt-wp-i18n and grunt-checktextdomain, which might simplify other parts of the build.

[David-Brown]

I'm wondering if introducing an additional build tool might be too opinionated, since, as @msroberts says, a user can compile Sass without additional tooling. I also use Grunt, but a lot of my colleagues prefer Gulp or Webpack. I wonder if it would a good idea (without producing too much overhead for maintenance) to add an example Gruntfile and an example Gulpfile? That would assist users new to the tooling in the discovery/education process, and those experienced with these tools can easily discard them in favor of their own configurations.

[grappler]

As far as implementation goes, I’d be curious to compare the potential for technical debt created by @grappler’s original idea with that of @tiagonoronha’s Grunt idea used in Storefront.

I am not sure what you fully mean with technical debt in this case. What I can add is that most Grunt Tasks are based on NPM packages. It is proven that NPM packages are faster than Grunt or Gulp but I don't think this is a big factor here. As for some of the features in Storefront, I don't think we need a watch task as we are not actively developing the CSS. We have not minified the CSS and JS files in the past so we can leave the decision to the theme developer.

@msroberts NPM has packages too for generating POT files and RTLCSS so there is no need for grunt tasks.

@David-Brown I don't think having an example Gruntfile and Gulpfile is the solution here. Though it should not stop people from sharing their config files.

[davidakennedy]

This has been a great discussion, and I appreciate everyone being open to and brining different ideas.

To double back to the question from @joshmcrty about data:

it would be cool if we had some data about underscores.me downloads using CSS vs. Sass. Is that tracked?

Since August, 2014 when Sass first dropped in _s and we began tracking it, about 13 percent of total downloads from underscores.me have included Sass. It has had its peaks and valleys but has stayed consistent with that number over time.

Discussing whether or not Sass makes sense for _s on the whole is a good discussion to have at this point.

I'm going to leave more questions here than answers while I continue to ponder this. 😄

I think it's hard to judge the implementation of Sass in _s purely as useful or not because the theme doesn't have any design. So the chances to take advantage of Sass' power are slim. It's better to judge it like we do _s on the whole: does it save you time or does it get in the way of doing your standard setup?

The other question worth asking: If Sass were removed, could we do anything simple to make it easy to drop in Sass, Less or whatever else you want to do preprocessor wise? That's also an option.

Right now, I'm leaning toward removing since it does seem like an opinion we should leave it up designers and developers.

That said, I think we could still explore automating some of our other pain points, like the RTL styles and the POT file. I'd also say that this isn't about _s not being opinionated. I think it should get more opinionated, but not in the way of benefits for themers, but in the way of benefits that show up in the themes created from _s for end users.

[bahiirwa]

Let me add a pebble. I think the stats could be affected by the UI of underscores.me website. I stand to be corrected. The call to action to get advanced settings is so tiny and can easily be passed for a comment. Personally I did not start using the sassify options until a few weeks ago yet have been using underscores for close to 3 years.

I hope I throw a little vote to leave SASS in there.

[tyrann0us]

What I love about having SASS in _s is the ability to include parts of the stylesheet (like @import ../media/_galleries.scss) and ignore the rest of it. Without SASS, we would need to write these "core" styles over and over again.

If you remove SASS, it will be a step backwards, not forward.

[skynet]

Don't forget Yarn - the new kid on the block

[davidakennedy]

I chatted with a handful of my colleagues on the Automattic Theme Team about moving this issue forward, plus have been thinking over all the comments here from the community... Here are some decisions: 🚀

1. Keep Sass. It's obvious that many in the community find it valuable. Plus, it allows for more flexibility when including or excluding certain CSS from generated builds on Underscores.me. Also, with Gutenberg themes coming, Sass may even be more handy down the road in a more componentized, style-driven theme world.
2. Pursue a build process with the generator on Underscores.me doing the heavy lifting. The idea of having no style.css file in the GitHub repo, with it being generated on a build by the generator should allow us to make everyone happy. Themers can pick what they want, Sass or vanilla CSS. Maintainers don't need to worry as much about files getting out sync. And the GitHub repo can remain less opinionated about the build process, letting themers still use whatever they'd like.

cc: @grappler @m-e-h @jrfnl since you all have been heavily involved in build process discussions and PRs.

[davidakennedy]

Also worth noting that if there is a way to keep the style.css file in the GitHub repo without the possibility of things getting out of sync, that's a possibility too.

[grappler]

@davidakennedy This seems to be the right decision. We currently have a few moving parts so will need to see in which order we do things. Here are a list of items that we need to keep track of.

• Update Normalize maintainable-ize normalize #1144/Update Normalize.css to v7.0.0 #1155 (Still needs input)
• Update Sass Styling Format SCSS #1168 (waiting on Normalize)
• Add the compiling process CSS: Add package.json for linting and compiling #1159
• Research how the CSS generation process will work Automatically generate a style.css from Sass underscores.me#62
• WooCommerce support Basic WooCommerce Integration #1191 (makes changes to CSS too and has new woocomerce.css)

[ix-xerri]

@m-e-h I am getting Error: './style.css' does not match any files when I run npm run stylelint with the package.json you described.

[m-e-h]

@ix-xerri if you're theme has a style.css and your typing the command from the themes root folder, I'm not sure why that would be.
PR #1159 might be a more complete and tested reference than the snippet above.

[xicubed]

Understrap.com adds _s and Bootstrap while using a Grunt/SASS/npm build process...

[Ismail-elkorchi]

Closing this issue as linting and compiling tools were added in #1386, and #1391.