Conversation
This is a re-write of the `@webref/css` package README to document the JSON structure more thoroughly. All keys are now described with references to a definition in CSS specs when possible, considerations about their meaning and what to expect from key values, along with examples. The README also includes example logic to gather information about specs from their URLs using browser-specs, as discussed in: #1519 (comment) There are a couple of cases where it may be valuable to clean up the data (that would introduce breaking changes though): - The `extended` key is always set, but then it's only meaningful for properties. It might become useful for other types of CSS features in the future, but could be dropped in the meantime not to create false expectations. - Descriptors have a `for` key that targets their parent at-rule. That sort of goes without saying. I haven't documented the key, especially since the `for` key is an array in all other cases. There may also be a couple of cases where we could strengthen guarantees without necessarily creating more work for us, e.g., to clean up `initial` and `animationType` values. To be addressed separately! Via #1874.
dontcallmedom
approved these changes
Mar 24, 2026
Member
dontcallmedom
left a comment
dontcallmedom
left a comment
There was a problem hiding this comment.
Great addition, thanks! LGTM with a few nits/suggestions
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is a re-write of the
@webref/csspackage README to document the JSON structure more thoroughly. All keys are now described with references to a definition in CSS specs when possible, considerations about their meaning and what to expect from key values, along with examples.The README also includes example logic to gather information about specs from their URLs using browser-specs, as discussed in:
#1519 (comment)
There are a couple of cases where it may be valuable to clean up the data (that would introduce breaking changes though):
extendedkey is always set, but then it's only meaningful for properties. It might become useful for other types of CSS features in the future, but could be dropped in the meantime not to create false expectations.forkey that targets their parent at-rule. That sort of goes without saying. I haven't documented the key, especially since theforkey is an array in all other cases.There may also be a couple of cases where we could strengthen guarantees without necessarily creating more work for us, e.g., to clean up
initialandanimationTypevalues. To be addressed separately!Via #1874.