Naming convention for semantic CSS
JavaScript
Latest commit bdc8c37 Aug 22, 2016 @redaxmedia Update build

README.md

Named Cascading Style Sheets Naming convention for semantic CSS

NCSS

NCSS is a naming convention for semantic CSS. Get rid of reading your HTML again and again to find out what elements, tags and sections are affected.

Build Status Dependency Status Dependency Status GitHub Stats

Why

Massive CSS on larger projects used to cause issues:

  • Teamwork without uniform conventions
  • Missing context to the project's layout and structure
  • Big ball of mud instead of modularization
  • Lack of inline documentation
  • No possibility for automated validation

Getting started

There is no specification the use hyphen, underscore or camelcase for your classnames - it is upon your personal preference, but we recommended to use the language's native hyphen style.

Named Cascading Style Sheets are divided into:

Structural classes

Structural classes provide a semantic context for the underlaying elements and are preferably utilized to define a layout.

Syntax: .{context} and .{context}-{name}

Tag Example
article .content
address .address
body .body
footer .footer
header .header
main .main
nav .navigation
section .section
side .sidebar

Component classes

Component classes provide a group context for the underlaying elements and are preferably utilized to define a working unit.

Syntax: .component-{name}

Prefix Tag Example
component- * .component-accordion

Type classes

Type classes are the foundation to write re-usable, modular and semantic CSS - tell the reader what kind of elements, tags and sections are affected. Keep in mind that structural tags are rather unsuitable to contain a type prefix.

Syntax: .{type} and .{type}-{context}

Prefix Tag Example
audio- audio, object .audio-content
box- blockquote, div .box-content
break- hr .break-content
button- a, button .button-content
caption- caption .caption-content
code- code, pre .code-content
col- td, th .col-content
data- datalist .data-content
field- input, select, textarea .field-content
form- form .form-content
frame- iframe .frame-content
image- img, object, picture, svg .image-content
item- dd, dt, li .item-content
label- label .label-content
legend- legend .legend-content
link- a .link-content
list- dl, ol, ul .list-content
modal- div .modal-content
overlay- div .overlay-content
set- fieldset .set-content
shape- cicle, path, rect, symbol, use .shape-content
table- table .table-content
row- tr .row-content
text- em, small, span, strong, p .text-content
title- h1, h2, h3, h4, h5, h6 .title-content
video- object, video .video-content
wrapper- * .wrapper-content

Modifier classes

There is no limitation to extend your type classes with individual state, size and position modifier. Proper handling of context and type should prevent the need of adjoining classes.

Syntax: .{type}-{state} and .{type}-{context}-{state}

Syntax: .{type}-{size} and .{type}-{context}-{size}

Syntax: .{type}-{position} and .{type}-{context}-{position}

Suffix Tag Example
State
-active * .item-active
-idle * .item-idle
-hover * .item-hover
-touch * .item-touch
Size
-small * .item-small
-medium * .item-medium
-large * .item-large
Position
-first * .item-first
-second * .item-second
-third * .item-third
-last * .item-last
-odd * .item-odd
-even * .item-even

Functional classes

Functional classes using pure CSS are marked with the is, no, has and fn prefix. Javascript enhanced and therefore re-usable classes on the other hand can be identified by the js prefix. Each of them should never have styles for painting, use an additional type class for this purpose.

Syntax: .is-{state}, .has-{context}, .no-{feature} and .fn-{action}

Syntax: .js-{action} and .js-{context}

Prefix Tag Example
is- * .is-active
has- * .has-tooltip
no- * .no-webgl
fn- * .fn-clearfix
js- * .js-click

Namespaces

Consider to pick a unique namespace once you provide a framework to third party applications or generally want to prevent naming conflicts inside your project. Never mix up namespaces and follow the pretended naming of third party components.

Syntax: .{namespace}-{type} and .{namespace}-{context}

Prefix Tag Example
{namespace}- * .fb-main

Exceptions

Syntax: .wrapper-{type}

Prefix Tag Example
wrapper- * .wrapper-body

Conclusion

The goal of NCSS is to provide semantic information while reading CSS:

  • What kind of elements, tags and sections are affected
  • What is the relation and inheritance of one class to another
  • Where is the most accurate place to add new declarations

Further reading