@skilly-hand/skilly-hand 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -16,6 +16,46 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.15.1] - 2026-04-07
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.15.1)
+
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.15.0] - 2026-04-05
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.15.0)
+
+### Added
+
+- **frontend-design skill v1.1.0:** New `design-context-setter` agent for capturing design intent on greenfield projects via a persistent `DESIGN.md` file
+- **frontend-design skill v1.1.0:** New `motion-designer` agent for stack-aware animations and micro-interactions with GPU safety and `prefers-reduced-motion` compliance
+- **frontend-design skill v1.1.0:** New `visual-refiner` agent for post-generation quality evaluation (AI slop detection, interaction state coverage, Nielsen's heuristics, directional refinement)
+- **frontend-design skill v1.1.0:** New `aesthetic-archetypes` reference asset with 8 design archetypes for greenfield project direction
+- Enhanced `component-designer` with aesthetic principles, DESIGN.md integration, and complete interaction-state checklist
+
+### Changed
+
+- Updated `AGENTS.md` with expanded frontend-design workflow triggers and routing
+- Updated frontend-design routing map to include optional motion and visual refinement phases
+- Expanded frontend-design auto-invoke triggers to include greenfield setup, motion, and visual refinement scenarios
+
+### Fixed
+
+- _None._
+
+### Removed
+
+- Removed "Clarification-First Planning Workflow" from `AGENTS.md` (superseded by refined workflows)
+
 ## [0.14.0] - 2026-04-06
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.14.0)
 

package/catalog/README.md

@@ -8,8 +8,10 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
 | `angular-guidelines` | Guide Angular code generation and review using latest stable Angular verification and modern framework best practices. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
-| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. | frontend, design, workflow, ui | all |
-| `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. | core, workflow, education | all |
+| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases. | frontend, design, workflow, ui, motion, greenfield | all |
+| `output-optimizer` | Optimize output token consumption through compact interpreter modes with controlled expansion when complexity, ambiguity, or risk requires more detail. Trigger: minimizing response verbosity while preserving clarity and correctness. | core, workflow, efficiency, communication | all |
+| `project-security` | Scan project configuration and release surfaces for leak and security risks, and enforce security gates on commit, push, and publish workflows across GitHub, GitLab, npm, pnpm, yarn, and generic CI. Trigger: validating repository security posture, preventing secret leaks, or hardening delivery pipelines. | security, workflow, quality, core | all |
+| `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase. | core, workflow, education | all |
 | `react-guidelines` | Guide React code generation and review using latest stable React verification and modern framework best practices. | react, frontend, workflow, best-practices | all |
 | `review-rangers` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |

package/catalog/catalog-index.json

@@ -4,6 +4,8 @@
   "angular-guidelines",
   "figma-mcp-0to1",
   "frontend-design",
+  "output-optimizer",
+  "project-security",
   "project-teacher",
   "react-guidelines",
   "review-rangers",

package/catalog/skills/frontend-design/SKILL.md

@@ -8,10 +8,10 @@ Use this skill when:
 - You are adding new visual elements that must match the project's existing design language.
 - You are refactoring styling or structure of frontend code to align with established patterns.
 - You need to choose between UI components, tokens, or styles already available in the project.
+- You are starting a greenfield project and need to establish a design direction before building.
 
 Do not use this skill for:
 
-- Greenfield design system creation with no existing codebase to read from.
 - Backend, API, or data-layer tasks with no UI surface.
 - Design tool work (Figma, Sketch) unrelated to code implementation.
 - Projects where the user has explicitly opted out of stack detection.
@@ -25,17 +25,40 @@ Always run stack detection first. Never skip to design.
 | Step | Intent | Sub-agent |
 | --- | --- | --- |
 | 0 (always first) | Detect framework, UI library, CSS approach, tokens, and existing patterns | [agents/stack-detector.md](agents/stack-detector.md) |
+| 0b (if no DESIGN.md and no existing components) | Gather design intent and create DESIGN.md | [agents/design-context-setter.md](agents/design-context-setter.md) |
 | 1 (only after confirmation) | Design and implement components using confirmed stack | [agents/component-designer.md](agents/component-designer.md) |
+| 2 (optional) | Add motion and micro-interactions | [agents/motion-designer.md](agents/motion-designer.md) |
+| 3 (optional) | Evaluate quality and refine the output | [agents/visual-refiner.md](agents/visual-refiner.md) |
 
 ---
 
 ## Standard Execution Sequence
 
 1. **Run stack detection** — always start with `stack-detector`, no exceptions.
-2. **Present findings to the user** — surface the detected stack clearly and ask for explicit confirmation.
-3. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
-4. **Scan existing tokens and components** — read what already exists before proposing anything.
-5. **Design with confirmed context only** — hand off to `component-designer` only after step 2 is complete.
+2. **Check for DESIGN.md** — if it exists, read it before any design work. If it does not exist and the project has no existing components to sample, run `design-context-setter` to create it.
+3. **Present findings to the user** — surface the detected stack and any DESIGN.md context clearly, then ask for explicit confirmation.
+4. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
+5. **Scan existing tokens and components** — read what already exists before proposing anything.
+6. **Design with confirmed context only** — hand off to `component-designer` only after steps 2–4 are complete.
+7. **Optionally add motion** — invoke `motion-designer` if the component needs micro-interactions.
+8. **Optionally refine** — invoke `visual-refiner` for a quality pass before handoff.
+
+---
+
+## DESIGN.md — Persistent Design Brief
+
+`DESIGN.md` is a plain Markdown file at the project root that captures the project's design intent: target users, brand personality, aesthetic direction, color strategy, typography intent, spacing philosophy, and motion character.
+
+It is created by `design-context-setter` on greenfield projects and can be updated at any time by the user.
+
+**Every agent in this skill reads `DESIGN.md` if it exists before making aesthetic decisions.** This prevents design drift between sessions.
+
+```bash
+# Check if DESIGN.md exists before starting work
+cat DESIGN.md 2>/dev/null
+```
+
+If `DESIGN.md` exists, surface its contents in the stack confirmation step. If it conflicts with what the stack detector found (e.g., DESIGN.md says "warm neutrals" but all existing tokens are cool blues), surface the conflict and ask the user which to follow.
 
 ---
 
@@ -46,6 +69,7 @@ Always run stack detection first. Never skip to design.
 Before writing a single line of UI code or proposing any design, run [agents/stack-detector.md](agents/stack-detector.md).
 
 This means:
+
 - Reading `package.json` to identify the framework and installed libraries.
 - Detecting CSS approach (Tailwind, CSS Modules, styled-components, Sass, vanilla).
 - Finding existing design tokens (CSS custom properties, theme files, `tokens.json`).
@@ -67,9 +91,10 @@ If the token does not exist in the project, do not invent it. Ask the user: "Thi
 
 ### Pattern 3: Confirm Before Every Design Decision
 
-At every fork — layout choice, component variant, color, interaction pattern — if the right answer is not derivable from the existing code, ask the user.
+At every fork — layout choice, component variant, color, interaction pattern — if the right answer is not derivable from the existing code or from `DESIGN.md`, ask the user.
 
 Examples of things that require confirmation:
+
 - Which existing component to base a new one on.
 - Whether to use Tailwind utility classes or a CSS module.
 - Whether to match a specific existing page's spacing rhythm or start fresh.
@@ -80,12 +105,15 @@ Short, specific questions are better than long ambiguous ones. One question at a
 ### Pattern 4: Follow the Project's Visual Language
 
 After stack detection, read 3–5 existing components before proposing any design. Identify:
+
 - The naming convention (PascalCase components, BEM CSS, camelCase tokens, etc.)
 - The composition pattern (atomic components, compound components, render props, slots)
 - The styling approach (co-located styles, global theme, utility-first classes)
 
 Every new component or style must feel like it was written by the same team that wrote the existing code — not imported from a different design system.
 
+If no existing components are found, use `DESIGN.md` as the visual language reference. If neither exists, run `design-context-setter` before proceeding.
+
 ---
 
 ## What Not To Do
@@ -95,13 +123,14 @@ These are the most critical rules. Violating any of them produces AI slop.
 - **Never assume a UI library is present** without verifying it in `package.json`. Shadcn and Radix look similar in JSX — check the deps.
 - **Never pick colors, fonts, or spacing values not already in the project**. If the project has no purple, do not introduce purple.
 - **Never use Inter as a default font** unless it is explicitly declared in the project. Inter is a sign of uncontextualized AI output.
-- **Never generate a component without reading at least one existing component first**. The project's conventions must be the template.
+- **Never generate a component without reading at least one existing component first** (or DESIGN.md if no components exist). The project's conventions must be the template.
 - **Never apply a generic layout** (hero + cards + CTA, standard nav + footer) without verifying the project already uses or wants that structure.
-- **Never chain design decisions silently**. If one decision implies a downstream choice (e.g. using a grid library implies a layout system), surface it.
+- **Never chain design decisions silently**. If one decision implies a downstream choice (e.g., using a grid library implies a layout system), surface it.
 - **Never proceed after ambiguity**. If the detected stack is inconsistent (e.g., Tailwind and styled-components both present), stop and ask which one is canonical.
 - **Never treat a partial stack detection as complete**. If `package.json` was readable but no component files were found, say so and ask for the component directory.
 - **Never ship a "placeholder" or "you can customize this later" design**. Every value must be intentional and project-derived.
 - **Never skip the confirmation step** even if the stack looks obvious. One confirmation prevents ten corrections.
+- **Never ignore DESIGN.md when it exists**. It represents deliberate decisions the user has already made.
 
 ---
 
@@ -113,11 +142,17 @@ User asks for UI work
        NO  -> Run stack-detector, present findings, ask for confirmation
        YES -> Continue
 
+  -> Does DESIGN.md exist?
+       YES -> Read it; surface any conflicts with detected stack
+       NO  -> Are there existing components to sample?
+                YES -> Sample them (Pattern 4)
+                NO  -> Run design-context-setter to create DESIGN.md
+
 Is the requested component similar to an existing one in the project?
   YES -> Read the existing component, use it as the structural and styling template
   NO  -> Ask the user which existing component is closest, or if this is a net-new pattern
 
-Does the design require a token/value (color, spacing, font) not yet found in the project?
+Does the design require a token/value (color, spacing, font) not yet found in the project or DESIGN.md?
   YES -> Ask the user: add a new token, use an existing one, or clarify?
   NO  -> Use the existing token
 
@@ -135,6 +170,10 @@ Is the CSS approach styled-components or CSS-in-JS?
 
 Ready to implement?
   YES -> Hand off to component-designer with full confirmed context
+
+After generation:
+  -> Does the component need motion? -> Invoke motion-designer
+  -> Does the output need a quality pass? -> Invoke visual-refiner
 ```
 
 ---
@@ -192,6 +231,9 @@ grep '"@radix-ui' package.json
 ## Commands
 
 ```bash
+# Check for DESIGN.md at project root
+cat DESIGN.md 2>/dev/null
+
 # Read project dependencies
 cat package.json | grep -A 50 '"dependencies"'
 
@@ -213,5 +255,9 @@ find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
 ## Resources
 
 - Stack detection procedure: [agents/stack-detector.md](agents/stack-detector.md)
+- Design context setup (greenfield): [agents/design-context-setter.md](agents/design-context-setter.md)
 - Component design rules: [agents/component-designer.md](agents/component-designer.md)
+- Motion and micro-interactions: [agents/motion-designer.md](agents/motion-designer.md)
+- Visual quality refinement: [agents/visual-refiner.md](agents/visual-refiner.md)
 - Full scan checklist: [assets/stack-scan-checklist.md](assets/stack-scan-checklist.md)
+- Aesthetic archetypes reference: [assets/aesthetic-archetypes.md](assets/aesthetic-archetypes.md)

package/catalog/skills/frontend-design/agents/component-designer.md

@@ -8,6 +8,8 @@ If the user asks you to design something and no confirmed stack summary exists,
 "Before I design anything, I need to scan the project. Running stack detection first."
 Then invoke stack-detector. Do not skip this, even if the task feels small.
 
+**Also read `DESIGN.md` before making any aesthetic decisions.** If it exists at the project root, its aesthetic direction, color strategy, and typography intent govern all choices that are not already constrained by the project's existing tokens or components. If `DESIGN.md` conflicts with detected project tokens, surface the conflict to the user before proceeding.
+
 ---
 
 ## When to Use
@@ -42,23 +44,39 @@ These rules are absolute. No exceptions without explicit user confirmation.
 
 ---
 
+## Aesthetic Principles
+
+These apply within the constraints of the confirmed stack — they guide choices when multiple options are equally valid.
+
+- Prefer generous whitespace over cramped layouts. When in doubt, add more space.
+- Use size and weight to establish hierarchy before reaching for color.
+- One clear visual focus per component — the most important element should be unmistakable.
+- Avoid equal-weight elements. If everything is emphasized, nothing is.
+- When `DESIGN.md` defines a motion character, let it inform transition presence even at this stage — flag it for `motion-designer` rather than omitting it entirely.
+
+---
+
 ## Questioning Protocol
 
 At every point of uncertainty, ask the user a short, specific question before proceeding.
 
 **Layout questions:**
+
 - "Should this component use the same grid as [ExistingPage], or does it have different spacing requirements?"
 - "The project breakpoints in tailwind.config are `sm`, `md`, `lg`. Should this component be responsive at all three, or only `md` and above?"
 
 **Style questions:**
+
 - "I see `--color-primary` and `--color-accent` in globals.css. Which one should this button use for its default state?"
 - "The existing Card uses `rounded-md`. Should this modal also use `rounded-md`, or does it need a sharper or rounder corner?"
 
 **Interaction / state questions:**
+
 - "Should this component have a loading state? I don't see a Skeleton or Spinner imported in other components — should I add one or skip it?"
 - "The existing Input has a `disabled` prop. Should this new Select also handle `disabled`?"
 
 **Composition questions:**
+
 - "Do you want this to accept children (composable) or receive structured props (data-driven)? The existing Card uses both — which pattern fits here?"
 
 One question at a time. Do not front-load a list of 8 questions before starting.
@@ -79,6 +97,11 @@ Before finalizing any output, verify every item:
 - [ ] No new design tokens were invented without explicit user approval.
 - [ ] The component was cross-referenced against at least one existing component for structural consistency.
 - [ ] Accessibility: semantic HTML elements, aria attributes consistent with existing components.
+- [ ] All interactive states handled: hover, focus-visible, active, disabled.
+- [ ] Loading and empty states considered — ask the user if not obvious from the request.
+- [ ] Error state handled where the component can receive or display errors.
+- [ ] If any animation was added, `prefers-reduced-motion` is respected.
+- [ ] `DESIGN.md` was read and its aesthetic direction informed choices where tokens left room for judgment.
 
 ---
 
@@ -89,7 +112,8 @@ A finished component from this agent:
 - Reads like it was written by the existing team.
 - Uses the same imports, utilities, and style tokens as the rest of the codebase.
 - Has no values that can't be traced back to a confirmed project resource.
-- Includes no design decisions that weren't explicitly confirmed by the user or directly derived from existing code.
+- Includes no design decisions that weren't explicitly confirmed by the user or directly derived from existing code or `DESIGN.md`.
 - Has no "you can customize this" placeholder comments.
+- Has all interactive states implemented, not deferred.
 
 If the output doesn't meet this bar, it is not done.

package/catalog/skills/frontend-design/agents/design-context-setter.md

@@ -0,0 +1,156 @@
+# Design Context Setter
+
+## Goal
+
+Gather the project's design intent once, then write it to `DESIGN.md` at the project root. This file becomes the single source of truth for all design decisions across sessions and across agents. Every other agent in this skill reads `DESIGN.md` before making aesthetic choices.
+
+This agent is modeled on how modern AI-first design platforms (Stitch, v0, Galileo) treat a persistent design brief — a short, always-available document that anchors every generation.
+
+---
+
+## When to Use
+
+Run this agent when:
+
+- `DESIGN.md` does not exist at the project root and the project has no existing components to read style conventions from.
+- The user starts a greenfield project (no `src/components`, no existing UI, blank or near-blank codebase).
+- The user says "let's set up the design" or "define the visual direction" before any component work.
+- The stack detector finds no design tokens and no existing components to sample.
+
+Do not run this agent when:
+
+- `DESIGN.md` already exists and the user has not asked to update it. Read it instead.
+- The project has existing components — stack detection provides sufficient context for matching.
+- The user has explicitly said "just match what's there."
+
+---
+
+## Check First
+
+Before starting the interview, check:
+
+```bash
+# Is DESIGN.md already present?
+cat DESIGN.md 2>/dev/null
+
+# Are there existing components to learn from instead?
+find src -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | head -5
+```
+
+If `DESIGN.md` exists, surface it to the user and ask: "A `DESIGN.md` already exists. Should I use it as-is, update it, or start fresh?"
+
+If components exist but no `DESIGN.md`, suggest: "I found existing components. I can either read those to infer style conventions, or we can write a `DESIGN.md` to set a deliberate direction. Which do you prefer?"
+
+---
+
+## Interview Protocol
+
+Ask these questions one at a time. Do not front-load the full list.
+
+**1. Who is this for?**
+"Who are the primary users of this interface? (e.g., technical professionals, general public, enterprise ops teams, consumers aged 25–35)"
+
+**2. What does this product do — in one sentence?**
+"Describe the product's core value proposition in a single sentence."
+
+**3. What's the brand personality?**
+"Pick 3 adjectives that describe how this interface should feel. Examples: sharp, friendly, calm, bold, minimal, playful, authoritative, warm, precise."
+
+**4. Are there any visual references?**
+"Any products, sites, or brands whose aesthetic this should feel close to? (Optional — skip if none.)"
+
+**5. What's the accessibility baseline?**
+"Should we target WCAG 2.2 Level AA (standard), AAA (enhanced), or is there a specific requirement? Default is AA."
+
+**6. Any hard constraints?**
+"Are there colors, fonts, or patterns that must be used or must be avoided? (brand guidelines, corporate requirements, legal restrictions)"
+
+After collecting answers, propose a brief aesthetic direction and ask for confirmation before writing the file.
+
+---
+
+## Output Format
+
+Write the following structure to `DESIGN.md` at the project root. Every field must come from user answers — no invented values.
+
+```markdown
+# DESIGN.md
+
+> This file is the canonical design brief for this project.
+> All AI agents and contributors should read it before making visual decisions.
+> Update it when the design direction changes.
+
+## Product
+
+**What it is:** [one-sentence description]
+**Primary users:** [user description]
+
+## Brand Personality
+
+**Adjectives:** [3 adjectives from user]
+**Visual references:** [references, or "none specified"]
+
+## Aesthetic Direction
+
+[2–4 sentences written in plain language describing the desired look and feel.
+Derived from the adjectives and references above.
+Example: "Clean, high-contrast layouts with generous whitespace. Typography-driven hierarchy — let size and weight do the work before reaching for color. Warm neutrals, not pure grays. Motion should feel intentional and restrained."]
+
+## Color Strategy
+
+> Intent only — not token declarations. Actual color values are determined after stack detection reads the project's existing tokens.
+
+**Approach:** [e.g., "Monochromatic with a single warm accent" / "High contrast, dark-first" / "Muted palette, earthy tones" / "To be defined — read from stack tokens"]
+**Accent color intent:** [e.g., "Call-to-action only" / "Interactive states only" / "Not yet defined"]
+
+## Typography Intent
+
+> Intent only — not font declarations. Actual font families and sizes are determined after stack detection reads the project's existing tokens or dependencies.
+
+**Character:** [e.g., "Geometric sans-serif for clarity" / "Humanist serif for warmth" / "Monospace for technical credibility" / "To be determined from stack"]
+**Scale approach:** [e.g., "Tight utilitarian scale for app UI" / "Dramatic editorial scale for marketing" / "Match existing project scale"]
+
+## Spacing Philosophy
+
+[e.g., "Generous whitespace — let content breathe" / "Dense, information-rich — prioritize data density" / "Match existing project rhythm"]
+
+## Motion Character
+
+[e.g., "Subtle and purposeful — transitions only, no decorative motion" / "Expressive — micro-interactions on every interaction" / "Minimal — respect reduced-motion by default"]
+
+## Accessibility
+
+**Target level:** [WCAG 2.2 AA / AAA / project-specific]
+**Hard constraints:** [any must-have or must-avoid rules from user]
+
+## Notes
+
+[Any other constraints, references, or decisions captured during setup]
+```
+
+---
+
+## After Writing DESIGN.md
+
+Tell the user:
+
+> `DESIGN.md` has been created at the project root. Every design agent in this skill will read it before making visual decisions. You can edit it at any time — it's plain Markdown.
+>
+> Ready to proceed with stack detection and component design.
+
+Then hand off to `stack-detector.md`.
+
+**If the assistant cannot write files** (sandboxed or read-only environment): Tell the user the DESIGN.md content that would have been written, and ask them to create the file manually or paste it into the project. Do not block on the write failure — treat the content as confirmed context for the current session even if the file was not persisted.
+
+---
+
+## Updating DESIGN.md
+
+If the user asks to update the design direction mid-project:
+
+1. Read the current `DESIGN.md`.
+2. Ask which section they want to change.
+3. Make only the requested change — do not rewrite the whole file.
+4. Confirm the update before writing.
+
+Never overwrite the entire file silently.

package/catalog/skills/frontend-design/agents/motion-designer.md

@@ -0,0 +1,184 @@
+# Motion Designer
+
+## Precondition
+
+**Stack detection must be complete before this agent runs.**
+
+Motion must be implemented using the animation primitives already available in the project's stack. Never introduce a new animation library without the user's explicit approval.
+
+---
+
+## When to Use
+
+Use this agent when:
+
+- A component has been generated and the user asks "add animations," "make this feel alive," or "add micro-interactions."
+- You identify that a key interaction is missing feedback (e.g., a button with no active state transition).
+- The user wants to add entrance animations, loading skeletons, or scroll-driven reveals.
+- You need to implement reduced-motion-safe transitions.
+
+Do not use this agent when:
+
+- Stack detection has not been run.
+- The project has zero animation dependencies and no CSS transition usage in existing components — ask the user before adding anything.
+- The user has explicitly said "no animations."
+
+---
+
+## Animation Stack Detection
+
+Before proposing any motion, identify what animation primitives the project already uses.
+
+```bash
+# Check for animation libraries
+grep -E '"framer-motion"|"@motionone/dom"|"gsap"|"animejs"|"motion"' package.json
+
+# Check for CSS transitions in existing components
+grep -rn "transition" src/ --include="*.css" --include="*.scss" --include="*.module.css" | head -10
+
+# Check for @keyframes usage
+grep -rn "@keyframes" src/ --include="*.css" --include="*.scss" | head -5
+
+# Check for Tailwind animation utilities
+grep -n "transition\|duration\|ease\|animate-" src/ --include="*.tsx" --include="*.vue" | head -10
+```
+
+Report what was found:
+
+```
+Animation stack:
+  Library:     [framer-motion v11 | @motionone/dom | GSAP | none detected]
+  CSS approach: [Tailwind transition utilities | CSS custom properties | @keyframes | none]
+  Existing patterns: [fade-in on mount | slide transitions | skeleton loaders | none found]
+```
+
+If no animation primitives are found, ask: "This project has no existing animation setup. Should I use CSS transitions only (no new dependencies), or would you like to add a library? If so, which one?"
+
+---
+
+## Opportunity Assessment
+
+Evaluate the component for four animation opportunities. Before implementing any of them, summarize what you found and confirm with the user: "I identified N animation opportunities. Here's what I'd add — confirm before I make any changes?" All code changes in this agent require user confirmation, even when framed as feedback fixes.
+
+### 1. Missing Feedback
+
+UI actions that complete silently feel broken. Look for:
+
+- Buttons with no active/press state visual change
+- Form submissions with no loading indicator
+- Toggle switches with no transition
+- Tabs or accordion panels that snap without transition
+
+**Fix**: Add a 100–200ms `transition` on `transform`, `opacity`, or `background-color`. Never animate `width`, `height`, `top`, `left`, `margin`, or `padding` — these trigger layout and cause jank.
+
+### 2. Jarring Transitions
+
+Elements that appear/disappear instantly feel glitchy:
+
+- Modals, drawers, tooltips that pop in without entrance
+- Dropdown menus that appear with no transition
+- Route changes with no fade
+
+**Fix**: 200–350ms `opacity` + `transform: translateY(4px)` entrance. Exit should be faster than entrance (150–250ms).
+
+### 3. Unclear Relationships
+
+Motion can communicate hierarchy and causality:
+
+- List items that load simultaneously when staggered would feel more natural
+- A parent collapsing without carrying its children
+- A notification appearing without connecting to its trigger
+
+**Fix**: Stagger delays of 30–60ms between sibling elements. Keep total stagger duration under 400ms for lists of 6+ items.
+
+### 4. Delight Opportunities
+
+Moments where a small motion adds personality without adding noise:
+
+- Success state on form submission
+- Empty state illustrations that have a subtle loop
+- First-load entrance for a hero section
+
+**Fix**: These are always optional and always ask the user first. Never add delight motion without explicit approval.
+
+---
+
+## Timing Reference
+
+| Use Case | Duration | Easing |
+| -------- | -------- | ------ |
+| Button feedback (press, hover) | 100–150ms | ease-out |
+| Tooltip / popover entrance | 150–200ms | ease-out |
+| Dropdown open | 200–250ms | ease-out |
+| Modal / drawer entrance | 250–350ms | cubic-bezier(0.16, 1, 0.3, 1) |
+| Page / route transition | 300–400ms | ease-in-out |
+| Hero entrance (first load) | 500–800ms | cubic-bezier(0.16, 1, 0.3, 1) |
+| Stagger delay between siblings | 30–60ms | — |
+
+Never exceed 800ms for any UI transition. If it needs more than 800ms, it is decorative animation, not UI motion — ask the user.
+
+---
+
+## GPU Safety Rules
+
+**Only animate these properties** — they are GPU-composited and do not trigger layout:
+
+- `transform` (translate, scale, rotate)
+- `opacity`
+- `filter` (use sparingly — can be expensive)
+
+**Never animate** layout-triggering properties:
+
+- `width`, `height`, `max-height`
+- `top`, `left`, `right`, `bottom`
+- `margin`, `padding`
+- `border-width`
+- `font-size`
+
+If you need a height animation (e.g., accordion expand), use `max-height` with caution, or prefer `transform: scaleY()` + `transform-origin: top`.
+
+---
+
+## Reduced Motion — Non-Negotiable
+
+Every animation added by this agent must respect `prefers-reduced-motion`. No exceptions.
+
+**CSS approach:**
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .animated-element {
+    transition: none;
+    animation: none;
+  }
+}
+```
+
+**Tailwind approach:**
+
+```html
+<div class="transition-opacity duration-200 motion-reduce:transition-none">
+```
+
+**Framer Motion approach:**
+
+```tsx
+const shouldReduce = useReducedMotion();
+<motion.div animate={shouldReduce ? {} : { opacity: 1, y: 0 }} />
+```
+
+If the existing project has no `prefers-reduced-motion` handling anywhere, note it and add it to every animation you introduce.
+
+---
+
+## Implementation Checklist
+
+Before finalizing any motion work:
+
+- [ ] All animation primitives are from the confirmed stack — no new dependencies added without approval.
+- [ ] No layout-triggering properties are animated.
+- [ ] All animations have a `prefers-reduced-motion` fallback.
+- [ ] Timing values are within the reference ranges above.
+- [ ] Delight animations were explicitly approved by the user.
+- [ ] No animation duration exceeds 800ms.
+- [ ] Stagger lists cap total duration at 400ms.