`@csstools/css-syntax-patches-for-csstree` experience report

[romainmenke]

After @dontcallmedom reached out to the CSSWG I thought it might good to detail how I've been using @webref/css.

I've also been working on a data set that combines csstree with @webref/css.

csstree is based on mdn/data but also contains some patches for errors and omissions. Some of these might have long since been fixed in mdn/data, but csstree doesn't update very often.

I've been mostly focussed on property value syntaxes and less so on atrules and selectors.

The end result is a list of definitions that can be given back to csstree so that syntax validation uses both the original csstree definitions and every new and updated definition from @webref/css.

This is used in Stylelint to give feedback to authors on invalid property values.

It is also used in https://www.npmjs.com/package/cssstyle but unsure exactly to what end.

---

When starting this I was also concerned with the amount of attention this would require and it does take up considerable time each week 😅.

The scripts scrape data from both @webref/css and csstree and every definition that differs is added to a json file.

Additions aren't checked manually but modifications are.
For example:

{
	"absolute-size": {
		"type": "modified",
		"comment": "",
		"syntax-b": "xx-small | x-small | small | medium | large | x-large | xx-large | xxx-large",
		"syntax-a": "xx-small | x-small | small | medium | large | x-large | xx-large",
		"syntax-m": "xx-small | x-small | small | medium | large | x-large | xx-large | xxx-large",
		"tests": {
			"passing": [
				{
					"property": "font-family",
					"value": "xxx-large"
				}
			],
			"failing": []
		}
	}
}

• syntax-b -> csstree
• syntax-a -> @webref/css
• syntax-m -> merged

This json also has some fields to add tests that are expected to either pass or fail.

---

The resulting dataset is loaded back into csstree to make sure that it loads and that there aren't any broken or missing definitions.

A final step is to check the definition of some CSS frameworks and libraries.

---

My workflow when updating the data:

• update @webref/css and csstree
• re-generate the diff between both
• use git diff to check what has changed in files like webref-over-csstree-types.json
• optionally:
  • check the spec prose for changed entries
  • add some tests to verify the syntax

When csstree is more behind the list of entries grows, when it catches up, the list shrinks.

---

Current challenges are:

• the definitions in specs are sometimes incorrect or incomplete
• some details can only be expressed in prose (e.g. which keywords are valid in calc, rgb(from red 0 0 calc(b + 1)) where b is only described in prose)

---

@webref/css really has been awesome to integrate and use.
It makes it much more viable to do syntax validation in IDE's and keep doing this over time.
Thank you for working on this 🙇

I can't allocate much time after the day job, my open source work and CCSWG participation, ... but this is something I am very interested in :)

can be closed after reading