In reply to Withheld.

I feel your pain. The file format selected (json) lack of support for comments was a massive mistake. Furthermore, being able to reuse pieces of json (read: boilerplate and/or snippets) isn’t possible either. The theme.json on the frontend is static and without comments begging for confusion.

That said, you can filter the theme.json serverside (with PHP). For all intents and purposes you can replace the frontend json w/ backend PHP – which allows comments and other library-like reusability.