CSS Properties and Values API Level 1 （日本語訳）

◎要約

この~CSS~moduleは、新たな~CSS~propを登録するための~APIを定義する。この~APIを利用して登録された~propは、［型, 継承の挙動, 初期~値］を定義する構文解析-構文を伴って供される。 ◎ This CSS module defines an API for registering new CSS properties. Properties registered using this API are provided with a parse syntax that defines a type, inheritance behaviour, and an initial value.

1. 序論

~CSSは、 ~web文書の［ ~layout, 塗り, 挙動］を改変するために操作できる~propたちが成す，包括的な集合を定義している。しかしながら、 ~web作者が，この集合に~propを追加して拡張したいと望むこともよくある。 ◎ CSS defines a comprehensive set of properties that can be manipulated in order to modify the layout, paint, or behaviour of a web document. However, web authors frequently wish to extend this set with additional properties.

`css-variables$r は，作者が制御する~propを定義するための基礎的な手段を供しているが、これらの~propは，常に~token~listを値にとり, 常に継承されなければならない。加えて、それが影響iし得るのは，文書の~layoutや塗りに限られる — `var^f 参照を介して他の~propの値を組入れることにより。 ◎ [css-variables] provides primitive means for defining user-controlled properties, however these properties always take token lists as values, must always inherit, and can only impact document layout or paint by being re-incorporated into the value of other properties via a var() reference.

この仕様は、 `css-variables$r を拡張し，［値~型, 初期~値, 定義-済みな継承の挙動］を備える~propを登録できるようにする — 次の 2 種の手法を介して： ◎ This specification extends [css-variables], allowing the registration of properties that have a value type, an initial value, and a defined inheritance behaviour, via two methods:

~JS~APIによる `registerProperty()$m ~method。 ◎ A JS API, the registerProperty() method
~CSS~at-規則 `property$at 規則。 ◎ A CSS at-rule, the @property rule

この仕様は［ `css-paint-api-1$r ／ `css-layout-api-1$r ］を補うものであり、 ~custom~propが［塗り／~layout ］の挙動に直に影響iできるようにする。 ◎ This specification is complementary to [css-paint-api-1] and [css-layout-api-1], which allow custom properties to directly impact paint and layout behaviours respectively.

2. 登録-済み~custom~prop

`~custom~prop$は、 `登録-済み~custom~prop@ になり得る — それは、［ ~UAにより検査される構文, 初期~値, 特有な継承の挙動］を与えることで，より~UA定義な~propの様に動作する。これは、［ `property$at 規則／ `CSS.registerProperty()$m ~JS関数］により行える。 ◎ A custom property can become a registered custom property, making it act more like a UA-defined property: giving it a syntax that’s checked by the UA, an initial value, and a specific inheritance behavior. This can be done by the @property rule, or the registerProperty() JS function.

`~custom~prop$は、その名前 %名前に関して ~OR↓ が満たされるならば，`文書$ %文書用に登録されたものと見なされる： ◎ A custom property is considered to be registered for a Document if＼

%文書のある~stylesheet内で %名前用の妥当な `property$at 規則が定義されている。 ◎ there is a valid @property rule defined for its name in one of the document’s stylesheets, or＼
%文書の`登録-済み~prop集合$[ %名前 ] ~NEQ ε （すなわち， `CSS.registerProperty()$m を~callして登録された）。 ◎ its name is contained in the document’s [[registeredPropertySet]] slot (that is, registerProperty() was called to register it).

`登録-済み~custom~prop$は、以下に定義されるものを除いて，未登録な`~custom~prop$と同様に動作する。 ◎ A registered custom property acts similarly to an unregistered custom property, except as defined below.

2.1. 登録の決定-法

各`登録-済み~custom~prop$は、 `~custom~prop登録@ を有する — それは、次に挙げるものからなる`構造体$であり，［ ~custom~propを本物の~propの様に扱うために必要yな，すべての~data ］を包含する： ◎ A registered custom property has a custom property registration that contains all the data necessary to treat it like a real property. It’s a struct consisting of:

~prop名 ⇒ `~custom~prop名~文字列$ ◎ a property name (a custom property name string)
構文 ⇒ `構文~文字列$ ◎ a syntax (a syntax string)
継承-~flag ⇒ `真偽値$ ◎ an inherit flag (a boolean)
初期~値（省略可能） ⇒＃ ε （省略時【 `initial-value$d を見よ】）／構文に`則って構文解析-$した結果は `失敗^i にならない`文字列$ ◎ optionally, an initial value (a string which successfully parses according to the syntax)

所与の`~custom~prop$ %~prop 用の`~custom~prop登録$は、 %~prop の名前 %名前により，次に従って決定される： ◎ ↓

`文書$の`登録-済み~prop集合$[ %名前 ] ~NEQ ε ならば，それが登録を与える。 ◎ If the Document’s [[registeredPropertySet]] slot contains a record with the custom property’s name, the registration is that record.
他の場合，次を満たす妥当な `property$at 規則が在るならば、それらのうち文書~順序で最後のものが登録を与える ⇒ ［ %名前用の登録を表現している］~AND［包含している~stylesheetは`文書$にて作動中である］ ◎ Otherwise, if the Document’s active stylesheets contain at least one valid @property rule representing a registration with the custom property’s name, the last such one in document order is the registration.
他の場合、登録を与えるものは無い — %~prop は、 `登録-済み~custom~prop$には`ならない^em。 ◎ Otherwise there is no registration, and the custom property is not a registered custom property.

2.2. 構文解析-時点の挙動

`登録-済み~custom~prop$は、未登録な`~custom~prop$と正確に同じに構文解析され，ほぼ何でも許容される。 ~propに登録された構文は、構文解析-時点では`検査されない^em。 ◎ Registered custom properties parse exactly like unregistered custom properties; almost anything is allowed. The registered syntax of the property is not checked at parse time.

注記：しかしながら，構文は、 `var$f を介した`代入$より前の，算出d値の時点で検査される。 `§ 算出d値の時点の挙動＠#calculation-of-computed-values$ を見よ。 ◎ Note: However, the syntax is checked at computed-value time, before substitution via var(). See § 2.4 Computed Value-Time Behavior.

なぜ、 ~custom~prop構文は検査されないか？ ◎ Why aren’t custom properties syntax-checked?

速さ, ~memory両面を助けるため、各種~UAは共通して，~pageの~CSSを構文解析するときにいくつかの最適化を施す。 ◎ When parsing a page’s CSS, UAs commonly make a number of optimizations to help with both speed and memory.

そのような最適化として、実際に効果がある~propに限り格納して，無効な~propを棄てることが挙げられる。同じ宣言~block内に同じ~propを複数回~書いた場合、最後の妥当なもの以外は，すべて棄てられることになる（これは、 ~CSSにおける［ ~error回復, 前方-互換性］の挙動の重要な一部を成す）。 ◎ One of those optimizations is that they only store the properties that will actually have an effect; they throw away invalid properties, and if you write the same property multiple times in a single declaration block, all but the last valid one will be thrown away. (This is an important part of CSS’s error-recovery and forward-compatibility behavior.)

これは、 ~propの構文が — ~pageが生き続ける間 — 決して変化しないなら，申し分なく働く。しかしながら，~custom~propが登録された場合、その構文は変化し得るため，それまで無効であった~propが突如~妥当になり得る。 ◎ This works fine if the syntax of a property never changes over the lifetime of a page. If a custom property is registered, however, it can change its syntax, so that a property that was previously invalid suddenly becomes valid.

これを取扱うためには、あらゆる宣言を — 初期~時には無効であったものも含め — 格納するか（~pageの~memory~costを高める）， ~page全体の~CSSを新たな構文~規則で構文解析し直す（~custom~propを登録する処理~costを高める）他にないが、どちらも，あまり望ましくない。 ◎ The only ways to handle this are to either store every declaration, even those that were initially invalid (increasing the memory cost of pages), or to re-parse the entire page’s CSS with the new syntax rules (increasing the processing cost of registering a custom property). Neither of these are very desirable.

更には，~UA定義な~propの構文は、各~利用者が~pageに利用している~UAの~versionにより決定され，~page作者の制御が及ぶ所でない — ~CSSの~error回復の挙動, および様々な~support~level用に複数の宣言を書く実施がある理由は、すべてそこにある。他方，~custom~propの構文は — ~stylesheet, ~scriptどちらであれ，作者が~page内に含ませたものに則って — ~page作者により制御されるので、管理すべき予測不能性は無い。したがって，構文に違反している~custom~propを棄てることは、最善でも~page作者にとっての便利にしかならず，~UA定義な~propのための様な必要性はない。 ◎ Further, UA-defined properties have their syntax determined by the version of the UA the user is viewing the page with; this is out of the page author’s control, which is the entire reason for CSS’s error-recovery behavior and the practice of writing multiple declarations for varying levels of support. A custom property, on the other hand, has its syntax controlled by the page author, according to whatever stylesheet or script they’ve included in the page; there’s no unpredictability to be managed. Throwing away syntax-violating custom properties would thus only be, at best, a convenience for the page author, not a necessity like for UA-defined properties.

2.3. `指定d値$の時点の挙動

未登録な他の`~custom~prop$と同じく，`登録-済み~custom~prop$は、登録された構文を問わず，［ `inherit$v, `revert$v ］などの`~CSS全域~keyword$を受容する。それらの挙動は、 `CSS-CASCADE-4$r `§ 明示的な~default法＠~CASCADE#defaulting-keywords$ にて定義される。 ◎ Just like unregistered custom properties, all registered custom properties, regardless of registered syntax, accept the CSS-wide keywords, such as inherit or revert. Their behavior is defined in CSS Cascading 4 § 7.3 Explicit Defaulting.

2.4. 算出d値の時点の挙動

`登録-済み~custom~prop$の`算出d値$は、その`~custom~prop登録$の構文により決定される。 ◎ The computed value of a registered custom property is determined by the syntax of its registration.

`~custom~prop登録$の構文が`全称~構文~定義$である場合、 ~propの`算出d値$は，未登録な`~custom~prop$に対するときと同じになる（指定d値を成す変数たちに`代入$を適用した結果か，`無効が保証される値$になる）。 ◎ If the registration’s syntax is the universal syntax definition, the computed value is the same as for unregistered custom properties (either the specified value with variables substituted, or the guaranteed-invalid value).

他の場合、 ~propの値を，登録された構文に`則って構文解析-$しようと試みる。これに失敗した場合、当の宣言は`算出d値の時点で無効$であり，`算出d値$はそれに則って決定される。成功した場合の`算出d値$は、構文が指定するもの【`構文~文字列$】に依存する： ◎ Otherwise, attempt to parse the property’s value according to its registered syntax. If this fails, the declaration is invalid at computed-value time and the computed value is determined accordingly. If it succeeds, the computed value depends on the specifics of the syntax:

`<length>^l

`<length-percentage>^l

`<angle>^l

`<time>^l

`<resolution>^l

`<integer>^l

`<number>^l

`<percentage>^l

算出d値は、指定d値に応じて： ◎ For "<length>", "<length-percentage>", "<angle>", "<time>", "<resolution>", "<integer>", "<number>", and "<percentage>" values:

~literalで与えられた`次元$である場合（ `50em^v や `.2s^v など） ⇒ 指定d値を，その単位に対応する`正準-単位$による値に換算した結果になる。 ◎ If the specified value is a dimension literal (such as 50em or .2s), the computed value is the same value, but with the unit converted to the corresponding canonical unit for the type of value.
他の数量-~literalである場合（ `5^v や `20%^v など） ⇒ 指定d値が，そのまま算出d値になる（特に，百分率が何かに対し解決されることは決してない）。 ◎ If the specified value is any other numeric literal (such as 5 or 20%), the computed value is as specified. (In particular, percentages are never resolved against anything.)
挙げられたいずれかの型に評価される関数である場合（`~math関数$など） ⇒ その関数により定義される。 ◎ If the specified value is a function that evaluates to one of those types (such as a math function), the computed value is defined by that function.

`<string>^l

算出d値は、指定されたとおりになる。 ◎ For "<string>" values, the computed value is as specified.

`<color>^l

算出d値は、 `算出d色$になる。 ◎ For "<color>" values, the value is computed by resolving color values, per CSS Color 4 § 14. Resolving <color> Values.

`<custom-ident>^l

`ident^t 【`参照＠#_ident$】

`*^l

指定d値がそのまま算出d値になる。 ◎ For "<custom-ident>", ident, or "*" values, the computed value is as specified.

`<url>^l ◎ For "<url>" values, the computed value is one of the following:

指定d値は相対~URLである場合、算出d値は `css3-values$r に従って絶対~URLに解決した結果になる。 ◎ if the URL is a relative URL, the computed value is the resolved absolute URL as described in [css3-values].

他の場合、指定d値がそのまま算出d値になる。 ◎ otherwise, the computed value is as specified.

~URLの挙動~例： ◎ URL behavior examples

~URLは，それが現れる~stylesheetの基底~URLに対して解決されるので、複数の相対~URLが異なる基底~URLに対して解決される結果になり得る — それらが同じ【名前の】~prop内に現れようが。 ◎ Because URLs resolve against the base URL of the stylesheet they appear in, we can end up with multiple relative URLs that resolve against different base URLs, even though they appear in the same property.

例えば `--url-foo^p, `--url-bar^p は、どちらも，構文に `url$t を与えて登録された~custom~propとする。ある~stylesheetが `/style/foo/foo.css^c に在って： ◎ For example, suppose --url-foo and --url-bar are registered custom properties with <url> syntax, and that we have a stylesheet at /style/foo/foo.css:

div {
  --url-foo: url("foo.png");
}

別の~stylesheetが `/style/bar/bar.css^c に在って： ◎ and another stylesheet at /style/bar/bar.css

div {
  --url-bar: url("bar.png");
}

文書は `/index.html^c に在るとする： ◎ and finally a document at /index.html:

<link href="/style/foo/foo.css" rel="stylesheet" type="text/css">
<link href="/style/bar/bar.css" rel="stylesheet" type="text/css">
<div style="background-image: var(--url-foo), var(--url-bar);">
</div>

ここでは、［ `var(--url-foo)^v ／ `var(--url-bar)^v ］参照は［ `/style/foo^c ／ `/style/bar^c ］に対して解決される~URLを生産することになる。 ◎ Here, the var(--url-foo) reference would produce a URL that resolves against /style/foo, and the var(--url-bar) reference would produce a URL that resolves against /style/bar.

他方，［ `--url-foo^p, `--url-bar^p ］がともに`未登録に^emされた場合、それぞれの~literal値（相対~URL）が， `/index.html^c 内の~stylesheetの中へ代入される結果，~URLは `/index.html^c に対し解決されることになる。 ◎ On the other hand, if both --url-foo and --url-bar were unregistered, they would substitute their literal values (relative URLs) into the /index.html stylesheet, which would then resolve the URLs against /index.html instead.

`<image>^l

算出d値は、 `image^t `用の算出d値＠~CSSIMAGE#computed-image$になる。【！~CSSIMAGE4#computed-image】 ◎ For "<image>" values, the computed value is the computed <image>.

`<transform-function>^l

`<transform-list>^l

算出d値は、指定d値を成すすべての長さ値を，各自の算出d値に解決した結果になる。 ◎ For "<transform-function>" and "<transform-list>" values, the computed value is as specified but with all lengths resolved to their computed values.

`複化子$を伴う構文

算出d値は、 ~listを成す各~項に基底~型~用の算出d値の規則を適用した結果になる。 ◎ For values with multipliers, the computed value is a list of the computed values of the base type.

`|^css `結合子$で指定された構文

算出d値は、指定d値に［それに合致する最初の項の型］用の算出d値の規則を適用した結果になる。 ◎ For syntaxes specified with the | combinator, the computed value is given by applying the computed-value rules for the first clause that matches the value.

2.5. ~animationの挙動

注記：［ `css3-animations$r ／ `css3-transitions$r ］にて定義されるとおり，~custom~propを参照する［ ~animation ／遷移］を指定することもアリである。 ◎ Note: As defined by [css3-animations] and [css3-transitions], it is possible to specify animations and transitions that reference custom properties.

［ ~animation／遷移］から参照される~custom~propの値は、その値が構文解析された型に則って，`算出d値により$ `補間-$される。 ◎ When referenced by animations and transitions, custom property values interpolate by computed value, in accordance with the type that they parsed as.

注記：このことは、 `color^t+ や `color^t# などの値~listは、単純~listとして補間されることを含意する — 互いの成分を各~indexごとに対応~付けて，成分の個数が合致しない場合は失敗するように。 ◎ Note: This implies that a list of values, such as <color>+ or <color>#, will interpolate as a simple list, matching up each component index-by-index, and failing if the number of components doesn’t match.

上の規則に対する例外として、［ `transform-list^t ／ `transform-function^t ／ `transform-function^t+ ］として構文解析される値は、代わりに `transform$p ~propに従って補間される。 ◎ As an exception to the above rule, a value that parsed as a <transform-list>, a <transform-function>, or a <transform-function>+ instead interpolates as per the transform property.

注記：何らかの理由で，構文 `transform-function^t# を伴って定義された~custom~propは、先ず単純~listとして補間されてから，各~list~itemが `transform$p 値として補間されることになる。 ◎ Note: If, for whatever reason, a custom property is defined with a syntax of <transform-function>#, this will thus first interpolate as a simple list, and then each list item will interpolate as a transform value.

注記： ~custom~propを登録すると（あるいは登録を変更したときも）、その算出d値も変化し得る結果，~CSS遷移を開始したり中断し得る。 ◎ Note: Registering (or changing the registration) of a custom property can change its computed value, which can start or interrupt a CSS transition.

2.6. 条件付き規則

`§ 構文解析-時点の挙動＠#parsing-custom-properties$ にて言明したとおり、［未登録な`~custom~prop$, `登録-済み$なそれ］どちらも，構文解析-時点ではアリな（ほぼ）すべての値を受容する。 `登録-済み$な`~custom~prop$の構文は、 `算出d値$の時点に限り適用される。 ◎ As stated in § 2.2 Parse-Time Behavior, both unregistered and registered custom properties accept (almost) all possible values at parse-time. Registered custom properties only apply their syntax at computed value time.

なので，すべての`~custom~prop$は、 `登録-済み$か否かを問わず， `supports$at 規則による~testの結果は `真^i になる — `~custom~prop$用の（ごく寛容な）汎用~構文に違反していない限り。 ◎ So, all custom properties, regardless of whether they’re registered or unregistered, will test as "true" in an @supports rule, so long as you don’t violate the (very liberal) generic syntax for custom properties.

例えば，~custom~prop `--foo^p が `syntax: "<color>";^c を伴って登録された場合でも、 `supports$at (`--foo^p: `1em^v) {...} の様な規則は `真^i に評価され，その中の~styleは適用される — その【丸括弧で括られた】宣言は、妥当な~propとして`成功裡に構文解析される^emので。 ◎ For example, even if a custom property is registered with syntax: "<color>";, a rule like @supports (--foo: 1em) {...} will still evaluate as true and apply those styles, because the declaration does successfully parse as a valid property.

2.7. `var^f を介した代入

`登録-済み~custom~prop$の値は、未登録な~custom~propと同様に，別の値の中の `var$f 関数へ代入され得る。しかしながら，登録-済み~custom~propは、その`算出d値として代入される＠#calculation-of-computed-values$ — その値を生産するときに利用される元の~token列ではなく。 ◎ Like unregistered custom properties, the value of a registered custom property can be substituted into another value with the var() function. However, registered custom properties substitute as their computed value, rather than the original token sequence used to produce that value.

`var$f 関数のうち，`登録-済み~custom~prop$を参照するものは、 `等価な~token列@ — 次の結果の文字列を`~token化$して生産される~token列 — に置換するモノトスル ⇒ `~CSS値を直列化する$( ~custom~propの算出d値 ) ◎ Any var() function that references a registered custom property must be replaced with an equivalent token sequence, which is equal to the token sequence that would have been produced by serializing the computed value, and tokenizing the resulting string.

~custom~prop `--x^p は `length$t 構文で登録されていて， `--y^p は未登録な~custom~propとする。 ◎ Suppose that --x is registered with <length> syntax, and that '--y’is an unregistered custom property.

div {
  font-size: 10px;
  --x: 8em;
  --y: var(--x);
}

`--x^p の算出d値（を直列化した結果）は `80px^l になるので、 `--y^p の算出d値は［数値 80, 単位 `px^l ］を伴う `dimension-token$t になる。 ◎ Because the computed value of --x (when serialized) is "80px", the computed value of --y is a <dimension-token> with a value of "80" and unit "px".

2.7.1. `var^f 参照における~fallback

`var$f 関数を利用する`登録-済み~custom~prop$への参照は，~fallbackを供してもヨイが、 ~fallback値は，参照-先の~custom~propの`構文~定義$に合致しなければナラナイ — さもなければ、宣言は`算出d値の時点で無効$になるとする。 ◎ References to registered custom properties using the var() function may provide a fallback. However, the fallback value must match the syntax definition of the custom property being referenced, otherwise the declaration is invalid at computed-value time.

注記：これは、 ~fallbackが利用されるかどうかに関わらず，適用される。 ◎ Note: This applies regardless of whether or not the fallback is being used.

2.7.2. 相対~単位を介する循環依存

`登録-済み~custom~prop$は、循環依存の解決にあたり，`未登録な~custom~propと同じ規則＠~CSSVAR#cycles$に従うが、以下に挙げる追加的な拘束も~~課される: ◎ Registered custom properties follow the same rules for dependency cycle resolution as unregistered custom properties, with the following additional constraints:

%要素上の %~prop が`登録-済み~custom~prop$であって，その構文~成分に［ `length$t ／ `length-percentage$t ］を伴う場合、 %~prop の値が： ◎ For any registered custom property with a <length> or <length-percentage> syntax component:

［ `em$u ／ `ex$u ／ `cap$u ／ `ch$u ／ `ic$u ／ `lh$u ］単位を伴う場合 ⇒ %~prop から %要素の `font-size$p ~propへ辺で結ぶ。 ◎ If the property contains any of the following units: em, ex, cap, ch, ic, lh; then add an edge between the property and the font-size of the current element.
`lh$u 単位を伴う場合 ⇒ %~prop から %要素の `line-height$p ~propへ辺で結ぶ。 ◎ If the property contains the lh unit, add an edge between the property and the line-height of the current element.
［ `rem$u ／ `rlh$u ］単位を伴う場合 ⇒ %~prop から`根~要素$の `font-size$p ~propへ辺で結ぶ。† ◎ If the property contains any of the following units: rem, rlh; then add an edge between the property and the font-size' of the root element.
`rlh$u 単位を伴う場合 ⇒ %~prop から`根~要素$の `line-height$p ~propへ辺で結ぶ。† ◎ If the property contains the rlh unit, add an edge between the property and the line-height' of the root element.

【† %要素が`根~要素$でないならば、これが有意になることはない。要素とその先祖の間では、循環依存は生じ得ないので。】

例えば，次の登録が与えられたとする： ◎ For example, given this registration:

CSS.`registerProperty$m({
  name: "--my-font-size",
  syntax: "<length>",
  initialValue: "0px",
  inherits: false
});

次の~styleは、循環依存を生産することになる： ◎ the following will produce a dependency cycle:

div {
  --my-font-size: 10em;
  font-size: var(--my-font-size);
}

`font-size^p は、値 `unset$v が指定されていたかのように挙動することになる。 ◎ and font-size will behave as if the value unset was specified.

2.8. ~shadow~DOM

~CSSにおける多くの概念（ `CSS-SCOPING-1$r `§ 名前を定義する構成子と継承＠~CSSSCOPING#shadow-names$ を見よ）と違って、 ~prop登録の視野は， ~tree視野にはならない。どの登録も、それが［最も外縁な文書~内, `~shadow~tree$の中］どちらに現れようが，当の`文書$用の同じ大域的な登録~map内でヤリトリする。 ◎ Unlike many concepts in CSS (see CSS Scoping 1 § 3.5 Name-Defining Constructs and Inheritance), property registrations are not scoped to a tree scope. All registrations, whether they appear in the outermost document or within a shadow tree, interact in a single global registration map for the Document.

注記：登録を視野~付きにできないのはなぜか？ ◎ Why can’t registrations be scoped?

~prop登録を視野~付きにする明瞭な利用事例もある ⇒ ある~componentが~shadow~DOMを利用していて，自前の内部~利用~用に何らかの`~custom~prop$を登録しているなら、おそらく，外縁~pageから当の登録が見られることは意図しない — 外縁~pageは、当の~componentがその~propを利用していることすら知らないので。 ◎ There are clear use-cases for property registrations to be scoped—a component using Shadow DOM and registering some custom properties for its own internal use probably doesn’t intend for the outer page to see the registration, since the outer page doesn’t even know the component is using that property.

しかしながら，当の登録を視野を絞らない理由もある ⇒ `~custom~prop$は、 ~componentの`中へ^em~dataを~pipeするためにも利用される — 外縁~pageにとっては、そのような~custom~propが設定-可能になり，当の登録により構文を検査させることが有用になる。類似に，~propの初期~値などの概念は、当の~prop登録が大域的に存在しない限りさほどイミを成さないので，文書の根においても当の~propに適用される。 ◎ However, there are also reasons to not scope the registration—custom properties are used to pipe data into a component, and it’s useful for the outer page to be able to set such custom properties and have them syntax-checked by the registration; similarly, concepts such as a property’s initial value don’t make much sense unless the property registration exists globally, so it applies to the property even at the document’s root.

が、上述が意味するのは，［登録の視野は、制御-可能になるべきものかもしれず，大域的になるよう強制されるべきでない］ことだけである。 ◎ But the above just means that registration scope might be something that should be controllable, not that it should be forced to be global.

登録が大域的でなければならない理由は、要素は同時に複数の~tree視野に入り得るからである — 各~tree視野からの~styleが混ぜ合わされ，一緒に~cascadeされるよう。このことは、 `~shadow~tree$を`~hostしている要素＠~CSSSCOPING#shadow-gloss$【！~TR/css-scoping-1/#host-element0】にも, ~shadow~DOMの内側にある要素にも適用される — 前者は［外縁~tree【`~light~tree$】内に住まうが， `host$ps 選択子により~shadow~treeからも~style可能］であり，後者は［ `part()$pe 疑似要素により外縁~treeから~target可能］である。 ◎ The reason registrations must be global is because elements can exist in multiple tree scopes at the same time, with styles from each tree scope intermingling and cascading together. This applies to the host element, which lives in the outer tree but is stylable from the shadow tree by the :host selector, but also elements inside a shadow DOM that are targetable from the outer tree by the ::part() pseudo-element.

登録の視野を~tree視野に絞れたとする場合、［同じ名前の【！a single】~propが~treeの内側でも外側でも登録された場合に、どの登録を適用する下で値を構文解析するべきか］は，明瞭でない。ある値がどの~treeから来たかを（他の［視野が~treeに絞られた値］用に行われる何かのように）追跡して，対応する登録を適用したとする場合でも、適理な結果を与えるようになるかは，明瞭でない — ~shadow~DOMは、ある~propが特定0の値~空間に入ることを期待するかもしれない — 外縁~treeが~cascadeに勝って，自前の登録を適用したときには、意に沿わない完全に異なる何かを受取ることになろう。 ◎ If registrations could be scoped to a tree scope, and a single property was registered both inside and outside, it’s not clear which registration should be applied to parse the value. Even if we tracked which tree a value came from (something we do for other tree-scoped values) and applied the corresponding registration, it’s not clear that this would give a reasonable result—the shadow DOM might expect a property to have a particular value space, and be surprised when it receives something completely different due to the outer tree winning the cascade and applying its own registration.

この［大域的な登録の挙動］は、 `~custom~prop$が［ある~shadow~DOMを利用している~componentの公な~API ］の一部として公開されるときには，意図されたとおりに働く。外縁~pageが，同じ名前のある~custom~propを異なる目的で利用している場合、それは事前に解決される必要がある競合であり，登録の挙動がそれを悪化させることはない。 ◎ When custom properties are exposed as part of a Shadow DOM-using component’s public API, this global registration behavior works as intended. If the outer page is using a custom property of the same name for different purposes, that is already a conflict that needs to be resolved, and the registration behavior does not make it worse.

しかしながら，ある`~custom~prop$が［ある~component用に私的な，内部的な用法が意図されたもの］である場合、当の~propには［他の文脈との衝突のアリ性を最小~化するよう，一意になると見込まれる名前］を与えることが推奨される — 例えば、当の~propの名前に［ ~project名や, 何らかの短い~randomな文字列］などを含めることにより。 ◎ If a custom property is intended for private internal usage for a component, however, it is recommended that the property be given a likely-unique name, to minimize the possibility of a clash with any other context. This can be done, for example, by including the project name, or some short random string of text, in the name of the property.

3. `property^at 規則

`property@at 規則は、 ~JSを走らすことなく，`~custom~prop登録$を~stylesheet内で直に表現する。妥当な `property$at 規則からは、等価な~parameterで `registerProperty()$m を~callしたかのように，`登録-済み~custom~prop$が得られることになる。 ◎ The @property rule represents a custom property registration directly in a stylesheet without having to run any JS. Valid @property rules result in a registered custom property, as if registerProperty() had been called with equivalent parameters.

`property$at の構文は： ◎ The syntax of @property is:

@property `custom-property-name$t {
	`declaration-list$t
}

妥当な `property$at 規則は、 `~custom~prop登録$を表現する。その~prop名は、規則の導入部に与えた `custom-property-name$t の直列化になる。 ◎ A valid @property rule represents a custom property registration, with the property name being the serialization of the <custom-property-name> in the rule’s prelude.

`property$at 規則には、［ `syntax$d, `inherits$d ］記述子が要求される。どちらかが欠落な場合、規則~全体が無効になり，無視されるモノトスル。 `initial-value$d 記述子は、構文が`全称~構文~定義$である場合に限り省略可能であり，他の場合は要求される — 欠落な場合、規則~全体が無効になり，無視されるモノトスル。 ◎ @property rules require a syntax and inherits descriptor; if either are missing, the entire rule is invalid and must be ignored. The initial-value descriptor is optional only if the syntax is the universal syntax definition, otherwise the descriptor is required; if it’s missing, the entire rule is invalid and must be ignored.

未知な記述子は、無効であり無視されるが， `property$at 規則を無効~化することはない。 ◎ Unknown descriptors are invalid and ignored, but do not invalidate the @property rule.

`§ 登録の決定-法＠#determining-registration$に指定されるとおり，同じ `custom-property-name$t 用に複数の妥当な `property$at 規則が定義された場合、 ~stylesheet順序で最後のものが “勝つ”。 `registerProperty()$m による~custom~prop登録は、同じ `custom-property-name$t 用のどの `property$at 規則にも勝つ。 ◎ Note: As specified in § 2.1 Determining the Registration, if multiple valid @property rules are defined for the same <custom-property-name>, the last one in stylesheet order "wins". A custom property registration from CSS.registerProperty() further wins over any @property rules for the same <custom-property-name>.

3.1. `syntax^d 記述子

◎述 `syntax@d ◎用 `property$at ◎値 `string$t ◎初可用でない（注釈文を見よ） ◎ n/a (see prose) ◎表終

`property$at 規則で表現される`~custom~prop登録$の構文を指定する。それは、 `算出d値$の時点で~propの値がどう構文解析されるかを制御する。 ◎ Specifies the syntax of the custom property registration represented by the @property rule, controlling how the property’s value is parsed at computed value time.

`property$at 規則が妥当になるためには、この記述子が要求される。欠落な場合、 `property$at 規則は無効になる。 ◎ The syntax descriptor is required for the @property rule to be valid; if it’s missing, the @property rule is invalid.

供された文字列が妥当な`構文~文字列$でない場合（`構文~定義を消費する$( その文字列 ) の結果が `失敗^i になる場合）、記述子は無効になり，無視されるモノトスル。 ◎ If the provided string is not a valid syntax string (if it returns failure when consume a syntax definition is called on it), the descriptor is invalid and must be ignored.

3.2. `inherits^d 記述子

◎述 `inherits@d ◎用 `property$at ◎値 `true^v | `false^v ◎初可用でない（注釈文を見よ） ◎ n/a (see prose) ◎表終

`property$at 規則で表現される`~custom~prop登録$の継承-~flagを指定する。それは、 ~propが既定で継承されるかどうかを制御する。 ◎ Specifies the inherit flag of the custom property registration represented by the @property rule, controlling whether or not the property inherits by default.

`property$at 規則が妥当になるためには、この記述子が要求される。欠落な場合、 `property$at 規則は無効になる。 ◎ The inherits descriptor is required for the @property rule to be valid; if it’s missing, the @property rule is invalid.

3.3. `initial-value^d 記述子

◎述 `initial-value@d ◎用 `property$at ◎値 `declaration-value$t? ◎初 `無効が保証される値$（注釈文を見よ） ◎ the guaranteed-invalid value (but see prose) ◎表終

`property$at 規則で表現される`~custom~prop登録$の初期~値を指定する。それは、 ~propの`初期~値$を制御する。 ◎ Specifies the initial value of the custom property registration represented by the @property rule, controlling the property’s initial value.

この記述子は、 `syntax$d 記述子の値が`全称~構文~定義$である場合には，省略可能である。省略された場合、 ~propの`初期~値$は，`無効が保証される値$になる。 ◎ If the value of the syntax descriptor is the universal syntax definition, then the initial-value descriptor is optional. If omitted, the initial value of the property is the guaranteed-invalid value.

`syntax$d 記述子の値が`全称~構文~定義$でない場合、 `property$at 規則が妥当になるためには， ~AND↓ が満たされなければナラナイ： ◎ Otherwise, if the value of the syntax descriptor is not the universal syntax definition, the following conditions must be met for the @property rule to be valid:

`initial-value$d 記述子が在る。 ◎ The initial-value descriptor must be present.
`initial-value$d 記述子の値は、 `syntax$d 記述子の値に指定された文法（`構文~定義$）に則って，成功裡に構文解析される。【！#consume-a-syntax-definition】 ◎ The initial-value descriptor’s value must parse successfully according to the grammar specified by the syntax definition.
`initial-value$d は`独立に算出-可能$である。 ◎ The initial-value must be computationally independent.

上のいずれかの条件が満たされない場合、 `property$at 規則は無効になる。 ◎ If the above conditions are not met, the @property rule is invalid.

4. ~JSにおける~custom~propの登録-法

~JSを介して~custom~propを登録するため、 `CSS$I 名前空間は， `registerProperty()$m ~methodで拡張される： ◎ To register a custom property via JS, the CSS object is extended with a registerProperty() method:

dictionary `PropertyDefinition$I {
  required `DOMString$ `name$m;
           `DOMString$ `syntax$m = "*";
  required `boolean$   `inherits$m;
           `DOMString$ `initialValue$m;
};

partial namespace `CSS$I {
  `undefined$ `registerProperty$m(`PropertyDefinition$I %definition);
};

各`文書$は、 `登録-済み~prop集合@ を有する — それは、 `有順序~map$であり，`登録-済み~custom~prop$について述べる~record【`~custom~prop登録$】たちを~~保持する。 ◎ Additional, the Document object gains a new [[registeredPropertySet]] private slot, which is a set of records that describe registered custom properties.

【これは，原文では、 “`registeredPropertySet^sl `private slot^en” （~JS内部~slot）と称され，その構造も明示的に指定されていないが、実質的には~prop名を`~custom~prop登録$ （それは、抽象-~dataである）に対応付ける~mapとして挙動するので，この訳ではこのように改める。】

4.1. `registerProperty()^m ~method

`registerProperty(definition)@m ~methodは、供された環境設定~option群に則って~custom~propを登録する。その~method~手続きは ⇒ `~custom~propを登録する$( ↓ ) ⇒＃ %definition[ "`name$m" ], %definition[ "`syntax$m" ], %definition[ "`inherits$m" ], %definition[ "`initialValue$m" ] ◎ The registerProperty(PropertyDefinition definition) method registers a custom property according to the configuration options provided in definition.＼ ◎ When it is called, it executes the register a custom property algorithm, passing the options in its definition argument as arguments of the same names.

`~custom~propを登録する@ ときは、所与の ( 文字列 %名前, 文字列 %構文, 真偽値 %継承するか, 文字列 %初期~値 ) に対し，次の手続きを実行する： ◎ To register a custom property with name being a string, and optionally syntax being a string, inherits being a boolean, and initialValue being a string, execute these steps:

%~prop集合 ~LET `現在の大域~obj$に`結付けられた文書$の`登録-済み~prop集合$ ◎ Let property set be the value of the current global object’s associated Document’s [[registeredPropertySet]] slot.
~IF［ %名前は`~custom~prop名~文字列$でない］ ⇒ ~THROW `SyntaxError$E ◎ If name is not a custom property name string, throw a SyntaxError and exit this algorithm.
~IF［ %~prop集合[ %名前 ] ~NEQ ε ］ ⇒ ~THROW `InvalidModificationError$E ◎ If property set already contains an entry with name as its property name (compared codepoint-wise), throw an InvalidModificationError and exit this algorithm.
%構文~定義 ~LET `構文~定義を消費する$( %構文 ) ◎ Attempt to consume a syntax definition from syntax.＼
~IF［ %構文~定義 ~EQ `失敗^i ］ ⇒ ~THROW `SyntaxError$E ◎ If it returns failure, throw a SyntaxError. Otherwise, let syntax definition be the returned syntax definition.
%構文解析した初期~値 ~LET 次の手続きを遂行した結果： ◎ ↓
1. ~IF［ %構文~定義は`全称~構文~定義$である］：
  1. ~IF［ %初期~値 ~EQ ε ］ ⇒ ~RET ε — これは［ `css-variables$r に定義されるとおり，`~custom~prop$の “既定の” 初期~値【すなわち、`無効が保証される値$】］として扱うモノトスル。
  2. ~RET %初期~値を `declaration-value$t に`則って構文解析-$した結果
  ◎ If syntax definition is the universal syntax definition, and initialValue is not present, let parsed initial value be empty. This must be treated identically to the "default" initial value of custom properties, as defined in [css-variables]. Skip to the next step of this algorithm. ◎ Otherwise, if syntax definition is the universal syntax definition, parse initialValue as a <declaration-value>. If this fails, throw a SyntaxError and exit this algorithm. Otherwise, let parsed initial value be the parsed result. Skip to the next step of this algorithm.
2. ~IF［ %初期~値 ~EQ ε ］ ⇒ ~RET `失敗^i ◎ Otherwise, if initialValue is not present, throw a SyntaxError and exit this algorithm.
3. %結果 ~LET %初期~値を %構文~定義に`則って構文解析-$した結果 ◎ Otherwise, parse initialValue according to syntax definition.＼
4. ~IF［ %結果 ~EQ `失敗^i ］ ⇒ ~RET `失敗^i ◎ If this fails, throw a SyntaxError and exit this algorithm.
5. ~IF［ %結果は`独立に算出-可能$でない］ ⇒ ~RET `失敗^i ◎ Otherwise, let parsed initial value be the parsed result. If parsed initial value is not computationally independent, throw a SyntaxError and exit this algorithm.
6. ~RET %結果 ◎ ↑
~IF［ %構文解析した初期~値 ~EQ `失敗^i ］ ⇒ ~THROW `SyntaxError$E ◎ ↑
%登録 ~LET 新たな`~custom~prop登録$【！`構造体$】 — その ⇒＃ ~prop名 ~SET %名前, 構文 ~SET %構文~定義, 初期~値 ~SET %構文解析した初期~値, 継承-~flag ~SET %継承するか ◎ Set inherit flag to the value of inherits. ◎ Let registered property be a struct with a property name of name, a syntax of syntax definition, an initial value of parsed initial value, and an inherit flag of inherit flag.＼
%~prop集合[ %名前 ] ~SET %登録 ◎ Append registered property to property set.

要素の~propの値【`指定d値$】は、当の値および［ ~CSSにより変更し得ない “大域的な” 情報］のみを利用して`算出d値$に変換できるならば， `独立に算出-可能@ であるとされる。 ◎ A property value is computationally independent if it can be converted into a computed value using only the value of the property on the element, and "global" information that cannot be changed by CSS.

例えば `5px^v は、 `独立に算出-可能$になる — それを算出d値に変換した結果は ~~元のままなので。同様に，`1in^v も、 `独立に算出-可能$になる — 算出d値に変換するときには，［ `1in^v は `96px^v である］という “大域的な知識” のみに依拠し、 ~CSSにおける何ものも，それを［改める／調整する］ことはないので。 ◎ For example, 5px is computationally independent, as converting it into a computed value doesn’t change it at all. Similarly, 1in is computationally independent, as converting it into a computed value relies only on the "global knowledge" that 1in is 96px, which can’t be altered or adjusted by anything in CSS.

他方， `3em^v は`独立に算出-可能$でない — それは、要素（または要素の親）の `font-size$p 値に依拠するので。 `var$f 関数を伴う値も`~custom~prop$の値に依拠するので~~同様になる。 ◎ On the other hand, 3em is not computationally independent, because it relies on the value of font-size on the element (or the element’s parent). Neither is a value with a var() function, because it relies on the value of a custom property.

所与の型を伴う~custom~propが登録されたとき、その~prop用の指定d値を算出d値に転換する処理-は，選定された型により全部的に定義される — `§ 算出d値の時点の挙動＠#calculation-of-computed-values$ にて述べられるとおり。 ◎ When a custom property is registered with a given type, the process via which specified values for that property are turned into computed values is defined fully by the type selected, as described in § 2.4 Computed Value-Time Behavior.

注記：将来には、 ~propを未登録にする仕方も追加され得る。 ◎ Note: A way to unregister properties may be added in the future.

~custom~propの登録は、いかなる仕方でも，`~cascade$に影響しないモノトスル。登録された~prop用に指定した構文を問わず、 `~custom~prop$は，構文解析-時点では通常通りほぼ何でも受容するように構文解析される。しかしながら，`登録-済み~custom~prop$用の`指定d値$が登録した構文に違反する場合、 ~propは`算出d値の時点で無効$になる（したがって，登録した初期~値に設定し直される）。 ◎ Registering a custom property must not affect the cascade in any way. Regardless of what syntax is specified for a registered property, at parse time it is still parsed as normal for a custom property, accepting nearly anything. If the specified value for a registered custom property violates the registered syntax, however, the property becomes invalid at computed-value time (and thus resets to the registered initial value).

既定では、一連の~token並びとして構文解析できるどの~custom~prop宣言も妥当になる。よって，次の~stylesheetによる結果は： ◎ By default, all custom property declarations that can be parsed as a sequence of tokens are valid. Hence, the result of this stylesheet:

.thing {
  --my-color: green;
  --my-color: url("not-a-color");
  color: var(--my-color);
}

`class^a `thing^l を伴う要素の `color$p ~propは、 `inherit$v に設定される — 2 個目の `--my-color^p 宣言は，構文解析-時に 1 個目のものを上書きし（両者とも妥当である）、 `color$p ~prop内の `var$f 参照は `算出d値の時点で無効$と見出されるので（ `url("not-a-color")^v は `color$t でないので）。 ~CSS~pipelineのこの段階（算出d値の時点）で可用な~fallbackは，~propの初期~値しかなく、 `color$p の事例では `inherit$v になる。利用-可能な妥当な値は他にもあるが（ `green^v ）、 `url^f がより~~優先されるので，構文解析-時に除去される。 ◎ is to set the color property of elements of class "thing" to inherit. The second --my-color declaration overrides the first at parse time (both are valid), and the var() reference in the color property is found to be invalid at computed-value time (because url("not-a-color") is not a color). At this stage of the CSS pipeline (computation time), the only available fallback is the initial value of the property, which in the case of color is inherit. Although there was a valid usable value (green), this was removed during parsing because it was superseded by the URL.

次を~callした場合： ◎ If we call:

CSS.`registerProperty$m({
  name: "--my-color",
  syntax: "<color>",
  initialValue: "black",
  inherits: false
});

この登録が上の~stylesheetを構文解析する前, 後どちらに生じようが、構文解析が有意に変化することはない。登録が生じたときの，唯一の相違は：代わりに `--my-color^p ~propが`算出d値の時点で無効$になり、その初期~値 `black^v に設定される。それから、 `color$p が妥当に `black$v に設定される — `算出d値の時点で無効$にされて `inherit$v になるのではなく。 ◎ the parsing doesn’t significantly change, regardless of whether the registration occurs before or after the stylesheet above. The only difference is that it’s the --my-color property that becomes invalid at computed-value time instead and gets set to its initial value of black; then color is validly set to black, rather than being invalid at computed-value time and becoming inherit.

4.2. `PropertyDefinition^I 辞書

`PropertyDefinition@I 辞書は、作者が指定した［ ~custom~prop用の環境設定~option群］を表現する — それは、次に挙げる~memberからなる： ◎ A PropertyDefinition dictionary represents author-specified configuration options for a custom property. PropertyDefinition dictionaries contain the following members:

`name@m ◎ name, of type DOMString: 定義する~custom~propの名前を与える。 ◎ The name of the custom property being defined.
`syntax@m ◎ syntax, of type DOMString, defaulting to "*": この~custom~propをどう構文解析するかを表現する文字列を与える。 ◎ A string representing how this custom property is parsed.
`inherits@m ◎ inherits, of type boolean: この~custom~propは［継承するべきならば ~T ／他の場合は ~F ］。 ◎ True if this custom property should inherit down the DOM tree; False otherwise.
`initialValue@m ◎ initialValue, of type DOMString: この~custom~propの初期~値を与える。 ◎ The initial value of this custom property.

5. 構文~文字列

`構文~文字列@ は、［ `登録-済み~custom~prop$が受容する値~型］を述べる。構文~文字列は、【 `*^l でないならば，】いくつかの`構文~成分~名$ — それぞれが省略可能な`複化子$を伴い，`結合子$で分離されたそれら — からなる。 ◎ A syntax string describes the value types accepted by a registered custom property. Syntax strings consists of syntax component names, that are optionally multiplied and combined.

`構文~文字列$は、次のいずれかの`構文~定義$に構文解析され得る： ◎ A syntax string can be parsed into a syntax definition, which is either:

【1 個以上の】`構文~成分$たちが成す~list — 各~構文~成分は、 `§ ~supportされる名前＠#supported-names$ にて指定される対応する値~型を受容する。 ◎ A list of syntax components, each of which accept the value types specified in § 5.1 Supported Names, or
`全称~構文~定義$（ `*^l ） — ~~任意の妥当な~token~streamを受容する。 ◎ The universal syntax definition (*), which accepts any valid token stream.

注記：指定された構文を問わず，すべての~custom~propは、 `~CSS全域~keyword$を受容して，それらの値を適切に処理する。 ◎ Note: Regardless of the syntax specified, all custom properties accept CSS-wide keywords, and process these values appropriately.

例えば，次に挙げるものは、どれも妥当な構文~文字列になる： ◎ For example, the following are all valid syntax strings.

`<length>^l: 【！Any valid 略】長さ値を受容する。 ◎ accepts length values
`<length> | <percentage>^l: 次に挙げる値を受容する ⇒＃長さ, 百分率, 百分率を与える~calc式, 長さを与える~calc式 ◎ accepts lengths, percentages, percentage calc expressions, and length calc expressions,＼; ［長さ値, 百分率~値］の組合nを包含している~calc式は受容しない。 ◎ but not calc expressions containing a combination of length and percentage values.
`<length-percentage>^l: ［ `<length> | <percentage>^l ］が受容するすべての値を受容する。 ◎ accepts all values that "<length> | <percentage>" would accept,＼; 長さ値と百分率~値の組合nを包含している~calc式も受容する。 ◎ as well as calc expressions containing a combination of both length and percentage values.
`big | bigger | BIGGER^l: 次に挙げる値（いずれも `ident^t ）を受容する ⇒＃ `big^v, `bigger^v, `BIGGER^v ◎ accepts the ident big, or the ident bigger, or the ident BIGGER.
`<length>+^l: ~space等で分離された 1 個~以上の長さ値たちが成す~listを受容する。 ◎ accepts a space-separated list of length values.
`*^l: 妥当などの~token~streamも受容する。 ◎ accepts any valid token stream

注記：構文~文字列の内部的な文法は、 `値~定義~構文＠~CSSVAL#value-defs$ `CSS-VALUES-4$r の下位集合である。この仕様の将来~levelでは、［ ~CSS~propが許容する全部的な構文を，より近く真似る~custom~prop ］も許容するよう［許容される文法の複階性を拡げる］ものと期待されている。 ◎ Note: The internal grammar of syntax strings is a subset of the CSS Value Definition Syntax. Future levels of this specification are expected to expand the complexity of the allowed grammar, allowing custom properties that more closely resemble the full breadth of what CSS properties allow.

以降の各節では、構文~文字列の内部的な文法を述べる。 ◎ The remainder of this chapter describes the internal grammar of the syntax strings.

5.1. ~supportされる名前

この節は、 `~supportされる構文~成分~名@ および［結果の`構文~成分$が受容する，その成分~名に対応する型］を定義する。 ◎ This section defines the supported syntax component names, and the corresponding types accepted by the resulting syntax component.

`<length>^l: 【！Any valid】 `length$t 値 ◎ Any valid <length> value
`<number>^l: `number$t 値 ◎ <number> values
`<percentage>^l: `percentage$t 値 ◎ Any valid <percentage> value
`<length-percentage>^l: `length$t 値 ◎ Any valid <length>＼; `percentage$t 値 ◎ or <percentage> value,＼; `length$t, `percentage$t 成分を組合せている `calc()$t 式【より一般には（~UAが~supportするなら）、`~math関数$になるであろう。】 ◎ any valid <calc()> expression combining <length> and <percentage> components.
`<string>^l: `string$t 値 ◎ Any valid <string> value
`<color>^l: `color$t 値 ◎ Any valid <color> value
`<image>^l: `image$t 値 ◎ Any valid <image> value
`<url>^l: `url$t 値 ◎ Any valid <url> value
`<integer>^l: `integer$t 値 ◎ Any valid <integer> value
`<angle>^l: `angle$t 値 ◎ Any valid <angle> value
`<time>^l: `time$t 値 ◎ Any valid <time> value
`<resolution>^l: `resolution$t 値 ◎ Any valid <resolution> value
`<transform-function>^l: `transform-function$t 値 ◎ Any valid <transform-function> value
`<custom-ident>^l: `custom-ident$t 値 ◎ Any valid <custom-ident> value
`~identから開始して$いる並びのうち，次を満たすもの ⇒ ［ `名前として消費できる＠~CSSSYN#consume-name$ ］~AND［ `custom-ident$t 生成規則に合致する］ ◎ Any sequence which starts an identifier, can be consumed as a name, and matches the <custom-ident> production: その識別子 ◎ That identifier; 注記： `custom-ident$t は、符号位置ごとに比較される。これは、［ ~UA定義な~CSS ］における通常の挙動（~ASCIIに制限され, `~ASCII大小無視$で比較される）とは異なる。なので， `Red^v の様な `ident^t を指定した場合、値 `Red^v は受容されるが， `red^v, `RED^v は合致しない。 ~CSS表記規約に合致するためには、 `ident^t は~ASCIIのみに制約した上で，小文字で記すことが推奨される。 ◎ Note: <custom-ident>s are compared codepoint-wise with each other; this is different than the normal behavior of UA-defined CSS which limits itself to ASCII and is ASCII case-insensitive. So, specifying an ident like Red means that the precise value Red is accepted; red, RED, and any other casing variants are not matched by this. It is recommended that idents be restricted to ASCII and written in lower-case, to match CSS conventions.
`<transform-list>^l: 1 個以上の妥当な `transform-function$t 値たちが成す~list。これは、 `<transform-function>+^l に等価な，`量指定済み~data型~名$であることに注意。 ◎ A list of valid <transform-function> values. Note that "<transform-list>" is a pre-multiplied data type name equivalent to "<transform-function>+"

注記：構文~文字列 `*^l は、 `全称~構文~定義$を生産する — それは`構文~成分$ではないので、 `複化子$を付与できないし，他のものと`結合子$で組合できない。 ◎ Note: A syntax string of "*" will produce the universal syntax definition, which is not a syntax component. Therefore, "*" may not be multiplied or combined with anything else.

5.2. `+^css, `#^css 複化子

`量指定済み~data型~名$を除き、 `構文~成分~名$には，直後に複化子を付与してもヨイ： ◎ Any syntax component name except pre-multiplied data type names may be immediately followed by a multiplier:

~U002B: ~space等で分離された~listを指示する。 ◎ Indicates a space-separated list.
~U0023: ~commaで分離された~listを指示する。 ◎ Indicates a comma-separated list.

`<length>+^l: ~space等で分離された 1 個以上の長さ値たちが成す~listを受容する ◎ accepts a space-separated list of length values
`<color>#^l: ~commaで分離された 1 個以上の色~値たちが成す~listを受容する ◎ accepts a comma-separated list of color values

注記：複化子は、 ~~対象の`構文~成分~名$の直後に現れなければナラナイ。 ◎ Note: The multiplier must appear immediately after the syntax component name being multiplied.

5.3. `|^css 結合子

`構文~文字列$は、 ~U007C を利用して，複数の`構文~成分~名$を供してもヨイ。そのような構文~文字列による結果は、複数の`構文~成分$を伴う`構文~定義$になる。 ◎ Syntax strings may use U+007C VERTICAL LINE (|) to provide multiple syntax component names. Such syntax strings will result in a syntax definition with multiple syntax components.

ある~CSS値を構文解析するときに，複数の`構文~成分$を伴う`構文~定義$が利用される場合、各構文~成分は，指定された順序で照合される。 ◎ When a syntax definition with multiple syntax components is used to parse a CSS value, the syntax components are matched in the order specified.

注記：すなわち，構文~文字列として `red | <color>^l が与えられた下では、［値 `red^v と照合したときは、識別子として構文解析する］ことになる一方，［値 `blue^v と照合したときは、 `color$t として構文解析する］ことになる。 ◎ Note: That is, given the syntax string "red | <color>", matching the value red against it will parse as an identifier, while matching the value blue will parse as a <color>.

`<length> | auto^l: 次に挙げる値を受容する ⇒＃長さ, `auto^v ◎ accepts a length, or auto
`foo | <color># | <integer>^l: 次に挙げる値を受容する ⇒＃ `foo^v, ~commaで分離された 1 個以上の色~値たちが成す~list, 1 個の整数 ◎ accepts foo, a comma-separated list of color values, or a single integer

5.4. 構文~文字列の構文解析

5.4.1. 定義

`~data型~名@: 次の順による`符号位置$並び ⇒＃ ~U003C, 0 個以上の`~ident符号位置$, ~U003E ◎ A sequence of code points consisting of a U+003C LESS-THAN SIGN (<), followed be zero or more ident code points, and terminated by U+003E GREATER-THAN SIGN (>).
`量指定済み~data型~名@: `~data型~名$のうち，［ `複化子$を伴う別の`構文~成分$を表現するもの］をすでに含んでいるもの。 ◎ A data type name that represents another syntax component with a multiplier already included.
`構文~成分@: 次のものからなる~obj ⇒ `構文~成分~名$, 0 〜 1 個の`複化子$ ◎ An object consisting of a syntax component name, and an optional multiplier.
`構文~成分~名@: 次のいずれかを与える`符号位置$並び ⇒＃ `~data型~名$ ／ `custom-ident$t を生産し得るもの ◎ A sequence of code points which is either a data type name, or a sequence that can produce a <custom-ident>.
`構文~定義@: 1 個以上の`構文~成分$たちが成す~listからなる~obj。 ◎ An object consisting of a list of syntax components.
`全称~構文~定義@: 妥当などの~token~streamも受容する，特別な構文~定義。【`構文~文字列$としては `*^l 。】 ◎ A special syntax definition which accepts any valid token stream.

5.4.2. 構文~定義を消費する

この節では、 `構文~定義を消費する@ 方法を述べる。それは、所与の ( `文字列$ %文字列 ) から［ `構文~成分$たちが成す~listを伴う`構文~定義$ ／ `全称~構文~定義$ ］を生産する： ◎ This section describes how to consume a syntax definition from a string string. It either produces a syntax definition with a list of syntax components, or the universal syntax definition.

%文字列から`前後の~ASCII空白~列を剥ぐ$ ◎ Strip leading and trailing ASCII whitespace from string.
~IF［ %文字列の`長さ$ ~EQ 0 ］ ⇒ ~RET `失敗^i ◎ If string’s length is 0, return failure.
~IF［ %文字列 ~EQ `*^l （ 1 個の ~U002A ）］ ⇒ ~RET `全称~構文~定義$ ◎ If string’s length is 1, and the only code point in string is U+002A ASTERISK (*), return the universal syntax definition.
%~stream ~LET %文字列を成す`符号位置$並びを前処理して作成される`入力~stream$ `css-syntax-3$r ◎ Let stream be an input stream created from the code points of string, preprocessed as specified in [css-syntax-3].＼
%定義 ~LET 新たな`~list$ ◎ Let definition be an initially empty list of syntax components.
~WHILE 無条件： ◎ ↓
1. %成分 ~LET %~stream から`構文~成分を消費する$() ◎ Consume a syntax component from stream.＼
2. ~IF［ %成分 ~EQ `失敗^i ］ ⇒ ~RET `失敗^i ◎ If failure was returned, return failure;＼
3. %定義に %成分を`付加する$ ◎ otherwise, append the returned value to definition.
4. ~WHILE［ `次回の入力~符号位置$は`空白$である］ ⇒ %~stream から 1 個の`入力~符号位置を消費する$ ◎ Consume as much whitespace as possible from stream.
5. %~stream から 1 個の`入力~符号位置を消費する$ ◎ Consume the next input code point in stream:
6. `現在の入力~符号位置$に応じて： ◎ ↑
  
  `EOF^i
  
  ~RET %定義 ◎ return definition.
  
  ~U007C
  
  ~CONTINUE ◎ Repeat step 5.
  
  他全部
  
  ~RET `失敗^i ◎ Return failure.

5.4.3. 構文~成分を消費する

`符号位置$の %~stream から `構文~成分を消費する@ ときは： ◎ To consume a syntax component from a stream of code points stream:

~WHILE［ `次回の入力~符号位置$は`空白$である］ ⇒ %~stream から 1 個の`入力~符号位置を消費する$ ◎ Consume as much whitespace as possible from stream.
%名前 ~SET 空~文字列
%複化子 ~SET ε（なし） ◎ Let component be a new syntax component with its name and multiplier initially empty.
%~stream から 1 個の`入力~符号位置を消費する$ ◎ Consume the next input code point in stream:
`現在の入力~符号位置$に応じて： ◎ ↑
~U003C
1. %結果 ~LET %~stream から`~data型~名を消費する$
2. ~IF［ %結果 ~EQ `失敗^i ］ ⇒ ~RET `失敗^i
3. %名前 ~SET %結果
◎ Consume a data type name from stream. If it returned a string, set component’s name to the returned value. Otherwise, return failure.
`~identを開始する符号位置$

~U005C
1. ~IF［ %~stream は`~identから開始して$いない］ ⇒ ~RET `失敗^i
2. %~stream から`現在の入力~符号位置を消費し直す$
3. %名前 ~SET %~stream から`~identを消費する$
4. ~IF［ %名前は `custom-ident$t として構文解析されなかった］ ⇒ ~RET `失敗^i
◎ If the stream starts with an ident sequence, reconsume the current input code point from stream then consume an ident sequence from stream, and set component’s name to the returned value. Otherwise return failure. ◎ If component’s name does not parse as a <custom-ident>, return failure.
他全部

~RET `失敗^i ◎ Return failure.
~IF［ %名前は`量指定済み~data型~名$でない］~AND［ %~stream 内の`次回の入力~符号位置$ ~IN { ~U002B, ~U0023 } ］：
1. %~stream から 1 個の`入力~符号位置を消費する$
2. %複化子 ~SET `現在の入力~符号位置$
◎ If component’s name is a pre-multiplied data type name, return component. ◎ If the next input code point in stream is U+002B PLUS SIGN (+) or U+0023 NUMBER SIGN (#), consume the next input code point from stream, and set component’s multiplier to the current input code point.
~RET 新たな`構文~成分$ — その ⇒＃名前 ~SET %名前, 複化子 ~SET %複化子 ◎ Return component.

5.4.4. ~data型~名を消費する

`符号位置$の~streamから `~data型~名を消費する@ ときは： ◎ To consume a data type name from a stream of code points:

注記：この~algoは、 `符号位置$ ~U003C がすでに~streamから消費-済みであると見做す。 ◎ Note: This algorithm assumes that a U+003C LESS-THAN SIGN (<) code point has already been consumed from the stream.

%名前 ~LET `<^l（ 1 個の ~U003C ） ◎ Let name initially be a string containing a single U+003C LESS-THAN SIGN (<) code point.
%~stream から`入力~符号位置を繰返し消費する$： ◎ Repeatedly consume the next input code point:
~U003E
1. %名前に`現在の入力~符号位置$を付加する
2. ~IF［ %名前は`~supportされる構文~成分~名$である］ ⇒ ~RET %名前
3. ~RET `失敗^i
◎ Append the code point to name. If name is a supported syntax component name, return name. Otherwise return failure.
`~ident符号位置$

%名前に`現在の入力~符号位置$を付加する ◎ Append the code point to name.

他全部

~RET `失敗^i ◎ Return failure.

6. ~CSSOM

注記：登録-済み~custom~prop用に指定された値は、算出d値の時点まで解釈されない。このことは、影響される~APIは，算出d値を検索取得するものに限られることを意味する。他の~APIは、当の`文書$の`登録-済み~prop集合$を無視して，すべての~custom~propを未登録として扱うモノトスル。 ◎ The value specified for a registered custom property is not interpreted until computed-value time. This means that only APIs that retrieve computed values are affected. Other APIs must ignore the [[registeredPropertySet]] slot of the associated Document, and treat all custom properties as unregistered.

6.1. `CSSPropertyRule^I ~interface

`CSSPropertyRule$I ~interfaceは、ある `property$at 規則を表現する。 ◎ The CSSPropertyRule interface represents an @property rule.

[`Exposed$=Window]
interface `CSSPropertyRule@I : `CSSRule$I {
  readonly attribute `CSSOMString$ `name$mD;
  readonly attribute `CSSOMString$ `syntax$mD;
  readonly attribute `boolean$ `inherits$mD;
  readonly attribute `CSSOMString$? `initialValue$mD;
};

`name@mD 取得子~手続きは ⇒ ~RET コレが表現する `property$at 規則に結付けられた~custom~prop名 ◎ name, of type CSSOMString, readonly • The custom property name associated with the @property rule.

`syntax@mD 取得子~手続きは ⇒ ~RET コレが表現する `property$at 規則に結付けられた構文 — 正確に指定されたとおりの ◎ syntax, of type CSSOMString, readonly • The syntax associated with the @property, exactly as specified.

`inherits@mD 取得子~手続きは ⇒ ~RET ~IS［コレが表現する `property$at 規則に結付けられた `inherits$d 記述子の値 ~EQ `true^v ］ ◎ inherits, of type boolean, readonly • The inherits descriptor associated with the @property rule.

`initialValue@mD 取得子~手続きは ⇒ ~RET コレが表現する `property$at 規則に `initial-value$d 記述子【！結付けられた初期~値】は［在るならばその値／無いならば ~NULL ］ ◎ initialValue, of type CSSOMString, readonly, nullable • The initial value associated with the @property rule, which may not be present.

`CSSPropertyRule^I を直列化するときは、所与の ( `CSSPropertyRule$I ~obj %規則 ) に対し：

%名前 ~LET `識別子を直列化する$( %規則の `name$mD【！name】 )
%構文 ~LET `文字列を直列化する$( %規則の `syntax$mD【！`syntax$d】 )
%継承- ~LET %規則の `inherits$mD【！`inherits$d】属性の値に応じて［ ~T ならば `true^l／ ~F ならば `false^l ］
%初期~値 ~LET %規則が表現する `property$at 規則に `initial-value$d 記述子【！ `initialValue$mD 】は［在るならばその値／無いならば ~NULL ］
%初期~値~宣言 ~LET ~NULL
~IF［ %初期~値 ~NEQ ~NULL ］ ⇒ %初期~値~宣言 ~SET 次を順に`連結する$ ⇒＃ `initial-value:^l `~CSS値を直列化する$( 規則の `initial-value$d の値 ) `003B^U `SEMICOLON^cn, `0020^U `SPACE^cn
~RET 次を順に`連結する$ ⇒＃ `@property^l, `0020^U `SPACE^cn, %名前, `0020^U `SPACE^cn, `007B^U `LEFT CURLY BRACKET^cn ( `{^l ), `0020^U `SPACE^cn, `syntax:^l, `0020^U `SPACE^cn, %構文, `003B^U `SEMICOLON^cn, `0020^U `SPACE^cn, `inherits:^l, `0020^U `SPACE^cn, %継承-, `003B^U `SEMICOLON^cn, `0020^U `SPACE^cn, %初期~値~宣言, `007D^U `RIGHT CURLY BRACKET^cn ( `}^l )

◎ To serialize a CSSPropertyRule, return the concatenation of the following: • The string "@property" followed by a single SPACE (U+0020). • The result of performing serialize an identifier on the rule’s name, followed by a single SPACE (U+0020). • The string "{ ", i.e., a single LEFT CURLY BRACKET (U+007B), followed by a SPACE (U+0020). • The string "syntax:", followed by a single SPACE (U+0020). • The result of performing serialize a string on the rule’s syntax, followed by a single SEMICOLON (U+003B), followed by a SPACE (U+0020). • The string "inherits:", followed by a single SPACE (U+0020). • For the rule’s inherits attribute, one of the following depending on the attribute’s value: •• true ••• The string "true" followed by a single SEMICOLON (U+003B), followed by a SPACE (U+0020). •• false ••• The string "false" followed by a single SEMICOLON (U+003B), followed by a SPACE (U+0020). • If the rule’s initial-value is present, follow these substeps: •• The string "initial-value:". •• The result of performing serialize a CSS value in the rule’s initial-value followed by a single SEMICOLON (U+003B), followed by a SPACE (U+0020). • A single RIGHT CURLY BRACKET (U+007D).

6.2. `CSSStyleValue$I の具象化

`登録-済み~custom~prop値を具象化する@ ときは、所与の ( ~prop %~prop, `構文~定義$ %構文 ) に対し，次の手続きを走らす： ◎ To reify a registered custom property value given a property property and syntax definition syntax, run these steps:

%~prop の指定d値 %値に対しては ⇒ ~RET `成分~値~listを具象化する$( %値 ) ◎ For specified values, reify a list of component values from the value, and return the result.
%~prop の算出d値 %値に対しては、 %値の型に応じて： ◎ For computed values:

`length$t

`integer$t

`number$t

`angle$t

`time$t

`resolution$t

`percentage$t

`length-percentage$t

~RET `数量-値を具象化する$( %値 ) ◎ If the value is a <length>, <integer>, <number>, <angle>, <time>, <resolution>, <percentage> or <length-percentage>; reify a numeric value from the value and return the result.

`transform-function$t

~RET `変形~関数を具象化する$( %値 ) ◎ If the value is a <transform-function>, reify a <transform-function> from the value and return the result.

`transform-list$t

~RET `変形~listを具象化する$( %値 ) ◎ If the value is a <transform-list>, reify a <transform-list> from the value and return the result.

`image$t

~RET `画像を具象化する$( %値 ) ◎ If the value is an <image>, reify a CSSImageValue from the value and return the result.

`識別子$

~RET `識別子を具象化する$( %値 ) ◎ If the value is an identifier, reify an identifier from the value and return the result.

`全称~構文~定義$

~RET `成分~値~listを具象化する$( %値 ) ◎ If syntax is the universal syntax definition, reify a list of component values from the value, and return the result.

その他

~RET `~CSSStyleValueとして具象化する$( %~prop, %値 ) ◎ Otherwise, reify as a CSSStyleValue with the [[associatedProperty]] internal slot set to property, and return the result.

7. 例

7.1. ~custom~propを利用して~animationの挙動を追加する例

<script>
CSS.`registerProperty$m({
  name: "--stop-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "rgba(0,0,0,0)"
});
</script>

<style>

.button {
  --stop-color: red;
  background: linear-gradient(var(--stop-color), black);
  transition: --stop-color 1s;
}

.button:hover {
  --stop-color: green;
}

</style>

7.2. `property^at を利用して~propを登録する例

<script>
  CSS.`paintWorklet$m.`addModule$m('circle.js');
</script>
<style>
  @property --radius {
    syntax: "<length>";
    inherits: false;
    initial-value: 0px;
  }

  div {
    width: 100px;
    height: 100px;
    --radius: 10px;
    background: paint(circle);
    transition: --radius 1s;
  }

  div:hover {
    --radius: 50px;
  }
</style>
<div></div>

// circle.js
`registerPaint$m('circle', class {
    static get inputProperties() { return ['--radius']; }
    paint(%ctx, %geom, %properties) {
      let %radius = %properties.get('--radius').value;
      %ctx.fillStyle = 'black';
      %ctx.beginPath();
      %ctx.arc(%geom.width / 2, %geom.height / 2, %radius, 0, 2 * Math.PI);
      %ctx.fill();
    }
});

~securityの考慮点

この仕様に与える特能により導入される，既知な~securityの課題は無い。 ◎ There are no known security issues introduced by these features.

~privacyの考慮点

この仕様に与える特能により導入される，既知な~privacyの課題は無い。 ◎ There are no known privacy issues introduced by these features.

10. 変更点

`2020年 10月 13日作業草案＠~TR/2020/WD-css-properties-values-api-1-20201013/$ から変更点（ 2024年 3月 20日まで） ◎ 10.1. Changes since the Working Draft of 13 October 2020 /* to 20 March 2024 */: `initial-value$d 用の値を~custom~propと同じく， `declaration-value^t? にした。（ `9078$issue ） ◎ Made "initial-value" have a <declaration-value>?, same as custom properties. (#9078); ~shadow~treeにおいても `property$at を許容した。（ `pull #1085＠https://github.com/w3c/css-houdini-drafts/pull/1085$ ） ◎ Allowed @Property in shadow trees. (#1085); ~prop登録の視野がなぜ~shadowに絞られず大域的になるかについて説明する節を追加した。 ◎ Added section explaining why property registration is global, rather than shadow-scoped.; 他の仕様から利用できるよう，用語 “`登録-済み~custom~prop$”, “`全称~構文~定義$” を~exportした。（ `pull #1020＠https://github.com/w3c/css-houdini-drafts/pull/1020$ ） ◎ Exported the terms "registered custom property" and "universal syntax definition", for use in other specifications. (#1020); “`無効が保証される値$” に代えて “`算出d値の時点で無効$” を利用するようにした。 ◎ Used the term "invalid at computed-value time" rather than "guaranteed-invalid value".