How to extend the web toolkit

file.md

• use classes for everything, seriously everything

  • some html elements will have a ton of classes and that’s okay—-the fewer things a single CSS class does the easier it is to understand
  • in the vast majority of cases you shouldn't write your CSS rules using html tags (like a or li), add a class instead so your rules aren't as tightly coupled to markup (what if you need to swap out that a for a span later? hopefully you shouldn't have to change your CSS)

• keep the specificity of your CSS rules as low as possible: a single class is the ideal

  • Sass makes it really easy to nest rules, but resist the urge; think about namespacing your classes instead
    It is easy and tempting to match your rule nesting to your DOM nesting:

    .listing-card {
      .listing-card-title {}
    }
    

  But avoiding nesting works better for CSS maintainability. All of your rules will maintain the same specificity and you're not making any assumptions about the structure of your markup.

  .listing-card {}
  .listing-card-title {}
  

  • use CSS ordering to apply your overrides [I think? is this terrible? it caused most of the unscoped->scoped toolkit bugs but that seems like a one-off thing …]

• create new classes instead of overriding existing ones; make variation classes

  • a variation class is where you may want your selector to be more specific than the base UI toolkit class, e.g. .listing-card.listing-card--compact would be a reasonable selector

• make your own utility classes instead of adding one-off rules/overrides in other classes

  • particularly, you will likely be happier and your css will be easier to use and maintain later if you use utility classes for things like tweaking spacing, element colors, font sizes--things you may want to do a lot of places and that may not necessarily apply to everywhere you might use the component you're adjusting

  • utility classes are basically the only place where it is a good idea to use !important--if you're using a utility class (like .b-b-0 -- "border bottom zero" / remove the bottom border) you want it to override everything else (and won't have to try to override it elsewhere, you can delete it from your markup if you change your mind)

• don't mix toolkit and 3rd party styles in markup