Styleguide   •   Documentation   •   Wiki

Style guide de HIDDEN MARKET réalisé avec Nucleus et basé sur la logique Atomic Design.

Quick start

A more detailed installation instruction can be found here.

Install globally (prefered):

npm install -g nucleus-styleguide

Inside your project root folder, create a configuration with:

nucleus init

Run nucleus:

nucleus

Open http://YOUR_LOCAL_DEV_URL/styleguide .

General rules for annotations

The value of the annotation may be a single line, or multiple lines indented by at least one space (starting on a new line).

/**
 * @atom Button
 * @section Navigation > Buttons
 * @description
 *  Buttons for various purposes.
 * @modifiers
 *  .button--alert an alert button
 * @markup
 *   <button class="button">A button</button>
 *   <button class="button button--alert">
 *     An alert button
 *   </button>
 */
.button {
 /* ... */
 &.button--alert { /* ... */ }
}

If no @section is set, it will be set to "Other". To nest sections, separate the levels by ">" like shown above. In addition to @section and @description, some element types have more annotations available or even a short version to define then.

For every entity type besides @nuclide, @mixin and @color, the @markup annotation is available. This is where you should provide the minimal HTML to use that element, which is also used to generate the preview of the element.

Quarks

Nuclides are parts of the stylesheet source that are not directly useable on their own. This could be mixins, variables like colors and sizes, or settings.

To mark a variable or mixin as a nuclide, annotate it with the @nuclide tag, followed by the name of the nuclide. For basic nuclides, only @description and @section are valid annotations.

/**
 * The relative path to the image assets folder.
 *
 * @nuclide Image-Folder
 * @section Config > Paths
 */
$config--image-folder: "../images";

Special nuclides are @color and @mixin.

Colors

A @color often does not need any more information, that's why you may also write it as a one-line annotation.

/**
 * A red color variable.
 *
 * @color
 * @section Message Colors
 */
$color--red: #F00;

/** @color Solid black */
$color: #000;

Mixins

For @mixin, the @markup annotation does not make much sense, so it becomes @example. Also, you should describe the parameters (and what they are meant for) with @param. Nucleus should automatically recognize if a mixin parameter is optional or not.

/**
 * Put rounded borders around the element
 * and a border color.
 *
 * @mixin
 * @section Style Mixins
 * @param $radius This could be single line ...
 * @param $color
 *  Or multi-line, you decide!
 * @example
 *  @include brc(3px);
 *  @include brc(3px, $color--red);
 */
@mixin brc($radius, $color = '#333') {
  /* ... */
}

Atoms

Atoms are the very basic elements of the stylesheet. Imagine every single-class element or selector rules as an atom. Examples are buttons, links, headlines, inputs ... you get it, right?

To mark a variable or mixin as an atom, annotate it with the @atom tag, followed by the name of the component.

/**
 * @atom Button
 * @section Navigation > Buttons
 * @modifiers
 *  .button--alert an alert button
 * @markup
 *  <button class="button">
 *    A button
 *  </button>
 *  <button class="button button--alert">
 *    An alert button
 *  </button>
 */
.button {
 /* ... */
 &.button--alert { /* ... */ }
}

Molecules

Molecules consist of one or more nested rules, but each of them is not more than an atom. For example, using icons or buttons in molecules is valid, but using other molecules is not.

To mark an element as molecule, annotate it with the @molecule tag, followed by the name of the component.

/**
 * Buttons with icons and text or icons only.
 *
 * @molecule Icon Buttons
 * @markup
 *  <div class="SG-button">
 *    <i class="SG-ico SG-ico--question"></i>
 *  </div>
 *  <div class="SG-button SG-button--ico">
 *    <i class="SG-ico SG-ico--question"></i>
 *    With text
 *  </div>
 */
.SG-button {
  .SG-ico {
    /* ... */
  }

  &.SG-button--ico .SG-ico {
    /* ... */
  }
}

Organisms

Structures are the most complex types. They may even consist of multiple molecules or other structures again.

/**
 * Header bar with logo, navigation, and tool icons at the top of the page.
 * Note: This is just a minified example.
 *
 * @structure Header
 * @markup
 *  <div class="SG-header">
 *    <div class="SG-logo">
 *      <div class="SG-ico SG-ico--logo SG-ico-lg"></div>
 *      <div class="SG-logo__name">Nucleus</div>
 *    </div>
 *    <ul class="SG-nav">
 *      <li>
 *        <a href="nuclides.html" class="SG-nav__item">Nuclides</a>
 *      </li>
 *      <li>
 *        <a href="atoms.html" class="SG-nav__item">Atoms</a>
 *      </li>
 *    </ul>
 *    <ul class="SG-nav-icons">
 *      <!-- ... -->
 *    </ul>
 *  </div>
 */
.SG-header { /* ... */ }

Modifier

For listing variations of blocks/elements @modifiers are available to use on certain elements.

For example, if you have modifiers for an element that you need to document, but don't necessarily want to display in the @markup.

/**
 *
 *
 * @atom Button
 * @modifiers
 *  .btn--primary for use in positive flows
 *  .btn--secondary for use in alternative flows
 * @markup
 *  ...
 */
.btn {
  ...
  &--primary { /* ... */ }
  &--secondary { /* ... */ }
}