This styleguide setup and builder has the following features:
- Color Swatches
- Pattern Markers
From within the /src/styleguide folder
Run npm install
to get up and running. You can then run the following
to build your styleguide:
npm run generate-styleguide
Run npm run generate-styleguide swatches
to also generate color
swatches.
This will compile the styleguide's CSS and create the styleguide pages
based on comments found in files in the /src/styles/
folder and the
markup HTML found in the src/styleguide/pattern-markup/
folder.
Odds are good this won't be needed regularly, but in the event you need
to rebuild the styleguide-specific theme CSS, run
npm run generate-styleguide compile-css
.
Run npm run generate-styleguide complete
to generate the styleguide
while running all optional build tasks outlined above.
While in the src/styleguide/ folder, running npm start
will start a
local server to aid in review, which is recommended. This will get
around quirks that can crop up with font rendering outside of a server
setting.
KSS uses a slight variation of markdown to populate Handlebars templates and create your styleguide. This markdown should be included in relevant CSS files, and provides inline documentation of your CSS as a nice byproduct. Detailed examples can be found in the KSS Node project repo.
If you find your example markup extends beyond four or five lines, it's best to move it into a separate HTML file that KSS-node will reference, rather than kept inside your Sass or CSS file. KSS-node crawls all folders inside the styles folder, so if it finds any template names referenced in your CSS they will be included in their correct position.
Also, if you don't want your markdown to appear in your final compiled
CSS (and ideally you shouldn't), remember to use //
to comment rather
than /* */
so that the markdown will be omitted.
The styleguide's index page is rendered from the markdown file
homepage.md in the src/styleguide/project-assets
folder.
Caxy's Zaba theme can display the current breakpoint in the upper
righthand corner. To enable this, add a breakpoints object to your
kss-config.json
file like so:
{
"source": [
...
],
"breakpoints": {
"micro": "20.3125rem",
"small": "42.5rem",
"medium": "57.5rem",
"large": "75rem",
"xlarge": "88.75rem",
"xxlarge": "100rem"
}
}
Caxy's Zaba theme builder adds two pattern markers, defined with custom kss values:
PatternType
: Pattern TypeStatus
: Pattern Status (not active by default)
The are added to your markup in the following way:
// Pattern Name
//
// Pattern description...
//
// PatternType: atom
//
// Status: ready
//
// Styleguide 3.1.1
Marker values should be lowercase.
Because not all styleguide projects will be iterative, pattern status markers are not active by default. For situations where patterns will need some kind of indicator of their production-readiness, these status markers can be activated.
To activate pattern status markers for your project, set
hide_pattern_status
to false
in the config/kss-config.json file.
This marker has three values available:
development
: In Development (default)review
: In Reviewready
: Production Ready
Pattern status markers are aggressively applied in an effort to encourage mindful documentation. If no status is set for a given pattern, it will automatically display as In Development.
Pattern types follow Brad Frost's Atomic Design methodology.
Use of this marker is entirely optional. If no PatternType
value is
found, no marker displays.
To utilize these markers, the following values are available:
atom
molecule
organism
template
page
Color swatches for Zaba are generated using a specially named map in your project's Sass files.
To populate your project's color swatches, do the following:
In your styleguide-specific Sass file, create sets of colors and group them as follows:
$color-set-1 (
primary: $color-primary,
secondary: $color-secondary
);
Please note: Referenced .scss files need to have comments in
multiline (/* */
, not single line (//
) format, and cannot depend
on @import
for values.
Add your created color sets to a Sass map and note the name (the
styleguide will reference $kss-color-sets
by default). For the keys,
use names you would like to have appear in the styleguide.
$kss-color-sets: (
"Brand Colors": $color-set-1,
"Font Colors": $color-set-2,
);
Please note: At this time, special characters are not allowed.
In src/styleguide/js/generate-styleguide.js
, update the following
object with information for your project:
const colorOptions = {
variableFile : '../styles/example-colors.scss', // File where your $kss-color-sets map is.
swatchColorSetName : '$kss-color-sets', // Default value
markupPath : './pattern-markup/' // Path to your project's styleguide markup files
};