0
# normalize-scss
1

2
normalize-scss is a Sass port of normalize.css v7.0.0 that provides cross-browser normalization styles with additional Sass features. It extends the original normalize.css with configurable variables, vertical rhythm mixins for consistent typography scaling, and flexible section-based output control.
3

4
## Package Information
5

6
- **Package Name**: normalize-scss
7
- **Package Type**: npm
8
- **Language**: Sass/SCSS
9
- **Installation**: `npm install normalize-scss`
10

11
## Core Imports
12

13
Standard Sass import:
14

15
```scss
16
@import 'normalize-scss/sass/normalize';
17
```
18

19
Immediate import (outputs CSS directly):
20

21
```scss
22
@import 'normalize-scss/sass/normalize/import-now';
23
```
24

25
## Basic Usage
26

27
### Simple Usage
28

29
```scss
30
@import 'normalize-scss/sass/normalize';
31
@include normalize();
32
```
33

34
### With Custom Variables
35

36
```scss
37
// Set variables before importing
38
$base-font-size: 18px;
39
$base-line-height: 27px;
40
$base-font-family: 'Helvetica Neue', Arial, sans-serif;
41

42
@import 'normalize-scss/sass/normalize';
43
@include normalize();
44
```
45

46
### Selective Output
47

48
```scss
49
@import 'normalize-scss/sass/normalize';
50

51
// Include only specific sections
52
@include normalize((document sections forms));
53

54
// Exclude specific sections
55
@include normalize($exclude: (embedded scripting));
56
```
57

58
## Architecture
59

60
normalize-scss is built around several key components:
61

62
- **Core Normalize Mixin**: Main `normalize()` mixin with section-based filtering
63
- **Configuration Variables**: 11 variables controlling typography, layout, and behavior
64
- **Vertical Rhythm System**: Advanced typography mixins for consistent spacing and line-height calculations
65
- **Multiple Integration Methods**: Support for npm, Eyeglass, Ruby Gem, and Bower
66
- **Section-Based Output**: Modular CSS output organized into logical sections (document, forms, text, etc.)
67

68
## Capabilities
69

70
### Core Normalization
71

72
Primary normalization functionality that outputs cross-browser CSS styles with optional section filtering.
73

74
```scss { .api }
75
/**
76
 * Main mixin to output normalize CSS with optional section filtering
77
 * @param $include - Sections to include (default: (all))
78
 * @param $exclude - Sections to exclude (default: ())
79
 */
80
@mixin normalize($include: (all), $exclude: ());
81
```
82

83
Available sections: `document`, `sections`, `grouping`, `links`, `text`, `embedded`, `forms`, `interactive`, `scripting`, `hidden`
84

85
### Configuration Variables
86

87
Typography configuration variables that control font sizing, spacing, and layout behavior.
88

89
```scss { .api }
90
// Typography variables
91
$base-font-size: 16px !default;
92
$base-line-height: 24px !default;
93
$base-unit: 'em' !default;
94
$base-font-family: null !default;
95

96
// Heading font size variables
97
$h1-font-size: 2 * $base-font-size !default;
98
$h2-font-size: 1.5 * $base-font-size !default;
99
$h3-font-size: 1.17 * $base-font-size !default;
100
$h4-font-size: 1 * $base-font-size !default;
101
$h5-font-size: 0.83 * $base-font-size !default;
102
$h6-font-size: 0.67 * $base-font-size !default;
103

104
// Layout variables
105
$indent-amount: 40px !default;
106
$normalize-vertical-rhythm: false !default;
107
```
108

109
### Vertical Rhythm System
110

111
Advanced typography system for maintaining consistent vertical spacing and line-height calculations across all elements.
112

113
```scss { .api }
114
/**
115
 * Converts px values to specified unit for vertical rhythm
116
 * @param $value - Value to convert (must be in px)
117
 * @param $relative-to - Reference font size (default: $base-font-size)
118
 * @param $unit - Target unit (default: $base-unit)
119
 * @return Converted value in target unit
120
 */
121
@function normalize-rhythm($value, $relative-to: $base-font-size, $unit: $base-unit);
122

123
/**
124
 * Sets font-size using vertical rhythm conversion
125
 * @param $value - Font size in pixels
126
 * @param $relative-to - Reference font size (default: $base-font-size)
127
 */
128
@mixin normalize-font-size($value, $relative-to: $base-font-size);
129
```
130

131
[Vertical Rhythm](./vertical-rhythm.md)
132

133
## Integration Methods
134

135
### NPM Integration
136

137
```scss
138
@import 'normalize-scss/sass/normalize';
139
@include normalize();
140
```
141

142
### Eyeglass Integration
143

144
When using Eyeglass, import as:
145

146
```scss
147
@import 'normalize';
148
@include normalize();
149
```
150

151
### Ruby Gem Integration
152

153
With Compass:
154

155
```ruby
156
require "normalize-scss"
157
```
158

159
```scss
160
@import 'normalize';
161
@include normalize();
162
```
163

164
### Bower Integration
165

166
The Bower package points to the immediate import version:
167

168
```scss
169
@import 'bower_components/normalize.scss/sass/normalize/import-now';
170
```
171

172
## Browser Support
173

174
- Chrome (last four versions)
175
- Edge (version 25 and later)
176
- Firefox (last four versions)
177
- Firefox ESR
178
- Internet Explorer 9+
179
- Opera (last four versions)
180
- Safari (last four versions)
181

182
## Types
183

184
```scss { .api }
185
// Section names for include/exclude parameters
186
type NormalizeSection = 
187
  | 'document'
188
  | 'sections' 
189
  | 'grouping'
190
  | 'links'
191
  | 'text'
192
  | 'embedded'
193
  | 'forms'
194
  | 'interactive'
195
  | 'scripting'
196
  | 'hidden'
197
  | 'all';
198

199
// Supported units for vertical rhythm
200
type Unit = 'px' | 'em' | 'rem';
201
```