@zvndev/darkmown 1.3.0 → 1.4.0

package/AGENTS.md

@@ -253,6 +253,8 @@ input:focus-visible
 ```
 Always include: a tokens block, a real type scale, generous spacing, a `max-width` centered `main`, styled `button`/`input` with `:hover`/`:focus-visible` states, and a responsive `@media` rule (`.skin` supports `@media` — its indented rules are wrapped automatically). The `font` property is the CSS shorthand when it leads with a size (`font 16px/1.6 system-ui`) and `font-family` otherwise. Prefer `.skin`; a plain `<style>` block in a `.wd` also works.
 
+**Scoped styles — opt in with `scoped`.** A `.skin` is **global** by default (style site-wide; the right default for your design system). To stop a reusable component's classes from clashing with the rest of the page, make the **first line** of its `.skin` the word `scoped` — its selectors then only match the component it's colocated with (a page skin scopes that page; an include skin scopes just that include's subtree). You still write `class="card"`; the build stamps a `data-wd-scope` attribute and rewrites the selectors — zero runtime, a static page stays static. **Tokens stay global** (a `tokens`/`tokens dark` block still emits `:root` vars, so `$accent` and dark mode keep working). Escape a single rule with `:global(.x)` (whole-selector only). `page`/`*`/`html`/`body`/`::selection` are a compile error in a scoped skin — those belong in a global skin.
+
 **Layout gotcha — CTAs and link rows.** Markdown wraps adjacent links/buttons on consecutive lines into a single `<p>`, so putting `display:flex` on their container won't space them. To lay out a row of buttons or nav links, wrap them in explicit raw HTML and style that:
 ```wd
 <div class="actions">

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 1.4.0 — 2026-06-28
+
+Scoped styles — the long-standing "`.skin` selectors are global" gap, closed. Opt-in, compile-time, and **zero runtime** (the shared runtime is still 7459 B gzipped; nothing new ships to the client but one HTML attribute and one attribute selector).
+
+- **`scoped` skins.** Put `scoped` as the first line of a `.skin` file and its selectors apply only to the page or include it ships with — so two components can reuse the same class name (`.card`) without colliding. The compiler appends a per-file `[data-wd-scope="wd-xxxx"]` attribute to each selector's subject and stamps the matching subtree's HTML; the scope id is a stable hash of the skin's path. Selectors compose as you'd expect: descendant selectors scope only the subject, comma lists scope each branch, `@media`/`@supports` wrappers pass through, and `&`-nesting/pseudo-classes resolve before the attribute is attached.
+- **Tokens stay global.** A `tokens` / `tokens dark` block in a `scoped` skin still emits global `:root` custom properties, so `var(--…)`, dark mode, `:theme`, and the `$code-*` highlight tokens keep working across the whole site — only your component's selector rules are scoped.
+- **`:global(...)` escape hatch** for a whole selector that must stay global (e.g. a class you portal elsewhere). Page-level selectors (`page`, `*`, `html`, `body`, `::selection`) are rejected in a scoped skin with a corrective hint — those belong in a global design-system skin.
+- **Fully backward compatible.** A `.skin` without the `scoped` marker is unchanged, byte-for-byte (covered by a golden test). Existing global skins — `base.skin`, `nav.skin`, every scaffolded project — keep styling the whole site exactly as before. Unused scoped selectors produce a build *warning* (never silently removed, since a colocated `.js` behavior may add the class at runtime).
+
 ## 1.3.0 — 2026-06-28
 
 The "table-stakes batteries" release — the build-time, zero-JS features a markdown site is expected to ship. The runtime is unchanged (still 7459 B gzipped, well under the 8 KB budget); everything here is compile-time HTML/CSS or build output.

package/README.md

@@ -809,6 +809,50 @@ A single `tokens dark` block powers **both** theming paths: it compiles to `:roo
 
 Because `tokens dark` already emits the `[data-theme="dark"]` rule, **no extra skin block is needed** — the same palette drives the toggle. `"light"` forces the light palette even under OS dark; `"auto"` clears the attribute and follows the OS again; `theme` persists across reloads and tabs like any `:store`. (`:theme name = "light"` renames the store and seeds a different default. The older `tokens [data-theme=dark]` block — a manual-only override — still works for bespoke setups.)
 
+## Scoped styles — `scoped`
+
+*New in 1.4.0.* By default a colocated `.skin` is **global** — its selectors match the whole page, exactly like a stylesheet. That's the right default for a design system. But when two components both want a class called `.card`, global CSS makes them fight. Opt a skin into **scoping** so its selectors only ever match the component it ships with: make the **first line** of the `.skin` file the word `scoped`.
+
+```skin
+scoped
+
+.card
+  padding 1.5rem
+  bg $panel
+  radius $radius
+```
+
+Scoping is **pure compile time** — a short, path-derived id (e.g. `wd-7c21`) is stamped onto the component's HTML (`data-wd-scope="wd-7c21"`) and appended to each of the skin's selectors:
+
+```css
+.card[data-wd-scope="wd-7c21"] { padding: 1.5rem; }
+.card[data-wd-scope="wd-7c21"] { background: var(--panel); }
+```
+
+A second component's `.card` gets a **different** id, so the two never collide. There is **no runtime cost and no class renaming in your markup** — you still write `class="card"`; the framework adds the attribute during the build. A static page with a scoped skin stays **zero-JS**.
+
+**What scopes, what stays global:**
+
+| In a `scoped` skin | Result |
+|---|---|
+| A selector rule (`.card`, `.card:hover`, `.card .title`, `h2, h3`) | Scoped — the attribute lands on the **subject** (rightmost) selector, before any `:hover`/`::before` so it stays valid CSS |
+| A descendant selector (`.card .title`) | Only `.title` (the subject) is scoped; `.card` matches inside the subtree |
+| `tokens` / `tokens dark` / `tokens [data-theme=…]` | **Global** — design tokens always emit on `:root`, so `$accent` and dark mode keep working site-wide |
+| `:global(.toast)` (whole selector) | **Opts back out** — emits a plain, unscoped `.toast { … }` |
+| `@media` / `@supports` wrappers | Untouched; only the inner rule's selector is scoped |
+| `page` / `*` / `html` / `body` / `::selection` | **Compile error** — page-level styles belong in a global skin, not a scoped one |
+
+Where the scope applies depends on **where the skin lives**:
+
+- A skin colocated with a **page** (`about.skin` next to `about.wd`) scopes that page's body.
+- A skin colocated with an **include** (`card.skin` next to `card.wd`) scopes just that include's subtree wherever it's `@include`d — so the same scoped component can appear many times on a page without leaking into its neighbours.
+
+**Caveats (honest limits this release):**
+
+- **Whole-selector `:global()` only.** A descendant `:global` (`.card :global(.x)`) is **not** supported yet — use a whole-selector `:global(.x)`.
+- **Unused selectors warn, they aren't removed.** If a scoped selector's class/element/id never appears in the stamped subtree, the build prints `hint: scoped selector ".badge" in card.skin matches no element` — but the rule is **kept** (a colocated `.js` may add the class at runtime). It's a typo nudge, not a dead-code remover.
+- **Scoping is opt-in.** Every existing `.skin` (no `scoped` marker) is byte-for-byte unchanged.
+
 ## The escape hatch
 
 Reactive pages expose `window.wd` so a colocated `.js` file can do anything the directives deliberately don't — keyboard, drag/touch, canvas, charts, maps:

package/docs/spec-alignment.md

@@ -134,6 +134,22 @@ Four progressive-disclosure capabilities plus an assets and a security change. T
 - **Page-colocated static assets:** any non-page file under `site/pages/` (anything but `.md`/`.wd` routes and colocated `.skin`/`.js`) is copied to `dist/` at its path (`site/pages/logo.svg` → `dist/logo.svg`). The shelf (`site/_/` → `/__wd/media`, `/__wd/data`) is unchanged; a name clash with an emitted route is skipped with a warning. As of v0.14.1, hidden path segments (`.`, `-`, `_`) and symlinked page assets are skipped. `.avif` was added to the served content-types.
 - **`:fetch` URL scheme hardening (security):** `:fetch`/`refresh=` URLs are validated at compile time — relative, `http(s)://`, or a leading `{ state }` interpolation are allowed; protocol-relative `//host` and non-http(s) schemes (`file:`, `data:`, `javascript:`, …) are rejected with a corrective hint. **This is scheme validation, not a host allowlist** — SSRF to arbitrary http(s) hosts remains the author's responsibility (see the trust boundary).
 
+## 1.4.0 additions — compile-time scoped styles (2026-06-28)
+
+The 1.4.0 cycle ships one feature: **opt-in scoped styles** for colocated `.skin` files, closing the "no CSS scoping" gap an audit flagged (two components couldn't reuse a class name without collision). **Pure compile time, zero runtime** — `src/runtime.js` and the 8 KB budget are untouched, and a static page with a scoped skin stays `runtime: false`.
+
+- **Authoring surface — the `scoped` marker:** a `.skin` scopes its selectors **only** when its first non-comment, non-blank, non-divider line is exactly `scoped`; colocation alone changes nothing. Every existing `.skin` (no marker) stays **global** and emits **byte-identical CSS** to before (golden-tested against `site/_/base.skin`). `scoped` anywhere but the first line is a compile error (`"scoped" must be the first line of a .skin file`). The only other new surface is `:global()` inside a scoped skin — no new `.wd` syntax.
+
+- **Mechanism — id + selector rewrite + HTML stamp.** The scope id is a short, deterministic hash of the skin's **project-relative path** (e.g. `wd-7c21`) — path-based (stable across content edits, unique per file), computed in `src/builder.js` (the coordination point) and re-derived identically by the HTML stamp from the same path, so `src/skin.js` stays a pure string→CSS function (`compileSkin(src, { scope })`). In scoped mode `compileSkin` appends `[data-wd-scope="<id>"]` to the **subject** (rightmost compound) of each comma-separated selector, **after** `&`-nesting resolves and **before** any trailing pseudo-class/element (`.card[data-wd-scope="…"]:hover`, never `.card:hover[…]`; `::before` likewise) — so descendant selectors scope only the subject (`.card .title` → `.title` gets the attribute) and `@media`/`@supports` wrappers are untouched. The HTML half (`stampScope` in `src/compiler/page.js`, an `enhanceImages`-style regex post-pass) stamps `data-wd-scope="<id>"` onto every opening tag of the scoped subtree that doesn't already carry one (first stamp wins, so a nested include keeps its own id). A **page**-colocated scoped skin stamps the page body; an **include**-colocated scoped skin is stamped in `handleInclude` over just that include's returned subtree — so the same scoped component repeats on a page without its scope leaking to siblings.
+
+- **Tokens stay global.** A `tokens` / `tokens dark` / `tokens [attr]` block in a scoped skin still emits a global `:root { --name: … }` (and the dark/manual-toggle variants) — never scoped — so `var(--x)`, dark mode, `:theme`, and the `$code-*` highlight tokens keep resolving site-wide. Enforced by only touching the selector-rule construction, leaving the token/`:root` path identical.
+
+- **`:global()` escape + disallowed selectors.** A **whole-selector** `:global(.toast)` emits a plain, unscoped `.toast { … }`. Page-level selectors in a scoped skin — `page` (→ body), bare top-level `*`/`html`/`body`/`::selection`, and any bare top-level declaration that would land on `:root` — are a **compile error** with a hint pointing to a global skin (chosen over silently auto-`:global`-ing them).
+
+- **Unused-selector handling — warn, never remove.** The builder has both the scoped subject set (collected by `compileSkin`) and the stamped subtree HTML, so it warns (`hint: scoped selector ".badge" in card.skin matches no element`) when a scoped subject's class/element/id never appears in the stamped subtree — but **keeps the rule** (a colocated `.js` may add the class at runtime). A typo nudge, not a dead-code remover.
+
+- **Honest caveats:** only **whole-selector** `:global()` this release — descendant `:global` (`.card :global(.x)`) is deferred; unused selectors **warn, are not removed**. Demonstrated end-to-end by the [`/scoped/`](/scoped/) demo (two components reuse `.card` with no collision; a global skin still works alongside).
+
 ## 1.3.0 additions — table-stakes batteries (2026-06-28)
 
 The 1.3.0 cycle closes table-stakes gaps a new user expects out of the box. Tracks land in parallel; this entry covers the **syntax-highlighting** and **drafts + feeds** tracks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/site/_/scoped-promo.skin

@@ -0,0 +1,43 @@
+scoped
+
+/* Component A — a warm promo card. Same class names as scoped-stat.skin
+   (.card / .title / .body), but scoped, so neither leaks. Tokens stay global,
+   so $accent / $warm / $radius still resolve from base.skin's :root. */
+
+.card
+  display grid
+  gap .6rem
+  padding 1.5rem
+  bg $warm-soft
+  border 1px solid $warm
+  border-left 4px solid $warm
+  radius $radius
+
+.badge
+  justify-self start
+  font-size .7rem
+  font-weight 700
+  text-transform uppercase
+  letter-spacing .08em
+  color #fff
+  bg $warm
+  padding .2rem .55rem
+  radius 999px
+
+.title
+  margin 0
+  font-size 1.25rem
+  color $ink
+
+.body
+  margin 0
+  color $ink-soft
+  max-width none
+
+.cta
+  justify-self start
+  font-weight 600
+  color $warm
+
+.cta:hover
+  color $ink

package/site/_/scoped-promo.wd

@@ -0,0 +1,10 @@
+<!-- Scoped component A. Its colocated scoped-promo.skin opts into scoping, so the
+     `.card` here gets its OWN look — a warm, accent-bordered promo — without
+     clashing with the identically-named `.card` in scoped-stat.wd. handleInclude
+     stamps just this returned subtree with the component's scope id. -->
+<article class="card">
+  <span class="badge">Promo</span>
+  <h3 class="title">Same class name, zero collision</h3>
+  <p class="body">This <code>.card</code> is a warm promo panel. The component beside it also calls its root <code>.card</code> — and they do not fight, because each scoped skin only matches inside its own stamped subtree.</p>
+  <a class="cta" href="/docs/">How scoping works →</a>
+</article>

package/site/_/scoped-stat.skin

@@ -0,0 +1,32 @@
+scoped
+
+/* Component B — a dark stat tile. Identical class names to scoped-promo.skin,
+   but a completely different look. Scoping keeps them apart; tokens are global
+   so $accent-deep / $accent / $radius-lg come straight from base.skin's :root. */
+
+.card
+  display grid
+  gap .35rem
+  justify-items center
+  text-align center
+  padding 2rem 1.5rem
+  bg $accent-deep
+  border 1px solid $accent-deep
+  radius $radius-lg
+
+.title
+  font-size 3rem
+  font-weight 700
+  line-height 1
+  color #fff
+
+.body
+  margin 0
+  max-width none
+  color $accent-soft
+
+.badge
+  font-size .68rem
+  text-transform uppercase
+  letter-spacing .1em
+  color $accent

package/site/_/scoped-stat.wd

@@ -0,0 +1,9 @@
+<!-- Scoped component B. Reuses the SAME class names as scoped-promo.wd
+     (.card / .title / .body) but its colocated scoped-stat.skin scopes them to a
+     dark, centered stat tile. Proof the leak is gone: two `.card` definitions on
+     one page, each only styling its own subtree. -->
+<article class="card">
+  <span class="title">99.9%</span>
+  <p class="body">uptime, because there is no client framework to crash</p>
+  <span class="badge">measured</span>
+</article>

package/site/pages/docs/index.wd

@@ -414,6 +414,29 @@ For an explicit light/dark switch alongside the OS preference, declare `:theme`
 
 A single `tokens dark` block in your `.skin` already powers both the OS `prefers-color-scheme` query and this toggle — no extra block needed. `"auto"` clears the attribute and follows the OS again. See it on the [Ledger demo](/ledger/).
 
+## Scoped styles — `scoped`
+
+A colocated `.skin` is **global** by default. Make its **first line** `scoped` and its selectors only ever match the component it ships with — so two components can both use `.card` without colliding. It's pure compile time: a path-derived id (e.g. `wd-7c21`) is stamped onto the HTML and appended to each selector.
+
+```skin
+scoped
+
+.card
+  padding 1.5rem
+  bg $panel
+```
+
+compiles to `.card[data-wd-scope="wd-7c21"] { … }`, and the component's markup is stamped `data-wd-scope="wd-7c21"`. You still write `class="card"` — no renaming, no runtime, **zero JS** on a static page. A page skin scopes the page body; an **include** skin scopes just that include's subtree wherever it's used.
+
+| In a `scoped` skin | Result |
+|---|---|
+| A selector rule | Scoped — attribute on the subject, before any `:hover`/`::before` |
+| `tokens` / `tokens dark` | **Global** on `:root` — `$vars` and dark mode keep working site-wide |
+| `:global(.toast)` (whole selector) | Opts back out — plain unscoped `.toast { … }` |
+| `page` / `*` / `html` / `body` / `::selection` | Compile error — page-level styles belong in a global skin |
+
+Honest limits this release: only **whole-selector** `:global()` (no `.card :global(.x)` yet), and an **unused** scoped selector **warns but is not removed** (a colocated `.js` may add the class). See the side-by-side [Scoped demo](/scoped/).
+
 ## Media — `:video`, `:audio`, `:embed`
 
 Three compile-time-only directives (they emit no `data-wd-*`, so a media page stays zero-JS):

package/site/pages/scoped/index.skin

@@ -0,0 +1,23 @@
+scoped
+
+/* Page-scoped skin for this route. The whole page body is stamped, so these
+   selectors style only this page's own markup — proving page-level scoping
+   alongside the two include-scoped components. A :global() escape hatch shows a
+   single rule opting back out to a plain, unscoped selector. */
+
+.intro
+  margin 2rem 0 3rem
+
+.duo
+  margin 3rem 0
+
+.how
+  margin 4rem 0 2rem
+
+.how ul
+  color $ink-soft
+
+/* :global escape — this selector ships UNSCOPED, matching site-wide. */
+:global(.scoped-note)
+  font-size .85rem
+  color $muted

package/site/pages/scoped/index.wd

@@ -0,0 +1,47 @@
+---
+title: Scoped styles — same class name, zero collision
+description: Two components reuse the class name .card and never clash. Compile-time scoped styles stamp each component's subtree with a path-derived id and rewrite its skin's selectors to match only there. Zero runtime JS — a static page stays static.
+transitions: true
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 1.4</span>
+
+# Scoped styles
+
+Two components on this page both call their root element `.card`. In plain CSS the second skin would overwrite the first. Here they coexist: a `.skin` whose first line is `scoped` only ever styles the subtree it ships with. It's pure compile time — a path-derived id stamped onto the HTML and appended to the skin's selectors. No runtime, no class hashing in your markup, no collision.
+
+</section>
+
+<section class="duo">
+
+<div class="grid cols-2">
+
+@include /scoped-promo.wd
+@include /scoped-stat.wd
+
+</div>
+
+</section>
+
+<section class="how">
+
+## What actually shipped
+
+- The `.card` in the warm promo and the `.card` in the dark stat tile are **different rules**, scoped to different ids.
+- This page also uses a **global** skin (`base.skin`, via `/base.wd`) — `.btn`, `.eyebrow`, `.grid` still work everywhere, unscoped.
+- Design **tokens stay global**: every scoped skin still reads `$accent`, `$warm`, `$radius` from `:root`, so dark mode keeps working for free.
+- A `:global(.x)` selector inside a scoped skin opts a single rule back out.
+
+<a class="btn primary" href="/docs/">Read the docs</a>
+
+</section>
+
+</main>
+
+@include /footer.wd

package/src/builder.js

@@ -17,7 +17,7 @@ import {
 import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
 import { HIGHLIGHT_CSS } from "./highlight.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
-import { compileSkin } from "./skin.js";
+import { compileSkin, scopeIdFor } from "./skin.js";
 
 /**
  * @typedef {import("./config.js").Paths} Paths
@@ -91,7 +91,7 @@ export function buildSite(cwd = process.cwd(), options = {}) {
     fs.mkdirSync(path.dirname(outFile), { recursive: true });
     fs.writeFileSync(outFile, page.html);
     if (route.route === "/404/") notFoundHtml = page.html;
-    emitAssets(page.assets, paths);
+    emitAssets(page.assets, paths, page.html, warned);
     if (page.assets.runtime) emitRuntime(paths);
     emitBehaviors(page.assets, paths);
     if (page.assets.hasCode) emitHighlight(paths);
@@ -544,22 +544,95 @@ function emitHighlight(paths) {
 }
 
 /**
+ * Emit a page's colocated assets. `.skin` files compile through {@link compileSkin}
+ * (other files copy verbatim). A skin that opted into scoping (`assets.scopedSkins`)
+ * compiles in scoped mode: the scope id is derived here from its PROJECT-RELATIVE
+ * PATH — the single coordination point with the HTML stamp, which derives the same
+ * id from the same path — and threaded into `compileSkin({ scope })`. The compiler
+ * also reports the scoped subject selectors, which we check against the stamped page
+ * HTML to warn (never remove) on a scoped selector that matches no element.
  * @param {Assets} assets
  * @param {Paths} paths
+ * @param {string} pageHtml Assembled page HTML (carries the `data-wd-scope` stamps).
+ * @param {Set<string>} warned Cross-route dedupe set for emitted hints.
  * @returns {void}
  */
-function emitAssets(assets, paths) {
+function emitAssets(assets, paths, pageHtml, warned) {
   for (const [source, href] of assets.files) {
     const out = path.join(paths.distRoot, href);
     fs.mkdirSync(path.dirname(out), { recursive: true });
     if (source.endsWith(".skin")) {
-      fs.writeFileSync(out, compileSkin(fs.readFileSync(source, "utf8")));
+      const src = fs.readFileSync(source, "utf8");
+      if (assets.scopedSkins.has(source)) {
+        const rel = path.relative(paths.cwd, source).replaceAll(path.sep, "/");
+        const scope = scopeIdFor(rel);
+        /** @type {Set<string>} */
+        const subjects = new Set();
+        fs.writeFileSync(out, compileSkin(src, { scope, subjects }));
+        warnUnusedScoped(subjects, scope, pageHtml, path.basename(source), warned);
+      } else {
+        fs.writeFileSync(out, compileSkin(src));
+      }
     } else {
       fs.copyFileSync(source, out);
     }
   }
 }
 
+/**
+ * Warn (do NOT remove) when a scoped selector's subject never appears in its
+ * stamped subtree — a likely typo or stale rule. We only have a class/element/id
+ * to look for, so we scan the elements actually stamped with THIS scope id in the
+ * assembled page and check each subject against them. A colocated `.js` may add
+ * classes at runtime, so this stays advisory: the rule is always emitted. An empty
+ * subject token (a bare attribute-selector subject) is unknowable here and skipped.
+ * @param {Set<string>} subjects Scoped subject tokens (`.card`, `h2`, `#id`).
+ * @param {string} scope Scope id.
+ * @param {string} pageHtml Assembled page HTML.
+ * @param {string} skinName Skin filename for the message.
+ * @param {Set<string>} warned Cross-route dedupe set.
+ * @returns {void}
+ */
+function warnUnusedScoped(subjects, scope, pageHtml, skinName, warned) {
+  // The opening tags carrying this scope id — the only elements the scoped
+  // stylesheet can match. One scan, reused for every subject.
+  const stamped = pageHtml.match(
+    new RegExp(`<[a-zA-Z][\\w-]*[^>]*\\bdata-wd-scope="${scope}"[^>]*>`, "g")
+  );
+  const tags = stamped ?? [];
+  for (const subject of subjects) {
+    if (!subject) continue;
+    const present = tags.some((tag) => subjectMatchesTag(subject, tag));
+    if (present) continue;
+    const warning = `scoped selector "${subject}" in ${skinName} matches no element`;
+    if (warned.has(warning)) continue;
+    warned.add(warning);
+    console.warn(`hint: ${warning}`);
+  }
+}
+
+/**
+ * Whether a scoped subject token (`.card` / `#id` / a bare tag like `h2`) could
+ * match a single stamped opening tag. Class subjects look in the tag's `class`
+ * attribute; id subjects in `id`; a bare tag compares the element name.
+ * @param {string} subject
+ * @param {string} tag A single opening tag string.
+ * @returns {boolean}
+ */
+function subjectMatchesTag(subject, tag) {
+  if (subject.startsWith(".")) {
+    const cls = subject.slice(1);
+    const m = tag.match(/\bclass\s*=\s*"([^"]*)"/);
+    return m ? m[1].split(/\s+/).includes(cls) : false;
+  }
+  if (subject.startsWith("#")) {
+    const m = tag.match(/\bid\s*=\s*"([^"]*)"/);
+    return m ? m[1] === subject.slice(1) : false;
+  }
+  const name = tag.match(/^<([a-zA-Z][\w-]*)/);
+  return name ? name[1].toLowerCase() === subject.toLowerCase() : false;
+}
+
 /**
  * Copy non-page shelf assets (JSON data, media) into `dist/__wd`.
  * @param {Paths} paths

package/src/compiler/context.js

@@ -35,6 +35,10 @@
  * @property {boolean} hasCode Whether the page has a build-time-highlighted code
  *   block, so the framework highlight stylesheet (`/__wd/highlight.css`) is
  *   emitted and linked — pay-for-what-you-use, zero JS.
+ * @property {Set<string>} scopedSkins Source paths of colocated `.skin` files
+ *   that opted into scoping (`scoped` first line). The builder emits these with
+ *   the scope attribute and runs the unused-selector warning against the stamped
+ *   subtree; the HTML stamp uses them to scope the matching page/include subtree.
  */
 
 /**
@@ -144,7 +148,8 @@ export function createCompilation() {
       files: new Map(),
       runtime: false,
       behaviors: new Set(),
-      hasCode: false
+      hasCode: false,
+      scopedSkins: new Set()
     },
     state: new Map(),
     stores: new Set(),

package/src/compiler/directives.js

@@ -12,7 +12,7 @@
 import { compileBody } from "./body.js";
 import { at, createScope, LOOP_META } from "./context.js";
 import { FORMATTERS } from "./format.js";
-import { resolveInclude } from "./includes.js";
+import { resolveInclude, scopedSkinFor } from "./includes.js";
 import {
   escapeHtml,
   getPath,
@@ -26,7 +26,7 @@ import {
   stripQuotes,
   validatePath
 } from "./interpolation.js";
-import { compileFile } from "./page.js";
+import { compileFile, stampScope } from "./page.js";
 import { compileComputedExpr, compileWhen, evalPredicate } from "./predicates.js";
 
 /**
@@ -45,17 +45,23 @@ export function handleInclude(line, ctx, index) {
   if (!match) throw new Error(`Malformed @include in ${at(ctx.file, index)}: ${line}`);
   const target = resolveInclude(match[1], ctx.file, ctx.context);
   const args = parseIncludeArgs(match[2] || "", ctx);
-  const scope = createScope(ctx.scope, args);
+  const childScope = createScope(ctx.scope, args);
   const child = compileFile(
     target,
     ctx.context,
     ctx.stack,
-    scope,
+    childScope,
     ctx.comp,
     ctx.sections,
     ctx.loopItem
   );
-  return child.html;
+  // An include with its OWN scoped colocated skin stamps just its returned
+  // subtree — so a scoped `.card` in the include can't collide with a `.card`
+  // anywhere else on the page, and the scope never leaks to the include's
+  // siblings (only this child HTML is stamped). The CSS rewrite (builder) uses
+  // the same path-derived id, so attribute and stylesheet line up.
+  const scopedSkin = scopedSkinFor(target, ctx.context);
+  return scopedSkin && scopedSkin.scoped ? stampScope(child.html, scopedSkin.scopeId) : child.html;
 }
 
 /**

package/src/compiler/includes.js

@@ -6,6 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { scopeIdFor } from "../skin.js";
 import { pageIncludeExtensions } from "./context.js";
 import { stripQuotes } from "./interpolation.js";
 
@@ -15,6 +16,47 @@ import { stripQuotes } from "./interpolation.js";
  * @typedef {import("./context.js").Compilation} Compilation
  */
 
+/**
+ * Read a `.skin` file's first meaningful line (skipping `//` line comments,
+ * `/* … *\/` block comments, blanks, and decorative dividers — the same skip
+ * rules `compileSkin` applies) to decide whether it opts into scoping. A skin
+ * scopes its selectors ONLY when that first line is exactly `scoped`; otherwise
+ * it is global and untouched. This is the single source for "is this skin
+ * scoped + what is its id", so the CSS rewrite (builder) and the HTML stamp
+ * (page/include) always agree on both.
+ * @param {string} skinPath Absolute path to the colocated `.skin` file.
+ * @param {string} cwd Project root, for the path-based scope id.
+ * @returns {{ scoped: boolean, scopeId: string }}
+ */
+export function scopeInfoForSkin(skinPath, cwd) {
+  const rel = path.relative(cwd, skinPath).replaceAll(path.sep, "/");
+  const scopeId = scopeIdFor(rel);
+  const src = fs.readFileSync(skinPath, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+  for (const raw of src.split("\n")) {
+    const t = raw.trim();
+    if (!t || t.startsWith("//") || !/[A-Za-z0-9]/.test(t)) continue;
+    return { scoped: t === "scoped", scopeId };
+  }
+  return { scoped: false, scopeId };
+}
+
+/**
+ * The scope info for a page/include's OWN colocated `.skin` sibling, or null
+ * when there is no sibling skin. Used by the HTML stamp sites: a route's own
+ * scoped skin → stamp the page body; an include's scoped skin → stamp the
+ * returned subtree. Resolution mirrors `collectColocatedAssets` (same stem,
+ * `.skin` extension).
+ * @param {string} file Absolute path to the page/include source file.
+ * @param {Paths} context
+ * @returns {{ scoped: boolean, scopeId: string } | null}
+ */
+export function scopedSkinFor(file, context) {
+  const ext = path.extname(file);
+  const candidate = `${file.slice(0, -ext.length)}.skin`;
+  if (!fs.existsSync(candidate)) return null;
+  return scopeInfoForSkin(candidate, context.cwd);
+}
+
 /**
  * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
  * @param {string} file
@@ -35,7 +77,12 @@ export function collectColocatedAssets(file, context, assets) {
     const outputExt = assetExt === ".skin" ? ".css" : ".js";
     const publicPath = `/__wd/${folder}/${rel.slice(0, -assetExt.length).replace(/[/.]/g, "_")}${outputExt}`;
     assets.files.set(candidate, publicPath);
-    if (assetExt === ".skin") assets.skins.add(publicPath);
+    if (assetExt === ".skin") {
+      assets.skins.add(publicPath);
+      // Surface "this skin is scoped" so the warning pass (builder) and the HTML
+      // stamp can find the scoped skins among all colocated ones by source path.
+      if (scopeInfoForSkin(candidate, context.cwd).scoped) assets.scopedSkins.add(candidate);
+    }
     if (assetExt === ".js") assets.scripts.add(publicPath);
   }
 }

package/src/compiler/index.js

@@ -20,4 +20,4 @@
 export { parseFrontmatter } from "./frontmatter.js";
 export { escapeHtml } from "./interpolation.js";
 export { loopKeyOf } from "./loops.js";
-export { compileDocument, compilePage, enhanceImages } from "./page.js";
+export { compileDocument, compilePage, enhanceImages, stampScope } from "./page.js";

package/src/compiler/page.js

@@ -12,7 +12,7 @@ import { htmlHasHighlight } from "../highlight.js";
 import { compileBody } from "./body.js";
 import { createCompilation, createScope } from "./context.js";
 import { parseFrontmatter, warnLikelyFrontmatter } from "./frontmatter.js";
-import { collectColocatedAssets, scanMarkdownHints } from "./includes.js";
+import { collectColocatedAssets, scanMarkdownHints, scopedSkinFor } from "./includes.js";
 import { escapeHtml } from "./interpolation.js";
 import { selectMd } from "./markdown.js";
 
@@ -132,7 +132,14 @@ export function compilePage(file, context, options = {}) {
     ? `\n  <script type="speculationrules">{"prerender":[{"where":{"and":[{"href_matches":"/*"},{"not":{"selector_matches":".no-prefetch"}},{"not":{"selector_matches":"[rel~=nofollow]"}}]},"eagerness":"moderate"}]}</script>`
     : "";
 
-  const body = enhanceImages(compiled.html, context);
+  // A route whose OWN colocated skin opted into scoping stamps the whole page
+  // body so its scoped selectors match. Pure compile-time string post-pass (like
+  // enhanceImages) — no runtime, no `data-wd-*` marker, so a static page stays
+  // static. Include-scoped skins are stamped earlier, in handleInclude.
+  const scopedSkin = scopedSkinFor(file, context);
+  const stamped =
+    scopedSkin && scopedSkin.scoped ? stampScope(compiled.html, scopedSkin.scopeId) : compiled.html;
+  const body = enhanceImages(stamped, context);
 
   return {
     meta: compiled.meta,
@@ -192,6 +199,30 @@ export function enhanceImages(html, paths) {
   });
 }
 
+/**
+ * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
+ * half of compile-time scoped styles, mirroring {@link enhanceImages}: a regex
+ * post-pass over assembled HTML, zero runtime JS. Every element start tag that
+ * doesn't already carry a scope attribute gets one, so the scoped stylesheet
+ * (whose selectors end in `[data-wd-scope="<id>"]`) matches inside this subtree
+ * and nowhere else. Void/self-closing tags are stamped too (the attribute is
+ * valid on any element). Closing tags, comments, doctype, and the `<!`/`<?`
+ * families are left alone. A tag that ALREADY has a `data-wd-scope` (e.g. a
+ * nested include with its own scope) keeps its own — first stamp wins.
+ * @param {string} html Subtree HTML to scope.
+ * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
+ * @returns {string}
+ */
+export function stampScope(html, scopeId) {
+  return html.replace(
+    /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g,
+    (tag, name, attrs, slash) => {
+      if (/\bdata-wd-scope\s*=/.test(attrs)) return tag;
+      return `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
+    }
+  );
+}
+
 /**
  * Extract the `src` attribute value from an `<img>` tag, or "" if absent.
  * @param {string} tag

package/src/compiler.js

@@ -22,5 +22,6 @@ export {
   enhanceImages,
   escapeHtml,
   loopKeyOf,
-  parseFrontmatter
+  parseFrontmatter,
+  stampScope
 } from "./compiler/index.js";

package/src/skin.js

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+
 const aliases = new Map([
   ["radius", "border-radius"],
   ["shadow", "box-shadow"],
@@ -19,6 +21,29 @@ function resolveProp(prop, rest) {
   return aliases.get(prop) || prop;
 }
 
+/**
+ * Derive a short, deterministic scope id from a skin's PROJECT-RELATIVE PATH.
+ * Path-based (stable across content edits, unique per component file) and short
+ * enough to read in the emitted CSS (`wd-7c21`). The same path always yields the
+ * same id, so the CSS rewrite (builder) and the HTML stamp (page/include) agree
+ * without sharing state — they just hash the same relative path. The path is
+ * normalized to POSIX separators first so a build is identical on Windows.
+ * @param {string} relPath Skin path relative to the project root (cwd).
+ * @returns {string} The scope id, e.g. `wd-7c21`.
+ */
+export function scopeIdFor(relPath) {
+  const posix = relPath.replaceAll("\\", "/");
+  const hash = crypto.createHash("sha256").update(posix).digest("hex");
+  return `wd-${hash.slice(0, 4)}`;
+}
+
+// Selectors that style the whole page, not a component subtree. In a `scoped`
+// skin they are a mistake: scoping appends an attribute to the *subject* element,
+// so `page`/`body`/`html`/`*`/`::selection` would either become a no-op (no
+// element in the subtree carries the attribute on <body>/<html>) or silently
+// fail to do what the author means. We error and point them at a global skin.
+const PAGE_LEVEL_SELECTORS = new Set(["page", "*", "html", "body", "::selection"]);
+
 /**
  * A nesting frame in the indentation stack.
  * @typedef {object} SkinFrame
@@ -29,10 +54,25 @@ function resolveProp(prop, rest) {
 
 /**
  * Compile indentation-based `.skin` source into CSS.
+ *
+ * Scoping (opt-in): when `opts.scope` is set the skin is compiled in scoped
+ * mode — every selector RULE gets `[data-wd-scope="<id>"]` appended to the
+ * subject of each compound selector, so the stylesheet only ever matches inside
+ * the stamped subtree. Design tokens (`tokens` / `tokens dark` / `tokens [attr]`)
+ * stay GLOBAL on `:root` regardless, so `var(--x)` and dark mode keep working
+ * site-wide. A whole-selector `:global(.x)` escapes scoping. Page-level selectors
+ * (`page`/`*`/`html`/`body`/`::selection`) are a compile error in scoped mode.
+ * Without `opts.scope`, output is byte-identical to before this feature existed.
  * @param {string} source
+ * @param {{ scope?: string, subjects?: Set<string> }} [opts] `scope`: the scope
+ *   id enabling scoped mode. `subjects`: an optional set the compiler fills with
+ *   every scoped subject token (`.card`, `h2`, `#id`) for the unused-selector
+ *   warning, so the caller need not re-parse the source.
  * @returns {string}
  */
-export function compileSkin(source) {
+export function compileSkin(source, opts = {}) {
+  const scope = opts.scope;
+  const subjects = opts.subjects;
   const lines = source
     .replace(/\r\n?/g, "\n")
     .replace(/\/\*[\s\S]*?\*\//g, "") // strip /* … */ block comments (any span)
@@ -47,6 +87,19 @@ export function compileSkin(source) {
     })
     .map((raw) => ({ indent: (raw.match(/^\s*/)?.[0] ?? "").length, text: raw.trim() }));
 
+  // The opt-in marker: `scoped` must be the FIRST meaningful line (the filter
+  // above has already dropped comments, blanks, and dividers). Anywhere else it
+  // is an error — a `scoped` mid-file means the author misread the contract.
+  let start = 0;
+  if (scope && lines.length && lines[0].text === "scoped" && lines[0].indent === 0) {
+    start = 1;
+  }
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i].text === "scoped" && lines[i].indent === 0) {
+      throw new Error('"scoped" must be the first line of a .skin file');
+    }
+  }
+
   /** @type {SkinFrame[]} */
   const stack = [];
   /** @type {string[]} */
@@ -65,7 +118,7 @@ export function compileSkin(source) {
   /** @type {Map<string, string[]>} */
   const attrVars = new Map();
 
-  for (let i = 0; i < lines.length; i++) {
+  for (let i = start; i < lines.length; i++) {
     const { indent, text } = lines[i];
     // Structure decides meaning: a line opens a block (selector) exactly when
     // the next line is indented deeper. Everything else is a declaration.
@@ -119,17 +172,28 @@ export function compileSkin(source) {
       if (text.startsWith("@")) {
         stack.push({ indent, selector: parent ?? null, media: text });
       } else {
+        if (scope) guardPageLevel(text, parent);
         stack.push({ indent, selector: normalizeSelector(text, parent) });
       }
       continue;
     }
 
     const current = stack.at(-1)?.selector || ":root";
+    // A leaf with no enclosing selector lands on `:root` — a page-level write. In
+    // a scoped skin that is the same mistake `guardPageLevel` rejects (and the
+    // place a filtered bare `*`/`page` reset would otherwise leak through to), so
+    // it errors with the same hint instead of emitting a never-matching rule.
+    if (scope && current === ":root") {
+      throw new Error(
+        `page-level declaration "${text}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      );
+    }
     const media = stack.find((frame) => frame.media)?.media;
     const [prop, ...rest] = text.split(/\s+/);
     const cssProp = resolveProp(prop, rest);
     const value = rest.join(" ").replace(/\$([a-zA-Z0-9_-]+)/g, "var(--$1)");
-    const rule = `${current} { ${cssProp}: ${value}; }`;
+    const subject = scope ? scopeSelector(current, scope, subjects) : current;
+    const rule = `${subject} { ${cssProp}: ${value}; }`;
     css.push(media ? `${media} { ${rule} }` : rule);
   }
 
@@ -153,6 +217,86 @@ export function compileSkin(source) {
   return css.join("\n");
 }
 
+/**
+ * Reject page-level selectors in a scoped skin. Checks the AUTHORED selector
+ * text (before `page`→`body` rewrite) so `page` is caught by name. Each
+ * comma-separated part is inspected; a bare top-level selector (no parent) that
+ * is one of the page-level set, or a top-level `::selection`, errors with a hint
+ * pointing the author at a global skin.
+ * @param {string} text Raw selector line.
+ * @param {string | null | undefined} parent Enclosing selector, if nested.
+ * @returns {void}
+ */
+function guardPageLevel(text, parent) {
+  // Only TOP-LEVEL selectors are page-level mistakes — `.card *` (a descendant
+  // wildcard inside a component) is fine, so the check applies when there is no
+  // parent selector chain (`:root` is the implicit root, treated as none).
+  if (parent && parent !== ":root") return;
+  for (const part of text.split(",")) {
+    const clean = part.trim();
+    if (PAGE_LEVEL_SELECTORS.has(clean)) {
+      throw new Error(
+        `page-level selector "${clean}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      );
+    }
+  }
+}
+
+/**
+ * Append the scope attribute to a resolved selector list (post `&`-nesting).
+ * Each comma-separated compound selector gets `[data-wd-scope="<id>"]` on its
+ * SUBJECT (rightmost simple selector), inserted BEFORE any trailing
+ * pseudo-class/element so the result stays valid CSS (`.card[…]:hover`, never
+ * `.card:hover[…]`). A whole-selector `:global(.x)` unwraps to a plain `.x` with
+ * NO attribute — the documented escape hatch (whole-selector only this release).
+ * @param {string} selectorList Resolved selector list (may contain commas).
+ * @param {string} scope Scope id.
+ * @param {Set<string>} [subjects] Optional sink for subject tokens (warning).
+ * @returns {string}
+ */
+function scopeSelector(selectorList, scope, subjects) {
+  return selectorList
+    .split(",")
+    .map((part) => {
+      const clean = part.trim();
+      // Whole-selector `:global(.toast)` → `.toast`, unscoped. Descendant
+      // `:global` (`.card :global(.x)`) is intentionally NOT supported yet.
+      const global = clean.match(/^:global\(\s*(.+?)\s*\)$/);
+      if (global) return global[1];
+      // The subject is the last whitespace-delimited compound. Combinators
+      // (`>`, `+`, `~`) stand as their own tokens, so the subject is whatever
+      // follows the final combinator/descendant gap.
+      const tokens = clean.split(/\s+/);
+      const subjectIndex = tokens.length - 1;
+      const lead = tokens.slice(0, subjectIndex);
+      const subject = tokens[subjectIndex];
+      // Split the subject into its base (tag/class/id, plus attribute selectors)
+      // and any trailing pseudo `:hover` / `::before`. The attribute slots in at
+      // the base/pseudo seam: `.card::before` → `.card[scope]::before`.
+      const seam = subject.search(/::?[a-zA-Z-]/);
+      const base = seam === -1 ? subject : subject.slice(0, seam);
+      const pseudo = seam === -1 ? "" : subject.slice(seam);
+      if (subjects) subjects.add(subjectBase(base));
+      const scoped = `${base}[data-wd-scope="${scope}"]${pseudo}`;
+      return [...lead, scoped].join(" ");
+    })
+    .join(", ");
+}
+
+/**
+ * Reduce a scoped subject base to the single token the unused-selector warning
+ * checks against the stamped subtree: the leading `.class`, `#id`, or bare tag,
+ * dropping any chained attribute selectors (`a[href]` → `a`). Returns `""` for a
+ * subject that has no checkable token (a bare attribute selector), which the
+ * caller treats as "always present" (never warns).
+ * @param {string} base
+ * @returns {string}
+ */
+function subjectBase(base) {
+  const m = base.match(/^([.#]?[A-Za-z_][\w-]*)/);
+  return m ? m[1] : "";
+}
+
 /**
  * Normalize a bracketed token modifier into a valid attribute selector,
  * quoting the value so `[data-theme=dark]` becomes `[data-theme="dark"]`.