From 11825fa01f38cb127aa5569c91eea099136cb23a Mon Sep 17 00:00:00 2001
From: Nikita Vasilev <nv3212@gmail.com>
Date: Sun, 18 Jan 2026 19:43:18 +0400
Subject: [PATCH] docs: update `README.md`

---
 CONTRIBUTING.md | 646 +++++++++++++++++++++++++++++++++++++++++++++---
 README.md       | 298 ++++++++++++++++++++--
 2 files changed, 879 insertions(+), 65 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d97da7b..16fda6f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,61 +1,627 @@
-# Contributing Guidelines
+# Contributing to Transitions
 
-This document contains information and guidelines about contributing to this project.
-Please read it before you start participating.
+First off, thank you for considering contributing to Transitions! It's people like you that make Transitions such a great tool.
 
-**Topics**
+## Table of Contents
 
-* [Reporting Issues](#reporting-issues)
-* [Submitting Pull Requests](#submitting-pull-requests)
-* [Developers Certificate of Origin](#developers-certificate-of-origin)
-* [Code of Conduct](#code-of-conduct)
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+  - [Development Setup](#development-setup)
+  - [Project Structure](#project-structure)
+- [How Can I Contribute?](#how-can-i-contribute)
+  - [Reporting Bugs](#reporting-bugs)
+  - [Suggesting Features](#suggesting-features)
+  - [Improving Documentation](#improving-documentation)
+  - [Submitting Code](#submitting-code)
+- [Development Workflow](#development-workflow)
+  - [Branching Strategy](#branching-strategy)
+  - [Commit Guidelines](#commit-guidelines)
+  - [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+  - [Swift Style Guide](#swift-style-guide)
+  - [Code Quality](#code-quality)
+  - [Testing Requirements](#testing-requirements)
+- [Community](#community)
 
-## Reporting Issues
+## Code of Conduct
 
-A great way to contribute to the project is to send a detailed issue when you encounter a problem. We always appreciate a well-written, thorough bug report.
+This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to nv3212@gmail.com.
 
-Check that the project issues database doesn't already include that problem or suggestion before submitting an issue. If you find a match, feel free to vote for the issue by adding a reaction. Doing this helps prioritize the most common problems and requests.
+## Getting Started
 
-When reporting issues, please fill out our issue template. The information the template asks for will help us review and fix your issue faster.
+### Development Setup
 
-## Submitting Pull Requests
+1. **Fork the repository**
+   ```bash
+   # Click the "Fork" button on GitHub
+   ```
 
-You can contribute by fixing bugs or adding new features. For larger code changes, we recommend first discussing your ideas on our [GitHub Discussions](https://github.com/space-code/transitions/discussions). When submitting a pull request, please add relevant tests and ensure your changes don't break any existing tests.
+2. **Clone your fork**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/transitions.git
+   cd transitions
+   ```
 
-## Developer's Certificate of Origin 1.1
+3. **Set up the development environment**
+   ```bash
+   # Bootstrap the project
+   make bootstrap
+   ```
 
-By making a contribution to this project, I certify that:
+4. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
 
-- (a) The contribution was created in whole or in part by me and I
-      have the right to submit it under the open source license
-      indicated in the file; or
+5. **Open the project in Xcode**
+   ```bash
+   open Package.swift
+   ```
 
-- (b) The contribution is based upon previous work that, to the best
-      of my knowledge, is covered under an appropriate open source
-      license and I have the right under that license to submit that
-      work with modifications, whether created in whole or in part
-      by me, under the same open source license (unless I am
-      permitted to submit under a different license), as indicated
-      in the file; or
+## How Can I Contribute?
 
-- (c) The contribution was provided directly to me by some other
-      person who certified (a), (b) or (c) and I have not modified
-      it.
+### Reporting Bugs
 
-- (d) I understand and agree that this project and the contribution
-      are public and that a record of the contribution (including all
-      personal information I submit with it, including my sign-off) is
-      maintained indefinitely and may be redistributed consistent with
-      this project or the open source license(s) involved.
+Before creating a bug report, please check the [existing issues](https://github.com/space-code/transitions/issues) to avoid duplicates.
 
-## Code of Conduct
+When creating a bug report, include:
+
+- **Clear title** - Describe the issue concisely
+- **Reproduction steps** - Detailed steps to reproduce the bug
+- **Expected behavior** - What you expected to happen
+- **Actual behavior** - What actually happened
+- **Environment** - iOS version, Xcode version, Swift version
+- **Code samples** - Minimal reproducible example
+- **Error messages** - Complete error output if applicable
+
+**Example:**
+```markdown
+**Title:** Custom transition not triggering on dismissal
+
+**Steps to reproduce:**
+1. Create CustomTransition subclass with custom dismissal animation
+2. Assign transition to view controller using customTransition property
+3. Present view controller
+4. Dismiss view controller
+
+**Expected:** Custom dismissal animation should play
+**Actual:** Default dismissal animation is used instead
+
+**Environment:**
+- iOS 16.0
+- Xcode 15.3
+- Swift 5.10
+
+**Code:**
+```swift
+final class FadeTransition: CustomTransition {
+    override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
+        super.animateTransition(using: transitionContext)
+        // Custom animation code
+    }
+}
+
+let vc = UIViewController()
+vc.customTransition = FadeTransition()
+present(vc, animated: true)
+dismiss(animated: true) // Uses default animation instead of custom
+```
+```
+
+### Suggesting Features
+
+We love feature suggestions! When proposing a new feature, include:
+
+- **Problem statement** - What problem does this solve?
+- **Proposed solution** - How should it work?
+- **Alternatives** - What alternatives did you consider?
+- **Use cases** - Real-world scenarios
+- **API design** - Example code showing usage
+- **Breaking changes** - Will this break existing code?
+
+**Example:**
+```markdown
+**Feature:** Add interactive transition support
+
+**Problem:** Current implementation doesn't support interactive (gesture-driven) transitions, limiting use cases for custom dismissal gestures.
+
+**Solution:** Add `InteractiveTransition` protocol and gesture recognizer integration to enable swipe-to-dismiss and other interactive transitions.
+
+**API:**
+```swift
+final class SwipeDismissTransition: CustomTransition, InteractiveTransition {
+    var percentComplete: CGFloat = 0
+    
+    func updateInteractiveTransition(_ percentComplete: CGFloat) {
+        self.percentComplete = percentComplete
+    }
+    
+    func finishInteractiveTransition() {
+        // Complete transition
+    }
+    
+    func cancelInteractiveTransition() {
+        // Cancel and return to original state
+    }
+}
+
+let vc = UIViewController()
+vc.customTransition = SwipeDismissTransition()
+vc.customTransition?.enableInteractiveGesture(.swipeDown)
+```
+
+**Use case:** Modal views that can be dismissed by swiping down, similar to native iOS modal presentations.
+```
+
+### Improving Documentation
+
+Documentation improvements are always welcome:
+
+- **Code comments** - Add/improve inline documentation
+- **DocC documentation** - Enhance documentation articles
+- **README** - Fix typos, add examples
+- **Guides** - Write tutorials or how-to guides
+- **API documentation** - Document public APIs
+
+### Submitting Code
 
-The Code of Conduct governs how we behave in public or in private
-whenever the project will be judged by our actions.
-We expect it to be honored by everyone who contributes to this project.
+1. **Check existing work** - Look for related issues or PRs
+2. **Discuss major changes** - Open an issue for large features
+3. **Follow coding standards** - See [Coding Standards](#coding-standards)
+4. **Write tests** - All code changes require tests
+5. **Update documentation** - Keep docs in sync with code
+6. **Create a pull request** - Use clear description
 
-See [CODE_OF_CONDUCT.md](https://github.com/space-code/transitions/blob/master/CODE_OF_CONDUCT.md) for details.
+## Development Workflow
+
+### Branching Strategy
+
+We use a simplified branching model:
+
+- **`main`** - Main development branch (all PRs target this)
+- **`feature/*`** - New features
+- **`fix/*`** - Bug fixes
+- **`docs/*`** - Documentation updates
+- **`refactor/*`** - Code refactoring
+- **`test/*`** - Test improvements
+
+**Branch naming examples:**
+```bash
+feature/interactive-transitions
+fix/dismissal-animation-timing
+docs/add-advanced-examples
+refactor/simplify-transition-context
+test/add-presentation-tests
+```
+
+### Commit Guidelines
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) for clear, structured commit history.
+
+**Format:**
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation changes
+- `style` - Code style (formatting, no logic changes)
+- `refactor` - Code refactoring
+- `test` - Adding or updating tests
+- `chore` - Maintenance tasks
+- `perf` - Performance improvements
+
+**Scopes:**
+- `core` - Core transition logic
+- `animation` - Animation implementations
+- `delegate` - Transitioning delegate
+- `extension` - UIViewController extensions
+- `deps` - Dependencies
+
+**Examples:**
+```bash
+feat(core): add interactive transition support
+
+Implement InteractiveTransition protocol to enable gesture-driven
+transitions. Includes percentage-based updates and completion/
+cancellation handlers.
+
+Closes #23
 
 ---
 
-*Some of the ideas and wording for the statements above were based on work by the [Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md) and [Linux](https://elinux.org/Developer_Certificate_Of_Origin) communities.
+fix(animation): correct alpha animation timing for fade transition
+
+Fade animations were completing too quickly due to incorrect
+duration calculation. Now properly uses transitionDuration
+property for consistent timing.
+
+Fixes #45
+
+---
+
+docs(readme): add slide transition example
+
+Add complete example showing implementation of slide-in/slide-out
+transition with spring animation and proper frame calculations.
+
+---
+
+test(core): increase coverage for CustomTransition
+
+Add tests for:
+- Presentation with nil views
+- Dismissal animation completion
+- Spring animation parameters
+- Context cleanup on completion
+```
+
+**Commit message rules:**
+- Use imperative mood ("add" not "added")
+- Don't capitalize first letter
+- No period at the end
+- Keep subject line under 72 characters
+- Separate subject from body with blank line
+- Reference issues in footer
+
+### Pull Request Process
+
+1. **Update your branch**
+   ```bash
+   git checkout main
+   git pull upstream main
+   git checkout feature/your-feature
+   git rebase main
+   ```
+
+2. **Run tests and checks**
+   ```bash
+   # Run all tests
+   swift test
+   
+   # Check test coverage
+   swift test --enable-code-coverage
+   ```
+
+3. **Push to your fork**
+   ```bash
+   git push origin feature/your-feature
+   ```
+
+4. **Create pull request**
+   - Target the `main` branch
+   - Provide clear description
+   - Link related issues
+   - Include examples if applicable
+   - Request review from maintainers
+
+5. **Review process**
+   - Address review comments
+   - Keep PR up to date with main
+   - Squash commits if requested
+   - Wait for CI to pass
+
+6. **After merge**
+   ```bash
+   # Clean up local branch
+   git checkout main
+   git pull upstream main
+   git branch -d feature/your-feature
+   
+   # Clean up remote branch
+   git push origin --delete feature/your-feature
+   ```
+
+## Coding Standards
+
+### Swift Style Guide
+
+We follow the [Swift API Design Guidelines](https://swift.org/documentation/api-design-guidelines/) and [Ray Wenderlich Swift Style Guide](https://github.com/raywenderlich/swift-style-guide).
+
+**Key points:**
+
+1. **Naming**
+   ```swift
+   // ✅ Good
+   func animateTransition(using transitionContext: UIViewControllerContextTransitioning)
+   let transitionDuration: TimeInterval
+   
+   // ❌ Bad
+   func animate(_ ctx: UIViewControllerContextTransitioning)
+   let duration: Double
+   ```
+
+2. **Protocols**
+   ```swift
+   // ✅ Good - Descriptive protocol names
+   protocol ICustomTransitionAnimating {
+       func animatePresentation(using context: UIViewControllerContextTransitioning)
+       func animateDismissal(using context: UIViewControllerContextTransitioning)
+   }
+   
+   // ❌ Bad
+   protocol Animator { }
+   ```
+
+3. **Access Control**
+   ```swift
+   // ✅ Good - Explicit access control
+   open class CustomTransition: NSObject {
+       public var transitionDuration: TimeInterval = 0.3
+       private(set) var isPresenting: Bool = true
+       
+       open func animateTransition(
+           using transitionContext: UIViewControllerContextTransitioning
+       ) {
+           // Implementation
+       }
+       
+       public func completeTransaction() {
+           // Implementation
+       }
+   }
+   ```
+
+4. **Documentation**
+   ```swift
+   /// A base class for creating custom view controller transitions.
+   ///
+   /// Subclass `CustomTransition` to create custom presentation and dismissal
+   /// animations for view controllers. Override `animateTransition(using:)` to
+   /// implement your custom animation logic.
+   ///
+   /// - Note: Always call `super.animateTransition(using:)` at the beginning
+   ///   of your implementation to ensure proper setup.
+   ///
+   /// - Example:
+   /// ```swift
+   /// final class FadeTransition: CustomTransition {
+   ///     override func animateTransition(
+   ///         using transitionContext: UIViewControllerContextTransitioning
+   ///     ) {
+   ///         super.animateTransition(using: transitionContext)
+   ///         
+   ///         guard let toView = transitionContext.view(forKey: .to) else {
+   ///             transitionContext.completeTransition(false)
+   ///             return
+   ///         }
+   ///         
+   ///         // Implement fade animation
+   ///     }
+   /// }
+   /// ```
+   open class CustomTransition: NSObject {
+       // Implementation
+   }
+   ```
+
+### Code Quality
+
+- **No force unwrapping** - Use optional binding or guards
+- **No force casting** - Use conditional casting
+- **No magic numbers** - Use named constants
+- **Single responsibility** - One class, one purpose
+- **DRY principle** - Don't repeat yourself
+- **SOLID principles** - Follow SOLID design
+
+**Example:**
+```swift
+// ✅ Good
+private enum TransitionConstants {
+    static let defaultDuration: TimeInterval = 0.3
+    static let springDamping: CGFloat = 0.7
+    static let springVelocity: CGFloat = 0.5
+}
+
+guard let toView = transitionContext.view(forKey: .to) else {
+    transitionContext.completeTransition(false)
+    return
+}
+
+// ❌ Bad
+let view = transitionContext.view(forKey: .to)!
+if view.frame.width > 0.7 {
+    // Magic numbers and force unwrap
+}
+```
+
+### Testing Requirements
+
+All code changes must include tests following the naming convention: `test_that<action>_when<condition>`
+
+1. **Unit tests** - Test individual components
+2. **Integration tests** - Test component interactions
+3. **Animation tests** - Test animation behavior
+4. **Edge cases** - Test boundary conditions
+5. **Error handling** - Test failure scenarios
+
+**Coverage requirements:**
+- New code: minimum 80% coverage
+- Modified code: maintain or improve existing coverage
+- Critical paths: 100% coverage
+
+**Test structure:**
+```swift
+import XCTest
+@testable import Transitions
+
+final class CustomTransitionTests: XCTestCase {
+    var sut: CustomTransition!
+    var mockTransitionContext: MockTransitionContext!
+    
+    override func setUp() {
+        super.setUp()
+        sut = CustomTransition()
+        mockTransitionContext = MockTransitionContext()
+    }
+    
+    override func tearDown() {
+        sut = nil
+        mockTransitionContext = nil
+        super.tearDown()
+    }
+    
+    // MARK: - Presentation Tests
+    
+    func test_thatAnimatesPresentation_whenIsPresentingIsTrue() {
+        // Given
+        sut.isPresenting = true
+        let expectation = expectation(description: "Animation completes")
+        
+        // When
+        sut.animateTransition(using: mockTransitionContext)
+        
+        // Then
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.4) {
+            XCTAssertTrue(self.mockTransitionContext.didCompleteTransition)
+            expectation.fulfill()
+        }
+        
+        waitForExpectations(timeout: 1.0)
+    }
+    
+    // MARK: - Dismissal Tests
+    
+    func test_thatAnimatesDismissal_whenIsPresentingIsFalse() {
+        // Given
+        sut.isPresenting = false
+        let expectation = expectation(description: "Animation completes")
+        
+        // When
+        sut.animateTransition(using: mockTransitionContext)
+        
+        // Then
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.4) {
+            XCTAssertTrue(self.mockTransitionContext.didCompleteTransition)
+            expectation.fulfill()
+        }
+        
+        waitForExpectations(timeout: 1.0)
+    }
+    
+    // MARK: - Edge Cases
+    
+    func test_thatCompletesTransitionWithFailure_whenToViewIsNil() {
+        // Given
+        sut.isPresenting = true
+        mockTransitionContext.toView = nil
+        
+        // When
+        sut.animateTransition(using: mockTransitionContext)
+        
+        // Then
+        XCTAssertTrue(mockTransitionContext.didCompleteTransition)
+        XCTAssertFalse(mockTransitionContext.transitionWasSuccessful)
+    }
+    
+    func test_thatUsesCustomDuration_whenDurationIsSet() {
+        // Given
+        let customDuration: TimeInterval = 0.5
+        sut.transitionDuration = customDuration
+        
+        // When
+        let duration = sut.transitionDuration(using: mockTransitionContext)
+        
+        // Then
+        XCTAssertEqual(duration, customDuration)
+    }
+    
+    // MARK: - Animation Behavior Tests
+    
+    func test_thatAppliesCorrectInitialState_whenPresentationStarts() {
+        // Given
+        sut.isPresenting = true
+        let toView = UIView()
+        mockTransitionContext.toView = toView
+        
+        // When
+        sut.animateTransition(using: mockTransitionContext)
+        
+        // Then
+        // Verify initial animation state
+        XCTAssertNotNil(toView.layer.animationKeys())
+    }
+}
+
+// MARK: - Mock Objects
+
+final class MockTransitionContext: NSObject, UIViewControllerContextTransitioning {
+    var containerView: UIView = UIView()
+    var isAnimated: Bool = true
+    var isInteractive: Bool = false
+    var transitionWasCancelled: Bool = false
+    var presentationStyle: UIModalPresentationStyle = .custom
+    
+    var didCompleteTransition = false
+    var transitionWasSuccessful = false
+    
+    var toView: UIView?
+    var fromView: UIView?
+    
+    func completeTransition(_ didComplete: Bool) {
+        didCompleteTransition = true
+        transitionWasSuccessful = didComplete
+    }
+    
+    func viewController(forKey key: UITransitionContextViewControllerKey) -> UIViewController? {
+        return nil
+    }
+    
+    func view(forKey key: UITransitionContextViewKey) -> UIView? {
+        switch key {
+        case .to: return toView
+        case .from: return fromView
+        default: return nil
+        }
+    }
+    
+    // Implement other required protocol methods...
+}
+```
+
+**Test naming examples:**
+```swift
+// ✅ Good - Clear, descriptive test names
+func test_thatAnimatesPresentation_whenIsPresentingIsTrue()
+func test_thatCompletesTransition_whenAnimationFinishes()
+func test_thatCallsSuperMethod_whenAnimateTransitionIsCalled()
+func test_thatAddsToViewToContainer_whenPresenting()
+func test_thatRemovesFromView_whenDismissing()
+
+// ❌ Bad - Vague or unclear
+func testAnimation()
+func testPresent()
+func testThatWorks()
+```
+
+## Community
+
+- **Discussions** - Join [GitHub Discussions](https://github.com/space-code/transitions/discussions)
+- **Issues** - Track [open issues](https://github.com/space-code/transitions/issues)
+- **Pull Requests** - Review [open PRs](https://github.com/space-code/transitions/pulls)
+
+## Recognition
+
+Contributors are recognized in:
+- GitHub contributors page
+- Release notes
+- Project README (for significant contributions)
+
+## Questions?
+
+- Check [existing issues](https://github.com/space-code/transitions/issues)
+- Search [discussions](https://github.com/space-code/transitions/discussions)
+- Ask in [Q&A discussions](https://github.com/space-code/transitions/discussions/categories/q-a)
+- Email the maintainer: nv3212@gmail.com
+
+---
+
+Thank you for contributing to Transitions! 🎉
+
+Your efforts help make this project better for everyone.
\ No newline at end of file
diff --git a/README.md b/README.md
index a6b91c5..dca2bfc 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+# transitions
+
 <h1 align="center" style="margin-top: 0px;">transitions</h1>
 
 <p align="center">
@@ -5,69 +7,315 @@
 <a href="https://swiftpackageindex.com/space-code/transitions"><img alt="Swift Compatibility" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fspace-code%2Ftransitions%2Fbadge%3Ftype%3Dswift-versions"/></a> 
 <a href="https://swiftpackageindex.com/space-code/transitions"><img alt="Platform Compatibility" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fspace-code%2Ftransitions%2Fbadge%3Ftype%3Dplatforms"/></a> 
 <a href="https://github.com/space-code/transitions"><img alt="CI" src="https://github.com/space-code/transitions/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+<a href="https://github.com/apple/swift-package-manager" alt="transitions on Swift Package Manager" title="transitions on Swift Package Manager"><img src="https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg" /></a>
+<a href="https://codecov.io/gh/space-code/transitions"><img src="https://codecov.io/gh/space-code/transitions/graph/badge.svg"/></a>
 </p>
 
 ## Description
-`transitions` is a framework that reduces the hassle of creating custom transitions.
+Transitions is a modern, lightweight Swift framework that simplifies the creation of custom view controller transitions for iOS. Built to reduce boilerplate and enhance code clarity, it provides an elegant API for crafting beautiful presentation and dismissal animations with minimal effort.
+
+## Features
+
+✨ **Simple API** - Clean, intuitive interface for custom transitions  
+🎨 **Flexible Animations** - Full control over presentation and dismissal  
+🎯 **Type-Safe** - Leverages Swift's type system for compile-time safety  
+🔧 **Customizable** - Tailor transitions to match your app's unique style  
+📱 **iOS Native** - Built specifically for iOS with UIKit best practices  
+⚡ **Lightweight** - Minimal footprint with zero dependencies  
+
+## Table of Contents
 
-- [Usage](#usage)
 - [Requirements](#requirements)
 - [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Creating a Custom Transition](#creating-a-custom-transition)
+  - [Applying Transitions](#applying-transitions)
+- [Common Use Cases](#common-use-cases)
 - [Communication](#communication)
+- [Documentation](#documentation)
 - [Contributing](#contributing)
+  - [Development Setup](#development-setup)
 - [Author](#author)
 - [License](#license)
 
-## Usage
+## Requirements
+
+| Platform  | Minimum Version |
+|-----------|----------------|
+| iOS       | 12.0+          |
+| Xcode     | 15.3+          |
+| Swift     | 5.10+           |
+
+## Installation
+
+### Swift Package Manager
+
+Add the following dependency to your `Package.swift`:
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/space-code/transitions.git", from: "1.0.0")
+]
+```
+
+Or add it through Xcode:
+
+1. File > Add Package Dependencies
+2. Enter package URL: `https://github.com/space-code/transitions.git`
+3. Select version requirements
+
+## Quick Start
 
 ```swift
 import Transitions
 
+// Create your custom transition
 final class ZoomTransition: CustomTransition {
-    // Implementation of the required protocol methods and properties.
+    // Implement your custom animation logic
 }
 
+// Apply it to a view controller
 let viewController = UIViewController()
 viewController.customTransition = ZoomTransition()
 
-self.present(viewController, animated: true)
+// Present with your custom transition
+present(viewController, animated: true)
 ```
 
-## Requirements
+## Usage
 
-- iOS 12.0+
-- Xcode 14.0
-- Swift 5.7
+### Creating a Custom Transition
 
-## Installation
-### Swift Package Manager
+Transitions makes it easy to create custom animations by conforming to the `CustomTransition` protocol:
 
-The [Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the `swift` compiler. It is in early development, but `transitions` does support its use on supported platforms.
+```swift
+import Transitions
+import UIKit
+
+final class FadeTransition: CustomTransition {
+    override func animateTransition(
+        using transitionContext: UIViewControllerContextTransitioning
+    ) {
+        
+        super.animateTransition(using: transitionContext)
+        
+        let containerView = transitionContext.containerView
+        
+        guard let animatingView = isPresenting ?
+                transitionContext.view(forKey: .to) :
+                    transitionContext.view(forKey: .from)
+        else {
+            transitionContext.completeTransition(false)
+            return
+        }
+        
+        if isPresenting {
+            animatingView.alpha = 0
+            containerView.addSubview(animatingView)
+        }
+        
+        let finalAlpha: CGFloat = isPresenting ? 1.0 : 0.0
+        
+        UIView.animate(
+            withDuration: transitionDuration,
+            animations: {
+                animatingView.alpha = finalAlpha
+            },
+            completion: { finished in
+                self.completeTransaction()
+            }
+        )
+    }
+}
+```
 
-Once you have your Swift package set up, adding `transitions` as a dependency is as easy as adding it to the `dependencies` value of your `Package.swift`.
+### Applying Transitions
+
+Once you've created your custom transition, applying it is straightforward:
 
 ```swift
-dependencies: [
-    .package(url: "https://github.com/space-code/transitions.git", .upToNextMajor(from: "1.0.0"))
-]
+import Transitions
+
+let detailViewController = DetailViewController()
+detailViewController.customTransition = FadeTransition()
+
+present(detailViewController, animated: true)
+```
+
+## Common Use Cases
+
+### Zoom Transition
+
+```swift
+import Transitions
+import UIKit
+
+final class ZoomTransition: CustomTransition {
+    override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
+        super.animateTransition(using: transitionContext)
+        
+        if isPresenting {
+            animatePresentation(using: transitionContext)
+        } else {
+            animateDismissal(using: transitionContext)
+        }
+    }
+    
+    // MARK: - Private Methods
+    
+    private func animatePresentation(using transitionContext: UIViewControllerContextTransitioning) {
+        guard let toView = transitionContext.view(forKey: .to) else {
+            transitionContext.completeTransition(false)
+            return
+        }
+        
+        let containerView = transitionContext.containerView
+
+        toView.transform = CGAffineTransform(scaleX: 0.1, y: 0.1)
+        toView.alpha = 0
+        containerView.addSubview(toView)
+        
+        UIView.animate(
+            withDuration: transitionDuration,
+            delay: 0,
+            usingSpringWithDamping: 0.7,
+            initialSpringVelocity: 0.5,
+            options: .curveEaseInOut,
+            animations: {
+                toView.transform = .identity
+                toView.alpha = 1.0
+            },
+            completion: { _ in
+                self.completeTransaction()
+            }
+        )
+    }
+    
+    private func animateDismissal(using transitionContext: UIViewControllerContextTransitioning) {
+        guard let fromView = transitionContext.view(forKey: .from) else {
+            transitionContext.completeTransition(false)
+            return
+        }
+        
+        UIView.animate(
+            withDuration: transitionDuration,
+            animations: {
+                fromView.transform = CGAffineTransform(scaleX: 0.1, y: 0.1)
+                fromView.alpha = 0
+            },
+            completion: { _ in
+                self.completeTransaction()
+            }
+        )
+    }
+}
+```
+
+### Slide Transition
+
+```swift
+import Transitions
+import UIKit
+
+final class SlideTransition: CustomTransition {
+    override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
+        super.animateTransition(using: transitionContext)
+        
+        if isPresenting {
+            animatePresentation(using: transitionContext)
+        } else {
+            animateDismissal(using: transitionContext)
+        }
+    }
+    
+    // MARK: - Private Methods
+    
+    private func animatePresentation(using transitionContext: UIViewControllerContextTransitioning) {
+        guard let toView = transitionContext.view(forKey: .to) else {
+            transitionContext.completeTransition(false)
+            return
+        }
+        
+        let containerView = transitionContext.containerView
+        let finalFrame = transitionContext.finalFrame(for: transitionContext.viewController(forKey: .to)!)
+
+        toView.frame = finalFrame.offsetBy(dx: finalFrame.width, dy: 0)
+        containerView.addSubview(toView)
+        
+        UIView.animate(
+            withDuration: animationDuration,
+            delay: 0,
+            options: .curveEaseOut,
+            animations: {
+                toView.frame = finalFrame
+            },
+            completion: { _ in
+                self.completeTransaction()
+            }
+        )
+    }
+    
+    private func animateDismissal(using transitionContext: UIViewControllerContextTransitioning) {
+        guard let fromView = transitionContext.view(forKey: .from) else {
+            transitionContext.completeTransition(false)
+            return
+        }
+        
+        UIView.animate(
+            withDuration: animationDuration,
+            delay: 0,
+            options: .curveEaseIn,
+            animations: {
+                fromView.frame = fromView.frame.offsetBy(dx: fromView.frame.width, dy: 0)
+            },
+            completion: { _ in
+                self.completeTransaction()
+            }
+        )
+    }
+}
 ```
 
 ## Communication
-- If you **found a bug**, open an issue.
-- If you **have a feature request**, open an issue.
-- If you **want to contribute**, submit a pull request.
+
+- 🐛 **Found a bug?** [Open an issue](https://github.com/space-code/transitions/issues/new)
+- 💡 **Have a feature request?** [Open an issue](https://github.com/space-code/transitions/issues/new)
+- ❓ **Questions?** [Start a discussion](https://github.com/space-code/transitions/discussions)
+- 🔒 **Security issue?** Email nv3212@gmail.com
+
+## Documentation
+
+Comprehensive documentation is available: [Transitions Documentation](https://space-code.github.io/transitions/)
 
 ## Contributing
-Bootstrapping development environment
 
-```
+We love contributions! Please feel free to help out with this project. If you see something that could be made better or want a new feature, open up an issue or send a Pull Request.
+
+### Development Setup
+
+Bootstrap the development environment:
+
+```bash
 make bootstrap
 ```
 
-Please feel free to help out with this project! If you see something that could be made better or want a new feature, open up an issue or send a Pull Request!
-
 ## Author
-Nikita Vasilev, nv3212@gmail.com
+
+**Nikita Vasilev**
+- Email: nv3212@gmail.com
+- GitHub: [@ns-vasilev](https://github.com/ns-vasilev)
 
 ## License
-transitions is available under the MIT license. See the LICENSE file for more info.
+
+Transitions is released under the MIT license. See [LICENSE](https://github.com/space-code/transitions/blob/main/LICENSE) for details.
+
+---
+
+<div align="center">
+
+**[⬆ back to top](#transitions)**
+
+Made with ❤️ by [space-code](https://github.com/space-code)
+
+</div>
\ No newline at end of file