adamsilver / maintainablecss.com-jekyll

Write CSS without worrying that overzealous, pre-existing styles will cause problems. MaintainableCSS is an approach to writing modular, scalable and of course, maintainable CSS.

MaintainableCSS

Write CSS without worrying that overzealous, pre-existing styles will cause problems. MaintainableCSS is an approach to writing modular, scalable and of course, maintainable CSS.

Visit website

maintainablecss.com-jekyll's Issues

FAQ

• prototyping - use whatever, it's a prototype, bootstrap, atomic css whatever.

Note on mixins and reuse

color: red; vs @include red(); and refer to comma - also perf for this one.

.clearfix vs comma for those, but even the comma isn't enough because the clearfix as an example should only be applied at various breakpoints etc - here a mixin is actually helpful (if you're using sass or whatever) but from a maintainance persective only. That is, what gets output is the same otherwise, duplication, and performance hits - although not problem, ull end up with the same shit.

State and Modifiers: why are new classes necessary?

Basically, what makes this…

.myModule-isHidden { display: none }

… materially better than this?

.myModule.isHidden { display: none }

---

One obvious difference is the same as with components: if you ever declare …

.isHidden { display: none }

… then that style will apply to all uses of isHidden. But in this case, to me that seems a strength rather than a weakness: which isHidden isn’t going to want to display: none? (And if there is one – well, the chained selector has higher specificity than the naked one.)

Note that because the state classes always have the form isFoo, it’s easy to have a rule that state classes should never be styled by themselves – outside of a few exceptions. And you can define a convention for where to put these few exceptions. And in any case it’s not hard to search for rules that match on naked .isFoo.

Also, you probably want to have two possible prefixes for state classes, isFoo and hasFoo, both having the same rules.

---

And if that’s all true, it would apply to modifiers also. This will obviously not fly:

.categoryHeader.girls { ... }

This girls class is much too openly named. We might pick up styles from elsewhere. But this, it seems to me, would work:

.categoryHeader.forGirls { ... }

Now it can no longer cross wires with a module called girls. For modifier classes, unlike state classes, you probably want to make it an iron rule without exceptions that a naked forFoo class shall never be styled anywhere.

As with state, for modifiers you probably want to cordon off another prefix, maybe inFoo (e.g. inGreen).

---

Is there some drawback in this approach that I am overlooking?

Typo in Javascript chapter

var module1Collasper = new Collapser

Spelling error on Reuse page

If you’re going to do <div class="red"> you may as will do <div style="color: red"> which is more explicit anyway.

Should be 'well'

Typos in Reuse chapter, "Granular Styles"

If you’re going to do <div class="red"> you may as will do <div style="color: red" which is more explicit anyway.

I think that should be may as well. Also seems that <div style="color: red" is missing the closing >.

Kindle Book?

https://kdp.amazon.com/help?topicId=A37Z49E2DDQPP3&ref_=gs

State, modifer, combined classes (or whatever you call them) and aria attribute selectors

1. Add FAQ as to why the modifier and the state are prefixed. And why blah.isBlah doesn't work and why .blah.modifier doesn't work.

2. Address people's point about using aria attributes for style

• lack of browser support - users > developers etc. I prefer to know users are covered than to attempt to work out if certain browsers have no users. And did people stop coming because you dropped support or did you drop support because people couldn't use ur site etc?

• not all visual states need aria e.g. hasProducts?

Integrate the buttons example into a chapter and remove from FAQ

This is because, that question is an important one and it's a form of reuse. Bumping up a component into a module is fundamental mental approach to reuse.

https://www.w3.org/QA/Tips/goodclassnames

Be clearer about searchability yielding 1 result (that's just for css files)

Comment about instances of modules - really it will just be within the single template say for a bunch of .blah-component {} (think lists)

HTML5 tags (header, section,..) as modules without class

Hi Adam,
This is reaction to your tweet - https://twitter.com/adambsilver/status/740434324323995648.

At current project, this is, how my HTML document looks like:

<body>
  <!-- header as a module instead of "<div class="header"> -->
  <header>
    <div class="header-component">...</div>
  </header>

  <!-- main as a module instead of "<div class="main"> -->
  <main>
    <div class="main-component">...</div>
  </main >

  <!-- footer as a module instead of "<div class="footer"> --> 
  <footer>
    <div class="footer-component">...</div>
  </footer >
</body>

I don`t use those tags more than once on the page, so I think there is no need to access those elements by class, or is there?

Module template reuse note

Need to add a note about a module being encapsulated to a templates and protecting its meaning.

Chapter: What didn't work for me

A component such as .blah .something {} and a module such as .something {} and how the module affected the component.

Still semantic
Still meaningful
...but there is an unwanted collision and regression going on

Performance address perhaps

Reuse: perf: spread across global.min.css and page.specific.css?

Definition of semantic

Wondering what you are using for a definition of semantic?

Good and bad examples of class names

Try and spot the difference between non-semantic and semantic class names…

You use the word semantic a lot in your site, but your use of it seems to be inaccurate from my understanding of the definition.
Some definitions and etymology:

1655-65; < Greek sēmantikós having meaning, equivalent to sēmant (ós) marked ( sēman-, base of sēmaínein to show, mark + -tos verbal adjective suffix; akin to sêma sign) + -ikos -ic

noun, ( used with a singular verb)
1.
Linguistics.
the study of meaning.
the study of linguistic development by classifying and examining changes in meaning and form.
2.
Also called significs. the branch of semiotics dealing with the relations between signs and what they denote.
3.
the meaning, or an interpretation of the meaning, of a word, sign, sentence, etc.

Semantics (from Ancient Greek: σημαντικός sēmantikós, "significant")[1][2] is the study of meaning. It focuses on the relationship between signifiers—like words, phrases, signs, and symbols—and what they stand for, their denotation. Linguistic semantics is the study of meaning that is used for understanding human expression through language.

Can you explain how the example classes you use below fall outside of the definition and spirit of the word semantic?

<!-- bad -->
<div class="red pull-left"></div>
<div class="grid row"></div>
<div class="col-xs-4"></div>

Abstraction for common bits (using a comma)

Question: DRY vs. Module-State

Hi Adam,

thanks for this fantastic work. I have one question:

For example: There are 2 Modules used. Module-A and Module-B. Both will have the same state "isHidden" with exact the same css-code (display:none).
What would be best practice to keep css maintainable without losing the module states and without repeating the same css-code to every module-state class?

Thanks for the good read and answering my question.

Sascha

Chapter: File organisation

• Consider 32 file limit perhaps?
• Splitting modules up with comments inside CSS.

State Classes and Modifiers

First off, great job on putting all of this together. Out of all of the CSS "conventions" I've read through - yours most closely aligns to what I personally use for my projects. With that in mind, I have a few suggestions that you may (or may not) like:

State
I no longer use a module-state or module-component-state naming convention, as I've found that abstracting state into its own is-* class makes it easier to reuse:

.is-active { display: block; }
.is-inactive { display: none; }

... and if you need to override its behavior for a particular element, you can nest/chain the selector:

.foo {
    &.is-active { opacity: 1; }
}

Otherwise you'll end writing dozens of classes that potentially behave the same:

.foo-isActive { display: block; }
.foo-isInactive { display: none; }

.bar-isActive { display: block; }
.bar-isInactive { display: none; }

.baz-isActive { display: block; }
.baz-isInactive { display: none; }

In addition, this helps immensely with my JavaScript. While we should all strive to separate our concerns as much as possible - inevitably there are times when it makes sense to share classes between CSS and JavaScript (particularly when it comes to state). In this case the is-* classes mentioned above can be set by JavaScript, to communicate a module's state to the CSS.

Modifiers
Personally I prefer double dashes as delimiters. IMO this makes your class names even more semantic. For example, at first glance it's hard to tell if this is a component or a modifier class:

.related-sidebar { ... }

... whereas by using double dashes, it's immediately clear that you are looking at a modifier class:

.related--sidebar { ... }

Chapter: Reuse and slight differences

When something is the same but has the slightest difference then obviously don't duplicate.

things like -type1 or -someCategory or -colourX

Splitting modules up with comments inside CSS.

Minor typographical errors

I enjoyed your site and look forward to applying the principles you discuss on future projects

On the Organisation page, the first sentence has "nad" where "and" is appropriate.

On the FAQs page, the answer to the first question has "your" where "you're" is appropriate.

Thank you for your hard work!

Misc bits

• Wording section, details, primary, wrapper, container, item, items

Why is html bloat worse than css bloat?

You make the claim that reusing atomic styles will lead to "html bloat"
Do you have any data that it is harder to maintain and degrades performance?
It seems that the payload of css is a larger hit to performance from my user testing. HTML bloat has seemed to be minimal, general less than 1kb of difference in an html file. While css bloat can lead to file sizes that even after minification and gzipping are more than 100kb larger than necessary due to the duplication in css.

Consider this excerpt from Nicolas Gallaghers post

A note on raw file size and HTTP compression

Related to any discussion about modular/scalable CSS is a concern about file size and “bloat”. Nicole Sullivan’s talks often mention the file size savings (as well as maintenance improvements) that companies like Facebook experienced when adopting this kind of approach. Further to that, I thought I’d share my anecdotes about the effects of HTTP compression on pre-processor output and the extensive use of HTML classes.

When Twitter Bootstrap first came out, I rewrote the compiled CSS to better reflect how I would author it by hand and to compare the file sizes. After minifying both files, the hand-crafted CSS was about 10% smaller than the pre-processor output. But when both files were also gzipped, the pre-processor output was about 5% smaller than the hand-crafted CSS.

This highlights how important it is to compare the size of files after HTTP compression, because minified file sizes do not tell the whole story. It suggests that experienced CSS developers using pre-processors don’t need to be overly concerned about a certain degree of repetition in the compiled CSS because it can lend itself well to smaller file sizes after HTTP compression. The benefits of more maintainable “CSS” code via pre-processors should trump concerns about the aesthetics or size of the raw and minified output CSS.

In another experiment, I removed every class attribute from a 60KB HTML file pulled from a live site (already made up of many reusable components). Doing this reduced the file size to 25KB. When the original and stripped files were gzipped, their sizes were 7.6KB and 6KB respectively – a difference of 1.6KB. The actual file size consequences of liberal class use are rarely going to be worth stressing over.

Do you have any performance data about file size to counter these stats?

Theme based styles

Hello,

Please could you help with the following?

Scenario:
Imagine your website gives the user the power to change the skin colour e.g. text could be black in one and grey in the other.

How would you handle this without reusing the style?

Lets say you had a CSS and HTML like this:

.header-siteName { 
    colour: #000; 
}

<div class="header">
    <div class="header-siteName">Site Name</div>
</div>

You could use a modifier on each element and remove the above style completely.

.header-siteName-blackTxt {
    color: #000;
}

<div class="header">
    <div class="header-siteName header-siteName-blackTxt">Site Name</div>
</div>

.header-siteName-greyTxt {
    color: #AAA;
}

<div class="header">
    <div class="header-siteName header-siteName-greyTxt">Site Name</div>
</div>

This is a good approach but is quite heavy on HTML bloat if you add a modifier to lots of elements.

Another idea is to use a modifier on the parent.

.header-blackTxt {
    color: #000;
}

<div class="header header-blackTxt">
    <div class="header-siteName">Site Name</div>
</div>

This is fine until you start changing background colour. You would need to update the style directly or add a class onto that element.

.header-blackBg  .header-siteName {
    background-color: #000;
}

<div class="header header-blackBg">
    <div class="header-siteName">Site Name</div>
</div>

.header-blackBg {
    background-color: #000;
}

<div class="header">
    <div class="header-siteName header-blackBg">Site Name</div>
</div>

The latter can cause bloat (if over-used) and the first goes against the one selector rule (ignoring HTML selectors like .element h2)

How is this best handled?

Should a theme style-sheet be created and loaded based on the skin chosen?

You could remove all styles related to the skin and add them to these themes. You would not be re-using them that way.

Another approach is overriding the CSS but this breaks the MaintainableCSS rule and everything becomes unclean.

For example:

**grey-theme.css**

.header-blackBg {
    background-color: #AAA;
}

**black-theme.css**

.header-blackBg {
    background-color: #000;
}

This kind of issue could occur if you have two separate sites with the same layout. Everything would be the same but there might be small differences e.g. colour. I have seen multiple sites that do this but its hard to figure out the right way of approaching it.

Thanks for reading :).

Cheers

Patrick

Is it JavaScript or Javascript?

http://maintainablecss.com/chapters/javascript/

I know this isn't programming-related, but I'm curious what you thinks about this subject. The official name is JavaScript instead of Javascript, though it really doesn't matter in practice. You can view the documentation here.

Thanks for attention! BTW beautiful work, congratulations @adamsilver.

Difference to BEM CSS?

I'm evaluating different methodologies at the moment. As far as I can see, MaintainableCSS shares the basic principles of BEM. Are there any major key differences?

Information about readability

http://uxpamagazine.org/people_who_do_not_read_easily/

Reference this article or stuff from this article about how we read.

Inclusivity from a dev perspective too. i.e. easy to read code. easy to read variable names. etc.

Address reddit comment

https://www.reddit.com/r/webdev/comments/4farx2/maintainablecss_an_approach_to_writing_modular/d27izoy

Yeh, so buttons are an interesting one and is something that I will address in MaintainableCSS - there is a lot more to come.
You could consider "primaryButton" a module (that is made up of just one component).
The problem is that sometimes these buttons have different spacing, floating, and display rules depending on the context. So you have to be really careful with what goes inside the curly braces for this one.
You're also right that I haven't addressed an almost identical modules/components that have say 1 very tiny difference such as a different background colours.
I would do this with an extra class much like state. So if the team decides to make primaryButton a module then:
.primaryButton-blue {}
.primaryButton-green {}
You could also decide not to using style names:
.primaryButton-type1 {}
.primaryButton-type2 {}
But not sure if this is valuable - it just depends on your situation.
If this approach becomes painful then I would choose a slightly different approach whereby a bunch of different modules/components subscribe to the same rules (as I mention in reuse).
/* common primary button */
.basket-removeButton,
.someOtherButton {
...
}
HTH

SUIT CSS

Do you know SUIT CSS?

https://suitcss.github.io

Where to put media queries - separate file - no - in situ - yes.

Rec

https://twitter.com/webjac/status/726113913042030592?s=09

Possible mistype on Reuse chapter

On the reuse chapter, near the top, there is this line

"If you don’t repeat yourself, then you break semantics. Go read that chapter."

Should this be?

"If you repeat yourself, then you break semantics. Go read that chapter."

If that is the case, I can submit a pull request.

Different types

things like -type1 or -someCategory or -colourX

Fork and translate into Traditional Chinese

Hi,
MaintainableCSS is really handy for beginners.
May I fork your work and translate into Traditional Chinese?

Thank you!

Button as a module

Discuss what didn't work for me

.moduleName {}
.moduleName .componentName {}

This is super clean and reusable, however, there is nothing to stop a different moduleName matching a different componentName, and when that happens you will inherit styles you didn't wish to happen. So you end up changing the name or overriding. Both not useful. Quite rare, but not helpful.

Second slightly lesser reason is, when you're inspecting .componentName you cannot tell there and then if you're dealing with a component OR a module. Would be nice to know without referring to CSS. HTML is modular too etc.

Response to MaintainableCSS

"Avoid growth" - no, it's about the way developers handle the growth - more features will always equal larger codebases. Microservices in lot's of repsects are designed for maintainability. But they are bigger in many ways, but just lots of discrete moving parts etc.

"Semantic html is wrong" - whilst you can be pedantic with the word, it's about having meaningful html inside HTML. That is class names reside in HTML, so make it meaningful to HTML - not to mention all the othe benefits of doing so i.e. content semantics.

Semantics doesn't just pertain to what a browser can understand, it's what a human understands.

I can understand why you would suggest "meaningful" over "semantic" - but then it's soooo similar.

"Don't add classes for styles, add styles for classes" - yes and use

"The worst possible way to structure your CSS is to make classes for each and every style you want to apply." - yep

"How do you fix x, etc" - yes and have included in the guides.

"Be careful when reusing styles. Be careful using a power drill. If you're careless you can get hurt. If you're careful you can save a lot of effort." - totally, reuse but be careful, and I have added to guides.

"composition over inheritance" - yes, but even then it's dangerous as per the guides.

"stats ouch" - have built a million very large scale websites, css been a problem once, and it was down to the stuff inbetween the braces.

"ids" - i actually used to disagree too, but now we both agree.

"Bem" - yes agree, it's similar, and it's ugly. And agree with rest of section.

"Doesn't matter what u call modules, atoms etc" It doesn't in terms of technically, but does in terms of devs ability to understand and reason about.

"Basket reuse" - potentially right, but in my case, wrong, but then again you haven't seen the design.

"State" - yes, will be addressing - several ways to go, none "perfect"

"Versioning" - can use a modifier if it is a tiny bit different- need to cover with types/colours/categories

Why semantic point: Because red only means something to css, not to HTML. Semantic CSS means something to both.

Page and module

.deliveryAndReturns {}

.product .deliveryAndReturns {}

kidly

What about using 3rd party css tools like Bootstrap or animate.css?

These tools use class names to define their appearance. Like <h1 class="animated infinite bounce">Example</h1>

Is there anyway these tools can be compatible with MaintainableCSS philosophy?

Question on human understanding

Do you have any data or academic research that can support this statement?

This is because humans are good at understanding human communication and bad at understanding abbreviated, non-semantic abstractions.

Seems like unix systems have done quite well with abbreviations e.g the command for copy is cp, the command for move is mv.

DRY

http://cssguidelin.es/#dry
http://cssguidelin.es/#composition-over-inheritance

Why not use semantic elements in examples?

Here you use these code example as "good" but they don't inform a computer or screenreader how to classify the content. Screenreader's do not parse class names for meaning. Can you elaborate how this markup in the example is more semantic?

<!-- good -->
<div class="header"></div>
<div class="basket"></div>
<div class="product"></div>
<div class="searchResults"></div>

Translate to Brazilian Portuguese

Hi, thanks for sharing this material.
I can translate it to pt-BR?

Thanks.

How to write modules inside sass partials?

Hi Adam.
Just read maintainablecss.com. Great stuff!

In modules chapter you presented an example of buttons -

.basket-removeButton,
.another-loginButton,
.another-deleteButton {
  background-color: green;
  padding: 10px;
  color: #fff;
}

Now let's say I have multiple partials for auth, basket and orderSummary. Where should I put this css? Should I put this in the global module and then extend it to respective partials for other properties such as float, margin or width etc.? Because if I put this code in all the partials (depending on respective classes) it would mean code repetition. What's the better way according to you? Please help.

Inheritance/basic styling of elements

As I read through the content I became curious of what your thoughts are on inheritance. I was mainly thinking of elements like h1, p, ul and li etc.

What do you think about covering this specifically in a future chapter?

For example, would you make a class called .h1 and make your styles there, or would you rather have it defined to the h1 element and let your modules/component inherit from that?

It could even be taken so far and you opt for styling body.myBody instead of body directly for setting your font-family and background etc.

What I am aiming at is, what is the best approach to have the general styles of you CSS maintainable?

Not sure if it makes sense or if you think it would make an interesting read, maybe it is more FAQ related. Nevertheless I'm interested to hear your thoughts.

GlobalCSS

IE fixes and common hacks