{"id":16831528,"url":"https://github.com/nonoesp/folio-scss","last_synced_at":"2025-03-18T02:19:30.666Z","repository":{"id":69995966,"uuid":"72948080","full_name":"nonoesp/folio-scss","owner":"nonoesp","description":"🎨 Reusable SCSS components for Laravel Folio.","archived":false,"fork":false,"pushed_at":"2023-05-09T08:04:52.000Z","size":263,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-24T09:41:35.131Z","etag":null,"topics":["dom","namespace","sass","scss","stylesheets","web"],"latest_commit_sha":null,"homepage":"https://nono.ma","language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nonoesp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-05T19:18:23.000Z","updated_at":"2022-06-09T00:35:26.000Z","dependencies_parsed_at":"2024-11-24T08:03:20.720Z","dependency_job_id":null,"html_url":"https://github.com/nonoesp/folio-scss","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nonoesp%2Ffolio-scss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nonoesp%2Ffolio-scss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nonoesp%2Ffolio-scss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nonoesp%2Ffolio-scss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nonoesp","download_url":"https://codeload.github.com/nonoesp/folio-scss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244141479,"owners_count":20404837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dom","namespace","sass","scss","stylesheets","web"],"created_at":"2024-10-13T11:44:15.401Z","updated_at":"2025-03-18T02:19:30.640Z","avatar_url":"https://github.com/nonoesp.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Folio SCSS 🎨\n\nThis repository contains a set of sass stylesheets with elements and tools that intend to be reusable. The file structure is inspired by [inuitcss](https://github.com/inuitcss/inuitcss), and the following guidelines are a reminder from [Harry Roberts](docs/csswizardry-namespaces.md) of the naming convention which this project intends to stick to.\n\nThe Namespaces\n--------------\n\nIn no particular order, here are the individual namespaces and a brief\ndescription. We’ll look at each in more detail in a moment, but the\nfollowing list should acquaint you with the kinds of thing we’re hoping\nto achieve.\n\n-   `o-`{.highlighter-rouge}: Signify that something is an Object, and\n    that it may be used in any number of unrelated contexts to the one\n    you can currently see it in. Making modifications to these types of\n    class could potentially have knock-on effects in a lot of other\n    unrelated places. Tread carefully.\n-   `c-`{.highlighter-rouge}: Signify that something is a Component.\n    This is a concrete, implementation-specific piece of UI. All of the\n    changes you make to its styles should be detectable in the context\n    you’re currently looking at. Modifying these styles should be safe\n    and have no side effects.\n-   `u-`{.highlighter-rouge}: Signify that this class is a Utility\n    class. It has a very specific role (often providing only one\n    declaration) and should not be bound onto or changed. It can be\n    reused and is not tied to any specific piece of UI. You will\n    probably recognise this namespace from libraries and methodologies\n    like [SUIT](https://suitcss.github.io/).\n-   `t-`{.highlighter-rouge}: Signify that a class is responsible for\n    adding a Theme to a view. It lets us know that UI Components’\n    current cosmetic appearance may be due to the presence of a theme.\n-   `s-`{.highlighter-rouge}: Signify that a class creates a new styling\n    context or *Scope*. Similar to a Theme, but not necessarily\n    cosmetic, these should be used sparingly—they can be open to abuse\n    and lead to poor CSS if not used wisely.\n-   `is-`{.highlighter-rouge}, `has-`{.highlighter-rouge}: Signify that\n    the piece of UI in question is currently styled a certain way\n    because of a state or condition. This stateful namespace is\n    gorgeous, and comes from [SMACSS](https://smacss.com/). It tells us\n    that the DOM currently has a temporary, optional, or short-lived\n    style applied to it due to a certain state being invoked.\n-   `_`{.highlighter-rouge}: Signify that this class is the worst of the\n    worst—a hack! Sometimes, although incredibly rarely, we need to add\n    a class in our markup in order to force something to work. If we do\n    this, we need to let others know that this class is less than ideal,\n    and hopefully temporary (i.e. “do not bind onto this”).\n-   `js-`{.highlighter-rouge}: Signify that this piece of the DOM has\n    some behaviour acting upon it, and that JavaScript binds onto it to\n    provide that behaviour. If you’re not a developer working with\n    JavaScript, leave these well alone.\n-   `qa-`{.highlighter-rouge}: Signify that a QA or Test Engineering\n    team is running an automated UI test which needs to find or bind\n    onto these parts of the DOM. Like the JavaScript namespace, this\n    basically just reserves hooks in the DOM for non-CSS purposes.\n\nEven from this short list alone, we can see just how much more\ninformation we can communicate to developers simply by placing a\ncharacter or two at the front of our existing classes.\n\nIt is probably worth noting at this point that these namespaces do not\nexist for encapsulation and sandboxing of styles, but for clarity and\ninformative reasons. [Ben Frain](https://twitter.com/benfrain)’s\n[FUN](http://benfrain.com/fun-css-naming-convention-explained/)\nconvention utilises namespacing as a means of soft encapsulation.\n\nObject Namespaces: `o-`{.highlighter-rouge}\n-------------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.o-object-name[\u003celement\u003e|\u003cmodifier\u003e] {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.o-layout {}\n\n  .o-layout__item {}\n\n.o-layout--fixed {}\n```\n\n\u003c/div\u003e\n\nThe `o-`{.highlighter-rouge} namespace for Objects is a very useful one\nfor any teams who use Object-Oriented CSS.\n\nOOCSS is fantastic in that it teaches us to abstract out the repetitive,\nshared, and purely structural aspects of a UI into reusable *objects*.\nThis means that things like layout, wrappers and containers, the [Media\nObject](http://www.stubbornella.org/content/2010/06/25/the-media-object-saves-hundreds-of-lines-of-code/),\netc. can all exist as non-cosmetic styles that handle the skeletal\naspect of a lot of UI components, without ever actually looking like\ndesigned ‘things’.\n\nThis leads to much DRYer and drastically smaller stylesheets, but does\nbring with it one problem: how do we know which classes might be purely\nstructural, and therefore possibly being used in an open-ended number of\ninstances?\n\nThis poses problems on projects quite frequently. Picture the following\nexample.\n\nImagine you’re a developer new to a project, and you have no intimate\nknowledge of the CSS or what its classes mean or do. You’re asked by a\nProduct Owner to add some padding around the testimonials that appear on\nthe site. You right click, Inspect Element, and you see this:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cblockquote class=\"media  testimonial\"\u003e\n\u003c/blockquote\u003e\n```\n\n\u003c/div\u003e\n\nNow, it should be fairly clear here that what you should do is go and\nfind the `.testimonial {}`{.highlighter-rouge} ruleset in your CSS and\nadd the padding there. However, using DevTools, you find that adding the\npadding to the `.media {}`{.highlighter-rouge} ruleset has exactly the\noutcome you expected. Perfect! Let’s go and add that into the source CSS\nfile.\n\nThe issue here is that `.media`{.highlighter-rouge} is an abstraction\n(it’s actually the poster child of Nicole Sullivan’s OOCSS) which, by\ndefinition, is a reusable and non-cosmetic design pattern that can\nunderpin any number of different UI components. Sure, altering the\npadding of it in this instance gave us the desired results, but it also\nmay have just unintentionally broken 20 other pieces of UI elsewhere.\n\nBecause objects don’t belong to any one specific component, and can\nunderpin several vastly different components, it is incredibly risky to\never modify one. This is why we should introduce a namespace, to let\nother developers know that this class forms an abstraction and that any\nchanges here will be reflected in every object sitewide. The object\nitself does not necessarily have anything to do with the\nimplementation-specific bit of the UI that you are trying to change.\n\nBy adding a leading `o-`{.highlighter-rouge} to the classes for our\nobjects, we can tell other developers about their universal nature, and\nhopefully avoid ever having people binding onto them and breaking\nthings. If you ever see a class that begins with\n`o-`{.highlighter-rouge}, alarm bells should ring and you should know to\nstay well away from it.\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cblockquote class=\"o-media  testimonial\"\u003e\n\u003c/blockquote\u003e\n```\n\n\u003c/div\u003e\n\n-   Objects are abstract.\n-   They can be used in any number of places across the project—places\n    you might not have even seen.\n-   Avoid modifying their styles.\n-   Be careful around anything with a leading `o-`{.highlighter-rouge}.\n\nComponent Namespaces: `c-`{.highlighter-rouge}\n----------------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.c-component-name[\u003celement\u003e|\u003cmodifier\u003e] {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.c-modal {}\n\n  .c-modal__title {}\n\n.c-modal--gallery {}\n```\n\n\u003c/div\u003e\n\nComponents are some of the safest types of selectors we will encounter.\nComponents are finite, discrete, implementation-specific parts of our UI\nthat most people (users, designers, developers, the business) would be\nable to identify: “This is a button”; “This is the date picker”; etc.\n\nUsually when we make changes to a Component’s ruleset, we will\nimmediately see those changes happening every- (and only) where we’d\nexpect. Unlike with Objects, changing the padding on the\n`.c-modal__content`{.highlighter-rouge} should not affect anything else\nin the site other than the content area of our modal. Where Objects are\nimplementation-agnostic, Components are implementation-specific.\n\nIf we revisit the previous example, and introduce the Object and\nComponents’ namespaces, we’d be left with this:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cblockquote class=\"o-media  c-testimonial\"\u003e\n\u003c/blockquote\u003e\n```\n\n\u003c/div\u003e\n\nNow I can tell *purely* from this HTML that any changes I make to the\n`.o-media`{.highlighter-rouge} class may be felt throughout the entire\nsite, but any changes I make to the `.c-testimonial`{.highlighter-rouge}\nruleset will only modify testimonials, and nothing else.\n\n-   Components are implementation-specific bits of UI.\n-   They are quite safe to modify.\n-   Anything with a leading `c-`{.highlighter-rouge} is a specific\n    *thing*.\n\nUtility Namespaces: `u-`{.highlighter-rouge}\n--------------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.u-utility-name {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.u-clearfix {}\n```\n\n\u003c/div\u003e\n\nYou will most likely be familiar with the Utility notation because of\n[SUIT](https://github.com/suitcss/utils). Utilities are complete [single\nresponsibility](http://csswizardry.com/2012/04/the-single-responsibility-principle-applied-to-css/)\nrules which have a very specific and targeted task. It is also quite\ncommon for these rules’ declarations to carry\n`!important`{.highlighter-rouge} so as to guarantee they beat other less\nspecific ones. They do one thing in a very heavy-handed and inelegant\nway. They are to be used as a last resort when no other CSS hooks are\navailable, or to tackle completely unique circumstances, e.g. using\n`.u-text-center`{.highlighter-rouge} to centrally align one piece of\ntext once and once only. They are only one step away from inline styles,\nso should be used sparingly.\n\nBecause of their heavy-handed approach, their global reusability, and\ntheir exceptional use-case, it is incredibly important that we signal\nUtilities to other developers. We do not want anyone trying to bind onto\nthese in future selectors. Take the following example, which actually\nhappened on a project I worked on. A number of months into a project, a\ndeveloper wrote this bit of CSS:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.footer .text-center {\n  font-size: 75%;\n}\n```\n\n\u003c/div\u003e\n\nHere we can see a problem: the `.text-center`{.highlighter-rouge} class\nnow has two responsibilities when it appears anywhere inside\n`.footer`{.highlighter-rouge}. It now has side effects, which are\nsomething that Utilities should never, ever have.\n\nBy using a namespace, we can introduce a simple and unbreakable rule: if\nit begins with `u-`{.highlighter-rouge}, never reassign to it.\n\nUtilities should be defined once, and never need changing.\n\nAnother problem that the Utility namespace solves is that it actually\nlets people know that there is a heavyweight rule being applied to the\nsection of the DOM. It will help explain why certain things might be\nhappening and hard to override. Take this example:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cdiv class=\"font-size-large\"\u003e\n  ...\n\n  \u003cblockquote class=\"pullquote\"\u003e\n  \u003c/blockquote\u003e\n\n  ...\n\u003c/div\u003e\n```\n\n\u003c/div\u003e\n\nA developer inheriting this might be confused as to why the\n`blockquote`{.highlighter-rouge}’s font size is different to what they\nexpected. This is because it’s inheriting the font size from a\n`.font-size-large`{.highlighter-rouge} class used a little further up\nthe DOM tree. By adding a little more clarity to our classes, we can\nmore quickly identify any potential offenders: “Ah, here’s a Utility,\nthat must be what’s causing it.” (This is actually a fairly good example\nof why we should use Utilities sparingly.)\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cdiv class=\"u-font-size-large\"\u003e\n  ...\n\n  \u003cblockquote class=\"c-pullquote\"\u003e\n  \u003c/blockquote\u003e\n\n  ...\n\u003c/div\u003e\n```\n\n\u003c/div\u003e\n\nPlease see this post’s sister article [Immutable\nCSS](http://csswizardry.com/2015/03/immutable-css/) for more detail on\nthese kinds of rule.\n\n-   Utilities are style heavyweights.\n-   Alert people as to their existence.\n-   Never reassign to anything that carries a leading\n    `u-`{.highlighter-rouge}.\n\nTheme Namespaces: `t-`{.highlighter-rouge}\n------------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.t-theme-name {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.t-light {}\n```\n\n\u003c/div\u003e\n\nWhen we work with [Stateful\nThemes](https://speakerdeck.com/csswizardry/4half-methods-for-theming-in-s-css?slide=29)\n(that is to say, themes that we toggle on and off) we normally do so by\nadding a class to the `body`{.highlighter-rouge} element. Examples of\nthis approach to theming include style-switchers (a user can toggle\nbetween different themes) and sub-sections of a site (all blog posts\nhave one theme colour, all news pages have another theme colour, etc.).\nWe simply add a class high up the DOM which then invokes that theme for\nthat particular page.\n\nA simple way to denote any theme-related classes is to simply prepend\nthem with `t-`{.highlighter-rouge}. Seeing a `t-`{.highlighter-rouge}\nclass in your HTML should tell you that “Ah, right, the view probably\nlooks the way it currently does because we have a theme invoked.”\n\nNow, all of the namespaces we’ve looked at so far are mainly of use to\nus in our markup, but Theme namespaces are helpful in both our HTML and\nour CSS. Seeing, for example, `.t-light`{.highlighter-rouge} in our\nmarkup tells us that the entire DOM has a current state applied to it,\nwhich is important to know whilst debugging. Seeing that class in our\nCSS also tells us a lot: it helps to sandbox and isolate any chunks of\ntheme-related CSS inside namespaced rulesets:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.c-btn {\n  display: inline-block;\n  padding: 1em;\n  background-color: #333;\n  color: #e4e4e4;\n\n  .t-light \u0026 {\n    background-color: #e4e4e4;\n    color: #333;\n  }\n\n}\n```\n\n\u003c/div\u003e\n\nHere we can see that our buttons have a light grey text colour on top of\na dark grey background, but when we invoke the\n`.t-light`{.highlighter-rouge} theme, those colours invert. Here we are\nencapsulating the style information, which means that finding,\ndebugging, and modifying Theme rules becomes much simpler.\n\n-   Theme namespaces are very high-level.\n-   They provide a context or scope for many other rules.\n-   It’s useful to signal the current condition of the UI.\n\nScope Namespaces: `s-`{.highlighter-rouge}\n------------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.s-scope-name {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.s-cms-content {}\n```\n\n\u003c/div\u003e\n\nScoped contexts in CSS solve a very specific and particular problem:\nplease be entirely certain that you actually have this problem before\nemploying Scopes, because they can be misused and end up leading to\nactively bad CSS.\n\nOftentimes it can be useful to set up a brand new styling context for a\nparticular section of your UI. A perfect example of this is areas of\nuser-generated content, where some long-form/prose HTML has come from a\nCMS. The styling of this kind of content usually differs from the more\napp-like UI around it. You may have a class-heavy UI architecture to\nprovide complex pieces of design like navigations, buttons, modals,\netc., and inside all of this you may have a simple blog post which is\npopulated via a CMS where the user writes plain text and cannot add any\nclasses or complexity.\n\nFor a really terse but effective example of Scoping styles, see [David\nBushell](https://twitter.com/dbushell)’s [Scoping Typography\nCSS](http://dbushell.com/2012/04/18/scoping-typography-css/).\n\nYou **might** want to style this free-form text differently from the\nrest of the surrounding UI, so you *might* employ a scoping context. For\nexample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cnav class=\"c-nav-primary\"\u003e\n  ...\n\u003c/nav\u003e\n\n\u003csection class=\"s-cms-content\"\u003e\n\n  \u003ch1\u003e...\u003c/h1\u003e\n\n  \u003cp\u003e...\u003c/p\u003e\n\n  \u003cp\u003e...\u003c/p\u003e\n\n  \u003cul\u003e\n    ...\n  \u003c/ul\u003e\n\n  \u003cp\u003e...\u003c/p\u003e\n\n\u003c/section\u003e\n\n\u003cul class=\"c-share-links\"\u003e\n  ...\n\u003c/ul\u003e\n\n\u003ca href=\"\" class=\"c-btn  c-btn--primary\"\u003eNext article...\u003c/a\u003e\n```\n\n\u003c/div\u003e\n\nEverything inside the `.s-cms-content`{.highlighter-rouge} is\ninaccessible: we can’t get at the DOM to add any classes to the nodes\ninside of it, so we *might* begin styling via a Scope. That *might* look\nsomething like this:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n/**\n * Create a new styling context for any free-text CMS content (blog posts,\n * news pages, etc.).\n *\n * 1. Use a larger and more readable typeface for continuous prose.\n * 2. Force all headings to have the same appearance, regardless of their\n *    hierarchy.\n * 3. Make links inside long text more apparent.\n */\n.s-cms-content {\n  font: 16px/1.5 serif; /* [1] */\n\n  h1, h2, h3, h4, h5, h6 {\n    font: bold 100%/1.5 sans-serif; /* [2] */\n  }\n\n  a {\n    text-decoration: underline; /* [3] */\n  }\n\n}\n```\n\n\u003c/div\u003e\n\nI cannot stress the word *might* enough here. [Nesting selectors is\nbad](http://cssguidelin.es/#nesting): it leads to location-based\nstyling, meaning that styles are now tightly coupled to DOM structure;\nit prevents people from being able to opt into styles, because nested\nselectors are very dictatorial (i.e. “this **will** happen if you put\nthat in there”); having a type selector as a Key Selector creates very\ngreedy selectors, which can match more of the DOM than you intend; and\nour specificity gets increased, meaning our Scope will override\npreviously defined styles, and in turn the Scope itself becomes harder\nto override.\n\nThere’s a really good example we can grab from the Sass above. When\ncompiled, that code will give us this selector:\n`.s-cms-content a {}`{.highlighter-rouge}. This selector is in charge of\nadding underlines to links, and is also of a higher specificity than a\nselector like `.c-btn {}`{.highlighter-rouge}. This means that if we\nwere to put a button inside of this Scope, it would get an\nunderline—this is something we probably don’t want. This simple example\noutlines the potential for problems when working with Scopes, so tread\ncarefully.\n\nPlease make triple sure that that you need to employ a Scope before you\nstart writing lots of nested selectors. If you are unsure, it may be\nbest to err on the side of caution and leave Scopes out entirely.\n\nWarnings aside, the actual `s-`{.highlighter-rouge} namespace becomes\nincredibly useful for signalling to developers that an entire area of\nthe DOM is subject to one big caveat. Anything we see styled in here\nmight have an extra layer of styling applied to it in a pretty\nopinionated and greedy manner.\n\n-   Scopes are pretty rare: make triple sure you need them.\n-   They rely entirely on nesting, so make sure people are aware of\n    this.\n\nStateful Namespaces: `is-`{.highlighter-rouge}/`has-`{.highlighter-rouge}\n-------------------------------------------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.[is|has]-state {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.is-open {}\n\n.has-dropdown {}\n```\n\n\u003c/div\u003e\n\nStateful namespaces are lovely. They come from\n[SMACSS](https://smacss.com/book/type-state), and they tell us about\nshort-lived or temporary states of the UI that need styling accordingly.\n\nWhen looking at a piece of interactive UI (e.g. a modal overlay) through\ndeveloper tools, we’ll probably spend some time toggling things on and\noff. Being able to see classes like `.is-open`{.highlighter-rouge}\nappear and disappear in the DOM is a highly readable and very obvious\nway of learning about state:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cdiv class=\"c-modal  is-open\"\u003e\n  ...\n\u003c/div\u003e\n```\n\n\u003c/div\u003e\n\nIt’s also incredibly handy in our CSS to tell people possible states\nthat a piece of UI can exist in, for example:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.c-modal {\n  ...\n\n  \u0026.is-open { ... }\n\n}\n\n\n  .c-modal__content {\n    ...\n\n    \u0026.is-loading { ... }\n\n  }\n```\n\n\u003c/div\u003e\n\nThese classes work by chaining other classes, for example\n`.c-modal.is-open`{.highlighter-rouge}. This heightened specificity\nensures that the State always takes prominence over the default styling.\nIt also means that we would never see a bare Stateful class on its own\nin a stylesheet: it must always be chained to something.\n\nThe way in which States are different to BEM’s Modifiers is that States\nare temporary. States (can) change from one moment to the next, perhaps\nbased on user action (e.g. `.is-expanded`{.highlighter-rouge}) or from\nchanges that are being pushed from a server (e.g.\n`.is-updating`{.highlighter-rouge}).\n\n-   States are very temporary.\n-   Ensure that States are easily noticed and understood in our HTML.\n-   Never write a bare State class.\n\nHack Namespaces: `_`{.highlighter-rouge} {#hack-namespaces-}\n----------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n._\u003cnamespace\u003ehack-name {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n._c-footer-mobile {}\n```\n\n\u003c/div\u003e\n\nIn certain and usually quite rare circumstances, we might need to add a\nclass to our markup purely in order to help us hack or override\nsomething. If we ever do that, we need to signal that this class is\nhacky, it’s (hopefully) quite temporary, we want to get rid of it at\nsome point, therefore do not bind onto, reuse or otherwise interface\nwith it.\n\nThe reason for the leading underscore is simply to mirror the paradigm\nof private variables in programming languages. Variables that are\nprivate to the program should not be relied upon or reused by other\ndevelopers, and that’s the same with our Hack classes.\n\nThese types of class are pretty easy to spot in our codebase, so any\nhacks will become very apparent, which is a [good\nthing](http://csswizardry.com/2013/04/shame-css/).\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n@media screen and (max-width: 30em) {\n\n  /**\n   * We need to force the footer to be a fixed height on smaller screens.\n   */\n  ._c-footer-mobile {\n    height: 80px;\n  }\n\n}\n```\n\n\u003c/div\u003e\n\n-   Hacks are ugly—give them ugly classes.\n-   Hacks should be temporary, do not reuse or bind onto their classes.\n-   Keep an eye on the number of Hacks classes in your codebase.\n\nJavaScript Namespaces: `js-`{.highlighter-rouge}\n------------------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.js-component-name {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.js-modal {}\n```\n\n\u003c/div\u003e\n\nJavaScript namespaces are pretty common now, and most people tend to use\nthem. The idea is that—in order to properly separate our concerns—we\nshould never have styling and behaviour bound to the same hooks. To bind\nboth technologies onto the same hook means we can’t have one without the\nother: our UI becomes all-or-nothing, which makes it very opinionated\nand inflexible.\n\nWhen I worked at [Sky](http://csswizardry.com/case-studies/bskyb/), we\nhad an incident where a developer had built a text-callout UI component\nthat had a distinct appearance, and some behaviour to fade text in and\nout of it. A Product Owner asked that we reuse the same piece of UI\nelsewhere, but we didn’t need to fade multiple pieces of text in and\nout; it was just going to say the same thing all the time. Because the\ncomponent had been built with JS and CSS binding onto the same hook, it\nmeant that I couldn’t have a configuration of the component with its\nlook and feel but without its behaviour. It took a chunk of refactoring\nto fix, and it could have been avoided simply by binding onto separate\nhooks.\n\nIt also means that we can work a lot more safely. It means that CSS\ndevelopers can work and refactor freely without the worry that they will\nbreak some JS, and vice versa. It separates our concerns and leaves each\nteam with its own hooks for its own purposes.\n\nIt’s probably also worth noting that because the JS namespace has\nnothing at all to do with CSS, its format should be determined by your\nJS engineers. If your JS team’s naming convention for variables etc. is\ncamel case, then they should be allowed to choose JS hooks like\n`.jsModal`{.highlighter-rouge} if they so desire.\n\n-   JavaScript and CSS are separate concerns—use separate hooks for\n    them.\n-   Giving different teams/roles different hooks makes for safer\n    collaboration.\n\nQA Namespaces: `qa-`{.highlighter-rouge}\n----------------------------------------\n\nFormat:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.qa-node-name {}\n```\n\n\u003c/div\u003e\n\nExample:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n.qa-error-login {}\n```\n\n\u003c/div\u003e\n\nAn unusual, but potentially very useful namespace is this one, for your\nQA team. When running automated UI tests with something like\n[Selenium](http://www.seleniumhq.org/), or a headless browser, it is\nquite common to do something like:\n\n1.  Visit `site.dev/login`{.highlighter-rouge}\n2.  Enter an incorrect username.\n3.  Enter an incorrect password.\n4.  Expect to see an error appear in the DOM.\n\nI’ve had problems before where the authors of these automated UI tests\nwere binding onto CSS classes: e.g. “Does\n`.message--error`{.highlighter-rouge} appear in the DOM?” The problem\nwith these tests looking out for style hooks is that simply refactoring\nyour CSS to use a different name can cause a test to fail, even if the\nfunctionality is exactly the same. In a similar vein to our JS hooks,\nautomated UI tests should not be reliant on CSS classes. To do so breaks\nour separation of concerns.\n\nWhat we need to do is have the QA team bind onto a suite of their own\nclasses that we leave well alone. This means that if we start out with\nthis:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cstrong class=\"message  error  qa-error-login\"\u003e\n```\n\n\u003c/div\u003e\n\n…and we refactor those nasty `.message`{.highlighter-rouge} and\n`.error`{.highlighter-rouge} classes, we should be left with something\nlike this:\n\n\u003cdiv class=\"highlighter-rouge\"\u003e\n\n``` {.highlight}\n\u003cstrong class=\"c-message  c-message--error  qa-error-login\"\u003e\n```\n\n\u003c/div\u003e\n\nWe can make all of the CSS changes we like, as long we we ensure that\nthe QA team’s hook stays in place.\n\n-   Binding automated UI tests onto style hooks is too inexplicit—don’t\n    do it.\n-   Bind tests onto dedicated test classes.\n-   Ensure that any UI refactoring doesn’t affect the QA team’s hooks.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnonoesp%2Ffolio-scss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnonoesp%2Ffolio-scss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnonoesp%2Ffolio-scss/lists"}