Skip to content

Commit fc34fe4

Browse files
nex3nex3
committed
Some colors function docs
1 parent efc113e commit fc34fe4

File tree

3 files changed

+229
-14
lines changed

3 files changed

+229
-14
lines changed

‎helpers/sass_helpers.rb

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -336,29 +336,37 @@ def _impl_status_row(name, status)
336336
# Renders API docs for a Sass function.
337337
#
338338
# The function's name is parsed from the signature. The API description is
339-
# passed as a Markdown block. If `returns` is passed, it's included as the function's return type.
340-
def function(signature, returns: nil)
341-
name = signature.split("(").first
342-
html = Nokogiri::HTML(_render_markdown(<<MARKDOWN))
339+
# passed as a Markdown block. If `returns` is passed, it's included as the
340+
# function's return type.
341+
#
342+
# Multiple signatures may be passed, in which case they're all included in
343+
# sequence.
344+
def function(*signatures, returns: nil)
345+
names = []
346+
highlighted_signatures = signatures.map do |signature|
347+
name = signature.split("(").first
348+
names << name
349+
html = Nokogiri::HTML(_render_markdown(<<MARKDOWN))
343350
```scss
344351
@function #{signature}
345352
{}
346353
```
347354
MARKDOWN
348-
highlighted_signature = html.css("pre code").children.
349-
drop_while {|el| el.text != "@function"}.
350-
take_while {|el| el.text != "{}"}[1...-1].
351-
map(&:to_html).join.strip
355+
highlighted_signature = html.css("pre code").children.
356+
drop_while {|el| el.text != "@function"}.
357+
take_while {|el| el.text != "{}"}[1...-1].
358+
map(&:to_html).join.strip
359+
end
352360

353-
concat(content_tag :div, [
361+
html = content_tag :div, [
354362
content_tag(:pre, [
355-
content_tag(:code, highlighted_signature)
363+
content_tag(:code, highlighted_signatures.join("\n"))
356364
], class: 'signature highlight scss'),
357-
358365
returns ? content_tag(:div, returns, class: 'return-type') : '',
359-
360366
_render_markdown(capture {yield})
361-
], class: 'function', id: name)
367+
], class: 'function', id: names.first
368+
369+
concat(names[1..-1].inject(html) {|h, n| content_tag(:div, h, id: n)})
362370
end
363371

364372
# A helper method that renders a chunk of Markdown text.

‎source/documentation/functions/colors.html.md.erb

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
title: Color Functions
3+
---
4+
5+
<% function <<SIGNATURE, returns: 'color' do
6+
adjust-color($color,
7+
$red: null, $green: null, $blue: null,
8+
$hue: null, $saturation: null, $lightness: null,
9+
$alpha: null)
10+
SIGNATURE
11+
%>
12+
Increases or decreases one or more properties of `$color` by fixed amounts.
13+
14+
The value passed for each keyword is added to the corresponding property of the
15+
color, and the adjusted color is returned. It's an error to specify an RGB
16+
property (`$red`, `$green`, and/or `$blue`) at the same time as an HSL property
17+
(`$hue`, `$saturation`, and/or `$alpha`).
18+
19+
All optional arguments must be numbers. The `$red`, `$green`, and `$blue`
20+
arguments must be [unitless][] and between -255 and 255 (inclusive). The `$hue`
21+
argument must have either the unit `deg` or no unit. The `$saturation` and
22+
`$lightness` arguments must be between `-100%` and `100%` (inclusive), and may
23+
be unitless. The `$alpha` argument must be unitless and between -1 and 1
24+
(inclusive).
25+
26+
[unitless]: ../values/numbers#units
27+
28+
See also:
29+
30+
* [`scale-color()`](#scale-color) for fluidly scaling a color's properties.
31+
* [`change-color()`](#change-color) for setting a color's properties.
32+
33+
<% example(autogen_css: false) do %>
34+
@debug adjust-color(#6b717f, $red: 15); // #7a717f
35+
@debug adjust-color(#d2e1dd, $red: -10, $blue: 10); // #c8e1e7
36+
@debug adjust-color(#998099, $lightness: -30%, $alpha: -0.4); // rgba(71, 57, 71, 0.6)
37+
===
38+
@debug adjust-color(#6b717f, $red: 15) // #7a717f
39+
@debug adjust-color(#d2e1dd, $red: -10, $blue: 10) // #c8e1e7
40+
@debug adjust-color(#998099, $lightness: -30%, $alpha: -0.4) // rgba(71, 57, 71, 0.6)
41+
<% end %>
42+
<% end %>
43+
44+
<% function 'adjust-hue($color, $degrees)', returns: 'color' do %>
45+
Increases or decreases `$color`'s hue.
46+
47+
The `$hue` must be a number between `-360deg` and `360deg` (inclusive) to add to
48+
`$color`'s hue. It may be [unitless][].
49+
50+
[unitless]: ../values/numbers#units
51+
52+
See also [`adjust-color()`](#adjust-color), which can adjust any property of a
53+
color.
54+
55+
<% example(autogen_css: false) do %>
56+
// This will produce a color with hue 180deg.
57+
@debug adjust-hue(hsl(120deg, 30%, 90%), 60deg); // #deeded
58+
59+
// This will produce a color with hue 60deg.
60+
@debug adjust-hue(hsl(120deg, 30%, 90%), -60deg); // #ededde
61+
62+
// #036 has hue 210deg, so the result has hue 255deg.
63+
@debug adjust-hue(#036, 45); // #1a0066
64+
===
65+
// This will produce a color with hue 180deg.
66+
@debug adjust-hue(hsl(120deg, 30%, 90%), 60deg) // #deeded
67+
68+
// This will produce a color with hue 60deg.
69+
@debug adjust-hue(hsl(120deg, 30%, 90%), -60deg) // #ededde
70+
71+
// #036 has hue 210deg, so the result has hue 255deg.
72+
@debug adjust-hue(#036, 45) // #1a0066
73+
<% end %>
74+
<% end %>
75+
76+
<% function 'alpha($color)', 'opacity($color)', returns: 'color' do %>
77+
Returns the alpha channel of `$color` as a number between 0 and 1.
78+
79+
As a special case, this supports the Internet Explorer syntax
80+
`alpha(opacity=20)`, for which it returns an [unquoted string][].
81+
82+
[unquoted string]: ../documentation/values/strings#unquoted
83+
84+
<% example(autogen_css) do %>
85+
@debug alpha(#e1d7d2); // 1
86+
@debug alpha(rgb(210, 225, 221, 0.4)); // 0.4
87+
@debug alpha(opacity=20); // alpha(opacity=20)
88+
===
89+
@debug alpha(#e1d7d2) // 1
90+
@debug alpha(rgb(210, 225, 221, 0.4)) // 0.4
91+
@debug alpha(opacity=20) // alpha(opacity=20)
92+
<% end %>
93+
<% end %>
94+
95+
alpha($color) / opacity($color) : Gets the alpha component (opacity) of a color.
96+
blue($color) : Gets the blue component of a color.
97+
change-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) : Changes one or more properties of a color.
98+
complement($color) : Returns the complement of a color.
99+
darken($color, $amount) : Makes a color darker.
100+
desaturate($color, $amount) : Makes a color less saturated.
101+
grayscale($color) : Converts a color to grayscale.
102+
green($color) : Gets the green component of a color.
103+
104+
<% function 'hsl($hue, $saturation, $lightness)', returns: 'color' do %>
105+
Returns a color with the given [hue, saturation, and lightness][] and the given
106+
alpha channel.
107+
108+
[hue, saturation, and lightness]: https://en.wikipedia.org/wiki/HSL_and_HSV
109+
110+
The hue is a number between `0deg` and `360deg` (inclusive). The saturation and
111+
lightness are numbers between `0%` and `100%` (inclusive). All these numbers may
112+
be [unitless][].
113+
114+
[unitless]: ../values/numbers#units
115+
116+
<% example(autogen_css: false) do %>
117+
@debug hsl(210deg, 100%, 20%); // #036
118+
@debug hsl(34, 35%, 92%); // #f2ece4
119+
===
120+
@debug hsl(210deg, 100%, 20%) // #036
121+
@debug hsl(34, 35%, 92%) // #f2ece4
122+
<% end %>
123+
<% end %>
124+
125+
<% function 'hsla($hue, $saturation, $lightness, $alpha)', returns: 'color' do %>
126+
<% impl_status dart: true, libsass: false, ruby: '3.7.0' do %>
127+
LibSass and older versions of Ruby Sass don't support alpha values specified as
128+
percentages.
129+
<% end %>
130+
131+
Returns a color with the given [hue, saturation, and lightness][].
132+
133+
[hue, saturation, and lightness]: https://en.wikipedia.org/wiki/HSL_and_HSV
134+
135+
The hue is a number between `0deg` and `360deg` (inclusive). The saturation and
136+
lightness are numbers between `0%` and `100%` (inclusive). All these numbers may
137+
be [unitless][]. The alpha channel can be specified as either a unitless number
138+
between 0 and 1 (inclusive), or a percentage between `0%` and `100%`
139+
(inclusive).
140+
141+
[unitless]: ../values/numbers#units
142+
143+
<% example(autogen_css: false) do %>
144+
@debug hsl(210deg, 100%, 20%, 50%); // rgba(0, 51, 102, 0.5)
145+
@debug hsl(34, 35%, 92%, 0.5); // rgba(242, 236, 228, 0.2)
146+
===
147+
@debug hsl(210deg, 100%, 20%, 50%) // rgba(0, 51, 102, 0.5)
148+
@debug hsl(34, 35%, 92%, 0.5) // rgba(242, 236, 228, 0.2)
149+
<% end %>
150+
<% end %>
151+
152+
hue($color) : Gets the hue component of a color.
153+
ie-hex-str($color) : Converts a color into the format understood by IE filters.
154+
invert($color, [$weight]) : Returns the inverse of a color.
155+
lighten($color, $amount) : Makes a color lighter.
156+
lightness($color) : Gets the lightness component of a color.
157+
mix($color1, $color2, [$weight]) : Mixes two colors together.
158+
opacify($color, $amount) / fade-in($color, $amount) : Makes a color more opaque.
159+
red($color) : Gets the red component of a color.
160+
161+
<% function 'rgb($red, $green, $blue)', returns: 'color' do %>
162+
Returns a color with the given red, green, and blue channels.
163+
164+
Each channel can be specified as either a [unitless][] number between 0 and 255
165+
(inclusive), or a percentage between `0%` and `100%` (inclusive).
166+
167+
[unitless]: ../values/numbers#units
168+
169+
<% example(autogen_css: false) do %>
170+
@debug rgb(0, 51, 102); // #036
171+
@debug rgb(95%, 92.5%, 89.5%); // #f2ece4
172+
===
173+
@debug rgb(0, 51, 102) // #036
174+
@debug rgb(95%, 92.5%, 89.5%) // #f2ece4
175+
<% end %>
176+
<% end %>
177+
178+
<% function 'rgba($red, $green, $blue, $alpha)', returns: 'color' do %>
179+
<% impl_status dart: true, libsass: false, ruby: '3.7.0' do %>
180+
LibSass and older versions of Ruby Sass don't support alpha values specified as
181+
percentages.
182+
<% end %>
183+
184+
Returns a color with the given red, green, blue, and alpha channels.
185+
186+
The red, green, and blue channels can be specified as either a [unitless][]
187+
number between 0 and 255 (inclusive), or a percentage between `0%` and `100%`
188+
(inclusive). The alpha channel can be specified as either a unitless number
189+
between 0 and 1 (inclusive), or a percentage between `0%` and `100%`
190+
(inclusive).
191+
192+
[unitless]: ../values/numbers#units
193+
194+
<% example(autogen_css: false) do %>
195+
@debug rgba(0, 51, 102, 0.5); // rgba(0, 51, 102, 0.5)
196+
@debug rgba(95%, 92.5%, 89.5%, 20%); // rgba(242, 236, 228, 0.2)
197+
===
198+
@debug rgba(0, 51, 102, 0.5) // rgba(0, 51, 102, 0.5)
199+
@debug rgba(95%, 92.5%, 89.5%, 20%) // rgba(242, 236, 228, 0.2)
200+
<% end %>
201+
<% end %>
202+
203+
204+
saturate($color, $amount) : Makes a color more saturated.
205+
saturation($color) : Gets the saturation component of a color.
206+
scale-color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha]) : Fluidly scales one or more properties of a color.
207+
transparentize($color, $amount) / fade-out($color, $amount) : Makes a color more transparent.

‎source/layouts/components/_reference_table_of_contents.haml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
* [Built-In Functions](/documentation/functions)
4646
* [Plain CSS](/documentation/functions/css)
4747
* [Numbers](/documentation/functions/math)
48-
* [Strings](/documentation/functions/strings) <!-- unique-id() goes here -->
48+
* [Strings](/documentation/functions/strings)
4949
* [Colors](/documentation/functions/colors)
5050
* [Lists](/documentation/functions/lists)
5151
* [Maps](/documentation/functions/maps)

0 commit comments

Comments
 (0)