<commit_before>doctype html
html(lang="en" xmlns="http://www.w3.org/1999/xhtml")
  head
    title CSS Architecture
    meta(charset="utf-8")
    meta(name="author" content="<NAME>")
    meta(name="description" content="Write good CSS.")
    meta(name="keywords" content="css, code organization, code architecture")
    meta(name="viewport" content="width=device-width, initial-scale=1")
    link(rel="stylesheet" href="../../styles/chharvey.css")
  body.o-GoldenContainer
    p(style="position:fixed;font-weight:bold;font-size:1.5rem;color:red;") WARNING: THIS DRAFT IS INCOMPLETE AND POSSIBLY EVEN INCORRECT. DO NOT CITE OR REFERENCE IT. IT WILL BE MERGED INTO ANOTHER DOCUMENT AND RELEASED AT A LATER TIME.
    main.o-GoldenContainer__Content.c-Document(data-status="draft" itemscope="" itemtype="https://schema.org/Article")
      header
        h1(itemprop="name headline") CSS Architecture
        p.o-GoldenContainer__Content__SideMinor.o-Box.o-Box--island.c-Alert.c-Alert--dang.
          This document is a work in progress.
        dl.c-Document__Meta
          dt Author
          dd(itemprop="author") <NAME>
          dt Description
          dd(itemprop="description").
            A discussion on writing and organizing
            good, scalable, maintainable, powerful, efficient
            #[abbr.c-Acro(title="Cascading Stylesheets") CSS] code.
          dt Keywords
          dd(itemprop="keywords"): abbr(title="Cascading StyleSheets") CSS
          dd(itemprop="keywords"): abbr(title="HyperText Markup Languge") HTML
          dd(itemprop="keywords") code organization, architecture
          dt Version History
          dd.update
            time(datetime="2015-03-27") Mar 27, 2015
          dd.update
            time(datetime="2015-04-09 17:54") Apr 8, 2015 #[span.tod 5:54 PM]
          dd.update
            time(datetime="2015-04-13 14:30") Apr 13, 2015 #[span.tod 2:30 PM]
          dd.update
            time(datetime="2015-08-20 19:06") Aug 20, 2015 #[span.tod 7:06 PM]
          dd.update
            time(datetime="2015-10-03 12:13") Oct 3, 2015 #[span.tod 12:13 PM]
          dd.update
            time(datetime="2016-02-03 17:47") Feb 3, 2016 #[span.tod 5:47 PM]
          dd.update
            time(datetime="2016-02-03 23:14" itemprop="dateModified") Feb 3, 2016 #[span.tod 11:14 PM]
            small.o-Textbox.c-Label.c-Label--dang(class="!ml:1") Latest
      section.c-Document__Draft
        h2 Introduction
        p.c-Lede.c-Lede--dropcap.
          This document is a compilation of what I have learned about writing
          good, scalable, maintainable, powerful, efficient
          #[abbr.c-Acro(title="Cascading Stylesheets") CSS] code.
        p.c-Lede.
          First we start off from a narrow approach, looking at the CSS language itself,
          and then we work our way larger, discussing the ways it interacts with itself and
          with HTML.
        //- p Define properties, selectors, and stylesheets in order of increasing specificity.
        p.c-Lede.
          Note that this is not a coding style guide. How you format your code is up to you
          or a style guide you&rsquo;re using. Here we look at code from a higher level
          point of view.
      section#grouping-css-properties.c-Document__Complete
        h2 Grouping CSS Properties
        p.
          A CSS ruleset contains one or more property-value pairs. Within this ruleset,
          properties should be grouped by function, and these groups should be
          ordered in #[strong decreasing structure definition].
        p.
          There are two reasons for this. First, code hand-typed in this manner is
          much easier to communicate, maintain, and visualize. For example, you&rsquo;d like
          to know what a class looks like just by its code, not having to test it in the browser.
          Having an arbitrary order (such as alphabetical) makes it harder to visualize it.
        p: small.
          One of the arguments for alphabetical ordering is that it makes maintenance
          easier. That would be true, if selectors normally had a ton of rules
          in their rulesets. But we&rsquo;ll see later on that this is rarely,
          if ever, the case. If you keep your rulesets to a minimum of, say,
          five rules, then alphabetical ordering is basically useless.
        p.
          There is another reason to group properties by function, as well.
          CSS classes can be split into designated responsibilities, that is, authors may use
          separate classes for layout #[i(lang="la"): abbr(title="versus") vs.]
          structure #[i(lang="la"): abbr(title="versus") vs.] text properties.
          This makes the CSS
          more modular and reusable, and we will see how that is done in the next section.
        p.
          Also keep in mind that this order applies to properties #[em within a ruleset].
          We&rsquo;ll talk later about ordering rulesets within a stylesheet&mdash;and
          then later, ordering stylesheets themselves.
        figure
          img(style="box-shadow: none;" src="../images/css-pyramid-props.svg" alt="An inverted triangle illustrates how CSS properties are related.")
          figcaption.c-Caption.c-Caption--after.
            This inverted triangle illustrates how CSS properties are related.
            From top to bottom, structural definition is exchanged for cosmetic styling.
        ol
          li: p.
            #[strong Layout.]
            The top base of the triangle contains properties that set up foundation and layout,
            such as display and position. These properties most define the element&rsquo;s
            relationship with others on the page.
          li: p.
            #[strong Box Structure.]
            The next level is similar, but with more of an inner focus, setting up box structure
            like width, padding, and margin. Transformations are also included in this level.
          li: p.
            #[strong Text Structure.]
            The middle level contains typographical structure: font, text alignment and spacing,
            etc. Anything that describes the composition of text goes here.
          li: p.
            #[strong Box Cosmetics.]
            This level sets the look-and-feel of the box model of elements.
            These properties only change the cosmetics, not the structure of the box.
            The styles of the box are set before the styles of the text inside.
          li: p.
            #[strong Text Cosmetics.]
            This level sets the decorative style of the text, again, unrelated
            to its structure.
            Notice how we work from outer to inner, styling the
            cosmetics of the container before its contents.
          li: p.
            #[strong Other.]
            The last level, at the vertex, is for miscellaneous properties.
            These properties don&rsquo;t belong in any particular category.
        figure
          figcaption.c-Caption.c-Caption--before.
            An outline listing the most common CSS properties in each category.
            #[strong This is not a complete list of all CSS properties.]
            If a property is not listed, use your best judgement for its place.
          ol(class="a-ff-accent a-fzb-milli")
            li Layout:
              ol
                li display
                li position, top, left, bottom, right
                li float, clear
                li z-index
                li vertical-align
                li flex-direction, flex-wrap, justify-content, align-content, align-items, flex, order
            li Box Structure:
              ol
                li box-sizing
                li width, height
                li padding, margin
                li transformations
            li Text Structure:
              ol
                li font[-style|-variant|-weight|-size|-family]? #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li line-height                                  #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li letter-spacing                               #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li word-spacing                                 #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-align                                   #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-indent                                  #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li white-space                                  #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li overflow-wrap (word-wrap)                    #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li column[-count|-width|s]
                li page-break-[before|after]
            li Box Cosmetics:
              ol
                li border[-width|-style|-color|-radius]?
                li outline
                li box-shadow
                li background[-image|-position|-size|-repeat|-attachment|-origin|-clip|-color]?
                li overflow
                li opacity
                li visibility                          #[small.o-Textbox.c-Label.c-Label--skss inherited]
            li Text Cosmetics:
              ol
                li text-rendering                      #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-transform                      #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-decoration
                li text-shadow                         #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-overflow
                li list-style[-type|-position|-image]? #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li quotes
                li color                               #[small.o-Textbox.c-Label.c-Label--skss inherited]
            li Other:
              ol
                li cursor                              #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li transition
      aside.o-GoldenContainer__Content__SideMajor.c-Document__Draft#semantics-trumps-style
        h2 Semantics Trumps Style
        p.
          When it comes down to efficient HTML
          versus efficient CSS, HTML wins. The reason? Semantics trumps style.
          This happens on two fronts. First simply for the sake of principle. The most
          important data is the actual content being presented. This trumps any data on
          #[em how] it is being presented. If you have to sacrifice one for the other,
          content trumps presentation.
          While that seems fine as a theoretical argument, there is also evidence to back it up.
        p.
          The second front on which semantics trumps style is seen from a more practical
          point of view. For example, every design change should, at
          least mostly, be taken care of in the CSS.
          You&rsquo;ve got a problem when you find yourself having to adjust a massive
          number of #[code class] attributes to implement a design change (ahem, looking at you, Atomic CSS).
          Or wrapping content with unsemantic #[code div] elements just to make it look right.
          It should be the other way around: when the design changes, you should
          be&mdash;mostly&mdash;adjusting your CSS. It is the CSS that should conform to
          how HTML is written, even if it means sacrificing a little bit of efficiency.
        p.
          One of the arguments against this is, #[q well, the bloat&rsquo;s gotta be somewhere.]
          But the trade-off can be seen on the user end. Which is worse, HTML bloat
          or CSS bloat? Every time the user loads a new page, all that markup is downloaded,
          every time, whereas hopefully your stylesheet will have been downloaded only once
          and then cached.
      section.c-Document__Complete
        h2(class="!fs:i !fv:i !fw:i")
          b(class="!fw:9") class&middot;i&middot;tis
          |  (kl&aelig;s-a&#x026a;&apos;t&#x0258;s) 
          abbr(class="!fs:t" title="noun") n.
        p.
          No, I&rsquo;m not talking about an overuse of classes&mdash;I don&rsquo;t
          believe you can ever use too many classes in HTML. #[b Classitis] in my
          opinion refers to the fact that we are using HTML classes for #[em everything],
          and this becomes overwhelming when it comes to architecting and maintaining CSS.
        p.
          We need to seriously analyze the many, #[em many] different ways that we use
          the HTML #[code class] attribute,
          separate and categorize them into #[i classifications] to clearly identify each use,
          and talk about the different types of CSS classes we can create based on each use.
        //- p.
          Maybe we can provide some alternative methods and/or conventions for implementing
          semantics and style.
          I even go insofar as to suggest ammendments to the CSS specification. After all,
          #[a we are using a very old technology to achieve very new things].
        p.
          All the types of classes we discuss here are syntactically indistinguishable: like
          any CSS class, they have a given set of properties and thus aren&rsquo;t differentiated
          by browsers. However, seeing as they are actually used for different purposes, we must make
          the distinction clear to provide a starting point for the cure of classitis.
        p But first, some background information.
        section.c-Document__Draft
          h3 Background
          p.
            #[strong The original intent of HTML classes.]
            The HTML #[code class] attribute was #[a originally] meant to group
            semantically similar elements together. For example, all elements that
            represent warnings on a page could all have #[code [class="warning"]].
            A side effect of semantically similar elements belonging to one class
            is that they can all be styled the same way with the CSS #[code .warning] class.
            Well, it seems now we have blown this way out of proportion.
          p.
            With the development of #[a Object-Oriented CSS], we have learned to take advantage of
            classes and use them for many different reasons. This can be a good thing or a bad thing.
            On one hand, authors are successfully implementing best practices: separating concerns,
            abstracting reusable components, maximizing performance,
            #[i(lang="la"): abbr(title="et cetera") etc.] On the other hand,
            such a diverse use of one specific feature of HTML has grown so large it has become an epidemic.
          p.
            Now, instead of using CSS classes to merely group similar elements together, we are using them
            to define patterns of style repeated throughout a page or site,
            and then making elements #[i instantiate] them, if you will.
            While syntactically, there really is no change, there&rsquo;s something fundamentally,
            subtly, different going on here. Instead of saying,
            #[q these two elements are similar in meaning; I should give them the same class so that they appear the same],
            we&rsquo;re now saying,
            #[q I want these two elements to appear the same (for whatever reason); I should give them the same class].
            It&rsquo;s almost backwards!
          p.
            I&rsquo;m not here to tell you not to use classes. In fact I think classes are the perfect
            mechanism for this. But as you read this article I do hope you become more aware of the
            different types of classes you are using, and you are able to make smart decisions about
            when you should or should not be using them.
        section
          h3 #[i Classes] of Classes
          p.
            In the last section, we talked about CSS properties, a relatively lower level aspect
            of CSS architecture. You might have noticed however that I&rsquo;ve already hinted at
            something slightly more involved, and that is it can be good practice to literally
            group related properties, not within a CSS selector, but into separate selectors.
          p.
            For the sake of simplicity, we will not be discussing the actual naming
            of CSS classes in this section, so I will refrain from using them and
            instead keep the discussion in the abstract.
          p The following subsections name and categorize classes by the properties in their defining rulesets.
          section
            h4 Objects
            p: strong.
              #[dfn#object Objects] are classes used for creating patterns of structure
              that can be reused many times for many different purposes.
            p.
              Objects are free from content, cosmetics, and function. They provide
              page layout/grid systems, or common structural patterns for elements.
              Examples include the Media Object, the Nav Abstraction, and the Island Object.
              These classes do not affect look-and-feel, only visual structure. Think back to
              the #[b Layout] and #[b Box Structure] levels of the inverted CSS property triangle above.
          section
            h4 Components
            p: strong.
              #[dfn#component Components] are classes used for creating patterns of look-and-feel
              that are each only used for one functional purpose.
            p.
              In contrast to Objects, Components are heavily dependent on content, cosmetics,
              and function. They are recognizable pieces of user-interaction that have a particular
              look-and-feel. Buttons, breadcrumb lists, labels, and tags are all good examples.
              Components have properties belonging in the smallest 4 layers of the
              inverted CSS property triangle.
            p.
              To build a fully-functional visual element on a page, you must combine
              Objects and Components. Using just a Component class is not sufficient, because
              you will get the skin without the structure.
            aside
              p.
                In most cases, the cosmetics of a Component laregly contribute to its function.
                As frequent as Components come, they are unusual in that
                their semantics are derived from their presentation,
                that is, the look-and-feel of a Component may determine its meaning in terms of usability.
                For example, a #[code span] might not look like anything with CSS turned off,
                but with the right class and CSS turned on it might clearly represent a label attached
                to a heading or link.
              p: small.
                As a consequence, authors should be careful with Components because users with
                a visual interface might have an advantage over users with, say, an audio interface.
                Therefore authors should continue to support
                #[a HTML5 Microdata] and #[a ARIA roles]
                to accommodate the latter.
            div.c-Document__Informative
              p.
                I have not decided yet whether to make these next sections formal. This is just an idea:
                There are two types of Components: Typographical, and UI (User-Interactive).
              section
                h5 Typographical Components
                p.
                  Typographical Components are static and textual. There is no user interaction or
                  functionality. Examples include special headings, lede paragraphs, callout boxes,
                  and inline-level elements such as dates, places, and acronyms.
              section
                h5 UI Components
                p.
                  UI Components are the dynamic bells-and-whistles
                  that make a webpage pop. These are things that users are likely to interact
                  with, such as alerts, labels, navigation, and buttons.
                  Not all of these must be interactive, though: some UI Components can
                  just sit there and look pretty, like an icon or badge.
          section
            h4 Themes
            p: strong.
              #[dfn#theme Themes] are classes that provide context.
            p.
              Theme classes are very tricky. A Theme applied to an element might not only affect
              the element itself, but will also probably affect its descendants. This gets complicated
              because the said descendant&rsquo;s style becomes dependent on its location.
              Move the element, or change the Theme, then the element will look different.
              (This could be a good or a bad thing.)
              We must be careful not to let the element&rsquo;s style depend heavily on the
              Theme classes of its ancestors. Thus we should limit the styles in a Theme class
              to those belonging in the #[b Box Cosmetics] and #[b Text Cosmetics] levels
              of the inverted triangle. Most themes only affect font family, color, and the like.
          section
            h4 Helpers
            p: strong.
              #[dfn#helper Helpers] are somewhat explicit classes used for enhancing default styles.
            p.
              When an element already #[i instantiates] Objects and Components (has their classes),
              but you need a little bit more, a Helper class is the solution.
              Helpers tack on a very small combination of extra styles to achieve a specific look.
              The clearfix is an excellent example. Even though it affects structure, it doesn&rsquo;t
              count as an Object because it&rsquo;s not really a #[i thing], it&rsquo;s more of a tool.
              #[small (which is a thing, I know. shut up.)]
            p.
              Helper classes should be rare enough that they don&rsquo;t become full-fledged site-wide
              reusable patterns, yet they should be common enough to save you the frustration of
              copying those inline styles. Properties in Helper classes can range anywhere in the
              CSS property triangle, from #[b Layout] to structural styles to cosmetic styles.
          section
            h4 Atoms
            p: strong.
              #[dfn#atom Atoms] are very specific classes used for creating anomalies
              or fixing broken styles.
            p.
              To be honest, I stole the name #[i atom] from #[a Atomic CSS] and
              #[a Atomic Design by <NAME>]. These ideas use the word #[i atom] in the sense
              that it is a small (actually #[em the] smallest) block from which larger items can be built.
              Given the nature of these classes, which I&rsquo;ll talk about later, the name stuck.
            p.
              However, classes I call #[i Atoms] are hardly that:
              these classes are #[em not] to be used as building blocks, rather, they are used as
              #[a trumps, in Harry Roberts&rsquo; words]. That is, these classes are end-all-be-all rules
              that always win, no matter what. Instead of living at the foundation of your codebase,
              they&rsquo;re right there at the very tippy top.
            p: small.
              Kind of like that card in the card game
              #[cite Cards Against Humanity]&mdash;#[span(title="The Biggest, Blackest, Dick") you know the one I&rsquo;m talking about]&mdash;people
              call it #[i the trump card] because
              whenever you play it you basically automatically win. But I&rsquo;d prefer not to
              call these classes #[i trumps] due to a certain republican presidential candidate.
            p.
              Anyway, an Atom does one job and it does it very well. Each atom typically has
              one style in its ruleset, which is usually accompanied by #[code !important].
              Add an Atom class to an element when you need a quick fix, override, or when you
              simply need to style it differently for no logical reason at all.
              Like Helpers, there can be Atoms for any property in the CSS property triangle.
          section
            h4 Non-CSS Classes
            p.
              Last but not least, we have all the classes used in markup that you
              don&rsquo;t write in your CSS codebase. They
              are automated by scripting languages (either server-side or client-side),
              are made for the purpose of query selecting, or
              come prepackaged in some other system, such as #[a microformats].
              Classes from imported stylesheets don&rsquo;t count in this category;
              they&rsquo;re still part of your codebase, even if you didn&rsquo;t write them.
              I&rsquo;m talking about, for example, classes generated by #[a MathJax], and<commit_msg>finish 'classes of classes'<commit_after>doctype html
html(lang="en" xmlns="http://www.w3.org/1999/xhtml")
  head
    title CSS Architecture
    meta(charset="utf-8")
    meta(name="author" content="<NAME>")
    meta(name="description" content="Write good CSS.")
    meta(name="keywords" content="css, code organization, code architecture")
    meta(name="viewport" content="width=device-width, initial-scale=1")
    link(rel="stylesheet" href="../../styles/chharvey.css")
  body.o-GoldenContainer
    p(style="position:fixed;font-weight:bold;font-size:1.5rem;color:red;") WARNING: THIS DRAFT IS INCOMPLETE AND POSSIBLY EVEN INCORRECT. DO NOT CITE OR REFERENCE IT. IT WILL BE MERGED INTO ANOTHER DOCUMENT AND RELEASED AT A LATER TIME.
    main.o-GoldenContainer__Content.c-Document(data-status="draft" itemscope="" itemtype="https://schema.org/Article")
      header
        h1(itemprop="name headline") CSS Architecture
        p.o-GoldenContainer__Content__SideMinor.o-Box.o-Box--island.c-Alert.c-Alert--dang.
          This document is a work in progress.
        dl.c-Document__Meta
          dt Author
          dd(itemprop="author") <NAME>
          dt Description
          dd(itemprop="description").
            A discussion on writing and organizing
            good, scalable, maintainable, powerful, efficient
            #[abbr.c-Acro(title="Cascading Stylesheets") CSS] code.
          dt Keywords
          dd(itemprop="keywords"): abbr(title="Cascading StyleSheets") CSS
          dd(itemprop="keywords"): abbr(title="HyperText Markup Languge") HTML
          dd(itemprop="keywords") code organization, architecture
          dt Version History
          dd.update
            time(datetime="2015-03-27") Mar 27, 2015
          dd.update
            time(datetime="2015-04-09 17:54") Apr 8, 2015 #[span.tod 5:54 PM]
          dd.update
            time(datetime="2015-04-13 14:30") Apr 13, 2015 #[span.tod 2:30 PM]
          dd.update
            time(datetime="2015-08-20 19:06") Aug 20, 2015 #[span.tod 7:06 PM]
          dd.update
            time(datetime="2015-10-03 12:13") Oct 3, 2015 #[span.tod 12:13 PM]
          dd.update
            time(datetime="2016-02-03 17:47") Feb 3, 2016 #[span.tod 5:47 PM]
          dd.update
            time(datetime="2016-02-03 23:14" itemprop="dateModified") Feb 3, 2016 #[span.tod 11:14 PM]
            small.o-Textbox.c-Label.c-Label--dang(class="!ml:1") Latest
      section.c-Document__Draft
        h2 Introduction
        p.c-Lede.c-Lede--dropcap.
          This document is a compilation of what I have learned about writing
          good, scalable, maintainable, powerful, efficient
          #[abbr.c-Acro(title="Cascading Stylesheets") CSS] code.
        p.c-Lede.
          First we start off from a narrow approach, looking at the CSS language itself,
          and then we work our way larger, discussing the ways it interacts with itself and
          with HTML.
        //- p Define properties, selectors, and stylesheets in order of increasing specificity.
        p.c-Lede.
          Note that this is not a coding style guide. How you format your code is up to you
          or a style guide you&rsquo;re using. Here we look at code from a higher level
          point of view.
      section#grouping-css-properties.c-Document__Complete
        h2 Grouping CSS Properties
        p.
          A CSS ruleset contains one or more property-value pairs. Within this ruleset,
          properties should be grouped by function, and these groups should be
          ordered in #[strong decreasing structure definition].
        p.
          There are two reasons for this. First, code hand-typed in this manner is
          much easier to communicate, maintain, and visualize. For example, you&rsquo;d like
          to know what a class looks like just by its code, not having to test it in the browser.
          Having an arbitrary order (such as alphabetical) makes it harder to visualize it.
        p: small.
          One of the arguments for alphabetical ordering is that it makes maintenance
          easier. That would be true, if selectors normally had a ton of rules
          in their rulesets. But we&rsquo;ll see later on that this is rarely,
          if ever, the case. If you keep your rulesets to a minimum of, say,
          five rules, then alphabetical ordering is basically useless.
        p.
          There is another reason to group properties by function, as well.
          CSS classes can be split into designated responsibilities, that is, authors may use
          separate classes for layout #[i(lang="la"): abbr(title="versus") vs.]
          structure #[i(lang="la"): abbr(title="versus") vs.] text properties.
          This makes the CSS
          more modular and reusable, and we will see how that is done in the next section.
        p.
          Also keep in mind that this order applies to properties #[em within a ruleset].
          We&rsquo;ll talk later about ordering rulesets within a stylesheet&mdash;and
          then later, ordering stylesheets themselves.
        figure
          img(style="box-shadow: none;" src="../images/css-pyramid-props.svg" alt="An inverted triangle illustrates how CSS properties are related.")
          figcaption.c-Caption.c-Caption--after.
            This inverted triangle illustrates how CSS properties are related.
            From top to bottom, structural definition is exchanged for cosmetic styling.
        ol
          li: p.
            #[strong Layout.]
            The top base of the triangle contains properties that set up foundation and layout,
            such as display and position. These properties most define the element&rsquo;s
            relationship with others on the page.
          li: p.
            #[strong Box Structure.]
            The next level is similar, but with more of an inner focus, setting up box structure
            like width, padding, and margin. Transformations are also included in this level.
          li: p.
            #[strong Text Structure.]
            The middle level contains typographical structure: font, text alignment and spacing,
            etc. Anything that describes the composition of text goes here.
          li: p.
            #[strong Box Cosmetics.]
            This level sets the look-and-feel of the box model of elements.
            These properties only change the cosmetics, not the structure of the box.
            The styles of the box are set before the styles of the text inside.
          li: p.
            #[strong Text Cosmetics.]
            This level sets the decorative style of the text, again, unrelated
            to its structure.
            Notice how we work from outer to inner, styling the
            cosmetics of the container before its contents.
          li: p.
            #[strong Other.]
            The last level, at the vertex, is for miscellaneous properties.
            These properties don&rsquo;t belong in any particular category.
        figure
          figcaption.c-Caption.c-Caption--before.
            An outline listing the most common CSS properties in each category.
            #[strong This is not a complete list of all CSS properties.]
            If a property is not listed, use your best judgement for its place.
          ol(class="a-ff-accent a-fzb-milli")
            li Layout:
              ol
                li display
                li position, top, left, bottom, right
                li float, clear
                li z-index
                li vertical-align
                li flex-direction, flex-wrap, justify-content, align-content, align-items, flex, order
            li Box Structure:
              ol
                li box-sizing
                li width, height
                li padding, margin
                li transformations
            li Text Structure:
              ol
                li font[-style|-variant|-weight|-size|-family]? #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li line-height                                  #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li letter-spacing                               #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li word-spacing                                 #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-align                                   #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-indent                                  #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li white-space                                  #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li overflow-wrap (word-wrap)                    #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li column[-count|-width|s]
                li page-break-[before|after]
            li Box Cosmetics:
              ol
                li border[-width|-style|-color|-radius]?
                li outline
                li box-shadow
                li background[-image|-position|-size|-repeat|-attachment|-origin|-clip|-color]?
                li overflow
                li opacity
                li visibility                          #[small.o-Textbox.c-Label.c-Label--skss inherited]
            li Text Cosmetics:
              ol
                li text-rendering                      #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-transform                      #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-decoration
                li text-shadow                         #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li text-overflow
                li list-style[-type|-position|-image]? #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li quotes
                li color                               #[small.o-Textbox.c-Label.c-Label--skss inherited]
            li Other:
              ol
                li cursor                              #[small.o-Textbox.c-Label.c-Label--skss inherited]
                li transition
      aside.o-GoldenContainer__Content__SideMajor.c-Document__Draft#semantics-trumps-style
        h2 Semantics Trumps Style
        p.
          When it comes down to efficient HTML
          versus efficient CSS, HTML wins. The reason? Semantics trumps style.
          This happens on two fronts. First simply for the sake of principle. The most
          important data is the actual content being presented. This trumps any data on
          #[em how] it is being presented. If you have to sacrifice one for the other,
          content trumps presentation.
          While that seems fine as a theoretical argument, there is also evidence to back it up.
        p.
          The second front on which semantics trumps style is seen from a more practical
          point of view. For example, every design change should, at
          least mostly, be taken care of in the CSS.
          You&rsquo;ve got a problem when you find yourself having to adjust a massive
          number of #[code class] attributes to implement a design change (ahem, looking at you, Atomic CSS).
          Or wrapping content with unsemantic #[code div] elements just to make it look right.
          It should be the other way around: when the design changes, you should
          be&mdash;mostly&mdash;adjusting your CSS. It is the CSS that should conform to
          how HTML is written, even if it means sacrificing a little bit of efficiency.
        p.
          One of the arguments against this is, #[q well, the bloat&rsquo;s gotta be somewhere.]
          But the trade-off can be seen on the user end. Which is worse, HTML bloat
          or CSS bloat? Every time the user loads a new page, all that markup is downloaded,
          every time, whereas hopefully your stylesheet will have been downloaded only once
          and then cached.
      section.c-Document__Complete
        h2(class="!fs:i !fv:i !fw:i")
          b(class="!fw:9") class&middot;i&middot;tis
          |  (kl&aelig;s-a&#x026a;&apos;t&#x0258;s) 
          abbr(class="!fs:t" title="noun") n.
        p.
          No, I&rsquo;m not talking about an overuse of classes&mdash;I don&rsquo;t
          believe you can ever use too many classes in HTML. #[b Classitis] in my
          opinion refers to the fact that we are using HTML classes for #[em everything],
          and this becomes overwhelming when it comes to architecting and maintaining CSS.
        p.
          We need to seriously analyze the many, #[em many] different ways that we use
          the HTML #[code class] attribute,
          separate and categorize them into #[i classifications] to clearly identify each use,
          and talk about the different types of CSS classes we can create based on each use.
        //- p.
          Maybe we can provide some alternative methods and/or conventions for implementing
          semantics and style.
          I even go insofar as to suggest ammendments to the CSS specification. After all,
          #[a we are using a very old technology to achieve very new things].
        p.
          All the types of classes we discuss here are syntactically indistinguishable: like
          any CSS class, they have a given set of properties and thus aren&rsquo;t differentiated
          by browsers. However, seeing as they are actually used for different purposes, we must make
          the distinction clear to provide a starting point for the cure of classitis.
        p But first, some background information.
        section.c-Document__Draft
          h3 Background
          p.
            #[strong The original intent of HTML classes.]
            The HTML #[code class] attribute was #[a originally] meant to group
            semantically similar elements together. For example, all elements that
            represent warnings on a page could all have #[code [class="warning"]].
            A side effect of semantically similar elements belonging to one class
            is that they can all be styled the same way with the CSS #[code .warning] class.
            Well, it seems now we have blown this way out of proportion.
          p.
            With the development of #[a Object-Oriented CSS], we have learned to take advantage of
            classes and use them for many different reasons. This can be a good thing or a bad thing.
            On one hand, authors are successfully implementing best practices: separating concerns,
            abstracting reusable components, maximizing performance,
            #[i(lang="la"): abbr(title="et cetera") etc.] On the other hand,
            such a diverse use of one specific feature of HTML has grown so large it has become an epidemic.
          p.
            Now, instead of using CSS classes to merely group similar elements together, we are using them
            to define patterns of style repeated throughout a page or site,
            and then making elements #[i instantiate] them, if you will.
            While syntactically, there really is no change, there&rsquo;s something fundamentally,
            subtly, different going on here. Instead of saying,
            #[q these two elements are similar in meaning; I should give them the same class so that they appear the same],
            we&rsquo;re now saying,
            #[q I want these two elements to appear the same (for whatever reason); I should give them the same class].
            It&rsquo;s almost backwards!
          p.
            I&rsquo;m not here to tell you not to use classes. In fact I think classes are the perfect
            mechanism for this. But as you read this article I do hope you become more aware of the
            different types of classes you are using, and you are able to make smart decisions about
            when you should or should not be using them.
        section
          h3 #[i Classes] of Classes
          p.
            In the last section, we talked about CSS properties, a relatively lower level aspect
            of CSS architecture. You might have noticed however that I&rsquo;ve already hinted at
            something slightly more involved, and that is it can be good practice to literally
            group related properties, not within a CSS selector, but into separate selectors.
          p.
            For the sake of simplicity, we will not be discussing the actual naming
            of CSS classes in this section, so I will refrain from using them and
            instead keep the discussion in the abstract.
          p The following subsections name and categorize classes by the properties in their defining rulesets.
          section
            h4 Objects
            p: strong.
              #[dfn#object Objects] are classes used for creating patterns of structure
              that can be reused many times for many different purposes.
            p.
              Objects are free from content, cosmetics, and function. They provide
              page layout/grid systems, or common structural patterns for elements.
              Examples include the Media Object, the Nav Abstraction, and the Island Object.
              These classes do not affect look-and-feel, only visual structure. Think back to
              the #[b Layout] and #[b Box Structure] levels of the inverted CSS property triangle above.
          section
            h4 Components
            p: strong.
              #[dfn#component Components] are classes used for creating patterns of look-and-feel
              that are each only used for one functional purpose.
            p.
              In contrast to Objects, Components are heavily dependent on content, cosmetics,
              and function. They are recognizable pieces of user-interaction that have a particular
              look-and-feel. Buttons, breadcrumb lists, labels, and tags are all good examples.
              Components have properties belonging in the smallest 4 layers of the
              inverted CSS property triangle.
            p.
              To build a fully-functional visual element on a page, you must combine
              Objects and Components. Using just a Component class is not sufficient, because
              you will get the skin without the structure.
            aside
              p.
                In most cases, the cosmetics of a Component laregly contribute to its function.
                As frequent as Components come, they are unusual in that
                their semantics are derived from their presentation,
                that is, the look-and-feel of a Component may determine its meaning in terms of usability.
                For example, a #[code span] might not look like anything with CSS turned off,
                but with the right class and CSS turned on it might clearly represent a label attached
                to a heading or link.
              p: small.
                As a consequence, authors should be careful with Components because users with
                a visual interface might have an advantage over users with, say, an audio interface.
                Therefore authors should continue to support
                #[a HTML5 Microdata] and #[a ARIA roles]
                to accommodate the latter.
            div.c-Document__Informative
              p.
                I have not decided yet whether to make these next sections formal. This is just an idea:
                There are two types of Components: Typographical, and UI (User-Interactive).
              section
                h5 Typographical Components
                p.
                  Typographical Components are static and textual. There is no user interaction or
                  functionality. Examples include special headings, lede paragraphs, callout boxes,
                  and inline-level elements such as dates, places, and acronyms.
              section
                h5 UI Components
                p.
                  UI Components are the dynamic bells-and-whistles
                  that make a webpage pop. These are things that users are likely to interact
                  with, such as alerts, labels, navigation, and buttons.
                  Not all of these must be interactive, though: some UI Components can
                  just sit there and look pretty, like an icon or badge.
          section
            h4 Themes
            p: strong.
              #[dfn#theme Themes] are classes that provide context.
            p.
              Theme classes are very tricky. A Theme applied to an element might not only affect
              the element itself, but will also probably affect its descendants. This gets complicated
              because the said descendant&rsquo;s style becomes dependent on its location.
              Move the element, or change the Theme, then the element will look different.
              (This could be a good or a bad thing.)
              We must be careful not to let the element&rsquo;s style depend heavily on the
              Theme classes of its ancestors. Thus we should limit the styles in a Theme class
              to those belonging in the #[b Box Cosmetics] and #[b Text Cosmetics] levels
              of the inverted triangle. Most themes only affect font family, color, and the like.
          section
            h4 Helpers
            p: strong.
              #[dfn#helper Helpers] are somewhat explicit classes used for enhancing default styles.
            p.
              When an element already #[i instantiates] Objects and Components (has their classes),
              but you need a little bit more, a Helper class is the solution.
              Helpers tack on a very small combination of extra styles to achieve a specific look.
              The clearfix is an excellent example. Even though it affects structure, it doesn&rsquo;t
              count as an Object because it&rsquo;s not really a #[i thing], it&rsquo;s more of a tool.
              #[small (which is a thing, I know. shut up.)]
            p.
              Helper classes should be rare enough that they don&rsquo;t become full-fledged site-wide
              reusable patterns, yet they should be common enough to save you the frustration of
              copying those inline styles. Properties in Helper classes can range anywhere in the
              CSS property triangle, from #[b Layout] to structural styles to cosmetic styles.
          section
            h4 Atoms
            p: strong.
              #[dfn#atom Atoms] are very specific classes used for creating anomalies
              or fixing broken styles.
            p.
              To be honest, I stole the name #[i atom] from #[a Atomic CSS] and
              #[a Atomic Design by <NAME>rost]. These ideas use the word #[i atom] in the sense
              that it is a small (actually #[em the] smallest) block from which larger items can be built.
              Given the nature of these classes, which I&rsquo;ll talk about later, the name stuck.
            p.
              However, classes I call #[i Atoms] are hardly that:
              these classes are #[em not] to be used as building blocks, rather, they are used as
              #[a trumps, in Harry Roberts&rsquo; words]. That is, these classes are end-all-be-all rules
              that always win, no matter what. Instead of living at the foundation of your codebase,
              they&rsquo;re right there at the very tippy top.
            p: small.
              Kind of like that card in the card game
              #[cite Cards Against Humanity]&mdash;#[span(title="The Biggest, Blackest, Dick") you know the one I&rsquo;m talking about]&mdash;people
              call it #[i the trump card] because
              whenever you play it you basically automatically win. But I&rsquo;d prefer not to
              call these classes #[i trumps] due to a certain republican presidential candidate.
            p.
              Anyway, an Atom does one job and it does it very well. Each atom typically has
              one style in its ruleset, which is usually accompanied by #[code !important].
              Add an Atom class to an element when you need a quick fix, override, or when you
              simply need to style it differently for no logical reason at all.
              Like Helpers, there can be Atoms for any property in the CSS property triangle.
          section
            h4 Hacks and More
            p.
              Last but not least, this section describes two types of classes:
              Hacks and other non-CSS classes.
              Hacks are classes that doesn&rsquo;t belong in your codebase in the long run.
              They address bugs that can&rsquo;t immediately be fixed with Atoms or inline styles
              because of specificity issues or other reasons.
              These bugs probably have more elegant solutions, but you might not have time to
              find them right away.
              Hacks are likely to be more than just class selectors: they may be
              #[i compound selectors] (qualified selectors) or
              #[i complex selectors] (child/descendant/sibling selctors) as well.
              Hacks are okay as long as they don&rsquo;t remain permanently in your codebase.
            p.
              We also have other other non-CSS classes, which are classes used in markup that you
              don&rsquo;t write in your CSS codebase. They
              are automated by scripting languages (either server-side or client-side),
              are made for the purpose of query selecting, or
              come prepackaged in some other system, such as #[a microformats].
              Classes from imported stylesheets don&rsquo;t count in this category;
              they&rsquo;re still part of your codebase, even if you didn&rsquo;t write them.
              Rather, I&rsquo;m talking about, for example, classes generated by #[a MathJax], and
{'fraction_non_alphanumeric': 0.05855206791806215, 'fraction_numerical': 0.006737284835267544, 'mean_word_length': 1.944782110091743, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 14, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5618174', 'n_tokens_mistral': 12683, 'n_tokens_neox': 12038, 'n_words': 5918}