This CSS module defines an API for registering new CSS properties. Properties registered using this API are provided with a parse syntax that defines a type, inheritance behaviour, and an initial value.
Status of this document
This section describes the status of this document at the time of
its publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical report
can be found in the W3C technical reports
index at http://www.w3.org/TR/.
This document is a First Public Working Draft.
Publication as a First Public Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
The (archived) public
mailing list [email protected] (see instructions) is preferred
for discussion of this specification. When sending e-mail, please put the
text “css-properties-values-api” in the subject, preferably like this:
“[css-properties-values-api] …summary of comment…”
This document was produced by groups operating under the 5 February
2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (
CSS,
TAG) made in
connection with the deliverables of the groups; those pages also include
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains Essential
Claim(s) must disclose the information in accordance with section
6 of the W3C Patent Policy.
CSS defines a comprehensive set of properties that can be manipulated in order
to modify the layout, paint, or behaviour of a web document. However, web authors
frequently wish to extend this set with additional properties.
[css-variables] provides primitive means for defining user-controlled properties,
however these properties always take token lists as values, must always inherit, and
can only impact document layout or paint by being re-incorporated into the value
of other properties via a var() reference.
This specification extends [css-variables], allowing the registration of properties
that have a value type, an initial value, and a defined inheritance behaviour.
This specification is complementary to [css-paint-api] and [css-layout-api], which
allow custom properties to directly impact paint and layout behaviours respectively.
A PropertyDescriptor dictionary represents author-specified configuration
options for a custom property. PropertyDescriptor dictionaries contain the
following members:
For example, "3cm" is a computationally idempotent length, and hence valid as an initial value.
However, "3em" is not (depending on the environment, 3em could compute to
multiple different values). Additionally, "var(--foo)" is not computationally idempotent.
define computational idempotency.
Is computational idempotency the right thing to do here? We could also just
resolve any relative values once (against all the other initial values) and use
that. OR! We could allow specified values and just fix our engines...
When a custom property is registered with a given type, the process via which specified
values for that property are turned into computed values is defined
fully by the type selected, as described in §2.4 Calculation of Computed Values.
If registerProperty() is called with a descriptor name that matches an already registered property,
then an InvalidModificationError is thrown and the re-registration fails.
Properties can be unregistered using unregisterProperty(DOMString name).
If this function is called with a name that doesn’t match an existing property
then a NotFoundError is thrown.
Successful calls to both registerProperty() and unregisterProperty() change the set of registered properties. When the set of registered properties
changes, previously syntactically invalid property values can become valid and vice versa.
This can change the set of declared values which requires the cascade to
be recomputed.
By default, all custom property declarations that can be parsed as a sequence of tokens
are valid. Hence, the result of this stylesheet:
is to set the color property of elements of class "thing" to "inherit".
The second --my-color declaration overrides the first at parse time (both are valid),
and the var reference in the color property is found to be invalid at computation time
(because url("not-a-color") is not a color). At computation time the only
available fallback is the default value, which in the case of color is "inherit".
if we call:
registerProperty({name:"--my-color",syntax:""});
then the second --my-color declaration becomes syntactically invalid, which means that
the cascade uses the first declaration. The color therefore switches to green.
2.3. Supported syntax strings
The following syntax strings are supported:
""
Any valid value
""
values
""
Any valid value
""
Any valid or value, any valid expression combining and components.
""
Any valid value
""
Any valid value
""
Any valid value
""
Any valid value
""
Any valid value
"
Any valid value
""
Any valid value
""
Any valie value
""
Any valid value
Any string, the contents of which matches the production
That identifier
Any one of the preceding strings, followed by '+'
A list of values of the type specified by the string
Any combination of the preceding, separated by '|'
Any value that matches one of the items in the combination, matched in specified order.
"*"
Any valid token stream
Note: [css3-values] maintains a distinction between properties that accept
only a length, and properties that accept both a length and a percentage,
however the distinction doesn’t currently cleanly line up with the productions.
Accordingly, this specification introduces the length-percentage production
for the purpose of cleanly specifying this distinction.
Regardless of the syntax specified, all custom properties will accept CSS-wide keywords as well as revert, and process these values
appropriately.
For example, the following are all valid syntax strings.
""
accepts length values
" | "
accepts lengths, percentages, percentage calc expressions, and length calc
expressions, but not calc expressions containing a combination of length
and percentage values.
""
accepts all values that " | " would
accept, as well as calc expresssions containing a combination of both length
and percentage values.
"big | bigger | BIGGER"
accepts the ident "big", or the ident "bigger", or the ident "BIGGER".
"+"
accepts a list of length values.
2.4. Calculation of Computed Values
The syntax of a custom property fully determines how computed values are
generated from specified values for that property.
For values, the computed value is the absolute length expressed in pixels.
For values, the computed value is one of the following:
if the specified value contains only length units, the computed value is the absolute length
expressed in pixels.
if the specified value contains only percentages, the computed value is a
simple percentage.
otherwise, the computed value is a calc expression containing an absolute
length expressed in pixels, and a percentage value.
For , ident, , , , ,
,
For and values which are not calc expressions, the
computed value is identical to the specified value. Calc expressions that are
and values get reduced during computation to simple
numbers and percentages respectively.
For values specified by a syntax string that include "|" clauses, the computed
value is given by applying the calculation rules for the first clause that
matches to the specified value.
For list values, the computed value is a list of the computed values of the
primitives in the list.
3. Behavior of Custom Properties
3.1. Animation Behavior of Custom Properties
Note: As defined by [css3-animations] and [css3-transitions], it is possible to
specify animations and transitions that reference custom properties.
When referenced by animations and transitions, custom properties interpolate
in a manner defined by their types.
If the start and end of an interpolation have matching types, then they
will interpolate as specified in [css3-animations].
Otherwise, the interpolation falls back to the default 50% flip described in [css3-animations].
Intermediate interpolated results of animations on custom properties must
be able to generate a token stream representing their value. We should ensure that
this is standard across implementations to avoid interop issues.
Note: In other words, for the purpose of determining whether a value is
supported by a given custom property, the type registered for the custom property is
ignored and any value consisting of at least one token is considered valid.
should @supports pay attention to type when considering custom properties?
4. Examples
4.1. Example 1: Using custom properties to add animation behavior
There are no known security issues introduced by these features.
6. Privacy Considerations
There are no known privacy issues introduced by these features.
Conformance
Document conventions
Conformance requirements are expressed with a combination of
descriptive assertions and RFC 2119 terminology. The key words “MUST”,
“MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
“RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this
document are to be interpreted as described in RFC 2119.
However, for readability, these words do not appear in all uppercase
letters in this specification.
All of the text of this specification is normative except sections
explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for example”
or are set apart from the normative text with class="example",
like this:
This is an example of an informative example.
Informative notes begin with the word “Note” and are set apart from the
normative text with class="note", like this:
Note, this is an informative note.
Advisements are normative sections styled to evoke special attention and are
set apart from other normative text with , like
this: UAs MUST provide an accessible alternative.
Conformance classes
Conformance to this specification
is defined for three conformance classes:
A style sheet is conformant to this specification
if all of its statements that use syntax defined in this module are valid
according to the generic CSS grammar and the individual grammars of each
feature defined in this module.
A renderer is conformant to this specification
if, in addition to interpreting the style sheet as defined by the
appropriate specifications, it supports all the features defined
by this specification by parsing them correctly
and rendering the document accordingly. However, the inability of a
UA to correctly render a document due to limitations of the device
does not make the UA non-conformant. (For example, a UA is not
required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification
if it writes style sheets that are syntactically correct according to the
generic CSS grammar and the individual grammars of each feature in
this module, and meet all other conformance requirements of style sheets
as described in this module.
Partial implementations
So that authors can exploit the forward-compatible parsing rules to
assign fallback values, CSS renderers must treat as invalid (and ignore
as appropriate) any at-rules, properties, property values, keywords,
and other syntactic constructs for which they have no usable level of
support. In particular, user agents must not selectively
ignore unsupported component values and honor supported values in a single
multi-value property declaration: if any value is considered invalid
(as unsupported values must be), CSS requires that the entire declaration
be ignored.
Experimental implementations
To avoid clashes with future CSS features, the CSS2.1 specification
reserves a prefixed
syntax for proprietary and experimental extensions to CSS.
Prior to a specification reaching the Candidate Recommendation stage
in the W3C process, all implementations of a CSS feature are considered
experimental. The CSS Working Group recommends that implementations
use a vendor-prefixed syntax for such features, including those in
W3C Working Drafts. This avoids incompatibilities with future changes
in the draft.
Non-experimental implementations
Once a specification reaches the Candidate Recommendation stage,
non-experimental implementations are possible, and implementors should
release an unprefixed implementation of any CR-level feature they
can demonstrate to be correctly implemented according to spec.
To establish and maintain the interoperability of CSS across
implementations, the CSS Working Group requests that non-experimental
CSS renderers submit an implementation report (and, if necessary, the
testcases used for that implementation report) to the W3C before
releasing an unprefixed implementation of any CSS features. Testcases
submitted to W3C are subject to review and correction by the CSS
Working Group.
Further information on submitting testcases and implementation reports
can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/.
Questions should be directed to the [email protected] mailing list.
Is computational idempotency the right thing to do here? We could also just
resolve any relative values once (against all the other initial values) and use
that. OR! We could allow specified values and just fix our engines... ↵
Intermediate interpolated results of animations on custom properties must
be able to generate a token stream representing their value. We should ensure that
this is standard across implementations to avoid interop issues. ↵
should @supports pay attention to type when considering custom properties? ↵