Written By Kuol Kuol
- 1. Folder Structure
- 2. File Structure
- Documentation Specifications
- 4. Style Guide Format
- 5. Useful Links
This project uses the architecture known as the 7–1 pattern (7 folders, 1 file), is a widely-adopted structure that serves as a basis for large projects. All the partials are organised into 7 different folders, and a single file sits at the root level (named main.scss) to handle the imports — which is the file you compile into CSS.
Here’s a sample 7–1 directory structure, I’ve included some examples of files that would sit inside of each folder:
sass/
|
|– helpers
| |– _variables.scss // Sass Variables
| |– _functions.scss // Sass Functions
| |– _mixins.scss // Sass Mixins
| |– _all.scss // Import File
|
|– base/
| |– _reset.scss // Resets CSS
| |– _typography.scss // Typography rules
| |– _all.scss // Import File
|
|– components
| |– _static/
| | |– _header.scss // Header
| | |– _footer.scss // Footer
| | |– _all.scss // Import File
|
| |– _variable.scss/
| | |– _buttons.scss // Buttons
| | |– _slider.scss // Sliders
| | |– _all.scss // Import File
|
|– layout/
| |– _navigation.scss // Navigation
| |– _grid.scss // Grid system
| |– _header.scss // Header
| |– _footer.scss // Footer
| |– _sidebar.scss // Sidebar
| |– _forms.scss // Forms
| |– _all.scss // Import File
|
|– pages/
| |– _home.scss // Home specific styles
| |– _about.scss // About specific styles
| |– _contact.scss // Contact specific styles
| |– _all.scss // Import File
|
|– themes/
| |– _theme.scss // Default theme
| |– _admin.scss // Admin theme
| |– _all.scss // Import File
|
|– vendors/
| |– _bootstrap.scss // Bootstrap
| |– _jquery-ui.scss // jQuery UI
| |– _all.scss // Import File
|
`– main.scss // Main Sass file (Imports every all.scss files)
These files don’t output any CSS when compiled, they are to be used by the other files to create custom styles. This folder holds Sass tools, helper files, variables, and config files.
This folder contains the boilerplate code which is used throughout the project such as css resets and typographic rules.
Holds all of the styles for buttons, carousels, sliders, and similar page components (think widgets). Your project will typically contain a lot of component files — as the whole site/app should be mostly composed of small modules.
-
Holds all the styles for modules that have multiple varients. Example: big and small buttons with different colors.
-
Holds all the styles for modules that never change and have only one version. Example: Navigation bars, Sidebars, and Footers.
Contains all styles involved with the macro layout of the project which includes the grid system.
Contains any styles specific to individual pages. For example it’s not uncommon for the home page of your site to require page specific styles that no other page receives.
Hold files that create project specific themes. For example, if sections of the site contain alternate color schemes for night and day mode settings for website readers.
Contains all third party css and sass code from external libraries and frameworks. Example: Normalize.css.
Located in the root directory, this file handles the imports of all the partials. This is done by importing every all.scss file in every folder.
Handles the imports for partials in specific folders. These files are to be imported into te main.scss file.
KSS is a documentation specification and style guide format. It attempts to provide a methodology for writing maintainable, documented CSS within a team. Most developers use it due to its popularity, expressiveness, and simplicity.
The KSS format is human-readable and machine-parsable. Therefore, it is intended to help automate the creation of a living style guide.
Each KSS documentation block consists of three parts: a description of what the element does or looks like, a list of modifier classes or pseudo-classes and how they modify the element, and a reference to the element’s position in the styleguide.
The basic format for KSS documentation can be best explained in an example:
// A button suitable for giving stars to someone.
//
// :hover - Subtle hover highlight.
// .stars-given - A highlight indicating you’ve already given a star.
// .stars-given:hover - Subtle hover highlight on top of stars-given styling.
// .disabled - Dims the button to indicate it cannot be used.
//
// Styleguide 2.1.3.
a.button.star{
…
&.star-given{
…
}
&.disabled{
…
}
}
- Install kss-node and michelangelo theme project dependency:
npm install --save-dev kss michelangelo
- Verify that it was installed by running
./node_modules/.bin/kss --version
- Create a file named kss-config.json to configure our KSS settings.
{
"title": "Title of the Style Guide",
// Source tells KSS where the CSS, Sass, or SCSS is that it should parse for documentation comments.
// Here we are assuming your sass is in a directory at the root level of your project.
"source": "sass/",
// Destination tells KSS where to compile your style guide to.
"destination": "styleguide/",
// Builder tells KSS where to look for a theme.
// If you aren't using michelangelo, you don't need this.
"builder": "node_modules/michelangelo/kss_styleguide/custom-template/",
// CSS gives KSS the path to your CSS, so it can pull your styles into the style guide.
// The path needs to be relative to your style guide destination.
// Here, our style guide is in /styleguide and our compiled css is at our project root.
"css": [
"../main.css"
],
// If you want to include any javascript files, add this block, with the path to your javascript file.
// Also relative to your style guide destination.
// Optional.
"js" : [
"../bundle.js"
]
}
- Compile style guide by running:
./node_modules/.bin/kss --config kss-config.json
- Or add a script to the scripts block in your
package.jsonand npm run kss:
"scripts": {
"kss": "kss --config kss-config.json"
},
- We'll use the onchange package. First install it:
install onchange --save-dev
- Then add a new script in our scripts object:
"scripts": {
"watch": "onchange 'sass/**/*.sass' -- npm run kss",
"kss": "kss --config kss-config.json"
},
All documentation for helper functions should have a description section, parameters section, and compatibility section. The description section follows the same guidelines as style documentation.
Example of mixin documentation:
// Creates a linear gradient background, from top to bottom.
//
// $start - The color hex at the top.
// $end - The color hex at the bottom.
//
// Compatible in IE6+, Firefox 2+, Safari 4+.
@mixin gradient($start, $end){
…
}
All SASS files should include indentation and spacing to make code more readable.
#nav {
li {
color:black;
}
}
All Pseudo-Selectors should follow the LoVeHAte ordering model:
a:link {
color:black;
}
a:visited {
color:blue;
}
a:hover {
color:red;
}
a:active {
color:purple;
}
All Short Hand Rules should follow the TRouBLed ordering model:
margin-top:10px;
margin-right:20px;
margin-bottom:30px;
margin-left:40px;
All properties should be sorted in alphabetical order
#alphabetical-order {
background:#000;
color:black;
z-index:9;
}
All z-index rules should be grouped together in one SASS file.
SASS files should include styles for mobile, tablet and desktop screens.