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.

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.