Hacker News Reader

Comment by itsuka | Hacker News Reader

I wish they'd update their docs with better examples before creating content in other areas, such as tutorials and blogs.

As an example, when comparing these two pages:

- Blog: https://developer.mozilla.org/en-US/blog/css-color-module-le...

- Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/color

It is apparent that the reference page lacks any mention of features from level 4 such as oklch, display-p3, and color function. Also, a search for "display-p3" in the search bar returns no result on that page.

View on HN

You’re looking at the reference page for the ‘color’ property, but that’s the wrong thing: all this stuff belongs on the page for the <color> data type; and that’s where it’s found: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value. Frankly, I’d prefer the color property page (and background-color, and border-color, and …) to deliberately not have so many diverse examples, and link much more prominently to the <color> page.

You're right. I am not as familiar with MDN's organization and CSS as you are (I only recently discovered that CSS is a typed language). However, I find it confusing that some pages have their own page for values, while others don't. As a reference page, I expect the valid syntax for all values to be provided. But I agree that specific examples can be linked to other resources.

Things like colours and units get used in many properties (color, background-color, border-color, box-shadow—in which <color> is only a part of the syntax—and many more; width, length, font-size, font—a shorthand in which <length> is only a part—and many more), and if they get expanded in one place, then all properties that use them take the new definition—hence <color>, <length>, &c. as the only sensible way to structure things (in spec, reference and mental model). By contrast, the values of properties like ‘display’ aren’t used anywhere else.

It sounds like a large part of the problem is helping to build the right mental model. If you understand that colours and lengths are used in many places, it will make sense that they will be documented separately from the properties, and that the properties’ references will just refer to them.

Thank you for taking the time to explain things so clearly to me. Considering the reuse, having values in a separate page makes sense now.

Reply on news.ycombinator.com