added animation reference for the skill

.github/workflows/sync-readme-references.yml

@@ -9,6 +9,8 @@ jobs:
   sync-readme:
     if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -31,7 +33,8 @@ jobs:
           fi
 
           git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
           git add README.md
           git commit -m "chore: sync README references [skip ci]"
           git push

README.md

@@ -110,6 +110,9 @@ This skill gives your AI coding tool practical SwiftUI guidance. It can:
 swiftui-expert-skill/
   SKILL.md
   references/
+    animation-advanced.md - Performance, interpolation, and complex animation chains
+    animation-basics.md - Core animation concepts, implicit/explicit animations, timing
+    animation-transitions.md - View transitions, matchedGeometryEffect, and state changes
     image-optimization.md - AsyncImage usage, downsampling, caching
     layout-best-practices.md - Layout patterns and GeometryReader alternatives
     liquid-glass.md - iOS 26+ glass effects and fallback patterns

swiftui-expert-skill/SKILL.md

@@ -16,6 +16,7 @@ Use this skill to build, review, or improve SwiftUI features with correct state
 - Verify view composition follows extraction rules (see `references/view-structure.md`)
 - Check performance patterns are applied (see `references/performance-patterns.md`)
 - Verify list patterns use stable identity (see `references/list-patterns.md`)
+- Check animation patterns for correctness (see `references/animation-basics.md`, `references/animation-transitions.md`)
 - Inspect Liquid Glass usage for correctness and consistency (see `references/liquid-glass.md`)
 - Validate iOS 26+ availability handling with sensible fallbacks
 
@@ -25,6 +26,7 @@ Use this skill to build, review, or improve SwiftUI features with correct state
 - Extract complex views into separate subviews (see `references/view-structure.md`)
 - Refactor hot paths to minimize redundant state updates (see `references/performance-patterns.md`)
 - Ensure ForEach uses stable identity (see `references/list-patterns.md`)
+- Improve animation patterns (use value parameter, proper transitions, see `references/animation-basics.md`, `references/animation-transitions.md`)
 - Suggest image downsampling when `UIImage(data:)` is used (as optional optimization, see `references/image-optimization.md`)
 - Adopt Liquid Glass only when explicitly requested by the user
 
@@ -34,6 +36,7 @@ Use this skill to build, review, or improve SwiftUI features with correct state
 - Use `@Observable` for shared state (with `@MainActor` if not using default actor isolation)
 - Structure views for optimal diffing (extract subviews early, keep views small, see `references/view-structure.md`)
 - Separate business logic into testable models (see `references/layout-best-practices.md`)
+- Use correct animation patterns (implicit vs explicit, transitions, see `references/animation-basics.md`, `references/animation-transitions.md`, `references/animation-advanced.md`)
 - Apply glass effects after layout/appearance modifiers (see `references/liquid-glass.md`)
 - Gate iOS 26+ features with `#available` and provide fallbacks
 
@@ -102,6 +105,17 @@ Use this skill to build, review, or improve SwiftUI features with correct state
 - Gate frequent geometry updates by thresholds
 - Use `Self._printChanges()` to debug unexpected view updates
 
+### Animations
+- Use `.animation(_:value:)` with value parameter (deprecated version without value is too broad)
+- Use `withAnimation` for event-driven animations (button taps, gestures)
+- Prefer transforms (`offset`, `scale`, `rotation`) over layout changes (`frame`) for performance
+- Transitions require animations outside the conditional structure
+- Custom `Animatable` implementations must have explicit `animatableData`
+- Use `.phaseAnimator` for multi-step sequences (iOS 17+)
+- Use `.keyframeAnimator` for precise timing control (iOS 17+)
+- Animation completion handlers need `.transaction(value:)` for reexecution
+- Implicit animations override explicit animations (later in view tree wins)
+
 ### Liquid Glass (iOS 26+)
 **Only adopt when explicitly requested by the user.**
 - Use native `glassEffect`, `GlassEffectContainer`, and glass button styles
@@ -232,6 +246,16 @@ Button("Confirm") { }
 - [ ] Using relative layout (not hard-coded constants)
 - [ ] Views work in any context (context-agnostic)
 
+### Animations (see `references/animation-basics.md`, `references/animation-transitions.md`, `references/animation-advanced.md`)
+- [ ] Using `.animation(_:value:)` with value parameter
+- [ ] Using `withAnimation` for event-driven animations
+- [ ] Transitions paired with animations outside conditional structure
+- [ ] Custom `Animatable` has explicit `animatableData` implementation
+- [ ] Preferring transforms over layout changes for animation performance
+- [ ] Phase animations for multi-step sequences (iOS 17+)
+- [ ] Keyframe animations for precise timing (iOS 17+)
+- [ ] Completion handlers use `.transaction(value:)` for reexecution
+
 ### Liquid Glass (iOS 26+)
 - [ ] `#available(iOS 26, *)` with fallback for Liquid Glass
 - [ ] Multiple glass views wrapped in `GlassEffectContainer`
@@ -246,6 +270,9 @@ Button("Confirm") { }
 - `references/list-patterns.md` - ForEach identity, stability, and list best practices
 - `references/layout-best-practices.md` - Layout patterns, context-agnostic views, and testability
 - `references/modern-apis.md` - Modern API usage and deprecated replacements
+- `references/animation-basics.md` - Core animation concepts, implicit/explicit animations, timing, performance
+- `references/animation-transitions.md` - Transitions, custom transitions, Animatable protocol
+- `references/animation-advanced.md` - Transactions, phase/keyframe animations (iOS 17+), completion handlers (iOS 17+)
 - `references/sheet-navigation-patterns.md` - Sheet presentation and navigation patterns
 - `references/scroll-patterns.md` - ScrollView patterns and programmatic scrolling
 - `references/text-formatting.md` - Modern text formatting and string operations