compass-lucid-grid 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -1,24 +1,28 @@
1
1
  #Lucid: A _smarter_ CSS grid for Compass
2
2
 
3
- ###Philosophy and Killer Features
3
+ ###Philosophy
4
4
 
5
- CSS grids make web development easier... except when they don't.
5
+ CSS grids make web development easier... except when they don't. Wrapping `<div>`s, `.alpha` `.omega` madness, and fighting with gutters to get layouts aligned... These are the compromises that developers are forced live with.
6
6
 
7
- Wrapping `<div>`s, `.alpha` `.omega` madness, and fighting with gutters to get layouts aligned... These are the compromises that developers are forced live with.
7
+ Lucid is an effort to make CSS grids _sane_ again by taking full advantage of [SASS](http://sass-lang.com/) and [Compass](http://compass-style.org/).
8
8
 
9
- But NOT anymore. Lucid makes full use of [SASS](http://sass-lang.com/) and [Compass](http://compass-style.org/) in order to make CSS grids sane again.
9
+ ###The Basics
10
10
 
11
- Not only does it match other grids in functionality, but it also comes with a handful of unique features:
11
+ * Configure grid dimensions / columns instantly through variables
12
+ * Fixed width (`px` based) for finer control
13
+ * Tested in IE6+, Chrome, FF
12
14
 
13
- * Adjust grid dimensions / number of columns instantly through variables (as with all SASS grids)
14
- * Add borders and padding _directly to your grid elements_ without using nested `<div>`s
15
+ ###The Specifics
16
+
17
+ * Add borders and padding _directly to your grid elements_ without using nested `<div>`s or ugly overrides
15
18
  * Use "gutterless" grid elements for nesting and precise styling
16
- * Cater to multiple screen widths by reconfiguring Lucid inside media queries
19
+ * Create new rows without wrapping `<div>`s
20
+ * Cater to multiple screen widths by initializing new grid dimensions within media queries
17
21
  * Achieve leaner compiled CSS than other SASS grids, due to Lucid's internal [@extend](http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#extend) logic
18
22
 
19
- Go ahead! Judge for yourself:
23
+ #Documentation
20
24
 
21
- #Installation
25
+ ##Installation
22
26
 
23
27
  ```bash
24
28
  (sudo) gem install compass-lucid-grid
@@ -33,19 +37,9 @@ echo "require 'lucid'" >> config.rb
33
37
  compass install -r lucid lucid
34
38
  ```
35
39
 
36
- Or
37
-
38
- ```bash
39
- compass create -r lucid --using lucid your_new_project
40
- ```
41
-
42
- (Note: Creating a project with Lucid does not generate the default Compass stylesheets, only the `_grid.scss` partial.)
43
-
44
- #Documentation
45
-
46
- ###Setup `+grid-init`
40
+ ##Setup `+grid-init`
47
41
 
48
- After installation, @import '_grid.scss' or copy its contents into your base file. It should look something like this:
42
+ After installation, `@import` \_grid.scss or copy its contents into your base file. Defaults (safe to remove) are shown below:
49
43
 
50
44
  ```scss
51
45
  // Remove the following line if Compass has already been included
@@ -74,23 +68,25 @@ $grid-centering: true;
74
68
  @include grid-init;
75
69
  ```
76
70
 
77
- ###Basic Usage `+container, +columns( $columns (int) )`
71
+ ##Basic Layout `+container, +columns( $columns (int) )`
78
72
 
79
- Now we're ready to style:
73
+ Now we're ready to style. All you need is a grid container and its child elements to start.
74
+
75
+ Note: Instead of applying repetative styles directly to each and every element, Lucid groups selectors that contain the same styles. This results in MUCH leaner compiled CSS.
80
76
 
81
77
  ```scss
82
78
  /* SCSS */
83
79
 
84
- .container {
85
- @include container; // defines grid container
80
+ .blue-box {
81
+ @include container; // container element to "contain" child elements
86
82
  background: blue;
87
83
 
88
84
  .sidebar {
89
- @include columns(3); // 3 column element
85
+ @include columns(4); // 4 column element (1/3 row)
90
86
  }
91
87
 
92
88
  .main {
93
- @include columns(9); // 9 column element
89
+ @include columns(8); // 8 column element (2/3 row)
94
90
  }
95
91
 
96
92
  .custom {
@@ -99,114 +95,71 @@ Now we're ready to style:
99
95
  }
100
96
  }
101
97
 
102
- .another-container {
103
- @include container; // yet another container
98
+ .red-box {
99
+ @include container; // multiple containers are fine and dandy
104
100
  background: red;
105
101
  }
106
102
 
107
103
 
108
104
  /* Compiled CSS */
109
105
 
110
- .grid-container,
111
- .container,
112
- .another-container {
113
- // container styles
106
+ .grid-clearfix:after, // clearfix styles
107
+ .grid-container:after,
108
+ .blue-box:after,
109
+ .red-box:after {
110
+ content: "";
111
+ display: table;
112
+ clear: both;
114
113
  }
115
114
 
116
- .grid-clearfix,
117
- .grid-container,
118
- .container,
119
- .another-container {
120
- // clearfix styles
115
+ .grid-container, // shared container styles
116
+ .blue-box,
117
+ .red-box {
118
+ margin-left: auto;
119
+ margin-right: auto;
120
+ width: 990px;
121
121
  }
122
122
 
123
- .container {
123
+ .blue-box { // unique container styles
124
124
  background: blue;
125
125
  }
126
126
 
127
- .another-container {
127
+ .red-box {
128
128
  background: red;
129
129
  }
130
130
 
131
- .grid-element,
132
- .container .sidebar,
133
- .container .main,
134
- .container .custom {
135
- // styles shared by all grid elements
131
+ .grid-element, // shared grid element styles
132
+ .blue-box .sidebar,
133
+ .blue-box .main,
134
+ .blue-box .custom {
135
+ display: inline;
136
+ float: left;
137
+ margin-left: 15px;
138
+ margin-right: 15px;
136
139
  }
137
140
 
138
- .container .sidebar {
139
- // 3 column width
141
+ .blue-box .sidebar { // 4 column width
142
+ width: 300px;
140
143
  }
141
144
 
142
- .container .main {
143
- // 9 column width
145
+ .blue-box .main { // 8 column width
146
+ width: 630px;
144
147
  }
145
148
 
146
- .container .custom {
147
- width: 123px; // custom width
149
+ .blue-box .custom { // custom width
150
+ width: 123px;
148
151
  }
149
152
  ```
150
153
 
151
- Did you get that?
152
-
153
- Instead of applying styles directly to each grid element, whenever possible, Lucid groups grid selectors that contain the same styles.
154
-
155
- This results in MUCH leaner compiled CSS, as it avoids needless repetition.
154
+ ##Adjusting for Borders and Padding `+columns( $columns (int), $adjustment (px) )`
156
155
 
157
- ###Offset Positioning `+offset( $offset (int), $gutters (0 || none) )`
156
+ Grids typically don't play nice with borders and padding - these properties affect the width of elements, causing layouts to break. Using a wrapping `<div>` was often the cleanest method to accomodate styling.
158
157
 
159
- Sometimes, your layout needs a little bit of whitespace. Not a problem with Lucid:
160
-
161
- ```scss
162
- .offset-to-the-right {
163
- @include columns(6);
164
- @include offset(3); // shifts element to the right 3 columns
165
- }
166
-
167
- .offset-to-the-left {
168
- @include columns(6);
169
- @include offset(-3); // shifts element to the left 3 columns
170
- }
171
-
172
- .offset-gutterless {
173
- @include columns(6, 0, none);
174
- @include offset(3, none); // include 'none' or '0' when grid element is gutterless
175
- }
176
- ```
177
-
178
- Unlike other grids that use padding or relative positioning to achieve this, Lucid does it with just `margin-left`. That means the element itself can still safely recieve styling!
179
-
180
- ###New Rows `+row-break`
181
-
182
- Because of the way Lucid was designed, elements that exceed the width of the container will automatically wrap into the next row. If you want to insert a "row break" manually, it's dead simple:
183
-
184
- ```scss
185
- .container {
186
- @include container; // 12 column container
187
- // would normally accomodate all 4 children
188
- .on-row-1 {
189
- @include columns(3);
190
- }
191
-
192
- .also-on-row-1 {
193
- @include columns(3);
194
- }
195
-
196
- .on-row-2 {
197
- @include columns(3); // would have been on row 1
198
- @include row-break; // +row-break puts it on row 2
199
- }
200
-
201
- .also-on-row-2 {
202
- @include columns(3); // all following elements affected as well
203
- }
204
- }
205
- ```
158
+ With Lucid, this practice is no longer necessary - you can now adjust the width of grid elements individually. Just add your total borders / padding together and pass the negative value as a mixin parameter.
206
159
 
207
- ###Using with Borders and Padding `+columns( $columns (int), $adjustment (px) )`
160
+ Note: Adjusting the width of a grid element makes it less suitable as a parent element for nesting (it can no longer contain the full expected width).
208
161
 
209
- With other grids, styling an inner `<div>` is often the cleanest method to accomodate borders and padding, since it preserves the width of the grid element:
162
+ ####Old Way:
210
163
 
211
164
  ```html
212
165
  <div class="container">
@@ -229,7 +182,7 @@ With other grids, styling an inner `<div>` is often the cleanest method to accom
229
182
  }
230
183
  ```
231
184
 
232
- With Lucid, this practice is no longer necessary, as you can adjust the width of grid elements individually! Just add your total borders / padding together and pass the negative value as a mixin parameter. Like this:
185
+ ####With Lucid:
233
186
 
234
187
  ```html
235
188
  <div class="container">
@@ -248,14 +201,14 @@ With Lucid, this practice is no longer necessary, as you can adjust the width of
248
201
  }
249
202
  ```
250
203
 
251
- Note, adjusting the width of a grid element means that nesting other grid elements within is no longer guaranteed to add up correctly. You *can* make use of Lucid's `+grid-reinit` to define a new inner grid however!
204
+ ##Gutterless Elements `+columns( $columns (int), $adjustment (px), $gutters (0 || none) )`
252
205
 
253
- ###Gutterless Elements `+columns( $columns (int), $adjustment (px), $gutters (0 || none) )`
206
+ Sometimes, it's convenient to have grid elements without gutter margins. This is especially useful for nesting elements or defining custom margins.
254
207
 
255
- Sometimes, it's convenient to have grid units without gutters. For example, when you want to nest elements within other elements:
208
+ To turn off gutters, just pass a third parameter:
256
209
 
257
210
  ```scss
258
- .gutterless {
211
+ .gutterless { // a gutterless element
259
212
  @include columns(9, 0, none); // $gutters can accept 'none' or '0'
260
213
 
261
214
  .nested {
@@ -268,48 +221,104 @@ Sometimes, it's convenient to have grid units without gutters. For example, when
268
221
  }
269
222
  ```
270
223
 
224
+ ##Offset Positioning `+offset( $offset (int), $gutters (0 || none) )`
225
+
226
+ Layouts oftentimes call for a bit of whitespace. Not a problem with Lucid. Just remember to specify whether the element you're including to has gutters or not - this is factored into the calculation.
227
+
228
+ Unlike other grids that use padding or relative positioning to achieve this, Lucid does it with just `margin-left`. That means the element itself can still safely recieve background styling.
229
+
230
+ ```scss
231
+ .offset-to-the-right {
232
+ @include columns(6);
233
+ @include offset(3); // shifts element to the right 3 columns
234
+ }
235
+
236
+ .offset-to-the-left {
237
+ @include columns(6);
238
+ @include offset(-3); // shifts element to the left 3 columns
239
+ }
240
+
241
+ .offset-gutterless {
242
+ @include columns(6, 0, none);
243
+ @include offset(3, none); // include 'none' or '0' when grid element is gutterless
244
+ }
245
+ ```
246
+
247
+ ##New Rows `+row-break`
248
+
249
+ Elements that exceed the width of the container will automatically wrap into the next row. If you want to insert a "row break" manually, it's dead simple:
250
+
251
+ ```scss
252
+ .container {
253
+ @include container; // this 12 column container
254
+ // would normally accomodate all 4 children
255
+ .on-row-1 {
256
+ @include columns(3);
257
+ }
258
+
259
+ .also-on-row-1 {
260
+ @include columns(3);
261
+ }
262
+
263
+ .on-row-2 {
264
+ @include columns(3); // this would have been on row 1
265
+ @include row-break; // +row-break puts it on row 2
266
+ }
267
+
268
+ .also-on-row-2 {
269
+ @include columns(3); // all following elements affected as well
270
+ }
271
+ }
272
+ ```
273
+
271
274
  #Advanced
272
275
 
273
- ###Media Queries and Grid Reformatting `+grid-reinit`
276
+ ##Media Queries and Grid Reformatting `+grid-reinit`
277
+
278
+ Lucid uses pixels, which means that it's a fixed-width grid (percentages aren't precise enough). Fortunately, this doesn't mean that your sites have to be fixed-width.
274
279
 
275
- Lucid uses pixels, which means that it's a fixed-width grid (percentages aren't precise enough). Fortunately, this doesn't mean that your sites have to be fixed-width:
280
+ "Reinitialize" Lucid inside a media query (or any other a wrapping container) to adjust the size of grid elements within the container. Just preface it with a new `$grid-width` and/or `$grid-columns`.
276
281
 
277
282
  ```scss
283
+ /* Full width grid */
284
+
278
285
  @include grid-init;
279
286
 
280
- // full width grid
281
287
  .container { @include container; }
282
288
  .sidebar { @include column(3); }
283
289
  .main { @include column(9); }
284
290
 
291
+ /* Miniature grid within media query */
292
+
285
293
  @media screen and (max-width: 480px) {
286
294
 
287
295
  // redeclare one or more variables
288
296
  $grid-width: 480px;
297
+ $grid-columns: 6;
289
298
 
290
- // outputs a single modified @extend hook
291
299
  @include grid-reinit;
292
300
 
293
- // same proportions as before, just smaller!
294
301
  .container { @include container; }
295
- .sidebar { @include column(3); }
296
- .main { @include column(9); }
302
+ .sidebar { @include column(2); }
303
+ .main { @include column(4); }
297
304
 
298
305
  }
299
306
  ```
300
307
 
301
- ###Modifying @extend Hooks
308
+ ##Modifying @extend Hooks
302
309
 
303
- As mentioned before, Lucid used @extend internally to achieve leaner stylesheets. In order to do this, `+grid-init` outputs four benign classes for @extend to "hook" onto. These classes can be modified (defaults shown):
310
+ Lucid uses `@extend` internally to achieve leaner stylesheets. In order to do this, `+grid-init` outputs four benign selectors for `@extend` to "hook" onto. These selectors can be modified (defaults shown):
304
311
 
305
312
  ```scss
306
313
  $grid-hook-clearfix: ".grid-clearfix";
307
314
  $grid-hook-container: ".grid-container";
308
315
  $grid-hook-element: ".grid-element";
309
316
  $grid-hook-gutterless: ".grid-column-gutterless";
317
+
318
+ @include grid-init;
310
319
  ```
311
320
 
312
- ###Unsemantic Class Names `+grid-classes( $gutterless (bool), $prefix (str), $prefix-gutterless (str) )`
321
+ ##Unsemantic Class Names `+grid-classes( $gutterless (bool), $prefix (str), $prefix-gutterless (str) )`
313
322
 
314
323
  For testing purposes, or for those who are unwilling to part with old ways, Lucid provides a class name generator mixin:
315
324
 
@@ -326,3 +335,10 @@ For testing purposes, or for those who are unwilling to part with old ways, Luci
326
335
  @include grid-classes(true, 'grid-', 'gutterless-');
327
336
  ```
328
337
 
338
+ #Your Turn
339
+
340
+ Love it? Hate it? Bugs? Suggestions?
341
+
342
+ [I'd love to know.](https://github.com/ezYZ/lucid/issues) Thanks for stopping by!
343
+
344
+ \-Y
@@ -5,6 +5,7 @@
5
5
  // MIT License [https://github.com/ezYZ/lucid/blob/master/LICENSE.txt]
6
6
  //
7
7
  // @import this into your project or paste into your base/bootstrap file
8
+ // The variables included below are the defaults and are safe to remove.
8
9
  //
9
10
  //============================================================================//
10
11
 
@@ -9,9 +9,9 @@ help %Q{
9
9
  THE LUCID GRID
10
10
  plugin by Yifei Zhang [http://yifei.co]
11
11
 
12
- A smarter CSS grid for Compass.
12
+ A Compass/SASS grid for developers who love semantics.
13
13
 
14
- For detailed documentation and examples, visit [https://github.com/ezYZ/lucid]
14
+ A Compass/SASS grid that outputs lean, semantic stylesheets. Avoids CSS repetition on SASS compilation and reduces the need for wrapper <div>s.
15
15
 
16
16
  ***
17
17
 
@@ -24,7 +24,7 @@ welcome_message %Q{
24
24
  THE LUCID GRID
25
25
  plugin by Yifei Zhang [http://yifei.co]
26
26
 
27
- A smarter CSS grid for Compass.
27
+ A Compass/SASS grid that outputs lean, semantic stylesheets. Avoids CSS repetition on SASS compilation and reduces the need for wrapper <div>s.
28
28
 
29
29
  For detailed documentation and examples, visit [https://github.com/ezYZ/lucid]
30
30
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: compass-lucid-grid
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.0
4
+ version: 0.5.1
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -9,11 +9,11 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2011-06-30 00:00:00.000000000Z
12
+ date: 2011-07-01 00:00:00.000000000Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: compass
16
- requirement: &78872390 !ruby/object:Gem::Requirement
16
+ requirement: &70127160 !ruby/object:Gem::Requirement
17
17
  none: false
18
18
  requirements:
19
19
  - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
21
21
  version: '0.11'
22
22
  type: :runtime
23
23
  prerelease: false
24
- version_requirements: *78872390
24
+ version_requirements: *70127160
25
25
  description: A Compass/SASS grid that outputs lean, semantic stylesheets. Avoids CSS
26
26
  repetition on SASS compilation and reduces the need for wrapper <div>s.
27
27
  email: yz@yifei.co