diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7fa19eb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,620 @@
+# BuyMeCoffee.Maui
+
+[](https://dotnet.microsoft.com/apps/maui)
+[](https://dotnet.microsoft.com/apps/maui)
+[](LICENSE)
+[](https://www.nuget.org)
+
+A comprehensive .NET MAUI library for integrating Buy Me a Coffee support into your cross-platform applications. Provides branded buttons, QR codes, and interactive widgets with official BMC styling and theming.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Controls](#controls)
+ - [BuyMeACoffeeButton](#buymeacoffeebutton)
+ - [BuyMeACoffeeQrCode](#buymeacoffeeqrcode)
+ - [BuyMeACoffeeWidget](#buymeacoffeewidget)
+- [Theming](#theming)
+- [API Reference](#api-reference)
+- [Platform Support](#platform-support)
+- [Dependencies](#dependencies)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+✅ **BuyMeACoffeeButton** - Branded button with official coffee cup logo and 8 color themes
+✅ **BuyMeACoffeeQrCode** - QR code generator with embedded BMC logo overlay
+✅ **BuyMeACoffeeWidget** - Full-featured support widget with amount selection, name/message fields, and monthly toggle
+✅ **Official Branding** - Uses authentic Buy Me a Coffee colors, logos, and styling
+✅ **Cross-Platform** - Supports Android, iOS, macOS, and Windows
+✅ **Customizable** - Extensive theming and styling options
+✅ **Touch Optimized** - Smooth animations and hover effects
+✅ **QR Code Generation** - High-quality QR codes with error correction level H
+
+## Installation
+
+### Prerequisites
+
+- .NET 10.0 SDK or later
+- .NET MAUI workload installed
+- Visual Studio 2022 17.8+ or Visual Studio Code with .NET MAUI extension
+
+### Add to Your Project
+
+1. **Add the project reference** to your .NET MAUI application:
+
+```xml
+
+
+
+```
+
+2. **Register the library** in your `MauiProgram.cs`:
+
+```csharp
+using BuyMeCofee.Maui;
+
+public static class MauiProgram
+{
+ public static MauiApp CreateMauiApp()
+ {
+ var builder = MauiApp.CreateBuilder();
+ builder
+ .UseMauiApp()
+ .UseBuyMeACoffee(); // Add this line
+
+ return builder.Build();
+ }
+}
+```
+
+This automatically registers SkiaSharp dependencies required for QR code rendering.
+
+## Quick Start
+
+Add the namespace to your XAML page:
+
+```xml
+xmlns:bmc="clr-namespace:BuyMeCofee.Maui.Controls;assembly=BuyMeCofee.Maui"
+```
+
+Add a button to your page:
+
+```xml
+
+```
+
+## Controls
+
+### BuyMeACoffeeButton
+
+A branded button that opens your Buy Me a Coffee page in the default browser.
+
+#### Basic Usage
+
+```xml
+
+```
+
+#### With Custom Styling
+
+```xml
+
+```
+
+#### Custom Theme
+
+```xml
+
+```
+
+#### Code-Behind Example
+
+```csharp
+using BuyMeCofee.Maui.Controls;
+using BuyMeCofee.Maui.Enums;
+
+var button = new BuyMeACoffeeButton
+{
+ Username = "yourname",
+ ButtonText = "Buy me a coffee",
+ Theme = BmcButtonTheme.Blue,
+ CornerRadius = 10,
+ FontSize = 16,
+ CupSize = 28
+};
+
+layout.Children.Add(button);
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
+| `ButtonText` | `string` | `"Buy me a coffee"` | Button label text |
+| `Theme` | `BmcButtonTheme` | `Yellow` | Color theme preset (Yellow, Black, White, Blue, Violet, Orange, Red, Green, Custom) |
+| `CustomBackgroundColor` | `Color?` | `null` | Background color (Custom theme only) |
+| `CustomTextColor` | `Color?` | `null` | Text color (Custom theme only) |
+| `CornerRadius` | `double` | `8.0` | Border corner radius |
+| `FontSize` | `double` | `16.0` | Button text font size |
+| `CupSize` | `double` | `28.0` | Coffee cup logo height |
+
+### BuyMeACoffeeQrCode
+
+Generates a QR code linking to your BMC profile with the coffee cup logo overlaid in the center.
+
+#### Basic Usage
+
+```xml
+
+```
+
+#### With Custom Colors
+
+```xml
+
+```
+
+#### Code-Behind Example
+
+```csharp
+using BuyMeCofee.Maui.Controls;
+
+var qrCode = new BuyMeACoffeeQrCode
+{
+ Username = "yourname",
+ Size = 250,
+ ForegroundColor = Colors.Black,
+ BackgroundColor = Colors.White,
+ LogoSizeFraction = 0.25
+};
+
+layout.Children.Add(qrCode);
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
+| `Size` | `double` | `200.0` | Width and height of the QR code |
+| `ForegroundColor` | `Color` | `Black` | QR code module color |
+| `BackgroundColor` | `Color` | `White` | QR code background color |
+| `LogoSizeFraction` | `double` | `0.25` | Logo size as fraction of QR code (0.0-0.35) |
+
+### BuyMeACoffeeWidget
+
+A full-featured support widget with amount entry, preset chips, name/message fields, and monthly subscription toggle.
+
+#### Basic Usage
+
+```xml
+
+```
+
+#### With Custom Configuration
+
+```xml
+
+```
+
+#### Handling Support Events
+
+```xml
+
+```
+
+```csharp
+private void OnSupportRequested(object sender, SupportRequestedEventArgs e)
+{
+ Console.WriteLine($"Support requested by: {e.Name ?? "Anonymous"}");
+ Console.WriteLine($"Amount: ${e.Amount}");
+ Console.WriteLine($"Message: {e.Message ?? "No message"}");
+ Console.WriteLine($"Monthly: {e.IsMonthly}");
+
+ // Log analytics, show confirmation, etc.
+}
+```
+
+#### Code-Behind Example
+
+```csharp
+using BuyMeCofee.Maui.Controls;
+using BuyMeCofee.Maui.Models;
+
+var widget = new BuyMeACoffeeWidget
+{
+ Username = "yourname",
+ DisplayName = "John Doe",
+ DefaultAmount = 5,
+ SuggestedAmounts = new[] { 25, 50, 100 },
+ AccentColor = Color.FromArgb("#6C5CE7"),
+ ShowMonthlyOption = true,
+ SupportButtonText = "Support"
+};
+
+widget.SupportRequested += (sender, e) =>
+{
+ // Handle support request
+ Debug.WriteLine($"Amount: ${e.Amount}, Monthly: {e.IsMonthly}");
+};
+
+layout.Children.Add(widget);
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
+| `DisplayName` | `string` | `""` | Name displayed in header ("Support {DisplayName}") |
+| `SuggestedAmounts` | `int[]` | `[25, 50, 100]` | Preset amount chips |
+| `DefaultAmount` | `int` | `5` | Initial amount in entry field |
+| `AccentColor` | `Color` | `#6C5CE7` | Support button background color |
+| `ShowMonthlyOption` | `bool` | `true` | Show "Make this monthly" checkbox |
+| `SupportButtonText` | `string` | `"Support"` | Support button label text |
+
+#### Events
+
+| Event | EventArgs | Description |
+|-------|-----------|-------------|
+| `SupportRequested` | `SupportRequestedEventArgs` | Raised when user taps Support button, before opening browser |
+
+**SupportRequestedEventArgs Properties:**
+
+```csharp
+public class SupportRequestedEventArgs : EventArgs
+{
+ public string Username { get; init; } // BMC username
+ public int Amount { get; init; } // Support amount
+ public string? Name { get; init; } // Supporter name (optional)
+ public string? Message { get; init; } // Support message (optional)
+ public bool IsMonthly { get; init; } // Monthly subscription toggle
+}
+```
+
+## Theming
+
+### Button Themes
+
+The library includes 8 official Buy Me a Coffee color themes:
+
+```csharp
+public enum BmcButtonTheme
+{
+ Yellow, // #FFDD00 - Official BMC brand color
+ Black, // #0D0C22 - Dark theme
+ White, // #FFFFFF - Light theme with stroke
+ Blue, // #5F7FFF
+ Violet, // #BD5CFF
+ Orange, // #FF813F
+ Red, // #FF6073
+ Green, // #78DEC7
+ Custom // Use CustomBackgroundColor and CustomTextColor
+}
+```
+
+### Theme Examples
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### Brand Colors Reference
+
+```csharp
+public static class BmcColors
+{
+ public const string CupYellow = "#FFDD00"; // Official cup color
+ public const string BrandDark = "#0D0C22"; // Brand dark
+ public const string WidgetPurple = "#6C5CE7"; // Widget accent
+ public const string WhiteStroke = "#E0E0E0"; // Border color
+}
+```
+
+## API Reference
+
+### Extension Methods
+
+```csharp
+public static class BuyMeACoffeeExtensions
+{
+ ///
+ /// Registers Buy Me a Coffee controls and their dependencies (SkiaSharp).
+ /// Call this in your MauiProgram.cs CreateMauiApp() builder.
+ ///
+ public static MauiAppBuilder UseBuyMeACoffee(this MauiAppBuilder builder);
+}
+```
+
+### Helper Classes
+
+#### BmcThemeResolver
+
+```csharp
+public static class BmcThemeResolver
+{
+ ///
+ /// Resolves a BmcButtonTheme enum to theme colors.
+ ///
+ /// Thrown for Custom theme
+ public static BmcThemeInfo Resolve(BmcButtonTheme theme);
+}
+
+public record BmcThemeInfo(Color Background, Color TextColor, Color StrokeColor);
+```
+
+#### BmcBrandAssets
+
+```csharp
+internal static class BmcBrandAssets
+{
+ internal static ImageSource GetCupLogo();
+ internal static Stream GetCupLogoStream();
+}
+```
+
+### Constants
+
+```csharp
+public static class BmcConstants
+{
+ public const string BaseUrl = "https://buymeacoffee.com/";
+ public const string DefaultButtonText = "Buy me a coffee";
+ public const string DefaultSupportButtonText = "Support";
+ public const double ButtonCornerRadius = 8.0;
+ public const double WidgetCornerRadius = 16.0;
+ public static readonly int[] DefaultSuggestedAmounts = [25, 50, 100];
+}
+```
+
+## Platform Support
+
+| Platform | Minimum Version | Status |
+|----------|----------------|--------|
+| **Android** | API 21 (Android 5.0) | ✅ Supported |
+| **iOS** | 15.0+ | ✅ Supported |
+| **macOS** (Catalyst) | 15.0+ | ✅ Supported |
+| **Windows** | 10.0.17763.0+ | ✅ Supported |
+
+**Note:** On Linux, only Android targets are built by default. iOS and macOS Catalyst require macOS build environment.
+
+## Dependencies
+
+The library requires the following NuGet packages:
+
+```xml
+
+
+
+```
+
+These are automatically installed when you reference the project.
+
+## Examples
+
+### Complete Page Example
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### Dynamic Theme Switching
+
+```csharp
+using BuyMeCofee.Maui.Controls;
+using BuyMeCofee.Maui.Enums;
+
+public partial class ThemePage : ContentPage
+{
+ private BuyMeACoffeeButton _button;
+ private readonly BmcButtonTheme[] _themes =
+ {
+ BmcButtonTheme.Yellow,
+ BmcButtonTheme.Black,
+ BmcButtonTheme.Blue,
+ BmcButtonTheme.Violet,
+ BmcButtonTheme.Orange,
+ BmcButtonTheme.Red,
+ BmcButtonTheme.Green
+ };
+ private int _currentThemeIndex = 0;
+
+ public ThemePage()
+ {
+ InitializeComponent();
+
+ _button = new BuyMeACoffeeButton
+ {
+ Username = "yourname",
+ Theme = _themes[0]
+ };
+
+ var switchButton = new Button { Text = "Change Theme" };
+ switchButton.Clicked += OnSwitchTheme;
+
+ var layout = new VerticalStackLayout
+ {
+ Spacing = 20,
+ Padding = 20,
+ Children = { _button, switchButton }
+ };
+
+ Content = layout;
+ }
+
+ private void OnSwitchTheme(object sender, EventArgs e)
+ {
+ _currentThemeIndex = (_currentThemeIndex + 1) % _themes.Length;
+ _button.Theme = _themes[_currentThemeIndex];
+ }
+}
+```
+
+### Analytics Integration
+
+```csharp
+using BuyMeCofee.Maui.Controls;
+using BuyMeCofee.Maui.Models;
+
+public partial class AnalyticsPage : ContentPage
+{
+ public AnalyticsPage()
+ {
+ InitializeComponent();
+
+ var widget = new BuyMeACoffeeWidget
+ {
+ Username = "yourname",
+ DisplayName = "John Doe"
+ };
+
+ widget.SupportRequested += OnSupportRequested;
+
+ Content = widget;
+ }
+
+ private void OnSupportRequested(object sender, SupportRequestedEventArgs e)
+ {
+ // Log to analytics service
+ AnalyticsService.TrackEvent("SupportRequested", new Dictionary
+ {
+ { "username", e.Username },
+ { "amount", e.Amount.ToString() },
+ { "is_monthly", e.IsMonthly.ToString() },
+ { "has_name", (!string.IsNullOrEmpty(e.Name)).ToString() },
+ { "has_message", (!string.IsNullOrEmpty(e.Message)).ToString() }
+ });
+
+ // Show confirmation
+ DisplayAlert("Thank You!",
+ $"You're about to support with ${e.Amount}. Redirecting to Buy Me a Coffee...",
+ "OK");
+ }
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
+
+### Development Setup
+
+1. Clone the repository
+2. Open in Visual Studio 2022 or VS Code
+3. Ensure .NET MAUI workload is installed
+4. Build and run the sample project
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+---
+
+**Not affiliated with Buy Me a Coffee.** This is an unofficial community library. Buy Me a Coffee and its branding are trademarks of Buy Me a Coffee LLC.
\ No newline at end of file