Code conventions

Guidelines for HTML, CSS, and JS with Orchid

Code design principles

Orchid is designed according to these principles for HTML and CSS:

HTML design principles

  • Use semantic markup. That means using the <button> tag rather than <div class="btn"> when a button is required, an <h3> tag when a third-level heading is required, and so on.
  • Strive for clarity. Developers should be able to decipher what’s going on with the markup at a glance. That means avoiding cryptic abbreviations and nicknames, using proper indenting & spacing, and inserting clear comments.
  • Accessibility. Markup should be accessible. Make use of ARIA role attributes and follow helpful accessibility guidelines.

CSS design principles

  • Make it modular. Orchid is modular in every way, which very much applies to the way CSS is written. There should be clear separation between components.
  • Legibility is key. Developers should be able to understand CSS code at a glance and understand the purpose of any given selector.
  • Clarity trumps succinctness. Orchid may sometimes seem verbose, but it delivers clarity and reslience in exchange. Keeping Orchid’s CSS legible and scalable means sacrificing a shorter syntax.
  • Keep things flat. Long selector strings should be avoided wherever possible in order to keep CSS as DOM-independent and modular as possible.

CSS naming conventions

Orchid follows a BEM-like syntax, extending it further to follow more of BEMIT-like conventions.

BEM syntax

BEM stands for “Block Element Modifier”. Here’s a breakdown of what that means:

  • Block is the primary component block, such as .c-card or .c-alert.
  • Element is a child of the primary block, such as .c-card__title.
  • Modifier is a variation of a component style, such as .c-alert--error.

Orchid extends BEM’s conventions to create even more explicit, encapsulated class names.

Global namespace

Orchid uses a global namespace of orc- prefix (for “Orchid”) to all styles that come from Orchid. This is done to:

  • Avoid naming collisions with code coming from other sources
  • Clarify the source of the code, distinguishing Orchid’s markup/styles from code coming from other libraries and platforms.

Class prefixes

Orchid uses class prefixes to provide additional clarity to the job a given class plays. Orchid uses the following class prefix conventions:

  • c- for UI components, such as .c-card
  • l- for layout-related styles, such as .l-grid__item
  • u- for utilities, such as .u-clearfix
  • is- and has- for specific states, such as .is-active
  • js- for targeting JavaScript-specific functionality, such as .js-modal-window

Putting it all together: anatomy of a class

Combining BEM conventions and category prefixes results in an explicit (and yes, verbose) class string that allows developers to deduce what job it does.

Let’s take a look at the following example:

.c-btn--secondary

  • c- is the category of class, which in this case c- means “component”
  • btn is the block name (“Block” being the “B” in BEM)
  • --secondary is a modifier, indicating a stylistic variation of the block (“Modifier” being the “M” in BEM)

Here’s another example:

.l-grid__item

  • l- is the category of class, which in this case l- means “layout”
  • grid is the block name
  • __item is an element, indicating that this is a child of the block (“Element” being the “E” in BEM)

JavaScript frameworks and Orchid

Orchid strives to be platform, library, and technology agnostic. With this in mind, and because many different JavaScript tools and libraries are utilized for Cosmopolitan apps and sites, the design system doesn’t tether itself to any one JavaScript framework or library.

JS classes

To create a clear separation between style and behavior, Orchid uses js- class prefixes for all JavaScript behavior.

Take the following example:

<button class="c-btn js-nav-trigger">Menu</button>

The class c-btn provide the button styles, while the class js-nav-trigger provides a JavaScript hook for the developer to target in their JavaScript code.

Here’s another example:

<a href="#1" class="c-accordion__title js-accordion-trigger">Accordion Title</a>
<div id="1" class="c-accordion__body js-accordion-panel">
	...
</div>

The classes c-accordion__title and c-accordion__body are used to style the accordion elements. The classes js-accordion-trigger and js-accordion-panel are used by JavaScript to provide the accordion’s open/close functionality.

Developers must never target non-js- classes to control behavior. And CSS developers must never use js- classes to provide style for components.