genjutsu

The art of illusion. Cast motion. Paint signatures.

Website  ·  Documentation  ·  Install  ·  Discussions

Creative coding skills for Claude Code, claude.ai and Cowork - transforms any interface from functional to exceptional through motion design, interaction patterns, and visual systems. Covers Web (React, Vue, Svelte, vanilla CSS, Three.js, Canvas), Android (Jetpack Compose, Compose Multiplatform), and Apple (SwiftUI iOS + macOS).

v3.0 - rebrand: this plugin used to be called creative-excellence. The skills /creative-excellence:creative-excellence and /creative-excellence:design-excellence are now /genjutsu:cast and /genjutsu:paint. See CHANGELOG.md for the migration steps if you had v2.x installed.

---

Documentation

genjutsu.athevon.dev is built with genjutsu itself. The ink on it is painted by your own scroll, and every mark is drawn in code, no image assets.

Page	What is in it
Overview	What genjutsu is, how the pieces fit, the shortest path to seeing something move
Install	Both surfaces, verifying the install, updating, uninstalling
cast	The seven-stage pipeline, its two validation gates, how to write a good request
paint	The five phases, the two theses, what lands in your repo
Modules	All fifteen, by family: foundations, web, Apple, Android
Principles	The rules the skills enforce, and why each one exists
FAQ	Plans, dependencies, cast against paint, what to check when output feels generic

---

Skills

/genjutsu:cast - The Illusionist

Takes any creative request and makes it exceptional. Adapts to your stack and scope.

Pipeline: Scan stack -> Evaluate scope -> Propose interaction thesis -> Load sub-skills -> Implement -> Mini-audit

• Detects your dependencies automatically across web (GSAP, Motion / Framer Motion, Three.js, CSS), Android (Jetpack Compose, Compose Multiplatform) and Apple (SwiftUI iOS / macOS)
• Proposes an interaction thesis before writing a single line of code, and asks how you want to see it first
• Scales from a single hover effect to a full scroll-driven page or a Compose SharedTransitionLayout flow
• Runs a quick audit on exit: reduced-motion, exit animations, recomposition, hitches, layout performance

/genjutsu:paint - The Master Painter

Builds a complete visual universe from scratch. Brainstorm first, implement second.

Pipeline: Brainstorm -> Define visual + interaction thesis -> Generate design system -> Implement -> Full audit

• Mandatory creative direction session before any code
• Shows the theses and the design system in the format you pick, instead of asking you to approve a palette as a list of hex codes
• Generates a persistent stack-aware MASTER.md design system (Tailwind/CSS for web, Theme.kt for Compose, Color+App.swift for SwiftUI, commonMain for CMP)
• Full audit at the end: motion gaps, accessibility, color consistency, responsive, performance, native hitches
• Optional MCP integration (Stitch, Nano Banana, 21st.dev Magic)

When to use which

Situation	Skill
"Add a scroll animation to this section"	/genjutsu:cast
"Make this dropdown feel snappy"	/genjutsu:cast
"Add a snappy spring to this Compose button"	/genjutsu:cast
"Polish the matchedGeometryEffect on this SwiftUI screen"	/genjutsu:cast
"Redesign the entire landing page"	/genjutsu:paint
"Build me a portfolio from scratch"	/genjutsu:paint
"Build a SwiftUI iOS app design system from scratch"	/genjutsu:paint
"Bootstrap a Compose Multiplatform design system"	/genjutsu:paint

Seeing what it proposes

Both skills stop and wait for your approval at a handful of points: the interaction thesis, the variants, the visual identity, the design system. A sentence cannot carry an easing curve and a list of hex codes cannot carry a palette, so before the first of those gates the skill asks how you want to see it.

Mode	What you get
Artifact	A live page. The easing curve plotted with its exact value, an element actually performing the motion with a replay button, the raw numbers, a reduced-motion toggle. For a design system: swatches with their contrast ratios, a real type specimen, the five states of every component.
Live preview	A throwaway route in your own project - real stack, real tokens, real components. On Compose or SwiftUI, a @Preview / #Preview scratch file. Deleted once you have approved.
Inline	The sentence, in the conversation. Still the right answer for a 150ms hover.

You are asked once. The choice holds for the rest of the session, later gates just announce the mode, and you switch by saying so. The preview is always throwaway: it exists to be looked at, never to become the implementation.

---

Sub-skills

Internal modules loaded dynamically by the orchestrators. Not invocable directly.

Foundation (always loaded)

Sub-skill	Scope	Files
motion-principles	Timing, easing, cross-platform reduced-motion API, BAD/GOOD do-not rules	SKILL + 3 references

Shared layers (loaded by context)

Sub-skill	Scope	Files
mobile-principles	Touch targets, no-hover doctrine, thumb zones, safe areas, gestures, mobile perf budgets	SKILL + 2 references
desktop-principles	Hover-mandatory, pointer precision, keyboard shortcuts, multi-window, focus management	SKILL + 2 references
design-audit	Multi-stack greps (web/Compose/SwiftUI), bundle size, Layout Inspector, Instruments Hitches	SKILL
ui-ux-pro-max	Design system intelligence (84 styles, 192 palettes, 74 font pairings, 25 charts, 22 stacks)	SKILL + data + scripts

Web stack

Sub-skill	Scope	Files
gsap	Core, timeline, ScrollTrigger, plugins	SKILL + 4 references
framer-motion	Motion and Framer Motion (same library, two package names) - AnimatePresence, layout, gestures, motion values	SKILL + 1 reference
css-native	Scroll-driven, View Transitions, @starting-style	SKILL + 1 reference
threejs-r3f	Three.js, React Three Fiber, shaders, postprocessing	SKILL + 2 references
canvas-generative	Particles, flow fields, noise, fractals, L-systems	SKILL + 1 reference

Android stack

Sub-skill	Scope	Files
compose-motion	animate*AsState, AnimatedVisibility, SharedTransitionLayout, springs, gestures	SKILL + 3 references
compose-graphics	M3 Expressive motion physics, AGSL shaders (Android 13+), Canvas/DrawScope	SKILL + 3 references
compose-multiplatform	KMP/CMP patterns, expect/actual, iOS/Android/Desktop interop	SKILL + 2 references

Apple stack

Sub-skill	Scope	Files
swiftui-motion	withAnimation, transitions, matchedGeometryEffect, PhaseAnimator, KeyframeAnimator, gestures	SKILL + 3 references
swiftui-graphics	Metal shaders (.colorEffect / .layerEffect / .distortionEffect), .visualEffect, Liquid Glass (iOS 26), Canvas	SKILL + 3 references

---

Installation

The short version is on the site: genjutsu.athevon.dev/docs/install. The long version, including partial installs, is below.

claude.ai (web/app)

Prerequisites: Plan Pro, Max, Team or Enterprise with "Code execution" enabled.

Option A - single bundle (recommended):

One upload, everything included (router + cast + paint + all sub-skills).

1. Download genjutsu.zip. That link always serves the newest release, so it never goes stale.
2. On claude.ai, go to Customize > Skills > Upload skill and upload genjutsu.zip.
3. Enable the toggle. Done - one skill, both cast and paint pipelines, all sub-skills bundled.

Want to confirm it mounted correctly? Follow the 2-minute smoke test in docs/claude-ai-testing.md.

How it shows up. The bundle installs as a single skill named genjutsu. In a normal chat it appears as one entry - invoke /genjutsu (or just describe your task) and it routes to the cast or paint pipeline internally. Surfaces that expose skills as individual commands (e.g. a code workspace) show /cast and /paint directly. Either way the pipelines need code execution enabled to load their sub-skills. Prefer /cast and /paint as separate entries everywhere? Use Option B.

Option B - individual skills:

Prefer separate skills, or only part of the stack? Upload the individual ZIPs (one per skill). Baseline for everyone: cast, paint, motion-principles, design-audit, ui-ux-pro-max. Then add per stack:

Your stack	ZIPs to upload (in addition to baseline)
Web only	mobile-principles, desktop-principles, gsap, framer-motion, css-native, threejs-r3f, canvas-generative
Android Compose only	mobile-principles, compose-motion, compose-graphics
iOS SwiftUI only	mobile-principles, swiftui-motion, swiftui-graphics
macOS SwiftUI only	desktop-principles, swiftui-motion, swiftui-graphics
Multi-target Apple (iOS + macOS)	mobile-principles, desktop-principles, swiftui-motion, swiftui-graphics
Compose Multiplatform	mobile-principles, compose-motion, compose-graphics, compose-multiplatform, swiftui-motion (if iOS target)

Build from source:

git clone https://github.com/AThevon/genjutsu.git
cd genjutsu
./package-for-claude-ai.sh
# dist/ has genjutsu.zip (the bundle) + 17 individual skill ZIPs

Claude Code (CLI)

Two slash commands, typed inside a Claude Code session:

/plugin marketplace add AThevon/genjutsu
/plugin install genjutsu

Then run /genjutsu:cast or /genjutsu:paint. You can pass the request on the same line: /genjutsu:cast make the pricing cards feel physical on hover.

The marketplace also accepts the full git URL if you prefer it: /plugin marketplace add git@github.com:AThevon/genjutsu.git.

Or as a git submodule in your dotfiles:

git submodule add git@github.com:AThevon/genjutsu.git claude/plugins/genjutsu
ln -sf ~/.dotfiles/claude/plugins/genjutsu ~/.claude/plugins/genjutsu

---

Cowork

Install it from the plugin panel, the same way as any other plugin, then invoke /genjutsu:cast or /genjutsu:paint.

/plugin marketplace add AThevon/genjutsu
/plugin install genjutsu

Cowork mounts skills under a per-session root rather than a fixed path, so sub-skill resolution probes for it - see Cowork compatibility for the resolution order, what the preview gate maps to on this surface, and why paint shortens itself for one-component requests here.

---

Architecture

genjutsu/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── skills/
│   ├── cast/SKILL.md                       <- orchestrator (Illusionist)
│   ├── paint/SKILL.md                      <- orchestrator (Master Painter)
│   └── _jutsu/                             <- internal sub-skills (never invoked directly)
│       ├── VERSIONS.md                     <- what every version claim was verified against
│       ├── motion-principles/              <- foundation, always loaded
│       ├── mobile-principles/              <- shared (touch contexts)
│       ├── desktop-principles/             <- shared (pointer/keyboard contexts)
│       ├── design-audit/                   <- shared (audit pipeline)
│       ├── ui-ux-pro-max/                  <- shared (design intel)
│       ├── gsap/                           <- web stack
│       ├── framer-motion/                  <- web stack
│       ├── css-native/                     <- web stack
│       ├── threejs-r3f/                    <- web stack
│       ├── canvas-generative/              <- web stack
│       ├── compose-motion/                 <- Android
│       ├── compose-graphics/               <- Android (M3 Expressive, AGSL, Canvas)
│       ├── compose-multiplatform/          <- KMP/CMP
│       ├── swiftui-motion/                 <- Apple
│       └── swiftui-graphics/               <- Apple (Metal, Liquid Glass, Canvas)
├── package-for-claude-ai.sh
├── CHANGELOG.md
└── README.md

Orchestrators detect the environment at runtime (Claude Code plugin directory, claude.ai /mnt/skills/user/, or a session-rooted Cowork mount - see Cowork compatibility) and pick what to load based on the SCAN phase. Sub-skills in _jutsu/ are loaded by orchestrator according to detected stack and selected scope - mobile-principles and desktop-principles are auto-loaded when context matches (touch target vs pointer/keyboard target). The underscore prefix keeps sub-skills internal so they never get invoked directly.

---

Cowork compatibility

genjutsu runs on three surfaces, and they mount the skill tree in three different places. Claude Code and claude.ai both have a fixed path. Cowork does not: it mounts under a per-session root that changes every run, for example /sessions/<session-id>/mnt/.claude/skills/genjutsu/_jutsu.

Path detection. The genjutsu:shared:skill-base block resolves $SKILL_BASE in this order, and stops at the first hit:

Order	Host	How it resolves
1	claude.ai, single bundle	_jutsu found directly under /mnt/skills/user
2	claude.ai, individual skills	the /mnt/skills/user mount itself
3	Claude Code	${CLAUDE_PLUGIN_ROOT}/skills/_jutsu, then the newest numbered version under ~/.claude/plugins/cache
4	Cowork, skills-directory installs	probed: $PWD and its ancestors, then ~/.claude/skills, /mnt/.claude/skills, /sessions, matching */.claude/skills/*/_jutsu

Step 4 is new and runs last, so steps 1 to 3 behave exactly as they did before. Every probe is depth-capped, so none of them can walk the filesystem. When all four miss, the failure is now explicit: the error names each root that was tried instead of letting a cat fail silently.

Preview mapping. The preview gate offers artifact, live preview or inline. What each one means depends on the host:

Host	A - artifact	B - live preview	C - inline
claude.ai	native artifact	throwaway route in your project	conversation text
Cowork	the host's persistent artifact	usually unavailable, no project checkout	the host's inline widget
Claude Code	the Artifact tool	throwaway route, or a @Preview / #Preview scratch file	conversation text
unknown	self-contained HTML at a temp path	not offered	conversation text

The gate detects the host itself, before LOAD runs. Cowork is tested before Claude Code because both can have a ~/.claude tree and only Cowork has the session-rooted mount, so the more specific signal has to win.

Pipeline weight. cast is the default entry point on every surface. paint is a five-phase pipeline and is disproportionate for the short requests that dominate on Cowork ("animate this word", "polish this hover"), so it now recognises light scope - one isolated component, no visual identity at stake, nothing downstream depending on it - and shortens to a single brainstorm question with no MASTER.md written. The gates stay; only their number goes down.

---

Voice

The skills speak in two registers:

• During execution: light ninja flair, short, signature ("Casting parallax on hero scroll.", "Brushing the color palette.")
• In reports / final summaries / audits: plain, factual, dev-readable. No mystic prose, no metaphors. Just what changed, files touched, next step.

---

Contributing

The most valuable contribution to this repo is "this claim is wrong, here is the primary source". It is a knowledge repository: a wrong sentence does not throw an error, it becomes wrong code in somebody else's project.

• CONTRIBUTING.md - the evidence standard, what not to touch, how to run the checks
• PLATFORM-CONTRACT.md - what a platform family must answer, what owning one costs, and how one gets removed
• skills/_jutsu/VERSIONS.md - what every version-sensitive claim was checked against and when. Rows marked VERIFY-NEEDED are the open work.

One person currently maintains roughly 736 API symbols across six targets. If you work in Compose, SwiftUI or motion-heavy web, owning one family's quarterly re-derivation is the single most useful thing anyone could do here.

---

Credits

Built by studying the best creative coding resources available.

Design intelligence

• nextlevelbuilder/ui-ux-pro-max-skill (MIT) - the ui-ux-pro-max sub-skill vendors this project's design dataset (styles, palettes, font pairings, UX guidelines, chart and stack guidance) and its Python search engine. See skills/_jutsu/ui-ux-pro-max/UPSTREAM.md for the vendoring notes and divergences.

Web foundation

• mxyhi/ok-skills - Granular GSAP decomposition, "Do Not" patterns, interaction thesis concept
• freshtechbro/claudedesignskills - BAD/GOOD pitfall patterns, reference file separation
• kylezantos/design-motion-principles - Designer perspectives (Emil Kowalski, Jakub Krehel, Jhey Tompkins), Motion Gap Analysis
• anthropics/claude-plugins-official - frontend-design plugin, anti-AI-slop philosophy

Android / Compose (v2.0)

• aldefy/compose-skill - granular Compose docs with androidx source receipts
• Meet-Miyani/compose-skill - Compose / CMP / KMP comprehensive
• new-silvermoon/awesome-android-agent-skills - Android architecture skills
• skydoves/Orbital - shared element transitions Compose multiplatform
• fornewid/material-motion-compose - Material Motion patterns Compose + CMP
• drinkthestars/shady - AGSL shaders rendered in Compose
• Mortd3kay/liquid-glass-android - glassmorphism AGSL Compose
• JumpingKeyCaps/DynamicVisualEffectsAGSL - AGSL playground
• mutualmobile/compose-animation-examples - Compose animation collection

Apple / SwiftUI (v2.0)

• twostraws/SwiftUI-Agent-Skill - SwiftUI best practices reference
• twostraws/swift-agent-skills - curated directory of Swift agent skills
• twostraws/Inferno - Metal shaders SwiftUI (the absolute reference)
• Treata11/iShader - Metal Fragment Shaders for SwiftUI
• jamesrochabrun/ShaderKit - composable Metal shaders + holographic UI
• raphaelsalaja/metallurgy - SwiftUI Metal Shaders library
• eleev/swiftui-new-metal-shaders - SwiftUI 5 Metal Shader Collection
• AvdLee/SwiftUI-Agent-Skill - SwiftUI animations + transitions + PhaseAnimator
• dpearson2699/swift-ios-skills - 83 Swift skills (incl. swiftui-animation, gestures, liquid-glass)
• rshankras/claude-code-apple-skills - Apple platform skills
• GetStream/swiftui-spring-animations - guide complete SwiftUI Spring
• amosgyamfi/open-swiftui-animations - collection SwiftUI animations
• Shubham0812/SwiftUI-Animations - 20+ custom SwiftUI animations + Metal

UX / motion theory

• Steven Hoober (thumb zones research) - "Designing for Touch"
• Material Design 3 - Motion and M3 Expressive
• Apple HIG iOS and macOS

---

Talk to me

Discussions are open.

• Show and tell - post what you cast. A gif, a screenshot, a link. Output that came out wrong is as useful as output that came out well.
• Q&A - install problems, a module that misfires, output that feels generic.
• Ideas - a surface, a framework, a module that is missing.

A bug with a clear repro is still better as an issue, it keeps a trail.

---

License

MIT

---

Built by Adrien Thevon, software engineer in Toulouse.
_{Also mine: TokenEater, a native macOS monitor for Claude usage limits  ·  worktigre, a git worktree manager}