@jay-framework/jay-stack-cli 0.24.7 → 0.25.0

package/agent-kit-template/designer/design-system-guide.md

@@ -148,8 +148,8 @@ component's **own** tags, and an optional `<style>` of **plain component CSS**.
 ```
 
 > **Author plain CSS here, not `@scope`.** In the template you write ordinary class rules
-> (`.ds-card { … }`). When a page flattens the element, `sync` copies this CSS into the page and rewrites it
-> into the canonical `@scope (.<ref>)` / `:scope` form for you — that scoped shape is a _page-side_ concern
+> (`.ds-card { … }`). When a page flattens the element, `sync` copies these rules into the page verbatim and
+> wraps them in a canonical `@scope (.<ref>)` block for you — that scoped wrapper is a _page-side_ concern
 > (see [The shape of a region's CSS](#the-shape-of-a-regions-css)); you don't write it in the template.
 
 ### 4. Choose the right axis of variation
@@ -217,7 +217,7 @@ the page's `<style>`, `@scope`-wrapped by the region's `ref`:
 
 ```html
 <jay:card ref="promo" heading="{title}">
-  <div class="card promo">
+  <div class="card">
     <h3 class="card-heading">{heading}</h3>
     <p class="card-body">Default body</p>
   </div>
@@ -226,7 +226,7 @@ the page's `<style>`, `@scope`-wrapped by the region's `ref`:
 
 ```css
 @scope (.promo) {
-  :scope {
+  .card {
     border: 1px solid #ccc;
     padding: 16px;
   }
@@ -236,8 +236,9 @@ the page's `<style>`, `@scope`-wrapped by the region's `ref`:
 }
 ```
 
-Note two things sync did to the CSS — both required for the styles to actually apply. **Write region CSS in
-this shape yourself**; the rules are below in [The shape of a region's CSS](#the-shape-of-a-regions-css).
+The flattened body is the template body **verbatim** — no synthetic class on the root — and the CSS is the
+component's own plain rules wrapped in one `@scope (.<ref>)` block. **Write region CSS in this shape
+yourself**; the rules are below in [The shape of a region's CSS](#the-shape-of-a-regions-css).
 
 > A bare `<jay:X>` with **no** flattened body is a hard error at build time — flatten it with `jay-stack
 sync` (first-fill is just the no-edits case of sync; there is no separate `add` command).
@@ -292,9 +293,9 @@ the second import its own region tag with `as=`:
 
 ## The shape of a region's CSS
 
-A region's CSS is the component's own CSS, copied into the page `<style>` and rewritten into a canonical
-form. `sync` produces this form and `validate` enforces it — but when you **hand-write or edit** a region's
-CSS, write it this way directly:
+A region's CSS is the component's own CSS, copied into the page `<style>` and wrapped in one `@scope` block.
+`sync` produces this form and `validate` enforces it — but when you **hand-write or edit** a region's CSS,
+write it this way directly:
 
 ### 1. Wrap the component's rules in `@scope (.<ref>)`
 
@@ -302,52 +303,47 @@ All of a region's rules live inside one `@scope` block keyed by the region's `re
 
 ```css
 @scope (.promo) {
-  /* …the card's rules… */
+  /* …the card's rules, as plain class selectors… */
 }
 ```
 
 This isolates the component's styles to that region — rules inside never leak out, and page rules outside
 never bleed in.
 
-### 2. The `ref` is a real class on the region root (scope-anchor)
-
-A jay `ref` is not emitted to the DOM, so `@scope (.promo)` would have nothing to match. The region root
-therefore carries the ref **as an actual class** — `<div class="card promo">` above. Keep that class on the
-root when you edit markup; it is what anchors the scope. (validate's drift check ignores this synthetic
-class, so it never shows up as drift.)
+### 2. Write plain class selectors — the ref is _not_ a class on your markup
 
-### 3. The component's own root rule targets `:scope`, not its block class
+A jay `ref` is not emitted to the DOM, so `@scope (.promo)` would have nothing to match. The compiler
+therefore synthesizes a `<div class="promo" style="display: contents">` **scope-anchor wrapper** around the
+region body at build time (DL#206). It is layout-transparent (`display:contents` generates no box) and you
+**never write it, see it in source, or style it** — it exists only so `.promo` has a real element to root at.
 
-This is the one that trips people up. **Inside `@scope (.<ref>) { … }`, a scoped selector matches
-_descendants_ of the scope root only — the scope root element itself is reachable solely through `:scope`.**
-So a rule for the region's own root element must be written as `:scope`, _not_ as the root's class:
+Because the wrapper is the scope root, your real roots are ordinary **descendants** of it. So every rule —
+including the component's own root element — is a **plain class selector**, exactly as authored in the
+template. Keep the template's classes on your markup unchanged; add **no** ref class:
 
 ```css
 @scope (.promo) {
-  :scope {
-    border: 1px solid #ccc;
-  } /* ✅ styles the region root (<div class="card promo">) */
   .card {
     border: 1px solid #ccc;
-  } /* ❌ never matches — .card IS the scope root, not a descendant */
+  } /* ✅ the region root — a plain class selector, matched as a descendant of the wrapper */
   .card-heading {
     color: black;
-  } /* ✅ descendant — plain class selector is correct */
+  } /* ✅ descendant — also a plain class selector */
 }
 ```
 
-Rule of thumb: the component's **root block class** → `:scope`; keep compounds and descendants on that
-class (`.card.active` → `:scope.active`, `.card .card-heading` → `:scope .card-heading`), and leave every
-**descendant/element** selector as its ordinary class.
+> **No `:scope` rewrite.** In the old model the root rule was rewritten to `:scope` and the ref was stamped
+> onto the root as a class. DL#206 removed both: page region CSS is now byte-for-byte the template's plain
+> rules, just wrapped in `@scope (.<ref>)`. `:scope` would now refer to the invisible wrapper — don't use it.
 
-### 4. Instances of the same component coalesce into one block
+### 3. Instances of the same component coalesce into one block
 
 When a page holds several regions flattened from the _same_ template, they share one `@scope` block with a
 selector list — never one duplicated block per `ref`:
 
 ```css
 @scope (.cardStarter, .cardPro) {
-  :scope {
+  .card {
     border: 1px solid #ccc;
   }
   .card-heading {
@@ -359,6 +355,21 @@ selector list — never one duplicated block per `ref`:
 Regions from _different_ templates stay in separate blocks. If you add a second instance by hand, fold its
 ref into the existing block's selector list rather than copying the block.
 
+### 4. A CSS-shipping region must have a `ref` (error)
+
+The `@scope (.<ref>)` anchor is derived from the region's `ref=`. A region whose `template=` ships CSS but
+whose `<jay:X>` tag has **no `ref`** has nothing to scope to — the materialiser cannot wrap the CSS and
+`jay-stack sync` silently drops it. `validate` catches this as a **hard error** (`REGION-CSS-NO-REF`, DL#209):
+
+```
+<jay:card> flattens template="./components/card/card.jay-html" which ships CSS, but the region has no ref=
+— so its CSS cannot be scoped and `jay-stack sync` will silently drop it.
+  → Add a ref= to the <jay:card> so sync can scope its CSS as an @scope (.<ref>) block and preserve it.
+```
+
+Fix it by adding a `ref` — there is no suppression, because the alternative (keeping the CSS unscoped) would
+leak the region's styles across the whole page.
+
 ## Drift: what `jay-stack validate` tells you
 
 Because the copy has a known source (its `template=`), `jay-stack validate` diffs the two and reports each
@@ -490,7 +501,8 @@ CSS reconciles the same way as markup — drift is overwritten, marked facets ar
   never rewritten.
 - A block that **diverges without any pragma** is unmarked CSS drift: `sync` overwrites it back to the
   canonical form, exactly as it re-flattens unmarked markup. (This is what lets `sync` _migrate_ a page to a
-  new canonical form — e.g. an older `.card { … }` root rule is rewritten to `:scope { … }`.)
+  new canonical form — e.g. an older `:scope { … }` / ref-on-root block is rewritten to the DL#206 form:
+  plain class rules wrapped in `@scope (.<ref>)`.)
 
 So after one `sync` a page's CSS is in canonical form, and a `validate`-clean page is one `sync` leaves
 unchanged. To keep a hand-edit through `sync`, mark it with a `jay:override` pragma.

package/agent-kit-template/designer/jay-html-styling.md

@@ -19,12 +19,13 @@ Add `<style>` blocks in `<head>`:
 </head>
 ```
 
-## Styling a design-system region (`@scope` + `:scope`)
+## Styling a design-system region (`@scope`)
 
 CSS for a `<jay:X>` **design-system element** (a region with `template=` provenance) is not written as plain
-page rules — it lives in an `@scope (.<ref>)` block, and the component's own root rule must target `:scope`,
-not its block class (inside `@scope`, a class selector matches descendants of the scope root only). This has
-its own rules and is covered in full in
+page rules — it lives in an `@scope (.<ref>)` block keyed by the region's `ref`. Inside that block you write
+the component's **plain class rules** exactly as authored in the template (`.ds-card { … }`); the compiler
+synthesizes a `display:contents` scope-anchor so `.<ref>` has something to match — you never write it or use
+`:scope`. This has its own rules and is covered in full in
 [design-system-guide.md → The shape of a region's CSS](design-system-guide.md#the-shape-of-a-regions-css).
 The plain-`<style>` patterns on this page apply to ordinary page markup.
 

package/agent-kit-template/designer/validation-guide.md

@@ -27,6 +27,11 @@ So a warning about an `<img>` might come from a full-stack component's template,
 - **Errors** block the build. They must be fixed — there is no way to suppress them.
 - **Warnings** must be either fixed or explicitly suppressed. Do not ignore warnings — each one has a clear resolution path (add the missing attribute, or suppress via `<script type="application/jay-validations">`).
 
+One design-system rule is a **hard error**, not a warning: `REGION-CSS-NO-REF` (DL#209) — a `<jay:X>` region
+whose `template=` ships CSS but which has no `ref=`. Without a `ref` the CSS has no scope anchor, so `sync`
+silently drops it; the fix is to add a `ref` (see `design-system-guide.md` → _The shape of a region's CSS_).
+It is unsuppressible because the alternative would leak the region's styles across the whole page.
+
 ## How to Read Warnings
 
 Each warning has:
@@ -135,10 +140,38 @@ The core `jay-stack validate` emits four warnings that nudge you to reuse UI thr
 
 If a warning comes from dynamic content (`{post.content}`) or a generated file, you can't suppress it in the template. This is a validator limitation — the warning is a false positive. Don't loop trying to fix it.
 
+## Design-system scorecard (metrics to optimize)
+
+Below the warnings, `validate` prints a **report-only scorecard** (DL#207). It is **never** a pass/fail — it
+emits no warnings and never affects the exit code. It turns "prefer design-system elements" from a nudge into
+two numbers you can deliberately raise:
+
+- **Tag coverage** — of every contract tag/ref a page's regions _could_ bind, how many it actually binds.
+- **Design-system coverage %** — what share of a page's DOM elements come from `template=`-backed
+  design-system regions (vs. hand-authored markup). Higher = more of the page is built from the design system.
+- **Reuse** — how many catalogued templates are used **more than once** across the project. A design system
+  whose templates are each used once isn't really a design system.
+
+The healthy target: **most of each page is composed of design-system elements, and each template is reused
+more than once.** When building a page, prefer linking an existing template (raising coverage and reuse) over
+hand-authoring markup.
+
+By default the scorecard prints **one-line totals** for the whole project:
+
+```
+📦 Tag coverage: 100% (43/43 tags used across 10 page(s))
+📊 Design-system scorecard: 80% element coverage (74/92), 2 of 5 catalogued templates reused > 1
+   Run validate -v for per-page details.
+```
+
+Run with `-v` / `--verbose` to expand the **per-page** breakdown (coverage per file, which tags are unused,
+per-template reuse counts, and `⚠ low` flags on pages under 50% coverage).
+
 ## Running Validation
 
 ```bash
-jay-stack validate              # validate all pages
+jay-stack validate              # validate all pages (+ one-line scorecard totals)
+jay-stack validate -v           # add per-page tag coverage + scorecard detail
 jay-stack validate --strict     # treat warnings as errors
 ```
 

package/dist/index.js

@@ -4253,11 +4253,10 @@ function firstColon(decl) {
 }
 function diffBodies(sourceParent, regionParent) {
   const out = [];
-  const ignoreClass = isRegionTag(regionParent) ? readAttr(regionParent, "ref") : void 0;
-  diffChildren([], sourceParent, regionParent, ignoreClass, out);
+  diffChildren([], sourceParent, regionParent, out);
   return out;
 }
-function diffChildren(parentPath, sParent, rParent, ignoreClass, out) {
+function diffChildren(parentPath, sParent, rParent, out) {
   const rSup = isElement(rParent) ? parseOverride(rParent) : NO_SUPPRESSION;
   const sSup = isElement(sParent) ? parseContent(sParent) : NO_SUPPRESSION;
   const sup = unionSuppression(rSup, sSup);
@@ -4280,24 +4279,23 @@ function diffChildren(parentPath, sParent, rParent, ignoreClass, out) {
     if (rc.nodeType !== NodeType.ELEMENT_NODE) continue;
     const re = rc;
     if (isRegionTag(re)) continue;
-    const childIgnoreClass = parentPath.length === 0 ? ignoreClass : void 0;
-    diffElement([...parentPath, i], s2[i], re, childIgnoreClass, out);
+    diffElement([...parentPath, i], s2[i], re, out);
   }
 }
-function diffElement(path2, se, re, ignoreClass, out) {
+function diffElement(path2, se, re, out) {
   const sup = unionSuppression(parseOverride(re), parseContent(se));
   if (sup.all) return;
-  compareAttributes(path2, se, re, sup, ignoreClass, out);
+  compareAttributes(path2, se, re, sup, out);
   compareStyle(path2, se, re, sup, out);
-  diffChildren(path2, se, re, void 0, out);
+  diffChildren(path2, se, re, out);
 }
-function compareAttributes(path2, se, re, sup, ignoreClass, out) {
+function compareAttributes(path2, se, re, sup, out) {
   const sm = attrMap(se);
   const rm = attrMap(re);
   const names = [.../* @__PURE__ */ new Set([...sm.keys(), ...rm.keys()])].sort();
   for (const name of names) {
-    const sv = name === "class" ? stripClassToken(sm.get(name), ignoreClass) : sm.get(name);
-    const rv = name === "class" ? stripClassToken(rm.get(name), ignoreClass) : rm.get(name);
+    const sv = sm.get(name);
+    const rv = rm.get(name);
     const change = scalarChange(sv, rv, (a, b) => normalizeExpr(a) === normalizeExpr(b));
     if (!change) continue;
     const facet = { kind: "attribute", path: path2, element: tagOf(re), name };
@@ -4319,11 +4317,6 @@ function compareStyle(path2, se, re, sup, out) {
       out.push({ facet, change, sourceValue: sv, regionValue: rv });
   }
 }
-function stripClassToken(value, token) {
-  if (value === void 0 || !token) return value;
-  const kept = value.split(/\s+/).filter((t) => t && t !== token);
-  return kept.length ? kept.join(" ") : void 0;
-}
 function scalarChange(sv, rv, equal) {
   if (sv === void 0 && rv === void 0) return void 0;
   if (sv === void 0) return "added";
@@ -4541,7 +4534,7 @@ function coalesceCss(contributions) {
     (g) => g.selectors.length > 0 ? scopeWrap(g.css, g.selectors.join(", "), g.to) : g.css
   ).join("\n\n");
 }
-function fillRegions(container, stack, opts, errors, cssBlocks, parentScoped = false) {
+function fillRegions(container, stack, opts, errors, cssBlocks) {
   for (const region of directRegions(container)) {
     const name = contractName(region);
     const templatePath = opts.resolveTemplate(name);
@@ -4559,15 +4552,11 @@ function fillRegions(container, stack, opts, errors, cssBlocks, parentScoped = f
       );
       continue;
     }
-    const existing = region.innerHTML;
-    const filled = opts.preserveOverrides ? mergeOverrides(template.body, existing) : template.body;
+    const filled = opts.preserveOverrides ? mergeOverrides(template.body, region.innerHTML) : template.body;
     region.set_content(filled);
-    const ref = readAttr(region, "ref");
-    let scoped = false;
     if (template.css) {
       const selector = (opts.scopeSelector ?? defaultScopeSelector)(region);
       if (selector) {
-        scoped = true;
         const to = [
           ...new Set(
             directRegions(region).filter((c) => opts.resolveTemplate(contractName(c)) !== null).map((c) => readAttr(c, "ref")).filter((r) => !!r).map((r) => `.${r}`)
@@ -4576,15 +4565,14 @@ function fillRegions(container, stack, opts, errors, cssBlocks, parentScoped = f
         cssBlocks.push({
           key: `${templatePath}\0${[...to].sort().join(",")}`,
           selector,
-          css: scopeReadyCss(template.body, template.css),
+          css: template.css,
           to
         });
       } else {
         cssBlocks.push({ key: templatePath, selector: null, css: template.css });
       }
     }
-    if (ref && (scoped || parentScoped)) stampScopeAnchor(region, ref);
-    fillRegions(region, [...stack, templatePath], opts, errors, cssBlocks, scoped);
+    fillRegions(region, [...stack, templatePath], opts, errors, cssBlocks);
   }
 }
 function directRegions(container) {
@@ -4612,39 +4600,6 @@ function scopeWrap(css, selector, to) {
 ${css}
 }`;
 }
-function rootClassesOf(templateBody) {
-  const classes = /* @__PURE__ */ new Set();
-  for (const child of parse(templateBody).childNodes) {
-    if (child instanceof HTMLElement) {
-      for (const c of child.classList.values()) classes.add(c);
-    }
-  }
-  return classes;
-}
-function scopeReadyCss(templateBody, css) {
-  const rootClasses = rootClassesOf(templateBody);
-  if (rootClasses.size === 0) return css;
-  try {
-    const root = postcss.parse(css);
-    root.walkRules((rule) => {
-      rule.selectors = rule.selectors.map((sel) => rewriteRootSelector(sel, rootClasses));
-    });
-    return root.toString();
-  } catch {
-    return css;
-  }
-}
-function rewriteRootSelector(selector, rootClasses) {
-  return selector.replace(
-    /\.([A-Za-z0-9_-]+)/g,
-    (match, name) => rootClasses.has(name) ? ":scope" : match
-  );
-}
-function stampScopeAnchor(region, className) {
-  for (const child of region.childNodes) {
-    if (child instanceof HTMLElement) child.classList.add(className);
-  }
-}
 function mergeOverrides(templateBody, existingBody) {
   const tRoot = parse(templateBody);
   const eRoot = parse(existingBody);
@@ -5369,8 +5324,7 @@ function checkRegionCssDrift(jayHtml, loadTemplate) {
       if (content === void 0) {
         templateCss = null;
       } else {
-        const body = parse(content).querySelector("body");
-        templateCss = scopeReadyCss(body ? body.innerHTML : "", extractStyleCss(content));
+        templateCss = extractStyleCss(content);
       }
       templateCssCache.set(imp.template, templateCss);
     }
@@ -5462,6 +5416,33 @@ function checkNestedRegionRefs(jayHtml, loadTemplate) {
   }
   return warnings;
 }
+function checkRegionCssNoRef(jayHtml, loadTemplate) {
+  const importsWithTemplate = jayHtml.headlessImports.filter((imp) => imp.template);
+  if (importsWithTemplate.length === 0) return [];
+  const findings = [];
+  const shipsCssCache = /* @__PURE__ */ new Map();
+  const templateShipsCss = (rel) => {
+    let v = shipsCssCache.get(rel);
+    if (v === void 0) {
+      const content = loadTemplate(rel);
+      v = content !== void 0 && extractStyleCss(content).trim() !== "";
+      shipsCssCache.set(rel, v);
+    }
+    return v;
+  };
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = (region.rawTagName ?? "").toLowerCase().substring(4);
+    const imp = importsWithTemplate.find((i) => i.contractName === contractName2);
+    if (!imp?.template) continue;
+    if (region.getAttribute("ref")) continue;
+    if (!templateShipsCss(imp.template)) continue;
+    findings.push({
+      message: `<jay:${contractName2}> flattens template="${imp.template}" which ships CSS, but the region has no ref= — so its CSS cannot be scoped and \`jay-stack sync\` will silently drop it.`,
+      suggestion: `Add a ref= to the <jay:${contractName2}> so sync can scope its CSS as an @scope (.<ref>) block and preserve it.`
+    });
+  }
+  return findings;
+}
 const CONTENT_TAGS = /* @__PURE__ */ new Set([
   // inline text semantics
   "span",
@@ -5888,6 +5869,9 @@ async function validateJayFiles(options = {}) {
   const parsedFiles = [];
   let regionsSeen = 0;
   let templateImportsSeen = 0;
+  const designSystemCoverage = [];
+  const reuseByTemplate = /* @__PURE__ */ new Map();
+  const cataloguedContractFiles = /* @__PURE__ */ new Set();
   const pageJayHtmlFiles = await findJayFiles(scanDir);
   const componentJayHtmlFiles = await findJayFiles(componentsDir).catch(() => []);
   const jayHtmlFiles = [...pageJayHtmlFiles, ...componentJayHtmlFiles];
@@ -5895,6 +5879,7 @@ async function validateJayFiles(options = {}) {
   const componentContractFiles = await findContractFiles(componentsDir).catch(
     () => []
   );
+  for (const cf of componentContractFiles) cataloguedContractFiles.add(cf);
   const contractFiles = [...await findContractFiles(scanDir), ...componentContractFiles];
   const contractNameByFile = /* @__PURE__ */ new Map();
   if (options.verbose) {
@@ -6044,10 +6029,45 @@ async function validateJayFiles(options = {}) {
           suggestion: finding.suggestion
         });
       }
+      const cssNoRefErrors = checkRegionCssNoRef(parsedFile.val, readTemplateRel);
+      for (const finding of cssNoRefErrors) {
+        errors.push({
+          file: relativePath,
+          message: finding.message,
+          stage: "generate",
+          suggestion: finding.suggestion
+        });
+      }
       regionsSeen += collectRegionElements(parsedFile.val.body).length;
       templateImportsSeen += parsedFile.val.headlessImports.filter(
         (imp) => imp.template
       ).length;
+      if (!componentJayHtmlFileSet.has(jayFile)) {
+        const body = parsedFile.val.body;
+        const total = body.querySelectorAll("*").length;
+        const coveredNodes = /* @__PURE__ */ new Set();
+        for (const region of directChildRegions(body)) {
+          const contractName2 = regionContractName(region);
+          const imp = parsedFile.val.headlessImports.find(
+            (i) => i.contractName === contractName2
+          );
+          if (!imp?.template) continue;
+          coveredNodes.add(region);
+          for (const descendant of region.querySelectorAll("*")) {
+            coveredNodes.add(descendant);
+          }
+          const templateAbs = path$1.resolve(dirname, imp.template);
+          reuseByTemplate.set(templateAbs, (reuseByTemplate.get(templateAbs) ?? 0) + 1);
+          if (imp.contractPath) cataloguedContractFiles.add(imp.contractPath);
+        }
+        const covered = coveredNodes.size;
+        designSystemCoverage.push({
+          file: relativePath,
+          coveragePct: total ? covered / total : 0,
+          covered,
+          total
+        });
+      }
       const notLinkedWarnings = componentJayHtmlFileSet.has(jayFile) ? [] : checkRegionNotLinked(
         parsedFile.val,
         (imp) => listTemplatesForContractFile(imp.contractPath).map((t) => ({
@@ -6198,6 +6218,23 @@ async function validateJayFiles(options = {}) {
       suggestion: noDesignSystem.suggestion
     });
   }
+  const cataloguedTemplatePaths = /* @__PURE__ */ new Set();
+  for (const contractFile of cataloguedContractFiles) {
+    for (const t of listTemplatesForContractFile(contractFile)) {
+      cataloguedTemplatePaths.add(path$1.resolve(t.path));
+    }
+  }
+  const rel = (p) => "./" + path$1.relative(projectRoot, p).replace(/\\/g, "/");
+  const perTemplate = {};
+  for (const [abs, count] of reuseByTemplate) perTemplate[rel(abs)] = count;
+  const designSystemReuse = {
+    perTemplate,
+    catalogued: cataloguedTemplatePaths.size,
+    reusedMoreThanOnce: [...reuseByTemplate.values()].filter((n) => n >= 2).length,
+    reusedOfCatalogued: [...cataloguedTemplatePaths].filter(
+      (p) => (reuseByTemplate.get(p) ?? 0) >= 2
+    ).length
+  };
   const pluginValidators = await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
   return {
     valid: errors.length === 0,
@@ -6206,7 +6243,9 @@ async function validateJayFiles(options = {}) {
     errors,
     warnings,
     coverage,
-    pluginValidators
+    pluginValidators,
+    designSystemCoverage,
+    designSystemReuse
   };
 }
 function printJayValidationResult(result, options) {
@@ -6280,23 +6319,84 @@ function printJayValidationResult(result, options) {
       }
     }
   }
-  if (options.verbose && result.coverage.length > 0) {
-    logger.important("");
-    logger.important(chalk.bold("📦 Tag Coverage"));
-    for (const fileCov of result.coverage) {
-      logger.important(`   ${fileCov.file}`);
-      for (const contract of fileCov.contracts) {
-        const label = contract.key ? `${contract.key} (${contract.contractName})` : contract.contractName;
-        logger.important(
-          `     ${label}: ${contract.usedTags}/${contract.totalTags} tags used`
-        );
-        if (contract.unusedTags.length > 0) {
+  const { designSystemCoverage, designSystemReuse } = result;
+  const reuseTemplates = Object.keys(designSystemReuse.perTemplate);
+  const hasTagCoverage = result.coverage.length > 0;
+  const hasScorecard = designSystemCoverage.length > 0 || reuseTemplates.length > 0;
+  let totalUsedTags = 0;
+  let totalTags = 0;
+  for (const fileCov of result.coverage) {
+    for (const contract of fileCov.contracts) {
+      totalUsedTags += contract.usedTags;
+      totalTags += contract.totalTags;
+    }
+  }
+  let totalCovered = 0;
+  let totalElements = 0;
+  for (const cov of designSystemCoverage) {
+    totalCovered += cov.covered;
+    totalElements += cov.total;
+  }
+  if (options.verbose) {
+    if (hasTagCoverage) {
+      logger.important("");
+      logger.important(chalk.bold("📦 Tag Coverage"));
+      for (const fileCov of result.coverage) {
+        logger.important(`   ${fileCov.file}`);
+        for (const contract of fileCov.contracts) {
+          const label = contract.key ? `${contract.key} (${contract.contractName})` : contract.contractName;
           logger.important(
-            chalk.gray(`       Unused: ${contract.unusedTags.join(", ")}`)
+            `     ${label}: ${contract.usedTags}/${contract.totalTags} tags used`
           );
+          if (contract.unusedTags.length > 0) {
+            logger.important(
+              chalk.gray(`       Unused: ${contract.unusedTags.join(", ")}`)
+            );
+          }
         }
       }
     }
+    if (hasScorecard) {
+      logger.important("");
+      logger.important(chalk.bold("📊 Design-system scorecard"));
+      for (const cov of designSystemCoverage) {
+        const pct = Math.round(cov.coveragePct * 100);
+        const lowFlag = pct < 50 ? chalk.yellow("  ⚠ low") : "";
+        logger.important(
+          chalk.gray(
+            `   Coverage: ${cov.file}  ${pct}%  (${cov.covered}/${cov.total} elements)`
+          ) + lowFlag
+        );
+      }
+      if (reuseTemplates.length > 0) {
+        const parts = reuseTemplates.map((t) => {
+          const n = designSystemReuse.perTemplate[t];
+          return n < 2 ? `${t} ×${n}${chalk.yellow(" ⚠ single-use")}` : `${t} ×${n}`;
+        });
+        logger.important(chalk.gray(`   Reuse: ${parts.join("   ")}`));
+      }
+      logger.important(
+        chalk.gray(
+          `   ${designSystemReuse.reusedOfCatalogued} of ${designSystemReuse.catalogued} catalogued templates reused > 1`
+        )
+      );
+    }
+  } else if (hasTagCoverage || hasScorecard) {
+    logger.important("");
+    if (hasTagCoverage) {
+      const pct = totalTags ? Math.round(totalUsedTags / totalTags * 100) : 0;
+      logger.important(
+        chalk.bold("📦 Tag coverage: ") + `${pct}% (${totalUsedTags}/${totalTags} tags used across ${result.coverage.length} page(s))`
+      );
+    }
+    if (hasScorecard) {
+      const pct = totalElements ? Math.round(totalCovered / totalElements * 100) : 0;
+      const lowFlag = pct < 50 ? chalk.yellow("  ⚠ low") : "";
+      logger.important(
+        chalk.bold("📊 Design-system scorecard: ") + `${pct}% element coverage (${totalCovered}/${totalElements}), ${designSystemReuse.reusedOfCatalogued} of ${designSystemReuse.catalogued} catalogued templates reused > 1` + lowFlag
+      );
+    }
+    logger.important(chalk.gray("   Run validate -v for per-page details."));
   }
   logger.important("");
   if (result.valid && result.warnings.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.24.7",
+  "version": "0.25.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -25,17 +25,17 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@jay-framework/compiler-inline-composition": "^0.24.5",
-    "@jay-framework/compiler-jay-html": "^0.24.7",
-    "@jay-framework/compiler-shared": "^0.24.7",
-    "@jay-framework/dev-server": "^0.24.7",
-    "@jay-framework/fullstack-component": "^0.24.7",
-    "@jay-framework/logger": "^0.24.7",
-    "@jay-framework/plugin-validator": "^0.24.7",
-    "@jay-framework/production-build": "^0.24.7",
-    "@jay-framework/production-server": "^0.24.7",
-    "@jay-framework/stack-server-build": "^0.24.7",
-    "@jay-framework/stack-server-runtime": "^0.24.7",
+    "@jay-framework/compiler-inline-composition": "^0.25.0",
+    "@jay-framework/compiler-jay-html": "^0.25.0",
+    "@jay-framework/compiler-shared": "^0.25.0",
+    "@jay-framework/dev-server": "^0.25.0",
+    "@jay-framework/fullstack-component": "^0.25.0",
+    "@jay-framework/logger": "^0.25.0",
+    "@jay-framework/plugin-validator": "^0.25.0",
+    "@jay-framework/production-build": "^0.25.0",
+    "@jay-framework/production-server": "^0.25.0",
+    "@jay-framework/stack-server-build": "^0.25.0",
+    "@jay-framework/stack-server-runtime": "^0.25.0",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -46,7 +46,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.24.7",
+    "@jay-framework/dev-environment": "^0.25.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",