[css-color] Add intro to the API section.

Author: tabatkins

css-color/Overview.bs

@@ -2466,7 +2466,49 @@ Default Style Rules</h2>
 <h2 id='apis'>
 APIs for Parsing and Manipulating Colors</h2>
 
-	Issue: This section is in the process of being written and cleaned up.
+	In many applications, authors have to use and manipulate colors.
+	CSS allows many different useful syntaxes for colors,
+	but these are only usable in stylesheets,
+	not in script.
+
+	This section defines a number of APIs for creating and manipulating colors in script:
+
+	<ul>
+		<li>
+			It allows CSS colors to be parsed into JS objects--
+			use the <code>CSSColor.parse("rebeccapurple")</code> method to get a corresponding color object,
+			or one of the specific color constructors,
+			like <code>new HSLColor("rebeccapurple")</code>,
+			to get back a specific type of color class.
+
+		<li>
+			It allows colors to be manipulated in any of the syntaxes that CSS exposes:
+			<a idl>RGBColor</a> for RGBA colors, with components ranging from 0-1;
+			<a idl>HexColor</a> for RGBA colors, with components ranging from 0-255;
+			<a idl>HSLColor</a> for HSLA colors, corresponding to the ''hsla()'' syntax;
+			and <a idl>CMYKColor</a> for CMYK colors, corresponding to the ''device-cmyk()'' syntax.
+
+			All of these expose their components as attributes you can manipulate directly,
+			and colors can be easily converted between any of the classes with methods like <code>toRGB()</code> and <code>toHSL()</code>.
+
+		<li>
+			It allows colors to be automatically stringified back into a form that CSS understands,
+			so you can write code like:
+
+			<pre>
+			var c = new HSLColor("red");
+			c.l += .1;
+			el.style.backgroundColor = c;
+			// c is automatically turned into the string "rgba(100%, 20%, 20%, 100%)"
+			</pre>
+
+			If you wish, you can control what type of syntax it stringifies as,
+			like <code>c.toString("hsl")</code>.
+
+		<li>
+			It's explicitly designed to be easy to extend with new methods and new color types,
+			and gives guidance to help you do it correctly (see <a section href="#api-extending"></a>).
+	</ul>
 
 <h3 id='api-RGBColor'>
 The RGBColor Object</h3>

css-color/Overview.html

@@ -2589,7 +2589,48 @@ <h2 class="heading settled heading" data-level=14 id=sample><span class=secno>14
 <h2 class="heading settled heading" data-level=15 id=apis><span class=secno>15 </span><span class=content>
 APIs for Parsing and Manipulating Colors</span><a class=self-link href=#apis></a></h2>
 
-<p class=issue id=issue-dc028349><a class=self-link href=#issue-dc028349></a>This section is in the process of being written and cleaned up.</p>
+<p>In many applications, authors have to use and manipulate colors.
+	CSS allows many different useful syntaxes for colors,
+	but these are only usable in stylesheets,
+	not in script.</p>
+
+<p>This section defines a number of APIs for creating and manipulating colors in script:</p>
+
+	<ul>
+		<li>
+			It allows CSS colors to be parsed into JS objects—<wbr>use the <code>CSSColor.parse("rebeccapurple")</code> method to get a corresponding color object,
+			or one of the specific color constructors,
+			like <code>new HSLColor("rebeccapurple")</code>,
+			to get back a specific type of color class.
+
+		<li>
+			It allows colors to be manipulated in any of the syntaxes that CSS exposes:
+			<a data-link-type=idl href=#dom-rgbcolor title=rgbcolor>RGBColor</a> for RGBA colors, with components ranging from 0-1;
+			<a data-link-type=idl href=#dom-hexcolor title=hexcolor>HexColor</a> for RGBA colors, with components ranging from 0-255;
+			<a data-link-type=idl href=#dom-hslcolor title=hslcolor>HSLColor</a> for HSLA colors, corresponding to the <a class=css data-link-type=maybe href=#funcdef-hsla title=hsla()>hsla()</a> syntax;
+			and <a data-link-type=idl href=#dom-cmykcolor title=cmykcolor>CMYKColor</a> for CMYK colors, corresponding to the <a class=css data-link-type=maybe href=#funcdef-device-cmyk title=device-cmyk()>device-cmyk()</a> syntax.
+
+<p>All of these expose their components as attributes you can manipulate directly,
+			and colors can be easily converted between any of the classes with methods like <code>toRGB()</code> and <code>toHSL()</code>.</p>
+
+		<li>
+			It allows colors to be automatically stringified back into a form that CSS understands,
+			so you can write code like:
+
+			<pre>var c = new HSLColor("red");
+c.l += .1;
+el.style.backgroundColor = c;
+// c is automatically turned into the string "rgba(100%, 20%, 20%, 100%)"
+</pre>
+
+<p>If you wish, you can control what type of syntax it stringifies as,
+			like <code>c.toString("hsl")</code>.</p>
+
+		<li>
+			It’s explicitly designed to be easy to extend with new methods and new color types,
+			and gives guidance to help you do it correctly (see <a data-section="" href=#api-extending>§15.5 
+Extending the Color Classes</a>).
+	</ul>
 
 <h3 class="heading settled heading" data-level=15.1 id=api-RGBColor><span class=secno>15.1 </span><span class=content>
 The RGBColor Object</span><a class=self-link href=#api-RGBColor></a></h3>
@@ -4428,6 +4469,4 @@ <h2 class="no-num heading settled" id=issues-index><span class=content>Issues In
 		Really?  Shouldn’t video be consistent with images?
 		Or do implementations really do this differently?
 
-	<a href=#issue-9c7b92e0> ↵ </a></div><div class=issue>This section is in the process of being written and cleaned up.<a href=#issue-dc028349> ↵ </a></div>
-
-</div>
+	<a href=#issue-9c7b92e0> ↵ </a></div></div>