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

1.1. 値~定義

【 この節の内容は ~CSS日本語訳 共通~pageに移譲。 】

2.1. ~custom~propの値の構文

加えて、 `~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.

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

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

2.2. 無効が保証される値

`~custom~prop$の初期~値は、 `無効が保証される値@ である。 § ~cascade変数の利用-法 に定義されるように、 `var$f を利用して，これを値にとる`~custom~prop$で代用すると、 それを参照している~propは，`算出d値の時点で無効$になる。 ◎ The initial value of a custom property is a guaranteed-invalid value. As defined in § 3 Using Cascading Variables: the var() notation, using var() to substitute a custom property with this as its value makes the property referencing it invalid at computed-value time.

この値が直列化されるときは，空~文字列になるが、 ~custom~propの中に — `--foo: ;^css の様に — 実際に空~値を書いても，妥当な（空）値になり、 `無効が保証される値$にはならない。 理由が何であれ，変数を`無効が保証される値$に手動で設定し直したいと求めるならば、 ~keyword `initial$v 利用して行える。 ◎ This 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 variable to the guaranteed-invalid value, using the keyword initial will do this.

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.

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

重要な点として、 `~custom~prop$の値の中のどの `var$f 関数も，`算出d値の時点$で解決される 【`代用-$される】 — したがって、 その値が継承されるときには，`すでに^em解決されている — ことを銘記しておく。 一般に，循環依存が生じるのは、 同じ要素~上の複数の~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.

【 `算出d値の時点@ — 明示的には定義されていないが、 `~cascaded値の処理$における，`算出d値$を得る段階を指すと見受けられる。 】

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

3.1. 可変~単位

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

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

注記： `可変~単位~参照$は， ~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));.

3.2. 無効な変数

`~custom~prop$が`無効が保証される値$をとる場合、 `var$f 関数による代用に利用できなくなる。 そのような場合、 妥当な~fallbackが指定されていない限り，【当の関数を利用している】宣言は`算出d値の時点で無効$になる。 ◎ When a custom property’s value is the guaranteed-invalid 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 ］を包含する場合は `算出d値の時点で無効@ になる。 あるいは，それが妥当な`~custom~prop$を利用していても、［ 当の~propの値が，その中の `var$f 関数が代用された後に妥当でなくなる場合 ］にも無効になる。 これが起きた場合、 当の~prop %~prop の`算出d値$は，次に従って与えられる： ◎ A declaration can be invalid at computed-value time if it contains a var() that references a custom property with the guaranteed-invalid 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 is one of the following depending on the property’s type:

%~prop は登録-済みでない`~custom~prop$である場合 ◎ The property is a non-registered custom property

%~prop は`全称~構文~定義$を伴う`登録-済み~custom~prop$である場合 ◎ The property is a registered custom property with universal syntax

算出d値は、 `無効が保証される値$になる。 ◎ The computed value is the guaranteed-invalid value.

他の場合 ◎ Otherwise

算出d値は、［ %~prop は`継承d~prop$であるならば，その`継承d値$／ ~ELSE_ %~prop の`初期~値$ ］になる — %~prop の値として `unset$v ~keywordが指定されていたかのように。 ◎ 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.

:root { --not-a-color: 20px; }
p { background-color: red; }
p { background-color: var(--not-a-color); }

注記： `算出d値の時点で無効$の概念は、 `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.3. 略式~propにおける変数

`var$f 関数は、 次に挙げる所で，ある複雑化をもたらす ⇒＃ `略式~prop$を その各 非略式~成分に構文解析するとき／ それら各 非略式~成分から`略式~prop$を直列化するとき ◎ var() functions produce some complications when parsing shorthand properties into their component longhands, and when serializing shorthand properties from their component longhands.

所与の`略式~prop$の値が，その ある`非略式~prop$（下位~prop）用の成分として `var$f 関数を包含する場合、 当の`非略式~prop$には，代わりに `代用待ちの値@ をあてがうモノトスル — この値は： ◎ If a shorthand property contains a var() function in its value, the longhand properties it’s associated with must instead be filled in with＼

• 作者からは観測-不能な特別な値であり，［ 略式~propは変数を包含するので、 非略式~propの値は，変数が`代用-$されるまで決定し得ない ］ことを指示する。 ◎ a special, unobservable-to-authors pending-substitution value that indicates the shorthand contains a variable, and thus the longhand’s value can’t be determined until variables are substituted.
• 通常通り~cascadeするモノトスル。 ◎ This value must then be cascaded as normal,＼
• `var$f 関数が算出d値の時点で`代用-$され終えた後に、 略式~propの値を構文解析して，非略式~propに適切な値をあてがうモノトスル。 ◎ and at computed-value time, after var() functions are finally substituted in, the shorthand must be parsed and the longhands must be given their appropriate values at that point.

【 該当する非略式~propは、 1 個の `var$f 関数に対し複数個あり得る — 当の `var^f が成す略式~propの成分~値が，複数個の非略式~prop用の値を与えるものと定義されている場合や、 当の `var^f 関数~自体が複数個の非略式~prop用の値を まとめて与えている場合など。 】

注記： ある`略式~prop$が `var$f を伴わずに記された場合、 その値は，構文解析-時点で各 非略式~成分に分離されるよう構文解析される。 各`非略式~prop$は、 その後に`~cascade$に関与する — それに伴い，当の略式~propは およそ破棄される。 しかしながら，これは、 当の略式~propが `var$f を包含するときには行えない — `var$f は何にでも代用され得るので。 ◎ Note: When a shorthand is written without a var(), it is parsed and separated out into its component longhand properties at parse time; the longhands then participate in the cascade, with the shorthand property more or less discarded. When the shorthand contains a var(), however, this can’t be done, as the var() could be substituted with anything.

`代用待ちの値$は、 ~APIによる観測-が許容される所では，空~文字列に直列化するモノトスル。 ◎ Pending-substitution values must be serialized as the empty string, if an API allows them to be observed.

`略式~prop$は、 その各~非略式~成分の値を集めることにより直列化され， 同じ値~集合に構文解析されることになる値を合成することになる。 所与の`略式~prop$に対し： ◎ Shorthand properties are serialized by gathering the values of their component longhand properties, and synthesizing a value that will parse into the same set of values.

• すべての`非略式~prop$が`代用待ちの値$になる場合、 当の`略式~prop$は，その元の（ `var$f を包含している）値に直列化するモノトスル。 ◎ If all of the component longhand properties for a given shorthand are pending-substitution values from the same original shorthand value, the shorthand property must serialize to that original (var()-containing) value.
• 他の場合，いずれかの`非略式~prop$が［ `代用待ちの値$になる場合 ／ まだ代用されていない自前の `var$f 関数を包含する場合 ］、 当の`略式~prop$は，空~文字列に直列化するモノトスル。 ◎ Otherwise, if any of the component longhand properties for a given shorthand are pending-substitution values, or contain var() functions of their own that have not yet been substituted, the shorthand property must serialize to the empty string.

3.4. 過度に長い変数の安全な取扱い

素朴に実装された `var$f 関数は、 “`billion laughs^en 攻撃” 【十億の笑い】の一種に利用され得る： ◎ Naively implemented, var() functions can be used in a variation of the "billion laughs attack":

.foo {
  --prop1: lol; /* 笑 */
  --prop2: var(--prop1) var(--prop1);
  --prop3: var(--prop2) var(--prop2);
  --prop4: var(--prop3) var(--prop3);
  /* etc */
}

この類の攻撃を避けるため、 ~UAは，［ `var$f 関数を展開した結果の~token~streamに許容される長さ ］に自身が定義する上限を課すモノトスル。 `var^f がこの上限より長い~token~streamに展開される場合、 代わりに，~propは`算出d値の時点で無効$になるよう展開されるとする。 ◎ To avoid this sort of attack, UAs must impose a UA-defined limit on the allowed length of the token stream that a var() function expands into. If a var() would expand into a longer token stream than this limit, it instead makes the property it’s expanding into invalid at computed-value time.

この仕様は、 課すベキ上限~sizeは定義しない。 しかしながら， 1000 ~byte以上の~textを包含するような~custom~prop用の妥当な利用事例もあるので、 上限は多少高めに設定することが推奨される。 ◎ This specification does not define what size limit should be imposed. However, since there are valid use-cases for custom properties that contain a kilobyte or more of text, it’s recommended that the limit be set relatively high.

注記： ［ ~UAには、 資源の拘束に因り標準に違反することが許容される ］とする一般~原則は、 ここにも一般に該当する。 ~UAは、 自身が~supportできる［ ~custom~propの~~長さ, 識別子の~~長さ ］に別々な上限を課すこともあろう。 この節が，この攻撃を特定的に引き合いに出すのは、 それには長い歴史があり，初回の検分では巨大~過ぎな~~片は`無さそうに見える^emものでも行える事実があることによる。 ◎ Note: The general principle that UAs are allowed to violate standards due to resource constraints is still generally true here; a UA might, separately, have limits on how long of a custom property they can support, or how large of an identifier they can support. This section calls out this attack specifically because of its long history, and the fact that it can be done without any of the pieces seeming to be too large on first inspection.

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.

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