CSS syntax: replace heading Global values with Inheritance values

[leon-win]

Currently, the subheading Global values is used to describe all CSS properties in the syntax section. For example: https://developer.mozilla.org/en-US/docs/Web/CSS/accent-color

/* Global values */
accent-color: inherit;
accent-color: initial;
accent-color: revert;
accent-color: revert-layer;
accent-color: unset;

Users are probably already accustomed to this designation, but in my opinion it is not entirely correct. “Global” is a word that can be interpreted very broadly, that is, it is not very specific and clear in a given context. Because this section lists the values that are responsible for inheritance:
https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#controlling_inheritance
https://developer.mozilla.org/en-US/docs/Web/CSS/Inheritance
I think that it would be more correct to use another wording instead of Global values, for example:

• Inheritance values
• Controlling inheritance

How do you think?

Update

As a more general solution instead of current notation (using as example https://developer.mozilla.org/en-US/docs/Web/CSS/direction):

we can consider solutions of this kind:

1. 
2. 
3. 

But of course, it’s easier at the first step to rename the /* Global values */ section into something more accurately reflecting the essence of the properties being described.

[teoli2003]

The official name is CSS-wide property values (https://www.w3.org/TR/css-values/#common-keywords ), and they are used for Explicit defaulting (https://www.w3.org/TR/css-cascade/#defaulting-keywords ).

And the all property called them the CSS-wide property values too (It only accepts the CSS-wide keywords

So, if we rename them, maybe we should call them CSS-wide property values (there is no guarantee that none will be created for purposes other than inheritance in the future).

That said, I'm not convinced we need to rename these sections.

[leon-win]

Helpful note and links, @teoli2003 !

The fact is that at the moment the Global values section (at least in most cases) provides examples of inheritance values. That is, it so happened historically that in fact this section describes exactly Controlling inheritance.

But if we look at it more broadly, it might be logical to use more than one section for this (for example, CSS-wide property values and Default values), but but I think it's too radical change.

I want to draw attention to the fact that the term Global values is not official and is not described anywhere (if I'm not mistaken). And if at the moment in this section we are always talking about values like:

content: inherit;
content: initial;
content: revert;
content: revert-layer;
content: unset;

then maybe we can bring the section title in line with the content underneath it?

[leon-win]

There are different types of grouping: according to the essence of values, according to their applicability, etc. What is now in the Global values section are values that describe the possibility of inheritance. Moreover, some of them are CSS-wide property values, but in this context this is not a key aspect.

[leon-win]

@teoli2003, is there an example where we use a all property in a section Gloabls values? Or example where we use something other than inheritance values in this section?

[leon-win]

I manually checked all the places where the /* Global values */ section appears and only the following values are described:

• inherit
• initial
• revert
• revert-layer
• unset

That is, in this section we always describe the properties of inheritance. And also there is no description of the term "Global values". Therefore, I believe that renaming to "Inheritance values" (https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#controlling_inheritance) is logical and justified.

[dipikabh]

Hello @leon-win, thank you for initiating this discussion. I think it is a fair point.

For the sake of comparison, in HTML we have the concept of 'Global attributes' that apply to all HTML elements and they're also referenced by that term in the HTML specification. On HTML element pages, we refer to these attributes using this first sentence in the "Attributes" section: "This element's attributes include the global attributes" (see example).

In CSS, like @teoli2003 mentioned, the inheritance values we're discussing are referred to as "CSS-wide keywords", and not "Global", as we currently list them in "Syntax". The "Global values" terminology diverges from the spec - so I agree with you on the use of "Global".

Perhaps we can consider aligning the CSS documentation with the HTML documentation in this regard, somewhat similar to your proposal in point 1, that is:

• Remove the "Global values" part from "Syntax"
• Add this as the first sentence in the "Values" sub-section: "Valid values also include the CSS-wide keywords for inheritance".
  • This approach would be consistent with how we do this on HTML element pages.
  • Currently, we only have a page in the Learn area that defines and groups these keyword values in one place. So that's the link we'll have to use for now.

I am also strongly in favor of linking to a single source of truth instead of maintaining the list of keyword values on every single property page or having to add the list to every new property page we create. This ensures that if there is ever a change or addition to the list of keywords (like when I had to add revert-layer to all property pages when the keyword was introduced), we can keep our maintenance burden to a minimum. The above exercise would help with this.

Pinging @estelle to see what she thinks.

Thank you again for your valuable input.

[teoli2003]

We are trying to solve an inexistent problem here.

I have no strong feelings about changing Global values to CSS-wide keywords, though I failed to see how using the spec more complex prose will help developers. In 10 years of using this terminology, this is the first time someone has complained about it, not because it is not understood, but to match the spec. Do we know if CSS-wide keywords will be better understood by new developers?

Moving them out of the syntax box will do a disservice to developers: most have heard about these keywords, and listing them (directly visible) is a quick reminder that you can use them (and their names). To bury them on another page defeats why we added them there in the first place (granted, there were only 3 of them back then).

The argument that it will be less complicated to maintain is:

1. Irrelevant: we make decisions for the good of developers and not to ease authors' lives.
2. Incorrect as they are easy to maintain. A simple multiple-file find-and-replace is quickly done and would fix all occurrences, which is pretty rare (once every five years or less). Any modern code editor has such a feature, and it doesn't take more than 10 minutes to fix all syntax entries, including creating the PR. Changing all the titles, btw, will require the same operation.

[dipikabh]

• Could we change "Global values" to "Inheritance keyword values" to better convey what they are?
• Aside from the point raised in this discussion and whether or not we change "Global values", I think we should definitely add a link on each property page to where these keyword values are defined.
  So adding this sentence to the "Values" section might be useful:
  "Valid values also include the CSS-wide keywords for controlling inheritance". (or just "keywords" instead of "CSS-wide keywords")

[estelle]

As we use "keywords" for keyword values, we can't simply use "Keywords" instead of "CSS-wide keywords" - as we need to differentiate between keyword values like "true, false, auto, left," etc, and css-wide keyword values including "inherit, initial, unset" etc.

I do not support using the word "inheritance", or any version of the global CSS keyword value inherit, within our title unless the spec does. And it doesn't. Inherit is a keyword; notably one that needs to be explained because, unlike global, it is not globally understood. So much so, that it's not even used in the revert-layer definition.

We currently use "global". Global is globally understood. More notably, the keywords are, in fact, global. Every CSS property accepts them.

Global is not an overloaded term. Inheritance is not, yet, either. Let's not cause it to be.

We have three options: 1) continue using "global values", 2) change to "global CSS property values", or 3) change to "CSS-wide keyword values".(https://drafts.csswg.org/css-values-4/#css-wide-keywords)

doing nothing is the easiest solution and an acceptable solution, as there is no problem here that needs to be solved.

[dipikabh]

Thanks @teoli2003 and @estelle for sharing your thoughts! We’re sticking with Global values.

@leon-win, we hope this decision, through all the viewpoints shared here, addresses your concern.
I'm going to close this one for now. But don't hesitate to start a new thread if you think we missed anything.

[leon-win]

Thanks for trying to help, @dipikabh!