Title: CSS Linked Parameters Module Level 1
Shortname: css-link-params
Level: 1
Status: ED
Group: CSSWG
Work Status: exploring
ED: https://drafts.csswg.org/css-link-params/
Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/
Editor: Daniel Holbert, Mozilla
Editor: Jonathan Watt, Mozilla
Abstract: This spec introduces a way to pass CSS values into linked resources, such as SVG images, so that they can be used as CSS [=custom environment variables=] in the destination resource. This allows easy reuse of "templated" SVG images, which can be adapted to a site's theme color, etc. easily, without having to modify the source SVG.
Ignored Terms: css value definition syntax

spec:selectors-4; type:selector; text::hover
spec:html; type:element
	text: iframe
	text: a
spec:fill-stroke-3; type:property; text:fill
spec:css-env-1; type:function; text:env()

Introduction {#intro} ===================== SVG is stylable with CSS, and when used inline in HTML, this capability can be very useful. For example, an SVG icon can take on a different color based on whether the user is hovering it or not, just by applying a '':hover'' rule to it that changes the 'fill' property. When the SVG is referenced in a way that doesn't allow selectors or CSS inheritance from the outer page to apply to it (such as embedding it via <{img}> or <{iframe}> in HTML), though, this functionality is lost. The only way to change the display of such "external" SVG images is to produce several of them, and change which image you're referencing. This incurs delay on the page as a new resource is downloaded, and disallows dynamic effects like CSS Transitions. CSS link parameters are a way to set CSS custom environment variables on an "external" resource, either by a CSS property or thru a special fragment scheme on the URL. This gives a limited, but powerful, subset of the customizability that "inline" SVG images have to "external" SVG images. A [=link parameter=] is a pair of a <> name, and an arbitrary (possibly empty) <> value.

For example, an SVG image can be written to use [=link parameters=], allowing it to have its colors changed on the fly, like: <svg> <path fill="env(--color, black)" d="..." /> </svg> By default, it will fill its shape with black, as that's the fallback color specified. But [=link parameters=] can customize the color in several ways: <img src="image.svg#param(--color,green)">

		img {
			link-parameters: param(--color, green);
		}

		.foo {
			background-image: url("image.svg", param(--color, green));
		}

Setting a Link Parameter {#setting} =================================== An external resource can be accompanied by a list of [=link parameters=], each entry composed of a <> as a key, and a (possibly empty) <> as the value. There are three ways to specify a [=link parameter=]: * via the 'link-parameters' property, which applies to the resource itself (if the element represents an external resource), and to all external resources used in CSS properties on the element * via a special syntax in the fragment portion of the URL of an external resource * via a ''param()'' argument in the ''url()'' syntax If specified in multiple of these ways, all of the [=link parameters=] are appended into a single list for the external resource, in the order: 1. the 'link-parameters' property on the element, if relevant 2. the [=param()=] URL fragment identifiers 3. the ''param()'' <>s in ''url()'' If multiple [=link parameters=] exist with the same name, the last one in the list is used. How to access [=link parameters=] in the linked resource is defined in the next section, [[#using]]. In CSS: the 'link-parameters' property {#link-param-prop} --------------------------------------

Name: link-parameters
Value: none | <>#
Initial: none
Inherited: no
Applies to: all elements and pseudo-elements
Computed value: as specified
Animation type: discrete

The 'link-parameters' property is one way to set [=link parameters=] on the element itself (if it is an element representing an external resource, such as an HTML <{img}> or <{iframe}>), and on all external CSS resources specified on the element (such as background images, etc). Its values are:

: none :: No [=link parameters=] are specified. : <># :: A list of one or more [=link parameters=]. The param() function specifies a [=link parameter=], with a key of the <>, and a value of the <>?. (If the <> is omitted, it represents an empty value.) It has the syntax:

	<param()> = param( <> , <>? )

In The URL {#url-frag} ---------- A special "fragment identifier" can be used in the fragment of a URL used to reference an external resource. Several examples of existing "fragment identifiers" for SVG documents can be found in the SVG 1.1 specification. The syntax of an SVG parameter fragment identifier is:

param( <> , <>? )

(using the CSS value definition syntax; TODO define an actual parser for it).

For example, to set the ''env(--text-color)'' [=custom environment variable=] of an SVG image to ''blue'', one can reference the image with a url like “http://example.com/image.svg#param(--text-color,blue)”.

Multiple [=link parameters=] can be passed to an image by appending multiple [=param()=] fragment identifiers to the URL. When combined, either with each other or with other "fragment identifiers", each value is separated with an & character, as in a URL's query parameters.

For example, if the image from the previous example also used ''env(--bg-color)'', it could be referenced with a url like “http://example.com/image.svg#param(--text-color,blue)&param(--bg-color,white)” to set both ''env(--text-color)'' and ''env(--bg-color)''.

Note: Spaces, and some other characters that might be valid in CSS syntax, are not technically valid in URLs. In some contexts, you might need to escape those characters to form a valid URL. In most cases, though, such as HTML's <{a}> element or CSS's ''url()'' function, spaces are accepted and do not need to be escaped. Setting via the CSS ''url()'' Function {#setting-url} ----------------------------------------------------- When referencing an external resource via CSS, the param() function can be used in the ''url()'' function. But a common use-case is passing in values of the page's own custom properties; for example, a page might use a ''--primary-color'' custom property, and want to make an SVG image match. There's no way, however, to integrate the value of a custom property in CSS into the URL passed to the ''url()'' function. To accommodate this, ''param()'' is a valid <>. All the ''param()''s specified as a <> define [=link parameters=], as for 'link-parameters'.

For example, if the site is using a ''--primary-color'' custom property to theme its elements with, and wanted an SVG background using ''env(--color)'' to reflect it, it could write:

		.foo {
			background-image: url(
				"http://example.com/image.svg"
				param(--color, var(--primary-color))
			);
		}

Using Link Parameters {#using} ===================== When an external resource link has one or more [=link parameters=] specified, if the linked resource understands CSS (such as an SVG or HTML document), then those [=link parameters=] establish global [=custom environment variables=] for the resource with their name and value, accessible with the ''env()'' function in stylesheets.

For example, if an SVG image wanted to expose a ''--color'' parameter, it could use it like: <svg> <g style="fill: env(--color);"> <path d="..." /> </g> </svg>

It's usually a good idea to make your SVG image usable even if no parameters are given, by providing "default values" for each of the custom properties. There are several ways to do this. 1. On each ''env()'' function, provide a fallback value, like ''fill: env(--color, blue)''. 2. If the ''env()'' is going to be used a lot, such that providing a fallback for each individual ''env()'' is troublesome, store the [=custom environment variable=] in a [=custom property=] on the root element with the default specified, like:

			:root {
				--color: env(--color, blue);
			}

In this example, if ''--color'' is provided via a [=linked parameter=], ''var(--color)'' will contain its value. If not, it will contain the default ''blue'' value. In either case, ''var(--color)'' can be used in the stylesheet unconditionally, secure in the knowledge that it will always have a value.

Privacy Considerations

This specification introduces no new privacy considerations.

Security Considerations

This specification introduces a new way to pass information to a linked resource, potentially from a hostile source. While no explicit handshake is established for this channel, the use of ''env()'' to use the information minimizes the chance that the linked resource can be surprised by the information. The only way for the page to be vulnerable is to somehow be using an unknown ''env()'' in their styles, which will just result in invalid properties by default, and be visible in the developer's Dev Tools. Any hostile information can also only affect individual CSS properties that the resource explicitly opts itself into.