David Clark Develops the Web

Lessons I May Have Learned From Working on Stylelint

Sun, 10 Jul 2016 00:00:00 -0700

A little over a year ago I started working on stylelint, a PostCSS-powered stylesheet linter. (To learn more about stylelint, you can read my article in CSS-Tricks about it.)

It’s a fairly large open source project, and continues to grow at a fairly quick pace. I say “large” referring not only to codebase size, but also to exposed functionality and general ambition; and I say “grow” referring not only to code written, but also to attention received, issues opened, contributions offered, extensions created, etc.

What I’ve heard has proven true: writing and maintaining open source code can be an effective course of study. The main reason I’ve been working on stylelint is to actively learn. And I definitely have. So lately I’ve been reflecting a little on some ideas that have crystallized for me during this experience with stylelint — that is, while working with a few international collaborators on a large open source project written in JavaScript, about CSS.

I’m going to try to write down a few of these lessons I may have learned, for my own edification, and for anybody who comes across this.

(Note that I call them “lessons I may have learned” because just saying “lessons I have learned” sounds a little too confident for me, as though I tapped into Authority and now channel it. These may not be very good lessons, or I may not have learned them well. Judge for yourself. I know you want to.)

1. One of the best ways to learn about a language is to statically analyze it

I now know a million or so times more about CSS than I did before starting stylelint. A million. Working on this project involving intense static analysis has compelled me to learn and repeatedly use precise terminology about language features; to read specs; to make fine distinctions and really understand subtle differences.

And all that has led me to a judgment …

2. Non-standard syntaxes are a huge obstacle to CSS tooling

I’ve come to believe that the wild popularity of preprocessors with non-standard syntactic constructs has made it so-so-so-so much harder to create powerful CSS tools. Too much harder, for entirely inadequate payoff.

Effective CSS tools rely on effective stylesheet parsing, and non-standard syntax spoils (or dramatically complicates) that parsing. This means that any attempt at a CSS tool must make countless exceptions and accommodations to avoid stumbling. And everybody seems to use Sass or Less, so if you want to build a general-purpose tool you just can’t ignore them.

Someone prone to bold and punchy Twitter pronouncements should make one blaming Sass and Less for the CSS ecosystem not being better than it is. Sass and Less have won huge followings because they are good at what they do, but some portion of what they do effectively stunts other tools — and a lot of that portion is not actually very helpful. Without those behemoths running the show, who knows what it might have become by now? (We certainly would have had a great, widely used linter long before stylelint.)

CSS has at least two built-in syntactic constructs that in theory allow for indefinite extension: functions and at-rules. You could create all the custom functions and at-rules you want without violating the grammar of CSS — that is, without breaking tools that rely on parsing. But preprocessors went too far, introducing non-standard constructs — operators, //-comments, variable interpolation, lists and maps, etc. — and thereby hampering awhatever is not deliberately, specifically tailored to their eccentricities. They’ve fragmented the landscape, and required every tool-building effort to be dramatically more complex and ambitious than it would otherwise be, burdening creators and maintainers.

Ever since stylelint decided to support non-standard syntaxes, it seems that the majority of our actual bug reports have been — surprise, surprise — related to those non-standard syntaxes. I know those preprocessors were built on good intentions, but my work on stylelint makes me resent them. That’s demotivating. And most of the time (all of the time, really) I don’t think those constructs are worth the trouble they introduce. Not even close. Sass maps are not worth it. Less’s mixin syntax is not worth it (Sass got it right with at-rules). Even //-comments are really not worth it (more on that below).

3. I prefer to write Node modules without ES2015, without Babel compilation

ES2015 is wonderful; and Babel is wonderful. We’re all better off that both exist. And for browser code that is already going to be compiled (because I use modules and bundle things), I have no qualms, I think, about using them. But for Node modules, I do have qualms.

Many times I’ve regretted the early decision to write stylelint in ES2015, compiling with Babel. It introduced various complexities, tooling incompatibilities, bug-sources, and other slight burdens that could have been entirely avoided. And for what payoff? For sugary syntax changes that are nice enough but definitely not necessary. (The really helpful stuff, like new data structures, can be polyfilled without compilation).

By the time I regretted this decision, I already felt like it was too late to turn back.

From now on I will not be writing Node modules that require compilation, if I can help it. I will write them using the syntax available in the Node versions that I plan to support.

4. It’s nice to establish a standard way to do a thing, even if it’s a trivial thing

Usually this means writing a function and reusing it instead of repeating a procedural pattern. In stylelint we’re always trying to figure out what a string of CSS means, so we find ourselves writing little heuristics to determine whether a value is a Sass variable, a hex color is valid, a character is “whitespace,” a word is a font family name, and on and on. We’ve ended up accumulating a utility belt of functions, and in the process found that there’s almost always at least one little trick to each of these games that would have been neglected half the time had we just re-implemented some logic, repeated a pattern. Also, these functions can be independently tested. I like them quite a bit.

But a reusable function is not the only “standard way to do a thing.” Writing documentation gets easier the more formulaic you make it (and the documentation itself gets more consistent, and probably clearer and more accurate). The same goes for writing tests (more on that below). And reviewing code. And writing lots of very similar modules (like linter rules).

If you think you may have done something well once, try to make it easy to do that same thing just as well every time.

Also: If you contemplate what you’re doing as Establishing The Way To Do A Thing, you will probably analyze and solve the problem better than you would have if you’d just whipped off a few lines that apparently work in one context.

(Keep in mind that you can always change your mind, and substitute a new way for the old. There is no eternally enduring and unchanging Way.)

Then there’s all the minutiae, some that is arbitrary (like deciding whether or not to capitalize “stylelint”) and just needs to be decided upon; and some not so arbitrary — but still tiny, buried among similar minutiae, as easy to overlook as to frenetically fuss over. With these details, I find it’s often best to make a decision and stick with it — whether that means picking arbitrarily, or really weighing options — at the risk of seeming a little pedantic or over-strict. That way you don’t have to think about that minutiae anymore until a problem arises. That’s one of the major benefits of linters in the first place, or of usage manuals in writing, or of some minor Good Habits in Life: reduce the cognitive load from minor, repeated decisions so that you can focus on the less minor, less common problems.

I’m especially thankful for the patience and thoroughness of one of my collaborators, Richard Hallows, in figuring out standard ways to do things.

5. Make meanings and motivations explicit

This comes up all the time in all the large project I’ve worked on, including stylelint. I’ll find myself looking at a file I haven’t touched for 10 months, or looking at a file somebody else wrote and I reviewed quickly over breakfast while grumpy and half-watching hummingbirds. In these cases, I cannot rely on any remembered context (“… this line solved that one issue with operators in calc() … and this one addressed the fact that units can be uppercase…”).

There are always odd edge-cases to address, and the code that addresses them can be harmfully hermetic to a reader without context. So when I write or review code, I’m now trying to look at it as though I’ve already lost context, even when I have not (yet).

The more time passes, the more code you and others pile up, the less you are able to assume contextual knowledge. Instead, whenever reasonable, you should assume the lack of context — which means you must be explicit about the meanings of values and the motivations for decisions.

Look back at your code and imagine someone else or your future self asking “What does this mean?” and “Why did you do that?” Then figure out a way to communicate with that hypothetical interlocutor.

I’ve found a few practices that help with this.

Try to name variables and functions with purpose and precision. It is always better to type more letters than to rely on implicit context.
Write comments whenever variable and function names don’t mostly explain what’s going on.
Write down what you’re thinking and what you’ve done in issues and pull requests.
Write thorough tests. (Keep in mind, though, that tests can sometimes prove as mysterious as the source code if they do not include clear names and comments.)

If some bit of code is poorly named, uncommented, and untested, you can safely, sadly assume that someone is going to be confused and annoyed about it at some point — maybe tomorrow, maybe a year from now.

6. More trivial preferences

6a. I prefer object “options” arguments to long argument lists

Option keys can describe their values’ meanings, and that’s nice (see above). Also, unlike with an argument list, the order of properties in an object is arbitrary, the number indefinite. With an options object, it’s easy for function consumers to skip optional “arguments” they don’t need, or for you the author to add another “argument” in the future without worrying about where it falls in an already unwieldy list.

As stylelint changed and expanded, I found myself again and again refactoring functions to accept options objects instead of argument lists. Now, whenever I realize that a function is going to require more than a couple of arguments, I consider an object, instead.

6b. Return early when you can

Much of the logic in stylelint involves deciding what to ignore and what to analyze, because most of the rules only pertain to very specific chunks of your CSS. If a linting rule focuses on rgba() arguments, for example, it can ignore any text that’s not in the value of a declaration in a function named rgba, as well as any text in comments and strings. One way to think about this whittling down is as a series of nested conditionals:

if x is in a declaration
  and x is in the value of that declaration
    and x is in a function in that value
      and the function's name is rgba
        and x is not a comment
          and x is not a string
            check x

By inverting the statements and returning early, you flatten the logic:

if x is not in a declaration, ignore it
if x is not in the value of that declaration, ignore it
if x is not in a function in that value, ignore it
if that function's name is not rgba, ignore it
if x is in a comment, ignore it
if x is in a string, ignore it
check x

This reduces indentation and curly-braced blocks in the code, which everyone appreciates. I also find that it eases reading, at least a little bit, because I don’t have to think of each point in the sequence as the continuation of one long coordination.

6c. Make it as easy as possible to write tests, and you will have more tests

We have a lot of unit tests in stylelint. It looks like right now we’re at 21,174 assertions. We are able to write so many tests because we worked out a system that makes it as easy as can be to write them. This was a very good move, I think, because all of those tests we now have are very, very helpful. And new contributors don’t have much trouble writing new tests, because the process is so standard, so widely exemplified, so simple.

Whenever I find myself hesitant to write tests in a project, I now wonder whether the reason is because I’m worried that the act of writing those tests is going to be a pain in the ass. If that’s the case, if I fear that my ass will be pained, then I wonder if I should be dissatisfied with the testing setup, and should try to figure out some way to make writing tests for that project less painful.

In some cases, the ass pain may be inescapable. Some programs demand it. But in many cases, like stylelint’s, the pain can be ameliorated with a little planning and systematization upfront.

6d. Don’t worry about typing extra characters

Above I mentioned that I don’t think the //-comments provided by stylesheet preprocessors are important enough to justify the troubles caused by non-standard syntax. I’m sure that plenty of Sass users would protest this with a complaint approximating this: “It’s tedious to close comments with */.”

If I embedded GIFs into these posts, I’d embed one here showing somebody cocking an eyebrow suspiciously. Maybe next time I’ll think about GIFs.

Many common justifications for non-standard syntax features are essentially the same as this. You may think you need Sass lists because you can then make a list of states and loop through it to create 50 selectors like .state-[statename] without having to repeat that .state- part. You may think you need JS arrow functions because they save you from typing function all the time. Or you may think you should name your variable p instead of people because you’ll avoid typing 5 letters again and again throughout the function.

Even if we didn’t have autocomplete in our editors, the complaint is pretty silly. I think everybody knows this, in their hearts. It is a mistake to give up any real benefit, any at all, for the apparent advantage of typing p instead of people.

A Modular Approach to UI Problem Solving

Sat, 20 Feb 2016 00:00:00 -0700

At React Rally last year, I watched an excellent talk by Lin Clark called “Making small modules actually work with webpack and npm”. At the beginning of the talk, Lin called out some participants in browserify vs. webpack arguments for their condescending remarks about authentic “modularity,” who sucks and who doesn’t. It’s been suggested that webpack (and other mono-repos, like React) are not “modular” because they are not split across separately packaged repositories; in response, Lin pointed out that the core of modular programming is an approach to problem solving, not necessarily an approach to packaging. And it’s the problem-solving part that’s most important.

She explained that modular problem solving is about dismantling bigger problems into smaller problems, then solving those smaller problems with individual modules that are highly cohesive and loosely coupled. Each module should contain everything necessary to solve a particular, focused problem, and then provide a public interface that makes it usable by an indefinite variety of other modules, in an indefinite variety of contexts.

If Problem A can be broken down into Problems B, C, and D, then you might consider creating Modules B, C, and D, each solving their own particular problems, upon which Module A can depend. Module A then becomes pretty small. And when you run into Problem X, you might realize that it also involve Problems B and D, so you can reuse those modules.

Everybody is their own little world, of course, so you may disagree with this statement — but in my experience, it seems like not much effort has gone into modular problem solving for user interface components. Most UI libraries present themselves as complete drop-in solutions — the keyword being “complete.” These complete drop-in solution can be as small as a tooltip or as large as jQuery UI or Bootstrap.

I can think of many reasons why this pattern may have developed, and I’m sure more knowledgeable and experienced developers can think of even more. But the frontend realm has evolved in such a way that it’s high time we start experimenting with more modular approaches.

The time is ripe

Dependency management and bundling

Until recently, the more small scripts you loaded, the slower your site would be; and the more dependencies any given script relied upon, the harder it would be to use. <script> tags, global variables, and weak or non-existent build processes meant that we had good incentives to write and use big libraries that tackled as many problems as possible within a single codebase.

But dependency management and bundling are no longer significant impediments for developers versed in npm and bundlers like browserify and webpack. As everybody should be. (The rest of Lin Clark’s talk was about that.)

Let’s get sophisticated

Because of the way that web development can blend into graphic design and Wordpress and super-fast site churn for small clients, etc., there are many consumers of UI components that do not want to know what problems need solving or the best way to solve them: they just want a drop-in fancy-looking Thing.

I can see how plenty of people would need complete drop-in solutions for the kind of work they do. But frontend development has become increasingly complex, and there are more and more frontend developers who are technically minded, who want to pick apart their problems and want to consider a variety of possible solutions, and want or even need to customize their approach to a unique context. For us, drop-in solutions are becoming less and less appealing, if not out of the question altogether, most of the time.

My attempts at modular UI libraries

I’ve been working on a different approach while building a few open-source React components. Instead of constructing complete, drop-in, strictly React-focused solutions, I’ve tried to isolate problems and extract small JS libraries (ideally vanilla JS) to solve those problems; then include them as dependencies in the React component.

So while developing these three React components …

… I’ve published these lower-level vanilla JS libraries:

… and these lower-level React libraries:

I wrote this little post to explain why I did that.

Modular problem solving means better solutions

When you’ve opened a modal, you shouldn’t be able to scroll the main page until you’ve closed that modal. This is a basic virtue of any decent modal. So every drop-in modal library out there that aspires to decency must implement its own solution to that problem (scroll-stopping). And because each implementation will be different, some will be great, some will be good, and some will be bad.

One of the important niceties of a scroll-stopper is that it prevents the awkward horizontal bounce that can happen when the scrollbar disappears and reappears as modals open and close. This is a small but somewhat tricky problem: you have to detect whether the scrollbar is present or not, and if it is determine its width (which varies among browsers and operating systems), then alter some CSS styles to compensate and un-compensate as the scrollbar disappears and reappears.

Plenty of modal libraries don’t do this at all or don’t do it very well. It would be better, of course, if those bad implementations willingly gave up their claim to life, and their host libraries adopted a superior scroll-stopping solution shared by one of the other modal libraries. A scroll-stopping module.

When building react-aria-modal, I wanted to stop the scroll the best way I could, and at the same time make my solution available to others, making it easy for them to do the same thing at least as well as I could. So instead of writing my scroll-stopping logic directly into my React component, I made no-scroll.

Here are what I consider to be the benefits:

no-scroll focuses on solving one problem the best way I know how, without getting tangled up in other modal requirements.
Other people building other modal libraries can use no-scroll instead of reimplementing the same (or worse) logic in their own codebase.
If other people know of better ways to solve that one problem, they can help out Me And All The World by improving no-scroll, thereby improving react-aria-modal and anything else that uses no-scroll.
Use-cases other than modals might exist for scroll-stopping; so other libraries and components that stop scrolling can also depend on no-scroll and share the solution.

Modular problem solving means reusable solutions

Another problem with modals is that they work best when they are dynamically appended to the end of the <body> tag, instead of living in the DOM tree right next to whatever trigger invokes them.

This isn’t really a problem in vanilla JS, but is a problem in React. So I didn’t want to separate the solution from React, but still wanted to separate it from the modal components, because I knew that it would be handy in other components. (For example, a loading spinner that overlays the whole screen is also better off if appended to the end of the <body>.)

So I made react-displace, which I use in react-aria-modal and also use in some project-specific code for loading spinners and other things.

Modals also need to trap focus. That’s not a React-specific problem at all. So I made focus-trap to handle that in vanilla JS, so it could be used by other modal libraries and also by other UI components that may want to trap focus, like popovers with forms in them or who knows what else.

And so on. By extracting a problem and generalizing its solution you can ensure that the same (hopefully good) solution is easily available for you when that problem rises again, maybe unexpectedly, in another context.

The diversity of JS frameworks makes low-level libraries especially appealing

I’m using React a lot now, and liking it. But I do understand why other people are using Angular, Ember, web components, whatever else, no big weird framework at all, and so on. And I also know that I’ll probably be using some other component-creating-JS-tool in the future.

A React menubutton, no matter how good, is not the only menubutton that the world or I myself will need. There is not and will never be a menubutton to end all menubuttons.

Let’s say that I pull off a truly fabulous menubutton component in React, for users of React. That’s swell for Current React-Using Me, and swell for other React users; but if all the important code is written in a React-specific manner, it sucks for non-React users and for Future Me. For them, my fabulous React menubutton is about as useless as a crappy React menubutton, or none at all. When a Non-React User or Future Me tries to create a new, equally fabulous menubutton component in the UI framework of the future — let’s call it KrazyKomponents — they’re going to have to reimplement whatever made my React widget fabulous. And then if they improve their KrazyKomponents menubutton with Rad Feature X, my formerly-fabulous React component falls behind — unless I put in the labor to write my own React-specific implementation of Rad Feature X.

And so everybody loses, forever.

With react-aria-menubutton, I tried to isolate the hard problems into a vanilla JS library that I and others could re-use, even in non-React menubutton components (or, even further, in non-React, non-menubutton components). Hiding and showing stuff isn’t very hard. Neither is toggling ARIA attributes. Those problems are trivial in the React code, and probably will be in any other decent view library (current or future). But the keyboard interactions are more tricky. The up and down arrows should move focus through the items, wrapping from top to bottom and bottom to top; and it’s all so much better if your user can type letters to skip to specific menu items. So instead of solving those keyboard-interaction and focus-management problems with React-specific code, I wrote focus-group in vanilla JS, which provides an API enabling that kind of menu-y behavior.

Somebody writing ember-menubutton, or angular-menubutton, or krazykomponents-menubutton can use focus-group to get the same sweet keyboard interactions that I worked hard on for react-aria-menubutton. With those keyboard interactions taken care of, the rest of their framework-specific menubutton code might be pretty trivial, really.

Additionally, if those Ember, Angular, or KrazyKomponents authors figure out better keyboard interactions, we can update the focus-group library and react-aria-menubutton wins, too.

Everybody can win, at the same time.

(By the way: The earlier versions of react-aria-menubutton had not extracted this solution into focus-group. So in react-aria-tabpanel I implemented very similar logic that also involved left and right arrows keys, but did not bother doing anything with letter keys, because that’s kind hard. Now, both UI components use focus-group, which means both have the same quality of keyboard interaction and I was able to add letter-key navigation to react-aria-tabpanel without any additional strain and suffering.)

So that’s something worth trying, right?

I think so.

It's Time for Everyone to Learn About PostCSS

Tue, 14 Jul 2015 00:00:00 -0700

A while ago, I wrote “I’m Excited About PostCSS, But I’m Scared to Leave Sass”. Since then, I have wholeheartedly embraced PostCSS (and left Sass, at least temporarily). I’ve been using PostCSS on large-scale projects, contributing to and authoring plugins, communicating with the maintainers to learn more about what’s possible; and that’s all gone swimmingly. Just swimmingly.

Meanwhile, the buzz around PostCSS has increased, provoking all kinds of reactions — curiosity, excitement, suspicion, confusion, weariness, bitterness, defensiveness, vitriol, exhiliration, flippant indifference, smug disdain, cheerful fist-pumping, and so on.

I have two points I’d like to contribute to the fuss:

You don’t have to be afraid. The number of tools out there to process style-code is actually pretty small (or so it seems to me, who also writes JavaScript). The addition of more possibilities won’t hurt anybody or anything.
Everybody who writes CSS should learn what PostCSS is — what it really is, and what it can be used for (not just what some choleric, reactive Tweeter said about it) — whether or not you end up using it right now. Because if you think PostCSS is simply an alternative to Sass and Less, you’re misinformed.

I don’t know what I can do to encourage #1 … Some blend of comforting words, coach-like encouragement, gentle prodding, and perspective? I’m probably not the best counselor in this case.

So I’ll skip to #2, where I may be able to help. Having worked with PostCSS for a little while now, I think I’ve learned some things about it that are worth sharing.

What we mean when we say “PostCSS”

With the word “PostCSS” we might alternately refer to two things:

There is PostCSS, the tool itself — what you get when you run npm install postcss — and
The PostCSS plugin ecosystem powered by that tool.

The tool itself is a Node.js module that parses CSS into an abstract syntax tree (AST); passes that AST through any number of “plugin” functions; and then converts that AST back into a string, which you can output to a file. Each function the AST passes through may or may not transform it; sourcemaps will be generated to keep track of any changes.

The AST provides a straightforward API that developers can use to write plugins. For example, you can cycle through each rule set in a file with css.eachRule(), or each declaration in a rule with rule.eachDecl(). You can get the selector of a rule with rule.selector, or the name of an at-rule with atRule.name. From these few examples you can see that the PostCSS API makes it pretty easy to work with CSS source code (much easier and more accurately than if you were to rely on regular expressions, like a chump).

That’s all that PostCSS currently does: it does not alter your CSS. A plugin might do that. Or maybe it won’t. PostCSS plugins can do pretty much whatever they want with the parsed CSS. One plugin could enable variables, or some other useful language extension. Another could change all of your as to ks. Another could log a warning whenever you use an ID selector. Another could add Masonic ASCII art to the top of your stylesheets. Another could count all the times you use float declarations. And so on, forever.

PostCSS can power an unlimited variety of plugins that read and manipulate your CSS. These plugins have no unifying agenda, except to solve problems.

Note that neither the tool itself nor the plugin ecosystem are direct analogues to Sass and Less. However: bundle up a set of related plugins that transform author-friendly stylesheets into browser-friendly CSS, and then you have something analogous to the good ol’ “preprocessors.”

Buuuut keep in mind that these “plugin packs” are just additional members of the ecosystem, like all the non-packaged plugins. No given plugin or plugin pack is or represents “PostCSS”: instead, we have a growing ecosystem that consists of many individual modules (powered by PostCSS).

A few implications of PostCSS modularity

☞ Attempts to maintain that PostCSS is (or should be) a “postprocessor”, as opposed to the “preprocessors” Sass and Less, are misguided.

Whatever your definitions of “postprocessor” and “preprocessor”, there will be PostCSS plugins that fall into both camps. According to most definitions, Autoprefixer is the iconic “postprocessor”; but there’s also stuff like postcss-each, which is very “preprocessor”-y.

There are also plugins that don’t transform your CSS at all, like stylelint and postcss-bem-linter and list-selectors.

If you want to maintain some pure distinction in your own build process, only using PostCSS plugins for what you think of as “postprocessing” — well that’s just fine: select your plugins with care.

Building on that …

☞ Attempts to tie “PostCSS” to specific syntax extensions or transformations are misguided.

PostCSS is a low-level module that facilitates the creation of other tools; and there are no limits on what those higher-level tools (the plugins) might do.

So PostCSS is not “about” allowing you write CSS Of The Future (syntax and functions from spec drafts) any more that it is “about” providing loops and conditionals and other Sass-like features. There are individual plugins that do both, and plugin packs that do both (cssnext and precss); but none of these represents the extent of PostCSS.

All this means that …

☞ When people think they are criticizing “PostCSS,” they are probably criticizing some particular plugin, or plugin pack, or particular way to use a particular plugin.

Which is fine — criticize away — but don’t trick yourself into dismissing other PostCSS-based tools because one of them rubs you the wrong way.

Which leads to the next point …

☞ You can opt into or out of any PostCSS plugin at any time.

Each plugin is only part of your build process because you put it there. If a plugin displeases you, remove it. Nobody is going to stop you.

Keep in mind, though, that some plugins can be used in a variety of ways, and maybe your displeasure can be appeased by using the plugin differently.

Maybe you, like Chris Eppstein, don’t like that with postcss-define-property you can create new properties that look exactly like real, standard properties. Well, there’s a very simple solution for that: make new properties that don’t look exactly like real, standard properties.

And if you think a plugin needs better examples or new options, you can contribute, because …

☞ Plugins are relatively small modules, so they should be responsive to feedback and easy to contribute to.

And if you don’t see a plugin that does what you want, the way you want to do it …

☞ You can always build your own plugin to satisfy your own desires.

This is one of the most important points. It’s worth repeating …

☞ You can always build your own plugin to satisfy your own desires.

That makes PostCSS new and fantastic — the ease with which you can try something totally different.

Or you can slightly tweak what’s there. If some plugin uses syntax you like but functionality you hate, create a spin-off with the “right” functionality. If some other plugin provides functionality you love but syntax you abhor, create a spin-off with the “right” syntax. And when people see what you’ve wrought and complain about your plugin, you can always suggest they write their own, their way.

(At the risk of sounding ridiculous and grandiose …) I’d suggest that, for many designers and frontend developers, really learning about PostCSS should demystify the realm of CSS processing. All that functionality that Sass and Less provide — it’s not magic: it doesn’t have to be that way: those are just people behind the curtain, and though they may be smart and hard-working, you don’t have to assume that they know better than you what’s best for your situation.

Problem-Solving with PostCSS

Working with PostCSS has reminded me that CSS processing exists to solve problems; that pretty much all problems have multiple solutions; and that I might be qualified to pick between alternative solutions, or even construct my own.

Empowered by PostCSS, I’ve been tackling my CSS needs problem-first — similarly to how I deal with JavaScript. Instead of jumping behind a massive library before I really know what’s going on, first I think about the actual problem that needs solving; then I consider existing solutions; and then I either use an existing solution or start working on my own.

I think that process is fun and interesting.

Also, I think it’s helped me simplify my approach to CSS. Remember — though it may seem long ago — that many developers have at some point resisted adoption of Sass and Less because they were concerned that the “preprocessors” did not solve enough real problems to justify the complexity they might add to authoring. I’ve never really agreed (maybe because I’ve never minded a little complexity in my build process); but I do acknowledge the critique and concede that if you don’t feel like problems are getting solved by a tool, you should not feel obliged to use that tool.

I built (and continue to maintain) a substantial Sass utility library because it solved important problems at my previous job, where I had to pound out a lot of CSS quickly. Now I have a new job, with different problems (e.g. scalability, and weird, unique theming requirements); and for my current needs I find myself preferring a minimalistic approach to CSS, involving at least as much analysis as processing. I also want to limit the powers at my team’s disposal, only including non-standard features selectively. PostCSS, the tool and the ecosystem, is an excellent fit for my current needs.

That’s enough

I was going to write another section called “Now, for kicks, let’s address some ill-conceived criticisms of PostCSS.” But I think this post is already long enough. And I think that the astute reader will already understand what most of my rebuttals would look like. If you do have an accusation that you’d like to hear rebutted, tweet me at @davidtheclark and I’ll tweet you back.

Building an Open Source React Component

Sat, 02 May 2015 00:00:00 -0700

Recently I set out to build a fully accessible dropdown menu-button with React. It would have been trivial to code an inaccessible dropdown menu-button in React — just toss in a little state and a click handler to hide and show the menu. But adding accessibility, accommodating screen readers and keyboard users, was not trivial; so I decided I’d try to bundle my solution into a module that could be open-sourced and shared, reused and improved by others — a self-contained React component that would be (ideally) complete, composable, flexible, and well-tested.

The creation of react-aria-menubutton (demo here) was an interesting process: I had to confront a few of the dilemmas that make UI components so hard to isolate, modularize, and share effectively. I thought it might be worth writing about those dilemmas and the solutions that I settled on.

Accessibility is Hard

Don’t let anybody tell you otherwise.

Yes, yes, yes, I know, of course, you’re right, absolutely — there are indeed some very simple, elementary best-practices that do affect accessibility (e.g. use alt text! semantic tags! colors with sufficient contrast!). And if that’s all you’re worried about, then yes, accessibility is easy. But pass beyond those basics, try to build something sufficiently complex with JS interactivity, and (unless your experience is dramatically different from mine) your research will lead you into a baffling hodgepodge of incomplete, contradictory, insufficiently exemplified, inadequately verified, usually outdated material.

(If you care about accessibility, and have some knowledge in the area, you could gain a few Twitter followers by delivering self-righteous one-sentence decrees that universal accessibility is a divine mandate and any web project falling short of it has failed because of the sloth, willful ignorance, concupiscence, and general immorality of its individual developers. Or you could be honest about this bad situation — that inadequate information and poor exemplification is thwarting the best intentions — and try to improve it.)

What I needed to build my menu-button component was an authoritative resource telling me precisely what WAI-ARIA attributes, keyboard interactions, and focus management I would need to implement in order to achieve the best possible accessibility. I am not an expert myself and do not have the resources to run my own user tests, so I needed to rely on authority. Luckily, my intended component fit nicely into one of the WAI-ARIA Design Patterns: the Menu Button widget. I decided to accept that spec and its clear requirements as my authority, without worrying further about other contradictory resources, and follow it to the letter. (It’s possible, given the apparent uncertainty and lack of consensus around these issues, that some people would disagree that this pattern is the “ideal”; but unless a higher authority provides a clear alternative, it’s the best I have to go on.)

The main reason I consider react-aria-menubutton worth open-sourcing is that it carefully implements this ARIA Design Pattern. With React (or jQuery, or just plain JS), showing and hiding some menu element with the click of a button is too simple to justify an open source component. However, I would not want to re-implement, again and again, the fine details of the accessible interaction, especially the keyboard accommodations. I think this probably applies to many other frontend components, as well: the hardest generalizable part to implement is often solid accessibility.

CSS is Unavoidable and Problematic

In the realm of UI, JS must always integrate with CSS and HTML. There is no escape from this. You cannot create a working component without DOM elements, and, in almost every case, that component will hardly look or function as intended without some CSS.

This is a major obstacle for encapsulation, which is an essential feature of effective modules. Everything in CSS is global, everything cascades. It is so easy to write CSS so badly, littered with unintentional side-effects, uncontrolled consequences, quantum entanglements. And browsers come with inconsistent default styling that developers override in unique and unpredictable ways. All of this means that the module developer cannot really know whether or not her CSS will actually work in your context. Nevertheless, almost all UI components need to come with a stylesheet, at least something minimal. And on top of that, those styles need to be easily customizable, because (outside of frontend toolkits) no two designs are exactly the same, and an effective component needs to fit nicely into an indefinite multitude of stylistic contexts.

(Maybe the advent of web components, with “scoped styles”, will eventually solve this problem; but who knows when that technology will practically affect day-to-day development.)

In my opinion, it is more important for open source UI components to provide the means for custom-styling than it is for them to include pre-written styles. In my many attempts to use third-party components, I have spent more time fighting against built-in styles than embracing them, more time annoyed by the component’s CSS than grateful for it.

With react-aria-menubutton, my attempt to alleviate this problem has several parts:

In the JS I inline a few styles — just a few that I think are inevitable — so that users don’t have to think about them at all.
Instead of working hard on a single impressive skin for the component, I provide style suggestions in two forms:
1. A totally bare-bones stylesheet containing the minimum essential rules to “complete,” in a sense, the component’s functionality. I imagine that the user could copy-and-paste this code into her own stylesheets and then add more rules to make the thing match its context.
2. Several examples of polished skins (toggle between them in the demo). If a user wants to take one and run with it, that’s fine; but I imagine that most people will use them as sources of ideas, extracting and modifying the rules that blend with their different-but-similar design.
In the markup I include a coherent set of classes that follows SUIT CSS conventions, and I document these classes in the Readme. I’m a true believer in BEM-style CSS, so I think this may be the most important part of the CSS strategy.
Those class names are configurable (within the conventions of SUIT) through options. Users can change the component name (e.g. .AriaMenuButton-menuWrapper becomes .MyComponentName-menuWrapper) or add a namespace (e.g. .AriaMenuButton-menuWrapper becomes .myNamespace-AriaMenuButton-menuWrapper).

Notice that my solutions to the CSS conundrum depend upon ways that I “imagine” or “hope” users will put the component to work. So it goes. As far as I can tell there is no way to fully encapsulate a UI component that requires CSS: the user will almost always have to be aware of implementation details in styles, and will almost always need to tweak those styles to some degree. That said, the approach that I’ve adopted might work for a lot of people, especially those people who have bought into some BEM-style methodology like SUIT.

JS Distribution Problems: Receiving Dependencies, Exposing the API, Compiling

The jQuery plugin has been the dominant form of open source UI components for some time. Probably one key to the success of that ecosystem has been its standardized format for receiving dependencies and exposing APIs: expect a global $ and connect your plugin to that in a specified way.

That method worked for jQuery … but it’s outdated for many of us. More modern JS workflows avoid global variables, preferring modules — which in turn require a compilation process. And React, specifically, also requires compilation if the plugin code uses JSX.

But an open source author cannot know whether the user will have global variables or modules, will configure a suitable compilation process or not. Therefore, I think, a React open source component needs to work with both globals and modules, and needs to be distributed in a pre-compiled form.

I decided it would be justifiable to assume two user types: global-users and module-users. Global-users would have any of the library’s dependencies (just React, in this case) exposed as global variables and would expect the library to expose its own global variable. Module-users would import the library as needed and expect dependencies to resolve themselves.

Because I want to author the code with modules and JSX (and ES6), obviously I need to compile to a dist/ directory. But I need to compile two formats: the global-user format and module-user format. Following a pattern I saw in react-dnd, I setup the following build process:

Use Webpack to compile to a dist/ directory a bundle that expects dependencies as globals and exports the library as a global. Global-users should use this.
Use Babel to transpile JSX (and ES6) from src/ to a dist-modules/ directory, and have index.js reference files in that pre-compiled directory. Module-users will then import these pre-compiled files when they import the npm module; so the code should work regardless of the module-user’s build process (i.e. the user doesn’t have to deal with JSX or ES6).

(There’s one aspect of this “distribution problem” that I do not think I have suitably resolved: how to optionally utilize React’s CSSTransitionGroup. The CSSTransitionGroup component is only included in React.addons, a larger dependency than the base library — so I cannot assume that it will be available, and I do not want to surreptitiously import a larger dependency than the user expects. The solution I settled on is unusual, I think: provide a transition option that expects users to manually pass the CSSTransitionGroup component if they want to use transitions (see the docs). It’s not a familiar pattern; but it does solve the problem. I wonder if other people know of any alternate, better means to the same end?)

(UPDATE: Looks like a future release of React will allow addons to be included individually, without pulling in the whole pack — so that might take care of this last confusing problem.)

Testing

UI modules have always been inadequately tested — partly, I think, because with the DOM and CSS involved (as essential parts of the module’s “API”, really), the surface to test is large and confusing; also partly because UI developers aren’t always accustomed to the value of testing.

React makes this easier, with its functional format (props go in, DOM comes out) and handy TestUtils. Testing with React is straightforward enough that it should be expected of any open source React component.

Testing is especially important for react-aria-menubutton because it aspires to achieve accessibility by following an ARIA spec to the letter. The tests need to match the spec. To ensure that this happens, I’ve scattered quotations from the spec throughout the tests, illustrating which test-cases address which specific requirements.

Summary

Here’s a little summary of the measures I took in my attempt to make react-aria-menubutton a decent open source React component:

Follow a WAI-ARIA Design Pattern to ensure accessibility.
Provide users the means to write their own styles instead of pre-written styles they will have to override (via configurable classes, a base stylesheet, and fleshed-out examples).
Use strict SUIT CSS class naming conventions to make styling as smooth as possible — to ensure that the component follows best-practices, regardless of what the user’s CSS looks like.
Compile one version of the component, for global-users, to accept global dependencies and expose the component as a global variable (in dist/).
Compile another version of the component for module-users, which should work regardless of the module-user’s build configuration (in dist-modules/).
Provide a means for the user to manually pass in React’s CSSTransitionGroup if she wants transitions (this is the one I’m uncertain about …).
Write lots and lots of tests.

I think it’s still an open question whether React will sprout an ecosystem of high quality open source components that add real value to applications (especially accessibility) while remaining flexible enough for reuse. The quandries mentioned above, though, are not specific to React: almost all of them will apply to any open source frontend component that has to deal the overlapping of HTML, CSS, and JS and diverse frontend build processes and workflows. A bigger question, maybe — one applicable to non-React users — is this: Can we raise the bar on open source UI components, figure out how to modularize them more effectively than is typically done with good old jQuery plugins? react-aria-menubutton is my (first) attempt to experiment with that possibility and confront its challenges. I’m eager to see what other people come up with.

I'm Excited About PostCSS

Tue, 13 Jan 2015 00:00:00 -0700

I intend this to be a brief, spontaneous entry about one of my many tooling uncertainties. I hope it will provoke some others to weigh in on a choice that I consider important (if you write stylesheet code) but difficult (unless by haruspicy or other means you know the future) and definitely underdiscussed.

To be mentioned:

PostCSS — but everywhere I say “PostCSS” you could also think about Rework
Sass — but everywhere I say “Sass” you could substitute Less

Please follow up with your own tweets or blog posts about “Why we should all switch to PostCSS” or “Why it would be foolhardy not to rely on the Venerable Sass”, etc. (I’m serious. Tell me what to do.)

Standard Syntax and The Future CSS

There are (at least) two essential features that everybody wants (or should want) to add to their stylesheets: variables and calculations. So every CSS processor must provide (at least) those. Sass has its own $variables and operations; Less has its own @variables and operations; but a set of PostCSS plugins offer the synax of custom-properties and calc() — the syntax of present and future CSS standards.

The deeper, wiser parts of me don’t care whether I type $llama, @llama, or var(--llama) as I work. But one thing they do care about (besides the acquisition of desserts) is the interoperability of my syntax, and the only way to achieve that is to establish some kind of standard … which, it turns out, is what standards bodies are for. Because PostCSS plugins enable me to use standard CSS syntax, it’s not out of the question that the code I write using PostCSS might make sense to other CSS processors — not to mention real browsers. Even now, I could switch between postcss-custom-properties and rework-vars, postcss-calc and rework-calc without having to modify my stylesheets. The same should go for all the other PostCSS and Rework plugins that mimic standard syntax. That is fantastic —— that alone is almost enough to convert me.

Sass is definitely “the most mature, stable, and powerful professional grade CSS extension language in the world” (as its website boasts). Like jQuery, Sass is one of the few frontend tools that we can confidently predict will remain popular for years to come. But does that make it more secure and reliable than using standard CSS syntax and PostCSS? Even if PostCSS never takes off or fizzles out (which is unlikely, because of Autoprefixer’s popularity), some other tool could step in and carry the torch, simply by allowing us to use the standardized syntax that browsers will eventually understand.

(See cssnext if you’re interested in PostCSS plugins that “allow you to use tomorrow’s CSS syntax today.” It is packaged as a standalone tool, but all of its pieces are modular.)

Mature and Monolithic or Fresh and Modular?

While Sass delivers a monolithic extension language with a fixed feature-set, PostCSS is a framework with which to build focused plugins. A PostCSS user can selectively include plugins for features that fit her needs, preferences, and whims, or write her own if nothing exists.

Why does this appeal to me?

Sass provides more than I want. Not just more than I want to use; but more than I want myself or the other people working on the same stylesheets to be able to use. I think it offers too much — more than enough to become cleverly counterproductive. (Which specific parts of Sass I’d leave out is a topic for another post.) But I cannot pick and choose pieces of Sass; so if I include Sass at all, I must welcome into my work-home an API that is larger and more complex than I need or want. Through internal conventions and code review, I might be able to enforce a whitelist of Sass features; but I would prefer to be more selective upfront, by limiting what’s possible to what (I think) would be most productive.

(Is there a life lesson in the paragraph above? I’m not sure …)

Also, with compact modules the barrier to creation is low. I am confident that I could contribute to whatever existing plugins I choose to use, and also confident that I could write my own plugins as needed. (Nicolas Gallagher published a good post about doing that with Rework.)

It’s tempting to relate this discussion to ongoing debates about modularity in the JavaScript community, which pit the ideals of small, focused, UNIX-y packages against feature-rich behemoths like jQuery and Ember. In many respects, I think, the analogy makes sense. But if you read through the code of some PostCSS modules (probably short, relatively straightforward code), you’ll see that the simplicity of CSS — both the language itself and the things that we do with the language — seriously alters the premises of comparison, in favor of modularity. Because some of the strongest arguments in favor of large projects like jQuery and Ember hinge on the premise that those projects do things you could never do on your own, solve problems you could never solve on your own, tackle all kinds of complexity that would overwhelm you on your own, etc.; but your CSS problems aren’t really that complex, and with PostCSS you probably have more than enough power to solve them.

A Word About Using Both

You could use both: write SCSS files, compiled them to CSS, post-process those with PostCSS — go hog wild. That’s one way to aggregate power in this world. And if your primary reason for adding PostCSS to your Sass-based process is to have more power at your disposal, that would work. Harness them both. (Use @for and @if and Sass maps and then write crazy PostCSS plugins and make your fantasies reality.)

However: This would not simplify your dev stack — which is one of my goals in considering the switch. This would not selectively limit your powers — another of my goals. And you would still have to choose which process gets to take care of the key features — variables, calculations, imports.

Conclusion?

How do I conclude this?

The more that I write, the more I feel like I should switch from Sass to PostCSS. I seem to be convincing myself — am I convincing anybody else?

But I can’t shake the concern that dropping a tool as proven and popular as Sass — one of the few frontend tools we can truly, indefinitely rely on — is like setting myself adrift, and maybe unnecessarily.

… I should probably write a poem about it.

What do you think?

An Auto-Enforceable SCSS Styleguide

Sat, 13 Dec 2014 00:00:00 -0700

Automated Enforcement Matters, and SCSS-Lint is Excellent

(If you don’t really want to read, just look at SCSS-Lint and seriously consider using it.)

There seems to be universal agreement that consistent, predictable code style is important, in any language (at least if more than one fallible human is working on the project for more than one week); and that thorough code styleguides, which enable that consistency and predictability, are well worth writing, using, and sharing.

In the world of stylesheet-code (CSS and its relatives), plenty of individuals and organizations have published their approaches, with suggested guidelines spanning the gamut of from minute finetuning (whether there should be a leading zero in 0.5) to big-picture architecture (how modules should be named and organized). I’ve been trying to keep track of them in a Scalable CSS Reading List: take a look.

So I don’t think I have to advocate for the sharing of guidelines, generally. But I do think there could be more advocacy for the sharing of automatable guidelines. In that area, the CSS-cluster is far behind other languages.

There’s a vital distinction between discussions of best practices and the actual codification of clear, specific, concrete conventions and standards that will constitute, for some group of developers, enforced expectations. All the discussions are valuable, of course; but it’s easy to forget that they must be realized in day-to-day practice, in keyboard-tapping and mouse-clicking and glazed-eyeball-flickering. The “good ideas” should aspire to become “the way things are done”. That’s why I think that among the most important properties of any guideline, whatever its scale or focus, is if and how it will be enforced.

Sometimes, for some guidelines, manual code review with human senses and human brains is the only viable means of enforcement. Machine minds probably can’t determine meaningful rule categories, when to use utility classes, whether @mixins and @extends are helpful or harmful in a given situation — and so on.

But sometimes automation will work — maybe all on its own, or maybe as a first step that eases the burden on human brains, pointing out suspicious characters that deserve a second look. (… thank god I’m just talking about code and not law enforcement … machines are so much easier … I swear I’m not authoritarian …) And those times are the best times. Just trying to make a guideline auto-enforceable will probably improve it, since you’ll have to shake off all vagueries, honing what might be loose recommendations into well-defined and delineated, observable patterns.

Here’s a sentence for you: Any styleguide will become more valuable as more of its enforcement becomes more automated.

All that’s to say that the world of stylesheet-code would benefit from more and better tools for code style enforcement. Currently, SCSS-Lint stands alone, in my opinion. Thankfully, SCSS-Lint is excellent. Full-featured, configurable, exceptionally well-maintained. One of the major reasons I stick with SCSS is because of SCSS-Lint. There should be more tools like it. (I’m not fully warmed up yet to CSSComb — maybe I need to give it some more attention — and that seems to be just about the only other option right now (?).)

If you write SCSS, give SCSS-Lint some serious thought. Furrow your brow. Work it into your build system. Plug it in to your text editor. Talk with your family about it over the holidays. If you do not write SCSS, look into SCSS-Lint anyway, and if you have some extra energy maybe do one of the following: (1) convince me that CSSComb is as good as SCSS-Lint (or make it as good); or (2) make or contribute to a LESS or PostCSS/Rework linter that might one day match it (like maybe this one?).

Enough jabber. I share this little guide below for a few reasons:

As an introduction to the powers of SCSS-Lint, for those who don’t yet use it.
As an example of the auto-enforceable section that should be part of every real-world stylesheet-code styleguide. (Note that this does not aspire to be a complete styleguide, like Harry Robert’s cssguidlin.es: it’s just the auto-enforceable part. Note that.)
Just to share.

My SCSS-Lint-Powered SCSS Styleguide

Please keep in mind that this is just my styleguide, not The Styleguide, and SCSS-Lint is completely configurable to fit your own weird, sometimes misguided preferences.

If any terminology below is unfamiliar, search it out in the CSS 2 spec or the Sass docs. (I’m trying to use these words correctly: please send a tweet if I’m mistaken. Educate me.)

After each guideline I’ve included the name(s) of the SCSS-Lint linter(s) that will enforce it. And I’ve posted the configuration file that would make SCSS-Lint enforce all of this, so you can inspect or copy-paste it.

Last point: I am not going to spend a lot of time below justifying each guideline. A few are really just personal preference, but for most I do have some rational justification. But there are enough words on this page already. (Also, the SCSS-Lint documentation offers a little justification for each linter, which I usually, though not always, agree with.) And when I do justify, I may be facetiously dogmatic. If you think I should take the time to further explain something, send a tweet.

Whitespace and Punctuation

» Indent using 2 spaces. Or tabs. Whatever. Fight about it. [Indentation]

» End each file with an empty newline. After all, you’re not an animal, are you? [FinalNewline]

» Include an empty line between all statements — i.e. rule sets, at-rules, and Sass directives. Even the nested ones. Spaces help people, and people are important. (Variable definitions are like properties and don’t need to be spaced.) [EmptyLineBetweenBlocks]

» Include spaces after commas and colons, not before. As in written English. [SpaceAfterComma, SpaceAfterPropertyColon, SpaceAfterPropertyName]

» Do not include spaces between parentheses and parenthesized. As in written English. [SpaceBetweenParens]

» Use single quotation marks. That way you don’t have to push shift, everyone’s least favorite key. [StringQuotes]

» End every declaration with a semicolon, with no whitespace in front of it. (Did you even think about putting a space in front of it? What is wrong with you?) [TrailingSemicolon]

Selectors and Names

All of the guidelines in this section reflect my preference for class selectors and class selectors only (except in highly unusual and probably unhappy circumstances), and keeping the hierarchy as flat as possible.

Excuse me: I say “my preference” but I mean “God’s law”.

» Never use ID selectors. Find another way. (No, this is not “throwing out the baby with the bath water”. This is “not pooping in the bath”.) [IdSelector]

» Do not qualify type selectors. Better yet, don’t use them at all, if possible: just use classes. [QualifyingElement]

// bad
a[href='horse'] { ... }

// maybe fine
[href='horse'] { ... }

// good
.horse { ... }

» Provide lowercase, hyphen-delimited names for Sass variables and directives. That way they fit in with standard CSS keywords and property names. [NameFormat]

» Do not chain more than three simple selectors. In almost every case, one simple selector is best (that is, no chaining, flat specificity, world peace). Some situations call for two. But let’s just draw the line at three. Find another way. [SelectorDepth]

// good
.horse { ... }

// often useful
.horse + .horse { ... }

// suspicious
.horse > .donkey { ... }

// uh ...
.horse > .donkey + .mule { ... }

// call the police
ul li a span { ... }

» Include a line break between each selector in a group. [SingleLinePerSelector]

// bad
.horse, .donkey, .mule { ... }

// good
.horse,
.donkey,
.mule { ... }

» Include a single space between selectors and the curly braces that begin declaration blocks. [SpaceBeforeBrace]

» Use a consistent selector naming convention. This is probably the least globally portable guideline in my guide, because it’s hard to achieve consensus on naming conventions. But maybe you’ll like mine? I try to be strict (not because I’m a fascist but because I’ve seen strange horrors in stylesheets).

Here’s what I do: Class names should match the following regular expression:

/^(?:u|is|has)\-[a-z][a-zA-Z0-9]*$|^(?!u|is|has)[a-zA-Z][a-zA-Z0-9]*(?:\-[a-z][a-zA-Z0-9]*)?(?:\-\-[a-z][a-zA-Z0-9]*)?$/

This regular expression enforces the SUIT CSS naming convention (but without requiring the initial capital letter on a component). The possibilities can be summed up like this:

.u-utilityClass {}
.is-stateClass {}
.has-stateClass {}
// And maybe I'll add other verbs for state classes, as needed
.ComponentName {}
.ComponentName-descendentName {}
.ComponentName--modifierName {}
.ComponentName-descendentName--modifierName {}
// All of the above could also use `componentName`, without the initial capital

(All non-class-name selectors should be straightforward hyphenated lowercase — but I’d try not to use them anyway.) [SelectorFormat]

Rule Set Innards

» Include a line break between each declaration. Keep declarations isolated: that way you can monitor and discipline them more easily. [SingleLinePerProperty]

» Include quotation marks around URLs. SCSS-Lint documentation explains why. [UrlQuotes]

» Use shorthand properties when you can. As is the case with husbands: shorter is better. [Shorthand]

» Do not include units on zero values. It could be zero of anything: we don’t have to know. [ZeroUnit]

» Use border: 0 instead of border: none. Cuz. [BorderZero]

» Do not nest selectors more than 3 levels deep. Zero levels of nesting is best, of course. One level is often handy, and arguably helps organize some common code (especially pseudo-classes and pseudo-elements). Two or three raises eyebrows and specificity. More invites (induces?) disaster. [NestingDepth]

// best
.horse {
  font-size: 10em;

  // handy
  &:hover {
    font-size: 20em;

    // eyebrow-raising
    & > .donkey {
    color: #eee;

      // disaster-inviting(-inducing?)
      & + .mule {
        margin: 100em;

        // disaster-in-progress
        ul li a span {
          color: $death;
        }
      }
    }
  }

» Do not type vendor prefixes. You have too much life to live. Use Autoprefixer — or, at the very least, Bourbon or Compass mixins. [VendorPrefixes]

» Order declarations in a logical manner. Here’s one logical manner that SCSS-Lint can enforce: (A) @extend directives first; then (B) @include directives without inner @content; then (C) vanilla CSS declarations, with their properties and values; then (D) @include directives with inner @content; then (E) nested statements (rule sets and at-rules). [DeclarationOrder]

Why? (This is going to get weird.) A and B belong at the top so that C and E can override them as needed — whereas A and B should never need to override C or E, I think, or something has gone sour and refactoring is preferable. E is at the end so that it can override anything. And D is where it is because God only knows what it’s going to do. (I’m not sure this logic is 100% foolproof, but I’m giving it a try. We can’t simply be spectators to chance, can we? We must make choices and live with the consequences. There’s a movie about that, right?)

Colors

» Do not use color keywords — such as green instead of #008000. Color keywords are for children, aging parents, and pranks, not the robot-communication we all aspire to. [ColorKeyword]

» Use the shortest possible hex value. #fff instead of #ffffff. (See the statement about husbands, above.) [HexLength]

» Use lowercase letters inside hex values. #fff instead of #FFF. Unnecessary capital letters are obnoxious to the sensitive soul. And, again, why use shift when you don’t have to? Last reason: lowercase letters are, I think, a little bit easier to distinguish from numbers. I’m not making that up. [HexNotation]

Numbers

» Do not include unnecessary trailing zeros after a decimal point. 2em instead of 2.0em. [TrailingZero, UnnecessaryMantissa]

» Do include an unnecessary leading zero before decimal values less than 1. 0.5em instead of .5em. Don’t you think it improves readability? I do. [LeadingZero]

Sassy Things

» @extend placeholders only. This practice will help prevent some common @extend-related mistakes and misunderstandings. [PlaceholderInExtend]

» Include one space before any ! and no spaces after it, with !important and !default declarations. That’s just how it’s done. [BangFormat]

» Put @else on the same line as the curly brace it follows. [ElsePlacement]

// bad
@if {
  // ...
}
@else {
  // ...
}

// good
@if {
  // ...
} @else {
  // ...
}

» Do not include leading underscores or filename extensions in the basenames of SCSS files that you @import. @import 'horse/donkey' instead of @import 'horse/_donkey.scss';. [ImportPath]

Avoiding Mistakes

» Do not define any property more than once within a single rule set. You probably did it by accident, anyway. [DuplicateProperty]

» Do not leave @debug statements in your code. Clean up after yourself. [DebugStatement]

» Do not leave empty rule sets in your code. Pay attention. [EmptyRule]

» Only use three or six hexidecimal characters. Nothing else means anything, right? [HexValidation]

» Do not misspell properties. In fact, do not misspell anything, ever. [PropertySpelling]

The Role of Utility Classes in Scalable CSS

Sat, 20 Sep 2014 00:00:00 -0700

Lately, I’ve been thinking about how to write scalable CSS. Not so much about how to pull off snazzy effects, or take advantage of the latest modules, or play clever tricks with preprocessors — but how to create stylesheets that will remain coherent, maintainable, consistent, and extendable as projects grow and change — and how to do this systematically.

I’ve been reading everything I can find on the subject — which includes some very good stuff. (I’ve put together, and plan to maintain, a Scalable CSS Reading List to share what I consider the most important resources.) But there’s one particular question that keeps pestering me, a question that is rarely addressed, and never at length: Where exactly do “utility classes” fit in? — why, when, and how should they be used?

Every frontend framework includes some utility classes, but none offer substantial advice about when or why to use them. Considering that any given CSS declaration could be transformed into a utility class, is it possible that every declaration should be? If you can build a component, a page, or a whole site with utility classes alone, should you? (In “Challenging CSS Best Practices”, Thierry Koblentz argues for such an approach: “Atomic CSS,” he calls it.) If not, where do we draw the line; how do we determine if we’ve gone too far? Can reliance on utility classes hurt maintainability? The mind swims.

Two CSS Paradigms: Component and Utility Classes

All the scalable CSS approaches I’ve learned about endorse two distinct paradigms of classes: I’ll call them component and utility classes.

These two paradigms represent fundamentally different methods of styling; taken to extremes, they can result in dramatically different code and dramatically different workflows.

(I consider the older dichotomy between “semantic” and “presentational” classes outdated: I fully agree with Nicolas Gallagher that “the primary purpose of a class name is to be a hook for CSS and JavaScript” and “class names should communicate useful information to developers.” Either component or utility classes could be considered “presentational,” by the old logic, and I wouldn’t consider that to be a problem.)

Component Classes

A component class encapsulates the declarations required to style an element within the context of a component.

The HTML simply references that component’s classes, and maybe some modifiers, to implement the pattern. Bootstrap’s .btn exemplifies the single-element component. Other, multi-element Bootstrap components rely on namespaced classes or particular HTML structures. Systematic naming conventions like BEM’s and SUIT’s help to conceptualize, implement, and scale the component paradigm.

Using component classes (and SUIT naming), some navigation markup might look like this:

<nav class="Nav Nav--light">
  <ul class="Nav-list">
    <li class="Nav-item">
      <a class="Nav-link" href="...">...</a>
    </li>
    <li class="Nav-item">
      <a class="Nav-link is-current" href="...">...</a>
    </li>
  </ul>
</nav>

The class .Nav-link will apply all the rules necessary to style that <a> in that context. The .Nav component as a whole is reusable, but the .Nav-link class will never be used outside of its context — outside of a .Nav.

Keep in mind that what I’m calling “components” can be as granular as the situation demands, and “components” can contain other “components.” They are simply coherent, reusable patterns, and might address any level of a design — atoms, molecules, organisms, templates, or pages, in the terminology of Atomic Design. Also (with a nod to SMACSS), components might be organized into categories targeting different responsibilities — for instance, typography (like a .Heading) distinguished from layout (like a .Grid) and interface (like a .Button or a .Nav). OOCSS fans might call them “objects.” The point is that component classes represent named units, explicitly related to a reusable pattern, whose styles are defined and modified in a stylesheet.

Utility Classes

A utility class applies a single rule or a very simple, universal pattern. Think .float-right, .align-center, or .font-small for single rules; .list-unstyled, .clearfix, and .visually-hidden for patterns. (Sometimes they’re called “helpers,” as in Bootstrap.)

Utility classes are as simple, composable, and reusable as possible; so they will (and are intended to) end up scattered throughout your markup, performing their little role in diverse and sundry contexts. They must be strictly categorized and tightly focused, or they lose their … utility — their raison d’être. They must epitomize the single responsibility principle. Unlike a component class like .Nav-link, a utility class like .float-left could show up anywhere, on any element, in any context, so we need to know that it will always do exactly the same thing. That’s why The Authorities agree that utility classes must never change, and why they are a rare case when using !important might be the right choice).

(If you’re at all uncertain what I mean by “utility class,” have a look at some collections: Foundation’s, Bootstrap’s, UIKit’s, GroundworkCSS’s, and SUIT’s.)

More so than component classes, utility classes bring styling directly into the markup, without even the mediation of a name. Design patterns can be anonymous aggregates of globally shared styles. So if you want to change the appearance of an element styled with utility classes, you’ll have to change the markup — the class list, specifically — not the stylesheet.

Typically, it’s suggested or assumed that God made utility classes for straightforward situations calling for very few rules. You just want a button floated right, a centered heading, a different color, invisible text. Why give an element its own name, its own selector, its own ruleset in some stylesheet — why conceptualize a “component” for it — when all you want is to apply a very common, probably very basic pattern?

Theoretically, though, entire components and entire sites can be constructed by piecing together utility classes. Relying on utility classes alone, the navigation markup from above might look like this:

<nav class="pad-2 bg-light text-med text-upper">
  <ul class="list-unstyled clearfix">
    <li class="float-left">
      <a class="link-unstyled pad-1x2 bg-button" href="..." >...</a>
    </li>
    <li class="float-left margin-left-1">
      <a class="link-unstyled pad-1x2 bg-accent" href="...">...</a>
    </li>
  </ul>
</nav>

More Comparing and Contrasting

With component classes, implementation of a new design pattern will probably involve the creation of new classes and more lines of CSS. With utility classes, new design patterns can often be implemented with existing classes, no new CSS.
With component classes, maintenance and modification of styles happens in the stylesheets. With utility classes, it happens in the HTML, in class attributes.
Component classes entail repetition in stylesheets. Utility classes entail repetition in HTML.
Component classes are scoped to their component and should be built to prevent leakage; so one component can change without affecting others. Utility classes are global dependencies; so any change to a utility class will affect any number of elements.
Component class names primarily represent the relationships of component parts, usually without reference to style. Utility class names exclusively and transparently represent the styling applied.
Component classes are flexible: they can be attached to arbitrary, variable styles, different themes, etc. Utility classes are rigid and unchangeable — ideally, they are just as reliable as a declaration in CSS.

Some Alleged Benefits of Utility Classes

The component-class paradigm is a more straightforward, traditional utilization of CSS, I think. Apply a distinct class and tie that class to some styles. Add, modify, and remove declarations in the stylesheet. And so on. Though you may never achieve the fabled “Separation of Concerns” — and may not even care to — you will be closer to it and reap some of its rewards if you use component classes more, utility classes less.

So it’s worth articulating and assessing what people consider to be the benefits of utility classes. Why do we use them at all? Why are they included in every frontend framework? And why might some people consider using them exclusively?

1. DRYness and Consistency

Apply .float-left whenever you need something floated left, and you won’t end up filling stylesheets with repeated float: left; declarations. (CSSLint will be proud of you.) Reuse color utilities (e.g. .bg-dark), and you won’t have to copy and paste hex values; additionally, when the design changes, you can alter the value in one place instead of many. Rather than throwing 3px, 6px, and 7px of padding here and there — whatever seems right at the time — rely on a simple .pad-sm for consistent spacing. Utility classes can help you reduce repetition in your CSS and inadvertant irregularity in your style.

This benefit, however, is negligible if you use a preprocessor. The reuse of single-rule classes like .float-left merely shifts repetition from CSS to HTML. It’s still repetition: you still tell every individual element you want floated left to float left, in one way or another. And for more complex patterns and particular values, a preprocessor — with variables, mixins, and extends — enables the same degree of consistency by other, arguably more author-friendly, means.

2. Filesize

By taking repetition out of the CSS, utility classes reduce CSS filesize.

Preprocessors can’t match this benefit. Using mixins and variables to repeat patterns and values does result in DRYness and consistency but does not cut back on the size of the delivered CSS: every repeated mixin and variable generates repeated declarations.

Sass @extends can be used to reduce some repetition — but they are problematic in other, key ways. And rather than advocating @extends, I’d argue that this benefit is questionable. CSS filesize should be one of your last optimization concerns; and once Gzip gets involved, it’s possible that the savings won’t make a substantial difference. In any situation where the scalability of your CSS is at issue, where there’s any danger of things getting messy and confusing and out-of-control, authoring and maintenance considerations should trump kilobyte savings.

3. Expedience

There is no question that utility classes are handy, allowing HTML authors to apply styles more directly. Especially for those elements that require only one or two rules and don’t play an obvious role in some component structure — why add an extra layer of abstraction?

If you move quickly from project to project, a full set of utility classes — or a method of generating them as needed — could speed up your work. And it’s possible that utility classes could help backend engineers, or other collaborators, get things done without modifying any stylesheets.

There’s no denying this benefit; however, it needs to be considered in the context of your workflow, because often expedience is much less important than long-term maintainability — though sometimes it is the top priority.

Some Dangers of Utility Classes

Each of the dangers below would be minor, even trivial, if you use utility classes sparingly. But the more you rely on utility classes, the more significant these dangers become.

1. Inconstant Appearances

When an element’s appearance won’t stay constant, reliance on utility classes can become troublesome. Responsive design is one such circumstance: For example, if things float right at some widths but not others, different utility classes will have to be made to target different widths — something like float-right-sm, float-right-md, and float-right-lg. Or else you might need to develop a more complicated system that uses JavaScript to enact style changes (Thierry Koblentz does something like that).

You know things are going downhill if you ever end up with elements bearing the utility class .float-right that are not, in fact, floating right, for one reason or another.

Similar issues will arise if your project involves themed variations that rely on the same markup. In such cases the abstraction of component classes can allow for flexibility that the directness of utility classes precludes.

2. Readability and Reusability of Component-Relationships

The more you rely on utility classes, the fewer of your design elements will be explicitly associated with components, with class names that reflect their relationships to one another (like .Nav, .Nav-item, .Nav-link). Although the styles will be transparently communicated by the utility class names, the conceptual structure of the components and the page will not; and that ambiguity might result in some confusion down the line, when somebody is trying to read and understand your code, maybe trying to reuse a particular pattern.

3. Encouragement of One-Off Styles

Without component classes, any repeat occurrence of a pattern might feel more like a re-implementation than reuse — which could lead to slight tweaks here and there, variations that seem right in the heat of the moment but add up to inconsistency. At some point you may realize that your broad set of utility classes gave HTML authors too much freedom to diverge, to favor expedience over architecture, and the maintainability of your code suffered.

4. Too Many Decisions

With utility classes, it’s up to HTML authors to apply the right cluster of styles to the right elements. A good component class system, on the other hand, might allow authors to create HTML without knowing or caring much about why it ends up looking the way it ends up looking.

An important goal of any systematic methodology is to reduce on-the-spot decision-making — and component classes do that better than utility classes.

Conclusions, Prescriptions, Guesses

Light use of limited utility classes, for patterns that you know will never change, should not cause any problems that can’t be mended easily — by removing the utility class as needed, shifting the style-burden back into the stylesheets.

And there are some particular circumstances when heavy reliance on utility classes — building complete components or pages solely with them — might be ok:

If you are not using a preprocessor to facilitate DRYness and consistency.
If your workflow makes it just as easy or easier to adjust styles by modifying class lists in templates than by modifying rule sets in stylesheets.
If your responsive design hinges on very reliable breakpoints, and that’s all the inconstancy you anticipate.
If you are building a unique pattern, something you don’t plan on rebuilding the exact same way in other places.
If filesize is at an absolute premium.

In most situations, though — especially for large-scale projects and reusable components — it seems to me that the benefits of systematic component classes will prove more valuable than the expedience of utility classes. By using component classes, you get the communicative value of naming element groups and relationships; you encourage the creation of coherent, relatively self-contained components intended for reuse; and you allow for the flexibility to vary styling, to some degree, without changing markup.

I hope that’s enough words for you. That’s enough for me.