Refine CSS Value Processing document #40546

sakupi01 · 2025-07-27T10:58:07Z

Description

The change mainly aims for better accuracy to describe CSS value processing flow according to the specification.

Motivation

The previous version sometimes used incorrect terminology and descriptions, which will ultimately lead differences between mdn and the specs.

e.g.

CSS property value result will not come only from specificity - it will be the result of the entire cascade process
"specified values" were mostly used incorrectly/confused with "declared values" - "specified values" result from the defaulting process after cascading, but the previous version didn't make this clear
The document mainly described the stages after the Defaulting process, even though the terminology and phases before Defaulting
(which are Filtering, Cascading, and related terms) are necessary to make after-Defaulting values understandable. Omitting the before-Defaulting process essentially leads to misworded descriptions.
Initial value shouldn't be listed as a value processing stage according to the spec - it is the terminology used in the specified value resolution process

The change also includes some typo/wording updates, which will make the description more accurate or simpler.

Additional details

The changes ensure compliance with:

Related issues and pull requests

Signed-off-by: saku <[email protected]>

Josh-Cena

Drive-by, just looking at Markdown correctness. Not interested in reviewing, although this looks like good work; thank you!

files/en-us/web/css/css_cascade/value_processing/index.md

sakupi01 · 2025-07-27T11:52:00Z

@Josh-Cena

Thanks for the quick review! Fixed in:

correct anchor links
use non-code/redirect ref
update non-inherited/inherited property code description

sakupi01 · 2025-07-27T11:53:57Z

files/en-us/web/css/css_cascade/value_processing/index.md

+Every CSS property's value comes from the declaration that wins the [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) algorithm. When multiple declarations provide different property values for the same element, the declaration that ranks highest in the [cascade sorting order](/en-US/docs/Web/CSS/CSS_cascade/Cascade#cascading_order) gets applied.

-Each property value comes from a single property-value pair; is single value is applied from each property. Even if the value is a comma separated list of values, that list of values came from a single declaration.
+Each property value comes from a single property name-value pair; a single value is applied from each property. Even if the value is a comma separated list of values, that list of values came from a single declaration.


property = name + value

see: https://www.w3.org/TR/css-syntax-3/#declaration

files/en-us/web/css/css_cascade/value_processing/index.md

sakupi01 · 2025-07-27T11:59:47Z

files/en-us/web/css/css_cascade/value_processing/index.md

 ## Property values

-Every CSS property's value comes from the declaration with the greatest {{cssxref("specificity")}}. If two or more declarations with the same specificity provide different property values for the same element, the declaration value whose selector has the greatest algorithmic weight gets applied.
+Every CSS property's value comes from the declaration that wins the [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) algorithm. When multiple declarations provide different property values for the same element, the declaration that ranks highest in the [cascade sorting order](/en-US/docs/Web/CSS/CSS_cascade/Cascade#cascading_order) gets applied.


It could be read like property value comes because of only from the resolution of the specificity algorithm, but it's actually not.

files/en-us/web/css/css_cascade/value_processing/index.md

sakupi01 · 2025-07-27T12:10:15Z

files/en-us/web/css/css_cascade/value_processing/index.md

+- [Declared value](#declared_value)
+- [Cascaded value](#cascaded_value)
 - [Specified value](#specified_value)
 - [Computed value](#computed_value)
 - [Used value](#used_value)


The terminology "Initial value" is used IN the resolution phase of specified value, that is Defaulting phase - it's not the term to describe the part of value processing flow.

https://www.w3.org/TR/css-cascade-4/#value-stages
https://www.w3.org/TR/css-cascade-4/#defaulting

github-actions · 2025-07-29T16:17:03Z

Preview URLs

Flaws (5)

URL: /en-US/docs/Web/CSS/CSS_cascade/Value_processing
Title: CSS property value processing
Flaw count: 3

macros:
- Macro produces link /en-US/docs/Web/CSS/specificity which is a redirect
- Macro produces link /en-US/docs/Web/CSS/specificity which is a redirect
- Macro produces link /en-US/docs/Learn_web_development/Core/Styling_basics/Cool-looking_box which is a redirect

URL: /en-US/docs/Web/CSS/CSS_syntax/Error_handling
Title: CSS error handling
Flaw count: 2

macros:
- Macro produces link /en-US/docs/Web/CSS/at-rule which is a redirect
- Macro produces link /en-US/docs/Learn_web_development/Core/Styling_basics/Cool-looking_box which is a redirect

External URLs (1)

URL: /en-US/docs/Web/CSS/CSS_cascade/Value_processing
Title: CSS property value processing

https://drafts.csswg.org/cssom/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-08-28 12:20:15)

sakupi01 · 2025-08-04T13:08:33Z

@estelle

I would love a review from you, if that's possible!

estelle

This PR is excellent. I only got through the first bit, so have more to review, but I am heading out in 20 minutes for the week so I wanted to commit what I have instead of leaving you waiting.

I realize from the number of comments in just the first portion of this it seems like i may be being critical. I am just trying to ensure that the level is such that people with less knowledge than us aren't confused. So please don't take the number of edits as a reflection of the work you did. It's excellent. I am just making suggestions that I hope will answer the readers questions before they ask them.

files/en-us/web/css/css_cascade/value_processing/index.md

Co-authored-by: Estelle Weyl <[email protected]>

This reverts commit 49ed161.

sakupi01 · 2025-08-12T16:34:03Z

Thank you so much for taking the time to review this, @estelle!

I really appreciate your thoughtful feedback, especially knowing how busy you are.
I've addressed the points you raised and commented respectively.
Looking forward to your thoughts on the rest when you get a chance.

Enjoy your time off!

estelle

a few more suggestions and questions

files/en-us/web/css/css_cascade/value_processing/index.md

Co-authored-by: Estelle Weyl <[email protected]>

sakupi01 · 2025-08-27T13:05:12Z

Thank you very much for spending time, @estelle !

I made changes of:
grammar or english,
defaulting description with accuracy,
and CSS value processing index with 'Actual value'.

I hope they make sense!

estelle

Thank you!

estelle

Thank you!
Yay. That was quite the first content PR. Welcome to the team!

renew css value processing document

00b8842

Signed-off-by: saku <[email protected]>

sakupi01 requested a review from a team as a code owner July 27, 2025 10:58

sakupi01 requested review from estelle and removed request for a team July 27, 2025 10:58

github-actions bot added Content:CSS Cascading Style Sheets docs size/m [PR only] 51-500 LoC changed labels Jul 27, 2025

Josh-Cena reviewed Jul 27, 2025

View reviewed changes

files/en-us/web/css/css_cascade/value_processing/index.md Outdated Show resolved Hide resolved

files/en-us/web/css/css_cascade/value_processing/index.md Outdated Show resolved Hide resolved

files/en-us/web/css/css_cascade/value_processing/index.md Outdated Show resolved Hide resolved

sakupi01 added 3 commits July 27, 2025 20:39

correct anchor links

7a730ad

use non-code/redirect ref

e16c142

update non-inherited/inherited property code description

0a5567b

sakupi01 commented Jul 27, 2025

View reviewed changes

files/en-us/web/css/css_cascade/value_processing/index.md Show resolved Hide resolved

sakupi01 commented Jul 27, 2025

View reviewed changes

files/en-us/web/css/css_cascade/value_processing/index.md Show resolved Hide resolved

sakupi01 commented Jul 27, 2025

View reviewed changes

sakupi01 changed the title ~~renew css value processing document~~ Refine CSS Value Processing document Jul 27, 2025

estelle reviewed Aug 7, 2025

View reviewed changes

sakupi01 and others added 10 commits August 13, 2025 00:07

Apply suggestion from @estelle

da297a2

Co-authored-by: Estelle Weyl <[email protected]>

Apply suggestion from @estelle

a7ff563

Co-authored-by: Estelle Weyl <[email protected]>

Apply suggestion from @estelle

a2bc22b

Co-authored-by: Estelle Weyl <[email protected]>

Apply suggestion from @estelle

ddb85e1

Co-authored-by: Estelle Weyl <[email protected]>

links for layers and origins

57d9f35

modify&split the first paragraph

118b89e

make all code comments removed and replaced with prose explanations

10974c4

lowercased the link texts

c24c91f

remove spaces

21f4c15

merge bullet items and add link to error handling

49ed161

oihdsf added 3 commits August 13, 2025 01:05

filtering: include suggestion

8b7cd2a

Revert "merge bullet items and add link to error handling"

4bfb703

This reverts commit 49ed161.

merge bullet items and add link to error handling

6515be7

sakupi01 requested a review from estelle August 12, 2025 16:34

estelle reviewed Aug 18, 2025

View reviewed changes

sakupi01 and others added 5 commits August 27, 2025 20:28

Update files/en-us/web/css/css_cascade/value_processing/index.md

6467d7d

Co-authored-by: Estelle Weyl <[email protected]>

Update files/en-us/web/css/css_cascade/value_processing/index.md

1206ee9

Co-authored-by: Estelle Weyl <[email protected]>

all grammatical changes

9702e1e

fixed defaulting description with accuracy

864427f

Add 'Actual value' to CSS value processing index

af0de08

sakupi01 requested a review from estelle August 27, 2025 13:06

estelle approved these changes Aug 28, 2025

View reviewed changes

Merge branch 'main' into fix/value-processing

e94c0b9

estelle merged commit 07cb371 into mdn:main Aug 28, 2025
8 checks passed

sakupi01 mentioned this pull request Aug 28, 2025

Synchronize with latest updates to MDN CSS Value Processing document mdn/translated-content#28631

Open

Refine CSS Value Processing document #40546

Refine CSS Value Processing document #40546

Uh oh!

Conversation

sakupi01 commented Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

Josh-Cena left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sakupi01 commented Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sakupi01 Jul 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sakupi01 Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sakupi01 Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sakupi01 commented Aug 4, 2025

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sakupi01 commented Aug 12, 2025

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sakupi01 commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

sakupi01 commented Jul 27, 2025 •

edited

Loading

sakupi01 commented Jul 27, 2025 •

edited

Loading

sakupi01 Jul 27, 2025 •

edited

Loading

sakupi01 Jul 27, 2025 •

edited

Loading

github-actions bot commented Jul 29, 2025 •

edited

Loading

sakupi01 commented Aug 27, 2025 •

edited

Loading