@reqvire-org/ads 0.3.6 → 0.3.8

package/dist/public-api.mjs

@@ -2,6 +2,38 @@ import path from "node:path";
 import ts from "typescript";
 import { isDevelopmentFile, isInside } from "./config.mjs";
 import { uiOperation } from "./ui-framework.mjs";
+import { projectCompilerOptions } from "./boundaries.mjs";
+
+const resolvedCallables = new WeakMap();
+
+// The syntax guard omits libraries and dependency types. Resolve an ambiguous
+// public value lazily against the project's actual types, without importing it.
+// Keep the result with this immutable program so repeated discovery shares it.
+function resolvedCallable(program, options, name) {
+  if (!resolvedCallables.has(program)) {
+    const { dsRoot, config } = options;
+    const entryFile = path.join(dsRoot, config.publicEntry);
+    const compiler = projectCompilerOptions(options);
+    const semantic = ts.createProgram([entryFile], {
+      ...compiler, allowJs: true,
+      paths: { ...compiler.paths, [config.publicAlias]: [entryFile] },
+      types: compiler.types ?? [],
+    });
+    const checker = semantic.getTypeChecker();
+    const entry = semantic.getSourceFile(entryFile);
+    const module = entry && checker.getSymbolAtLocation(entry);
+    const callables = new Map();
+    for (const exported of module ? checker.getExportsOfModule(module) : []) {
+      const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+      const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+      if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
+      const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+      callables.set(exported.name, !!(type.getCallSignatures().length || type.getConstructSignatures().length));
+    }
+    resolvedCallables.set(program, callables);
+  }
+  return resolvedCallables.get(program).get(name) ?? false;
+}
 
 export function publicApi(program, options) {
   const checker = program.getTypeChecker();
@@ -33,7 +65,11 @@ export function publicApi(program, options) {
     }
     visit(declaration);
     const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
-    items.push({ name: exported.name, kind, file, declaration, renderable: kind !== "controllers" && renderable, behavioral: !!(type.getCallSignatures().length || type.getConstructSignatures().length) });
+    const behavioral = !!(type.getCallSignatures().length || type.getConstructSignatures().length
+      || !renderable && !!(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
+      && (program.getCompilerOptions().noLib || program.getCompilerOptions().noResolve)
+      && resolvedCallable(program, options, exported.name));
+    items.push({ name: exported.name, kind, file, declaration, renderable: kind !== "controllers" && renderable, behavioral });
   }
   return items;
 }

package/dist/scenarios.mjs

@@ -86,12 +86,22 @@ export function inspectScenarios(options, suppliedProgram) {
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     if (![".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].some(extension => existsSync(fixtureBase + extension))) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
     if (!metadata || Object.keys(metadata).some((key) => !["title", "kind", "covers", "exercises", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
-      || Object.hasOwn(metadata, "exercises") && (!Array.isArray(metadata.exercises) || metadata.exercises.some(name => typeof name !== "string" || !behaviorApis.has(name)))
       || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
       || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => known.get(name)?.kind === "patterns"))
       || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
       report(file, "Export static metadata with nonempty covers naming rendered public UI. Optional exercises names public behavioral APIs, not rendered UI. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
     }
+    // A bad behavioral entry must fail validation without erasing independent
+    // render evidence and manufacturing missing-coverage errors for real UI.
+    const exercises = [];
+    if (Object.hasOwn(metadata, "exercises")) {
+      if (!Array.isArray(metadata.exercises)) report(file, "Scenario exercises must be a static array naming public behavioral APIs.");
+      else for (const [index, name] of metadata.exercises.entries()) {
+        if (typeof name !== "string") report(file, `Scenario exercises[${index}] must name a public behavioral API, not ${JSON.stringify(name) ?? "an unresolved value"}.`);
+        else if (!behaviorApis.has(name)) report(file, `Scenario exercises[${index}] ${JSON.stringify(name)} is not a recognized public behavioral API. Use a public callable function, hook or controller; rendered UI belongs in covers. Discover the project's exports before declaring exercises.`);
+        else exercises.push(name);
+      }
+    }
     if (!["composition", "tokens"].includes(kind) && metadata.covers.some((name) => known.get(name).kind !== kind)) report(file, "Component scenarios cover primitives; pattern scenarios cover patterns. Use composition/ for larger interfaces.");
     const tokens = [...new Set([...(metadata.tokens ?? []), ...(metadata.samples ?? []).map(sample => sample.token)])];
     for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real token from its defining owner.` });
@@ -99,7 +109,7 @@ export function inspectScenarios(options, suppliedProgram) {
       const owner = scoped.inventory.owner(relative);
       for (const name of tokens) if (tokenInventory.tokens.find(token => token.name === name)?.owner !== owner) report(file, `Token ${name} needs a preview beside its defining owner. Shared tokens belong under the configured token directory; local tokens stay with their component/pattern.`);
     }
-    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(metadata.exercises ? { exercises: [...new Set(metadata.exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
@@ -137,10 +147,11 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
     }
     return symbol.declarations?.length ? symbol : null;
   }
-  const identities = new Map();
+  const identities = new Map(), behaviorIdentities = new Set();
   for (const item of publicApi(program, options)) {
     if (!identities.has(item.declaration)) identities.set(item.declaration, new Set());
     identities.get(item.declaration).add(item.name);
+    if (item.behavioral && !item.renderable) behaviorIdentities.add(item.declaration);
   }
 
   const covered = new Set();
@@ -180,6 +191,15 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
         if (ts.isPropertyAccessExpression(expression) && ["call", "apply"].includes(expression.name.text)) expression = expression.expression;
         const symbol = canonical(symbolOf(expression));
         for (const name of identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]) ?? []) exercised.add(name);
+        // A call on an attached method exercises its public behavioral receiver.
+        // Follow symbol identities through aliases, namespaces and re-exports;
+        // a property read or an unused callback still does not establish a call.
+        while (ts.isPropertyAccessExpression(expression) || ts.isElementAccessExpression(expression) && expression.argumentExpression && ts.isStringLiteralLike(expression.argumentExpression)) {
+          expression = expression.expression;
+          const receiver = canonical(symbolOf(expression));
+          const owner = receiver?.valueDeclaration ?? receiver?.declarations?.[0];
+          if (behaviorIdentities.has(owner)) for (const name of identities.get(owner) ?? []) exercised.add(name);
+        }
       }
       // Follow local adapters reachable from the default entry. Unused example
       // functions do not satisfy coverage; production implementations are never

package/dist/skills/ads-break-ui/SKILL.md

@@ -49,6 +49,13 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
+For atomic base/variant styling, helper/wrapper class composition, or an
+`atomic-composition-review` / `atomic-composition-limit` advisory, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
+
 Controllers are UI behavior owners: private helpers stay with their component or
 pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
 project's configured framework and declared dependencies, or plain TypeScript,

package/dist/skills/ads-break-ui/references/atomic-styles.md

@@ -0,0 +1,186 @@
+# Atomic style composition
+
+Use this guide when creating or migrating component/pattern styles, changing
+base/size/state combinations, or reviewing `atomic-composition-review` warnings.
+It is also available as `ads://guides/atomic-styles` through ADS MCP.
+
+## Why valid tokens can still render incorrectly
+
+Atomic Linaria extracts declarations into reusable classes. `cx` from
+`@linaria/atomic` or `@linaria/core` replaces earlier atoms with the same property
+and selector/condition key. It does not expand every CSS shorthand or resolve
+every overlap between physical and logical properties.
+
+For example, these declarations have different atomic keys:
+
+```tsx
+const base = css`
+  padding: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+
+cx(base, small);
+```
+
+Both classes survive. Both declarations can affect horizontal padding in a
+horizontal writing mode. In the inspected Linaria implementation, `padding` and
+`padding-inline` receive equal specificity. If a reset atom is emitted later,
+it can override the intended size. Shared atom reuse and CSS splitting can make
+this visible in a larger build even when an isolated view appears correct.
+The order of class names in HTML does not decide equal-specificity rule order.
+Valid tokens, successful extraction and a passing source check do not establish
+the intended computed value.
+
+See Linaria's [class merging implementation](https://github.com/callstack/linaria/blob/master/packages/core/src/cx.ts)
+and [property priority implementation](https://github.com/callstack/linaria/blob/master/packages/atomic/src/processors/helpers/propertyPriority.ts).
+Inspect the project's installed version when investigating its output.
+
+## Prefer matching properties across composed blocks
+
+Express the reset and overrides using the same property vocabulary:
+
+```tsx
+const base = css`
+  padding-block: 0;
+  padding-inline: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+const regular = css`
+  padding-block: var(--space-4);
+  padding-inline: var(--space-8);
+`;
+
+cx(base, compact ? small : regular);
+```
+
+Now each selected size replaces the corresponding base atom through `cx`.
+Review every size, including the default and icon-only variants. Changing only
+one size can leave another size mixing shorthand and logical properties.
+The names and tokens above are illustrative: use the project's real API and
+declared tokens. Preserve its intended dimensions and supported writing modes.
+
+The same reasoning applies to margin, inset, logical borders/corners, dimensions
+and overflow. For example, prefer `margin-inline: 0` plus a size's
+`margin-inline: var(...)` over combining `margin: 0` with that logical override.
+Choose consistent physical properties when the product deliberately positions
+against physical edges; logical properties are not mandatory.
+
+An intentional state override may have a different selector or condition:
+
+```tsx
+const treatment = css`
+  padding-inline: var(--space-6);
+  &:hover { padding-inline: var(--space-8); }
+`;
+```
+
+This is a distinct state, not two competing base atoms. Whether changing padding
+on hover is desirable remains a product decision.
+
+## Follow helpers and forwarded classes
+
+Composition can cross a helper or a component boundary. For example, in component
+implementation source:
+
+```tsx
+function baseClasses() { return base; }
+function Primitive({ className, ...props }) {
+  return <button {...props} className={cx(baseClasses(), className)} />;
+}
+function CompactPrimitive(props) {
+  return <Primitive {...props} className={small} />;
+}
+```
+
+The base and small atoms can reach the same button. Inspect both owners when
+correcting their property vocabulary. The wrapper's class does not style every
+descendant: a class on a child or sibling element is a separate composition.
+An imported stylesheet alone does not show that its classes co-apply.
+
+Spread order matters. `<button className={base} {...props} />` can replace the
+entire className; `<button {...props} className={cx(base, className)} />` composes
+it explicitly. Keep the product's intended forwarding behavior when fixing an
+overlap. Do not change the public API simply to make tracing easier.
+
+Warnings include a bounded `composition` path through traced helpers and
+components. A `target` identifies a statically reached DOM element. This
+establishes source composition, not that a scenario mounted it or that its
+computed result is wrong. `writingModeDependent: true` identifies overlaps that
+change with direction or writing mode; evaluate those against supported modes.
+Literal overlaps with provably equal values are omitted where the analyzer can
+expand them safely. Token formulas, inheritance and runtime values still need
+review. A margin shorthand and `margin-inline: auto` may agree horizontally but
+disagree in vertical text, so horizontal equality alone is insufficient.
+
+## Respond to a warning
+
+1. Follow the warning's related file/line locations and inspect the actual `cx`
+   composition. Variant lookups may contribute several possible combinations.
+2. In a current built preview, inspect computed properties and the winning CSS
+   rules. Establish whether extraction order, specificity, writing mode or an
+   intentional override explains the result.
+3. For accidental overlap, align property names/granularity across the base and
+   affected variants. Use Linaria's `cx`, preserve tokens and fix the owning
+   component/pattern. Reordering class strings does not remove overlapping keys.
+4. Verify the affected sizes/states and supported directions in the normal app
+   and preview build. Add a registered rendered check when a specific geometry
+   or computed-style guarantee matters.
+
+Increasing specificity, adding `!important`, copying styles into scenarios or
+moving component styling into `base.css` can hide the symptom while retaining
+the conflict. Prefer resolving the composition itself. If an overlap is
+intentional, document why its precedence is stable and verify the resulting
+behavior rather than changing product capabilities to silence a warning.
+
+Use existing behavior contracts and `ads_verify` for important geometry. Register
+a check beside its owner, link its real scenario and use the project's browser
+profile. An assertion can inspect the actual control in the App frame:
+
+```ts
+const frame = await openBehaviorScenario(page, "compact-spacing");
+await expect(frame.getByRole("button", { name: "Compact" }))
+  .toHaveCSS("padding-inline-start", "8px");
+```
+
+The name, check ID and expected value above are examples. Derive assertions from
+the project's intended API and design, with relevant variants, open/hover/focus
+states, themes and supported writing modes. Wait for observable readiness; an
+event-stream connection can prevent `networkidle` from settling. A generic
+overlap scan cannot decide which dimensions the product intended. A failed
+registered geometry assertion is blocking through the existing verification
+contract; an overlap warning remains a review signal.
+
+## What ADS checks
+
+`atomic-composition-review` is a nonblocking warning, returned under `advisories`
+with `severity: "warning"`. CLI checks still exit successfully when there are no
+errors; MCP checks and mutations preserve the warning and its guidance URI.
+
+The source review examines atomic Linaria templates and statically traceable
+`cx` arguments, including aliases, local imports/re-exports, local helper returns,
+arguments/defaults, nested composition, conditional expressions and variant-object
+lookups. It follows explicit `className` forwarding through local function
+components, props/rest spreads and imported React/Preact `memo`/`forwardRef`
+wrappers to an intrinsic JSX element. It checks known overlaps involving box
+spacing, inset, borders/corners, dimensions, overflow, backgrounds, typography,
+motion and common layout shorthands, plus `all` resets. It compares shared selector/condition contexts; separate alternatives
+within one conditional or lookup are not assumed to apply together. Matching
+atomic property/selector/condition keys are replaced during traced `cx`
+composition before comparing the surviving declarations.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not execute helpers or import project modules, enumerate every external
+class, or model arbitrary runtime mutation, component rendering, selectors or
+overlapping media queries. Recursive calls, unsupported call/control-flow paths,
+unresolved DOM targets and traversal limits produce bounded
+`atomic-composition-limit` informational advisories where known atomic styles
+reach an unresolved composition. Ordinary externally supplied className values
+remain open inputs, not guaranteed safe styles. Depth, work and alternative
+limits keep source inspection bounded; an unreported path or an empty warning
+list does not establish visual correctness. Actual failed registered
+browser/behavior checks remain blocking; potentially intentional source overlaps
+remain warnings.

package/dist/skills/ads-designer/SKILL.md

@@ -80,6 +80,13 @@ use the client's normal source-editing tools.
 For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
+For atomic base/variant styling, helper/wrapper class composition, or an
+`atomic-composition-review` / `atomic-composition-limit` advisory, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
+
 Controllers are UI behavior owners: private helpers stay with their component or
 pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
 project's configured framework and declared dependencies, or plain TypeScript,

package/dist/skills/ads-designer/references/atomic-styles.md

@@ -0,0 +1,186 @@
+# Atomic style composition
+
+Use this guide when creating or migrating component/pattern styles, changing
+base/size/state combinations, or reviewing `atomic-composition-review` warnings.
+It is also available as `ads://guides/atomic-styles` through ADS MCP.
+
+## Why valid tokens can still render incorrectly
+
+Atomic Linaria extracts declarations into reusable classes. `cx` from
+`@linaria/atomic` or `@linaria/core` replaces earlier atoms with the same property
+and selector/condition key. It does not expand every CSS shorthand or resolve
+every overlap between physical and logical properties.
+
+For example, these declarations have different atomic keys:
+
+```tsx
+const base = css`
+  padding: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+
+cx(base, small);
+```
+
+Both classes survive. Both declarations can affect horizontal padding in a
+horizontal writing mode. In the inspected Linaria implementation, `padding` and
+`padding-inline` receive equal specificity. If a reset atom is emitted later,
+it can override the intended size. Shared atom reuse and CSS splitting can make
+this visible in a larger build even when an isolated view appears correct.
+The order of class names in HTML does not decide equal-specificity rule order.
+Valid tokens, successful extraction and a passing source check do not establish
+the intended computed value.
+
+See Linaria's [class merging implementation](https://github.com/callstack/linaria/blob/master/packages/core/src/cx.ts)
+and [property priority implementation](https://github.com/callstack/linaria/blob/master/packages/atomic/src/processors/helpers/propertyPriority.ts).
+Inspect the project's installed version when investigating its output.
+
+## Prefer matching properties across composed blocks
+
+Express the reset and overrides using the same property vocabulary:
+
+```tsx
+const base = css`
+  padding-block: 0;
+  padding-inline: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+const regular = css`
+  padding-block: var(--space-4);
+  padding-inline: var(--space-8);
+`;
+
+cx(base, compact ? small : regular);
+```
+
+Now each selected size replaces the corresponding base atom through `cx`.
+Review every size, including the default and icon-only variants. Changing only
+one size can leave another size mixing shorthand and logical properties.
+The names and tokens above are illustrative: use the project's real API and
+declared tokens. Preserve its intended dimensions and supported writing modes.
+
+The same reasoning applies to margin, inset, logical borders/corners, dimensions
+and overflow. For example, prefer `margin-inline: 0` plus a size's
+`margin-inline: var(...)` over combining `margin: 0` with that logical override.
+Choose consistent physical properties when the product deliberately positions
+against physical edges; logical properties are not mandatory.
+
+An intentional state override may have a different selector or condition:
+
+```tsx
+const treatment = css`
+  padding-inline: var(--space-6);
+  &:hover { padding-inline: var(--space-8); }
+`;
+```
+
+This is a distinct state, not two competing base atoms. Whether changing padding
+on hover is desirable remains a product decision.
+
+## Follow helpers and forwarded classes
+
+Composition can cross a helper or a component boundary. For example, in component
+implementation source:
+
+```tsx
+function baseClasses() { return base; }
+function Primitive({ className, ...props }) {
+  return <button {...props} className={cx(baseClasses(), className)} />;
+}
+function CompactPrimitive(props) {
+  return <Primitive {...props} className={small} />;
+}
+```
+
+The base and small atoms can reach the same button. Inspect both owners when
+correcting their property vocabulary. The wrapper's class does not style every
+descendant: a class on a child or sibling element is a separate composition.
+An imported stylesheet alone does not show that its classes co-apply.
+
+Spread order matters. `<button className={base} {...props} />` can replace the
+entire className; `<button {...props} className={cx(base, className)} />` composes
+it explicitly. Keep the product's intended forwarding behavior when fixing an
+overlap. Do not change the public API simply to make tracing easier.
+
+Warnings include a bounded `composition` path through traced helpers and
+components. A `target` identifies a statically reached DOM element. This
+establishes source composition, not that a scenario mounted it or that its
+computed result is wrong. `writingModeDependent: true` identifies overlaps that
+change with direction or writing mode; evaluate those against supported modes.
+Literal overlaps with provably equal values are omitted where the analyzer can
+expand them safely. Token formulas, inheritance and runtime values still need
+review. A margin shorthand and `margin-inline: auto` may agree horizontally but
+disagree in vertical text, so horizontal equality alone is insufficient.
+
+## Respond to a warning
+
+1. Follow the warning's related file/line locations and inspect the actual `cx`
+   composition. Variant lookups may contribute several possible combinations.
+2. In a current built preview, inspect computed properties and the winning CSS
+   rules. Establish whether extraction order, specificity, writing mode or an
+   intentional override explains the result.
+3. For accidental overlap, align property names/granularity across the base and
+   affected variants. Use Linaria's `cx`, preserve tokens and fix the owning
+   component/pattern. Reordering class strings does not remove overlapping keys.
+4. Verify the affected sizes/states and supported directions in the normal app
+   and preview build. Add a registered rendered check when a specific geometry
+   or computed-style guarantee matters.
+
+Increasing specificity, adding `!important`, copying styles into scenarios or
+moving component styling into `base.css` can hide the symptom while retaining
+the conflict. Prefer resolving the composition itself. If an overlap is
+intentional, document why its precedence is stable and verify the resulting
+behavior rather than changing product capabilities to silence a warning.
+
+Use existing behavior contracts and `ads_verify` for important geometry. Register
+a check beside its owner, link its real scenario and use the project's browser
+profile. An assertion can inspect the actual control in the App frame:
+
+```ts
+const frame = await openBehaviorScenario(page, "compact-spacing");
+await expect(frame.getByRole("button", { name: "Compact" }))
+  .toHaveCSS("padding-inline-start", "8px");
+```
+
+The name, check ID and expected value above are examples. Derive assertions from
+the project's intended API and design, with relevant variants, open/hover/focus
+states, themes and supported writing modes. Wait for observable readiness; an
+event-stream connection can prevent `networkidle` from settling. A generic
+overlap scan cannot decide which dimensions the product intended. A failed
+registered geometry assertion is blocking through the existing verification
+contract; an overlap warning remains a review signal.
+
+## What ADS checks
+
+`atomic-composition-review` is a nonblocking warning, returned under `advisories`
+with `severity: "warning"`. CLI checks still exit successfully when there are no
+errors; MCP checks and mutations preserve the warning and its guidance URI.
+
+The source review examines atomic Linaria templates and statically traceable
+`cx` arguments, including aliases, local imports/re-exports, local helper returns,
+arguments/defaults, nested composition, conditional expressions and variant-object
+lookups. It follows explicit `className` forwarding through local function
+components, props/rest spreads and imported React/Preact `memo`/`forwardRef`
+wrappers to an intrinsic JSX element. It checks known overlaps involving box
+spacing, inset, borders/corners, dimensions, overflow, backgrounds, typography,
+motion and common layout shorthands, plus `all` resets. It compares shared selector/condition contexts; separate alternatives
+within one conditional or lookup are not assumed to apply together. Matching
+atomic property/selector/condition keys are replaced during traced `cx`
+composition before comparing the surviving declarations.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not execute helpers or import project modules, enumerate every external
+class, or model arbitrary runtime mutation, component rendering, selectors or
+overlapping media queries. Recursive calls, unsupported call/control-flow paths,
+unresolved DOM targets and traversal limits produce bounded
+`atomic-composition-limit` informational advisories where known atomic styles
+reach an unresolved composition. Ordinary externally supplied className values
+remain open inputs, not guaranteed safe styles. Depth, work and alternative
+limits keep source inspection bounded; an unreported path or an empty warning
+list does not establish visual correctness. Actual failed registered
+browser/behavior checks remain blocking; potentially intentional source overlaps
+remain warnings.

package/dist/skills/ads-import/SKILL.md

@@ -44,6 +44,13 @@ use the client's normal source-editing tools.
 For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
+For atomic base/variant styling, helper/wrapper class composition, or an
+`atomic-composition-review` / `atomic-composition-limit` advisory, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
+
 Controllers are UI behavior owners: private helpers stay with their component or
 pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
 project's configured framework and declared dependencies, or plain TypeScript,