Component styles apply to the component

vapors parses stylesheets with its own Rust CSS engine, vapors-css, and the element tree in vapors-elements applies the computed styles. A document’s styles come from three sources: a user-agent sheet, global sheets an application adds with Document::add_stylesheet, and each mounted component’s style section.

A component’s style applies only to the elements that component creates. Each element the component creates carries a data-wisp attribute naming the component’s scope, and the document rewrites every selector to require it:

  • the last compound requires the scope as an attribute selector, so a scoped rule gains one attribute’s specificity, (0,1,0);
  • every other compound, including those inside :is(), :not(), :where() and :has(), requires it inside :where(), which adds no specificity.

A child component’s elements carry the child’s scope, so a parent’s .title rule does not style a child’s .title. The panel demo on the examples page checks this.

:global(...) leaves the compound holding it unscoped, for an element the component did not create:

:global(body) {
  margin: 0;
  display: flex;
}

:global inside :is(), :not(), :where() or :has() is refused, and so is a :global { ... } block. In a global sheet, which has no scope, :global is refused anywhere. @keyframes names are global.

The style attribute

A literal style="..." attribute is read as author declarations above any selector’s specificity. An !important sheet declaration still overrides a normal inline one. A style attribute that does not parse is refused, naming the element, line and column. style={expression} is refused at build time, as is class={expression}: the compiler must see every declaration and class an element can have. Write the declarations under a class in the style section and toggle the class with class:name={bool}.

Selectors and the cascade

The engine supports type, class, ID and attribute selectors, combinators and structural pseudo-classes. The engine matches the state pseudo-classes :hover, :focus, :focus-visible, :focus-within, :active, :checked, :invalid, :disabled and :enabled from flags the tree sets. The element tree sets :hover and :active from the pointer, the three focus flags from keyboard and pointer focus, :checked on a checkbox, :invalid on a number field whose text is not a number in range, and :disabled or :enabled on a button.

Cascade resolution includes user-agent and author origins, specificity, source order, inheritance and !important. Supported functional selectors include :is(), :where(), :not() and :has(), within the limits documented in the framework guide.

Values and custom properties

Supported lengths include px, em, rem, %, vw, vh and ch. The value parser handles var() with fallbacks and typed arithmetic with calc(), min(), max() and clamp().

:root {
  --panel-padding: 16px;
  --foreground: #f0f5f9;
}

.panel {
  padding: var(--panel-padding);
  color: var(--foreground);
  width: calc(100% - 32px);
}

Custom properties inherit. An unresolved variable, a variable cycle or a substituted value that fails the property’s grammar returns an error naming the declaration. These cases are not silently dropped.

Environment and motion

Media queries read the supplied environment: viewport size, colour scheme, resolution and reduced-motion preference. The shell demo uses @media (width < 600px) to hide its side panel. The CSS engine evaluates container queries against the nearest container’s size, but the element tree does not apply container-type or container-name yet.

The engine can interpolate transitions and keyframes, sampled at an elapsed time the caller supplies; it has no internal clock. The element tree does not run them yet.

Explicit limits

The parser refuses unknown properties, unknown at-rules and unsupported values with line and column information. Pseudo-elements such as ::before and ::after are not implemented. At this revision @font-face, @import and @layer are refused.

The CSS engine parses some properties the element tree does not apply yet, among them transitions, animations, transform, opacity and filter. A rule that sets one to anything other than its initial value is refused when the document updates, naming the property, the element and the declaration’s position. The element tree also refuses some values the engine parses, such as dashed borders and position: sticky. It applies outline-*, scrollbar-color and scrollbar-width. Elements and events lists both.

Validation

The compiler reads each component’s style section with the runtime’s own CSS parser and scoping rules. A style that does not parse (an unknown property, an unknown at-rule, a value the parser refuses) or a :global() the scoping cannot honour fails the build, naming the .wisp file, line and column. wisp-check reports the same errors without a full build. This is separate from the build-time restrictions on expression-valued class and style attributes described above.

Some refusals still happen when the document updates: values the parser accepts but the element tree does not apply, listed under Explicit limits above, and styles an application adds from Rust with add_style. Values that depend on the running app, such as inherited custom properties, the viewport size and interaction state, are resolved at run time.

Component scoping controls which elements a stylesheet can affect. Validation checks whether its syntax and values are supported. Neither moves all style computation to build time: stylesheets are still parsed when a component first mounts, and rules that depend on state are matched at run time. The performance page describes what the compiler works out in advance.

The component styling lesson shows where the style section sits in a .wisp file. Performance explains how repeated elements can share computed styles and which inputs prevent sharing.