[css-env] Add first draft of Environment Variables.

Author: tabatkins

css-env-1/Overview.bs

@@ -0,0 +1,155 @@
+<pre class='metadata'>
+Title: CSS Environment Variables Module Level 1
+Shortname: css-env
+Level: 1
+Status: UD
+Group: CSSWG
+URL: https://drafts.csswg.org/css-env-1/
+Editor: Tab Atkins-Bittner, Google
+Editor: Dean Jackson, Apple
+Abstract: This specification defines the concept of [=environment variables=] and the ''env()'' function, which work similarly to custom properties and the ''var()'' function, but are defined globally for a document. These can be defined either by the User Agent, providing values that can be used on the page based on information the UA has special access to, or provided by the author for "global" variables that are guaranteed to be the same no matter where in the document they're used.
+</pre>
+
+Introduction {#intro}
+=====================
+
+The [[css-variables-1]] specification defined the concept of "cascading variables",
+author-defined variables created from the value of [=custom properties=],
+capable of being substituted into arbitrary other properties via the ''var()'' function.
+
+This specification defines a related, but simpler, concept of [=environment variables=].
+Unlike "cascading variables",
+which can change thruout the page as their corresponding [=custom property=] takes on different values,
+an [=environment variable=] is "global" to a particular document--
+its value is the same everywhere.
+The ''env()'' function can then be used to substitute the value into arbitrary locations,
+similar to the ''var()'' function.
+
+These "global" variables have both benefits and downsides versus cascading variables:
+
+* Many variables aren't meant to change over the course of a page;
+	they set up themes,
+	or are helpers for particular numerical values.
+	Using [=environment variables=] instead of [=custom properties=] to define these
+	communicates the proper intent,
+	which is good both for the author of the document
+	(particularly when multiple people are collaborating on a single document),
+	and for the user agent,
+	as it can store these variables in a more optimal way.
+* Because [=environment variables=] don't depend on the value of anything drawn from a particular element,
+	they can be used in places where there is no obvious element to draw from,
+	such as in ''@media'' rules,
+	where the ''var()'' function would not be valid.
+* Information from the User Agent itself,
+	such as the margin of the viewport to avoid laying out in by default
+	(for example, to avoid overlapping a "notch" in the screen),
+	can be retrieved via ''env()'',
+	whereas the element-specific nature of ''var()'' was not an appropriate place to pipe that information in.
+
+Environment Variables {#environment}
+====================================
+
+A CSS <dfn for=CSS>environment variable</dfn> is a name associated with a <<declaration-value>>
+(a sequence of zero more CSS tokens, with almost no restrictions on what tokens can exist),
+similar to a [=custom property=].
+[=Environment variables=] can be defined by the User Agent,
+or by the user.
+(In the latter case, the names are <<custom-property-name>>s,
+and start with `--` per standard for custom identifiers.)
+
+Issue: Is the set of UA-defined [=environment variables=] visible to script?
+If so, define an API on {{Document}} to expose them.
+
+Issue: Define how authors can add [=environment variables=],
+preferably both via JS
+and via CSS.
+Note that mixing CSS rules and JS-defined stuff can easily get messy,
+as demonstrated by CSSFontFaceRule vs FontFace...
+
+The following UA-defined [=environment variables=] are officially defined and must be supported,
+tho user agents may define additional undocumented [=environment variables=]:
+
+* Issue: define list of predefined vars
+
+Using Environment Variables: the ''env()'' notation {#env-function}
+===================================================================
+
+In order to substitute the value of an [=environment variable=] into a CSS context,
+use the ''env()'' function:
+
+<pre class=prod>
+	<dfn function>env()</dfn> = env( <<custom-ident>> , <<declaration-value>>? )
+</pre>
+
+The ''env()'' function can be used in place of any part of a value in any property on any element,
+or any part of a value in any descriptor on any [=at-rule=],
+and in several other places where CSS values are allowed.
+
+<div class=issue>
+	Define the full set of places ''env()'' can be used.
+
+	* Should be able to replace any subset of MQ syntax, for example.
+	* Should be able to replace selectors, maybe?
+	* Should it work on a rule level,
+		so you can insert arbitrary stuff into a rule,
+		like reusing a block of declarations?
+</div>
+
+The first argument to ''env()'' provides the name of an [=environment variable=] to be substituted.
+The second argument, if provided, is a fallback value,
+which is used as the substitution value
+when the referenced [=environment value=] does not exist.
+
+Note: The syntax of the fallback, like that of custom properties, allows commas.
+For example, ''env(foo, red, blue)'' defines a fallback of ''red, blue'';
+that is, anything between the first comma and the end of the function is considered a fallback value.
+
+If a property contains one or more ''env()'' functions,
+and those functions are syntactically valid,
+the entire property's grammar must be assumed to be valid at parse time.
+It is only syntax-checked at computed-time,
+after ''env()'' functions have been [=substituted=].
+
+If a descriptor contains one or more ''env()'' functions,
+and those functions are syntactically valid,
+the entire declaration's grammar must be assumed to be valid at parse time.
+It is only syntax-checked after ''env()'' functions have been [=substituted=].
+
+<div algorithm>
+	To <dfn export local-lt=substitute>substitute an env()</dfn> in a property or descriptor:
+
+	1. If the name provided by the first argument of the ''env()'' function
+		is a recognized [=environment variable=],
+		replace the ''env()'' function by the value of the named [=environment variable=].
+
+	2. Otherwise, if the ''env()'' function has a fallback value as its second argument,
+		replace the ''env()'' function by the fallback value.
+		If there are any ''env()'' references in the fallback,
+		[=substitute=] them as well.
+
+	3. Otherwise, the property or descriptor containing the ''env()'' function is [=invalid at computed-value time=].
+</div>
+
+Issue: Define when substitution happens.
+It has to be before ''var()'' substitution.
+Alternately, should ''env()'' substitution happen at parse time,
+so unknown variable names cause it to fail syntax checking?
+There's no particular reason to have it happen at computed-value time,
+like ''var()'' does--
+that was to ensure that [=custom properties=] could inherit their value down
+before they were picked up by a ''var()''.
+
+Issue: When I figure out where else ''env()'' can go,
+define how/when it substitutes.
+
+Environment Variables in Shorthand Properties {#env-in-shorthands}
+------------------------------------------------------------------
+
+Issue: If ''env()'' substitution happens during parsing,
+then this is unnecessary.
+
+The ''env()'' function causes the same difficulties with [=shorthand properties=]
+as the ''var()'' function does.
+When an ''env()'' is used in a [=shorthand property=],
+then,
+it has the same effects as defined in [[css-variables-1#variables-in-shorthands]].