1. 序論
◎非規範的巨大な文書や~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.
1.1. 値~定義
【 この節の内容は、 `~CSS日本語訳 共通~page＠~CSScommon#values$に移譲。 】
2. ~custom~propを定義する： ~propの族 `--*^p
この仕様は、 `~custom~prop$と呼ばれる，~~自由に~~拡張可能（ `open-ended^en ）な［ ~propたちが成す集合 ］を定義する。 それらは、 他の~propの値の中の `var$f 関数の代入~値 — `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? ◎初 `無効が保証される値$ ◎ the guaranteed-invalid value ◎適 すべての要素, すべての疑似要素（一部の~propに制約されるものも含む） ◎ all elements and all pseudo-elements (including those with restricted property lists) ◎継 される ◎百 受容しない ◎算 `無効が保証される値$／指定d値 — ただし，後者においては、 値~内の各~変数【 `var$f 関数／`任意-代入~関数$】には`代入-$される。 ◎ specified value with variables substituted, or the guaranteed-invalid value ◎順 文法に従う ◎ア 離散的 ◎表終~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 生成規則がこれに対応する — それは、 `dashed-ident$t （ 2 個の~dashから開始される，任意の妥当な`~CSS識別子$）として定義される。 ただし， "`--^c" 自体は除く — それは、 ~CSSによる将来の利用~用に予約される。 `~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 <dashed-ident> (a valid identifier that starts with two dashes), except -- itself, which is reserved for future use by CSS. 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 ）に対し宣言されているので、 その値は， `普通の継承d~propと同様に＠#as-normal-property$ — 別の `--main-color^p で上書きされない限り — 文書~内のどの要素（および疑似要素）にも継承され、 その結果，どの `var(--main-color)^v も値 `#06c^v が代入されることになる。 】
他の~CSS~propと違って、 ~custom~propの名前は`~ASCII大小無視$`ではない^em。 ~custom~propの名前は、 互いに`一致する$場合に限り，等しいとされる。 ◎ Unlike other CSS properties, custom property names are not ASCII case-insensitive. Instead, custom property names are only equal to each other if they are identical to each other.
`--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.
たぶん，もっと驚くことに、 `--foó^p と `--foó^p は，別個な~propになる。 前者は［ `00F3^U `LATIN SMALL LETTER O WITH ACUTE^cn ］で綴られ， 後者は［ ~ASCII "o", `0301^U `COMBINING ACUTE ACCENT^cn ］並びとして綴られるが、［ ~Unicode正規化, ~localeに特有な照合c ］による複階性と陥穽を避けるため， “`一致する$” 関係は［ 2 個の文字列が等しいかどうか ］を［ 符号位置ごとの直な比較 ］を利用して決定する。 ◎ Perhaps more surprisingly, --foó and --foó are distinct properties. The first is spelled with U+00F3 (LATIN SMALL LETTER O WITH ACUTE) while the second is spelled with an ASCII "o" followed by U+0301 (COMBINING ACUTE ACCENT), and the "identical to" relation uses direct codepoint-by-codepoint comparison to determine if two strings are equal, to avoid the complexities and pitfalls of unicode normalization and locale-specific collation.
各種［ ~OS／~keyboard／入力~method ］は，~textを［ 視覚的には一致するが，異なる符号位置を利用して符号化する ］こともあるので、 作者には、［ 混同の可能性を避けるよう，変数~名を選ぶ ］か［ 似て非なる並びが生じないことを確保するよう， 変数~名に~escapeその他の手段を利用する ］ことを勧める。 例えば， `CHARMOD-NORM$r の § 2.3 を見よ。 ◎ Operating systems, keyboards, or input methods sometimes encode visually-identical text using different codepoint sequences. Authors are advised to choose variable names that avoid potential confusion or to use escapes and other means to ensure that similar appearing sequences are identical. See Section 2.3 in [CHARMOD-NORM] for examples.
次の~CSSを保守している開発者は、 `.test^css がなぜ `red^v になるか困惑するかもしれない： ◎ Developers maintaining the following CSS might be confused why the test patch is red:
--fijord: red;
--fijord: green;
--fijord: blue;
.test {
background-color: var(--fijord);
}
その理由は、 これらの~custom~propは，見かけは一致するが異なる文字~並びを利用していることにある ⇒＃ 1 個目は `LATIN SMALL LETTER F^cn + `LATIN SMALL LETTER I^cn + `LATIN SMALL LETTER J^cn ／ 2 個目は `LATIN SMALL LETTER F^cn + `LATIN SMALL LIGATURE IJ^cn ／ 3 個目は `LATIN SMALL LIGATURE FI^cn + `LATIN SMALL LETTER J^cn ◎ The reason is that the first custom property uses the character sequence LATIN SMALL LETTER F + LATIN SMALL LETTER I + LATIN SMALL LETTER J; the second, identical-looking one uses the character sequence LATIN SMALL LETTER F + LATIN SMALL LIGATURE IJ while the third uses the character sequence LATIN SMALL LIGATURE FI + LATIN SMALL LETTER J.
なので、 この~CSSは， 3 つの別個な~custom~propを包含する — うち 2 つは利用されない。 ◎ So the CSS contains three distinct custom properties, two of which are unused.
~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 関数が解決される前 — 算出d値を得る前 — の段階で，`指定d値$（すなわち，`初期~値$または`継承d値$）にされる。 例えば，次の~stylesheet：
:root {
--foo: red;
}
p {
--foo: inherit;
color: var(--foo);
}
における `var(--foo)^v は、［ `inherit^v `ではなく^em， `--foo^p が継承する値 ］が代入されることになる。 したがって、 `p^e 要素の `color^p は，その先祖の［ `color^p `ではなく^em, `--foo^p ］~propの値（この例では `red^v ）をとることになる。 】
注記： この~moduleは， “変数” を作成するための［ `var$f による`~custom~prop$の利用 ］に注力しているが、 ~scriptから［ 構文解析される／作動される ］ような，実際の~custom~propとしても利用し得る。 `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.
~custom~propは、 “普通の” ~propであり，どの要素に対しても宣言できる。 それらは、 通常の［ 継承と~cascade規則 ］で解決される。 それらは、［ `media$at その他の`条件付き~group規則$により条件付きにすることもできる／ ~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$at 規則の中で利用される【宣言される】どの`~custom~prop$も， `~animationに染まって@ いるとされ、 各種~animation~prop（ `animation-*^p ）の中で `var$f 関数を介して参照されたときの扱われ方に影響する。 ◎ Notably, they can even be 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.
注記： 離散的に~animateする他の~propと同様に、 ~custom~propは，`遷移し得ない＠~TRANSITION#transitionable$。 しかしながら，`登録-済み~custom~prop$は、 それに与えた構文が離散的でない~animationの挙動を有する場合には，遷移し得る。 ◎ Note: Like any other property that animates discretely, custom properties can’t be transitioned. Registered custom properties can, however, if given a syntax that has non-discrete animation behavior.
~animationに染められるのは、 “伝染的” である： ~custom~propは、 `~animationに染まって$いる~propを参照するならば， 自身も`~animationに染まって$いることになる。 ◎ Animation-tainted is "infectious": custom properties which reference animation-tainted properties also become animation-tainted.
次の~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の`算出d値$から値を取り出す： ◎ 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 だけど、継承なんだな。</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(el) {--external-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.1. ~custom~propの値の構文
`~custom~prop$に許容される構文は極めて寛容にされている。 `declaration-value$t 生成規則は、［ 1 個~以上の~tokenからなり，次に挙げる~tokenは包含しない ］`任意の^em並びに合致する：
- `bad-string-token$P
- `bad-url-token$P
- 対を成さない括弧類： `)-token$P, `]-token$P, `}-token$P
- ~top-levelの `semicolon-token$P
- ~top-levelの `delim-token$P のうち，その.値に "`!^c" を伴うもの
加えて、 `~custom~prop$の値が `var$f 参照を包含している場合、 その `var$f 参照は，指定された `var$f 文法に則って妥当でなければナラナイ。 さもなければ、 `~custom~prop$は無効になり，無視するモノトスル。 ◎ 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.
例えば，次は、 妥当な~custom~propである： ◎ For example, the following is a valid custom property:
--foo: if(x > 5) this.width = 10;
この値は、 通常のどの~propの中でも無効になるので，`変数^emとしては明白に無用であるが、 ~JSにより［ 読取る／動作させる ］用途はあり得る。 ◎ 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 関数の値 ］の文字大小は、 `区別され^em，作者が与えた元の文字大小を保全するモノトスル。 （多くの~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は，`何でも^emを包含し得るので、 その内側に何があるか解釈する方法を知る一般的な仕方は無い （それを参照する `var$f を通して既知な~propの中へ`代入-$されるまでは）。 それらの値は — `部分的に^em，一部の事例に限って解決されることはなく — 完全に，解決されずに残され、［ `var^f 関数が合間に挟まれた，`~CSS~token列＠~CSSSYN#tokenization$ ］が成す裸の~streamになる。 ◎ Because custom properties can contain anything, there is no general way to know how to interpret what’s inside of them (until they’re substituted into a known property with var()). Rather than have them partially resolve in some cases but not others, they’re left completely unresolved; they’re a bare stream of CSS tokens interspersed with var() functions.
これには、
ある意外な含意がある。
例えば，~CSSにおける相対~URLは、
当の値が現れる~stylesheetの基底~URLを基準に解決される。
しかしながら，
`/a/style.css^l に在る~stylesheet内に
`--my-image^p: `url(foo.jpg)^v;
の様な~custom~propが~~現れる場合、
即時に絶対~URLに解決されることはない
— それを指す変数が後で
`/b/style.css^l に在る`異なる^em ~stylesheet内で
`background$p: `var(--my-image)^v;
の様に利用された場合、
`そこでは^em `/b/foo.jpg^l に解決されることになる。
◎
This has some knock-on implications. For example, relative URLs in CSS are resolved against the base URL of the stylesheet the value appears in. However, if a custom property like --my-image: url(foo.jpg); shows up in an "/a/style.css" stylesheet, it will not resolve into an absolute URL immediately; if that variable is later used in a different "/b/style.css" stylesheet like background: var(--my-image);, it will resolve at that point to "/b/foo.jpg".
2.2. 無効が保証される値
`~custom~prop$の初期~値は、 `無効が保証される値@ になるとする。 ◎ The initial value of a custom property is a guaranteed-invalid value.
`無効が保証される値$は、 字義どおり，無効になることが保証される。 ある~propの値に それが現れた場合、 当の~propは，`算出d値の時点で無効$になる。 ◎ The guaranteed-invalid value is, well, guaranteed to be invalid. If it ever appears in a property value, then at computed value time that property becomes invalid at computed-value time.
~prop以外の文脈は，`無効が保証される値$用の自前の挙動を定義することになるが、 それは，常に何らかのイミで “無効” になる。 ◎ Non-property contexts will define their own behavior for the guaranteed-invalid value, but it will always be "invalid" in some sense.
`無効が保証される値$が直列化されるときは，空~文字列になるが、 ~custom~propの中に — `--foo: ;^css の様に — 実際に空な値を書いても，妥当な（空な）値になり、 `無効が保証される値$にはならない。 理由が何であれ，［ `~custom~prop$を`無効が保証される値$に手動で設定し直す ］よう求めるならば、 ~keyword `initial$v 利用して行える。 ◎ The guaranteed-invalid value serializes as the empty string, but actually writing an empty value into a custom property, like --foo:;, is a valid (empty) value, not the guaranteed-invalid value. If, for whatever reason, one wants to manually reset a custom property to the guaranteed-invalid value, using the keyword initial will do this.
注記： ［ `登録-済み~custom~prop$でない`~custom~prop$の`初期~値$を呼出す ］こと以外に［ `無効が保証される値$を作成する仕方 ］は、 `任意-代入~関数$が無効になるようにする他にない。 ◎ Note: Other than invoking the initial value of a non-registered custom property, the only way to create the guaranteed-invalid value is by having an invalid arbitrary substitution function.
2.3. 循環依存の解決-法
`~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 へ辺で結ぶ。 ◎ 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.
この依存関係~graph内に循環がある場合、 その循環を成す どの`~custom~prop$も，`算出d値の時点で無効$になる。 ◎ If there is a cycle in the dependency graph, all the custom properties in the cycle are invalid at computed-value time.
注記： 定義-済み~propは、 ある［ 依存関係の循環 ］に関与する場合には，［ その値~内に無効な変数があることにより，`算出d値の時点で無効$になる ］か，循環~用に自前の取扱いを定義する（ `em$u 値を利用している `font-size$p の様に）。 それらは、 ~custom~propの様に`無効が保証される値$には算出されない。 ◎ Note: Defined properties that participate in a dependency cycle either end up with invalid variables in their value (becoming invalid at computed-value time), or define their own cyclic handling (like font-size using em values). They do not compute to the guaranteed-invalid value like custom properties do.
変数を安全に利用する~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.
他方，次の例における 2 つの変数は、 互いに依存しているので，無効な~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 どちらも， 今や`算出d値の時点で無効$になり、 長さでなく`無効が保証される値$に算出される。 ◎ Both --one and --two are now invalid at computed-value time, and compute to the guaranteed-invalid value rather than lengths.
`~custom~prop$の値を成す各 `var$f 関数は、 当の値が継承される`前に^em， 算出d値の時点で`解決される＠#resolve-a-var-function$ 【`代入-$される】ことに特に注意。 一般に，循環依存が生じるのは、 同じ要素~上の複数の~custom~propが互いを指すときに限られる。 要素~treeの中で，一方が他方の先祖である 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.
例えば，次の構造における、 ３個の~custom~propが循環することはない。 すべて妥当な変数を定義する： ◎ For example, given the following structure, these custom properties are not cyclic, and all define valid variables:
<one><two><three /></two></one>
<style>
one { --foo: 10px; }
two { --bar: calc(var(--foo) + 10px); }
three { --foo: calc(var(--bar) + 10px); }
</style>
`one^e 要素は、 `--foo^p 用の値を定義する。 `two^e 要素は、 この値を継承することに加え， `foo^css 変数を利用して自身の `--bar^p に値をアテガう。 最後に， `three^e 要素は、［ 変数が`代入された後の^em `--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? )
`var$f 関数は、 `任意-代入~関数$である。 ◎ The var() function is an arbitrary substitution function.
関数の最初の引数が、 代入~値を~~供する`~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 value of the referenced custom property is the guaranteed-invalid value.
【† 代入~値を~~供する~custom~propは、［［ `var$f を値に利用する~prop ］が適用される要素 ］上のそれになる。 】
通例的な［ 値どうしを分離していない~commaは省略するよう要求する規則 ］の例外として、 何も後続していない~commaが在る場合は，［ ~fallback値は空であることを指示している，妥当な `var$f ］として扱うモノトスル。 ◎ In an exception to the usual comma elision rules, which require commas to be omitted when they’re not separating values, a bare comma, with nothing following it, must be treated as valid in var(), indicating an empty fallback value.
注記： すなわち、 `var(--a,)^v は妥当な関数を指定している — ~custom~prop `--a^p が［ 妥当でない／欠落な ］場合、 `var$f は無に置換されるべきである。 ◎ Note: That is, var(--a,) is a valid function, specifying that if the --a custom property is invalid or missing, the var() should be replaced with nothing.
注記： ~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 %~prop の値が包含している `var$f 関数 %関数 用に`任意-代入~関数を解決する$ ときは： ◎ To resolve a var() function:
- %~custom~prop ~LET %関数 の 1 個目の引数により命名される［ %要素 の`~custom~prop$ ］ ◎ ↓
- %結果 ~LET %~custom~prop の値 ◎ Let result be the value of the custom property named by the function’s first argument, on the element the function’s property is being applied to.
- %~fallback ~LET %関数 の 2 個目の引数は［ 在るならば その値 ／ 無いならば ε【！`無効が保証される値$】 ］ ◎ Let fallback be the value of the function’s second argument, defaulting to the guaranteed-invalid value if it doesn’t have a second argument.
- ~IF［ %~custom~prop は`~animationに染まって$いる ］~AND［ %~prop は`~animate不可$である ］ ⇒ %結果 ~SET ε【！`無効が保証される値$】 ◎ If the custom property named by the var()’s first argument is animation-tainted, and the var() is being used in a property that is not animatable, set result to the guaranteed-invalid value.
- ~RET ( %結果, %~fallback ) ◎ Return result and fallback.
3.1. 可変~単位
【 この節は，この仕様の~level 2 に追加された主な内容であり、 編集上の都合により，この訳にて与えている。 】
`~custom~prop$は、 `var$f 関数で直に参照されることに加えて，~custom単位としても参照され得る。 それは、 文書~内の — たぶん，ある設計-~systemにより確立された — 有意な “基底~size” の倍数を容易に利用できるようにする。 ◎ In addition to being referenced directly with the var() function, custom properties can be referenced as custom units, making it easy to use multiples of significant "base sizes" in a document, perhaps established by a design system.
単位として `dashed-ident$t を伴う`次元$は、 `可変~単位~参照@ （ `variable unit reference^en ）になる。 その効果, それに対する制約は、 `var$f を利用するときと一致する — `~custom~prop$は、 当の単位の名前で参照される。 ◎ A dimension whose unit is a <dashed-ident> is a variable unit reference. It has identical effects and restrictions to using var(); the unit name is the custom property being referenced.
唯一の相違は、
`可変~単位~参照$は
— `~custom~prop$の値が直に代入されるのではなく —
次が代入されることである
⇒
calc(%X * (var(%Y)))
— ［
%X, %Y
］は，当の次元を成す［
数量-成分, 単位~成分
］
◎
The only difference is during substitution—rather than just substituting the custom property value directly, it substitutes as calc(X * (var(Y))), where X is numeric component of the dimension, and Y is the unit component of the dimension.
例えば， “流動的な（ `fluid^en ）~typography” は、 ~textを表示域の~sizeに則って~sizeする。 これのごく単純な~versionは、 次のように作成できる： ◎ For example, "fluid typography" sizes text according to the viewport size. A very simple version of this can be created as:
@property --fem { /*
“流動的な `em^u”
◎
"fluid em"
*/
syntax: "<length>";
initial-value: 2vw;
inherits: true;
}
.fluid-type {
font-size: 1.2--fem;
/*
は、
次と等価になる
◎
equivalent to
*/
font-size: calc(1.2 * (var(--fem)));
}
【 `initial-value$d 記述子は， 原文では `initial^d と記されているが（過去の名前と思われる）、 現在の仕様に基づくよう改めている。 】
もっと複階的な式も利用できる。 例えば，流動的な~typographyは、 ~screenがごく［ 大きい／小さい ］ときに退化する状況を避けるため，［ 表示域に応じて，~sizeが`どこまで^em応答するか ］に関して制限sを課すよう求まれることが多い： ◎ More complex expressions can be used as well. For example, fluid typography often wants to impose limits on how much the size responds to the viewport, to avoid degenerate situations on very large or very small screens:
@property --fem { /*
“流動的な `em^u”
◎
"fluid em"
*/
syntax: "<length>";
initial-value: clamp(10px, 1vw + 1vh, 1rem);
inherits: true;
}
.fluid-type {
font-size: 1.2--fem;
/*
`12px^v 以上 `1.2rem^v 以下になる。
◎
Won’t get smaller than 12px, or larger than 1.2rem.
*/
}
`可変~単位~参照$は，`~custom~prop$参照なので、 【子孫にて】`~custom~prop$を設定することで，通常に上書きできる。 これは、 ある~componentを汎用~的に~styleしつつ，~page上の位置に応じて特化するときに有用になり得る： ◎ As the variable unit reference is a custom property reference, it can be overridden by setting the custom property normally. This can be useful to specialize a component for a particular position on the page, while still styling it generically:
@property --bs { /*
塊~size
◎
block size
*/
syntax: "<length>";
initial-value: 8px;
inherits: true;
}
.module {
margin-block: 1.5--bs;
border-block: .5--bs;
/*
塊-軸［
~margin, ~border
］を［
`12px^v, `4px^v
］にする
◎
gives a vertical margin of 12px, and vertical border of 4px
*/
}
.sidebar .module {
--bs: 6px;
/*
`.sidebar^css 内では~componentが少し密になるよう，塊-軸［
~margin, ~border
］を［
`9px^v, `3px^v
］にする。
◎
Makes the components slightly more compact in the sidebar, with a vertical margin of 9px and a vertical border of 3px.
*/
}
注記： `可変~単位~参照$は， ~fallback値をとり得ないので 【関数-記法ではないので，~fallback値を指定し得ない】、 参照-先の`~custom~prop$が存在しない場合や`無効が保証される値$【！無効な値】になる場合， 当の単位~参照も無効になる。 代わりに， `property$at を利用して`登録-済み~custom~prop$を作成すること — そうすれば、 `initial-value$d 記述子の値が既定として利用されるようになるので。 ◎ Note: Variable unit references can’t have fallback values, so if the referenced custom property doesn’t exist or is invalid, the unit reference will be invalid as well. Use @property to create a registered custom property, as the initial value will instead be used as the default.
注記：
`可変~単位~参照$は，明瞭に［
参照-先の`~custom~prop$が数量-値をとる
］ことを
（ `calc$f の中へ代入されても妥当になるよう）
期待するが、
これを施行するものは無い。
数量-値でない値を給して，
初期~値を上書きした場合、
代入した結果は，
単純に無効な~propになる
（例： 上の `--fem^u 単位の例が与えられた下で，
`--fem^p: `red^v; を給したなら、
`font-size^p は `calc(1.2 * (red))^v になり，無効になる）。
◎
Note: While variable unit references clearly expect their referenced custom property to have a numeric value (so that it’s valid to substitute into a calc()), nothing enforces this. Supplying a non-numeric value, such as by using --fem: red; to override the initial value in the above examples, will simply result in an invalid property after substitution, like font-size: calc(1.2 * (red));.
4. ~API
すべての`~custom~prop$`宣言$に対し、 その`文字大小区別か$は ~T に設定される。 ◎ All custom property declarations have the case-sensitive flag set.
注記： ~custom~propは，名前の文字大小が区別されるので、 `CSSStyleDeclaration$I ~objの中に CamelCase 形で現れることはない。 自動的に CamelCase 化する~text変形nの類いは，これと互換になれない。 それらは、 `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 lowercase 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の名前を直列化した結果は、 作者から供されたものと正確に同じ符号位置~並びになるモノトスル — 文字大小を改めることなく。 ◎ Custom property names must be serialized as the exact code point sequence provided by the author, including not altering the case.
注記： ~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.
`~custom~prop$の指定d値は、 `正確に作者が指定したとおり^emに直列化するモノトスル。 他の~propにて生じ得る単純~化 — 値を成す［ ~commentを落とす／ 空白を正規化する／ 数量-~tokenを直列化し直す ］等々 — は、 生じないモノトスル。 ◎ Specified values of custom properties must be serialized exactly as specified by the author. Simplifications that might occur in other properties, such as dropping comments, normalizing whitespace, reserializing numeric tokens from their value, etc., must not occur.
類似に，`~custom~prop$の算出d値も、 `正確に作者が指定したとおり^emに直列化して， `var$f 関数の置換~用に保存するモノトスル。 ◎ Computed values of custom properties must similarly be serialized exactly as specified by the author, save for the replacement of any var() functions.
例えば，次の~propが与えられられたとき： ◎ For example, given the following properties:
--y: /* baz */; --x: /* foo */ var(--y) /* bar */;
`--x^p の指定d値の直列化は `/* foo */ var(--y) /* bar */^l になり， `--x^p の算出d値の直列化は `/* foo */ /* baz */ /* bar */^l にならなければならない。 ◎ the serialization of the specified value of --x must be "/* foo */ var(--y) /* bar */", while the serialization of the computed value of --x must be "/* foo */ /* baz */ /* bar */".
（値の頭部を成す空白は、 ~CSS構文解析器により自動的に削られ，ここでは保全されないことに注意。） ◎ (Note that the leading whitespace on the value is automatically trimmed by the CSS parser; it’s not preserved here.)
注記： この要件が存在するわけは、 作者は，ときには~custom~prop内に非~CSSな情報を格納することもあり、 この情報を “正規化する” と，作者~codeを非互換化する仕方で値が変化し得るからである。 ◎ This requirement exists because authors sometimes store non-CSS information in custom properties, and "normalizing" this information can change it in ways that break author code.
例えば，~custom~prop内に
`--uuid^p: `12345678-12e3-8d9b-a456-426614174000^v
の様に~UUIDが格納され、
~scriptから~accessされたとき，当の~UUIDを記されたとおり復唱することが要求されることもある。
◎
For example, storing a UUID in a custom property, like --uuid: 12345678-12e3-8d9b-a456-426614174000, requires the UUID to be echoed back out as written when it’s accessed by script.
この値は、 形上では，~CSSにより一連の隣接な［ 実数／次元 ］として構文解析される。 特に，区分 `-12e3^l は、 −12000 に等しい実数として構文解析される。 それを，他の文脈において［ ~CSSOMにより要求されるとおり，その形で直列化し直す ］と、 作者による値の利用を致命的に非互換化することになろう。 ◎ This value is technically parsed by CSS as a series of adjacent numbers and dimensions. In particular, the segment "-12e3" parses as a number, equal to -12000. Reserializing it in that form, as required by CSSOM in other contexts, would fatally break the author’s use of the value.
変更点
- `2022年 6月 16日 勧告候補~snapshot＠~TR/2022/CR-css-variables-1-20220616/$ からの変更点 ◎ 5.1. Changes Since the 16 June 2022 CR Snapshot
- 【直列化における】 元の~tokenたちの合間への~comment挿入は、 正確に 1 個ではなく 0 個以上の~comment【？】を伴って起こり得ることを明確化した。 ◎ Clarified that the comment-insertion can happen with 0+ comments between the original tokens, not just exactly 1.
- `~custom~prop$における遷移の挙動を注記において明確化した。 ◎ Clarified the transition behavior of custom properties, in a note
- `2021年 11月 11日 勧告候補~草案＠~TR/2021/CRD-css-variables-1-20211111/$ からの変更点 ◎ 5.2. Changes Since the 11 November 2021 CR Draft
- ~custom~propは，すべての疑似要素（一部の~propに制約されるものも含む）に適用されることを明確化した。 ◎ Clarified that custom properties apply all pseudo-elements (including those with restricted property lists)
- 【~custom~propの名前に関する】課題を［ 結合~文字, 合字, 等々 ］で~~説明する例を追加した。 ◎ Added example to illustrate issues with combining characters, ligatures, etc
- 別個な符号位置~並びを利用しつつ似た様に現れる変数~名について、 もっと踏み込んだ言い回しにした。 ◎ Strengthened wording around similar-appearing variable names that use distinct codepoint sequences
- より視覚的に別個な言語（英語と~Greek）を例として利用することにより、 例を明確化した。 ◎ Clarified an example by using more visually distinct languages as examples (English and Greek)
- § ~securityと~privacyの考慮点 を別々な節に分割した。 ◎ Split Security and Privacy into separate sections
- `2015年 12月 3日 勧告候補＠~TR/2015/CR-css-variables-1-20151203/$ からの変更点 ◎ 5.3. Changes Since the 03 December 2015 CR
- `css-syntax-3$r は，今や宣言~値から空白を自動で削るので、 空な変数でも許容されるよう， ~custom~prop文法における `declaration-value$t を省略可能にした。 （ `774$issue ） ◎ Now that [css-syntax-3] auto-trims whitespace from declaration values, made <declaration-value> optional in the custom property grammar, so that empty variables are still allowed. (Issue 774)
- 類似に、 `var$f 内の空な~fallbackは妥当になるようにした。 ◎ Similarly, made empty fallbacks valid in var().
- "`--^p" ~prop【 2 個の~dashのみ】を将来の~CSSによる利用-用に予約した。 ◎ The -- property is reserved for future use by CSS.
- “`~animationに染まって$いる” の概念を追加した — ［ ~animate不可な~propが，何らかの~animate能に紛れ込む ］ような変数の利用-法を防止するため。 ◎ Added concept of "animation-tainted", to prevent non-animatable properties from using a variable to smuggle in some animatability.
- `無効が保証される値$を定義した — ~custom~propの初期~値と［ 循環による失敗／代入における失敗 ］の結果を もっと単直にして、 失敗が代入を通して — 最終的に~finally~fallbackにより横取りされるまで — 伝播することを許容するため。 ◎ Defined the guaranteed-invalid value to make the initial value of custom properties and the result of cycles or substitution failure more straightforward, and allow failure to propagate thru substitutions until finally intercepted by a fallback.
- 循環は、 `算出d値の時点で無効$になる挙動を誘発するものと定義した。 ◎ Defined that cycles trigger invalid at computed-value time behavior.
- 変数を`~CSS全域~keyword$に解決することを許容した （アリになるのは、 当の~keywordを~fallbackとして供した場合に限られる）。 ◎ Allowed variables to resolve to a CSS-wide keyword (only possible by providing it as a fallback).
- `登録-済み~custom~prop$は、 `算出d値の時点で無効$になるときは，~customでない~propの様に動作することを明確化した。 ◎ Clarified that registered custom properties act like non-custom properties when they’re invalid at computed-value time.
- `var$f を伴う下位propは、 その略式~propが直列化-不能になることを誘発するようにした — `代入待ちの値＠~CSSVAL5#pending-substitution-value$を伴う下位propがすでにそうしていた様に。 ◎ Made longhands with var()s also trigger their shorthands to be unserializable, like longhands with pending-substitution values already did.
- 累乗的な代入による攻撃に抗して防御することを~UAに要求した。 ◎ Required UAs to defend against exponential substitution attacks.
- ~custom~propの`値^emを直列化する方法を定義した （それまで、 その名前の直列化~しか指定されてなかった）。 ◎ Defined how to serialize the values of custom properties (previously, only the property name’s serialization was specified).
- `2014年 5月 6日 最終~作業草案＠~TR/2014/WD-css-variables-1-20140506/$ からの変更点 ◎ 5.4. Changes since the May 6 2014 Last Call Working Draft
- 略式~propが変数を利用している場合の，下位propの直列化を定義した。 ◎ Serialization of longhands when shorthand uses a variable was defined.
- ~DOM標準【現在は `INFRA$r 】による “大小無視” の定義へ~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 文法に従って妥当でなければナラナイことを明確化した。 ◎ Clarified that usage of var() in a custom property must be valid per the var() grammar.
謝辞
何年にもわたり，~CSS変数の夢を生きたまま保ってこられた~CSS~WGの方々 — 特に， `Daniel Glazman^en, `David Hyatt^en 両氏 — に感謝する。 ~mailing~listにて，この仕様の開発に貢献するべく助力された人々 — 特に次に挙げる方々 — に感謝する： ◎ 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＼
~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 considerations.
~securityの考慮点
【 `CSS-VALUES-5^r 】 `§ 長過ぎな代入の安全な取扱い＠~CSSVAL5#long-substitution$は、［ `var$f 関数などの “~macro展開” の様な仕組み ］に対し仕掛けられ得る［ 昔からある~DoS攻撃 ］をとり挙げ，その攻撃に抗する防御を義務付ける。 ◎ § 4.3 Safely Handling Overly-Long Substitution calls out a long-standing Denial-of-Service attack that can be mounted against "macro-expansion"-like mechanisms, such as the var() function, and mandates a defense against that attack.