@reqvire-org/ads 0.3.17 → 0.3.20

package/dist/skills/ads-motion/references/layers.md

@@ -0,0 +1,123 @@
+# Components, patterns and application adapters
+
+Read this when choosing an owner, moving UI between layers, or resolving
+`component-dependency`, `component-contract`, `component-style`, `no-app-import`
+or `showcase-import`. MCP also serves this guide as `ads://guides/layers`.
+
+## Choose by responsibility
+
+A **component** provides one cohesive UI capability: semantics, input handling,
+focus, accessibility, states and appearance. It may compose other components and
+controllers. A notification using an icon, action button and spinner can still
+be one component.
+
+A **pattern** arranges capabilities and content slots into a reusable structure
+or workflow, such as navigation with search/account controls or a report screen.
+Layout parts may arrange `children` without importing several components.
+Patterns may compose other patterns. A native wrapper or a large implementation
+does not decide the layer.
+
+An **application adapter** supplies domain data, store access, route state and
+navigation/service callbacks. Domain-shaped inputs are valid in project-owned
+patterns; importing a particular application store/router is not.
+
+A **scenario** supplies demonstration inputs, local state and simulated services.
+A component scenario may compose several public components and development review helpers
+to demonstrate its subject. That does not turn its fixture or variant selectors
+into production API. Keep `covers` aligned with the scenario's subject layer.
+
+Do not classify by import count, JSX element count, names or file length. Review
+the capability and its consumer contract. Preserve valid APIs when tracing is
+inconclusive; do not make an export private or add a product prop just to pass.
+
+## Demonstrate the production implementation
+
+Product patterns are reusable application UI, not showcase replicas. A scenario
+imports the same production owner and supplies fixtures through its public API;
+the application supplies live data and callbacks to that API. Keep mock records,
+demo selections and simulated services in development files. Legitimate defaults,
+control labels and the pattern's own interaction logic remain with their owner.
+
+Demo framing must not replace a product pattern's styling or behavior. Browser
+checks should exercise both the demonstrated contract and relevant application
+integration; a successful showcase does not establish production parity. A new
+pattern need not already have an application consumer, and import counts cannot
+detect a duplicated implementation. Existing import guards prevent fixture/test
+dependencies; review and browser checks must assess hardcoded mock data and
+unrepresentative rendering that source ownership alone cannot prove.
+
+Review framing belongs in development-only `review/`, not production patterns.
+Use the separate review entry and [review.md](review.md) for the migration and
+build contract.
+
+## Dependency contracts (blocking)
+
+- Component runtime may depend on components, shared controllers and lower-level
+  helpers. It cannot depend on patterns or composition, including indirectly
+  through aliases, forwarding exports, helpers or literal dynamic imports.
+  Type-only pattern references do not introduce runtime dependencies.
+- Patterns consume component symbols published by the configured public entry,
+  including intentional public types. A relative import of a public symbol is
+  allowed inside the ADS; requiring a self-import through the barrel can create
+  cycles. Private state, class blocks and implementation helpers stay internal.
+  A public component may use its own private implementation dependencies.
+- Runtime code cannot import review implementations/types/styles, scenarios, fixtures or checks, including through
+  forwarding exports. Scenarios also cannot import application source.
+- ADS implementations receive application data/effects through inputs and
+  callbacks. Re-exporting application stores, routers or services from a helper
+  does not make them part of the ADS.
+
+For example, `components/Control → shared/helper → patterns/Navigation` fails
+`component-dependency`. Extract a lower-level capability/controller, or move the
+arrangement to a pattern. `patterns/Navigation → components/Control` is valid
+when `Control` is public. Replacing that import with its private state helper
+fails `component-contract` even through a forwarding module.
+
+## Styling contracts (blocking when ownership is established)
+
+Components own their control states and appearance. Patterns own arrangement,
+spacing and their own presentation. Use typed component props/variants, an
+intentional public class helper/hook, or registered non-state customization
+variables. Registration does not authorize overriding interaction policy.
+
+```tsx
+// Component-owned implementation; the marker is not a consumer styling API.
+function Control() {
+  return <button><span className="control-private-label">Label</span></button>;
+}
+
+// Pattern: rejected because it styles the component's private rendered part.
+const wrong = css`
+  & .control-private-label { color: var(--text-muted); }
+`;
+
+// Pattern: its own arrangement remains valid.
+const layout = css`
+  display: flex;
+  gap: var(--space-4);
+`;
+```
+
+The source guard matches component-emitted class names and unambiguous literal
+data markers to the selector's styled subject, including `:is()`/`:where()`.
+It also rejects reads of known private component variables. It does not treat
+an ancestor predicate or `:has()` query as styling that ancestor/descendant:
+`[data-layout="expanded"] > & { gap: var(--space-4); }` changes the pattern's
+own arrangement. Public hooks and registered non-state variables remain valid.
+Token definitions, namespaces and writes retain their existing guards.
+
+Opaque/computed imports, generated selectors, ambiguous shared markers, forwarded
+consumer classes and arbitrary service abstractions are not a complete static
+proof. Passing source checks does not prove that every visual override is safe.
+Review the real rendered states, computed styles, keyboard interactions and
+responsive layouts; use registered browser checks for promised behavior.
+
+## Refactoring an owner
+
+Move runtime source, its scenarios/fixtures and guides together; update public
+exports, dependent imports and documented scenario IDs. Keep callers on the
+same intentional public API. Navigation stays in an application callback or a
+normal link supplied by the consumer, rather than a hidden router mutation in
+the pattern. Validate the complete migration with project checks, product and
+preview builds, and behavior tests. An existing guard rejection is not permission
+to write around the guarded editing workflow.

package/dist/skills/ads-motion/references/motion-review.md

@@ -0,0 +1,35 @@
+# Review motion
+
+Read the item's local README before treating a choice as accidental. Compare
+the source state machine with actual rendered behavior when a browser is
+available. Mark source-only conclusions and untested performance hypotheses.
+
+Assess the following where applicable:
+
+| Area | Look for |
+|------|----------|
+| Purpose/frequency | A clear relationship to the action; repeated work is not slowed |
+| Easing | Entry decelerates naturally; continuous movement and elapsed-time motion use suitable curves |
+| Timing | Feedback starts promptly; total choreography fits its distance and task |
+| Origin/distance | Placement and scale point to the real trigger without excessive travel |
+| Continuity | Reversal and repeated updates retarget without snapping or restarting |
+| Lifecycle | Exit, cancellation, unmount, and zero-duration states clean up correctly |
+| Accessibility | Motion preference, focus, hidden content, and keyboard behavior remain correct |
+| Ownership | Motion uses tokens and owner styles; consumers do not override internals |
+| Cost | Measured rendering work matches the problem; no per-frame work is assumed harmless |
+
+The upstream guidance favors short transitions, restrained scale, and transform/
+opacity. Apply those as defaults with context. A documented 400 ms stack,
+measured height transition, or necessary loading loop is not inherently broken.
+Likewise, a transition below 300 ms is not automatically good. Verify whether an
+exception preserves the intended experience and has acceptable observed cost.
+
+Present only actionable findings. Include file/line, trigger, observed behavior,
+expected behavior, why the difference matters, and a concrete owner-level fix.
+For timing/easing proposals, name the current and proposed token policy and its
+scope. If a token is shared, identify affected neighbors before changing values.
+
+Use a before/after/why comparison for implemented fixes. Separate behavior
+defects, visual refinements, and profiling questions so a suspicion is not
+reported as a proved performance failure. If no defect is found, say what was
+checked and what remains unverified. Do not invent findings to fill a checklist.

package/dist/skills/ads-motion/references/review.md

@@ -1,35 +1,96 @@
-# Review motion
-
-Read the item's local README before treating a choice as accidental. Compare
-the source state machine with actual rendered behavior when a browser is
-available. Mark source-only conclusions and untested performance hypotheses.
-
-Assess the following where applicable:
-
-| Area | Look for |
-|------|----------|
-| Purpose/frequency | A clear relationship to the action; repeated work is not slowed |
-| Easing | Entry decelerates naturally; continuous movement and elapsed-time motion use suitable curves |
-| Timing | Feedback starts promptly; total choreography fits its distance and task |
-| Origin/distance | Placement and scale point to the real trigger without excessive travel |
-| Continuity | Reversal and repeated updates retarget without snapping or restarting |
-| Lifecycle | Exit, cancellation, unmount, and zero-duration states clean up correctly |
-| Accessibility | Motion preference, focus, hidden content, and keyboard behavior remain correct |
-| Ownership | Motion uses tokens and owner styles; consumers do not override internals |
-| Cost | Measured rendering work matches the problem; no per-frame work is assumed harmless |
-
-The upstream guidance favors short transitions, restrained scale, and transform/
-opacity. Apply those as defaults with context. A documented 400 ms stack,
-measured height transition, or necessary loading loop is not inherently broken.
-Likewise, a transition below 300 ms is not automatically good. Verify whether an
-exception preserves the intended experience and has acceptable observed cost.
-
-Present only actionable findings. Include file/line, trigger, observed behavior,
-expected behavior, why the difference matters, and a concrete owner-level fix.
-For timing/easing proposals, name the current and proposed token policy and its
-scope. If a token is shared, identify affected neighbors before changing values.
-
-Use a before/after/why comparison for implemented fixes. Separate behavior
-defects, visual refinements, and profiling questions so a suspicion is not
-reported as a proved performance failure. If no defect is found, say what was
-checked and what remains unverified. Do not invent findings to fill a checklist.
+# Development-only review UI
+
+Read this when creating or migrating demo frames, preview sizing helpers, token
+renderers or demonstration controls. MCP serves it as `ads://guides/review`.
+
+## Responsibilities and boundaries
+
+Components provide cohesive production capabilities. Patterns provide reusable
+application structures/workflows. Both receive variable application data and
+callbacks through their APIs. Their scenarios import the same implementation
+used by the application and supply fixtures; do not create a second implementation
+that only looks correct in the showcase.
+
+`design-system/review/` owns development-only presentation: example frames,
+arrangement, demonstration controls, token sample renderers and their styles.
+It remains project-owned. The MCP host shell stays generic; review code executes
+inside the preview App with the project's framework, foundation, fonts and styles.
+Nothing depends on particular helper names or an imported component library.
+
+The development entry defaults to `review/index.ts` relative to `dsDir`; configure
+`reviewEntry` for another script inside `review/`. Its import alias is the
+configured `publicAlias` plus `/review`, normally `@ds/review`. Discover the actual
+entry/alias through `ads_status.project.review`. Export helpers there, never from
+the production public barrel. Review implementations, types and styles must not
+enter application, component, pattern or controller dependencies. Tests, fixtures,
+scenarios and preview mounts can consume review code.
+
+Review helpers can own Linaria presentation, local state and demo controls. Normal
+style-token, variable ownership, measured-style-write and application separation
+gates still apply. They consume deliberate public component/pattern/controller
+contracts and may reuse local foundation helpers. They cannot target private
+component styles or replace real product behavior. Keep one-off fixture data in
+the scenario; a helper need not become a product API to frame an example.
+
+## Scenario and token contracts
+
+```tsx
+import { Panel } from "@ds";
+import { ReviewFrame } from "@ds/review";
+import { fixture } from "./Panel.fixture";
+
+export const scenario = { title: "Panel", covers: ["Panel"] };
+export default function Scenario() {
+  return <ReviewFrame><Panel {...fixture} /></ReviewFrame>;
+}
+```
+
+The names above are illustrative. `covers` names the production subjects actually
+demonstrated, not every review wrapper. A review export has no product catalogue
+entry and needs no standalone catalogue scenario. Keep review unit tests/specs
+beside their owner; optional behavior contracts can verify review guarantees
+through an existing real scenario. They establish no production coverage.
+
+A token scenario may name its real review renderer in `covers`, import it from
+the development entry, declare `samples: fixture.samples`, and pass those samples
+into the renderer. Existing real product patterns may also serve as token UI.
+Empty covers, unused samples, fabricated tokens and plain value lists remain
+invalid. The rendered App must still pass token-binding checks. See
+[scenarios.md](scenarios.md) for the full token/render contract.
+
+Review class helpers can supply source-proven Linaria classes to a scenario.
+Arbitrary scenario classes/styles remain forbidden. A review wrapper's own native
+controls do not authorize arbitrary native controls in its consuming scenario;
+slot/selector exceptions still need actual production-owner evidence. Keep
+production and review export names distinct where `covers` would be ambiguous.
+
+## Build and guarded edits
+
+The normal preview plugin registers the exact review alias before broader product
+aliases. Configure the same alias in project TypeScript and any independent
+preview/dev harness. In an ordered bundler alias map, put `@ds/review` before
+`@ds`; the broad `@ds` mapping must not resolve it as `index.ts/review`.
+Production entrypoints never import the development entry. Inspect the product
+bundle for review modules/CSS; passing static checks does not prove bundle parity.
+
+Use `ads_units` for `review/<Owner>` units. Scenarios, local specs and helper files
+follow ordinary flat/directory ownership. A review patch may update only its own
+re-exports in the development entry and its own documented style boundaries.
+Product owners retain the separate production entry companion. Use prepared
+patches/dry runs and coupled transactions as described in
+[guarded-editing.md](guarded-editing.md); do not bypass a rejected mutation.
+
+For an existing project, identify helpers by responsibility and actual consumers,
+not names or the number of imported components. Preserve real application patterns.
+Move only demo helpers, their styles and relevant guides to `review/`; update
+scenario/preview imports, style-boundary paths, TypeScript/bundler aliases and
+links. Remove their production exports and obsolete standalone product scenarios.
+Do not copy old example fixtures or export demonstration controls as product UI.
+
+Upgrade ADS before migrating a consuming project: older versions do not know the
+separate review entry. For staged guarded edits, first add distinctly named review
+exports, migrate consumers in passing owner patches, then remove the old pattern
+exports/owners once unused. Required coupled changes use a transaction. Check
+source gates, typecheck, preview and production builds, real browser rendering,
+registered behaviors and token bindings. A source move alone establishes none
+of those rendered guarantees.

package/dist/skills/ads-motion/references/scenarios.md

@@ -34,10 +34,31 @@ do not add scenario `preventDefault` handlers merely to hide it. Explicit App
 bases retain their declared behavior and CSP requirements; external hosts own
 their document-loading policy. Verify link activation as well as rendering.
 
+## Forms inside Apps
+
+Use real form semantics and the runtime owner's intended submit handler. ADS's
+showcase and diagnostic explorer permit `allow-forms` at every iframe layer,
+including legacy widgets. Browser constraint validation, Submit clicks, Enter and
+`requestSubmit()` can reach the normal submit path. Client-side forms call
+`preventDefault()` in their submit handlers; the host does not synthesize clicks
+or submit events. Native action requests are blocked by CSP `form-action 'none'`.
+Submit effects that use tools or resources still follow the MCP bridge.
+
+If a click fires but the `submit` handler never runs, inspect the browser's sandbox
+diagnostic and every ancestor iframe's permissions. Distinguish that host problem
+from native constraint validation legitimately preventing submission. Do not add
+scenario click interception to disguise a missing sandbox permission. External
+MCP hosts control their own sandbox/CSP policy.
+
+Verify an invalid submit, a valid submit, implicit Enter submission and the promised
+state effects. A working Next button is not evidence that form submission works.
+Keep native action navigation separate from client-side submission behavior;
+`allow-forms` does not grant host DOM access or top-level navigation.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
-A colocated `kind: "tokens"` scenario may render only the public review pattern
+A colocated `kind: "tokens"` scenario may render only the development-only review renderer
 with its fixture samples. Discovery adds the registered owner sheet to the
 generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
 into the token preview independently of the runtime component. Custom builders
@@ -91,7 +112,7 @@ These examples describe verification mistakes, not component-specific rules:
 
 | Situation | Do not | Do instead |
 |-----------|--------|------------|
-| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's development-only review helper or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
 | Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
 | A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
 
@@ -207,6 +228,6 @@ An `exercises` entry records behavioral use; it never grants styling permission.
 Keep helper signatures compatible with the product API. Fix ownership/provenance
 in the runtime owner when genuinely wrong; retain intentional public APIs when
 reporting an unsupported trace. Demo-only sizing, framing and arrangement still
-belong in public review/layout patterns. A style helper is not permission to
+belong in development-only review helpers. A style helper is not permission to
 author a second design in the scenario. For cascade risks and extraction issues,
 read [atomic-styles.md](atomic-styles.md).

package/dist/units.mjs

@@ -25,7 +25,7 @@ export function configurationFiles(options) {
     // fixtures to configuration. Those remain in the behavior owner's patch.
     if (isInside(dsRoot, file) && isDevelopmentFile(file, options)) return;
     if (!entrypoint && isInside(sourceRoot, file) && !isInside(dsRoot, file)) return;
-    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|controllers|composition|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
+    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|controllers|composition|review|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
       if (isInside(path.join(dsRoot, "controllers"), file) || isDevelopmentFile(file, options)) return;
       const folder = path.dirname(file), stem = path.basename(file).split(".")[0];
       const anchored = ["index", path.basename(folder)].some(name => [".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"].some(extension => existsSync(path.join(folder, name + extension))));
@@ -102,30 +102,31 @@ export function inspectUnits(options) {
   const directories = new Set(files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))));
   for (const file of files.filter(file => /^(?:components|patterns)\/.+\/tokens\.json$/.test(file))) directories.add(path.posix.dirname(file));
   for (const file of files) {
-    if (!/^(?:components|patterns|controllers|composition)\//.test(file) || !source.test(file)) continue;
+    if (!/^(?:components|patterns|controllers|composition|review)\//.test(file) || !source.test(file)) continue;
     const directory = slash(path.dirname(file)), name = path.basename(file).replace(source, "");
     if (!directory.includes("/") || /\.(?:scenario|fixture|scenario-adapter)$/.test(name)) continue;
     if (flatFamilies.has(directory)) continue;
     if (name === "index" || sameName(name) === sameName(path.posix.basename(directory)) || name === "fixture") directories.add(directory);
   }
   const directoryUnits = [...directories].sort((a, b) => b.length - a.length);
-  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|controllers|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
+  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|controllers|composition|review)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
     const base = path.basename(file).split(".")[0];
     return slash(path.join(path.dirname(file), base));
   }))].sort((a, b) => b.length - a.length);
   const publicEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.publicEntry)));
+  const reviewEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.reviewEntry)));
   const tokenDir = slash(path.relative(dsRoot, path.join(dsRoot, config.tokenDir)));
   const stylesEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.stylesEntry)));
   function owner(relative) {
     const projectFile = slash(path.relative(root, path.resolve(dsRoot, relative)));
     if (setup.has(projectFile)) return "configuration";
     if (!isInside(dsRoot, path.resolve(dsRoot, relative))) return isProjectDocument(projectFile) ? "documentation" : null;
-    if (relative === publicEntry) return null; // Controlled re-export bookkeeping.
+    if (relative === publicEntry || relative === reviewEntry) return null; // Controlled re-export bookkeeping.
     if (relative.startsWith(tokenDir + "/")) return "tokens";
     if (relative.startsWith("assets/")) return relative.split("/").length > 2 ? relative.split("/").slice(0, 2).join("/") : "assets";
     if (isProjectDocument(relative)) return "documentation";
     if (!relative.includes("/")) return /(?:\.(?:md|txt)$|^LICENSE$)/i.test(relative) ? "documentation" : "foundation";
-    if (!/^(?:components|patterns|controllers|composition)\//.test(relative)) return relative.split("/")[0] === "documentation" ? null : relative.split("/")[0];
+    if (!/^(?:components|patterns|controllers|composition|review)\//.test(relative)) return relative.split("/")[0] === "documentation" ? null : relative.split("/")[0];
     for (const directory of directoryUnits) if (relative.startsWith(directory + "/")) return directory;
     for (const unit of flatUnits) if (relative.startsWith(unit + "/") || relative.startsWith(unit + ".")) return unit;
     const base = path.basename(relative).split(".")[0];
@@ -146,22 +147,23 @@ export function inspectUnits(options) {
     if (!units.get(id).files.includes(file)) units.get(id).files.push(file);
   }
   for (const unit of units.values()) if (boundaryCompanion(unit.id)) {
+    if (unit.id.startsWith("review/")) (unit.companionFiles ??= []).push({ path: slash(path.relative(root, path.join(dsRoot, reviewEntry))), allowedChanges: "Only this review owner's re-exports in the separate development entry; never the production public entry." });
     (unit.companionFiles ??= []).push({ path: "ds.config.json", allowedChanges: "Only this owner's inlineStyleFiles and boundaries.styleWrites entries, together with its source change; preserve all other configuration and peer permissions." });
-    if (/^(?:components|patterns|controllers|composition)\//.test(unit.id)) {
+    if (/^(?:components|patterns|controllers|composition|review)\//.test(unit.id)) {
       for (let directory = unit.id; directory !== "."; directory = path.posix.dirname(directory)) {
         const marker = path.join(dsRoot, directory, ".gitkeep");
         if (existsSync(marker) && readFileSync(marker).length === 0) (unit.companionFiles ??= []).push({ path: slash(path.relative(root, marker)), allowedChanges: "Delete this empty placeholder only while adding real source in the selected owner below it." });
       }
     }
   }
-  return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, stylesEntry, tokenDir,
+  return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, reviewEntry, stylesEntry, tokenDir,
     relative: file => slash(path.relative(dsRoot, path.resolve(root, file))) };
 }
 
 function boundaryCompanion(unit) { return !["configuration", "documentation", "assets"].includes(unit.split("/")[0]); }
 
 export function validateUnitId(unit) {
-  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "controllers", "composition"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
+  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "controllers", "composition", "review"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
 }
 
 /** Reject arbitrary file batches, even when every path is inside the ADS. */
@@ -171,7 +173,7 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
     const relative = inventory.relative(change.path);
     if (path.posix.basename(relative) === ".gitkeep") {
       const directory = path.posix.dirname(relative);
-      if (change.originalContent !== "" || change.content !== null || !/^(?:components|patterns|controllers|composition)\//.test(relative)
+      if (change.originalContent !== "" || change.content !== null || !/^(?:components|patterns|controllers|composition|review)\//.test(relative)
         || !(unit === directory || unit.startsWith(directory + "/"))
         || !changes.some(item => item.originalContent === null && item.content !== null && source.test(item.path)
           && (inventory.relative(item.path).startsWith(unit + "/") || inventory.relative(item.path).startsWith(unit + ".")))) throw fail("Only delete an existing empty .gitkeep while adding source in the selected owner beneath it. Other hidden-file changes are not allowed.", change.path);
@@ -179,7 +181,7 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
     }
     if (allowNew && unit === "configuration") continue; // The candidate must register every setup/extension file.
     if (change.path === "ds.config.json" && boundaryCompanion(unit)) continue; // Validated against only this owner below.
-    if (relative === inventory.publicEntry) continue;
+    if (relative === inventory.publicEntry || relative === inventory.reviewEntry) continue;
     if (unit === "tokens" && relative === inventory.stylesEntry) continue; // Controlled foundation import bookkeeping.
     if (allowNew && change.originalContent === null && (relative.startsWith(unit + "/") || relative.startsWith(unit + "."))) continue;
     const owner = inventory.owner(relative);
@@ -232,13 +234,14 @@ export function checkUnitCandidate(afterOptions, unit, changes, before) {
     }
     if (JSON.stringify(unrelated(current)) !== JSON.stringify(unrelated(proposed))) throw fail("Foundation companion patches may change only canonical imports for token files created/deleted in this patch; preserve all other imports and comments.", foundationChange.path);
   }
-  const exportChange = changes.find(change => before.relative(change.path) === before.publicEntry);
-  if (exportChange) {
-    if (!["components", "patterns", "controllers"].includes(unit.split("/")[0])) throw fail("Only a component/pattern/controller unit may update its public re-exports.", exportChange.path);
+  for (const entry of [before.publicEntry, before.reviewEntry]) {
+    const exportChange = changes.find(change => before.relative(change.path) === entry);
+    if (!exportChange) continue;
+    if (!(entry === before.reviewEntry ? ["review"] : ["components", "patterns", "controllers"]).includes(unit.split("/")[0])) throw fail("Only its own layer may update re-exports: product owners use the public entry, review owners use the development review entry.", exportChange.path);
     const current = exportChange.originalContent ?? "", proposed = exportChange.content;
     if (proposed === null) throw fail("The shared public entry cannot be deleted.", exportChange.path);
     const resolve = importResolver(afterOptions);
-    const file = path.join(afterOptions.dsRoot, afterOptions.config.publicEntry);
+    const file = path.join(afterOptions.dsRoot, entry);
     const original = ts.createSourceFile(file, current, ts.ScriptTarget.Latest, true);
     const candidate = ts.createSourceFile(file, proposed, ts.ScriptTarget.Latest, true);
     const emptyExport = statement => ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.exportClause.elements.length;

package/docs/ADS.md

@@ -114,7 +114,7 @@ are generated development evidence, outside source ownership and product bundles
 See the portable [capture workflow](../skills/ads-designer/references/captures.md).
 Token entries under the configured token directory declare
 `export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };`.
-`TokenSamples` is any project-owned public review pattern, not a required name.
+`TokenSamples` is any project-owned development-only review renderer, not a required name.
 Its colocated fixture declares literal `samples: [{ token, property, probe }]`.
 Each token must exist and have sample coverage; duplicate bindings, missing probes,
 empty covers and value-only inspectors fail. The default entry passes the declared
@@ -184,6 +184,19 @@ instead of assigning shared tokens in JavaScript. Full application harnesses
 belong in application test support. Run ADS/project checks before application,
 preview builds; review meaningful states in both themes and sizes.
 
+## Development review layer
+
+`review/` contains demo framing, demonstration controls and token renderers.
+It has a separate `reviewEntry` (default `review/index.ts`), imported through
+`${publicAlias}/review` (`@ds/review` by default). Product patterns are production
+application UI. The public production barrel and product catalogue exclude review
+exports; production code cannot depend on their implementation, types or styles.
+Review rendering stays inside the App and retains the normal token/style and
+public product-contract gates. See the portable
+[review guide](../skills/ads-designer/references/review.md) for scenarios, guarded
+owners, build aliases and migration. `ads_status.project.review` discovers the
+connected project's actual entry. Older tooling must be upgraded before migration.
+
 ## Shared token contract
 
 ### Owner-local tokens
@@ -198,7 +211,7 @@ components/Notice/
   tokens.css               # :root { --notice-width: 356px; }
   Scenario.tsx
   fixture.ts
-  Tokens.scenario.tsx      # kind: "tokens", public review pattern + samples
+  Tokens.scenario.tsx      # kind: "tokens", development-only review renderer + samples
   Tokens.fixture.ts
 ```
 
@@ -216,7 +229,7 @@ Measured runtime variables retain their existing exact `styleWrites` boundary.
 `ads_tokens` returns each token's owner, definitions and local namespace.
 
 A colocated scenario sets `kind:"tokens"` and declares real fixture `samples`
-consumed by a public review pattern. Its ID still derives from its source path.
+consumed by a development-only review renderer. Its ID still derives from its source path.
 Discovery attaches its owner's registered definition sheet as `stylesheets` on
 the generated scenario record; `previewEntriesPlugin` imports it directly into
 that preview's module graph. CSS-only package side effects can then tree-shake
@@ -259,6 +272,16 @@ custom styling in fixture files. The ADS frame pattern uses `--ux-*`. Foreign br
 CSS imports the approved token files in order; shared assignments belong in
 those token files, never in consumer styles or component state overrides.
 
+Typed custom-property registrations follow the same ownership. Runtime-variable
+`@property` metadata lives in component/pattern Linaria; shared and owner-local
+token registrations live beside real token definitions. Names are document-global:
+unrelated owners and conflicting descriptor sets cannot claim the same name.
+Descriptors have their own CSS grammar and independent literal defaults; normal
+visual styling still uses tokens. Registration does not create token/sample
+coverage, and base resets/font metadata cannot host it. Preserve whole rules with
+the ADS Linaria resolver in product and MCP preview builds. See the portable
+[atomic styling guide](../skills/ads-designer/references/atomic-styles.md).
+
 Foundation roles are enforced by `foundation-role`, `foundation-selector` and
 `foundation-import`, alongside the regular token checks. Shared definitions
 belong on the document root or explicit root themes; ordinary declarations belong
@@ -284,7 +307,7 @@ layout, component-specific focus rules and hover/disabled skins are rejected.
 Shared token definitions belong in value sheets, not `base.css`. No project token
 names are embedded in this policy. A zero-specificity `:where()` wrapper does not
 change ownership. Put component design and animation in Linaria owners, and
-scenario layout variations in typed public review-pattern props. Browser review
+scenario layout variations in typed review-helper props. Browser review
 still checks the effects and accessibility of permitted defaults.
 
 
@@ -384,6 +407,8 @@ The checks enforce the architecture's ownership boundaries:
 |----------|------------------|
 | Tokens and styles | Fixed token vocabulary, required definitions, declared value types and references, raw visual values, shared-token assignments, foundation import order, and component/pattern namespaces |
 | Public API and dependencies | Consumers use public ADS imports; ADS implementations and showcase do not import application source; runtime code does not import showcase fixtures |
+| Component and pattern layers | Component runtime cannot depend on patterns/composition, including through resolved aliases, re-exports and helpers; patterns consume public component symbols, not implementation helpers/types |
+| Component styling contracts | Patterns cannot target proven private component classes/data markers or read known private component variables; public hooks and registered non-state customization variables remain available; ancestor context for a pattern's own styles is allowed |
 | Interaction policy | Primitive state variables stay inside components; non-state customization hooks require explicit registration |
 | Renderer exceptions | Inline styles and imperative writes require used, narrow configured boundaries; stale entries fail; public props omit inherited style and reject open-ended visual strings |
 | Preview ownership | Scenarios define no CSS, custom classes, or standalone native controls; native slot children require public runtime cloning evidence; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
@@ -408,6 +433,18 @@ tests. Passing static checks establishes only the policies and source formats
 they cover. Browser review and behavior tests still verify accessibility,
 interaction, responsive layout, themes, and motion.
 
+A component provides one cohesive UI capability; a pattern arranges capabilities
+into a reusable structure or workflow. Component count is not a rule. Components
+may compose components/controllers; layout patterns can arrange content slots;
+component scenarios may use development-only review helpers. Classification is design
+guidance, while `component-dependency`, `component-contract` and `component-style`
+are blocking source-ownership rules. Type-only higher-layer references are not
+runtime edges. Relative component imports inside the ADS are valid when the
+selected symbols are public; a self-import through the root barrel is not required.
+Opaque/computed dependencies and ambiguous/generated style hooks require review.
+See the skill-local [layer guide](../skills/ads-designer/references/layers.md), also
+available through MCP at `ads://guides/layers`.
+
 Component-specific usage rules belong to that component in the receiving
 project. Import applicable rules with the item and register them through
 project configuration or maintained tooling integration. Core tooling must
@@ -438,7 +475,7 @@ Root [bootstrap-ds/](../bootstrap-ds/README.md) is the canonical empty scaffold.
 Its identical copy under `skills/ads-designer/assets/bootstrap-ds/` makes the
 skill self-contained. Run `npm run sync:skill-starter` after edits and
 `npm run check:skill-starter` to verify the copy. Both contain empty product component/composition directories and a minimal project-owned
-token review pattern. The scaffold pattern can be renamed or replaced; the tool
+token review renderer. The scaffold pattern can be renamed or replaced; the tool
 does not require that name or its styles and ships no product UI catalogue.
 
 Tool releases should version contract changes, rules, skills, bootstrap support,