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.
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;
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 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 { /* ... */ }
}
Special atoms are @icons, and meant are glyphs of an icon font.
If you are using an automated process to generate the icon font, include the annotations directly into the source code template for the resulting stylesheet file. This way, the icons will automatically appear in the style guide.
/**
* @icon .SG-ico--logo
* @markup
* <i class="SG-ico SG-ico--logo"></i>
*/
.SG-ico--logo:before {
content: "\EA01"
}
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 {
/* ... */
}
}
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 { /* ... */ }