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

guides/user-experience/usage-aware-component-variations/expectations.md

@@ -0,0 +1,7 @@
+- The parent containers define semantic context flags using CSS custom properties (e.g., `--surface: featured` vs. the unset default).
+- The component uses `@container style()` queries to adapt its internal visual logic (e.g., button variant, badge visibility) based on these inherited properties.
+- When the surface is `featured`, the component reveals promotional elements (like a badge) and uses a more prominent "filled" button style.
+- When the surface is unset (default), the component hides promotional elements and uses a more subtle "outlined" button style.
+- The component does NOT rely on size queries (`min-width` or `max-width`) for this semantic variation.
+- The implementation uses logical properties (e.g., `inline-size`, `inset-block-start`) for consistent layout.
+- A progressive-enhancement fallback using selectors with `:where()` is provided so browsers without style query support still get the contextual styling.

guides/user-experience/usage-aware-component-variations/guide.md

@@ -1,6 +1,112 @@
 ---
 name: usage-aware-component-variations
-description: Build a component that can adapt its styles conditionally based on where it appears in the DOM (via CSS custom property inheritance) rather than available size. For example, a table of contents components that is expanded in the sidebar but collapsed in a single-column layout.
+description: Build components that adapt visual logic based on semantic context using CSS container style queries.
 web-feature-ids:
   - container-style-queries
+sources:
+  - https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container#container_style_queries
+  - https://developer.chrome.com/docs/css-ui/style-queries
 ---
+
+# Semantic Component Adaptation
+
+Use style queries (`@container style()`) to trigger component variations based on inherited semantic context flags rather than viewport or container dimensions. This replaces deep descendant selectors (e.g., `.sidebar .card`) and improves component encapsulation.
+
+In design systems, this lets a component respond to its surrounding context without that context needing to know the component exists. For example, a card placed inside a section marked `--surface: featured` can swap to a filled button and reveal a promotional badge — the section never names `.button` or `.badge`, and the card never inspects its parent.
+
+## How is this different from design-token-reactivity?
+
+[`design-token-reactivity`](../design-token-reactivity/guide.md) covers *token-level* changes: density modes, themes, and other higher-order tokens that uniformly shift values (paddings, colors) across many components.
+
+This guide covers *behavioral* changes: a component deciding **what to render, how to arrange itself, or which variant to present** in response to its context. Hiding/showing a badge, switching layout direction, or swapping a button variant all fit here.
+
+## Mental Model
+
+- **Size Queries:** Use for layout/density changes (width/height).
+- **Style Queries:** Use for semantic logic — what the component should *do* in this context.
+
+## Implementation Directives
+
+1. Define a semantic context flag using a CSS custom property on a container.
+2. **DO NOT** set `container-type` for style queries; they query inherited custom properties on the nearest ancestor and don't require an explicit containment context.
+3. **MANDATORY**: Use `@container style(--property: value)` to apply conditional styles to descendant elements. Style queries cannot match the element the property is set on — only its descendants.
+4. **DO** prefer style queries over descendant selectors to avoid specificity inflation and hardcoded DOM dependencies.
+
+## Implementation Example
+
+```css
+/* 1. Set the context on a layout container */
+.featured {
+  --surface: featured; /* Semantic context flag for children */
+}
+
+/* 2. Component reacts to inherited flag */
+.button {
+  /* Default: Outlined informational style */
+  background: transparent;
+  border: 1px solid currentColor;
+}
+
+.badge {
+  /* Default: Hidden — only revealed in featured surfaces */
+  display: none;
+}
+
+@container style(--surface: featured) {
+  .button {
+    /* Automatic switch to Filled promotional style */
+    background: var(--brand-accent);
+    color: white;
+    border: none;
+  }
+
+  .badge {
+    /* Reveal decorative elements only in featured context */
+    display: block;
+  }
+}
+```
+
+## Fallback Strategies
+
+{{ BASELINE_STATUS("container-style-queries") }}
+
+Until container style queries are widely available, layer them on as a progressive enhancement: ship a selector-based default that works everywhere, and let the style query override it when supported. Use `:where()` on the context selector so the style query (same specificity, later in source order) wins automatically.
+
+```css
+/* Default styles — work everywhere */
+.button {
+  background: transparent;
+  border: 1px solid currentColor;
+}
+
+.badge {
+  display: none;
+}
+
+/* Selector-based contextual styles — broad browser support */
+:where(.featured) .button {
+  background: var(--brand-accent);
+  color: white;
+  border: none;
+}
+
+:where(.featured) .badge {
+  display: block;
+}
+
+/* Progressive enhancement: style queries override when supported */
+@container style(--surface: featured) {
+  .button {
+    background: var(--brand-accent);
+    color: white;
+    border: none;
+  }
+
+  .badge {
+    display: block;
+  }
+}
+```
+
+The selector fallback ties the contextual styling to a class name, which couples the component to its DOM placement. Once style queries are widely supported, the `:where()` rule can be removed.