add semantic adaptation guide and demo for usage-aware-component-variations

[castastrophe]

Summary

• Refactored guide.md to focus on Semantic Component Adaptation, a more appropriate use case for style queries than size-based layout density.
• Updated demo.html to demonstrate a CTA Card adapting its visual logic (button style, badge visibility) based on a inherited --priority flag.
• Ensured the implementation uses logical properties (inset-block-start, min-block-size) and provides robust fallback strategies.
• Verified that this use case is distinct from the density-focused design-token-reactivity.

Test plan

• Manually reviewed the demo.html to ensure style queries correctly trigger variations on a Chromium-based browser (Limited Availability).
• Verified that the guide.md correctly identifies when to use style queries vs. size queries via a new decision matrix.

[knowler]

I wonder if it would be better to layer on style queries as a progressive enhancement in the fallback since container-type: inline-size wouldn’t have complete overlap with style queries (i.e. it would go back much farther and would match situations that don’t support style queries). For example, these could be the defaults that the style queries then overrides. Could use :where(section.promo) + order of appearance to ensure the style query wins.

/* Default styles */
.button {}

/* Contextual styles (wide support) */
:where(section.promo) .button {
  background: var(--brand-accent);
  color: white;
}

/* Style query aided contextual styles (limited support) */
@container style(--priority: high) {
  .button {
    /* Automatic switch to Filled promotional style */
    background: var(--brand-accent);
    color: white;
    border: none;
  }
}

[LeaVerou]

+1 to what @knowler said. And sadly we don't have a container-type: style to query.

And if you want to apply CSS when style CQs are supported without querying any particular property, you can do something like this: https://codepen.io/leaverou/pen/qEqqZQq

[castastrophe]

Yes, +1. I have an update I'll push, would love your thoughts on it.

[jamesnw]

A few questions and tweaks, but it looks good!

[LeaVerou]

Just a quick note that I have seen the review request and plan to take a proper look at this once I'm done with the dark mode rewrite.
Very excited about this use case!

[LeaVerou]

I understand what you mean, but I think this is hard to understand without a lot of context. Perhaps an example would make it clearer?

[castastrophe]

I'll update with some more concrete examples. Let me know what you think.

[LeaVerou]

I left some comments, but on a high level I think it's still unclear (to me at least!) what use cases are part of this and which ones are part of design-token-reactivity.

E.g. I'd expect that a --priority property would be a high-level property that affects multiple design tokens, and that elements it's applied on themselves need to adapt to it themselves (e.g. a button with --priority would need a different border, background, text color etc). But also I wouldn't expect --priority: promo and I have no idea whether that's higher or lower than --priority: high. Looking at the expectations, button variant also seems more design token-y.

The description does a good job at drawing a clear distinction between the two, so I think it just needs a different example that's closer to real-world usage and clearly distinct from design tokens. I can't think of one offhand, but will try to brainstorm a few examples as well.

A more practical caveat I have discovered when using style queries: there is no way to match the actual element the property was specified on, so if you want to apply any styling that shouldn't be inherited (e.g. add a shadow) in a style query, one way to do that without applying it to every element in that subtree is to register the custom property as non-inheritable. Then it will only match direct children and you can use descendant selectors inside it if needed. You can even set a regular property in that rule, so that you have an inherited and a non-inherited version to query. Happy to expand on this if it comes up, just dropping it here so that if you encounter it while working on these you know it has a solution.

[rviscomi]

@castastrophe is this ready for another look?

[castastrophe]

@rviscomi Not ready yet - it needs Lea's updates applied as well.

[LeaVerou]

@rviscomi Not ready yet - it needs Lea's updates applied as well.

You mean updates to things mentioned in my review or updates by me? 👀 Fine either way, just asking to make sure it doesn't fall off my radar if it's the latter!

[castastrophe]

@rviscomi Not ready yet - it needs Lea's updates applied as well.

You mean updates to things mentioned in my review or updates by me? 👀 Fine either way, just asking to make sure it doesn't fall off my radar if it's the latter!

Haha updates by me based on your already provided feedback. Cheers!

[castastrophe]

@LeaVerou

A more practical caveat I have discovered when using style queries: there is no way to match the actual element the property was specified on, so if you want to apply any styling that shouldn't be inherited (e.g. add a shadow) in a style query, one way to do that without applying it to every element in that subtree is to register the custom property as non-inheritable. Then it will only match direct children and you can use descendant selectors inside it if needed. You can even set a regular property in that rule, so that you have an inherited and a non-inherited version to query. Happy to expand on this if it comes up, just dropping it here so that if you encounter it while working on these you know it has a solution.

I think this is a really great approach to a more advanced concern than the use-case is covering. If I put on my design systems cap, those style queries are equivalent to design language "promo", "priority", etc. and when components are in that context, designers want certain things applied. Spectrum was filled with concepts like this throughout the system and I tried to pull out just one small example for this documentation. I think we could honestly go into much more use-case detail if the use-case expected more of a black-box implementation where the developer doesn't necessarily know where these assets will be used.

tldr; I didn't want to bloat this with too much nuance or detail. I love the idea of digging into it in the future though.

[rviscomi]

@castastrophe is this ready for re-review?

[castastrophe]

@rviscomi Yes, this is updated and should now address all review feedback.

[LeaVerou]

Much better, see comments!

[castastrophe]

@LeaVerou Updates applied, looking forward to your thoughts!

[LeaVerou]

I love what you did with the framing/routing sections! It kept the essence of what I suggested, but a lot tighter! 😍

Btw, custom states can sometimes serve as another way to decouple context. E.g. any component can set :state(featured) and other elements can react to it. Of course that's much more limited (it only works when the context is set on a WC, and there is no way to decouple the descendant), but I wonder if it may be worth mentioning in the fallback section. Not sure.

Anyhow, this LGTM! Great guide!

[castastrophe]

Btw, custom states can sometimes serve as another way to decouple context. E.g. any component can set :state(featured) and other elements can react to it. Of course that's much more limited (it only works when the context is set on a WC, and there is no way to decouple the descendant), but I wonder if it may be worth mentioning in the fallback section. Not sure.

Great point, custom states are a nice tool for reading context. I'm going to hold off for now though since, as a fallback, it doesn't broaden support (:state() and container style queries reached interop around the same time), and it only decouples the producer side — the reactor still needs a descendant selector (:host(:state(featured)) .badge). In addition, that it requires a web component is a bigger prerequisite than the rest of this guide assumes. I love it as a follow-up for the WC skill though and I know we were having discussions about that spec there too. Thanks for the thorough reviews on this one! 🙏

[castastrophe]

@rviscomi @malchata This one looks to be approved and ready for review!

[jamesnw]

LGTM!

[rviscomi]

Heads up that this guide was moved under css-layout in #909

[castastrophe]

@rviscomi I've updated the location and rebased against the latest from main. Should be good to go now 💃