Feature request: Add ordered shorthand expansion data to CSS properties

[lifeiscontent]

Summary

It would be very helpful if CSS shorthand properties included a shorthandFor (or similar) field that lists their constituent longhand properties in CSS specification order.

Current State

Currently, shorthand properties like margin have:

• syntax: <'margin-top'>{1,4} - shows the pattern but not the full ordered expansion
• logicalPropertyGroup: Groups related properties but in alphabetical order

For example, properties in the margin logicalPropertyGroup are listed alphabetically:

margin-block-end, margin-block-start, margin-bottom, margin-inline-end, 
margin-inline-start, margin-left, margin-right, margin-top

Proposed Enhancement

Add a shorthandFor array (or similar) that lists longhands in CSS specification order:

{
  "name": "margin",
  "syntax": "<'margin-top'>{1,4}",
  "shorthandFor": [
    "margin-top",
    "margin-right",
    "margin-bottom",
    "margin-left"
  ],
  ...
}

Other examples:

{
  "name": "border-radius",
  "shorthandFor": [
    "border-top-left-radius",
    "border-top-right-radius",
    "border-bottom-right-radius",
    "border-bottom-left-radius"
  ]
}

{
  "name": "gap",
  "shorthandFor": ["row-gap", "column-gap"]
}

{
  "name": "inset",
  "shorthandFor": ["top", "right", "bottom", "left"]
}

Use Case

CSS-in-JS libraries and CSS tooling often need to expand shorthand properties to their longhands. The expansion order matters because CSS shorthands like margin: 10px 20px 30px 40px map values positionally (top, right, bottom, left).

Currently, tools must hard-code this order since it's only defined in CSS spec prose, not in machine-readable data. Having this in webref would provide an authoritative, maintained source.

Affected Properties

Common shorthands that would benefit:

• margin, padding, inset, scroll-margin, scroll-padding
• border-width, border-style, border-color
• border-radius
• gap (row-gap, column-gap)
• overflow (overflow-x, overflow-y)
• flex, flex-flow
• grid, grid-template, grid-area, grid-row, grid-column
• animation, transition
• background, font, list-style, text-decoration, etc.

Thank you for considering this enhancement!

[tidoust]

Thanks for the well-articulated feature requests, @lifeiscontent!

@dontcallmedom and I are essentially off next couple of weeks, expect a bit of delay here ;) In general, I suspect our main concern for all of them is going to be: how do we get that data in and prevent it from becoming stall? It's relatively easy to add data that we can extract from specs on an automated basis (more often than not, it requires maintaining patches though, which already consumes time). We're more careful about introducing data that needs to be maintained on a manual basis as that requires injecting time that we do not have.

For shorthands, a good first step could be to look at the notion of logical property group which is usually set in the definition of longhand properties. It would probably not be enough to give the longhand properties in order though. And it does not seem to have been set for properties such as flex, animation, and font longhands.

I'm also wondering about practical usage in cases where the syntax of the shorthand differs from the syntax of its longhands. For example, you mentioned background as a shorthand of shorthands in #1770, what would shorthandFor contain for it? Other examples include border-radius, which isn't quite just a list of values for its four longhands, or border-block which sets both border-block-start and border-block-end to the same value.

[lifeiscontent]

Thanks for the thoughtful response, @tidoust! Totally understand about the holiday timing.

You raise excellent points about maintenance. Let me address the complex cases:

background: I'd suggest only listing the direct longhands: background-image, background-position, background-size, background-repeat, background-attachment, background-origin, background-clip, background-color. The fact that background-position is itself a shorthand for background-position-x/background-position-y would be captured by its shorthandFor entry - the nesting is self-documenting.

border-radius: You're right that it's not a simple 1:1 mapping. Perhaps a shorthandType field could distinguish:

• "positional" - margin, padding, inset (1-4 values map to specific longhands)
• "split" - border-radius (values before / → horizontal, after → vertical)
• "uniform" - border-block (single value applies to multiple longhands)

Automation: The syntax field already contains references like <'margin-top'> - could this be parsed to extract longhands programmatically? For properties where longhands appear in the syntax, that could be automated. The edge cases (border-radius, background layers) might need manual curation, but they're a small, stable set.

For my use case (CSS-in-JS tooling), even partial coverage of the common positional shorthands (margin, padding, inset, border-width, gap) would be valuable.

Happy to help with a proof-of-concept if that would be useful!

[tidoust]

Perhaps we shouldn't worry about shorthandType for the time being. At least, I would start with shorthandFor, which seems useful on its own. On top of usage in CSS-in-JS tooling, that information could perhaps be used by MDN as well: MDN pages typically list longhands in a Constituent properties section, maintained on a manual basis until now.

If you can provide a proof-of-concept, that would be fantastic! Do not worry too much about integrating with the rest of the curation logic, I'm happy to help with that afterwards.

I think that what we'd be looking for is:

• If possible, logic that can fill longhands automatically for a chunk of these properties. If that logic needs to run when the specs are crawled, that's fine, the code would just need to be added to Reffy.
• A set of manual patches.
• For manual patches, ways to detect when we should be looking at the patches again. For example, if the syntax of the shorthand changes, that probably signals we should re-validate the list of longhands. Same thing if another property appears with a logicalPropertyFor field set to a shorthand propery, while the shorthand property does not have that new property as longhand.

Another thought that came to mind is that we'll need to look at all, which is a shorthand for all properties (except a couple of them).

[tidoust]

Another thought: most shorthands have "See individual properties" values for a number of their fields in the data, notably the initial field (although that is something we may actually want to address at some point as that field should only contain valid syntaxes, see #707). That could be leveraged to provide an initial list of shorthands that need to be addressed.

Also, in most specs, the definition table for these shorthands seems to be followed by a paragraph that lists the longhands that the shorthand "sets". That paragraph does not always say that the property is a shorthand, but "sets" seems to be used somewhat thoroughly. It may be worth exploring whether the crawler could leverage that information. That won't be perfect. For example, it seems hard to automatically associate the right longhand properties to inset-block and inset-line with that approach given that the prose combines both properties in a single sentence.

[cdoublev]

You might be interested by w3c/csswg-drafts#6894 for context with a solution to define this in the specs.

Note that all is a shorthand for (almost) all longhands, and the canonical order is rather unspecified (see w3c/csswg-drafts#7984).

[tidoust]

@caugner, I'm wondering whether you could shed some light on MDN's approach to documenting shorthand properties, or perhaps redirect me to someone else who might...

For background (and to avoid having to read the above), the idea here, which #1821 would implement, is to add the list of longhands that a CSS property is shorthand for in the consolidated css.json file. MDN documents the list of longhands for a given shorthand property in a "Constituent properties" section. For example, see the border MDN page

Now, that does not seem to be done consistently. Some examples of shorthand properties that do not have a "Constituent properties" section:

• background-position - not a shorthand for MDN.
• border-block-color - not a shorthand for MDN
• line-clamp - not a shorthand for MDN.
• marker - not a shorthand for MDN although the page does allude to it being a shorthand when it describes its initial value.

Is it intended or is it a consequence of this section being manually maintained? In other words, does MDN further distinguish or want to distinguish between different types of shorthands?

Also, I see properties that are identified as shorthands, but that are not in the list of shorthand properties. For example caret or interest-delay. Or is it because they are still experimental?

A corollary question is whether there might be appetite in MDN to auto-generate the "Constituent properties" section and/or the list of shorthand properties automatically out of Webref data.