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

[jamesnw]

A few questions and tweaks, but it looks good!

[jamesnw]

I'm unsure- do you need to show .badge{ display: none} in the guide to show it's being overridden?

[jamesnw]

I don't think this exists? I could be wrong, but my understanding is there would need to be a file in /features/container-style-queries with a ## Fallbacks section for this to work.

[LeaVerou]

If a file doesn't exist, it will just print baseline status (so the next para isn't needed).

That said, we do need to have that content, either there or here! But if the intent is to add this so we can add the fallback later, that's OK, I think? (unsure)

[jamesnw]

Suggested change

	--priority: high; /* Semantic flag for children */
	--priority: promo; /* Semantic flag for children */

For consistency with the demo

[castastrophe]

Oh I meant to update the demo too - it felt like promo was too "what it is" and not "what the context means".

[jamesnw]

I'm not sure I understand what's meant by layout context fully- maybe another example?

[LeaVerou]

AFAIK name-only CQs have worse browser support than style queries, and no web-feature id so we can do BASELINE_STATUS.

Just filed web-platform-dx/web-features#4039 about that — laziest bug report ever but at least now there's something!

[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?

[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!