Style conditions and variants

[kof]

Note

Variants are property values styled through this shared system. They are not component-specific. See Builder components.

Problem

• The active style condition is hidden in the Style Sources menu.
• Condition selection is too closely tied to the selected token.
• Users need to style eligible elements by property or attribute value.

Goals

• Make the active style condition visible in the Style panel.
• Separate condition selection from style-source selection.
• Support CSS selectors, component-defined states, and property-value conditions.
• Keep property-value styling usable without Builder components.
• Keep the default condition list short; make other conditions searchable.

Model

• A style condition determines when declarations apply.
• Condition types:
  • CSS pseudo-classes and pseudo-elements.
  • Component-defined states.
  • Property-value conditions.
  • Custom selectors.
• “Variant” describes styling one or more property values.
• A variant is not a special property or component type.
• Local styles and tokens store declarations for conditions.
• Tokens do not own the element's available conditions.
• Select a condition to edit or preview it.
• Select Local or a token to choose where declarations are saved.

Style panel selector

• Add an always-visible condition selector.
• Keep it separate from Style Source selection.
• Preview the selected condition on the canvas.
• Default list includes conditions styled on the selected element's applied sources.
• Always include the currently selected condition.
• Add More… with search.
• Group search results by condition type.
• Do not list unrelated selectors from unapplied project tokens.
• Show whether the selected source has styles for each condition.
• After styles are saved, include the condition in the default list.

Selector notation

• Preserve native CSS syntax: :hover, :focus-visible, ::placeholder.
• Show component states using their metadata selector, such as [data-state="note"].
• A state label may be supporting text; never replace the selector.
• Show property conditions as property: value, using exact property spelling.
• Keep custom selector syntax intact.
• Selecting a condition changes the editing and preview context.
• The selected source still determines where declarations are stored.

Property-value conditions

Fixed-choice properties

• Define a finite set of values in property authoring.
• Use each value as its label; do not define separate labels.
• Set the default in property authoring.
• Show each value as a one-click condition.
• Example: select Appearance, then primary to activate appearance: primary.
• Keep fixed-choice property authoring independent from this selector UI.

Open-value properties

• Support exact-value conditions for eligible properties.
• Do not enumerate open-ended values.
• Let authors enter a specific exact value using the existing custom-selector flow.
• Example: [data-label="Summer sale"].
• Offer a known static or default value as a shortcut when available.
• Only include values that can be serialized for selector matching.
• Exclude complex values such as objects and arrays.
• Allow exact string matches for open-ended string values.

CSS output

• Keep the condition model semantic and independent of CSS output.
• Do not make @container style() the definition of a variant.
• @container style() is one possible output strategy.
• It queries an ancestor container and cannot style that container itself.
• Use attribute selectors or another scoped strategy when the element carrying the value must be styled.
• Choose output based on scope, target element, and browser support.
• Reference: MDN container style queries.
• Reference: May 2026 Baseline digest.

Implementation batches

Batch 1 — Condition model and discovery

• Model CSS selectors, component metadata states, property values, and custom selectors as distinct conditions.
• Keep condition availability independent from Local/token style sources.
• Find applicable CSS selectors and component states for the selected element.
• Find conditions already styled on the selected element's applied sources.
• Build the short default list from those conditions plus the active condition.
• Exclude conditions from unrelated, unapplied project tokens.

Batch 2 — Style panel selector

• Add an always-visible condition selector, separate from Style Source.
• Add More… with search and grouped condition types.
• Preserve CSS syntax, component state selectors, and exact property spelling.
• Show whether the selected source has declarations for a condition.
• Preview the selected condition on the canvas.
• Save edits to the selected Local or token source.
• Add newly styled conditions to the default list.

Batch 3 — Property-value conditions

• Connect fixed-choice property values to one-click conditions.
• Use option values as labels; keep defaults in property authoring.
• Add exact-value conditions for eligible open-value properties.
• Do not enumerate open-ended property values.
• Exclude non-serializable or complex property values.
• Keep property-value conditions independent of Builder component creation.

Batch 4 — CSS output and compatibility

• Select CSS output based on condition scope and target element.
• Support styling the element carrying the property value.
• Keep token cascade, breakpoints, and component metadata states working.
• Preserve existing custom selectors.

Acceptance criteria

• The active condition is visible independently of Local/token selection.
• The default list shows used conditions and the active condition.
• Search finds other applicable conditions under More….
• CSS selectors, metadata states, property values, and custom selectors are distinguishable.
• Selector notation preserves CSS syntax and property spelling.
• Fixed-choice values are selectable with one click.
• Open-value properties support exact matches without exhaustive option lists.
• Styles apply to the intended element and compose with tokens and breakpoints.
• Existing metadata states and custom selectors keep working.
• CSS output remains an implementation choice, not part of variant semantics.

Related issues

• Builder components (#2529) defines component properties. Those properties can use this shared condition system.

[Rocksteady808]

1. How is a condition stored? As the existing StyleDecl.state string, e.g. :is([data-ws-props~="=large"] *). The copy carries data-ws-props="=large …". Is a selector string OK, or should conditions be a structured field on StyleDecl?
2. Property id or name in the selector? I use the id, so renaming the property doesn't break styles. Renaming a value would mean rewriting styles, so that isn't supported yet. Should value rename be supported?
3. Styling the element carrying the value: copies have no element by default, so conditions currently style elements inside the copy. How should styling the carrier element work?
4. Auto-selecting the condition: selecting an element inside a copy set to a non-default value (e.g. size: large) pre-selects that condition, like Webflow variants. Copies on the default value edit the base styles. Keep this, or should it always be picked explicitly?
5. Combining with states: picking :hover while size: large is active edits size: large :hover. Is that the right notation and behavior?
6. Values bound to data: these style correctly in the Builder. On the published site the attribute currently only covers fixed values. Should data-bound values need to work there too?
7. Open-value conditions outside components: which SDK props should be eligible? Only props that