<pre class='metadata'>
Title: CSS Environment Variables Module Level 1
Shortname: css-env
Level: 1
Status: ED
Work Status: exploring
Group: CSSWG
URL: https://drafts.csswg.org/css-env-1/
Editor: Tab Atkins-Bittner, Google, w3cid 42199
Editor: Dean Jackson, Apple, w3cid 42080
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>

<pre class=link-defaults>
spec:dom; type:interface; text:Document
spec:css-variables-1; type:dfn; text:invalid at computed-value time
</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.
Additional UA-defined [=environment variables=] *must not* be supported
unless/until they are added to this list.

<index type=value for=env()></index>

Safe area inset variables {#safe-area-insets}
------------------------------------------------------------------

<table dfn-type=value dfn-for="env()">
	<tr>
		<th>Name
		<th>Value
	<tr>
		<td><dfn>safe-area-inset-top</dfn>
		<td><<length>>
	<tr>
		<td><dfn>safe-area-inset-right</dfn>
		<td><<length>>
	<tr>
		<td><dfn>safe-area-inset-bottom</dfn>
		<td><<length>>
	<tr>
		<td><dfn>safe-area-inset-left</dfn>
		<td><<length>>
</table>

The safe area insets are four [=environment variables=] that define a rectangle by
its top, right, bottom, and left insets from the edge of the viewport. For rectangular
displays, these must all be zero, but for nonrectangular displays they must form a
rectangle, chosen by the user agent, such that all content inside the rectangle is
visible, and such that reducing any of the insets would cause some content inside of
the rectangle to be invisible due to the nonrectangular nature of the display. This
allows authors to limit the layout of essential content to the space inside of the
safe area rectangle.

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 variable=] 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]].
