@reqvire-org/ads 0.3.6 → 0.3.7

package/dist/atomic-composition.mjs

@@ -0,0 +1,183 @@
+import path from "node:path";
+import ts from "typescript";
+import postcss from "postcss";
+import { isInside } from "./config.mjs";
+
+export const atomicStyleGuide = "ads://guides/atomic-styles";
+
+const sides = ["top", "right", "bottom", "left"];
+const logicalSides = ["block-start", "block-end", "inline-start", "inline-end"];
+const intersects = (a, b) => a.some(value => b.includes(value));
+const previewValue = value => value.length > 200 ? value.slice(0, 197) + "..." : value;
+const shorthands = {
+  background: ["background-attachment", "background-clip", "background-color", "background-image", "background-origin", "background-position", "background-repeat", "background-size"],
+  "background-position": ["background-position-x", "background-position-y"],
+  "background-repeat": ["background-repeat-x", "background-repeat-y"],
+  font: ["font-family", "font-size", "font-stretch", "font-style", "font-variant", "font-weight", "line-height"],
+  animation: ["animation-name", "animation-duration", "animation-timing-function", "animation-delay", "animation-iteration-count", "animation-direction", "animation-fill-mode", "animation-play-state"],
+  transition: ["transition-property", "transition-duration", "transition-timing-function", "transition-delay", "transition-behavior"],
+  flex: ["flex-grow", "flex-shrink", "flex-basis"],
+  "flex-flow": ["flex-direction", "flex-wrap"],
+  gap: ["row-gap", "column-gap"],
+  outline: ["outline-color", "outline-style", "outline-width"],
+  columns: ["column-count", "column-width"],
+  "column-rule": ["column-rule-color", "column-rule-style", "column-rule-width"],
+  "list-style": ["list-style-image", "list-style-position", "list-style-type"],
+  "text-decoration": ["text-decoration-color", "text-decoration-style", "text-decoration-line", "text-decoration-thickness"],
+};
+const expand = property => shorthands[property]?.flatMap(expand) ?? [property];
+const longhands = new Map(Object.keys(shorthands).map(property => [property, expand(property)]));
+
+// CSS-language relationships, independent of components, tokens and frameworks.
+function footprint(property) {
+  const box = /^(padding|margin|scroll-padding|scroll-margin|inset)(?:-(top|right|bottom|left|block|inline|block-start|block-end|inline-start|inline-end))?$/.exec(property);
+  if (box) {
+    const side = box[2];
+    const logical = !!side && !sides.includes(side);
+    return { family: box[1], logical, slots: !side ? logicalSides : /^(block|inline)$/.test(side) ? [`${side}-start`, `${side}-end`] : [side], whole: !side };
+  }
+  if (sides.includes(property)) return { family: "inset", logical: false, slots: [property] };
+  const border = /^border(?:-(top|right|bottom|left|block|inline|block-start|block-end|inline-start|inline-end))?(?:-(color|style|width))?$/.exec(property);
+  if (border) {
+    const side = border[1];
+    return { family: "border", logical: !!side && !sides.includes(side), slots: !side ? logicalSides : /^(block|inline)$/.test(side) ? [`${side}-start`, `${side}-end`] : [side], whole: !side, fields: border[2] ? [border[2]] : ["color", "style", "width"] };
+  }
+  const corner = /^border-(?:(top-left|top-right|bottom-left|bottom-right|start-start|start-end|end-start|end-end)-)?radius$/.exec(property);
+  if (corner) return { family: "radius", logical: /^(start|end)-/.test(corner[1] ?? ""), whole: !corner[1], slots: [corner[1]] };
+  const dimension = /^(min-|max-)?(width|height|inline-size|block-size)$/.exec(property);
+  if (dimension) return { family: `${dimension[1] ?? ""}size`, logical: dimension[2].endsWith("-size"), slots: [dimension[2]] };
+  const overflow = /^(overflow|overscroll-behavior)(?:-(x|y|block|inline))?$/.exec(property);
+  if (overflow) return { family: overflow[1], logical: ["block", "inline"].includes(overflow[2]), whole: !overflow[2], slots: [overflow[2]] };
+  return null;
+}
+
+function overlaps(a, b) {
+  if (a === b || a.startsWith("--") || b.startsWith("--")) return false;
+  if ([a, b].includes("all")) return ![a, b].some(value => ["direction", "unicode-bidi"].includes(value));
+  const first = footprint(a), second = footprint(b);
+  if (first && second && first.family === second.family) {
+    if (first.fields && !intersects(first.fields, second.fields)) return false;
+    return first.whole || second.whole || first.logical !== second.logical || intersects(first.slots, second.slots);
+  }
+  return intersects(longhands.get(a) ?? [a], longhands.get(b) ?? [b]);
+}
+
+function unwrap(node) {
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+  return node;
+}
+
+/** Review only: valid CSS can intentionally overlap. Never rewrite project CSS. */
+export function createAtomicCompositionReview(program, options) {
+  const checker = program.getTypeChecker(), templates = new Map();
+  function declaration(node) {
+    let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+    if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    return symbol?.valueDeclaration;
+  }
+  function imported(node, names, modules, seen = new Set()) {
+    node = unwrap(node);
+    if (!node || seen.has(node)) return false;
+    seen = new Set([...seen, node]);
+    const base = ts.isPropertyAccessExpression(node) ? node.expression : node;
+    const symbol = checker.getSymbolAtLocation(base);
+    for (const item of symbol?.declarations ?? []) {
+      if (ts.isImportSpecifier(item) && names.includes((item.propertyName ?? item.name).text) && modules.includes(item.parent.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isNamespaceImport(item) && ts.isPropertyAccessExpression(node) && names.includes(node.name.text) && modules.includes(item.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isVariableDeclaration(item) && imported(item.initializer, names, modules, seen)) return true;
+    }
+    return false;
+  }
+  const isCx = node => imported(node, ["cx"], ["@linaria/atomic", "@linaria/core"]);
+  function isAtomic(tag) {
+    if (ts.isCallExpression(tag)) tag = tag.expression;
+    if (imported(tag, ["css", "styled"], ["@linaria/atomic"])) return true;
+    return ts.isPropertyAccessExpression(tag) && imported(tag.expression, ["styled"], ["@linaria/atomic"]);
+  }
+  function entries(node) {
+    if (templates.has(node)) return templates.get(node);
+    const result = [];
+    templates.set(node, result);
+    const source = node.getSourceFile(), template = node.template;
+    const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text : template.head.text + template.templateSpans.map(span => `__ads_expression__${"\n".repeat(span.expression.getText(source).split("\n").length - 1)}${span.literal.text}`).join("");
+    const position = source.getLineAndCharacterOfPosition(template.getStart(source) + 1);
+    try {
+      postcss.parse(text).walkDecls(decl => {
+        const selectors = [], conditions = [];
+        for (let parent = decl.parent; parent?.type !== "root"; parent = parent?.parent) {
+          if (!parent) break;
+          if (parent.type === "rule") selectors.unshift(parent.selector.trim().replace(/\s+/g, " "));
+          if (parent.type === "atrule") conditions.unshift(`${parent.name} ${parent.params}`.trim().replace(/\s+/g, " "));
+        }
+        // Animation frames describe different instants, not combined classes.
+        if (conditions.some(condition => /^(?:-\w+-)?keyframes\b/.test(condition))) return;
+        result.push({ property: decl.prop.toLowerCase(), value: decl.value, important: !!decl.important, selectors: JSON.stringify(selectors), conditions: JSON.stringify(conditions),
+          file: path.relative(options.root, source.fileName).replaceAll("\\", "/"), line: position.line + decl.source.start.line, column: decl.source.start.column + (decl.source.start.line === 1 ? position.character : 0) });
+      });
+    } catch { /* The core CSS syntax diagnostic owns malformed templates. */ }
+    return result;
+  }
+  function object(node, seen = new Set()) {
+    node = unwrap(node);
+    if (!node || seen.has(node)) return null;
+    if (ts.isObjectLiteralExpression(node) || ts.isArrayLiteralExpression(node)) return node;
+    const owner = declaration(node);
+    return owner?.initializer ? object(owner.initializer, new Set([...seen, node])) : null;
+  }
+  function styles(node, seen = new Set()) {
+    node = unwrap(node);
+    if (!node || seen.has(node)) return [];
+    seen = new Set([...seen, node]);
+    if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) return entries(node);
+    if (ts.isConditionalExpression(node)) return [...styles(node.whenTrue, seen), ...styles(node.whenFalse, seen)];
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return [...(node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ? [] : styles(node.left, seen)), ...styles(node.right, seen)];
+    if (ts.isCallExpression(node) && isCx(node.expression)) return node.arguments.flatMap(argument => styles(argument, seen));
+    if (ts.isSpreadElement(node)) {
+      const value = object(node.expression);
+      return value && ts.isArrayLiteralExpression(value) ? value.elements.flatMap(element => styles(element, seen)) : [];
+    }
+    const owner = declaration(node);
+    if (owner?.initializer) return styles(owner.initializer, seen);
+    if (ts.isElementAccessExpression(node) || ts.isPropertyAccessExpression(node)) {
+      const value = object(node.expression);
+      if (!value || !ts.isObjectLiteralExpression(value)) return [];
+      const key = ts.isPropertyAccessExpression(node) ? node.name.text : node.argumentExpression && ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
+      return value.properties.flatMap(property => {
+        const name = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
+        return key !== null && name !== key ? [] : ts.isPropertyAssignment(property) ? styles(property.initializer, seen) : ts.isShorthandPropertyAssignment(property) ? styles(property.name, seen) : [];
+      });
+    }
+    return [];
+  }
+  return source => {
+    const warnings = [], seen = new Set();
+    function compare(first, second, location) {
+      for (const a of first) for (const b of second) {
+        if (a === b || a.selectors !== b.selectors || a.conditions !== b.conditions || a.important !== b.important || a.value === "0" && b.value === "0" || !overlaps(a.property, b.property)) continue;
+        const key = JSON.stringify([a, b].map(entry => [entry.file, entry.line, entry.column]).sort());
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const position = source.getLineAndCharacterOfPosition(location.getStart(source));
+        warnings.push({ rule: "atomic-composition-review", severity: "warning", line: position.line + 1, column: position.character + 1,
+          message: `Atomic declarations ${a.property}: ${previewValue(a.value)} and ${b.property}: ${previewValue(b.value)} may overlap without matching cx merge keys. Their winner can depend on extraction order, specificity or writing mode. Use consistent property names/granularity across the base and variants, compose with Linaria cx, and verify computed styles in the built preview. Review all affected variants; valid tokens do not establish cascade correctness. See ${atomicStyleGuide}.`,
+          guidanceUri: atomicStyleGuide, related: [a, b].map(({ selectors: _selectors, conditions: _conditions, important: _important, ...entry }) => ({...entry,value:previewValue(entry.value)})) });
+      }
+    }
+    function visit(node) {
+      if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) {
+        const declarations = entries(node);
+        for (let index = 0; index < declarations.length; index++) compare([declarations[index]], declarations.slice(index + 1), node);
+      }
+      if (ts.isCallExpression(node) && isCx(node.expression)) {
+        const groups = node.arguments.flatMap(argument => {
+          const value = ts.isSpreadElement(argument) ? object(argument.expression) : null;
+          return value && ts.isArrayLiteralExpression(value) ? value.elements.map(element => styles(element)) : [styles(argument)];
+        });
+        for (let index = 0; index < groups.length; index++) for (let next = index + 1; next < groups.length; next++) compare(groups[index], groups[next], node);
+      }
+      ts.forEachChild(node, visit);
+    }
+    if (isInside(options.dsRoot, source.fileName)) visit(source);
+    return warnings;
+  };
+}

package/dist/check.mjs

@@ -19,6 +19,7 @@ import { inspectBehaviors, inspectControllers } from "./behaviors.mjs";
 import { numericCssUnit, tokenLengthLiteral } from "./css-values.mjs";
 import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
 import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
+import { createAtomicCompositionReview } from "./atomic-composition.mjs";
 
 const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
 const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
@@ -50,6 +51,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const compiler = projectCompilerOptions(options);
   const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
   const checker = program.getTypeChecker();
+  const atomicCompositionReview = createAtomicCompositionReview(program, options);
   function report(file, rule, message, line = 1, column = 1) {
     diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
   }
@@ -149,6 +151,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     const source = program.getSourceFile(file);
     if (!source) continue;
     advisories.push(...pointerCaptureAdvisories(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
+    advisories.push(...atomicCompositionReview(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
     for (const diagnostic of program.getSyntacticDiagnostics(source)) {
       const position = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
       report(file, "source-syntax", ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"), position.line + 1, position.character + 1);

package/dist/cli.mjs

@@ -113,7 +113,7 @@ async function main(args) {
   if (!json && result.diagnostics?.length) {
     for (const diagnostic of result.diagnostics) console.error(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.rule}] ${diagnostic.message}`);
   }
-  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [advisory:${advisory.rule}] ${advisory.message}`);
+  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [${advisory.severity ?? "advisory"}:${advisory.rule}] ${advisory.message}`);
   if (result.ok === false || result.diagnostics?.length) process.exitCode = 1;
 }
 

package/dist/mcp/server.mjs

@@ -85,6 +85,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     return [
       { uri: GUIDE_URI, name: "Start here: design-system workflow", description: "Read first for UI/ADS tasks, especially when only resource access is exposed. Explains the exact workspace, tool sequence, skill selection, previews, project commands and fallback.", mimeType: "text/markdown" },
       { uri: "ads://guides/behaviors", name: "Controller and behavioral verification guide", mimeType: "text/markdown" },
+      { uri: "ads://guides/atomic-styles", name: "Atomic style composition: conflicts, prevention and fixes", mimeType: "text/markdown" },
       { uri: `${PROJECT_URI}/status`, name: "ADS project status", mimeType: "application/json" },
       { uri: BUILD_URI, name: "Preview build status and diagnostics", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/tokens`, name: "Project token values and themes", mimeType: "application/json" },
@@ -92,13 +93,13 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       { uri: `${PROJECT_URI}/scenarios`, name: "Independently mountable scenarios", mimeType: "application/json" },
       { uri: BEHAVIOR_URI, name: "Behavior contracts, demonstrations and current verification evidence", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/checks`, name: "Current ADS architecture diagnostics", mimeType: "application/json" },
+      ...documents.filter(document => promoted.has(document.uri)).sort((a, b) => Number(b.uri === context.publicEntryUri) - Number(a.uri === context.publicEntryUri)).map(({ file: _file, ...document }) => document),
       { uri: TOKENS_APP_URI, name: "Experimental token widget", mimeType: APP_MIME },
       { uri: SCENARIO_APP_URI, name: "Experimental scenario widget", mimeType: APP_MIME },
       ...(options.config.mcp.previewManifest ? [{ uri: PREVIEW_APP_URI, name: "Shared-resource preview App", mimeType: APP_MIME }, { uri: PREVIEW_MANIFEST_URI, name: "Preview dependency graph", mimeType: "application/json" }] : []),
       ...(options.config.mcp.previewManifest ? resourceAssets() : []),
       ...allApps().map((app) => ({ uri: appUri(app.id), name: app.title, description: app.description, mimeType: APP_MIME })),
       ...skills.skills.map(({ uri, frontmatter }) => ({ uri, name: frontmatter.name, description: frontmatter.description, mimeType: "text/markdown" })),
-      ...documents.filter((document) => promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
       ...documents.filter((document) => !promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
       ...[...skills.files.values()].filter((file) => !skillEntries.has(file.uri)).map(({ uri, name, mimeType }) => ({ uri, name, mimeType })),
     ];
@@ -121,6 +122,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   async function read(uri, signal) {
     if (uri === GUIDE_URI) return { contents: [{ uri, mimeType: "text/markdown", text: projectGuide(project(), [...previews(), ...scenarioApps()]) }] };
     if (uri === "ads://guides/behaviors") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../../docs/BEHAVIORS.md", import.meta.url), "utf8") }] };
+    if (uri === "ads://guides/atomic-styles") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/atomic-styles.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
     let value;
     if (uri === `${PROJECT_URI}/status`) value = status();
@@ -203,7 +205,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const matches = inventory.tokens.filter((token) => token.name.toLowerCase().includes(search.toLowerCase()));
         return json({ total: matches.length, tokens: matches.slice(0, limit), categories: tokenScenarios(), diagnosticCount: inventory.diagnostics.length, resourceUri: `${PROJECT_URI}/tokens` });
       } },
-      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking review advisories. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
+      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking review advisories. Atomic composition warnings identify overlapping properties and link ads://guides/atomic-styles for causes and fixes. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
         const result = checkProject(root);
         return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), advisoryCount: result.advisories?.length ?? 0, advisories: (result.advisories ?? []).slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
       } },

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 };
 }

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

@@ -49,6 +49,12 @@ 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 or an `atomic-composition-review` warning, 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,121 @@
+# 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.
+
+## 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.
+
+## 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, nested composition, conditional
+expressions and variant-object lookups. 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.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. 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,12 @@ 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 or an `atomic-composition-review` warning, 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,121 @@
+# 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.
+
+## 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.
+
+## 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, nested composition, conditional
+expressions and variant-object lookups. 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.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. 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,12 @@ 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 or an `atomic-composition-review` warning, 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-import/references/atomic-styles.md

@@ -0,0 +1,121 @@
+# 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.
+
+## 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.
+
+## 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, nested composition, conditional
+expressions and variant-object lookups. 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.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. 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-migrate/SKILL.md

@@ -46,6 +46,12 @@ 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 or an `atomic-composition-review` warning, 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-migrate/references/atomic-styles.md

@@ -0,0 +1,121 @@
+# 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.
+
+## 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.
+
+## 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, nested composition, conditional
+expressions and variant-object lookups. 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.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. 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-motion/SKILL.md

@@ -66,6 +66,12 @@ 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 or an `atomic-composition-review` warning, 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-motion/references/atomic-styles.md

@@ -0,0 +1,121 @@
+# 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.
+
+## 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.
+
+## 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, nested composition, conditional
+expressions and variant-object lookups. 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.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. An empty warning list does not establish
+visual correctness. Actual failed registered browser/behavior checks remain
+blocking; potentially intentional source overlaps remain warnings.

package/docs/ADS.md

@@ -367,6 +367,13 @@ Pointer capture without locally visible capture-loss cleanup produces a
 nonblocking advisory. Review delegated cleanup and browser behavior; neither a
 warning nor a handler's presence establishes lifecycle correctness.
 
+Potential atomic CSS overlaps produce `atomic-composition-review` warnings with
+related declarations and a guidance URI. They are nonblocking, including during
+guarded mutations: valid CSS can intentionally overlap. Read
+[atomic style composition](../skills/ads-designer/references/atomic-styles.md) for causes, matching-property fixes
+and the source review's limits. Registered rendered checks can enforce a
+project's intended computed geometry; token validity alone cannot establish it.
+
 Document a new ownership exception with its guard/configuration change and
 tests. Passing static checks establishes only the policies and source formats
 they cover. Browser review and behavior tests still verify accessibility,
@@ -390,6 +397,13 @@ Validate accepted and rejected cases, configuration, and false-positive limits.
 
 ## Bootstrap and updates
 
+The atomic composition guide lives in each skill's `references/atomic-styles.md`.
+The maintained copy is in `skills/ads-designer/references/atomic-styles.md`;
+MCP serves that packaged skill reference. `npm run sync:skill-references` copies
+it to the other skills for standalone use; `npm run check:skill-references`
+rejects drift during the tool build. Published packages include these references
+under `dist/skills/`.
+
 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

package/docs/ARCHITECTURE.md

@@ -122,6 +122,12 @@ Linaria's [colocation and extraction model](https://github.com/callstack/linaria
 and [atomic composition model](https://github.com/callstack/linaria/blob/master/docs/ATOMIC_CSS.md)
 support this combination of local ownership and compiled styling.
 
+Atomic merging matches property/selector/condition keys; it does not resolve
+every shorthand/logical-property overlap. ADS reports detectable composition
+risks as nonblocking warnings with guidance, while registered rendered checks
+can enforce actual geometry. See the skill-local
+[atomic style composition guide](../skills/ads-designer/references/atomic-styles.md).
+
 Airbnb's 2022 [migration report](https://medium.com/airbnb-engineering/airbnbs-trip-to-linaria-dc169230bd12)
 provides practical evidence for this choice: performance was its leading
 criterion, with separate CSS caching and colocated authoring among the benefits.

package/docs/BEHAVIORS.md

@@ -95,6 +95,15 @@ metadata string does not count. Dynamically passed behavior references produce a
 review advisory when a direct call cannot be established; verify those through
 registered execution checks rather than changing the API for the analyzer.
 
+Callable exports may be functions, callable objects with attached methods, or
+factory results. ADS uses their TypeScript call/construct signatures, including
+the project's library declarations; it does not execute modules or maintain a
+list of recognized factory names. The fast source guard resolves ambiguous public
+values lazily and shares that type discovery within the check. Untyped `any`
+values and objects containing methods do not establish a callable API.
+An invalid `exercises` entry names the offending value and fails validation while
+retaining independent render evidence for `covers`.
+
 Public APIs appear in `ads_catalog` with `apiKind: "ui"` or `"behavior"` and their
 scenario links. `ads_behaviors` joins contracts to demonstrations and evidence.
 A demonstrated API is not automatically a verified guarantee.

package/docs/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.3.7
+
+- Warn about statically traceable atomic CSS property overlaps without blocking
+  checks or guarded edits. Include source pairs, concrete correction guidance and
+  a guide inside every ADS skill's references folder, also served by MCP.
+  Keep regression cases
+  generic and validate computed geometry in a dummy compiled preview.
+
+- Preserve callable-object and factory-result recognition in the fast source
+  guard using lazy project type discovery. Name invalid scenario `exercises`
+  entries without discarding independent UI render coverage.
+
 ## 0.3.6
 
 - Isolate managed resource-graph output by session; reuse verified compiled

package/docs/MCP.md

@@ -188,6 +188,16 @@ resources. No arbitrary filesystem reader is exposed. Prefer bounded tools for
 large catalogues; explicit resource reads can enter model context and a client
 may truncate large payloads.
 
+`ads_check` and `ads://project/checks` return nonblocking atomic composition
+warnings under `advisories` with `severity: "warning"`, related source declarations
+and `guidanceUri: "ads://guides/atomic-styles"`. Read that guide for causes and
+component-level fixes. The full guide lives in every ADS skill as
+`references/atomic-styles.md` for standalone clients; MCP serves the packaged
+[skill-local reference](../skills/ads-designer/references/atomic-styles.md).
+Guarded mutation results preserve these warnings without rejecting valid source.
+An overlap warning is a review signal; failed registered rendered checks remain
+blocking.
+
 ### Behavioral verification
 
 Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -34,8 +34,10 @@
     "generate:icons": "node scripts/generate-icons.mjs",
     "sync:skill-starter": "node scripts/sync-skill-starter.mjs",
     "check:skill-starter": "node scripts/sync-skill-starter.mjs --check",
+    "sync:skill-references": "node scripts/sync-skill-references.mjs",
+    "check:skill-references": "node scripts/sync-skill-references.mjs --check",
     "lint": "npm run lint:tool",
-    "lint:tool": "npm run check:skill-starter && oxlint --deny-warnings src preview-client showcase-client mcp-explorer tests/*.test.mjs scripts/build-ads-tool.mjs scripts/pack-ads-tool.mjs",
+    "lint:tool": "npm run check:skill-starter && npm run check:skill-references && oxlint --deny-warnings src preview-client showcase-client mcp-explorer tests/*.test.mjs scripts/build-ads-tool.mjs scripts/pack-ads-tool.mjs scripts/sync-skill-references.mjs",
     "lint:project": "npm run lint:ds && npm run lint:style && npm run check:skill-starter",
     "lint:ds": "node dist/cli.mjs lint-config && node dist/cli.mjs check && oxlint --deny-warnings --config .ds/oxlintrc.json src design-system",
     "lint:style": "biome lint --config-path=biome.css.json .",