0
# Vertical Rhythm
1

2
Advanced typography system for maintaining consistent vertical spacing and line-height calculations across all elements. The vertical rhythm system automatically converts pixel values to the configured unit system and ensures harmonious spacing relationships.
3

4
## Capabilities
5

6
### Rhythm Conversion Function
7

8
Converts pixel values to the specified unit system for consistent vertical rhythm.
9

10
```scss { .api }
11
/**
12
 * Converts px values to specified unit for vertical rhythm
13
 * @param $value - Value to convert (must be in px)
14
 * @param $relative-to - Reference font size for em/rem calculations (default: $base-font-size)
15
 * @param $unit - Target unit: 'px', 'em', or 'rem' (default: $base-unit)
16
 * @return Converted value in target unit
17
 * @throws Error if $value is not in px units
18
 */
19
@function normalize-rhythm($value, $relative-to: $base-font-size, $unit: $base-unit);
20
```
21

22
**Usage Examples:**
23

24
```scss
25
// Convert 24px to em relative to 16px base
26
$line-height: normalize-rhythm(24px, 16px, 'em'); // 1.5em
27

28
// Convert using global defaults
29
$margin: normalize-rhythm(16px); // Uses $base-font-size and $base-unit
30

31
// Convert to rem
32
$padding: normalize-rhythm(32px, 16px, 'rem'); // 2rem
33
```
34

35
### Font Size Mixin
36

37
Sets font-size using vertical rhythm conversion for consistent typography scaling.
38

39
```scss { .api }
40
/**
41
 * Sets font-size using vertical rhythm conversion
42
 * @param $value - Font size in pixels
43
 * @param $relative-to - Reference font size for calculation (default: $base-font-size)
44
 * @throws Error if $value is not in px units
45
 */
46
@mixin normalize-font-size($value, $relative-to: $base-font-size);
47
```
48

49
**Usage Examples:**
50

51
```scss
52
.heading {
53
  @include normalize-font-size(24px);
54
  // Output: font-size: 1.5em; (when $base-unit is 'em' and $base-font-size is 16px)
55
}
56

57
.small-text {
58
  @include normalize-font-size(14px, 18px);
59
  // Output: font-size: 0.778em; (relative to 18px instead of base)
60
}
61
```
62

63
### General Rhythm Mixin
64

65
Sets any CSS property using vertical rhythm conversion, with support for unitless values that get automatic rhythm scaling.
66

67
```scss { .api }
68
/**
69
 * Sets CSS property values using vertical rhythm conversion
70
 * @param $property - CSS property name (e.g., 'margin', 'padding')
71
 * @param $values - Values to set (unitless values get automatic rhythm conversion)
72
 * @param $relative-to - Reference font size for calculations (default: $base-font-size)
73
 */
74
@mixin normalize-rhythm($property, $values, $relative-to: $base-font-size);
75
```
76

77
**Usage Examples:**
78

79
```scss
80
.content {
81
  // Unitless values get multiplied by base line height and converted
82
  @include normalize-rhythm(margin, 1 0 2 0);
83
  // Output: margin: 1.5em 0 3em 0; (when base-line-height is 24px, base-font-size 16px)
84
  
85
  // Mixed values: unitless gets converted, others pass through
86
  @include normalize-rhythm(padding, 1 10px);
87
  // Output: padding: 1.5em 10px;
88
}
89

90
.sidebar {
91
  @include normalize-rhythm(margin-top, 0.5, 18px);
92
  // Output: margin-top: 1em; (relative to 18px font size)
93
}
94
```
95

96
### Margin Rhythm Mixin
97

98
Convenience mixin specifically for setting margins using vertical rhythm.
99

100
```scss { .api }
101
/**
102
 * Sets margin using vertical rhythm conversion
103
 * @param $values - Margin values (unitless values get rhythm conversion)
104
 * @param $relative-to - Reference font size for calculations (default: $base-font-size)
105
 */
106
@mixin normalize-margin($values, $relative-to: $base-font-size);
107
```
108

109
**Usage Examples:**
110

111
```scss
112
.article {
113
  @include normalize-margin(1 0);
114
  // Output: margin: 1.5em 0; (one rhythm unit top/bottom, zero left/right)
115
}
116

117
.section {
118
  @include normalize-margin(2 1 1 1);
119
  // Output: margin: 3em 1.5em 1.5em 1.5em;
120
}
121
```
122

123
### Line Height Calculation Mixin
124

125
Automatically calculates and sets line-height to maintain vertical rhythm based on font size.
126

127
```scss { .api }
128
/**
129
 * Calculates and sets line-height to maintain vertical rhythm
130
 * @param $font-size - Font size for line-height calculation
131
 * @param $min-line-padding - Minimum padding between lines (default: 2px)
132
 */
133
@mixin normalize-line-height($font-size, $min-line-padding: 2px);
134
```
135

136
**Usage Examples:**
137

138
```scss
139
.large-heading {
140
  font-size: 32px;
141
  @include normalize-line-height(32px);
142
  // Automatically calculates appropriate line-height to maintain rhythm
143
  // If base-line-height is 24px, this might output: line-height: 1.5em;
144
}
145

146
.tight-text {
147
  font-size: 14px;
148
  @include normalize-line-height(14px, 1px);
149
  // Uses minimal line padding for tighter spacing
150
}
151
```
152

153
## Vertical Rhythm Variables
154

155
The vertical rhythm system is controlled by these key variables:
156

157
```scss { .api }
158
// Enable/disable vertical rhythm mode
159
$normalize-vertical-rhythm: false !default;
160

161
// Base measurements for rhythm calculations
162
$base-font-size: 16px !default;
163
$base-line-height: 24px !default;
164

165
// Output unit for rhythm values
166
$base-unit: 'em' !default; // 'px', 'em', or 'rem'
167
```
168

169
## How Vertical Rhythm Works
170

171
1. **Base Grid**: All vertical spacing is based on multiples of `$base-line-height`
172
2. **Unit Conversion**: Pixel values are converted to `$base-unit` (em, rem, or px)
173
3. **Unitless Scaling**: Unitless values in rhythm mixins are multiplied by the base line height
174
4. **Automatic Activation**: Setting custom font size variables automatically enables vertical rhythm mode
175
5. **Line Height Calculation**: Line heights are calculated to fit rhythm grid with minimum padding
176

177
## Integration with normalize() Mixin
178

179
When vertical rhythm is enabled (either manually or by customizing font variables), the main `normalize()` mixin automatically applies rhythm-based spacing to all normalized elements including headings, paragraphs, lists, and form elements.