Merge pull request #20 from MrDinsdale/feature/unit-map-refactor

Feature/unit map refactor

CHANGELOG.md

@@ -0,0 +1,17 @@
+# V1.1.0
+
+## Improvements
+
+* Removed dependency on `$cactus-breakpoint-config` to list required breakpoint keys.
+* Streamlined unit gutter generation to avoid repetition.
+* Restructured objects to avoid nesting.
+* Included Normalize 5.0.
+* Updated README.
+* Updated LICENSE.
+* Included CHANGELOG.
+
+## Fixes
+
+* Corrected default `$cactus-unit-config` map.
+
+---

LICENSE.md

@@ -19,3 +19,25 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+Normalize.css License
+=====================
+
+Copyright (c) Nicolas Gallagher and Jonathan Neal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -17,13 +17,25 @@ Cactus has a suite of automated tests, to run:
 For linting run:
 `npm run lint`
 
-## Build
+## Building
 To build a static CSS version of Cactus run:
 `npm run build`
 
 
 ## Cactus Structure
-Cactus is structured acording to ITCSS, this allows separation of concerns and gives greater context for what each class is used for. For more information checkout this [blog post on ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture).
+Cactus is structured acording to ITCSS, this allows separation of concerns and gives greater context for what each class is used for. For more information checkout this [blog post on ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture). The framework is split up into the following categories:
+
+* **Settings** - Settings contains all of the configuration settings for Cactus. These should never be overwritten directly.
+
+* **Tools** - Tools contains functions and mixins required for Cactus.
+
+* **Generic** - Generic is used for any generic global styling, this should be avoided where possible.
+
+* **Elements** - Elements contains styling for HTML elements such as `<img>`.
+
+* **Objects** - Objects contains class-based styling for non-cosmetic design patterns such as containers and layout.
+
+* **Debug** - Debug is an optional set of styling which enables some debug styling to highlight incorrect grid usage.
 
 
 ## Cactus Classes
@@ -39,24 +51,32 @@ Cactus makes use of BEM like naming convention for classes making for far more r
 For more information have a look at [MindBEMding - Getting your head round BEM syntax](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) by Harry Roberts, it's a great read!
 
 ### Cactus wrapper
-The Wrapper element sets the max width `$cactus-wrapper-width` of the content and centers it on the page, by default this is 60em (960px).
+The Wrapper element sets the a max-width constraint. The wrapper widths are define in`$cactus-wrapper-config` which expects a map:
 
 ``` scss
-.o-cactus__w
+$cactus-wrapper-config: (
+  sizes: (
+    default: 48em,
+    large: 56em,
+    small: 40em
+  )
+);
 ```
 
-An optional wide modifier can be set `$cactus-wrapper-width-wide`, by default this is set to false.
+This will create the following classes:
 
 ``` scss
-.o-cactus__w--wide
+.o-cactus__w
+.o-cactus__w--large
+.o-cactus__w--small
 ```
 
 ### Cactus Group
-The Group element wraps Units, it also allows us to adjust the gutter on direct descendant `cactus__u` elements.
+The Group element wraps Units and adds essential margins and offsets to create the layouts. All immediately nested elements should be cactus unit classes.
 
 ``` scss
-.o-cactus__g                // Default gutter width set by $cactus-gutter, 32px default.
-.o-cactus__g--gutter-small  // Sets gutter to value of $cactus-gutter-small, 8px default.
+.o-cactus__g                // Default gutter width.
+.o-cactus__g--gutter-small  // Optional modifier for gutter width.
 .o-cactus__g--gutter-none   // Removes gutter.
 .o-cactus__g--reverse       // Reverse child unit elements.
 ```
@@ -88,6 +108,9 @@ The Unit defines the ratios of your columns as well as breakpoints where it will
 ## Cactus Grid Generator
 There have been some major changes to how the settings for Cactus work. It will take me a while to re-write the documentation to account for this and add better tools for extending however for now here's a quick summary
 
+### Cactus Wrapper Config
+The Cactus wrapper is an optional element which sets a maximum width constraint, by default this is centrally aligned in the page. You can define
+
 
 ### Cactus Unit Config
 Here we can define each of the breakpoints we want to generate unit classes for and specify what those units should be:
@@ -97,12 +120,12 @@ $cactus-unit-config: (
   default: (
     name: false,
     breakpoint: false,
-    units: $cactus-unit-ratio-default
+    units: (1 1, 1 2, 1 4, 3 4)
   ),
   medium: (
     name: m,
     breakpoint: 75em,
-    units: $cactus-unit-ratio-default
+    units: (1 1, 1 2, 1 3, 2 3)
   )
 );
 ```
@@ -111,28 +134,8 @@ Here we have two breakpoints, `default` and `medium`. Each comprises of:
 
 - **`name`** - The name which will be used for the class, for example giving a name of 'm' will result in a generated class of `.o-cactus__u--m-X`. Setting to `false` means this is the global breakpoint with no media query attached.
 - **`breakpoint`** - This is the width at which the breakpoint should apply and should be set in em's. A breakpoint of `50em` would mean these classes only effect when the screen width is below `800px` etc.
-- **`units`** - This should be set to a variable containing an array of fractions, for the correct format of these see below.
+- **`units`** - Units expects an array of space separated fractions, so `1 2` is the same as `1/2` or `50%`. This lets us tailor the exact unit widths we want to include.
 
-### Cactus Unit Ratios
-These are the unit ratios we set for the various breakpoints. They currently need to be contained with in separate variables as sass maps don't support nested arrays. The benefit of this is that it potentially DRYs up our code:
-
-``` scss
-$cactus-unit-ratio-default: 1 1, 1 2, 1 3, 2 3, 1 4, 3 4;
-```
-
-The unit ratios are essentially fractions so `1 2` is the same as `1/2` or `50%`. There is no limit to how many you can have although it is recommended that you only include the ones you need.
-
-### Cactus Breakpoint Config
-
-Here we set which of the breakpoints we want to include in our project. The values in here must be the same as the maps nested within `$cactus-unit-config`.
-
-``` scss
-$cactus-breakpoint-config: (
-  default,
-  medium,
-  small
-);
-```
 
 ### Using the generated class names
 The classes and breakpoints we have defined will be exported in the following format:
@@ -145,4 +148,11 @@ The classes and breakpoints we have defined will be exported in the following fo
 .o-cactus__u--m-2-3   // Three quarter width at medium breakpoint
 
 .o-cactus__u--s-1     // Full width at small breakpoint
-```
+```
+
+## Customising
+To customise the default grid settings include your own overrides file and include before Cactus. You can include your own `$cactus-unit-config` or `$cactus-gutter-config` etc as your project requires. To see what options are available check `settings/_grid.scss`.
+
+## License
+
+See the [LICENSE file](https://github.com/MrDinsdale/Cactus/blob/master/LICENSE.md) for license text and copywrite information.

generic/_all.scss

@@ -1 +1,2 @@
+@import 'normalize';
 @import 'globals';