Styleguide Example

s which are the feed items. 89 | ``` 90 | 91 | To describe the status of a set of rules, you should prefix the description with **Experimental** or **Deprecated**. 92 | 93 | **Experimental** indicates CSS rules that apply to experimental styling. This can be useful when testing out new designs before they launch (staff only), alternative layouts in A/B tests, or beta features. 94 | 95 | ```less 96 | // Experimental: An alternative signup button styling used in AB Test #195. 97 | ``` 98 | 99 | **Deprecated** indicates that the rule is slated for removal. Rules that are deprecated should not be used in future development. This description should explain what developers should do when encountering this style. 100 | 101 | ```less 102 | // Deprecated: Styling for legacy wikis. We'll drop support for these wikis on 103 | // July 13, 2007. 104 | ``` 105 | 106 | ## The modifiers section 107 | 108 | If the UI element you are documenting has multiple states or styles depending on added classes or pseudo-classes, you should document them in the modifiers section. 109 | 110 | ```less 111 | // :hover - Subtle hover highlight. 112 | // .stars-given - A highlight indicating you've already given a star. 113 | // .stars-given:hover - Subtle hover highlight on top of stars-given styling. 114 | // .disabled - Dims the button to indicate it cannot be used. 115 | ``` 116 | 117 | ## The styleguide section 118 | 119 | If the UI element you are documenting has an example in the styleguide, you should reference it using the "Styleguide [ref]" syntax. 120 | 121 | ```less 122 | // Styleguide 2.1.3. 123 | ``` 124 | 125 | References should be integer sections separated by periods. Each period denotes a hierarchy of the styleguide. Styleguide references can point to entire sections, a portion of the section, or a specific example. 126 | 127 | If there is no example, then you must note that there is no reference. 128 | 129 | ```less 130 | // No styleguide reference. 131 | ``` 132 | 133 | ## The markup section 134 | 135 | *Note: This section is unofficial, and only implemented in `kss-node`.* 136 | 137 | If you wish to include example HTML for the UI element you are documenting, you should include an additional paragraph with sample markup and prefix it with `Markup:`. You should also note the placement of modifier classes with `{$modifiers}`, like so: 138 | 139 | ```less 140 | // Buttons 141 | // 142 | // :hover - Highlight the button when hovering. 143 | // 144 | // Markup: 145 | // Link 146 | // 147 | // 148 | // Styleguide 2.1.3. 149 | ``` 150 | 151 | If you're using the `kss-node` module or CLI, make sure not to include any double line-breaks, as only the first paragraph prefixed with `Markup:` will be included. 152 | 153 | # Preprocessor Helper Documentation 154 | 155 | If you use a CSS preprocessor like SCSS or LESS, you should document all helper functions (sometimes called mixins). 156 | 157 | ```less 158 | // Creates a linear gradient background, from top to bottom. 159 | // 160 | // $start - The color hex at the top. 161 | // $end - The color hex at the bottom. 162 | // 163 | // Compatible in IE6+, Firefox 2+, Safari 4+. 164 | @mixin gradient($start, $end){ 165 | ... 166 | } 167 | ``` 168 | 169 | Each documentation block should have a description section, parameters section, and compatibility section. The description section follows the same guidelines as style documentation. 170 | 171 | ## The parameters section 172 | 173 | If the mixin takes parameters, you should document each parameter and describe what sort of input it expects (hex, number, etc). 174 | 175 | ```less 176 | // $start - The color hex at the top. 177 | // $end - The color hex at the bottom. 178 | ``` 179 | 180 | ## The compatibility section 181 | 182 | You must list out what browsers this helper method is compatible in. 183 | 184 | ```less 185 | // Compatible in IE6+, Firefox 2+, Safari 4+. 186 | ``` 187 | 188 | If you do not know the compatibility, you should state as such. 189 | 190 | ```less 191 | // Compatibility untested. 192 | ``` 193 | 194 | # Styleguide 195 | 196 | In order to fully take advantage of KSS, you should create a living styleguide. A living styleguide is a *part of your application* and should include all of the CSS, Javascript, and layout the rest of your application does. 197 | 198 | To get started quickly use the CLI tool, which supports custom templates too. If you're feeling game you can (and should) build it up from scratch using the module's API. 199 | 200 | Overall, keep in mind that styleguides should adapt to the application they are referencing and be easy to maintain and as automatic as possible. 201 | 202 | ## Organization 203 | 204 | The styleguide should be organized by numbered sections. These sections can go as deep as you like. Every element should have a numbered section to refer to. For example: 205 | 206 | 1. Buttons 207 | 1.1 Form Buttons 208 | 1.1.1 Generic form button 209 | 1.1.2 Special form button 210 | 1.2 Social buttons 211 | 1.3 Miscelaneous buttons 212 | 2. Form elements 213 | 2.1 Text fields 214 | 2.2 Radio and checkboxes 215 | 3. Text styling 216 | 4. Tables 217 | 4.1 Number tables 218 | 4.2 Diagram tables 219 | 220 | The goal here is to create an organizational structure that is flexible, but rigid enough to be machine processed and referenced inside of documentation. 221 | -------------------------------------------------------------------------------- /demo/styles.less: -------------------------------------------------------------------------------- 1 | // Modules 2 | // 3 | // Reusable elements that can be used across the site. 4 | // So far this just includes buttons. 5 | // 6 | // Styleguide 1. 7 | @import "./elements/buttons.less"; 8 | 9 | // Forms 10 | // 11 | // Covers styles used for forms, such as the `` and ` 82 |

<a href="#" class="button {$modifiers}">Link Button</a> 124 | <button class="button {$modifiers}">Button Element</button> 125 | <input type="button" class="button {$modifiers}" value="input[type='button']"/>

Styleguide

Forms

Text Input

2.1.1 Single-Line Text Boxes

2.1.2 Label/Textbox Pairs

Styleguide

{{reference}} {{header}}

{{header}}