|
1 | 1 | # avalanche |
2 | | -avalanche is a modular front-end framework which can be extended with npm |
3 | | -packages. The goal is to provide a workflow to manage the complexity of big |
4 | | -front-end projects. |
| 2 | +[](https://travis-ci.org/avalanchesass/avalanche) |
5 | 3 |
|
6 | | -## Getting started |
7 | | -### Quick start |
8 | | -- Install [npm](https://docs.npmjs.com/getting-started/installing-node) and |
9 | | -[gulp](https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md) on |
10 | | -your system (if not already installed). |
11 | | -- Install avalanche globally `npm install -g avalanchesass`. |
12 | | -- Run `avalanchesass --template="project" --name="Your project name"` to create |
13 | | -a new avalanche project in the current directory. |
14 | | -- Run `npm install` inside your newly created project directory. |
15 | | -- Run `gulp` to start the build process. |
| 4 | +avalanche establishes the foundation for a package based CSS workflow. Heavy weight CSS toolkits often stay in your way when creating unique looking experiences or they lead to a rather bland design. But you don't have to reinvent the wheel for every new project either. avalanche provides building blocks for you to handpick and integrate into your workflow. |
16 | 5 |
|
17 | | -### Extend avalanche |
18 | | -The high modularity of avalanche requires that every part of the system is a |
19 | | -distinct package. There are multiple package types: |
| 6 | +## Get started |
| 7 | +avalanche comes with a CLI to kickstart new projects: |
20 | 8 |
|
21 | | -- **Function:** custom SASS functions |
22 | | -- **Base:** base styles like typography and other global default styles (mostly |
23 | | -unclassed HTML elements) |
24 | | -- **Object:** non-cosmetic styles (such as the famous media object) |
25 | | -- **Component:** concrete, implementation-specific piece of UI |
26 | | -- **Utility:** utility classes that do specific things (for example clearfix) |
27 | | - |
28 | | -You can find various available packages on |
29 | | -[npm](https://www.npmjs.com/browse/keyword/avalanchesass-package) |
30 | | -To extend your installation with a preconfigured package open your |
31 | | -`package.json` file, add the package to your *dependencies* and run |
32 | | -`npm install` afterwards. |
33 | | - |
34 | | -```json |
35 | | -"dependencies": { |
36 | | - "avalanchesass_base_default": "^3.0.0", |
37 | | - "avalanchesass_base_form": "^3.0.0", |
38 | | - "avalanchesass_base_typography": "^3.0.0", |
39 | | - "avalanchesass_object_media": "^3.0.0", |
40 | | - "normalize-scss": "^4.0.3" |
41 | | -} |
42 | | -``` |
43 | | - |
44 | | -## Working with avalanche |
45 | | -### Extend packages |
46 | | -If you wan’t to make changes to a class defined by a package it is recommended |
47 | | -to create a custom package with the name `_PACKAGE_NAME_extend.scss` in the scss |
48 | | -directory of your project. |
49 | | - |
50 | | -#### Example |
51 | | -Extending the `.c-button` class of the button component: |
52 | | - |
53 | | -- Create a file `_button_extend.scss` in `scss/component`. |
54 | | -- Define the `.c-button` class and override or change it’s properties. |
55 | | -- You can also remove properties by setting their value to `initial` and adding |
56 | | -a `/*!remove*/` comment at the end of the line. |
57 | | - |
58 | | -```scss |
59 | | -.c-button { |
60 | | - padding: initial;/*!remove*/ |
61 | | - text-transform: uppercase; |
62 | | -} |
| 9 | +```bash |
| 10 | +# Install the avalanche CLI. |
| 11 | +npm install @avalanche/cli -g |
| 12 | +# Create a new project with the name "Your Project Name". |
| 13 | +avalanche "Your Project Name" |
63 | 14 | ``` |
64 | 15 |
|
65 | | -**Attention:** removing properties and merging extended classes, will only |
66 | | -happen in the minified version of the CSS code. But the styling of your site |
67 | | -will be the same: setting a property value to `initial` has the same effect as |
68 | | -removing the property from the original class. Extending the original class by |
69 | | -defining it a second time, uses the default cascading behavior of CSS. |
70 | | - |
71 | | -### Override package variables |
72 | | -Most packages define there own default variables which you can override to |
73 | | -change the CSS output. There are two ways how to override variables of external |
74 | | -and custom packages: |
75 | | - |
76 | | -1. Similar to the extending of packages, you can create a separate file in which |
77 | | -you define the variables you want to override (for example |
78 | | -`_button_variable.scss`). |
79 | | -2. If you prefer to have one big file with all the variables inside, you can |
80 | | -also override package variables inside the `_variable.scss` file in your |
81 | | -projects `scss` directory. |
82 | | - |
83 | | -### CLI |
84 | | -`avalanchesass --template="" [--type=""] [--name=""] [--path=""]` |
85 | | - |
86 | | -#### Options |
87 | | -- `--template` *mandatory* |
88 | | - possible values: project | package | package-custom |
89 | | -- `--type` *optional* |
90 | | - possible values: Function | Base | Object | Component | Utility |
91 | | - default value: Component |
92 | | -- `--name` *optional* |
93 | | - possible values: "Your Project Name" |
94 | | - default value: "Avalanche Project" |
95 | | -- `--path` *optional* |
96 | | - possible values: /path/to/somewhere |
97 | | - default value: current working directory |
98 | | - |
99 | | -#### Examples |
100 | | -**Create a project** |
101 | | -`avalanchesass --template="project" --name="Project Name"` |
102 | | - |
103 | | -**Create a `Component` package** |
104 | | -`avalanchesass --template="package" --type="Component" --name="Package Name"` |
105 | | - |
106 | | -**Create a custom `Object` package** *assuming you are in the project diretory* |
107 | | -`avalanchesass --template="package-custom" --type="Object" --name="Package Name" --path="scss/object"` |
108 | | - |
109 | | -### BEM |
110 | | -avalanche uses the [BEM syntax](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/). |
111 | | -To make the meaning of the classes more transparent every BEM class name is |
112 | | -[namespaced](http://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/). |
113 | | -The BEM syntax helps to prevent [side effects in CSS](http://philipwalton.com/articles/side-effects-in-css/) |
114 | | -and the informative nature of the naming convention makes it ideal for teams and |
115 | | -larger projects. |
116 | | - |
117 | | -```css |
118 | | -.c-block {} |
119 | | -.c-block__element {} |
120 | | -.c-block--modifier {} |
| 16 | +avalanche is flexible in the way you can use it – it is also very easy to integrate avalanche packages into your existing project. [Learn more about how to use avalanche](https://avalanche.oberlehner.net/get-started/). |
121 | 17 |
|
122 | | -.c-menu {} |
123 | | -.c-menu__link {} |
124 | | -.c-menu--horizontal {} |
125 | | -``` |
126 | | - |
127 | | -### Style guide |
128 | | -avalanche uses [mdcss](https://github.com/jonathantneal/mdcss) to automatically |
129 | | -generate a style guide from CSS comments in markdown syntax |
130 | | -([avalanche style guide DEMO](http://avalanche.oberlehner.net)). |
131 | | - |
132 | | -Please follow the [official mdcss documentation](https://github.com/jonathantneal/mdcss#writing-documentation) |
133 | | -on how to format comments in your SCSS code for the style guide. |
134 | | - |
135 | | -To generate the style guide run `gulp style_guide`. You can also run |
136 | | -`gulp watch:style_guide` instead of the default `gulp` task to start the build |
137 | | -process. This automatically generates the style guide on every change you make |
138 | | -to your code base. |
139 | | - |
140 | | -### CSS extraction |
141 | | -[HTTP/2](https://en.wikipedia.org/wiki/HTTP/2) is coming and changes the way |
142 | | -[how we should build websites](https://mattwilcox.net/web-development/http2-for-front-end-web-developers). |
143 | | -With HTTP/2 it can be faster to load multiple small files (but only those which |
144 | | -are really needed) instead of one big file (with a potential overhead). Example: |
145 | | -the pager component isn’t used on most of your pages but the styles are loaded |
146 | | -on every request because they are concatenated into one big file. |
147 | | - |
148 | | -With CSS extraction you can split your styles into multiple separate CSS files. |
149 | | -This makes it possible to load just the styles you need. Amongst other things |
150 | | -there are the following advantages using this technique: |
151 | | - |
152 | | -- Increased cache granularity (avoids invalidating a whole sprite or |
153 | | -concatenated bundle when just a single part changes) |
154 | | -- Parallel downloading of files that before were bundled into one file |
155 | | -- Less energy/memory usage in the client |
156 | | - |
157 | | -By default every avalanche package is prepared for CSS extraction. |
158 | | -Run `gulp styles:extract` to create the CSS files - you can find them in |
159 | | -`dist-extract`. Or you can start a watch task with CSS extraction enabled: |
160 | | -`gulp watch:extract`. |
161 | | - |
162 | | -To make your custom packages CSS extraction ready, you have to add special |
163 | | -placeholder comments. |
164 | | - |
165 | | -```css |
166 | | -/* extract component_PACKAGE_NAME.css */ |
167 | | -.c-PACKAGE_NAME { … } |
168 | | -/* end extract component_PACKAGE_NAME.css */ |
169 | | -``` |
170 | | - |
171 | | -To prevent naming collisions it is recommended to add the package type as a |
172 | | -prefix to the name of the desired resulting CSS file. If you define two or more |
173 | | -extraction sections with the same name, those are combined into one file. |
174 | | - |
175 | | -It is recommended to also add placeholder comments for the package type. Because |
176 | | -extraction sections with the same name are combined you end up with separate |
177 | | -files per package type. |
178 | | - |
179 | | -```css |
180 | | -/* extract component.css */ |
181 | | -/* extract component_PACKAGE_NAME.css */ |
182 | | -.c-PACKAGE_NAME { … } |
183 | | -/* end extract component_PACKAGE_NAME.css */ |
184 | | -/* end extract component.css */ |
185 | | -``` |
| 18 | +## Testing |
| 19 | +- Test all packages at once: `npm test` |
| 20 | +- Test a specific package: `npm test -- -p PACKAGE-NAME` |
186 | 21 |
|
187 | 22 | ## About |
188 | 23 | ### Author |
189 | 24 | Markus Oberlehner |
190 | | -Twitter: https://twitter.com/MaOberlehner |
| 25 | +Twitter: https://twitter.com/MaOberlehner |
| 26 | +PayPal.me: https://paypal.me/maoberlehner |
191 | 27 |
|
192 | 28 | ### License |
193 | | -GPL v2 (http://www.gnu.org/licenses/gpl-2.0.html) |
| 29 | +MIT |
0 commit comments