@reqvire-org/ads 0.0.0-stage → 0.3.0

package/dist/skills/ads-import/references/tokens.md

@@ -0,0 +1,96 @@
+# Shared token contract and value imports
+
+## Distinguish identity from value
+
+A shared contract defines token names, meanings, categories, expected value types,
+and alias relationships. Project themes supply concrete values and overrides.
+For example, `--accent` remains the accent-color token when one project uses
+rose and another uses blue. That value difference does not require a new token
+name, a namespace, or a conflict prompt.
+
+Read source/target token directories, style entries, theme definitions, typed
+registries/helpers, and generation inputs. Follow imports outside the nominal
+token directory. Inventory the complete shared contract, including unused names,
+theme/media conditions, aliases, and fallback chains. Use available schema
+metadata and documentation; infer carefully when only CSS definitions exist.
+
+A source with different names or incompatible meanings/types needs an explicit
+mapping to the destination contract. A color and a dimension sharing a name are
+a real incompatibility; two colors with different values are a normal theme
+difference. Resolve genuinely ambiguous mappings or migrations with the user.
+Keep canonical shared names and document needed compatibility aliases. Avoid
+creating a second source-prefixed token vocabulary as the default solution.
+
+## Component, pattern, and style imports
+
+Preserve every existing destination value, including starter defaults, theme
+overrides, and value fallbacks. Source values are not imported automatically just
+because a component uses them. Rewrite source references only when canonical
+names differ under an agreed semantic mapping.
+
+Synchronize missing shared definitions from the source contract. Add initial
+values for those new names, relevant aliases/theme overrides, and typed registry
+entries. Source defaults can initialize missing values; alias-based values should
+resolve against the destination's existing tokens. Preserve target-only contract
+extensions and update maintained generation inputs instead of generated files.
+
+For a truly empty destination, introduce the initial contract and values needed
+to use it. For an existing destination, update its registry/helpers and stylesheet
+entry narrowly rather than replacing the entire token directory or source API.
+Private measured component variables travel with the selected runtime component;
+they are not shared theme values.
+
+Reuse destination font and asset values when their tokens already exist. Copy
+assets only when required by a new definition or selected implementation, and
+retain applicable notices. Keep source resets and global element styling from
+overwriting destination theme behavior during an item import.
+
+## Explicit `tokens` mode imports values
+
+ADS token names and prefixes are fixed. New definitions must follow the existing
+architecture; components use `--ds-*`, patterns `--ux-*`, and owned scenario review layouts
+`--ux-*` (`--showcase-*` is reserved, not permission for fixture CSS). Never add source-brand aliases or configurable prefix support.
+Normalize nonconforming source references to canonical ADS names during import,
+preserving destination values unless this mode explicitly requests changes.
+
+`tokens` requests all source-provided values, including unused tokens and supported
+theme/media variants. Do not ask for individual token selection. Apply those
+values to compatible shared names, add missing definitions, and preserve target-only
+tokens and variants that the source does not define. Brand artwork is a separate
+`brand` selection; fonts required by imported values remain in scope. An item import can also
+include source values when the user explicitly requests both.
+
+This request authorizes the value changes. Do not ask again simply because an
+existing destination value will change. Clarify only unresolved semantic/type
+incompatibilities or genuinely ambiguous theme-scope mapping. Report the actual
+changes and validate affected consumers.
+
+Import aliases as value relationships, preserving their theme resolution rather
+than flattening them to literals. Convert values to the destination format when
+needed, including canonical reference names, units, and theme selectors. Use
+syntax-aware edits; substring replacement can corrupt similarly named tokens.
+Retain the destination's registry/API shape and adapt existing static value maps
+or SSR fallbacks when they need to agree with the imported values.
+
+Bring font declarations/assets required by the new values and resolve URLs from
+their new owners. Preserve notices and integrate existing extraction/asset-copy
+tooling. Value import does not require copying unrelated reset rules, global
+element styles, theme-provider implementations, build configurations, or other
+components. Integrate only the mechanisms necessary to apply the values correctly.
+
+## Verify the chosen mode
+
+For item imports, check that existing values and overrides remain unchanged,
+missing shared definitions are represented, and all imported references resolve
+through the canonical contract. Compare behavior/motion mechanics separately
+from intentional destination-theme visual differences.
+
+For value imports, account for every source-provided value and variant. Check
+effective theme values, alias cycles/fallbacks, asset/font paths, registry/SSR
+consistency, and stylesheet order. A CSS build can succeed while undefined custom
+properties fall back or render incorrectly.
+
+Run relevant target checks and inspect existing/imported consumers for text
+metrics, spacing, colors, focus, layering, and motion where applicable. Record
+contract additions, value-import provenance, source revision, assets/notices,
+and significant theme effects in shared ADS documentation.

package/dist/skills/ads-motion/LICENSE.upstream

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/skills/ads-motion/README.md

@@ -0,0 +1,22 @@
+# Credits
+
+Adapted from [Emil Kowalski's skills](https://github.com/emilkowalski/skills),
+revision `2d228630ba1446365f614a108cb8252f1feda202`.
+
+| Upstream source at that revision | Material adapted here |
+|----------------------------------|-----------------------|
+| [animate](https://github.com/emilkowalski/skills/tree/2d228630ba1446365f614a108cb8252f1feda202/skills/animate) | Purpose/frequency, driver choice, easing/timing guidance, interaction recipes |
+| [review-animations](https://github.com/emilkowalski/skills/tree/2d228630ba1446365f614a108cb8252f1feda202/skills/review-animations) | Review categories and before/after/why reporting |
+| [improve-animations](https://github.com/emilkowalski/skills/tree/2d228630ba1446365f614a108cb8252f1feda202/skills/improve-animations) | Source audit and executable implementation plans |
+| [find-animation-opportunities](https://github.com/emilkowalski/skills/tree/2d228630ba1446365f614a108cb8252f1feda202/skills/find-animation-opportunities) | Purposeful, limited recommendations grounded in existing interactions |
+| [animation-performance](https://github.com/emilkowalski/skills/tree/2d228630ba1446365f614a108cb8252f1feda202/skills/animation-performance) and [performance cheatsheet](https://github.com/emilkowalski/skills/blob/2d228630ba1446365f614a108cb8252f1feda202/performance-cheatsheet.md) | Property/driver analysis, profiling, layout and style cost, cleanup |
+
+The local guides adapt these workflows to project-owned ADS source, shared token
+semantics, local motion values, public APIs, measured geometry boundaries,
+documented exceptions, and real build/browser checks. They do not copy upstream
+library-selection instructions or require its libraries and numeric defaults.
+
+[LICENSE.upstream](LICENSE.upstream) retains the full MIT license and
+Copyright (c) 2026 Emil Kowalski for copied/adapted upstream material. Keep it
+with that material on redistribution. It does not license unrelated project
+code or a separately studied component library.

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

@@ -0,0 +1,217 @@
+---
+name: ads-motion
+description: Implement, review, audit, or profile web animation in a project's local design system. Use for motion purpose, easing, timing, origins, interruptibility, reduced motion, and rendering performance while preserving token and component ownership.
+---
+
+Accept a component/pattern name, file, screen, or project path and infer the mode
+from the request. Inspect before proposing motion: read `docs/ARCHITECTURE.md` when
+present (or the existing architecture guide), the project's ADS guide,
+public exports, item README, motion tokens, styles, and relevant state logic.
+Preserve its framework and existing animation stack. Author component/pattern
+CSS motion in the required Linaria pipeline; keep dynamic geometry within the
+project's documented boundaries.
+
+React and native Preact are supported. Preserve the target runtime in both
+production and scenario builds; never alias React to Preact just to shrink a
+preview. Native Preact uses its own JSX transform, hooks and DOM events (live
+text updates use `onInput`). Native SVG uses DOM names such as `stroke-width`,
+not React presentation aliases. Keep Linaria extraction and the same public APIs.
+The shipped empty starter uses React; the tool repository's working example
+uses Preact. Neither is a component dependency of the receiving project.
+
+ADS is tooling only. Work on project-owned source; do not install a component
+library or animation dependency merely because an upstream example uses one.
+Use the actual local public API for demos and tests. An empty ADS needs a defined
+interaction/component before motion can be implemented.
+
+## Choose the mode
+
+When ADS MCP is connected, use `ads_status`/`ads_catalog` to find public UI, guides
+and addressable scenarios. Registered Apps render real project fixtures, while
+`ads_tokens` inspects motion values. Use the normal showcase for unsupported
+host behavior and performance measurement; HTML delivery does not verify motion.
+Resolve served skill references relative to this `SKILL.md` URI and load them
+lazily. Ordinary instruction reads do not establish native skill activation.
+Use the returned `projectRoot` and `project.commands`; the connected ADS may be
+inside a different or nested repository. Inspect the selected public API, owning
+source/available guides and relevant tokens, then mount its discovered scenario.
+Metadata and source reads do not prove rendered behavior.
+
+When `ads_status.mutations.enabled`, discover the owner with `ads_units`, read
+relevant ranges with `ads_read_file` and send only a Git unified diff through
+`ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
+scenarios and fixtures; imported peers remain separate. `tokens` is the token
+foundation unit. Unit discovery and file ownership are distinct from preview IDs.
+Include only that owner's required re-exports in the public entry. Use
+`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
+patches in their owner. Shared styles/helpers use `foundation`, root guides use
+`documentation`, and branding/fonts use their discovered `assets/*` unit.
+Intentional configuration, rule exceptions, registered guard code and compiler
+changes use `configuration`; validate the proposed settings and keep mandatory
+ADS gates. For binary/large assets, generate `git diff --binary --full-index` into
+`.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
+stay out of model context. Binary changes require Git. When editing is disabled,
+use the client's normal source-editing tools.
+
+Before trusting a preview after edits, check `ads_status.build` or
+`ads://project/build`. Fix build diagnostics in owned source; an older view or
+unreported freshness is not evidence of current code. Notifications may not
+reach the agent.
+
+| Request | Reference | Outcome |
+|---------|-----------|---------|
+| Build or change an animation | [build.md](references/build.md) | Implement purposeful motion in its owning component/pattern |
+| Review existing motion | [review.md](references/review.md) | Findings grounded in source and observed behavior |
+| Audit a component or screen, or find opportunities | [audit.md](references/audit.md) | Prioritized findings or a concrete implementation plan when requested |
+| Investigate jank or rendering cost | [performance.md](references/performance.md) | Evidence, a focused fix when requested, and a comparison |
+
+Load the relevant reference and [verification.md](references/verification.md);
+do not read all mode guides for a small task. A review/audit reports findings;
+implement when requested. If a request spans modes, use only those needed to
+complete it. Resolve routine choices from project contracts and existing
+authorization; ask only for a material unresolved product decision.
+
+## Keep ADS ownership
+
+Use the project showcase as the shared motion review surface for agents and
+humans. Use the connected MCP runtime URL or start `ads showcase`, with a configured
+project preview compiler. Keep the frame
+minimal and neutral. Showcase/scenario files define no CSS, custom classes, or
+widget markup; change the owning ADS pattern when a layout is needed.
+Scenarios use the same public ADS source,
+tokens, and styles as the app. Add repeatable triggers and relevant states,
+interruption cases, and reduced-motion examples; do not build separate demo
+animations or reproduce a control inside the mock. Fix motion in the shared
+owner so both consumers receive it. Run ADS/project guards for both builds and
+give a full running URL or exact command for review. Static guards and a still
+screenshot do not establish animation quality or parity.
+
+The showcase is a minimal shell plus an MCP client and Apps host, supplied by ADS
+tooling. It discovers Tokens/Components/Patterns/Composition entries through MCP
+tools and renders their scenarios in the preview App. Navigation, theme and
+pane/header visibility belong to the tool client. Do not create page files,
+copy its shell into the project or assemble a second catalogue/rendering pipeline.
+
+When MCP is connected, open the running URL from `ads_status`. Otherwise run the
+installed `ads showcase` or the project's `dev:showcase` script. Do not launch a
+second runtime/compiler for the same connected project. A configured project
+preview watcher publishes a shared graph on first demand and after source
+changes. The built-in client refreshes discovery and the active scenario in the
+same App after a successful build. Shared runtime, foundation CSS, fonts and
+selected scenario modules load through MCP
+resources inside the sandboxed App. Never inject project styles/runtime into
+the outer host. Keep the configured framework, compiler and mount/unmount adapter
+consistent; scenario teardown must release owned timers, portals and workers.
+The host shows errors and marks retained output as stale. Other hosts may need an
+explicit preview-tool invocation. Compilation remains project-owned and required
+for TSX/Linaria; it is automatic, not eliminated.
+
+Reusable review layouts belong in public project ADS patterns, while scenario
+files define no CSS, custom classes or widget replicas. Keep real presentation in
+its component/pattern owner. The tooling shell's CSS is outside that project
+contract. Legacy custom showcase pages may be retained during migration; new
+projects require no TokensPage/ComponentsPage/PatternsPage/CompositionPage files.
+
+Colocate `Scenario.tsx` and `fixture.ts` with tokens and each component/pattern; flat owners
+may use `<Owner>.scenario.tsx` and `<Owner>.fixture.ts`. Put larger entries under
+`composition/<Name>/Scenario.tsx` with their own `fixture.ts`. Export a default
+zero-input mountable view and literal metadata, for example
+`export const scenario = { title: "Button states", covers: ["Button"] };`.
+Import the real UI from the public ADS alias. Keep fixture inputs, simulated
+services and initial state/callback adapters beside the scenario. Empty fixtures
+are valid for an entry with no inputs. Extra development helpers use a
+`scenario/` or `fixtures/` subfolder, or `<Owner>.scenario-adapter.ts`, so guards
+recognize their role even beside runtime code. Never require a page, router or store to
+initialize the entry. Several contextual public parts may share one scenario.
+
+IDs derive from ADS-relative filenames: both `components/core/Button/Scenario.tsx`
+and `components/core/Button.scenario.tsx` identify `components/core/Button`.
+Use one form, no duplicate IDs or hand-maintained registry. Renames change IDs.
+The showcase and external hosts mount the same discovered entry. The Vite
+adapter uses `previewEntriesPlugin` and `createPreviewResources` with
+`runScenarioCompiler` to publish the shared graph. Its framework mount adapter
+returns cleanup; the project owns rendering and Linaria extraction. The older
+`scenarioRegistryPlugin` is only for retained legacy browsers. MCP discovers
+metadata without importing executable TSX. Existing apps need an explicitly
+integrated compiler; init alone adds no compiler or extraction setup.
+Use `ads_scenarios` (query/kind/limit) and `ads_show_scenario({id})` to open an exact
+entry. Check its build freshness; HTML delivery is not browser verification.
+If Apps or resource forwarding are unavailable, open that scenario in the real
+showcase, using the tool result's URL. Do not build a preview-only replica.
+
+For a production screen, find and render the application's public screen pattern.
+Its owner supplies structure, controls, layout and presentation. Scenario fixtures
+supply data/state/callbacks. Move shared presentation into a pattern if needed,
+preserving existing behavior and lazy imports, workers, caching and cancellation.
+Do not reassemble an alternative screen or substitute placeholder content.
+Screen reuse remains skill guidance, not a dedicated screen-parity lint.
+
+Resolve `scenario-contract`, `scenario-render` and `scenario-coverage` findings
+with meaningful entries. Every public renderable component and pattern needs an
+addressable scenario, including unused exports; types/constants/utilities do not.
+Only public render references reachable from the default entry count. Tests and
+unused imports/functions do not. Static reachability does not prove successful
+mounting, correct content, every branch/state or visual parity: open each affected
+entry independently and verify real behavior at narrow/wide sizes in both themes.
+The older `showcase-coverage` policy separately checks application references.
+
+Token previews use that same scenario pipeline. Colocate a token scenario and
+fixture under the configured token directory. Use static metadata
+`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
+literal const fixture fields; names/sample text are fixture data, values come
+from the real foundation CSS. Reuse a public project review pattern for styled
+samples. The minimal starter's foundation value scenario can have `covers: []`.
+Every declared token needs reachable scenario coverage; adding/removing a token
+requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
+and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
+count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
+resource compiler, omitting category opens the first project token scenario.
+Legacy compilers retain the generic definition inspector. Use `ads_tokens` for
+source definitions and values; inspecting definitions does not prove UI parity.
+The tool keeps the shared naming contract; sample templates and their token
+lists belong to the project.
+
+Scenarios, colocated fixtures and helpers are development-only. Never export them
+from the runtime barrel or import them in production, including through aliases,
+re-exports or dynamic imports. They may not import application stores, routers,
+providers or HTTP clients. Live business data is application-owned; UI uses typed
+inputs or injected services/callbacks. Direct global fetch/XHR/WebSocket/EventSource
+is rejected; custom clients and computed access require review/project guards.
+Use local simulated services in fixtures. Tests may import fixtures; load real
+foundation CSS rather than assigning shared token values in JavaScript. Keep
+full-app integration harnesses and workflow coverage in application test support.
+
+
+
+Register component/project Oxlint plugins and rules in `ds.config.json`. Use
+scoped `oxlint.overrides` for justified file-specific settings; never edit
+`.ds/oxlintrc.json`. These overrides configure Oxlint, not the independent
+architecture checks in `ads check`. Measured renderer properties and documented
+non-state hooks use explicit `boundaries`; shared token writes and primitive
+state overrides cannot be allowlisted. Add generic architectural protections to
+ADS core and keep domain/component-specific rules registered in project setup.
+
+- Motion constants belong in the project's token layer. Shared token meanings
+  stay compatible across projects; values can differ. Reuse a fitting token or
+  add a narrowly scoped one. Do not alter global timing to tune one component.
+- Components own state motion, layout, focus, gestures, and reduced-motion
+  behavior. Patterns own composition transitions. Applications supply state,
+  data, and callbacks through public props.
+- Preserve documented exceptions and accepted upstream parity. A Sonner-derived
+  stack may deliberately use a 400 ms curve and height transitions; generic
+  duration/property advice is not enough to classify that as a defect.
+- Measured geometry may use a private, documented, allowlisted boundary.
+  Keep visual policy in tokens and styles. A performance recommendation to write
+  `element.style.transform` is not permission to bypass local architecture rules.
+- Add component-local lint only for statically provable misuse of the public
+  contract. Profiling, perceptual quality, and arbitrary duration thresholds
+  cannot be reliably enforced by a blanket lint rule.
+
+Record public behavior, token hooks, important motion choices, validation,
+source links/revision, and accepted differences in the item's local README.
+Preserve copyright and applicable license notices for copied/adapted source;
+native integration does not by itself make that material independent.
+
+This workflow adapts Emil Kowalski's animation skills. See
+[README.md](README.md) and [LICENSE.upstream](LICENSE.upstream) for provenance.

package/dist/skills/ads-motion/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ADS Motion"
+  short_description: "Build, review, audit, and profile local ADS animation"
+  default_prompt: "Use $ads-motion to review animation in this project’s local design system."

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

@@ -0,0 +1,44 @@
+# Audit or plan motion
+
+Start with the requested component/screen, not the entire repository. Map its
+public inputs, state transitions, motion tokens, styles, geometry helpers,
+timers, cleanup, and tests. Read nearby call sites to understand frequency and
+composition. Track documented tradeoffs and accepted upstream comparisons.
+
+Review using the categories in [review.md](review.md). Expand into rendering
+performance only where observations or source evidence justify it; use
+[performance.md](performance.md) if profiling is requested. An audit does not
+silently apply production changes or rewrite configuration.
+
+## Opportunities
+
+When requested, suggest a small set of motion opportunities grounded in actual
+state changes: new content, removal, selection, disclosure, or spatial movement.
+For each, explain the user purpose, frequency, owner, and reduced-motion state.
+Reject ideas that delay frequent input, duplicate existing feedback, or require
+an unrelated library. It is valid to recommend no new animation.
+
+## Implementation plans
+
+If a plan is requested, make it executable against the inspected source:
+
+1. Name the problem and its reproduction, including observed vs source-only
+   evidence. Record the revision or inspected snapshot; do not invent a Git
+   commit when the project has no committed source.
+2. Identify owner files, public API implications, existing tokens, and any new
+   token definitions. Explain the intended state transitions and cancellation.
+3. Describe the smallest coherent implementation, including geometry and exit
+   cleanup. Give exact changes where they resolve ambiguity; keep raw visual
+   constants in the token layer rather than embedding them in component samples.
+4. List regression cases, real project commands, browser comparisons, and
+   practical limitations. Include reduced motion, interruption, and relevant
+   pointer/keyboard paths.
+5. Record accepted differences, affected neighbors, source credits/notices, and
+   the local README updates needed after implementation.
+
+Write a plan file only when the task or project workflow calls for one. Do not
+create a parallel documentation tree for a small review. When implementation is
+authorized, recheck the current source, execute the relevant plan, and update
+the documentation to match what actually shipped. Ask only when a required
+decision remains unresolved; routine implementation does not need another
+confirmation after the user has already asked for it.

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

@@ -0,0 +1,81 @@
+# Implement motion
+
+## Decide what motion explains
+
+Identify the trigger, user purpose, affected state, and expected frequency.
+Motion can show where a surface came from, confirm input, connect changing
+states, or preserve context when layout changes. Skip decorative movement that
+slows a repeated task. Frequent keyboard navigation usually benefits from
+immediate state changes; test the actual workflow before adding travel/delay.
+
+Describe the start, end, interrupted, dismissed, and reduced-motion states.
+Decide when content becomes interactive and when it can unmount. Avoid invisible
+focusable controls and completion callbacks that fire for a canceled transition.
+Animation must not delay the underlying action or make controls unusable.
+
+## Choose the driver
+
+Use the project's existing approach. CSS transitions suit retargetable state
+changes; keyframes suit a fixed sequence; WAAPI can give explicit cancellation
+and completion; an existing motion runtime may help with gestures, springs, or
+presence. Add a dependency only when the task needs it and simpler existing
+mechanisms do not cover the interaction. Check current official API/browser
+documentation before relying on version-specific behavior.
+
+Prefer transform and opacity when they express the desired effect. A real
+height change, accordion, or variable-height stack may need measured layout.
+Keep those reads/writes in the existing geometry boundary and verify their cost.
+Don't replace an agreed interaction with a visual approximation just to avoid
+layout animation. Animate a wrapper when its child already owns a transform.
+
+For rapid toggling, retarget from the current presentation rather than replaying
+an entry keyframe from zero. Use the owning state machine to distinguish pending,
+entered, leaving, and removed states. Handle completion, interruption, reduced
+motion, and unmount without leaking listeners or stranding hidden content.
+
+## Tune through tokens
+
+These are starting ranges from the upstream guidance, not pass/fail rules:
+
+| Interaction | Typical starting point | What to assess |
+|-------------|------------------------|----------------|
+| Press/hover feedback | 100–200 ms | Input feels immediate; keyboard activation remains equivalent |
+| Menu, tooltip, small popover | 150–250 ms | Origin follows its trigger/placement; nearby repeat tooltips can be immediate |
+| Dialog or surface transition | 200–300 ms | Distance and scale stay restrained; exit can be quicker |
+| Large drawer or notification stack | Component-specific, sometimes 300–500 ms | Travel, coupled states, and established parity justify the timing |
+
+Choose existing tokens by their meaning and effect, not just the closest number.
+If needed, define raw duration, easing, distance, or scale in the token layer and
+consume it through the owner's styles. Preserve theme values unless the request
+is explicitly a token-values/theme change.
+
+Use deceleration for a newly appearing surface and an origin tied to its source.
+Use balanced easing for a continuous move between visible positions, and linear
+motion for an elapsed-time indicator. Springs can suit direct manipulation
+when already supported; decorative bounce should not obscure a frequently used
+control. Keep neighboring interactions coherent without forcing one curve on
+all mechanics.
+
+## Interaction recipes to adapt
+
+- Button: a restrained press state, kept inside the primitive. Begin visual
+  feedback on press; commit ordinary click actions on release/activation so
+  cancellation and keyboard behavior remain intact.
+- Popover/menu: a small opacity/scale transition from the trigger edge. Keep
+  placement flips, portal location, focus, and dismissal in the existing API.
+- Dialog/drawer: animate its surface and overlay as coordinated states. Verify
+  scroll locking, focus trap/restoration, and repeated open/close during entry.
+- Accordion: animate the content container while maintaining correct expanded
+  state and hidden/focus behavior. Handle changing content after measurement.
+- Notification stack: use the actual host/store and documented lifecycle.
+  Exercise variable heights, additions during exit, hover/focus expansion,
+  swipe cancel/dismiss, loading completion, and timers. Do not assume the API or
+  lifetime rules are identical to Sonner.
+- Tabs: keep the selected content readable and keyboard state immediate.
+  Animate the indicator only if it helps locate the new selection; don't add
+  presence transitions that duplicate active content for assistive technology.
+
+Honor the local reduced-motion policy. Depending on the interaction, use instant
+state changes or a restrained opacity change; remove travel, bounce, or looping
+motion where required. Preserve all information and lifecycle behavior when
+transitions have no duration. Don't require animation merely to provide feedback.

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

@@ -0,0 +1,55 @@
+# Investigate animation performance
+
+Treat source inspection as a hypothesis. Reproduce the reported interaction
+with realistic content/load and profile it before claiming a performance cause.
+Record browser, device, viewport, fixture size, motion preference, driver, and
+test conditions. A desktop screenshot cannot establish smoothness on mobile.
+
+## Find the bottleneck
+
+Inspect a short performance recording around the actual interaction:
+
+- Long main-thread tasks and JavaScript cost, including per-frame React renders.
+- Repeated style recalculation, forced synchronous layout, paint, and raster work.
+- Frame cadence and whether a pause correlates with network/data work rather
+  than the animation itself.
+- Animated property, driver, affected subtree, layer count, and cancellation.
+
+Transform/opacity often avoid layout and paint, but compositing is not guaranteed
+by a property name or `translate3d`. Filters, clips, layer size, stacking contexts,
+the driver, and browser can change the result. Test a claim that a particular
+animation runs off the main thread in the actual supported runtime.
+
+CPU throttling helps expose main-thread cost; it is not an accurate weak-GPU or
+real-device simulation. State that limit. Do not report a frame-rate improvement
+without comparable recordings or measurements.
+
+## Fix the measured cause
+
+Keep reads and writes separated to avoid layout thrashing. Reuse measured
+geometry when it stays valid, and update it when content/viewport changes.
+Avoid rerendering a large tree every pointer frame when the local documented
+geometry/animation boundary can carry transient displacement instead.
+
+Inherited custom-property updates can broaden style recalculation, depending
+on scope and dependencies. Narrow their scope where possible and measure.
+Direct property writes or a different driver may help in some cases, but do not
+bypass the project's style guard. If a new measured boundary is necessary,
+document its property allowlist and validate its enforcement. Keep color,
+typography, timing, easing, and scale policy in tokens and owner styles.
+
+For expensive blur/shadow/paint effects, first reduce the affected area or avoid
+animating the expensive property if that preserves the intended appearance.
+Do not remove an established visual interaction solely on general advice.
+Use `will-change` only when measurement supports it, scope it narrowly, and
+remove temporary hints when appropriate. Permanent layer promotion can increase
+memory and raster cost.
+
+Handle cleanup for animation frames, listeners, observers, animation handles,
+and exit callbacks. Keep loading/hidden-document timer behavior aligned with
+the item contract. Reduced motion should preserve lifecycle correctness rather
+than relying on a transition event that never occurs.
+
+Compare the same case before/after. Verify normal content, rapid interruption,
+focus, reduced motion, and relevant gesture states. Report measurements and
+remaining limits separately from subjective visual observations.

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

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

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

@@ -0,0 +1,39 @@
+# Verify motion in the project
+
+Read the target's package scripts and component guide. Use existing lint,
+typecheck, build, and meaningful behavior tests; tooling checks do not prove
+focus, timers, gestures, or animation quality. Do not assume that this checkout's
+`build:project` or `test:toast` script exists in another project.
+
+For source-only review, state that rendered behavior was not checked. For
+implementation or profiling, use an isolated browser context and the real
+showcase/app public API. A fake HTML replica cannot validate the implementation.
+Preserve the user's open tabs. Stop temporary servers unless a running preview
+was requested.
+
+## Interaction coverage
+
+Exercise the changed behavior and relevant boundaries:
+
+- Enter, update, exit, reopen, and reversal while a transition is in progress.
+- Rapid repeated input and simultaneous additions/removals where supported.
+- Variable content height, narrow containers, viewport changes, and theme.
+- Keyboard activation, focus entry/restoration, hidden-content inertness, and
+  pointer/touch cancellation where the component owns those mechanics.
+- Reduced motion, zero-duration cleanup, unmount, and background/foreground
+  timers where those affect the local contract.
+
+Observe transition start, intermediate states, and settled state. A final-state
+screenshot misses jumps, delayed exits, and interruption defects. Use recordings,
+sampled frames, or timing assertions when they answer the actual question.
+
+If matching an external reference, use the actual pinned upstream package in an
+isolated harness with comparable inputs, options, viewport, and interactions.
+Record version, dependencies, and license notices. Keep that harness out of the
+production bundle and remove temporary copies/processes when comparison is done.
+Document intended differences rather than silently losing accepted parity.
+
+Put API/motion rationale, token hooks, accepted differences, meaningful tests,
+and provenance in the component-local README. Shared architecture and the
+geometry/lint contract belong in the project ADS guide. Add local lint only when
+it establishes a concrete misuse and has accepted/rejected regression cases.

package/dist/token-policy.mjs

@@ -0,0 +1,10 @@
+import { readFileSync } from "node:fs";
+
+export const tokenContract = JSON.parse(readFileSync(new URL("./contracts/tokens.json", import.meta.url), "utf8"));
+
+export function isSharedToken(name) {
+  return name in tokenContract.tokens || tokenContract.naming.names.includes(name)
+    || tokenContract.naming.prefixes.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
+}
+
+export const foundationFiles = ["fonts.css", "colors.css", "typography.css", "spacing.css", "elevation.css", "base.css"];