`linear-gradient()` Formal syntax is outdated

[gibson042]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient

What specific section or headline is this issue about?

Formal syntax

What information was incorrect, unhelpful, or incomplete?

The content appears to correspond with CSS Images Module Level 3 rather than the current CSS Images Module Level 4, and in particular is missing the <color-interpolation-method> = in [ <rectangular-color-space> | <polar-color-space> <hue-interpolation-method>? ] and <linear-color-stop> = <color> <color-stop-length>? and <color-stop-length> = <length-percentage>{1,2} productions that support color space interpolation and two-position color stops (which are used elsewhere on the page).

What did you expect to see?

Syntax defined in CSS Images Module Level 4, e.g.

<linear-gradient-syntax> =
  [ [ <angle> | to <side-or-corner> ] || <color-interpolation-method> ]? ,
  <color-stop-list>

<side-or-corner> = [left | right] || [top | bottom]

<color-interpolation-method> =
  in [ <rectangular-color-space> | <polar-color-space> <hue-interpolation-method>? ]

<color-stop-list> =
  <linear-color-stop> , [ <linear-color-hint>? , <linear-color-stop> ]#

<rectangular-color-space> =
  srgb | srgb-linear | display-p3 | a98-rgb | prophoto-rgb | rec2020 | lab |
  oklab | xyz | xyz-d50 | xyz-d65

<polar-color-space> = hsl | hwb | lch | oklch

<hue-interpolation-method> = [ shorter | longer | increasing | decreasing ] hue

<linear-color-stop> = <color> <color-stop-length>?

<linear-color-hint> = <length-percentage>

<color-stop-length> = <length-percentage>{1,2}

<length-percentage> = <length> | <percentage>

Do you have any supporting links, references, or citations?

As provided above:

• https://drafts.csswg.org/css-images-4/
• https://drafts.csswg.org/css-images-4/#linear-gradients
• https://drafts.csswg.org/css-images-4/#typedef-color-stop-list
• https://www.w3.org/TR/css-color-4/#color-interpolation-method

Do you have anything more you want to share?

Related issues:

• Mentioning a difference between the specification and current implementations of linear-gradient() content#23718
• css.types.image - Level-less spec link results in incorrect formal syntax on the linear-gradient() page browser-compat-data#18674

[Josh-Cena]

Hi! Our format syntax is pulled from webref, and it seems they haven't updated yet: https://github.com/w3c/webref/blob/32a07580b0927359ef6ed62f72999e9e5fb86304/ed/css/css-images.json#L187 once they have the new syntax, MDN will update automatically.

[gibson042]

That css-images.json file is for CSS Images Module Level 3, as indicated on line 3. Its level 4 sibling file is already correct: https://github.com/w3c/webref/blob/32a07580b0927359ef6ed62f72999e9e5fb86304/ed/css/css-images-4.json#L172-L177

Cf. mdn/content#23718 (comment)

Based on the issue raised at CSSWG, this issue is caused by the spec link pointing to editor's draft of CSS Images Module without a specific level, which effectively points to the content of Level 3, but the double-position syntax is actually defined in Level 4.

[Josh-Cena]

I see. Thanks for the additional context. If mdn/browser-compat-data#18699 already fixed the spec link, I'm unsure why the syntax is still from level 3.

[wbamberg]

I believe this is about the algorithm that decides which spec we use for the formal syntax, and is really a part of https://github.com/orgs/mdn/discussions/442.

[Josh-Cena]

Is there anything actionable in content? I'm unsure what to change.

[wbamberg]

Is there anything actionable in content?

No. We could transfer this to Yari I suppose. but a real systematic fix crosses both Yari and content and potentially BCD as well.

[estelle]

@bsmth @pransh15 can we move this issue to Yari?