1. 序論
~INFORMATIVE巨大な文書や~appは（あるいは小さなものですら）、相当量の~CSSを含み得る。 ~CSS~fileの中の値の多くは、同じ~dataを繰り返すことになる。 例えば、色の~~体系を確立して，全体を通して数個の色を再利用している~siteがあったとする。 この~dataを改めることは、~CSS~fileの中に散らばっている（あるいは複数~fileにわたっている）がために，難しく誤り易い~~作業にもなりかねず、また，検索置換も容易になるとは限らない。 ◎ Large documents or applications (and even small ones) can contain quite a bit of CSS. Many of the values in the CSS file will be duplicate data; for example, a site may establish a color scheme and reuse three or four colors throughout the site. Altering this data can be difficult and error-prone, since it’s scattered throughout the CSS file (and possibly across multiple files), and may not be amenable to Find-and-Replace.
この~moduleは、`~custom~prop$と~~総称される，作者により定義される~propの族を導入する。 それは、~stylesheet作者が，自身が選んだ名前による~propに任意の値を割当てて、 `var$f 関数を通して，その値を文書~内の至る所にある他の~propに利用できるようにする。 これにより、見かけからは~~意味を汲み取れない値にも，用途に見合った~~体系的な名前を付けられるようになり、巨大な~fileも読み易くなる。 また、`~custom~prop$の中で一箇所の値を変更するだけで，それが定義する変数を利用している箇所すべてに自動的に伝播することになるので、その種の~file編集も格段に容易かつ誤り難くなる。 ◎ This module introduces a family of custom author-defined properties known collectively as custom properties, which allow an author to assign arbitrary values to a property with an author-chosen name, and the var() function, which allow an author to then use those values in other properties elsewhere in the document. This makes it easier to read large files, as seemingly-arbitrary values now have informative names, and makes editing such files much easier and less error-prone, as one only has to change the value once, in the custom property, and the change will propagate to all uses of that variable automatically.
2. ~custom~propを定義する： ~propの族 `--*^p
この仕様は、`~custom~prop$と呼ばれる，~propの~~自由な（ `open-ended^en ）集合を定義する。 それは、他の~prop値の中の `var$f 関数の代用~値（ `substitution value^en ） — `var$f を置換することになる値 — を定義するために利用される。 ◎ This specification defines an open-ended set of properties called custom properties, which, among other things, are used to define the substitution value of var() functions.
◎名 `--*@p ◎値 `declaration-value$t ◎初 （ “空~値” — 注釈文を見よ） ◎ (nothing, see prose) ◎適 すべての要素 ◎継 される ◎百 受容しない ◎算 値の中の変数（ `var$f ）は`代用され$た結果の，指定値（ただし、無効な変数についての注釈文も見よ） ◎ specified value with variables substituted (but see prose for "invalid variables") ◎順 文法に従う ◎ア 不可 ◎表終~UAには、視覚的でないものも含む すべての媒体~上で，この~propを~supportすることが期待される。 ◎ User Agents are expected to support this property on all media, including non-visual ones.
`~custom~prop@ は、 "`--^c" から開始される任意の名前の~propである。 例えば `--foo^p の様に。 `custom-property-name@t 生成規則がこれに対応する — それは、［ 2 個の dash から開始される，任意の妥当な`識別子$ ］として，定義される。 `~custom~prop$は、もっぱら作者／利用者から利用されるものである。 ~CSSがここに示されるものを超える意味を与えることは決してない。 ◎ A custom property is any property whose name starts with two dashes (U+002D HYPHEN-MINUS), like --foo. The <custom-property-name> production corresponds to this: it’s defined as any valid identifier that starts with two dashes. Custom properties are solely for use by authors and users; CSS will never give them a meaning beyond what is presented here.
【 この名前は、~vendor接頭辞~付きの~prop（例： `-webkit-foo^p ）から~vendor接頭辞を取り除いたもの（例： `--foo^p ）と捉えることもできる（すなわち、作者~自身が “匿名の~vendor” である）。 そのような捉え方を意図して命名されているのかもしれない。 】
~custom~propは、多目的に利用できる変数を定義し， `var$f 記法で参照される。 例えば，一群の色を一貫して~designに利用する~pageは、それらの色を~custom~propに格納した上で，変数を通して利用できる： ◎ Custom properties define variables, referenced with the var() notation, which can be used for many purposes. For example, a page that consistently uses a small set of colors in its design can store the colors in custom properties and use them with variables:
`root$ps {
--main-color: #06c;
--accent-color: #006;
}
/*
~CSS~fileの残りの部分
◎
The rest of the CSS file
*/
#foo h1 {
`color$p: var(--main-color);
}
覚え易い色の命名により、色~codeの中の見つけ難い誤記は防がれ，~theme色が絶えず変更されるような場合でも、~web~page内のすべての~stylesheetに渡って多数の編集を行わずとも，単純な一箇所（~custom~prop値）の変更に集中すれば済むようになる。 ◎ The naming provides a mnemonic for the colors, prevents difficult-to-spot typos in the color codes, and if the theme colors are ever changed, focuses the change on one simple spot (the custom property value) rather than requiring many edits across all stylesheets in the webpage.
【 `var(--main-color)^v が参照するのは，［［ それを利用する~prop ］が適用される要素 ］上の `--main-color^p ~propの値になる。 この例では， `--main-color^p が文書の~根~要素~上（ `root$ps ）に宣言されているので、その値は，普通の継承~propと同様に文書~内のどの要素にも（別の `--main-color^p で上書きされない限り）継承され、その結果，どの `var(--main-color)^v も値 `#06c^v で代用されることになる。 】
他の~CSS~propと異なり、~custom~prop名の文字大小は， 区別される。 ◎ Unlike other CSS properties, custom property names are case-sensitive.
`--foo^p, `--FOO^p のいずれも名前として妥当であるが，それらは別々の~propであり、 `var(--foo)^v の利用は前者を指す一方, `var(--FOO)^v の利用は後者を指すことになる。 ◎ While both --foo and --FOO are valid, they are distinct properties - using var(--foo) will refer to the first one, while using var(--FOO) will refer to the second.
~custom~propは，`all$p ~propにより再設定されることはない。 将来には、すべての変数を再設定する~propも~~考えられている。 ◎ Custom properties are not reset by the all property. We may define a property in the future that resets all variables.
他の任意の~propと同じ意味で、~custom~propにも `~CSS全域~keyword$を利用できる。 ◎ The CSS-wide keywords can be used in custom properties, with the same meaning as in any another property.
注記： すなわち それらは、通常通りに `~cascaded値$の時点で解釈され，~custom~prop値のように保全されることはない†。 したがって，対応する変数が解決される時点で代用されることもない。 ◎ Note: That is, they’re interpreted at cascaded-value time as normal, and are not preserved as the custom property’s value, and thus are not substituted in by the corresponding variable.
【† すなわち，~custom~propに対する全域~keyword値は、 `var$f 関数が解決される前 — 算出値を得る前 — の段階で，`指定値$（すなわち，初期値または継承値）にされる。 例えば，次の~stylesheet：
p {
--foo: inherit;
color: var(--foo);
}
における `var(--foo)^v は、［ `inherit^v ではなく， `--foo^p が継承する値 ］で代用されることになる。 したがって、 `p^e 要素の `color^p は，その先祖の［ `color^p ではなく, `--foo^p ］~propの値をとることになる。 】
注記： この~moduleは、 “変数” を作成するための， `var$f による`~custom~prop$の用法に力点を置いているが、~scriptから構文解析-／作動されるような，実際の~custom~propとしても利用し得る。 CSS Extensions 仕様 `CSS-EXTENSIONS$r が、これらの~利用~事例について拡張し，より利用し易くするものと期待されている。 ◎ Note: While this module focuses on the use of custom properties with the var() function to create “variables”, they can also be used as actual custom properties, parsed by and acted on by script. It’s expected that the CSS Extensions spec [CSS-EXTENSIONS] will expand on these use-cases and make them easier to do.
2.1. ~custom~prop値の構文
`~custom~prop$に許容される構文は極めて寛容にされている。 `declaration-value$t 生成規則は、 1 個~以上の~tokenの並びであって, 次に挙げる~tokenは含まないような， 任意の 並びに合致する：
- `bad-string-token$P
- `bad-url-token$P
- 対を成さない，括弧類： `)-token$P, `]-token$P, `}-token$P
- ~top-levelの `semicolon-token$P
- ~top-levelの, 値に "`!^c" を伴う，`delim-token$P
加えて、`~custom~prop$の値が `var$f 参照を含んでいる場合、その `var$f 参照は，指定された `var$f 文法に則って妥当で~MUST。 さもなければ、`~custom~prop$は無効であり，無視され~MUST。 ◎ In addition, if the value of a custom property contains a var() reference, the var() reference must be valid according to the specified var() grammar. If not, the custom property is invalid and must be ignored.
注記： この定義と一般~CSS構文~規則から、~custom~prop値は，対を成さない引用符や括弧類を決して含まず、再び直列化される際には，それを囲っている~style規則などの, より大きな構文~構成子には~~影響しないことになる。 ◎ Note: This definition, along with the general CSS syntax rules, implies that a custom property value never includes an unmatched quote or bracket, and so cannot have any effect on larger syntax constructs, like the enclosing style rule, when reserialized.
注記： ~custom~propは末尾に `!important$css を含み得るが、これは~CSS構文解析器†により~propの値から自動的に除去された上で，~custom~propを~CSS~cascadeの中で “important” にする。 言い換えれば、~top-levelの "`!^c" 文字の禁則は， `!important^css の利用を妨げるものではない。 `!important^css は構文~検査の前に除去されるので。 ◎ Note: Custom properties can contain a trailing !important, but this is automatically removed from the property’s value by the CSS parser, and makes the custom property "important" in the CSS cascade. In other words, the prohibition on top-level "!" characters does not prevent !important from being used, as the !important is removed before syntax checking happens.
【 † CSS Syntax 仕様 にて定義される，~CSS構文解析器（各種~CSS仕様に固有の構文を解析するものではなく，その前~段階の一般~構文を解析する構文解析器）を指す。 この仕様に現れる語 構文解析-の多くも，同様の意味。 】
注記： `declaration-value$t は，少なくとも 1 個~以上の~tokenを表現し~MUSTが、その 1 個の~tokenが空白であってもよい。 したがって、 `--foo: ;^css は妥当であり，対応する `var(--foo)^v の呼び出しは、 1 個の~spaceをその代用~値に持つことになる。 一方で `--foo:;^css は無効になる。 ◎ Note: While <declaration-value> must represent at least one token, that one token may be whitespace. This implies that --foo: ; is valid, and the corresponding var(--foo) call would have a single space as its substitution value, but --foo:; is invalid.
例えば，次のものは妥当な~custom~propである： ◎ For example, the following is a valid custom property:
--foo: if(x > 5) this.width = 10;
この値は、通常のどの~propの中でも無効なので，変数 としては明らかに無用であるが、 JavaScript により読取る／動作させるような用途はあり得る。 ◎ While this value is obviously useless as a variable, as it would be invalid in any normal property, it might be read and acted on by JavaScript.
［ ~custom~propの値, および ~custom~propの値で代用される `var$f 関数の値 ］の文字大小は、区別され，作者が与えた元々の文字大小が保全され~MUST。 （多くの~CSS値は，`~ASCII大小無視$であり、~UAは それらを大小いずれかに “正準化-” できるが、~custom~propには それは許容されない。） ◎ The values of custom properties, and the values of var() functions substituted into custom properties, are case-sensitive, and must be preserved in their original author-given casing. (Many CSS values are ASCII case-insensitive, which user agents can take advantage of by "canonicalizing" them into a single casing, but that isn’t allowed for custom properties.)
`~custom~prop$の`初期値$は空~値，すなわち 何も無い — `nothing^en である。 この初期値は， `var$f 記法に対する特別な作用を持つ。 ~~詳細は `var$f を定義する節にて。 ◎ The initial value of a custom property is an empty value; that is, nothing at all. This initial value has a special interaction with the var() notation, which is explained in the section defining var().
~custom~propは “普通の” ~propであり，どの要素~上にも宣言できる。 それは、通常の継承0と~cascade規則に従って解決され， `media$at その他の`条件付き規則$にも仕立て上げれる。 また、 HTML の `style^a 属性の中でも利用でき， CSSOM を利用して読取る／設定することもできる，等々…。 ◎ Custom properties are ordinary properties, so they can be declared on any element, are resolved with the normal inheritance and cascade rules, can be made conditional with @media and other conditional rules, can be used in HTML’s style attribute, can be read or set using the CSSOM, etc.
特に、それらは遷移させたり~animateさせることすらできる — ただし、~UAには，それらの内容を解釈するすべがないので、他の，補間が利かない値~pairに対するときと同様に、常に， “50% の所で裏返す” 様なふるまいになる。 また、 @keyframes 規則の中で利用される 【宣言される】 どの`~custom~prop$も， `~animationに染って@ いるとされ、各種~animation~prop（ `animation-*^p ）の中で `var$f 関数を通して参照されたときの扱われ方に影響する。 ◎ Notably, they can even be transitioned or animated, but since the UA has no way to interpret their contents, they always use the "flips at 50%" behavior that is used for any other pair of values that can’t be intelligently interpolated. However, any custom property used in a @keyframes rule becomes animation-tainted, which affects how it is treated when referred to via the var() function in an animation property.
次の~style規則： ◎ This style rule:
:root {
--header-color: #06c;
}
は、根~要素~上に名前 `--header-color^p の`~custom~prop$を宣言し，値 "`#06c^v" を割当てる。 この~propは、文書の残りの部分の要素に継承される。 その値は `var$f 関数を通して参照できるようになる： ◎ declares a custom property named --header-color on the root element, and assigns to it the value "#06c". This property is then inherited to the elements in the rest of the document. Its value can be referenced with the var() function:
h1 { `background-color$p: var(--header-color); }
この規則は、 `background-color^p: `#06c^v; と記すことに等価であるが、変数~名から色の用途が明瞭になることに加え、根~要素~上の `--header-color^p ~propを変更すれば，文書~内の他の要素~上で利用されているすべての `var(--header-color)^v が，一括して更新される。 ◎ The preceding rule is equivalent to writing background-color: #06c;, except that the variable name makes the origin of the color clearer, and if var(--header-color) is used on other elements in the document, all of the uses can be updated at once by changing the --header-color property on the root element.
同じ名前の`~custom~prop$が複数回 宣言されている場合、標準の~cascade規則を利用して解決される。 変数は常に，同じ要素~上に結付けられている~custom~propの`算出値$から値を取り出す： ◎ If a custom property is declared multiple times, the standard cascade rules help resolve it. Variables always draw from the computed value of the associated custom property on the same element:
:root { --color: blue; }
div { --color: green; }
#alert { --color: red; }
* { color: var(--color); }
<p>僕は根~要素から `blue^v を継承しています。</p> <div>俺には `green^v が直に設定されている。</div> <div id='alert'> 私は `red^v が直に設定されているわ。 <p>私も `red^v 。でも直にではなく継承0よ。</p> </div> ◎ <p>I inherited blue from the root element!</p> <div>I got green set directly on me!</div> <div id='alert'> While I got red set directly on me! <p>I’m red too, because of inheritance!</p> </div>
現実における`~custom~prop$の用例として、文字列を その利用箇所から容易に外へ分離して，国際化の保守を援助することが挙げられる： ◎ A real-world example of custom property usage is easily separating out strings from where they’re used, to aid in maintenance of internationalization:
:root,
:root:lang(en) {--external-link: "external link";}
:root:lang(de) {--external-link: "externer Link";}
:root:lang(ja) {--external-link: "~~外部~~リンク";}
a[href^="http"]::after {
content: " (" var(--external-link) ")"
}
変数の宣言を別~fileに分けて，翻訳の保守をより単純にすることもできる。 ◎ The variable declarations can even be kept in a separate file, to make maintaining the translations simpler.
2.2. 循環依存の解決法
`~custom~prop$は、ほとんどの所では，評価されないままにされるが、その値の中の `var$f 関数の評価-は許容されている。 そのため、`~custom~prop$自身が，自身を指す `var$f を利用していたり、複数の`~custom~prop$のそれぞれが，他方を指している場合に、循環依存が生じ得る。 ◎ Custom properties are left almost entirely unevaluated, except that they allow and evaluate the var() function in their value. This can create cyclic dependencies where a custom property uses a var() referring to itself, or two or more custom properties each attempt to refer to each other.
各~要素に対し、各`~custom~prop$に対応する~nodeからなる有向~依存関係~graphを作成する： ある`~custom~prop$ %prop1 の値に，ある`~custom~prop$ %prop2 （ %prop1 と同じでもよい） を指している `var$f 関数が含まれている（ `var$f の~fallback引数も込みで）ならば、 %prop1 とその %prop2 を辺で繋ぐ。 依存関係~graphの中に循環が在るならば、その循環~内の`~custom~prop$すべての算出値は，それらの初期値（無効なことが保証された値）になる。 ◎ For each element, create a directed dependency graph, containing nodes for each custom property. If the value of a custom property prop contains a var() function referring to the property var (including in the fallback argument of var()), add an edge between prop and the var. Edges are possible from a custom property to itself. If there is a cycle in the dependency graph, all the custom properties in the cycle must compute to their initial value (which is a guaranteed-invalid value).
変数を安全に利用する~custom~propの例を示す： ◎ This example shows a custom property safely using a variable:
:root {
--main-color: #c06;
--accent-background: linear-gradient(
to top, var(--main-color), white
);
}
`--accent-background^p ~propは（あるいは `var(--main-color)^v を利用する他の~propも同様に）、 `--main-color^p ~propが変更されたときに自動的に更新されることになる。 ◎ The --accent-background property (along with any other properties that use var(--main-color)) will automatically update when the --main-color property is changed.
一方で，次のものは、互いに依存する変数の無効な~instanceの例になる： ◎ On the other hand, this example shows an invalid instance of variables depending on each other:
:root {
--one: calc(var(--two) + 20px);
--two: calc(var(--one) - 20px);
}
`--one^p, `--two^p のいずれも、今や長さでなく，それぞれの初期値に算出される。 ◎ Both --one and --two now compute to their initial value, rather than lengths.
重要な点として、`~custom~prop$の値の中のどの `var$f 関数も，`算出値の時点$で解決される 【`代用され$る】 — したがって、その値が継承されるときには，すでに 解決されている — ことを銘記しておく。 一般に，循環依存が生じるのは、同じ要素~上の複数の~custom~propが互いを指すときに限られる。 要素~木の中で，先祖~側, 子孫~側 2 つの要素~上に定義された~custom~propの間で参照が循環することは、決してない。 ◎ It is important to note that custom properties resolve any var() functions in their values at computed-value time, which occurs before the value is inherited. In general, cyclic dependencies occur only when multiple custom properties on the same element refer to each other; custom properties defined on elements higher in the element tree can never cause a cyclic reference with properties defined on elements lower in the element tree.
【 `算出値の時点@ — 明示的には定義されていないが、`~cascaded値の処理$における，`算出値$を得る段階を指すと見られる。 】
例えば，次の構造における、３個の~custom~propが循環することはない。 すべて妥当な変数を定義する： ◎ For example, given the following structure, these custom properties are not cyclic, and all define valid variables:
<one><two><three /></two></one>
one { --foo: 10px; }
two { --bar: calc(var(--foo) + 10px); }
three { --foo: calc(var(--bar) + 10px); }
`one^e 要素は、 `--foo^p に対する値を定義する。 `two^e 要素は、この値を継承することに加え， `foo^css 変数を利用して `--bar^p に値を割当てる。 最後に， `three^e 要素は、［ 変数が代用された後の `--bar^p 値 ］を継承する（言い換えれば、値 `calc(10px + 10px)^v を見る）。 しかる後，その値を通して自身の `--foo^p を再定義する。 `three^e が継承する `--bar^p 値は， `one^e 上で定義される `--foo^p ~propへの参照を最早~含んでいないので、 `var(--bar)^v 変数を利用して `--foo^p を定義することは循環的ではなく，（通常の~propの中で変数として参照されるときは）実際に最終的に `30px^v に解決される値を定義する。 ◎ The <one> element defines a value for --foo. The <two> element inherits this value, and additionally assigns a value to --bar using the foo variable. Finally, the <three> element inherits the --bar value after variable substitution (in other words, it sees the value calc(10px + 10px)), and then redefines --foo in terms of that value. Since the value it inherited for --bar no longer contains a reference to the --foo property defined on <one>, defining --foo using the var(--bar) variable is not cyclic, and actually defines a value that will eventually (when referenced as a variable in a normal property) resolve to 30px.
3. ~cascade変数の用法： `var^f 記法
`~custom~prop$は、 `var$f 関数を通して別の~propの中で`代用され$得る値を与える。 `var$f の構文は次で与えられる： ◎ The value of a custom property can be substituted into the value of another property with the var() function. The syntax of var() is:
`var@f = var( `custom-property-name$t [, `declaration-value$t ]? )
要素~上の任意の~propの中の値の任意の部分に代えて、この `var$f 関数を利用できる。 `var$f 関数を、~prop値~以外のもの — ~prop名や選択子など — に利用することはできない（そのようにしても、単に無効な構文になるか，変数とは繋がりの無い値になるだけである）。 ◎ The var() function can be used in place of any part of a value in any property on an element. The var() function can not be used as property names, selectors, or anything else besides property values. (Doing so usually produces invalid syntax, or else a value whose meaning has no connection to the variable.)
次の~codeは、~prop名として 変数の利用を試みるので，不正な例になる： ◎ For example, the following code incorrectly attempts to use a variable as a property name:
.foo {
--side: margin-top;
var(--side): 20px;
}
これは `margin-top^p: `20px^v; を設定することに等価でない。 2 個目の宣言は、単に無効な~prop名として構文~errorにされ，棄てられる。 ◎ This is not equivalent to setting margin-top: 20px;. Instead, the second declaration is simply thrown away as a syntax error for having an invalid property name.
関数の最初の引数が、代用~値†を~~供する`~custom~prop$の，名前を与える。 関数に 2 個目の引数が供されている場合、それが~fallback値になり，参照された`~custom~prop$が無効であるときの代用~値として利用される。 ◎ The first argument to the function is the name of the custom property to be substituted. The second argument to the function, if provided, is a fallback value, which is used as the substitution value when the referenced custom property is invalid.
【† 明示的に述べられていないが、代用~値を~~供するのは，［［ `var$f を値に利用する~prop ］が適用される要素 ］上の~custom~propの値になる。 】
注記： ~fallbackの構文でも、`~custom~prop$のそれと同様に，~commaが許容される。 例えば， `var(--foo, red, blue)^v は、~fallback `red, blue^v を定義する。 すなわち，最初の~commaと関数の末尾までの間のすべてが、~fallback値と見なされる。 ◎ Note: The syntax of the fallback, like that of custom properties, allows commas. For example, var(--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.
~fallback値により、一種の安全弁付き~code（ `defensive coding^en ）を書けるようになる。 例えば，より大きな~appに組み込むための~componentを作成する場合、変数をその~style付けに利用すれば，~componentを~appの他の部分と調和させることも容易になる。 ◎ The fallback value allows for some types of defensive coding. For example, an author may create a component intended to be included in a larger application, and use variables to style it so that it’s easy for the author of the larger application to theme the component to match the rest of the app.
~fallbackが無ければ、~app作者は，~componentが利用するすべての変数に値を給さなければならなくなる。 ~fallbackがあれば，~component作者が既定の値を給しておけるようになり、~app作者は，上書きしたい変数だけ値を給すれば済むようになる。 ◎ Without fallback, the app author must supply a value for every variable that your component uses. With fallback, the component author can supply defaults, so the app author only needs to supply values for the variables they wish to override.
/* ~componentの~style ◎ In the component’s style: */ .component .header { color: var(--header-color, blue); } .component .text { color: var(--text-color, black); } /* より大きな~appの~style： ◎ In the larger application’s style: */ .component { --text-color: #080; /* `--header-color^p は設定されないので~fallback値の青（ `blue^v ）のまま。 ◎ header-color isn’t set, and so remains blue, the fallback value */ }
~propに `var$f 関数が含まれていて, そのどれもが構文として妥当である場合、その~propは、構文解析-時には，妥当なものと見做され~MUST。 構文が検査されるのは、 `var$f 関数が`代用され$た後の，`算出値の時点$である。 ◎ If a property contains one or more var() 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-value time, after var() functions have been substituted.
~prop %property の値の中の `var$f `関数^V を `代用する@ （ `substitute^en する）ときは： ◎ To substitute a var() in a property’s value:
- `関数^V の最初の引数を名前に持つ 要素~上の`~custom~prop$を以下 %custom とする。
-
%custom は`~animationに染って$いる, かつ %property が次のいずれかに該当する場合、以下， %custom は初期値をとるものと扱う： ◎ If the custom property named by the first argument to the var() function is animation-tainted, and the var() function is being used in:
- ~animation~prop（ `animation$p ~propまたはその`下位prop$ ）である。 ◎ the animation property or one of its longhands,
- `display$p ~propである，かつ 代用~後に要素の~box生成を抑止する値をとることになる（ `none$v や `contents$v など）。 ◎ the display property, such that after substitution the property would have a value that suppresses the element’s box (such as none or contents) ◎ treat the custom property as having its initial value for the rest of this algorithm.
- %custom が，初期値でない値をとる場合、 `関数^V をその値に置換する。 ◎ If the value of the custom property named by the first argument to the var() function is anything but the initial value, replace the var() function by the value of the corresponding custom property.
- 他の場合、~fallback値が `関数^V の 2 個目の引数として与えられているならば， `関数^V を その~fallback値に置換する。 このとき、その~fallback値の中にも `var$f 参照が在るならば、それらも`代用する$。 ◎ Otherwise, if the var() function has a fallback value as its second argument, replace the var() function by the fallback value. If there are any var() references in the fallback, substitute them as well.
-
他の場合、 %property は，`算出値の時点で無効$になる。 ◎ Otherwise, the property containing the var() function is invalid at computed-value time.
【 %custom が当の要素や そのどの先祖にも宣言されていない場合など — 普通の継承~propと同様に， %custom は初期値をとると解釈されることになるので。 】
注記： %property を`算出値の時点で無効$にするものは、他にもあり得る。 ◎ Note: Other things can also make a property invalid at computed-value time.
注記： `var$f が`代用され$るのは、~CSS~token `css-syntax-3$r の~levelであり，~text~levelではない — 一部分だけ変数から供されるような単独の~tokenを築くことはできない： ◎ Note that var() substitution takes place at the level of CSS tokens [css-syntax-3], not at a textual level; you can’t build up a single token where part of it is provided by a variable:
.foo {
--gap: 20;
margin-top: var(--gap)px;
}
これは `margin-top^p: `20px^v; （長さ）を設定することに等価ではない。 `margin-top^p: `20 px^v; （値は、~spaceを挟んだ 数と識別子の並びからなる）と等価になり，単に `margin-top$p ~propに対する無効な値になる。 このような場合、 `calc$f 式を利用すれば，同じものを妥当に得られる — 次の様に： ◎ This is not equivalent to setting margin-top: 20px; (a length). Instead, it’s equivalent to margin-top: 20 px; (a number followed by an ident), which is simply an invalid value for the margin-top property. Note, though, that calc() can be used to validly achieve the same thing, like so:
.foo {
--gap: 20;
margin-top: calc(var(--gap) * 1px);
}
`var$f 関数は、`算出値の時点$で`代用され$る。 宣言の中のすべての `var$f 関数が代用された時点で，それが無効ならば、その宣言は `算出値の時点で無効$になる。 ◎ var() functions are substituted at computed-value time. If a declaration, once all var() functions are substituted in, is invalid, the declaration is invalid at computed-value time.
例えば，次の用法は、構文の観点からは~~問題ないが、変数が代用された後は無意味な結果になる： ◎ For example, the following usage is fine from a syntax standpoint, but results in nonsense when the variable is substituted in:
:root { --looks-valid: 20px; }
p { background-color: var(--looks-valid); }
`20px^v は `background-color$p の値としては無効なので、この~propの~instanceは，代わりに `transparent^v （ `background-color$p に対する`初期値$）に算出される。 ◎ Since 20px is an invalid value for background-color, this instance of the property computes to transparent (the initial value for background-color) instead.
~propが `color$p など，既定で継承されるものならば、`初期値$ではなく`継承値$に算出される。 ◎ If the property was one that’s inherited by default, such as color, it would compute to the inherited value rather than the initial value.
3.1. 無効な変数
`~custom~prop$が`初期値$をとる場合、 `var$f 関数による代用に利用できなくなる。 そのような場合、妥当な~fallbackが指定されていない限り，宣言は`算出値の時点で無効$になる。 ◎ When a custom property has its initial value, var() functions cannot use it for substitution. Attempting to do so makes the declaration invalid at computed-value time, unless a valid fallback is specified.
上で説明したように、宣言は，それが［ 初期値をとる`~custom~prop$を参照する `var$f ］を含む場合に， `算出値の時点で無効@ になる。 あるいは，それが妥当な`~custom~prop$を利用していても、~prop値が，その中の `var$f 関数が代用された後に妥当でなくなれば，無効になる。 これが生じた場合の~propの`算出値$は、それが`継承~prop$であるかどうかに応じて，その~propの`継承値$／`初期値$になる — ~propの値に `unset$v ~keywordが指定されていたかの様に。 ◎ A declaration can be invalid at computed-value time if it contains a var() that references a custom property with its initial value, as explained above, or if it uses a valid custom property, but the property value, after substituting its var() functions, is invalid. When this happens, the computed value of the property is either the property’s inherited value or its initial value depending on whether the property is inherited or not, respectively, as if the property’s value had been specified as the unset keyword.
例えば，次の~codeでは： ◎ For example, in the following code:
:root { --not-a-color: 20px; }
p { background-color: red; }
p { background-color: var(--not-a-color); }
`p^e 要素の背景は、赤（ `red^v ）ではなく，透明 — `background-color$p の`初期値$ `transparent$v — になる。 `~custom~prop$自身が `unset$v されたり, 無効な `var$f 関数が含まれている場合も同じことが生じる。 ◎ the <p> elements will have transparent backgrounds (the initial value for background-color), rather than red backgrounds. The same would happen if the custom property itself was unset, or contained an invalid var() function.
このことと，作者が単に~stylesheetに直に `background-color^p: `20px^v; と記した場合のふるまいとの相違に注意されたし。 それは通常の構文~errorなので，その規則は 【~cascadeの最初の段階で】 破棄され、その結果 `background-color^p: `red^v; 規則が代わりに利用されることになる。 ◎ Note the difference between this and what happens if the author had just written background-color: 20px directly in their stylesheet - that would be a normal syntax error, which would cause the rule to be discarded, so the background-color: red rule would be used instead.
注記： `算出値の時点で無効$の概念は、 `var$f 関数が他の構文~errorと異なり， “早期に失敗させ” 得ないがためにある。 ~prop値が~UAから無効なものと判明した時点では、 【より優先順位の低い】 他の`~cascaded値$は，すでに棄てられている。 ◎ Note: The invalid at computed-value time concept exists because variables can’t "fail early" like other syntax errors can, so by the time the user agent realizes a property value is invalid, it’s already thrown away the other cascaded values.
3.2. 略式~propにおける変数
`略式~prop$における `var$f 関数の利用には，ある~~特有の難しさがある。 ◎ The use of var() functions in shorthand properties presents some unique difficulties.
~customでない~propに対しては、略式~propの値は，構文解析-時に 対応する`下位prop$の成分に分離され、それらの下位propが`~cascade$に取り込まれた上で，元の略式~propの方は概ね破棄される。 しかしながら，略式~propに `var$f 関数が利用された場合、どこへどの値が割当てられるかを~~指示できなくなる — 事実，単独の `var$f 関数が 同時にいくつかの下位propの値を代用することもあるので、構文解析-時には分離-不能な場合もある。 ◎ For non-custom properties, the value of a shorthand property is separated out into its component longhand properties at parse time, and then the longhands themselves participate in the cascade, with the shorthand more-or-less discarded. If a var() functions is used in a shorthand, however, one can’t tell what values are meant to go where; it may in fact be impossible to separate it out at parse time, as a single var() function may substitute in the value of several longhands at once.
これに~~対処するため、実装は，次をし~MUST：
- ［ 略式~propに `var$f 関数が含まれているため、下位propの値は， `var$f 関数が代用されるまで待ち~~状態にある ］ことを指示するためとして、下位propに，特別な, 作者からは観測できないような `代用待ちの値@ を割当てる。
- `代用待ちの値$は、通常通りに~cascadeさせる。
- 算出値の時点で， `var$f 関数に対する代用を終えた所で、略式~propの値を構文解析した上で，下位propに対し適切な値を割当てる。
`代用待ちの値$は、~APIによる観測-が許容される所では，空~文字列に直列化され~MUST。 ◎ Pending-substitution values must be serialized as the empty string, if an API allows them to be observed.
同様に， `CSSOM$r においては、略式~propの直列化が，対応する下位propの値を適切に連結することを通して定義されているが、明示的な `var$f 関数を伴って指定されている略式~propについては、代わりに，元の `var$f が含まれた値のまま直列化され~MUST。 他の略式~propに対しては、対応する いずれかの下位propに`代用待ちの値$がある場合、その略式~propの値は，空~文字列に直列化され~MUST。 ◎ Similarly, while [CSSOM] defines that shorthand properties are serialized by appropriately concatenating the values of their corresponding longhands, shorthands that are specified with explicit var() functions must serialize to the original, var()-containing value. For other shorthands, if any of the longhand subproperties for that shorthand have pending-substitution values then the serialized value of the shorthand must be the empty string.
4. ~API
すべての`~custom~prop$`宣言$に対し、その`大小区別~flag$は ~ON にされる。 ◎ All custom property declarations have the case-sensitive flag set.
注記： ~custom~propは，名前の文字大小が区別されるので、 `CSSStyleDeclaration$I ~objの中に CamelCase 形で現れることはない。 自動的に CamelCase 化する~text変形の類いは，これと互換になれない。 それらは、 `getPropertyValue()$m, 等の~interfaceを通して，適正な名前で~accessできる。 ◎ Note: Custom properties do not appear on a CSSStyleDeclaration object in camel-cased form, because their names may have both upper and lower case letters which indicate distinct custom properties. The sort of text transformation that automatic camel-casing performs is incompatible with this. They can still be accessed by their proper name via getPropertyValue()/etc.
4.1. ~custom~propの直列化-法
~custom~prop名が直列化されるときには、作者から供された文字大小は保全され~MUST。 ◎ Custom property names must be serialized with the casing as provided by the author.
注記： ~customでない~propに対しては，その名前は~ASCII範囲に制約された上で, `~ASCII大小無視$になるので、実装は概して，名前を小文字~化した上で直列化する。 ◎ Note: For non-custom properties, property names are restricted to the ASCII range and are ASCII case-insensitive, so implementations typically serialize the name lowercased.
5. 2014 年 5 月 6 日付 最終作業草案からの変更点
- 略式~propが変数を利用している場合の，下位propの直列化が定義された。 ◎ Serialization of longhands when shorthand uses a variable was defined.
- DOM による “大小無視” の定義へ~linkした。 ◎ Link to DOM’s definition of "case-sensitive".
- `lang()$ps と伴に変数を利用して国際化に対応する，単純な例を追加した。 ◎ Added example of using variables with :lang() to do simple i18n.
- ~custom~propにおける `var$f の利用は、 `var$f 文法に対し妥当で~MUSTことが明確化された。 ◎ Clarified that usage of var() in a custom property must be valid per the var() grammar.
6. 謝辞
Many thanks to several people in the CSS Working Group for keeping the dream of variables alive over the years, particularly Daniel Glazman and David Hyatt. Thanks to multiple people on the mailing list for helping contribute to the development of this incarnation of variables, particularly Brian Kardell, David Baron, François Remy, Roland Steiner, and Shane Stephens.
7. ~privacy／保安~上の考慮点
この仕様が定義する仕組みは、作者が制御する~pageの中で，作者~levelの~style付け情報を使い回す以上のことはしない。 そのようなわけで、~privacyや保安~上の新たな考慮点はない。 ◎ This specification defines a purely author-level mechanism for passing styling information around within a page they control. ◎ As such, there are no new privacy or security considerations.