_index.en.md 2.9 KB
Newer Older
Laura Kalbag's avatar
Laura Kalbag committed
1
---
Laura Kalbag's avatar
Laura Kalbag committed
2
title: "Style Guides"
Laura Kalbag's avatar
Laura Kalbag committed
3
date: 2018-03-06T13:47:49+01:00
Laura Kalbag's avatar
Laura Kalbag committed
4
draft: false
Laura Kalbag's avatar
Laura Kalbag committed
5
6
---

Laura Kalbag's avatar
Laura Kalbag committed
7
## CSS Style Guide
Laura Kalbag's avatar
Laura Kalbag committed
8
9
10
11
12
13
14
15
16
17
18
19
20

Below are the basic rules we use for writing CSS consistently.

### Basics

CSS is written to aid readability and findability through consistency.

* Elements and curly brackets are always on their own lines.
* Single-line comments are used to describe CSS on the line below.
* Rules are always in alphabetical order, except 4-sided rules (margins, padding, borders) which are ordered by top, left, bottom, right, following the shorthand order. 
* Don’t break comments or rules mid-line. Let rules fill full-width so developers can use their chosen word wrap length.

```
Laura Kalbag's avatar
Laura Kalbag committed
21
.element {
Laura Kalbag's avatar
Laura Kalbag committed
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
    /* comment explains the line *below* */
    /* rules are in alphabetical order */
    font-size: 1em;
    font-weight: bold;
    margin: 0;
    /* padding, margin and border (4-sided) rules are in top-left-bottom-right order */
    padding-top: 1em;
    padding-left: 20%;
    padding-bottom: 0;
    padding-right: 2em;
}
```

### Structure

Elements are ordered from least specific to more specific, according to the cascade.

#### Headings and comments

Headings (as comments) are used to make it easy to skim-read and find specific rules. Use an empty line below every heading.

* H2-level headings are in UPPERCASE, and use dashes to segment groups of rules.

```
/* 
GENERAL RULES
- - - - - - - - - - - - - - - - - - - - - - - - */
```

* H3-level headings are in sentence case, and use a shorter series of dashes to segment groups of rules.

```
/*
Component name
- - - - - - - - - - - - */

Single line or multiline comments outside element refer to the element below. Use one line of space in between for readability.

/* Images are circular with grey border */

img
{
    border: 1px solid grey;
    border-radius: 50%;
}
```

Single line comments inside element refer to the line below.

```
/* mask image into circle using borders */
border-radius: 50%;
```

Avoid multi-line comments inside elements.

### Naming coventions

For the sake of compatibility, class names follow the Bulma naming conventions.

```
<div class='card-content'>
```

Laura Kalbag's avatar
Laura Kalbag committed
86
When overriding Bulma’s CSS, we override on the Bulma classes. *(While the example illustrates the point, we no longer override `rem`s for `em`s!)*
Laura Kalbag's avatar
Laura Kalbag committed
87
88
89
90
91
92
93
94
95

```
.card-content
{
    /* override Bulma’s use of rems on font sizes so font scales according to our global styles */
    font-size: 1em;
}
```

96
When creating custom (non-Bulma) components, we follow the Bulma-style naming convention of lowercase hyphen-separated class names.
Laura Kalbag's avatar
Laura Kalbag committed
97
98

```
99
<div class='profile-bio'>
Laura Kalbag's avatar
Laura Kalbag committed
100
101
102
103
104
105
106
107
108
```

### Units

We use `rem`s everywhere to keep our sizes relative to the root font size. This means that:

* All sizes will be relative to a person’s minimum font size as chosen in their browser settings.
* The entirety of the interface can be scaled using one media query to adjust the root font size.
* Values are always consistent and proportional to other values.