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

Named Cascading Style Sheets Naming convention for semantic CSS


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


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
-active * .item-active
-idle * .item-idle
-hover * .item-hover
-touch * .item-touch
-small * .item-small
-medium * .item-medium
-large * .item-large
-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


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


Syntax: .wrapper-{type}

Prefix Tag Example
wrapper- * .wrapper-body


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