Add `part` attributes to elements in the shadow DOM about carbon-for-ibm-dotcom

[areagan1030]

@oliviaflory Some general Figma thoughts — 

• We currently have our beta component library, but it's not being actively maintained right now. Those v1 component specs that the team has been working on are a closer source of truth. IMO, our update to CIBM v2 should be when we target heavier work on the AEM component library.
• I think it may be useful in the specs we're maintaining to add notes when we're relying on a part attribute
• I don't think we'd necessarily document on a docs component page where we're applying this attribute (can include this in specs as noted above), but I am thinking that this should be included on a "how to create components" page, where we also call out some steps on governing this usage

[oliviaflory]

@andy-blum followup question: would you want to apply this to C4IBM v1 because that's what AEM is currently on? Or were you thinking this would be applied to C4IBM v2 so when AEM does adopt (possibly soon?) it will enable this greater flexibility?

[andy-blum]

Oh that's a great question. Let me find out when we plan on upgrading to v2.

[andy-blum]

Sounds like updating to v2 is slated for mid-late Q2. We'd probably want to do some of this in v1 (the cta-block, for example is a current pain point), but we could probably limit how much we add in to v1.

[andy-blum]

Here's another demo, this time modifying cds-card to reduce it to a single web component (no special eyebrow, heading, footer components) as well as allowing CSS authors to override component internal styles.

An important thing to remember if we do this is how context plays into the CSS Cascade:

(image source)

Styles encapsulated within the component that conflict with global styles are resolved at the context level. The order, specificity, and @layer of styles are all irrelevant. Styles encapsulated within the shadowRoot will lose to global styles, unless they are given the !important tag, at which point the global styles cannot win. Therefore, it is critical to not use !important tags except for cases where we are certain the styles must be present.

In my demo, I've applied !important tags to the rules around focus rings, but we could just as easily use this as a way to enforce specific styles deemed "critical" for enforcing the IDL. Personally, that's not the way I'd choose to go, but it's an option available to us.

[oliviaflory]

@andy-blum thank you for your patience: Yes, let's move forward with the part attribute!

Versions

I assume you will apply this to C4IBM v1 because AEM is currently on that version
Q: Do you plan to apply the part attribute to ALL of the components, or a select number in v1 as needs arise?

• If you plan a select number then please let us know which ones
• What is the process for determining which components receive the part attributes

Documentation:

• We would love for you to document how you are applying the part attribute to the components
  • TBD on where we will surface the docs
• We will probably want to add some sort of warning to the part docs: ie just because you can, doesn't mean you should
• Q: How to communicate this to designers

Figma & design tooling

• At this time we will not be adding the component variants AEM creates to our Figma kit. Some considerations for your teams cc: @areagan1030
  • The parts will have to be overriden or broken from our Figma kit. Breaking loses any updates
  • How will your team document what variants designers and the CSS authors create or have created
  • Do you have a figma kit of your own that AEM designers use?
  • Will you surface the variants on the AEM doc site and explain when/how to use the variants

[andy-blum]

I assume you will apply this to C4IBM v1 because AEM is currently on that version

Actually, I don't think we want to invest the time in doing this for v1 components. From what I've been told, AEM is looking at an upgrade to v2 near end of Q2. Personally, I'd like to avoid enabling AEM to stick around on an old version longer than needed. If this kind of flexibility motivates the powers that be to upgrade to v2, so be it.

---

We would love for you to document how you are applying the part attribute to the components.

• TBD on where we will surface the docs

There seems to be a way to do this already in the @storybook/addon-docs plugin. We can see "CSS Shadow Parts" in the props table on the CAEM accordion item. We recently did an overhaul of our docs for CAEM components and noticed that was there but no other parts were appearing. @jkaeser might have more insight here.

---

We will probably want to add some sort of warning to the part docs: ie just because you can, doesn't mean you should
Q: How to communicate this to designers

Agreed, though I don't have a thought yet on the right wording for this.

---

How will your team document what variants designers and the CSS authors create or have created

I'm not sure this is necessary? The modifications are all controlled by code, and content authors won't be able to make design decisions that aren't explicitly given to them by developers.

[andy-blum]

Probably worth pointing out that there are already multiple places that v1 is using shadow parts