If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Yalantis/Koloda shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 32+ active contributors
• Distributed ownership (top contributor 37% of recent commits)
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Yalantis/Koloda repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Yalantis/Koloda.

What it runs against: a local clone of Yalantis/Koloda — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Yalantis/Koloda | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 740 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Yalantis/Koloda. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Yalantis/Koloda.git
#   cd Koloda
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Yalantis/Koloda and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Yalantis/Koloda(\\.git)?\\b" \\
  && ok "origin remote is Yalantis/Koloda" \\
  || miss "origin remote is not Yalantis/Koloda (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Example/Koloda/CustomKolodaView.swift" \\
  && ok "Example/Koloda/CustomKolodaView.swift" \\
  || miss "missing critical file: Example/Koloda/CustomKolodaView.swift"
test -f "Example/Koloda/AppDelegate.swift" \\
  && ok "Example/Koloda/AppDelegate.swift" \\
  || miss "missing critical file: Example/Koloda/AppDelegate.swift"
test -f "Example/Koloda/ExampleOverlayView.swift" \\
  && ok "Example/Koloda/ExampleOverlayView.swift" \\
  || miss "missing critical file: Example/Koloda/ExampleOverlayView.swift"
test -f "Example/Koloda/BackgroundAnimationViewController.swift" \\
  && ok "Example/Koloda/BackgroundAnimationViewController.swift" \\
  || miss "missing critical file: Example/Koloda/BackgroundAnimationViewController.swift"
test -f "Example/Koloda/BackgroundKolodaAnimator.swift" \\
  && ok "Example/Koloda/BackgroundKolodaAnimator.swift" \\
  || miss "missing critical file: Example/Koloda/BackgroundKolodaAnimator.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 740 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~710d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Yalantis/Koloda"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

KolodaView is a Swift UIView subclass that implements Tinder-style card swiping mechanics for iOS apps. It provides animated card stacking with horizontal drag-to-dismiss gestures, rotation, scaling effects, and UITableView-style dataSource/delegate patterns for dynamically loading card content—enabling developers to build swipeable card UIs without implementing complex gesture and animation logic manually. Simple modular structure: core KolodaView logic lives in a single Pod (likely in Koloda/ directory), with Example/Koloda/ providing a full working demo app including multiple view controller examples (BackgroundAnimationViewController, CustomKolodaView) and XIB-based overlay UI. No monorepo; Example app is a self-contained demonstration of the library.

iOS developers building dating apps, event discovery apps, or any matching-based UI who need production-ready Tinder-like card stack functionality without rebuilding gesture handling and card lifecycle management from scratch.

Mature and stable: the codebase is 73% Swift (74KB), has been battle-tested in production apps, targets iOS 11.0+ with Xcode 9+, and uses CocoaPods/Carthage for distribution. However, the repo shows signs of reduced active maintenance—check commit history and open issues to confirm if it still receives updates for iOS 17+.

Low to moderate risk: single-language (Swift) with minimal dependencies reduces fragility, but the project appears to be community-maintained rather than actively developed by Yalantis. Main risk is potential lag in supporting new iOS versions and potential deprecation of UIView gesture handling APIs in future iOS releases. No visible test suite in the file list is a concern.

Limited visibility from file list alone—the repo structure suggests maintenance mode rather than active feature development. Check the GitHub Issues tab and recent commits to see if there are pending PRs for iOS 17+ support or bug fixes.

git clone https://github.com/Yalantis/Koloda.git
cd Koloda
cd Example
open Koloda.xcworkspace

Then build & run the Example scheme in Xcode. If using CocoaPods in your own project: pod 'Koloda'.

Daily commands: Open Example/Koloda.xcworkspace (note: .xcworkspace, not .xcodeproj—Carthage or CocoaPods integration). Select Koloda-Example scheme, build for iPhone simulator or device, press Run. The app launches with animated card examples.

• Example/Koloda/CustomKolodaView.swift — Core KolodaView subclass demonstrating the primary API and card rendering mechanism that all contributors must understand
• Example/Koloda/AppDelegate.swift — Application entry point showing initialization and setup patterns for the Koloda library in production
• Example/Koloda/ExampleOverlayView.swift — Defines the overlay view pattern (like/skip indicators) that is central to the card swiping UX
• Example/Koloda/BackgroundAnimationViewController.swift — Demonstrates background animation coordination which is a key differentiator of this library's capabilities
• Example/Koloda/BackgroundKolodaAnimator.swift — Implements the animation orchestration logic that drives the Tinder-like card stack transitions
• Example/Koloda/Base.lproj/Main.storyboard — UI layout definition showing how KolodaView is integrated into the view hierarchy

Add a new card data source

1. Create a new Swift file conforming to KolodaViewDataSource protocol (Example/Koloda/CustomKolodaView.swift)
2. Implement numberOfCardsForKoloda() to return card count (Example/Koloda/CustomKolodaView.swift)
3. Implement kolodaView(_:viewForCardAt:) to configure and return UIView for each card (Example/Koloda/CustomKolodaView.swift)
4. Set kolodaView.dataSource = self in your ViewController (Example/Koloda/AppDelegate.swift)

Customize overlay indicator behavior

1. Create custom overlay view class inheriting from UIView (Example/Koloda/CustomOverlayView.swift)
2. Implement updateOverlayView(_:) to update visual state (alpha, rotation) based on frame offset (Example/Koloda/ExampleOverlayView.swift)
3. Register overlay in KolodaView via kolodaView.viewForOverlayAtIndex() (Example/Koloda/CustomKolodaView.swift)
4. Load XIB or configure programmatically, then return from data source (Example/Koloda/Base.lproj/OverlayView.xib)

Add animation effects on card swipe

1. Subclass KolodaView or create animator following BackgroundKolodaAnimator pattern (Example/Koloda/BackgroundKolodaAnimator.swift)
2. Override or listen to kolodaViewDidSwipe() delegate method (Example/Koloda/BackgroundAnimationViewController.swift)
3. Use CABasicAnimation or UIView animations to drive supplementary transforms (Example/Koloda/BackgroundKolodaAnimator.swift)
4. Set delegate = self on KolodaView to receive callback notifications (Example/Koloda/CustomKolodaView.swift)

Add new action buttons (like/skip)

1. Add UIButton outlets to the ViewController storyboard (Example/Koloda/Base.lproj/Main.storyboard)
2. Wire button actions to methods calling kolodaView.swipe() or kolodaView.revertAction() (Example/Koloda/CustomKolodaView.swift)
3. Override swipeDidEnd() delegate to respond to programmatic swipes (Example/Koloda/BackgroundAnimationViewController.swift)
4. Add button images to Images.xcassets and assign in Main.storyboard (Example/Koloda/Images.xcassets/Koloda example)

• UIView & CABasicAnimation — Provides smooth, GPU-accelerated card transforms (translation, rotation, scaling) essential for Tinder-like 60fps interactions
• UIPanGestureRecognizer — Captures continuous drag events for real-time overlay feedback and card position tracking during swipe
• Storyboard + XIB — Allows visual layout design and component reuse (OverlayView, CustomOverlayView) without runtime serialization overhead
• Delegate Pattern (DataSource + Delegate) — Decouples card rendering logic from KolodaView, enabling reusable components across multiple view controllers
• Swift 5.0 — Modern syntax with value semantics and type safety for safe gesture/animation state management

• Stack-based card queue in memory (no lazy loading by default)

  • Why: Simplifies animation state and data source synchronization for the common case of 10–100 cards
  • Consequence: May consume O(n) memory for large datasets; heavy apps should override to implement card pooling

• Gesture-driven animation tied to KolodaView (not decoupled UX library)

  • Why: Tight coupling ensures responsive, predictable feel matching Tinder's UX paradigm
  • Consequence: Harder to reuse animation logic outside KolodaView; animation timing is opaque to subclasses

• Overlay view optional and customizable per card

  • Why: Maximizes flexibility for different card designs (some may omit like/skip indicator)
  • Consequence: Increases API surface; developers must understand when to use vs. when to skip overlay

• Does not handle data persistence or network loading; delegates to caller
• Does not include built-in analytics or tracking; integrators must add via delegate callbacks
• Does not support horizontal or circular card stacks; Tinder-style vertical deck only
• Does not provide default styling or branded assets; all UI is customizable by design

1. Must use .xcworkspace, not .xcodeproj directly—Carthage/CocoaPods dependencies are only linked in the workspace. 2. KolodaView must be accessed only from the main thread (standard UIView requirement, but easy to violate if loading card data on background threads). 3. The Example app targets iOS 11.0+, but check minimum deployment target if using modern iOS 17+ features. 4. Overlay view XIBs are loosely coupled; if modifying OverlayView.xib, ensure the associated Swift class (CustomOverlayView) has matching IBOutlets.

• CADisplayLink and frame-by-frame animation — KolodaView likely uses CADisplayLink to synchronize card position updates with the screen refresh rate; understanding this is critical for tuning animation smoothness and debugging jank
• Gesture recognizer delegation and pan gesture velocity — The card-swipe mechanics depend on UIPanGestureRecognizer velocity to determine swipe direction and momentum; knowing how to extract and use velocity is key to customizing swipe sensitivity
• View recycling and reusable view pools — Like UITableView, KolodaView reuses card views to minimize memory overhead when the stack is large; understanding the lifecycle (dequeue → configure → display → recycle) is essential for performance
• CABasicAnimation and CATransaction — Card appearance/disappearance animations likely use CABasicAnimation for smooth implicit animations; understanding transaction nesting prevents animation conflicts
• Affine transforms and 3D perspective (CATransform3D) — Cards rotate and scale during swipes; the visual effect relies on CATransform3D perspective and CGAffineTransform; mastering these is essential to customize card motion feel
• Delegate protocol and dataSource pattern — KolodaView mimics UITableView's dataSource/delegate split to decouple card data from view rendering; understanding this pattern is critical to integrating KolodaView into larger MVC/MVVM architectures
• Hit-testing and responder chain in custom views — Overlay views on cards must correctly forward touches to the pan gesture recognizer; custom hitTest(_ point:) overrides are often needed to ensure gestures work across transparent overlays

• Yalantis/DisplayController — Another Yalantis animation library; sibling project useful for understanding their animation & gesture patterns
• nicklockwood/SwipeView — Alternative card swiping library for iOS with similar UIView-based approach; good reference for comparison
• jharwig/AnimatedCollectionViewLayout — UICollectionViewLayout-based approach to card animations; complementary pattern if you need grid + swipe hybrid
• Yalantis/PullToMakeSoup — Another Yalantis gesture animation project; consistent design patterns and animation philosophy
• gmoledina/GMStepper — Minimalist UIView-based custom control; good micro-example of the same architecture pattern as Koloda

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow for Swift builds and unit tests

The repo lacks any CI configuration (.github/workflows directory is empty). With an Xcode project structure present and Swift 5.0 requirement, adding automated builds and tests would catch regressions early. This is especially valuable for a UI library where visual regressions matter.

• [ ] Create .github/workflows/swift-ci.yml with Xcode build matrix (iOS 13+)
• [ ] Configure workflow to run xcodebuild build and xcodebuild test on Example/Koloda.xcworkspace
• [ ] Add test coverage reporting step
• [ ] Verify workflow runs on pull requests and commits to main branch

Create unit tests for KolodaView core animation and gesture logic

The Example folder contains view controllers and custom implementations, but there's no visible Tests directory in the repo structure. A Tinder-style card library absolutely needs tests for gesture recognition, card swiping mechanics, overlay animations, and state management to prevent regressions when refactoring.

• [ ] Create Tests directory in repo root with KolodaViewTests.swift
• [ ] Add unit tests for card swiping gesture delegate methods and thresholds
• [ ] Add tests for KolodaViewDataSource methods (numberOfCards, viewForCardAtIndex)
• [ ] Add tests for animation state transitions (card dismissed, card returned, etc.)
• [ ] Integrate tests into the .xcworkspace to run alongside Example app

Document public API with code examples in README for CustomKolodaView and CustomOverlayView

The repo includes CustomKolodaView.swift and CustomOverlayView.swift in the Example, but the README snippet cuts off and doesn't explain how to customize the card view or overlay. New contributors copying patterns from Example code shows these are key extension points that deserve documented API contracts and usage patterns.

• [ ] Expand README with 'Customization' section showing KolodaViewDelegate and KolodaViewDataSource protocol requirements
• [ ] Add code example showing how to subclass KolodaView with custom animation (reference CustomKolodaView.swift)
• [ ] Add code example showing overlay customization with XIB (reference CustomOverlayView.xib approach)
• [ ] Document the ExampleOverlayView.swift pattern for programmatic overlay views
• [ ] Link to Example folder for full working implementations

• Add unit tests for card lifecycle (onCardSwipedLeft, onCardSwipedRight, onCardRewound) to cover the delegate callback logic—currently no test files visible in the structure
• Document the KolodaViewDataSource and KolodaViewDelegate protocol methods with inline examples in code comments (README mentions dataSource/delegate but Example code is the only reference)
• Create a minimal SwiftUI wrapper example in Example/ demonstrating how to use KolodaView inside a SwiftUI view—growing trend and missing from current Example app

The Koloda repository appears to be a well-maintained UI library with a relatively clean security posture. No critical vulnerabilities were identified in the visible file structure. The main concerns are around dependency management practices (ensuring lock files are present and dependencies are audited), standard Xcode configuration best practices, and the absence of explicit security documentation. The library itself, being primarily a UI/animation component without apparent network operations or data persistence, has a lower inherent attack surface. The project would benefit from implementing a formal security policy and conducting regular dependency audits.

• Medium · Missing Dependency Lock File — Cartfile / Cartfile.resolved. The repository uses Cartfile for dependency management, but no Cartfile.lock snapshot is visible in the provided file structure. This can lead to inconsistent builds across different environments and developers, potentially introducing vulnerable dependency versions. Fix: Ensure Cartfile.lock is committed to version control to lock exact dependency versions. Review all dependencies in Cartfile for known vulnerabilities using tools like OWASP Dependency-Check or Snyk.
• Low · Xcode Project Configuration Exposure — Example/Koloda.xcodeproj/project.pbxproj, Example/Koloda.xcworkspace/. Xcode project files (.pbxproj) and workspace configurations are committed to version control. While this is common practice, these files can contain sensitive build settings, code signing identities, or other configuration details if not properly managed. Fix: Review .pbxproj and workspace files to ensure no hardcoded credentials, API keys, or sensitive paths are present. Use build configuration files or environment variables for sensitive settings.
• Low · Missing Security Policy Documentation — .github/. No visible SECURITY.md or security policy file in the .github directory. This makes it unclear how security vulnerabilities should be reported responsibly. Fix: Create a SECURITY.md file in the .github directory documenting how security issues should be reported, following GitHub's recommended practice for responsible disclosure.
• Low · Limited Input Validation Framework Visible — Source code not fully provided. As a UI library for card-based animations, there's limited visibility into input validation patterns. If the library accepts user-provided data for card content, improper validation could lead to injection vulnerabilities. Fix: Ensure all user-provided input is properly validated and sanitized before use. If displaying user content, use safe APIs that prevent XSS-like attacks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.