Skip to content

Instantly share code, notes, and snippets.

@calvinjuarez
Created February 12, 2021 20:46
Show Gist options
  • Save calvinjuarez/6f96fb028e56cfb3bac41c51046e0e77 to your computer and use it in GitHub Desktop.
Save calvinjuarez/6f96fb028e56cfb3bac41c51046e0e77 to your computer and use it in GitHub Desktop.
My Complex Box Naming Convention
<!-- A comprehensive demo of each piece of the convention and how they fit together. -->
<div class="boxes">
<section class="box">
<div class="box-inner">
<div class="box-X"></div>
<div class="box-main">
<header class="box-header">
<h1 class="box-heading">Foo</h1>
<h2 class="box-subheading">Bar</h2>
</header>
<div class="box-content">
<div class="box-section">
<p>Lorem ipsum dolor sit amet.</p>
<!--
At this point, you'd restart with `.box-section-inner`,
etc., though it's also a great time to consider whether
a new reusable pattern would be more appropriate.
-->
</div>
<div class="box-section">
<p>Lorem ipsum dolor sit amet.</p>
</div>
</div>
<footer class="box-footer">
<p>Baz.</p>
</footer>
</div>
<div class="box-X"></div>
</div>
</section>
<section class="box">
<!-- ... -->
</section>
</div>

Naming Convention for Common Elements in a Generic CSS Box Pattern

In general the principle is that you use only what you need. This convention helps you think about what the purpose of each part of your general pattern is so that if you don't need something now, but you find you do in a refactor down the road, you haven't already used the name that fits best. It also makes your patterns more consistent and therefore more readable to other developers (and to future you).

Yes this convention should be seen as a guideline, but the closer you stick to it, the more valuable it will be.

For some use cases showing where bits were omitted when the weren't necessary, see the examples below.

The Group Root .*s (plural)

OPTIONAL

In the event of a group of the pattern being common, the grouping element should be the simple plural of the pattern root.

The Root .*

The outermost element should be the thing. .*-container, .*-wrapper, etc. are confusing and make finding the root element of the pattern tougher than it needs to be.

An Inner .*-inner

OPTIONAL

It's sometimes necessary to define key characteristics of the internal layout of a pattern on a separate element to the one where you define external layout. Rather than creating a .*-container, which obscures the root element in the markup, instead you create an .*-inner element. This is just as semantic, but allows .* to be the root element.

This can be re-applied wherever you need to control interior layout. For example, you might find you need a .*-header-inner to control interior layout of your pattern's header.

While this re-application is possible with most of these pieces, it's important to ask yourself if a new reusable pattern would be more appropriate. In my experience, I find .*-inner to be the most re-applicable (because it's role is so specific and strongly defined).

Non-Core Stuff .*-X

OPTIONAL, REPEATABLE

Flexibility is given here to put things that sit next to the content and that are named appropriate to the use case.

For example, in a media object, this is where the actual image (or other media element) would sit, perhaps called .*-visual or .*-side. In that case, this could be thought of as roughly analogous to the <aside> element.

In another example, a toolbar of actions that sits outside the main "canvas" of the pattern. In that case you might call it .*-tools or .*-actions.

The Core .*-main

OPTIONAL

All the stuff that's core/intrinsic to what you're building should live here. This is probably about as low as you'll be putting the main pattern's primary background-color.

This element only needs to be explicitly created if you have .*-X elements and you need to wrap your outline elements together. I think in my experience this one is the one I end up needing the least.

The Outline Elements .*-header, .*-content, .*-footer

OPTIONAL

If there are no .*-head or .*-foot elements, .*-content .*-body start to blend together into redundancy. Only one of them should be used. Remember that .*-inner should be the place for whole-pattern inner layout.

Generally, if a .*-header and/or .*-footer is required, it's best to also include a .*-content element, but the opposite is not the case; it's common not to need a footer and only to need a headING, not a whole headER, but still need to wrap your content because it includes multiple paragraphs. That's just fine.

.*-header should never be put on an <h1>, <h2>, etc. The header is a whole container for everything that sits at the top

Alternaltely: .*-head could be used in place of .*-header. Likewise, .*-foot for .*-footer, and .*-body for .*-content. I'll admit there's something nice about the consistency of .*-head, .*-body, and .*-foot (all anatomical words with 4 letters) but I developed this by habit and convention, so those aren't what I use at the moment.

Outline-Interior Elements

OPTIONAL, REPEATABLE

.*-heading, .*-subheading, and .*-section are fairly transparent by their names what they do.

You do NOT have to define explicit outline elements to use the outline-interior elements.

Alternately: .*-title and .*-subtitle could be used instead of .*-heading and .*-subheading. Also .*-section may have a more semantic name depending on the pattern you're defining, though you might also consider wheter a new pattern would be more appropriate.

<article class="media">
<div class="media-visual">
<img src="https://via.placeholder.com/100"/>
</div>
<div class="media-main">
<h1 class="media-heading">Lorem Ipsum</h1>
<div class="media-content">
<p>Lorem ipsum.</p>
<p>Dolor sit amet.</p>
</div>
</div>
</article>
<article class="modal">
<div class="modal-inner">
<header class="modal-header">
<h2 class="modal-heading">Modal</h2>
<button type="button" class="modal-close">Close</button>
</header>
<div class="modal-content">
<!-- populate with other patterns -->
</div>
<footer class="modal-footer">
<button type="button" class="modal-button modal-button-cancel">Cancel</button>
<button type="button" class="modal-button modal-button-confirm">Confirm</button>
</footer>
</div>
</article>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment