What to do with "demo"?

Demo is an interesting bit of the schema. Right now it’s only referenced from CustomElement#demos, but really, anything could have an associated demo, including or especially the package as a whole.

We could add a demos field to all declarations, modules and package. We could also add an extensible metadata field to just about everything and make DemoMetadata well-known object that can appear there.

[Westbrook]

For “storybook”, I’d say it would be better to lean into the CSF format: https://storybook.js.org/docs/react/api/csf and speak in that language directly. In this way, if Storybook decided to move away from it at some point, we’d not be in as large a bind as CSF is structured for cross tool usage and means alternative “formats” would likely have new names, even if used by Storybook.

If we went this way, it would be cool if there was a types reference format that we could point to the actual story in a separate story file. Maybe?

/*
 * @demo {csf} {import('./my-el.stories.js').Default}
 * @demo {csf} {import('./my-el.stories.js').styles}
 * @demo {csf} {import('./my-el.stories.js').complex}
 */
class MyEl extends HTMLElement {} 

I could also see a nice plugin supporting the automatic association of these across files, etc.

[thepassle]

My opinion is to have demo be an optional URL or URL array, maybe maybe with title attr

But this again assumes the demo is something that has an url