-
Notifications
You must be signed in to change notification settings - Fork 222
/
modules.html.md.erb
278 lines (225 loc) · 10.2 KB
/
modules.html.md.erb
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
---
title: Built-In Modules
introduction: >
Sass provides many built-in modules which contain useful functions (and the
occasional mixin). These modules can be loaded with the
[`@use` rule](at-rules/use) like any user-defined stylesheet, and their
functions can be called [like any other module
member](at-rules/use#loading-members). All built-in module URLs begin with
`sass:` to indicate that they're part of Sass itself.
overview: true
---
<% content_for :before_introduction do %>
<%= partial 'snippets/built-in-module-status' %>
<% end %>
<% heads_up do %>
Before the Sass module system was introduced, all Sass functions were globally
available at all times. Many functions still have global aliases (these are
listed in their documentation). The Sass team discourages their use and will
eventually deprecate them, but for now they remain available for compatibility
with older Sass versions and with LibSass (which doesn't support the module
system yet).
[A few functions][] are *only* available globally even in the new module
system, either because they have special evaluation behavior ([`if()`][]) or
because they add extra behavior on top of built-in CSS functions ([`rgb()`][]
and [`hsl()`][]). These will not be deprecated and can be used freely.
[a few functions]: #global-functions
[`if()`]: #if
[`rgb()`]: #rgb
[`hsl()`]: #hsl
<% end %>
<% example do %>
@use "sass:color";
.button {
$primary-color: #6b717f;
color: $primary-color;
border: 1px solid color.scale($primary-color, $lightness: 20%);
}
===
@use "sass:color"
.button
$primary-color: #6b717f
color: $primary-color
border: 1px solid color.scale($primary-color, $lightness: 20%)
===
.button {
color: #6b717f;
border: 1px solid #878d9a;
}
<% end %>
Sass provides the following built-in modules:
* The [`sass:math` module][] provides functions that operate on [numbers][].
* The [`sass:string` module][] makes it easy to combine, search, or split apart
[strings][].
* The [`sass:color` module][] generates new [colors][] based on existing ones,
making it easy to build color themes.
* The [`sass:list` module][] lets you access and modify values in [lists][].
* The [`sass:map` module][] makes it possible to look up the value associated
with a key in a [map][], and much more.
* The [`sass:selector` module][] provides access to Sass's powerful selector
engine.
* The [`sass:meta` module][] exposes the details of Sass's inner workings.
[`sass:math` module]: modules/math
[numbers]: values/numbers
[`sass:string` module]: modules/string
[strings]: values/strings
[`sass:color` module]: modules/color
[colors]: values/colors
[`sass:list` module]: modules/list
[lists]: values/lists
[`sass:map` module]: modules/map
[map]: values/maps
[`sass:selector` module]: modules/selector
[`sass:meta` module]: modules/meta
## Global Functions
<% function 'hsl($hue $saturation $lightness)',
'hsl($hue $saturation $lightness / $alpha)',
'hsl($hue, $saturation, $lightness, $alpha: 1)',
'hsla($hue $saturation $lightness)',
'hsla($hue $saturation $lightness / $alpha)',
'hsla($hue, $saturation, $lightness, $alpha: 1)',
returns: 'color' do %>
<% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
LibSass and Ruby Sass only support the following signatures:
* `hsl($hue, $saturation, $lightness)`
* `hsla($hue, $saturation, $lightness, $alpha)`
Note that for these implementations, the `$alpha` argument is *required* if
the function name `hsla()` is used, and *forbidden* if the function name
`hsl()` is used.
<% end %>
<% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
LibSass and older versions of Ruby Sass don't support alpha values specified as
percentages.
<% end %>
Returns a color with the given [hue, saturation, and lightness][] and the given
alpha channel.
[hue, saturation, and lightness]: https://en.wikipedia.org/wiki/HSL_and_HSV
The hue is a number between `0deg` and `360deg` (inclusive) and may be
unitless. The saturation and lightness are numbers between `0%` and `100%`
(inclusive) and may *not* be unitless. The alpha channel can be specified as
either a unitless number between 0 and 1 (inclusive), or a percentage between
`0%` and `100%` (inclusive).
[unitless]: values/numbers#units
<% fun_fact do %>
You can pass [special functions][] like `calc()` or `var()` in place of any
argument to `hsl()`. You can even use `var()` in place of multiple
arguments, since it might be replaced by multiple values! When a color
function is called this way, it returns an unquoted string using the same
signature it was called with.
[special functions]: syntax/special-functions
<% example(autogen_css: false) do %>
@debug hsl(210deg 100% 20% / var(--opacity)); // hsl(210deg 100% 20% / var(--opacity))
@debug hsla(var(--peach), 20%); // hsla(var(--peach), 20%)
===
@debug hsl(210deg 100% 20% / var(--opacity)) // hsl(210deg 100% 20% / var(--opacity))
@debug hsla(var(--peach), 20%) // hsla(var(--peach), 20%)
<% end %>
<% end %>
<% heads_up do %>
Sass's [special parsing rules][] for slash-separated values make it
difficult to pass variables for `$lightness` or `$alpha` when using the
`hsl($hue $saturation $lightness / $alpha)` signature. Consider using
`hsl($hue, $saturation, $lightness, $alpha)` instead.
[special parsing rules]: operators/numeric#slash-separated-values
<% end %>
<% example(autogen_css: false) do %>
@debug hsl(210deg 100% 20%); // #036
@debug hsl(34, 35%, 92%); // #f2ece4
@debug hsl(210deg 100% 20% / 50%); // rgba(0, 51, 102, 0.5)
@debug hsla(34, 35%, 92%, 0.2); // rgba(242, 236, 228, 0.2)
===
@debug hsl(210deg 100% 20%) // #036
@debug hsl(34, 35%, 92%) // #f2ece4
@debug hsl(210deg 100% 20% / 50%) // rgba(0, 51, 102, 0.5)
@debug hsla(34, 35%, 92%, 0.2) // rgba(242, 236, 228, 0.2)
<% end %>
<% end %>
<% function "if($condition, $if-true, $if-false)" do %>
Returns `$if-true` if `$condition` is [truthy][], and `$if-false` otherwise.
This function is special in that it doesn't even evaluate the argument that
isn't returned, so it's safe to call even if the unused argument would throw an
error.
[truthy]: at-rules/control/if#truthiness-and-falsiness
<% example(autogen_css: false) do %>
@debug if(true, 10px, 15px); // 10px
@debug if(false, 10px, 15px); // 15px
@debug if(variable-defined($var), $var, null); // null
===
@debug if(true, 10px, 15px) // 10px
@debug if(false, 10px, 15px) // 15px
@debug if(variable-defined($var), $var, null) // null
<% end %>
<% end %>
<% function 'rgb($red $green $blue)',
'rgb($red $green $blue / $alpha)',
'rgb($red, $green, $blue, $alpha: 1)',
'rgb($color, $alpha)',
'rgba($red $green $blue)',
'rgba($red $green $blue / $alpha)',
'rgba($red, $green, $blue, $alpha: 1)',
'rgba($color, $alpha)',
returns: 'color' do %>
<% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
LibSass and Ruby Sass only support the following signatures:
* `rgb($red, $green, $blue)`
* `rgba($red, $green, $blue, $alpha)`
* `rgba($color, $alpha)`
Note that for these implementations, the `$alpha` argument is *required* if
the function name `rgba()` is used, and *forbidden* if the function name
`rgb()` is used.
<% end %>
<% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
LibSass and older versions of Ruby Sass don't support alpha values specified
as percentages.
<% end %>
If `$red`, `$green`, `$blue`, and optionally `$alpha` are passed, returns a
color with the given red, green, blue, and alpha channels.
Each channel can be specified as either a [unitless][] number between 0 and
255 (inclusive), or a percentage between `0%` and `100%` (inclusive). The
alpha channel can be specified as either a unitless number between 0 and 1
(inclusive), or a percentage between `0%` and `100%` (inclusive).
[unitless]: values/numbers#units
<% fun_fact do %>
You can pass [special functions][] like `calc()` or `var()` in place of any
argument to `rgb()`. You can even use `var()` in place of multiple
arguments, since it might be replaced by multiple values! When a color
function is called this way, it returns an unquoted string using the same
signature it was called with.
[special functions]: syntax/special-functions
<% example(autogen_css: false) do %>
@debug rgb(0 51 102 / var(--opacity)); // rgb(0 51 102 / var(--opacity))
@debug rgba(var(--peach), 0.2); // rgba(var(--peach), 0.2)
===
@debug rgb(0 51 102 / var(--opacity)) // rgb(0 51 102 / var(--opacity))
@debug rgba(var(--peach), 0.2) // rgba(var(--peach), 0.2)
<% end %>
<% end %>
<% heads_up do %>
Sass's [special parsing rules][] for slash-separated values make it
difficult to pass variables for `$blue` or `$alpha` when using the
`rgb($red $green $blue / $alpha)` signature. Consider using
`rgb($red, $green, $blue, $alpha)` instead.
[special parsing rules]: operators/numeric#slash-separated-values
<% end %>
<% example(autogen_css: false) do %>
@debug rgb(0 51 102); // #036
@debug rgb(95%, 92.5%, 89.5%); // #f2ece4
@debug rgb(0 51 102 / 50%); // rgba(0, 51, 102, 0.5)
@debug rgba(95%, 92.5%, 89.5%, 0.2); // rgba(242, 236, 228, 0.2)
===
@debug rgb(0 51 102) // #036
@debug rgb(95%, 92.5%, 89.5%) // #f2ece4
@debug rgb(0 51 102 / 50%) // rgba(0, 51, 102, 0.5)
@debug rgba(95%, 92.5%, 89.5%, 0.2) // rgba(242, 236, 228, 0.2)
<% end %>
---
If `$color` and `$alpha` are passed, this returns `$color` with the given
`$alpha` channel instead of its original alpha channel.
<% example(autogen_css: false) do %>
@debug rgb(#f2ece4, 50%); // rgba(242, 236, 228, 0.5);
@debug rgba(rgba(0, 51, 102, 0.5), 1); // #003366
===
@debug rgb(#f2ece4, 50%) // rgba(242, 236, 228, 0.5)
@debug rgba(rgba(0, 51, 102, 0.5), 1) // #003366
<% end %>
<% end %>