weft
ir 2.6.0 · warp 1.8.0

A component’s own stylesheet

Name a sheet .scoped.css and its selectors reach the elements that component declares, and nothing else on the page.

card.scoped.css — as authored
.card { border: 1px solid red }.card .body { opacity: 0.7 }
card.tsx — sealed by the compiler
<div data-w-d901a5ad class="card">  <p data-w-d901a5ad class="body">
on the wire
.card[data-w-d901a5ad] { … }.card .body[data-w-d901a5ad] { … }
The same mechanism Vue, Svelte and Angular use. What is different is when it happens: a template here is data rather than a function, so the attribute is stamped into the sealed bytes by the compiler — nothing at runtime, and one attribute per element on the wire.

Put a .css beside a fragment and every page that renders it links that sheet. Name the file .scoped.css instead and the sheet is narrowed: its selectors reach the elements that fragment declares, and nothing else on the page.

It is the same idea Vue, Svelte and Angular ship. What is different here is when it happens. A template is data rather than a function, so the compiler writes a scope attribute into the sealed bytes at build time — there is no hydration step, nothing injected in the browser, and no mangled class name to read past in devtools. The class in the sheet is the class in the markup; only its reach changed.

sketch — not compiled
// app/fragments/card.tsx
export default fragment(({ title }: Props) => (
  <div class="card">
    <h3 class="title">{title}</h3>
  </div>
))
sketch — not compiled
/* app/fragments/card.scoped.css, as you write it */
.card { border: 1px solid red }
.card .title { font-weight: 700 }

/* as it is served */
.card[data-w-d901a5ad] { border: 1px solid red }
.card .title[data-w-d901a5ad] { font-weight: 700 }

Opting in, by filename

Both files may sit beside one fragment, and they cascade in that order — global first, scoped after — so a component can take the shared look and then say what is different about it.

FileReach
card.cssGlobal. Linked by the pages that render card, as it always was
card.scoped.cssNarrowed to the elements card.tsx declares

The filename carries the decision because the decision has to be visible. A marker inside the file would put it where a reader of a diff does not look, and a config list would put it in a third place that can disagree with both. Renaming the file is the whole of the change.

It works for every kind of template the convention knows: app/layout.scoped.css, app/routes/<dir>/layout.scoped.css, app/routes/about.scoped.css, and the same beside a slot, an alternate layout or a fragment.

Where the scope stops

At a component boundary. A <Card/> rendered inside another fragment is its own sealed template and carries its own scope, so the parent’s rules do not reach into it.

What it costs

Nothing at runtime, and one attribute per element on the wire. The attribute is derived from the file’s path rather than its contents, so editing a template or its sheet never changes it and a cached stylesheet survives a typo fix.

A scoped sheet beside a route whose body is markup rather than a template is E_SCOPED_NO_TEMPLATE: there are no elements to narrow it to, and a sheet that silently applied to nothing is one that appears to work until somebody looks.