Skip to main content

Menu

Theme Scope

Info:Layout

0

A provider that derives an invocation and themes everything inside it.

theme

scope

provider

algorithm

invocation

derive

scheme

tokens

Each scope invokes a different algorithm and applies the result to its own subtree only. The page around them never moves, which is the whole point of target="self" being the default.

xtyle-default

Surfaces, text, and controls all derive from this scope.

xtyle-quiet

Surfaces, text, and controls all derive from this scope.

xtyle-loud

Surfaces, text, and controls all derive from this scope.

xtyle-hc

Surfaces, text, and controls all derive from this scope.

nxi-nite

Surfaces, text, and controls all derive from this scope.

scheme pins the mode. When the algorithm derives natively to the other one, the scope re-derives with invert, so every surface lands where the algorithm puts it rather than on a mirrored guess.

dark

Derived natively.

light

Re-derived inverted from the same inputs.

An invocation is more than an algorithm id: constraints pin it and knobs turn its own dials. The nested <xtyle-scheme-toggle> finds the scope and flips it, re-deriving through the engine instead of touching :root.

seeded accent

Click the toggle: only this card flips.

loud + duo

A knob turned on the same seed.

Theme Scope materializes an invocation — a named algorithm plus its knobs and token constraints — and applies the derived register to a target, so everything beneath it renders on that theme. It draws nothing of its own: the children you write are the content, untouched.

target decides what the tokens land on, and it defaults to self, scoping the theme to this element's subtree — that is what makes a themed card, a mockup frame, or two algorithms side by side possible without either one leaking onto the page. target="root" drives :root instead, for the single scope that themes a whole document. The scope also owns the scheme: it derives the algorithm natively, and when the requested scheme is not the one that derivation produced, it re-derives with invert, so one set of inputs yields both modes through the engine rather than a hand-mirrored guess. An <xtyle-scheme-toggle> nested anywhere inside drives the scope rather than the document. Each settled derivation fires xtyle:theme-scope carrying the scheme and the applied register, and a bad invocation reports the error on that same event instead of applying a half-derived theme.

When to use

How this component composes with the rest of the set.

Wrap a card, a preview frame, or a mockup to theme just that subtree, and put two next to each other to compare algorithms on one page.

Use one target="root" scope for the app-level theme, and nest target="self" scopes inside it wherever a region needs its own.

Nest an <xtyle-scheme-toggle> inside and it drives the scope through the engine's inversion instead of flipping :root[data-scheme].

Listen for xtyle:theme-scope to mirror the applied register elsewhere, or to surface a bad invocation's error.

Props

5 props, straight from the manifest.

Prop	Type	Default	Bindings	Description
algorithm	string	xtyle-default	html svelte astro	The id of the algorithm to invoke (`xtyle-default`, `xtyle-hc`, `xtyle-quiet`, `xtyle-loud`, `nxi-nite`, or any registered algorithm).
target	"self" \| "root" self root	self	html svelte astro	Where the derived tokens land: this element's subtree, or the document root.
scheme	"light" \| "dark" light dark	—	html svelte astro	Pins the rendered scheme, re-deriving inverted when the algorithm's native mode is the other one. Omit to take whatever the algorithm derives natively.
knobs	Knobs	—	html svelte astro	The algorithm's own dials, as an object in the framework bindings and JSON in the HTML attribute.
constraints	Constraints	—	html svelte astro	Direct token overrides applied over the derivation, the universal escape hatch.

Appearance

States

effective scheme

xtyle-theme-scope[data-effective-scheme]

The scheme the last derivation actually produced, published for anything that must reflect what is on screen rather than what was asked for.

Anatomy

The named parts that make up the component, with their selectors.

scope

xtyle-theme-scope

The element itself. Under the default target="self" the derived custom properties are set on it, so the cascade carries the theme to its children.

Tokens & coverage

What the component consumes, checked live against what the algorithm produces.

Success:fully covered

0/0 consumed tokens produced

default register: 310 tokens

Live coverage check against the xtyle-default register (derive(xtyleDefault, { anchors }) → coverComponent(manifest, register)). Every token this component consumes must be a key the algorithm produces.

Slots

default

html

svelte

astro

Everything the scope themes. Rendered exactly as authored; the scope adds no markup of its own.

Code

Scoped subtrees, pinned schemes, and the page-level scope

A scope theming just its own subtree, two invocations side by side owning their own schemes, and the root-targeting scope a toggle drives.

<!-- Scoped to its own subtree: everything inside renders on the derived theme -->
<xtyle-theme-scope algorithm="xtyle-quiet" constraints='{"--accent":"#7c5cff"}'>
	<xtyle-card>
		<xtyle-heading level="3">Quiet</xtyle-heading>
		<xtyle-text>Only this card is themed.</xtyle-text>
	</xtyle-card>
</xtyle-theme-scope>

<!-- Two invocations side by side, each owning its own scheme -->
<xtyle-theme-scope algorithm="xtyle-default" scheme="light">
	<xtyle-card>Light</xtyle-card>
</xtyle-theme-scope>

<!-- The page-level scope: drives :root, with a toggle that re-derives through it -->
<xtyle-theme-scope target="root" algorithm="xtyle-default">
	<xtyle-scheme-toggle></xtyle-scheme-toggle>
</xtyle-theme-scope>

<script lang="ts">
	import { ThemeScope, SchemeToggle, Card } from "@xtyle/svelte";
</script>

<ThemeScope algorithm="xtyle-quiet" constraints={{ "--accent": "#7c5cff" }}>
	<Card>Only this subtree is themed.</Card>
</ThemeScope>

<!-- the page-level scope, with a toggle that drives it -->
<ThemeScope target="root" scheme="light">
	<SchemeToggle />
</ThemeScope>

---
import ThemeScope from "@xtyle/astro/ThemeScope.astro";
import SchemeToggle from "@xtyle/astro/SchemeToggle.astro";
import Card from "@xtyle/astro/Card.astro";
---

<ThemeScope algorithm="xtyle-quiet" constraints={{ "--accent": "#7c5cff" }}>
	<Card>Only this subtree is themed.</Card>
</ThemeScope>

<!-- the page-level scope, with a toggle that drives it -->
<ThemeScope target="root" scheme="light">
	<SchemeToggle />
</ThemeScope>