@reqvire-org/ads 0.3.7 → 0.3.9

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

@@ -81,6 +81,91 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Preserve custom-property arithmetic during extraction
+
+Custom properties can hold an unevaluated token stream that becomes arithmetic
+only after substitution into a later `calc()`. For example:
+
+```css
+--i: 2;
+--scale: var(--i) * 0.05 + 1;
+transform: scale(calc(-1 * var(--scale)));
+```
+
+The result is scale `0.9`: substitution does not add parentheses around the
+custom property. Some Linaria/Stylis extraction versions strip the whitespace
+around the bare `+`, leaving `0.05+1`. The browser then treats the transform as
+invalid. This can happen with CSS minification disabled. Source guards cannot
+prove what a later extractor emits.
+
+Use ADS's build-only resolver in **both** the application's Linaria configuration
+and its separately configured MCP preview builder:
+
+```js
+import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
+
+// In the project's Vite plugins:
+wyw({ tagResolver: linariaTagResolver });
+```
+
+The resolver keeps the project's installed atomic processor and preserves opaque
+custom-property values through its nesting/atomization pass. It does not add a
+browser runtime or alter token ownership. Existing projects must adopt it in
+each extraction pipeline; upgrading ADS alone does not rewrite custom builders.
+If an existing `tagResolver` handles other tags, delegate atomic imports to
+`linariaTagResolver(source, tag)` and retain the existing fallback. WyW config
+files also support this resolver when a build integration requires serializable
+inline options.
+
+For a source workaround, write a self-contained formula and consume it directly:
+
+```css
+--scale: calc(1 - var(--i) * 0.05);
+transform: scale(var(--scale));
+```
+
+This also produces `0.9`. Simply wrapping the old value in `calc()` while keeping
+the outer `-1 *` changes its grouping and result. Verify extracted CSS text and a
+computed style after any rewrite, including nested `var()` fallbacks/transforms.
+Do not globally insert spaces into already extracted CSS: that can change valid
+signed numbers, identifiers, strings or URLs.
+
+## 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`
@@ -101,6 +186,24 @@ 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`
@@ -108,14 +211,26 @@ 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
+`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.
+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 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.
+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/references/scenarios.md

@@ -0,0 +1,83 @@
+# Scenario render evidence and public class helpers
+
+Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
+diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
+
+## Public children can share their parent's scenario
+
+Declare the public parts actually demonstrated in `covers`, even when their
+parent renders them internally:
+
+```tsx
+// Runtime owner
+export function Part() { return <span>Content</span>; }
+export function Frame({ visible = true } = {}) {
+  return <section>{visible && <Part />}</section>;
+}
+
+// Colocated Scenario.tsx
+import { Frame } from "@ds";
+export const scenario = { title: "Frame", covers: ["Frame", "Part"] };
+export default function Scenario() { return <Frame />; }
+```
+
+ADS follows returned JSX through local components/helpers, aliases, registered
+framework factories, memo/ref wrappers and context providers. Fixture props,
+spreads and destructuring defaults select the child path. An explicit
+`visible={false}` does not cover `Part`. When a condition remains unknown, only
+parts returned on every possible path receive transitive credit. Imports, unused
+JSX, event-handler bodies and uncalled functions do not establish child rendering.
+Only the explicitly declared `covers` entries acquire coverage; dependencies are
+not silently added to metadata or the catalogue.
+
+Tracing is bounded and does not execute the project. Recursion, written/escaped inputs,
+opaque external wrappers and unsupported control flow can prevent proof. The
+diagnostic explains known limits. Use meaningful fixture states or another real
+scenario; do not make a valid public part private or duplicate it in a parent
+just to satisfy a guard. Static evidence does not establish successful mounting,
+visibility, interaction, every state or visual parity. Verify those in the built
+App and registered browser checks.
+
+## Scenarios may consume verified public style helpers
+
+A deliberately public helper can expose its owner's Linaria treatment:
+
+```tsx
+// Runtime owner
+const treatment = css`padding-inline: var(--space-4);`;
+export function controlClasses() {
+  return cx("control-hook", treatment);
+}
+
+// Scenario: consume the public API; define no styles here
+<PublicLink className={controlClasses()}>Documentation</PublicLink>
+```
+
+The sample token and APIs are illustrative; use the project's real exports and
+tokens. Import helpers through the public ADS entry. ADS traces helper calls,
+returns, local aliases, finite known selections and Linaria `cx` composition.
+Styling must originate in component/pattern Linaria through a public callable
+helper. A literal stable hook authored in that runtime owner may accompany the
+verified styles. Each nonempty return path needs actual Linaria declarations;
+empty templates and hook-only/string-only returns do not qualify.
+
+These are still rejected:
+
+```tsx
+<PublicLink className="custom-layout" />
+<PublicLink className={arbitraryPublicFunctionReturningAString()} />
+<PublicLink className={controlClasses({ className: "custom-layout" })} />
+```
+
+Scenario-supplied strings, generated styles in fixtures, private style imports,
+spoofed Linaria functions and untraceable results acquire no permission by being
+passed through a public function. Known className values in props/spreads receive
+the same provenance check. Opaque spreads remain outside complete source proof.
+An `exercises` entry records behavioral use; it never grants styling permission.
+
+Keep helper signatures compatible with the product API. Fix ownership/provenance
+in the runtime owner when genuinely wrong; retain intentional public APIs when
+reporting an unsupported trace. Demo-only sizing, framing and arrangement still
+belong in public review/layout patterns. A style helper is not permission to
+author a second design in the scenario. For cascade risks and extraction issues,
+read [atomic-styles.md](atomic-styles.md).

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

@@ -44,10 +44,18 @@ 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
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, 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
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. 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

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

@@ -81,6 +81,91 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Preserve custom-property arithmetic during extraction
+
+Custom properties can hold an unevaluated token stream that becomes arithmetic
+only after substitution into a later `calc()`. For example:
+
+```css
+--i: 2;
+--scale: var(--i) * 0.05 + 1;
+transform: scale(calc(-1 * var(--scale)));
+```
+
+The result is scale `0.9`: substitution does not add parentheses around the
+custom property. Some Linaria/Stylis extraction versions strip the whitespace
+around the bare `+`, leaving `0.05+1`. The browser then treats the transform as
+invalid. This can happen with CSS minification disabled. Source guards cannot
+prove what a later extractor emits.
+
+Use ADS's build-only resolver in **both** the application's Linaria configuration
+and its separately configured MCP preview builder:
+
+```js
+import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
+
+// In the project's Vite plugins:
+wyw({ tagResolver: linariaTagResolver });
+```
+
+The resolver keeps the project's installed atomic processor and preserves opaque
+custom-property values through its nesting/atomization pass. It does not add a
+browser runtime or alter token ownership. Existing projects must adopt it in
+each extraction pipeline; upgrading ADS alone does not rewrite custom builders.
+If an existing `tagResolver` handles other tags, delegate atomic imports to
+`linariaTagResolver(source, tag)` and retain the existing fallback. WyW config
+files also support this resolver when a build integration requires serializable
+inline options.
+
+For a source workaround, write a self-contained formula and consume it directly:
+
+```css
+--scale: calc(1 - var(--i) * 0.05);
+transform: scale(var(--scale));
+```
+
+This also produces `0.9`. Simply wrapping the old value in `calc()` while keeping
+the outer `-1 *` changes its grouping and result. Verify extracted CSS text and a
+computed style after any rewrite, including nested `var()` fallbacks/transforms.
+Do not globally insert spaces into already extracted CSS: that can change valid
+signed numbers, identifiers, strings or URLs.
+
+## 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`
@@ -101,6 +186,24 @@ 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`
@@ -108,14 +211,26 @@ 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
+`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.
+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 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.
+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/references/scenarios.md

@@ -0,0 +1,83 @@
+# Scenario render evidence and public class helpers
+
+Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
+diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
+
+## Public children can share their parent's scenario
+
+Declare the public parts actually demonstrated in `covers`, even when their
+parent renders them internally:
+
+```tsx
+// Runtime owner
+export function Part() { return <span>Content</span>; }
+export function Frame({ visible = true } = {}) {
+  return <section>{visible && <Part />}</section>;
+}
+
+// Colocated Scenario.tsx
+import { Frame } from "@ds";
+export const scenario = { title: "Frame", covers: ["Frame", "Part"] };
+export default function Scenario() { return <Frame />; }
+```
+
+ADS follows returned JSX through local components/helpers, aliases, registered
+framework factories, memo/ref wrappers and context providers. Fixture props,
+spreads and destructuring defaults select the child path. An explicit
+`visible={false}` does not cover `Part`. When a condition remains unknown, only
+parts returned on every possible path receive transitive credit. Imports, unused
+JSX, event-handler bodies and uncalled functions do not establish child rendering.
+Only the explicitly declared `covers` entries acquire coverage; dependencies are
+not silently added to metadata or the catalogue.
+
+Tracing is bounded and does not execute the project. Recursion, written/escaped inputs,
+opaque external wrappers and unsupported control flow can prevent proof. The
+diagnostic explains known limits. Use meaningful fixture states or another real
+scenario; do not make a valid public part private or duplicate it in a parent
+just to satisfy a guard. Static evidence does not establish successful mounting,
+visibility, interaction, every state or visual parity. Verify those in the built
+App and registered browser checks.
+
+## Scenarios may consume verified public style helpers
+
+A deliberately public helper can expose its owner's Linaria treatment:
+
+```tsx
+// Runtime owner
+const treatment = css`padding-inline: var(--space-4);`;
+export function controlClasses() {
+  return cx("control-hook", treatment);
+}
+
+// Scenario: consume the public API; define no styles here
+<PublicLink className={controlClasses()}>Documentation</PublicLink>
+```
+
+The sample token and APIs are illustrative; use the project's real exports and
+tokens. Import helpers through the public ADS entry. ADS traces helper calls,
+returns, local aliases, finite known selections and Linaria `cx` composition.
+Styling must originate in component/pattern Linaria through a public callable
+helper. A literal stable hook authored in that runtime owner may accompany the
+verified styles. Each nonempty return path needs actual Linaria declarations;
+empty templates and hook-only/string-only returns do not qualify.
+
+These are still rejected:
+
+```tsx
+<PublicLink className="custom-layout" />
+<PublicLink className={arbitraryPublicFunctionReturningAString()} />
+<PublicLink className={controlClasses({ className: "custom-layout" })} />
+```
+
+Scenario-supplied strings, generated styles in fixtures, private style imports,
+spoofed Linaria functions and untraceable results acquire no permission by being
+passed through a public function. Known className values in props/spreads receive
+the same provenance check. Opaque spreads remain outside complete source proof.
+An `exercises` entry records behavioral use; it never grants styling permission.
+
+Keep helper signatures compatible with the product API. Fix ownership/provenance
+in the runtime owner when genuinely wrong; retain intentional public APIs when
+reporting an unsupported trace. Demo-only sizing, framing and arrangement still
+belong in public review/layout patterns. A style helper is not permission to
+author a second design in the scenario. For cascade risks and extraction issues,
+read [atomic-styles.md](atomic-styles.md).

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

@@ -46,10 +46,18 @@ 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
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, 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
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. 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

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

@@ -81,6 +81,91 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Preserve custom-property arithmetic during extraction
+
+Custom properties can hold an unevaluated token stream that becomes arithmetic
+only after substitution into a later `calc()`. For example:
+
+```css
+--i: 2;
+--scale: var(--i) * 0.05 + 1;
+transform: scale(calc(-1 * var(--scale)));
+```
+
+The result is scale `0.9`: substitution does not add parentheses around the
+custom property. Some Linaria/Stylis extraction versions strip the whitespace
+around the bare `+`, leaving `0.05+1`. The browser then treats the transform as
+invalid. This can happen with CSS minification disabled. Source guards cannot
+prove what a later extractor emits.
+
+Use ADS's build-only resolver in **both** the application's Linaria configuration
+and its separately configured MCP preview builder:
+
+```js
+import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
+
+// In the project's Vite plugins:
+wyw({ tagResolver: linariaTagResolver });
+```
+
+The resolver keeps the project's installed atomic processor and preserves opaque
+custom-property values through its nesting/atomization pass. It does not add a
+browser runtime or alter token ownership. Existing projects must adopt it in
+each extraction pipeline; upgrading ADS alone does not rewrite custom builders.
+If an existing `tagResolver` handles other tags, delegate atomic imports to
+`linariaTagResolver(source, tag)` and retain the existing fallback. WyW config
+files also support this resolver when a build integration requires serializable
+inline options.
+
+For a source workaround, write a self-contained formula and consume it directly:
+
+```css
+--scale: calc(1 - var(--i) * 0.05);
+transform: scale(var(--scale));
+```
+
+This also produces `0.9`. Simply wrapping the old value in `calc()` while keeping
+the outer `-1 *` changes its grouping and result. Verify extracted CSS text and a
+computed style after any rewrite, including nested `var()` fallbacks/transforms.
+Do not globally insert spaces into already extracted CSS: that can change valid
+signed numbers, identifiers, strings or URLs.
+
+## 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`
@@ -101,6 +186,24 @@ 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`
@@ -108,14 +211,26 @@ 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
+`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.
+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 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.
+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.