カスケードする変数用のカスタムプロパティ — CSS Custom Properties for Cascading Variables Module Level 1

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.

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.

~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” である）。 そのような捉え方を意図して命名されたのかもしれない。 】

`root$ps {
  --main-color: #06c;
  --accent-color: #006;
}
/* 
~CSS~fileの残りの部分
◎
The rest of the CSS file
 */
#foo h1 {
  `color$p: var(--main-color);
}

他の~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.

各種［ ~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.

--fijord: red;
--fijord: green;
--fijord: blue;

.test {
  background-color: var(--fijord);
}

~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.

:root {
  --foo: red;
}
p {
  --foo: inherit;
  color: var(--foo);
}

注記： この~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.

:root {
  --header-color: #06c;
}

h1 { `background-color$p: var(--header-color); }

: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>

: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) ")"
}

--foo: if(x > 5) this.width = 10;

:root {
  --main-color: #c06;
  --accent-background: linear-gradient(
      to top, var(--main-color), white
  );
}

:root {
  --one: calc(var(--two) + 20px);
  --two: calc(var(--one) - 20px);
}

<one><two><three /></two></one>
<style>
one   { --foo: 10px; }
two   { --bar: calc(var(--foo) + 10px); }
three { --foo: calc(var(--bar) + 10px); }
</style>

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.

/* 
~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
 */
}

@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)));
}

@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.
 */
}

@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.
 */
}

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.

--y: /* baz */;
--x: /* foo */ var(--y) /* bar */;

変更点

`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.