Improve design system anatomy JSON Schema

[lukewarlow]

Currently the anatomy that can be defined for a component in a design system is rather limited. Just an array of names with a description.

It's also displayed rather simply

It would be good to be able to represent the structure in an anatomy like we can in our anatomy proposals. It would also be good to display the anatomies in a way more akin to the concepts where the various design systems have their anatomies displayed and labelled with where the anatomy comes from.

This would make it far easier to turn these anatomies into a proposal with confidence that we cover X% of design systems.

[lukewarlow]

A syntax such as that below could be used instead allowing you to show nesting and then this could be converted to an actual HTML representation of the anatomy for display in the UI. Would have to think pseudo and legacy-pseudo would be optional and only really useful for browsers. Perhaps a more generic name could be thought of that would be shared with other design systems "slots and parts". But just an initial idea?

      "anatomy": [
        {
          "name": "slider-container",
          "legacy-pseudo": "-webkit-slider-container",
          "children": [
            {
              "name": "track",
              "pseudo": "slider-track",
              "legacy-pseudo": "-webkit-slider-runnable-track",
              "children": [
                {
                  "name": "thumb",
                  "pseudo": "slider-thumb",
                  "legacy-pseudo": "-webkit-slider-thumb"
                }
              ]
            }
          ]
        }
      ],

[css-meeting-bot]

The Open UI Community Group just discussed Improve design system anatomy JSON Schema and display.

The full IRC log of that discussion

<hdv> lukew: I was looking at input types in browsers
<hdv> lukew: and wonder if we could come up with an anatomy for inputs
<hdv> lukew: so I found the anatomies for design systems to be a bit lacking
<gregwhitworth> q+
<hdv> lukew: we don't have anatomies per design system without indication how common they are. So wanted to come up with a new JSON schema to be able to declare it better
<hdv> lukew: so that we can render anatomies and compare them more easily
<hdv> lukew: do we think that's worth it?
<masonf> q?
<hdv> lukew: so ideally it would have space for pseudos and legacy pseudos and more
<masonf> q+
<hdv> lukew: a lot of the browser components are quite detailed in terms of nesting
<hdv> lukew: I put a screenshot in the issue that shows a rough idea of what that would look like
<hdv> lukew: one thing I thought of… it relies on a single root element, which is not necessarily the case?
<keithamus> q+
<gregwhitworth> https://open-ui.org/components/slider.research.parts/
<hdv> gregwhitworth: I love the thoughts on the schema… eg in the link I just shared we lost who thing are assigned to
<hdv> gregwhitworth: for the file one we may end up with 40 anatomies… how would we deal with them, eg split them in separate pages?
<hdv> gregwhitworth: pseudos and slots are both optional in the schema but you can't mix and match
<gregwhitworth> ack gregwhitworth
<gregwhitworth> ack masonf
<hdv> gregwhitworth: I like it, let's have a separate issue for rendering them
<hdv> masonf: I like how you've added the browsers to the design system list, makes sense to me
<hdv> masonf: it'll be helpful to more easily see how things relate
<hdv> masonf: to be able to see it all in one page or see patterns seems very handy, +1 to doing all of this
<gregwhitworth> ack keithamus
<hdv> masonf: one comment: would not say you should have different names for this depending on whether it is a browser thing or not… probably not slots (because biased to web components) or pseudos (because biased to browsers), we need a common term
<gregwhitworth> q+
<hdv> keithamus: I think it's a great idea… one comment: it looks like you could use HTML/XML instead of JSON schema to represent these things. Which may make it easier to style / represent on the page, just some CSS rather than translate the format
<jarhar> https://developer.mozilla.org/en-US/docs/Web/XSLT
<masonf> +1 to representing the anatomy via HTML. That would be helpful to browser implementers, I think.
<hdv> gregwhitworth: would be hesitant to move over to XML personally… it's just a different way to do the same thing… we leverage them in different areas too not just for rendering
<gregwhitworth> https://open-ui.org/components/file.research/
<hdv> lukew: maybe this makes it harder to analyse, eg if we want to see how many elements have a shared name
<masonf> q?
<gregwhitworth> ack gregwhitworth
<gregwhitworth> Zakim, end meeting

[css-meeting-bot]

The Open UI Community Group just discussed Improve design system anatomy JSON Schema, and agreed to the following:

• RESOLVED: Improve design system schema to account for anatomies
• ACTION: luke open issue for naming of parts and slots

The full IRC log of that discussion

<hdv> luke: the current schemas have an anatomy for components… not sure if it is used much, there are a lot of components that don't use it
<hdv> luke: I feel it's not very effective
<hdv> luke: nesting and slots for pseudo els are tricky to do, for instance, so I've come up with a proposal for a new schema to make that easier
<gregwhitworth> q+
<hdv> luke: that way we don't have to manually write HTML for anatomies
<hdv> luke: currently I've gone for the approach of allowing to define a slot or pseudo els, not both
<hdv> luke: it would be good to have a more generic concept of which paths exists
<hdv> luke: so my Q: how should we handle that? can others think of aspect other than nesting to account for?
<hdv> gregwhitworth: as noted in the item for combobox, we're looking at this at Salesforce… I look forward to using the new schema
<hdv> gregwhitworth: as we graduate into WHATWG, we're not using the part schema… but it's the right definition
<hdv> gregwhitworth: I don't know if we need to come up with a new generic term, as part is already generic and can become elements in the end
<hdv> gregwhitworth: if this group can align on a name and agree on a proposed resolution that could work
<gregwhitworth> q?
<gregwhitworth> ack gregwhitworth
<masonf> q+
<gregwhitworth> ack masonf
<hdv> masonf: I do want to make sure we use one term… that could represent parts… basically to answer if you put a child in another child, where should it go?
<masonf> +1 to party-mc-partface and slotty-mc-slotface
<hdv> gregwhitworth: we could do a proposed resolution and open a separate issue for naming
<luke> Proposed Resolution: Improve design system schema to account for anatomies
<hdv> +1
<bkardell_> +1
<luke> RESOLVED: Improve design system schema to account for anatomies
<gregwhitworth> ACTION: luke open issue for naming of parts and slots

[gregwhitworth]

@lukewarlow as you were presenting this it dawned on me that we may want to actually standardize a web component schema. Then a colleague internally who works on one of our builders reached out about the potential for something along these lines and I remembered the WC manifest spec. Should we align schema with that proposal: https://github.com/webcomponents/custom-elements-manifest

[lukewarlow]

Huh that looks pretty neat. I think that's a good idea. Will be quite exhaustive that way.

Do we want to discuss that or should I just go ahead and do it? @gregwhitworth

[gregwhitworth]

@lukewarlow I don't think we need to discuss this at this moment; however I'm intrigued at your "quite exhaustive" statement as maybe we should influence that spec/proposal for changes? For now just land in the direction you were already heading and possibly do a draft that follows that proposal? @mfreed7 fyi since you requested the naming of "parts and slots" issue and if we do decide to adopt the WCCG schema then it may already be covered.

[lukewarlow]

I noticed our schemas were lacking in other places https://github.com/openui/open-ui/issues/875 that I think that above one could handle (events for example) and others that it might not handle (state pseudos see https://github.com/webcomponents/custom-elements-manifest/issues/113) that we can upstream.

In that case I have the open PR that we can land get the browser follow up one in aswell and then I can work on a draft using the linked schema.

I'm happy to iterate on this and migrate between them as time goes on so the duplicate work isn't an issue for me.

[lukewarlow]

@gregwhitworth on the topic of upstreaming improvements, I've made a PR to add custom state to the schema which we can use for both design systems proper and also for browser pseudo classes.

[github-actions[bot]]

There hasn't been any discussion on this issue for a while, so we're marking it as stale. If you choose to kick off the discussion again, we'll remove the 'stale' label.

[lukewarlow]

THe PR mentioned above got merged. So when I've got some time I'll pick this back up and see what I can come up with.