Add `part` attributes to elements in the shadow DOM

andy-blum commented 3 months ago

The problem

From time to time there is a need to navigate around styles encapsulated within components. For example:

Components that attempt to enforce spacing between their adjacent elements

The dds-cta-block component adds padding to :host as well as to .bx--content-layout. This ensures a certain amount of space between this component and another component added later. The problem, however, is that this spacing is prescriptive, and cannot possibly take into account every possible implementation of this component with every other component or with custom markup. While the padding on :host can be overridden, the padding of .bx--content-layout cannot.

Components that have an ever growing list of variations

Example: cards, links/buttons, tiles

Some of our components are highly atomic. That is, they are rarely used in isolation and frequently present differently in different contexts. An example of this is the caem-tile component that we have in Carbon For AEM.

caem-tile-group on ibm.com homepage

50-50-container on ibm.com/consulting

THINK Spotlight (proposed)

The caem-tile component was originally built as a deliberate deviation from dds-card, and was designed for the use on the homepage exhibited above. New designs came forward that were very close to the original specs, but expanded the components internal spacing for the use in the consulting leadspace. At this time, we created a "double-tile" variant as a quick solution. Now, there is another proposed deviation from the orginal design for a more compact spacing in the proposed THINK spotlight designs.

The solution

To avoid continually adding new variations to account for different sizing and spacing needs, we've opened up the shadowroots of CAEM components to styling from the AEM CSS Authors. This allows adopters to assume the responsibility of using components in a way that complies with the IDL and carbon specifications while using them in ways that original designs may not have accounted for. To see this in action, see this codepen demo

Instead of prescribing a limited set of variations and needing to handle new requests for new contexts, now AEM can maintain its own CSS that modifies the presentation of the components we've built. Instead of maintaining a "double-tile", authors can target caem-tile elements with a class or a parent selector and increase the spacing to satisfy their needs.

caem-tile.big {
  &::part(wrapper) {
    padding: 2rem;
    gap: 2rem;
  }

  &::part(label) {
    font-size: 1rem;
  }

  &::part(text) {
    font-size: 1.33rem;
    margin-block-end: 0.5rem;
  }
}

Likewise, instead of building a new "compact" variant for THINK, we can simply maintain the base version of a tile and the adopters can modifiy the spacing to satisfy their needs.

caem-tile.small {
  &::part(wrapper) {
    padding: 0.5rem;
    gap: 0.5rem;
  }

  &::part(outer):before {
    display: none;
  }

  &::part(text) {
    margin-block-end: 0.5rem;
  }
}

One downside of this approach is that the carefully-crafted carbon-compliant styles we've started with can be completely overridden to create new non-compliant interfaces

caem-tile.cyan {
  &::part(wrapper) {
    background: #e5f6ff;
  }

  &:hover::part(wrapper) {
    background: #bae6ff;
  }
}

oliviaflory commented 3 months ago

@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 commented 3 months ago

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

andy-blum commented 3 months ago

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 commented 3 months ago

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 commented 2 months ago

@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

areagan1030 commented 2 months ago

@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

andy-blum commented 2 months ago

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 commented 2 months ago

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

carbon-design-system / carbon-for-ibm-dotcom