-
Notifications
You must be signed in to change notification settings - Fork 23
/
index.html
1456 lines (1216 loc) · 69.1 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en-us">
<head>
<meta charset="utf-8">
<title>DoCSSa – Sass based CSS architecture and methodology</title>
<link rel="shortcut icon" href="favicon.ico">
<meta name="description"
content="DoCSSa {dok~sa} — Deferred Object CSS Architecture — Sass based CSS architecture and methodology for large & long lived sites.">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=Edge">
<link rel="stylesheet" href="css/custom.css">
<script src="js/modernizr.custom.20463.js"></script>
</head>
<!--[if IE 7]>
<body class="lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]>
<body class="lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!-->
<body> <!--<![endif]-->
<div class="mainContainer">
<header class="mainHeader">
<h1 class="mainTitle">
DoCSSa 2.0 {dok~sa}
</h1>
<h2 class="mainSubtitle">Sass based CSS architecture and methodology</h2>
</header>
<nav class="mainNav">
<ul class="mainMenu">
<li class="mainMenu_item">
<a class="mainMenu_link" href="#">Home</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#about">About</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#fileStructure">File Structure</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#components">Components</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#namingConventions">Naming conventions</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#responsive">Responsive</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#gettingStarted">Getting started</a>
</li>
<li class="mainMenu_item mainMenu_item--highlighted">
<a class="mainMenu_link" href="#contributing">Contributing</a>
</li>
</ul>
<button class="mainNav_opener">show/hide menu</button>
</nav>
<article class="mainContent">
<hr class="articleSeparator">
<section class="mainSection" id="about">
<header class="mainSection_header">
<h1 class="mainSection_title">About</h1>
</header>
<div class="mainSection_body">
<h2 class="mainSection_subtitle">What is DoCSSa ?</h2>
<p>DoCSSa is a CSS architecture and methodology to help structure rapid and maintainable
stylesheets development.<br>
It is intended for use in large, long lived sites, on which many frontend developers may be working
over time.<br>
The name stands for <em>Deferred Object CSS Architecture</em>.</p>
<h2 class="mainSection_subtitle">What are the key features of DoCSSa ?</h2>
<ul class="firstOrderList">
<li class="firstOrderList_item">
<span class="firstOrderList_item_content">
Clear and proven folder structure
</span>
</li>
<li class="firstOrderList_item">
<span class="firstOrderList_item_content">
Separation of concerns between HTML and CSS
</span>
</li>
<li class="firstOrderList_item">
<span class="firstOrderList_item_content">
Scalable and maintainable stylesheets
</span>
</li>
<li class="firstOrderList_item">
<span class="firstOrderList_item_content">
Easy to setup and flexible
</span>
</li>
</ul>
<h2 class="mainSection_subtitle">Why does DoCSSa exist ?</h2>
<p>As frontend web developers, we are living in a world of evergrowing complexity. What once was a
relatively easy thing to do (putting aside browsers inconsistencies) has grown into a very complex,
dynamic, everchanging reality.</p>
<p>So, we need flexible structures in order to be more efficient and less
under pressure when the rough times come. The more work we
can avoid by having defined the right tools and the right architecture ahead of time, the better.</p>
<p>DoCSSa is our attempt at an organization that aims toward a fast workflow that will keep the
flexibility required for the long run.</p>
<h2 class="mainSection_subtitle">How does DoCSSa bring its benefits ?</h2>
<p>DoCSSa is based on Sass, and leverages some of its key features to achieve its goal.
Most notably, DoCSSa takes advantage of imports and mixins.
It also suggests a file system organisation and a BEM based naming convention, and integrates
the core ideas found in OOCSS and SmaCSS.</p>
</div>
</section>
<hr class="articleSeparator">
<section class="mainSection" id="fileStructure">
<header class="mainSection_header">
<h1 class="mainSection_title">File Structure</h1>
</header>
<div class="mainSection_body">
<h2 class="mainSection_subtitle">Basics</h2>
<p>In DoCSSa, the file system is divided in four main directories in the sass folder :</p>
<ul class="firstOrderList">
<li class="firstOrderList_item">
<div class="firstOrderList_item_content">
<a class="navLink" href="#fileStructure_base">base</a>
</div>
</li>
<li class="firstOrderList_item">
<div class="firstOrderList_item_content">
<a class="navLink" href="#fileStructure_components">components</a>
</div>
</li>
<li class="firstOrderList_item">
<div class="firstOrderList_item_content">
<a class="navLink" href="#fileStructure_specifics">specifics</a>
</div>
</li>
<li class="firstOrderList_item">
<div class="firstOrderList_item_content">
<a class="navLink" href="#fileStructure_vendor">vendor</a>
</div>
</li>
</ul>
<p>Each base folder has a specific role, and CSS rules for a particular set of elements will end up in one of
these directories, according to their nature.<br>
The structure has a single point of entry, which we'll call <em>custom.scss</em>.
This file is located at the root of the sass folder.</p>
<p class="note">In most cases, it will be the only file with no
underscore(_) prefix: as you may know, the .scss to .css convertion process in Sass only converts
files that don't have an underscore in front of them. Most of the files in our structure being imported
by other files, they don't need to be rendered directly.<br>
Only components may be rendered separately, in order to be able to dynamically load them if needed,
but we'll get back to it.
</p>
<p>The main .scss file will look something like this :</p>
<div class="sample">
<ul class="sampleHeader">
<li class="sampleHeader_item _is_current">
<span class="sampleHeader_link">// custom.scss</span>
</li>
</ul>
<pre class="codeSample">
@charset "UTF-8";
/*!
========== INIT
*/
// styles reset (normalize) and third party scss entry point
@import 'vendor/__vendor';
/*!
========== BASE
*/
// variables, fonts, mixins, helpers... common styles used across the entire site
@import 'base/__base';
/*!
========== COMPONENTS
*/
// reusable components
@import 'components/__components';
/*!
========== SPECIFICS
*/
// declarations specific to the project, organized according to the items/sections represented
@import 'specifics/__specifics';
</pre>
</div>
<p>As you can see, it mostly acts as an aggregator for other files, which themselves import some
other scss files, and so on. With a well thought organization, this simple construct can prove very powerful!</p>
<p class="note">On a sidenote, remember that Sass is only a CSS precompiler, so you'll end up with only one .css file
with all the goodies, not a bunch of HTTP requests.</p>
<p>Here is an overview of what a basic file system might look like :</p>
<samp class="sampleTitle">// file system</samp>
<pre class="codeSample">
sass
¦ custom.scss
¦
+---base
¦ ¦ __base.scss
¦ ¦ _config.scss
¦ ¦
¦ +---project
¦ ¦ __project.scss
¦ ¦ _fonts.scss
¦ ¦ _globals.scss
¦ ¦ _mixins.scss
¦ ¦ _variables.scss
¦ ¦
¦ +---utils
¦ __utils.scss
¦ _mixins.scss
¦ _system.scss
¦
+---components
¦ ¦ __components.scss
¦ ¦
¦ +---button
¦ ¦ _button.scss
¦ ¦
¦ +---tabs
¦ _tabs.scss
¦
¦
+---specifics
¦ ¦ __specifics.scss
¦ ¦ _main.scss
| | _inbox.scss
¦ ¦
¦ +---popins
¦ __popins.scss
¦ _popin-congratulations.scss
¦ _popin-loginForm.scss
¦
+---vendor
__vendor.scss
</pre>
<h2 class="mainSection_subtitle" id="fileStructure_base">Base folder</h2>
<p>The "base" folder contains rules that are global to the site. It is divided in two parts : </p>
<ul class="firstOrderList">
<li class="firstOrderList_item">
<div class="firstOrderList_item_content">
<a class="navLink" href="#fileStructure_base_utils">utils</a>
</div>
</li>
<li class="firstOrderList_item">
<div class="firstOrderList_item_content">
<a class="navLink" href="#fileStructure_base_project">project</a>
</div>
</li>
</ul>
<p class="note">Note that the <em>base/_config.scss</em> file is located directly in the base
folder. It contains variables that are required by both the utils and the project. So far
only the $baseFontSize fell in that category, but we still dedicated a file to it in
order to be consistent.</p>
<p>
<strong id="fileStructure_base_utils">Utils</strong> contains only things that don't need to change
from a project to another. As of today, it consists of <em>_system</em> and <em>_mixins</em>.
</p>
<ul class="secondaryList">
<li class="secondaryList_item">
<div class="secondaryList_item_content">
<p><em>_system</em> is a special file that contains tools used by DoCSSa.<br>
Most notably, it contains a mixin that helps requiring content
from several places without generating duplicate content, and one that helps
the provided components to make use of Modernizr classes.
</p>
</div>
</li>
<li class="secondaryList_item">
<div class="secondaryList_item_content">
<p><strong>_mixins</strong> contains a collection of commonly used helpers.
They are particularily useful for handling vendor prefixes and
fallbacks. For example, DoCSSa comes with a linear-gradient mixin that compiles to
all required vendor prefixes (and only those required!) and generates a fallback
color from the input values for browsers that don't support linear-gradient at all.
DoCSSa recommends using Modernizr for feature detection and progressive enhancement, and the provided
mixins implementing CSS3 features rely on it by default for their output (even though it can be
disabled at include time).<br>
</p>
<p class="note">Mixins can accumulate and enrich your library
with no cost, as they are only compiled when used.<br>
Mixins are a great way to avoid repetition when coding. They end up in code
repetition in the css output, and for that reason the previous version of DoCSSa
was based on placeholders instead, but it has now been proven that this repetition
is not an issue once gzip comes into play
(<a href="https://tech.bellycard.com/blog/sass-mixins-vs-extends-the-data/">more
info</a>)</p>
<aside class="exampleNote">
<p>Here's what a mixin may look like in the <em>utils/_mixins</em> file :</p>
<samp class="sampleTitle">// base/utils/_mixins.scss</samp>
<pre class="codeSample">
@mixin linear-gradient($from, $to, $fallback: '', $useModernizr: true) {
// get the correct prefixes map
$prefixes: getPrefixes(cssgradients, $useModernizr);
// declare behaviour for the case of feature not available
#{map-get($prefixes, no)} & {
@if $fallback != '' {
background-color: $fallback;
} @else {
background-color: mix($from, $to);
}
}
// declare behaviour for the case of feature available
#{map-get($prefixes, yes)} & {
background-image: -webkit-gradient(linear, left top, left bottom, from($from), to($to)); // Saf4+, Chrome
background-image: -webkit-linear-gradient(top, $from, $to); // Chrome 10+, Saf5.1+, iOS 5+
background-image: -moz-linear-gradient(top, $from, $to); // FF3.6+
background-image: -o-linear-gradient(top, $from, $to); // Opera 11.10+
background-image: linear-gradient(to bottom, $from, $to);
}
}
</pre>
</aside>
</div>
</li>
</ul>
<p>
<strong id="fileStructure_base_project">Project</strong> is where every global setup of a project
is stored. Whereas <em>utils</em> is intended to be kept and grow from a project to the next,
<em>project</em> only stands true for a given project (although you may want to use it as a
boilerplate from project to project). As of today, it consists of <em>_variables</em>,
<em>_fonts</em>, <em>_mixins</em> and <em>_globals</em>.
</p>
<ul class="secondaryList">
<li class="secondaryList_item">
<div class="secondaryList_item_content">
<p><strong>_variables</strong> is were all site wide variables reside. Default values,
color theme, configuration variables, etc. go into this file.
</p>
<p>Here's what the <em>_variables.scss</em> file might look like :</p>
<samp class="sampleTitle">// _variables.scss</samp>
<pre class="codeSample">
/* _____ VARIABLES _____ */
// Generic
// ==========================================================================
$default-borderRadius: 4;
$containerWidth: 760;
// Colors
// ==========================================================================
$color-default-light: #fff;
$color-default-dark: #333;
$color-default-darker: #000;
$color-main: #ff7f50;
$color-main-light: #ff9e7e;
$color-main-lighter: #ffdec7;
$color-secondary: #5cbcaa;
$color-alt: #f1ede4;
$color-alt-dark: #c2c0bc;
$color-alt-light: #f8f5ec;
$color-alt2: #637c84;
</pre>
</div>
</li>
<li class="secondaryList_item">
<div class="secondaryList_item_content">
<p>The <strong>_fonts</strong> file is used —you guessed it— for the font-families declaration.<br>
In our implementation, we use a font mixin that is in charge of generating a bulletproof syntax
according to the passed configuration for each needed font, according to a file naming convention.</p>
<p class="note"> But where do we have to place the font files themselves, you may be wondering? Well, as
this Sass structure is
intended to be compiled to CSS in a different directory, the fonts will be in that directory.
Typically, you'll have the <em>custom.scss</em> file in a "sass" folder" compiled to a
<em>custom.css</em> in a
"css" or "styles" folder. The font files will have to be there (preferably in a "fonts"
subfolder in order to stay nice and tidy).<br>
Same goes for all the image files you may be referring to in your stylesheets.
</p>
</div>
</li>
<li class="secondaryList_item">
<div class="secondaryList_item_content">
<p><strong>_mixins</strong> is a place for you to store simple helper that you may want
to reutilize throughout the site, but are not generic enough to endup in the
utils/_mixins file.
</p>
</div>
</li>
<li class="secondaryList_item">
<div class="secondaryList_item_content">
<p><strong>_globals</strong> contains rules that are global
to the site. Things like box-sizing type, html font size, body background color,
headings and link defaults, etc. are defined here. It is also be a good place to store
your layout definition if it is used for all pages on the site.
</p>
</div>
</li>
</ul>
<h2 class="mainSection_subtitle" id="fileStructure_components">Components folder</h2>
<p>
The "components" folder is where your ui-components are located. It is the place dedicated to
store your reusable UI appearance.<br>
Components are an important part of DoCSSa, and we dedicated a whole section to explain all there is to know about them,
so we won't say much more about them here.
</p>
<h2 class="mainSection_subtitle" id="fileStructure_specifics">Specifics folder</h2>
<p>The "specifics" folder is your common playground. It is where you'll place the rules that don't belong
in the "base" or "components" folders. Until you become fluent with DoCSSa's organization system, what will
eventually end up in a component will probably exist in here first.</p>
<p>Specifics is the closest thing to your usual CSS file, except that everything in there
is split and dispatched in files and folders according to what they apply to. This fragmentation
is key to keeping things maintainable!</p>
<p>By convention, we're using two underscores(__) as a prefix for files that act as an import
summary, and only one underscore(_) for files which are content only. This usually evolves with the
project: you begin with an underscore prefixed file, you add another one, and at some point you stop calling them
directly from the main .scss file and you reorganize them in a folder with its own summary file. </p>
<aside class="exampleNote">
<p>For example you might begin writing some rules in specifics/__specifics.scss, and as it grows
realize that you have a bunch of rules all related to the popin windows. You'd then move those rules in a
_popin.scss file and import that file from __specifics.scss.</p>
<p>
After a while, you'll notice that you added some rules for a
bunch of specific popins on your site. That would be a good time to create a "popins" folder and
split the specific popin rules to different files in that folder (say, popins/_popin-loginForm.scss
and popins/_popin-congratulations.scss).<br>
Instead of importing _popins.scss from __specifics.scss, you'd then import popins/__popins.scss
instead, and let this summary file import all the specific popins required for your project.</p>
<p>This allow you to have all your feature related files in the same folder, and one summary
specific to that kind of feature which can import or leave out the files in its section as easily as commenting out a
line. If at some point you realize that you don't want to use the congratulations popin anymore, all you
have to do is to comment out the line importing its definition file (_popin-congratulations.scss) from the
popins summary (popins/__popins.scss).</p>
</aside>
<p class="note">DoCSSa encourages you to keep your definitions tidy and reorganize in subfolders as soon as it makes
sense.<br>
No file should ever be big enough that you can't scroll through it in a few mousewheel movements
max!</p>
<p>Before everyone in your team is familiar with DoCSSa, it can be helpful for occasional contributors
wondering where to place their code to have a dedicated file. In such case, we recommend using
a <em>_inbox.scss</em> file in the "specifics" folder and ask them to commit their work in there.<br>
It shall be emptied regularly by a more experienced DoCSSa user, who would move the CSS rules
defined in there to the correct place in the architecture.
</p>
<h2 class="mainSection_subtitle" id="fileStructure_vendor">Vendor folder</h2>
<p>The <em>vendor</em> folder is where we import SCSS files that come from third parties and can be updated at
any time. It can import from a bower folder, or have its assets directly in the folder.
As the .scss syntax is CSS compatible, all we have to do is to rename the .css files to
.scss, in order for them to be integrated to the .css compilation instead of referenced by the CSS
file as a classic @import.</p>
<p class="note"><em>_normalize.scss</em> is an excellent candidate for this section, along with more project specific
third party CSS. We currently rely on bower for fetching it for us.</p>
</div>
</section>
<hr class="articleSeparator">
<section class="mainSection" id="components">
<header class="mainSection_header">
<h1 class="mainSection_title">Components</h1>
</header>
<div class="mainSection_body">
<h2 class="mainSection_subtitle">Introduction</h2>
<p>Components are an important part of DoCSSa. They have been redesigned since version 1 of DoCSSa
to become simpler and easier to use. They are the "Deferred Object" part of DoCCSa.
</p>
<p>We say the Object is Deferred because its core resides in an abstraction (the mixin)
instead of being tied to a classname. DoCSSa's components are class agnostic. They are made of mixins.
A component mixin is in charge of binding the reusable styling to one or several HTML class(es).
Thanks to the BEM naming convention, the class passed to the component mixin can be
a prefix for other classes onto which to bind functionalities.
</p>
<p>This allows for components to be instantiated on any class, and to be composable if needed.
</p>
<p>As the component is not tied to a particular class, you can use it on whatever class you want, whenever you want,
from the stylesheet side. That means that you can (and should) keep a semantic meaning to your HTML classes, and change
their look and feel without having to modify the markup.<br>
When your markup comes from a RTE, this is a huge gain.
You can change the styling without asking the contributors to change their habits, and you can
affect everything already written without having to make search&replace throughout a database or without
having a "red" class helper mean the color is going to be purple!
</p>
<p class="exampleNote">
For example, instead of having a link with the "button red" classes, you can give it a "navTrigger"
class and bind a button component with a red skin to it. You could
also use the same component on a "submitTrigger" class so that both look the same. When time comes
to have a different look for your submits, all you have to do is bind the submitTrigger to another component
and you're done, without affecting the navTriggers and without touching the markup.<br>
Note that for advanced components,
the HTML may be expected to conform to a particular structure to be a valid target.
</p>
<p>If you need a component with a slightly different behaviour than the original one, you can pass
a parameter to the mixin to change the binding (or rules). If the exceptions become too numerous,
it's probably time to consider creating another component or a set of small components.
</p>
<div class="exampleNote">
<p>Here is what a component definition looks like :
</p>
<samp class="sampleTitle">// component example</samp>
<pre class="codeSample">
// map the placeholders content to some selectors through a mixin
@mixin example($selector, $defaultSkin: true) {
#{$selector} {
padding: 10px;
}
#{$selector}_inner {
padding: 20px;
}
#{$selector}:hover {
padding: 30px;
}
@if $defaultSkin != false {
@include example-skin-default($selector, $hover);
}
}
</pre>
</div>
<p>In order to fulfill their role, components need to respect those two guidelines :</p>
<ul>
<li><p>A component should be <strong>self contained</strong>.</p>
<p class="note">This means that what is outside of the visual boundaries of the
component doesn't belong in the component definition. Typically, things like margins or positioning
should reside in the "specifics" folder, not in the component. This is required for your component to
live in any possible context.</p>
</li>
<li><p><strong>Structure(layout)</strong> should be <strong>dissociated from skin(paint)</strong>.</p>
<p class="note">For example, background color, images, text colors, etc. may go into the skin section of the
component, not in its core definition. That way, you can create additional styles for them without
altering their expected behaviour as a component, and choose what visual style you want when binding
the component to a classname.</p>
</li>
</ul>
<p>Of course, it's up to you to compose with those precepts and adapt them to your constraints, but
respecting them results in a clean separation of concerns and genuinely reusable components, which is much
likely to make your dev faster further down the road.
</p>
<p class="note">
When beginning with DoCSSa, it's easy to think as everything as components, as they are so powerful.
You must be careful about that, and think about what needs to be a component and what doesn't.<br>
If you component-ize every set of rules, you risk spending more time building the same thing as you
would have in the "specifics" folder without enough additional value for it to be worth it.
Try to begin with small components to get the hang of it, and adjust your use little by little.<br>
You can begin everything the way you are used to in the "specifics" folder, organize it
in imported files and subfolders the DoCSSa way, and only extract a functionality to a component
when you feel that it would help you.<br>
DoCSSa only gives you tools to play with, what you implement and how you do things with it is up to you.
That's what we believe a "framework" should be anyway.
</p>
<h2 class="mainSection_subtitle">Description</h2>
<p>When looking at a component folder, you will see one file, and possibly some subfolders.
Let's take a <em>Tabs</em> component as an example, as probably everyone has already seen a tabbed
navigation in a page. The file in the Tabs folder would be: <em>_tabs.scss</em>.<br>
It is the component definition. Let's look at it in details.
</p>
<h3 class="mainSection_smallTitle" id="components_definition">Component's definition</h3>
<p>The component definition file contains two mixins. One for the component structure, one for
the component's skin.
</p>
<p>Here's the <em>structure</em> part of our "tabs" component :</p>
<div class="sample">
<ul class="sampleHeader">
<li class="sampleHeader_item _is_current">
<span class="sampleHeader_link">// components/tabs/_tabs.scss</span>
</li>
</ul>
<pre class="codeSample">
// _____ STRUCTURE _____ //
// define the component structure
@mixin tabs($selector, $defaultSkin: true) {
#{$selector} {
display: inline-block;
margin: 0;
padding: 0;
font-size: 0;
}
#{$selector}_item {
@include remIt(font-size, 18);
display: inline-block;
vertical-align: bottom;
line-height: 2.5;
}
#{$selector}_link {
padding: 0 10px;
}
@if $defaultSkin != false {
@include tabs-skin-default($selector);
}
}
</pre>
</div>
<p>A mixin named after the component is all it takes. Its role is to
actually bind the component's styling rules to the provided classname, its "elements", and its state.
</p>
<p class="note">We recommend that the "structure" part of the component doesn't make use of any
project variable in order to stay as generic and reusable as possible.
</p>
<p>By default, the component binding will also implement the default skin. If we have defined another
skin, all we need to do is pass "$defaultSkin: false" when instantiating the component, and
call another skin binding mixin to handle the component's skin.
</p>
<p class="note">We said earlier that a component folder may have subfolders. One of those is a "_skins"
folder that would host different skins that we could import as needed. The "_skins" folder
is prefixed by an underscore only so that it always show on top of the list in case you need
some other folders in there.
</p>
<p>Now let's look at the <em>skin</em> part of our "tabs" component :
</p>
<samp class="sampleTitle">// A component's skin part</samp>
<pre class="codeSample">
// _____ SKIN _____ //
// provide a default skin for the component
// only visual changes that don't affect the component layout should be in here
@mixin tabs-skin-default($selector) {
#{$selector} {
list-style: none;
}
#{$selector}_item {
border-bottom: 1px solid $color-main-lighter;
&._is_current {
border-bottom: 3px solid $color-main-light;
}
}
#{$selector}_item--highlighted {
background: $color-alt-light;
}
#{$selector}_link {
@include basicClickable(true);
border-left: 1px solid $color-main;
color: $color-default-dark;
font-family: 'titillium', Arial, 'sans-serif';
#{$selector}_item:first-child & {
border-left: 0;
}
#{$selector}_item._is_current & {
color: $color-main-light;
}
&:hover {
background: $color-alt;
}
}
}
</pre>
<p>As you can see, it is very close to the structure part. Actually it is placed inside the component's
folder for simplicity, but it could very well reside in a _skins folder right away.
</p>
<p class="note">As stated before, a component's "structure" should only contain it's layout, it's skeleton.
The "skin" part, unlike the structure, should
<em>only contain</em> rules that <em>don't affect</em> the structure. These rules can be
background-colors, background-images, border-radius, shadows, opacity... Anything you want as long as it doesn't
fiddle with the component's external boundaries.<br>
It is not always easy, but the more you practice it the
more it feels natural, and the easier it is to find out the right place when you come back to adjust
something about your component.
</p>
<h3 class="mainSection_smallTitle" id="components_implementation">Implementation</h3>
<p>Now that we know how a component is structured, it's time to implement it.
This is done by calling the component mixin and passing it a class selector.
</p>
<p>Here's what an implementation may look like :</p>
<samp class="sampleTitle">// in specifics/_main.scss</samp>
<pre class="codeSample">
@include tabs('.mainMenu');
</pre>
<p>That's right, now that you have defined your component, using it is as easy as that!</p>
<p>And here is what the output css will look like :</p>
<samp class="sampleTitle">// in css/custom.css</samp>
<pre class="codeSample">
.mainMenu {
display: inline-block;
margin: 0;
padding: 0;
font-size: 0;
}
.mainMenu_item {
font-size: 18px;
display: inline-block;
vertical-align: bottom;
line-height: 2.5;
}
.cssremunit .mainMenu_item {
font-size: 1.125rem;
}
.mainMenu_link {
padding: 0 10px;
}
.mainMenu {
list-style: none;
}
.mainMenu_item {
border-bottom: 1px solid #ffdec7;
}
.mainMenu_item._is_current {
border-bottom: 3px solid #ff9e7e;
}
.mainMenu_item--highlighted {
background: #f8f5ec;
}
.mainMenu_link {
background: none;
border: 0;
cursor: pointer;
text-decoration: none;
border-left: 1px solid #ff7f50;
color: #333;
font-family: 'titillium', Arial, 'sans-serif';
}
.mainMenu_item:first-child .mainMenu_link {
border-left: 0;
}
.mainMenu_item._is_current .mainMenu_link {
color: #ff9e7e;
}
.mainMenu_link:hover {
background: #f1ede4;
}
</pre>
<p>If later on you need to bind the tabs component to another class, all you have to do is to call the mixin
with that class and the parameters you want, and you're done!
</p>
<p>For example :</p>
<samp class="sampleTitle">// in specifics/_main.scss</samp>
<pre class="codeSample">
@include tabs('.articleTabs', $defaultSkin: false);
@include tabs-skin-alternate('.articleTabs');
</pre>
</div>
</section>
<hr class="articleSeparator">
<section class="mainSection" id="namingConventions">
<header class="mainSection_header">
<h1 class="mainSection_title">Naming conventions</h1>
</header>
<div class="mainSection_body">
<h2 class="mainSection_subtitle">HTML classes</h2>
<p>In DoCSSa, we decided to follow BEM class naming convention.<br>
HTML class names for <em>Blocks</em> are lowerCamelCase, and the <em>Elements</em> nested
within are separated by
an underscore(_). <em>Modifiers</em> are separated by a double dash(--), and they are used
for elements
<em>variants</em>. An element's <em>state</em> is written separately with a pattern that
begins with "_is_".
</p>
<p class="note">
<em>Variants</em> are dissociated from <em>states</em> because they play a different role,
and it appeared that with our components architecture, having a simple "_is_current" class for our items'
"current" state was way more effective than a "mainMenu_item--current" when it came to modifying the state through
javascript.<br>
BEM modifiers are now exclusively used for visual variants that don't change over time. They
have a meaning at the content(HTML) level. For example, if a tab needs to be highlighted so that
it stands out, it is applied a variant by using a modifier.<br>
By opposition, a "state" is something that is supposed to be handled by javascript and
change over time.
</p>
<div class="exampleNote">
<p>Here is an example of what that convention may look like in our tab example :</p>
<samp class="sampleTitle">// naming example</samp>
<pre class="codeSample">
<nav class="mainNav">
<ul class="mainMenu">
<li class="mainMenu_item">
<a class="mainMenu_link" href="#">Home</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#about">About</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#fileStructure">File Structure</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#components">Components</a>
</li>
<li class="mainMenu_item _is_current">
<a class="mainMenu_link" href="#namingConventions">Naming conventions</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#responsive">Responsive</a>
</li>
<li class="mainMenu_item">
<a class="mainMenu_link" href="#gettingStarted">Getting started</a>
</li>
<li class="mainMenu_item mainMenu_item--highlighted">
<a class="mainMenu_link" href="#contributing">Contributing</a>
</li>
</ul>
<button class="mainNav_opener"></button>
</nav>
</pre>
Note that this example is taken from the menu you're looking at just now in the present
page.
</div>
<p>At first, the BEM notation style can seem quite verbose and put off some developers, but it
is very powerful and allows us to go way behind old school naming conventions.<br>
It has to be tamed, though, and a classic beginner's mistake is to reflect the position of
each element in the component's DOM in its class name. To avoid that, we recommend that you look
at your low level elements first (those deeper in the DOM tree) and wonder if they could exist
elsewhere in the page or in the component.
Going up the tree, you can identify your most basic reusable components and set the names
accordingly.
</p>
<p class="exampleNote">
For example, in our example above, the "mainMenu_link" class doesn't need to reflect the
fact that it is contained in a "mainMenu_item", this doesn't really matter to the link, so there is no
reason to specify it in its name.<br>
Also, if the element can live outside the block you're looking at, it's probably not a good
idea to tie it to it, and it probably should exist on its own.
</p>
<h2 class="mainSection_subtitle">Sass files</h2>
<p>We talked about some of the aspects of the Sass file naming convention in the "File
Structure" section.</p>
<p>Each file is lowerCamelCase named and prefixed by an underscore(_) so that it is considered
by the Sass compiler as a partial and not rendered to a standalone CSS file.
</p>
<p>
Each folder has a single entry point in charge of importing other partial Sass files. This
file is named after the folder's name, and is prefixed with two underscores(__) so that it always
appears on top in the files list. It imports only the files in its own folder, except for other summary
indexes located in a direct subfolder. This way, you always can handle your imports very easily and stop the
imports of nested files at any level.<br>
Components definition files should have the same name as the component's folder name, and
have a single underscore prefix, as they are content and not imports list.
</p>
<h2>SASS variables</h2>
<p>Sass variable names should be composed of dash(-) separated parts, with each part sorted from
the most generic to the most specific variable characteristic. This is quite useful in most IDE as
you can take advantage of autocompletion.
</p>
<div class="exampleNote">
<p>For example :</p>
<samp class="sampleTitle">// variables example</samp>
<pre class="codeSample">
/* _____ VARIABLES _____ */
// Generic
// ==========================================================================
$default-borderRadius: 4;
$containerWidth: 760;
// Colors
// ==========================================================================
$color-default-light: #fff;
$color-default-dark: #333;
$color-default-darker: #000;
$color-main: #ff7f50;
$color-main-light: #ff9e7e;
$color-main-lighter: #ffdec7;
$color-secondary: #5cbcaa;
$color-alt: #f1ede4;
$color-alt-dark: #c2c0bc;
$color-alt-light: #f8f5ec;
$color-alt2: #637c84;
</pre>
</div>
</div>
</section>
<hr class="articleSeparator">