cast

The Illusionist. How the cast pipeline scans your stack, states an interaction thesis, implements motion in your own APIs, and audits itself.

/genjutsu:cast gives an interface motion. It adapts to what is already there, which makes it the right entry point for anything short of a full visual rebuild: a hover state, a section, a scroll narrative, a whole page that feels inert.

The pipeline

Seven stages. Two of them are gates where nothing proceeds without you.

1. Scan

Before asking you anything, it reads the project. On web that means package.json for the framework, the CSS layer, and any animation library. On Apple it means Package.swift or the Xcode project, distinguishing iOS from macOS by platform declaration or SDK root. On Android it means the Gradle files, including whether the Kotlin Multiplatform and Compose plugins are both present.

It also works out whether the context is mobile, desktop, or both, and notes whether the project mixes modern UI with legacy layouts (XIBs, storyboards, layout XML, setContentView).

The scan decides which modules load later. You do not get asked what stack you are on, because the answer is in the repository.

2. Discover

Skipped when your request is already specific. “Add a hover scale on this button” needs no interview.

Used when the request is open-ended. “Make this page feel more alive” could go in a dozen directions, so it asks: mood, references, constraints, what is explicitly out of scope. One question at a time, because the second question depends on your answer to the first.

Vague answers get pushed on rather than silently interpreted. “Something modern” comes back as a choice between concrete references, or as the inverse question, what would feel wrong.

3. Scope

The rule this table exists to enforce: a hover effect never justifies a scroll-driven animation pipeline.

4. Thesis, and this is a gate

One sentence, naming the feel and the technique. Real examples:

This dropdown will use 150ms CSS micro-transitions with slide plus fade, for a snappy, modern feel.

This hero will combine scroll-triggered parallax with staggered text reveals, for cinematic impact.

This SwiftUI tab transition will use matchedGeometryEffect with a .smooth spring (response 0.5, damping 0.85), for a tactile, spatial feel.

Nothing is written until you validate it. If you reject it, it does not start over from zero; it asks what feels wrong and adjusts.

The reason this gate exists is arithmetic. A wrong thesis caught here costs one sentence. Caught after implementation, it costs the implementation.

5. Load

Motion foundations always. Then the platform layer (mobile or desktop principles), the stack modules the scan identified, and the audit module when the scope is full. See the module reference for what each one carries.

6. Implement

Light scope goes straight to code. Medium and full scope propose variants first, graded by how far they push:

Variant A (subtle) - the feel, and the technique, in one line. Variant B (balanced) - the feel, and the technique, in one line. Variant C (impressive) - the feel, and the technique, in one line.

You pick before anything is written. Whatever you pick, the validated thesis still governs; a variant is a way of expressing the thesis, not a way around it.

7. Audit

Not optional, not skipped because the result looks good.

Every stack is checked for reduced-motion support, exit animations, absence of layout-property animation, visible focus, complete interactive states, and consistency with the project’s existing tokens. Web adds contrast at 4.5:1, a verified frame budget, no clickable divs, aria-hidden on decorative motion, and four breakpoints (375, 768, 1024, 1440). Compose adds recomposition counts and frame timing on a mid-range baseline. SwiftUI adds the Hitches instrument, accessibility labels, Reduce Motion on, and Dynamic Type at 200%.

Writing a good request

The pipeline works better with a target than with an adjective.

• Name the element. “The pricing cards” beats “the page”.
• Name the feeling, not the technique. “Should feel physical, like they have weight” gives more to work with than “add a spring”.
• Name what you do not want. Constraints sharpen a thesis faster than aspirations do.
• Mention a reference if you have one. One URL can replace three questions.

When to use paint instead

Reach for paint when there is no visual direction to adapt to, or when the existing one is what you want gone. cast improves what exists; paint decides what should exist.