{"id":36351898,"url":"https://github.com/sazardev/animal_crossing_ui","last_synced_at":"2026-01-13T21:58:52.140Z","repository":{"id":331864413,"uuid":"1102621815","full_name":"sazardev/animal_crossing_ui","owner":"sazardev","description":"Build delightful apps with the cozy charm of Animal Crossing!","archived":false,"fork":false,"pushed_at":"2025-11-24T23:58:16.000Z","size":1860,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-11T16:21:47.907Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sazardev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-23T19:35:27.000Z","updated_at":"2025-11-24T23:58:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sazardev/animal_crossing_ui","commit_stats":null,"previous_names":["sazardev/animal_crossing_ui"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sazardev/animal_crossing_ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sazardev%2Fanimal_crossing_ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sazardev%2Fanimal_crossing_ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sazardev%2Fanimal_crossing_ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sazardev%2Fanimal_crossing_ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sazardev","download_url":"https://codeload.github.com/sazardev/animal_crossing_ui/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sazardev%2Fanimal_crossing_ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-11T13:35:59.262Z","updated_at":"2026-01-13T21:58:52.134Z","avatar_url":"https://github.com/sazardev.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Animal Crossing UI\n\nA comprehensive Flutter UI component library inspired by the warm, friendly design of Animal Crossing. Build beautiful applications with 60+ custom widgets, 16+ predefined themes, and a complete design system - no Material or Cupertino dependencies required.\n\n[![pub package](https://img.shields.io/pub/v/animal_crossing_ui.svg)](https://pub.dev/packages/animal_crossing_ui)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Flutter](https://img.shields.io/badge/Flutter-3.10.0+-blue.svg)](https://flutter.dev/)\n\n![Banner Logo](assets/banner.png)\n\n## Overview\n\nAnimal Crossing UI (ACUI) is a production-ready Flutter package that brings the signature flat, rounded, and friendly aesthetic of Animal Crossing games to your applications. Every component is built from scratch using Flutter's widget system, providing a cohesive design language independent of Material Design or Cupertino.\n\n**Key Features:**\n\n- **60+ Custom Components** - Complete widget library covering buttons, forms, navigation, dialogs, data display, and specialized game-inspired elements\n- **16+ Predefined Themes** - Character-based and seasonal color palettes with full light/dark mode support\n- **True Flat Design** - Authentic Animal Crossing aesthetic with rounded corners, soft colors, and friendly typography\n- **Zero Dependencies** - Built entirely with Flutter primitives, no Material or Cupertino required\n- **Responsive Utilities** - Built-in breakpoints and helpers for mobile, tablet, and desktop layouts\n- **Comprehensive Documentation** - Every component includes detailed API docs, examples, and usage patterns\n- **Production Ready** - Type-safe, well-tested, and optimized for real-world applications\n\n## Design Philosophy\n\nAnimal Crossing UI was created to provide Flutter developers with an alternative to Material Design and Cupertino, drawing inspiration from Nintendo's beloved life simulation franchise. The design system emphasizes:\n\n**Visual Principles:**\n\n- **Flat Design** - No shadows, gradients, or depth effects. Simple, clean surfaces.\n- **Rounded Everything** - Generous border radius on all interactive elements (8-20px)\n- **Soft Color Palette** - Pastel tones and muted colors that feel warm and welcoming\n- **Friendly Typography** - Rounded sans-serif fonts with comfortable sizing\n- **Consistent Spacing** - 8px base unit system for predictable layouts\n\n**Interaction Design:**\n\n- **Gentle Animations** - Smooth 200ms transitions with easing curves\n- **Clear Feedback** - Hover states, pressed states, and visual confirmation\n- **Intuitive Controls** - Familiar patterns adapted to flat aesthetic\n- **Accessibility First** - Semantic structure and screen reader support\n\n**Interaction Design:**\n\n- **Gentle Animations** - Smooth 200ms transitions with easing curves\n- **Clear Feedback** - Hover states, pressed states, and visual confirmation\n- **Intuitive Controls** - Familiar patterns adapted to flat aesthetic\n- **Accessibility First** - Semantic structure and screen reader support\n\n## Installation\n\nAdd to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  animal_crossing_ui: ^0.4.0\n```\n\nThen run:\n\n```bash\nflutter pub get\n```\n\n## Quick Start\n\n```dart\nimport 'package:flutter/widgets.dart';\nimport 'package:animal_crossing_ui/animal_crossing_ui.dart';\n\nvoid main() =\u003e runApp(const MyApp());\n\nclass MyApp extends StatelessWidget {\n  const MyApp({super.key});\n\n  @override\n  Widget build(BuildContext context) {\n    return ACUIApp(\n      title: 'My Application',\n      theme: ACUIThemePresets.isabelle,\n      home: ACUIScaffold(\n        appBar: ACUIAppBar(\n          title: const Text('Welcome'),\n        ),\n        body: Center(\n          child: ACUIButton(\n            onPressed: () {},\n            child: const Text('Get Started'),\n          ),\n        ),\n      ),\n    );\n  }\n}\n```\n\n## Component Library\n\nAnimal Crossing UI provides 60+ components organized into logical categories:\n\n### Core Components\n\n**ACUIApp** - Root application widget with theme management\n- Light/dark mode support\n- Custom theme configuration\n- Navigator integration\n- Global theme access via `ACUITheme.of(context)`\n\n**ACUIScaffold** - Screen layout structure\n- Predefined architectures (basic, centered, split, tabbed, etc.)\n- AppBar integration\n- Drawer support\n- Bottom navigation\n- Responsive layout helpers\n\n### Buttons \u0026 Actions\n\n**ACUIButton** - Primary action button\n- Variants: primary, secondary, outlined, text, icon\n- Sizes: small, medium, large\n- States: enabled, disabled, loading\n- Full customization support\n\n### Form Controls\n\n**ACUITextField** - Text input with validation\n- Placeholder and label support\n- Prefix/suffix icons\n- Error states\n- Focus animations\n- Password visibility toggle\n\n**ACUICheckbox** - Boolean toggle\n- Checked/unchecked states\n- Tri-state support\n- Custom colors\n\n**ACUISwitch** - Toggle switch\n- Smooth slide animation\n- Active/inactive states\n- Customizable colors\n\n**ACUIRadio** - Single choice selection\n- Generic type support\n- ACUIRadioListTile variant with label/subtitle\n- Group management\n\n**ACUISlider** - Value selection\n- Continuous range\n- Min/max constraints\n- Visual feedback\n\n**ACUIDropdown** - Selection menu\n- Scrollable options\n- Custom item rendering\n- Keyboard navigation\n\n### Data Display\n\n**ACUICard** - Content container\n- Rounded corners\n- Optional tap handling\n- Customizable padding and colors\n\n**ACUIListTile** - List item layout\n- Leading/trailing widgets\n- Title and subtitle\n- Interactive states\n\n**ACUIChip** - Tag or category label\n- Optional delete action\n- Compact sizing\n- Background customization\n\n**ACUIBadge** - Notification indicator\n- Dot or label variants\n- Positioning offset\n- Custom colors\n\n**ACUIAvatar** - Profile pictures\n- Image or placeholder support\n- Circular shape\n- Configurable radius\n\n**ACUIIcon** - Icon rendering\n- No Material dependency\n- Custom IconData support\n- Size and color props\n\n### Navigation\n\n**ACUIAppBar** - Top navigation bar\n- Title display\n- Leading widget (back button)\n- Action buttons\n- Automatic text contrast\n\n**ACUIDrawer** - Side navigation panel\n- Header and footer sections\n- Grouped menu items\n- Selection states\n- Custom width\n\n**ACUIBottomNavigationBar** - Bottom tabs\n- Icon and label display\n- Multiple items\n- Active state indicator\n- Badge support\n\n**ACUITabBar** - Segmented control\n- Equal-width tabs\n- Selection animation\n- Custom colors\n\n**ACUITabView** - Tab content display\n- State preservation with IndexedStack\n- Syncs with ACUITabBar\n- Lazy loading support\n\n### Dialogs \u0026 Overlays\n\n**ACUIDialog** - Modal dialog\n- Custom content\n- Dismissible barrier\n- Fade and scale animation\n- `showACUIDialog()` helper function\n\n**ACUIAlert** - Confirmation dialog\n- Title and message\n- OK/Cancel buttons\n- Async result handling\n- `showACUIAlert()` helper function\n\n**ACUISnackbar** - Bottom notification\n- Auto-dismiss\n- Optional action button\n- Slide-up animation\n- `showACUISnackbar()` helper function\n\n**ACUIToast** - Brief notification\n- Four types: success, error, warning, info\n- Global controller\n- Position options (top/center/bottom)\n- Auto-dismiss with custom duration\n\n**ACUIMenu** - Popup menu\n- Context menu support\n- Item list with icons\n- Position calculation\n- Generic return type\n- `showACUIMenu()` helper function\n\n### Pickers\n\n**ACUIDatePicker** - Calendar selection\n- Month/year navigation\n- Date range constraints\n- Today highlighting\n- `showACUIDatePicker()` helper function\n\n**ACUITimePicker** - Time selection\n- 12/24 hour format\n- Hour and minute adjustment\n- AM/PM toggle\n- `showACUITimePicker()` helper function\n\n### Progress Indicators\n\n**ACUILinearProgress** - Horizontal progress bar\n- Determinate (0.0-1.0 value)\n- Indeterminate (animated loading)\n- Custom colors and height\n\n**ACUIProgressIndicator** - Circular spinner\n- Determinate arc\n- Indeterminate rotation\n- CustomPaint rendering\n- Configurable size and stroke width\n\n**ACUILoadingSpinner** - Animated loading states\n- Six animation styles: spinner, dots, typing, fallingLetters, leaf, bells\n- Optional text display\n- Theme-aware colors\n- Game-inspired animations\n\n### Layout Utilities\n\n**ACUISection** - Labeled content area\n- Title and description\n- Optional action button\n- Organized grouping\n\n**ACUIContainer** - Styled box\n- Theme-aware colors\n- Rounded corners\n- Padding and margins\n- Alternative to ACUICard for simpler needs\n\n**ACUIExpansionPanel** - Collapsible section\n- Header with arrow icon\n- Smooth expand/collapse\n- State management\n- Title and subtitle support\n\n**ACUIDivider** / **ACUIVerticalDivider** - Visual separators\n- Horizontal and vertical variants\n- Configurable thickness\n- Theme border color\n- Optional indentation\n\n**ACUIListView** / **ACUIListViewBuilder** - Scrollable lists\n- Automatic spacing between items\n- Vertical/horizontal scrolling\n- Builder pattern for performance\n- Configurable padding\n\n**ACUIGridView** / **ACUIGridViewBuilder** - Grid layouts\n- Responsive column count\n- Aspect ratio control\n- Gap spacing\n- Builder pattern for efficiency\n\n**ACUISearchBar** - Search input\n- Search icon\n- Clear button\n- onChange callback\n- Submit handling\n\n**ACUIBanner** - Notification banner\n- Four types: info, warning, success, error\n- Leading icon\n- Dismiss action\n- Semantic colors\n\n**ACUIEmptyState** - No content placeholder\n- Icon display\n- Title and message\n- Optional action button\n- Centered layout\n\n### Navigation Extras\n\n**ACUINavigationDrawer** - Alternative drawer\n- Scrollable content\n- Header/footer support\n- ACUINavigationDrawerItem for menu entries\n- Selection states\n\n### Animal Crossing Game Components\n\nSpecialized widgets inspired by in-game interfaces:\n\n**ACUIBellCounter** - Currency display\n- Animated counting\n- Formatted numbers\n- Bell icon\n- Smooth transitions\n\n**ACUIStarRating** - Rating display\n- Interactive or read-only\n- Full and half stars\n- CustomPaint rendering\n- Configurable star count\n\n**ACUIDialogBox** - Character dialog\n- Typing animation\n- Three speed options\n- Character name display\n- Blinking cursor\n\n**ACUIInventoryGrid** - Pocket interface\n- Grid of item slots\n- Selection handling\n- Empty slot display\n- Quantity badges\n\n**ACUICatalogCard** - Item showcase\n- Image display\n- Name and price\n- Owned indicator\n- Bell currency\n\n**ACUIReactionWheel** - Circular picker\n- Radial layout\n- Emoji reactions\n- Tap selection\n- Animated highlight\n\n**ACUIWeatherWidget** - Weather display\n- Condition types\n- Temperature\n- Themed colors\n- Icon support\n\n**ACUIFossilDisplay** - Museum collection\n- Donated status\n- Icon display\n- Interactive cards\n- Progress tracking\n\n**ACUIFruitCounter** - Harvest tracking\n- Fruit type selection\n- CustomPaint fruit icons\n- Count display\n- Themed colors\n\n**ACUIMessageBottle** - Collectible message\n- Expandable content\n- Animation states\n- Author and date\n- Interactive disclosure\n\n**ACUISeasonalBanner** - Event announcements\n- Season themes\n- Custom messages\n- Responsive sizing\n- Decorative display\n\n**ACUINookPhone** - App launcher\n- Grid of apps\n- Icon and label\n- Tap handling\n- Phone-style interface\n\n**ACUIVillagerCard** - Character profile\n- Personality types\n- Photo display\n- Species and birthday\n- Catchphrase\n\n**ACUIAchievementBadge** - Reward display\n- Tier levels (bronze/silver/gold/platinum)\n- Icon and title\n- Description\n- Date earned\n\n**ACUIProgressTracker** - Collection progress\n- Current/total display\n- Progress bar\n- Percentage\n- Custom icons\n\n## Theming System\n\nAnimal Crossing UI includes a sophisticated theming system with 16+ predefined themes and full customization support.\n\n### Predefined Themes\n\n**Character Themes:**\n- `ACUIThemePresets.isabelle` - Cheerful yellow\n- `ACUIThemePresets.tomNook` - Warm brown\n- `ACUIThemePresets.kk` - Cool blue\n- `ACUIThemePresets.celeste` - Celestial purple\n- `ACUIThemePresets.timmy` - Friendly green\n- `ACUIThemePresets.kicks` - Stylish teal\n- `ACUIThemePresets.blathers` - Scholarly blue\n- `ACUIThemePresets.sable` - Elegant rose\n\n**Seasonal Themes:**\n- `ACUIThemePresets.spring` - Cherry blossom pink\n- `ACUIThemePresets.summer` - Beach blue\n- `ACUIThemePresets.autumn` - Maple orange\n- `ACUIThemePresets.winter` - Snowy white\n\n**Special Themes:**\n- `ACUIThemePresets.nookMiles` - Teal and orange\n- `ACUIThemePresets.nookShopping` - Shopping green\n- `ACUIThemePresets.classic` - Original game palette\n- `ACUIThemePresets.pastelDream` - Soft pastels\n\n### Custom Themes\n\nCreate your own theme:\n\n```dart\nfinal customTheme = ACUIThemeData(\n  primaryColor: Color(0xFF9ACD7B),\n  secondaryColor: Color(0xFF87CEEB),\n  backgroundColor: Color(0xFFFFFAF0),\n  surfaceColor: Color(0xFFFFFFFF),\n  textColor: Color(0xFF4A4A4A),\n  textSecondaryColor: Color(0xFF8A8A8A),\n  borderColor: Color(0xFFE0E0E0),\n  errorColor: Color(0xFFFF6B6B),\n  successColor: Color(0xFF9ACD7B),\n  warningColor: Color(0xFFFFB347),\n);\n\nACUIApp(\n  theme: customTheme,\n  // ...\n)\n```\n\n### Dark Mode\n\nAll themes include automatic dark mode variants accessed via `brightness` parameter:\n\n```dart\nACUIThemeData.fromPreset(\n  ACUIThemePresets.isabelle,\n  brightness: Brightness.dark,\n)\n```\n\nOr respond to system settings:\n\n```dart\nACUIApp(\n  theme: ACUIThemeData.fromPreset(\n    ACUIThemePresets.isabelle,\n    brightness: MediaQuery.of(context).platformBrightness,\n  ),\n  // ...\n)\n```\n\n## Responsive Design\n\nBuilt-in utilities for adaptive layouts:\n\n```dart\n// Breakpoints\nACUIResponsive.isMobile(context)   // \u003c 600px\nACUIResponsive.isTablet(context)   // 600-1200px\nACUIResponsive.isDesktop(context)  // \u003e 1200px\n\n// Responsive values\nfinal columns = ACUIResponsive.value(\n  context: context,\n  mobile: 1,\n  tablet: 2,\n  desktop: 3,\n);\n\n// Responsive spacing\nfinal spacing = ACUIResponsive.spacing(context);\n```\n\n## Validation Utilities\n\nForm validation helpers:\n\n```dart\n// Email validation\nACUIValidators.isValidEmail(email)\n\n// Password strength\nACUIValidators.getPasswordStrength(password) // Returns 0-4\n\n// Phone validation\nACUIValidators.isValidPhoneNumber(phone)\n\n// URL validation\nACUIValidators.isValidUrl(url)\n\n// Custom validators\nACUIValidators.minLength(text, minLength)\nACUIValidators.maxLength(text, maxLength)\nACUIValidators.matches(text, pattern)\n```\n\n## Page Transitions\n\nAnimated route transitions:\n\n```dart\nNavigator.push(\n  context,\n  ACUIPageTransition(\n    type: ACUIPageTransitionType.slideUp,\n    child: NextPage(),\n  ),\n);\n```\n\nAvailable transitions: `fade`, `slideUp`, `slideDown`, `slideLeft`, `slideRight`, `scale`, `rotate`, `fadeScale`\n\n## Layout Presets\n\nPre-built layout patterns:\n\n```dart\n// Form layout\nACUILayouts.form(\n  children: [\n    ACUITextField(/* ... */),\n    ACUIButton(/* ... */),\n  ],\n)\n\n// Grid layout\nACUILayouts.grid(\n  crossAxisCount: 2,\n  children: items,\n)\n\n// Card list\nACUILayouts.cardList(\n  children: cards,\n)\n```\n\n## Best Practices\n\n**Theme Access:**\n\n```dart\nfinal theme = ACUITheme.of(context);\nfinal primaryColor = theme.primaryColor;\n```\n\n**Spacing:**\n\nUse `ACUISpacing` constants for consistent gaps:\n\n```dart\nSizedBox(height: ACUISpacing.md)  // 16px\nPadding(padding: EdgeInsets.all(ACUISpacing.lg))  // 24px\n```\n\n**Border Radius:**\n\nUse `ACUIBorderRadius` for consistent roundedness:\n\n```dart\nBorderRadius.circular(ACUIBorderRadius.md)  // 12px\nBorderRadius.circular(ACUIBorderRadius.full)  // Pill shape\n```\n\n**Text Styles:**\n\nUse `ACUITextStyles` for typography:\n\n```dart\nText('Title', style: ACUITextStyles.titleLarge)\nText('Body', style: ACUITextStyles.bodyMedium)\n```\n\n**Responsive Layouts:**\n\nCheck screen size before rendering:\n\n```dart\nif (ACUIResponsive.isMobile(context)) {\n  return MobileLayout();\n} else {\n  return DesktopLayout();\n}\n```\n\n## Example App\n\nA comprehensive example app is included showcasing all components and features. Run it with:\n\n```bash\ncd example\nflutter run\n```\n\nThe example demonstrates:\n- All 60+ components in action\n- Theme switcher\n- Responsive layouts\n- Form validation\n- Navigation patterns\n- Dialog and overlay usage\n- Animal Crossing game components\n- Custom layouts and compositions\n\n## Requirements\n\n- **Dart SDK**: ^3.10.0\n- **Flutter**: \u003e=3.0.0\n- **Dependencies**: flutter_svg ^2.0.10\n\nNo other dependencies required. Works on all Flutter platforms: iOS, Android, Web, Windows, macOS, Linux.\n\n## Migration Guide\n\n### From v0.3.x to v0.4.0\n\nNew components added, no breaking changes. Simply update your dependency version.\n\n### From v0.2.x to v0.3.x\n\n- `ACUILoadingSpinner` now supports multiple animation styles via `style` parameter\n- All dialogs now use `showACUI*` helper functions for consistency\n\n## Contributing\n\nContributions are welcome! Please read the contributing guidelines before submitting pull requests.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nInspired by Nintendo's Animal Crossing series. This is an unofficial fan project and is not affiliated with or endorsed by Nintendo.\n\n## Support\n\n- **Documentation**: [pub.dev/documentation/animal_crossing_ui](https://pub.dev/documentation/animal_crossing_ui/latest/)\n- **Issues**: [GitHub Issues](https://github.com/sazardev/animal_crossing_ui/issues)\n- **Repository**: [GitHub](https://github.com/sazardev/animal_crossing_ui)\n\n---\n\nBuilt with care by the Flutter community.\n\n**9 brand new components!** 🎉\n\n| Component | Use Case | Example |\n|-----------|----------|---------|\n| 🔘 **Radio Buttons** | Single choice selection | Pick your favorite fruit |\n| 📋 **Dropdowns** | Select from lists | Choose a villager |\n| 🔍 **Search Bar** | Filter and find | Search your catalog |\n| ⏳ **Loading Spinner** | Show progress | Loading island data |\n| 🏝️ **Empty States** | No content yet | First-time user experience |\n| 📢 **Banners** | Important messages | Island announcements |\n| 📦 **Containers** | Flexible wrappers | Custom layouts |\n| 📑 **Sections** | Organized content | Settings categories |\n| 🎪 **Expansion Panels** | Collapsible areas | FAQ sections |\n\n**Plus powerful utilities!**\n\n- 📏 **ACUIResponsive** - Adapt to any screen size effortlessly\n- ✅ **ACUIValidators** - Email, password, phone validation and more\n- 🎨 **ACUILayouts** - Pre-built patterns (forms, grids, lists)\n- ☁️ **ACUIShadows** - Subtle depth when you need it\n\n## 📦 Installation\n\n```yaml\ndependencies:\n  animal_crossing_ui: ^0.4.0\n```\n\n```bash\nflutter pub get\n```\n\n## 🚀 Quick Start\n\n### Your First ACUI App (2 minutes!)\n\n```dart\nimport 'package:flutter/widgets.dart';\nimport 'package:animal_crossing_ui/animal_crossing_ui.dart';\n\nvoid main() =\u003e runApp(const MyIslandApp());\n\nclass MyIslandApp extends StatelessWidget {\n  const MyIslandApp({super.key});\n\n  @override\n  Widget build(BuildContext context) {\n    return ACUIApp(\n      title: 'My Island',\n      theme: ACUIThemePresets.isabelle,  // 🐶 Cheerful yellow theme!\n      home: Column(\n        children: [\n          ACUIAppBar(title: const Text('Welcome! 🏝️')),\n          Expanded(\n            child: Center(\n              child: ACUIButton(\n                onPressed: () =\u003e print('Hello!'),\n                child: const Text('Say Hello!'),\n              ),\n            ),\n          ),\n        ],\n      ),\n    );\n  }\n}\n```\n\n**That's it!** Run it and see the magic! ✨\n\n## 🎨 Beautiful Themes\n\nChoose from 16+ pre-designed themes or create your own!\n\n### Character Themes 🎮\n\n```dart\nACUIThemePresets.isabelle   // 🐶 Cheerful yellow \u0026 coral\nACUIThemePresets.tomNook    // 🦝 Professional green \u0026 brown\nACUIThemePresets.kkSlider   // 🎸 Musical blue \u0026 white\nACUIThemePresets.celeste    // ⭐ Dreamy pink \u0026 purple\nACUIThemePresets.blathers   // 🦉 Scholarly brown \u0026 teal\n```\n\n### Seasonal Themes 🌸\n\n```dart\nACUIThemePresets.spring     // 🌸 Cherry blossom pink\nACUIThemePresets.summer     // ☀️ Ocean blue\nACUIThemePresets.autumn     // 🍂 Warm orange \u0026 brown\nACUIThemePresets.winter     // ❄️ Icy blue \u0026 white\n```\n\n**All themes have automatic dark mode!**\n\n```dart\nACUIApp(\n  theme: ACUIThemePresets.isabelle,       // Light\n  darkTheme: ACUIThemePresets.isabelleDark,  // Dark\n  home: const HomePage(),\n)\n```\n\n## 🧱 Essential Components\n\n### 🎯 Buttons\n\n```dart\n// Primary action\nACUIButton(\n  onPressed: () =\u003e print('Planted!'),\n  child: const Text('Plant Tree 🌳'),\n)\n\n// Secondary action\nACUIButton.secondary(\n  onPressed: () =\u003e print('Cancelled'),\n  child: const Text('Cancel'),\n)\n\n// Sizes: small, medium, large\nACUIButton(\n  size: ACUIButtonSize.large,\n  child: const Text('Big Button!'),\n)\n```\n\n### 📝 Forms\n\n```dart\n// Text input\nACUITextField(\n  placeholder: 'Enter island name...',\n  onChanged: (text) =\u003e print(text),\n)\n\n// Radio selection\nACUIRadioListTile\u003cString\u003e(\n  title: const Text('Apple 🍎'),\n  value: 'apple',\n  groupValue: selected,\n  onChanged: (val) =\u003e setState(() =\u003e selected = val),\n)\n\n// Dropdown\nACUIDropdown\u003cString\u003e(\n  hint: const Text('Choose fruit'),\n  items: [\n    ACUIDropdownItem(value: 'apple', child: const Text('Apple 🍎')),\n    ACUIDropdownItem(value: 'orange', child: const Text('Orange 🍊')),\n  ],\n  onChanged: (val) =\u003e print(val),\n)\n\n// Search\nACUISearchBar(\n  placeholder: 'Search catalog...',\n  onChanged: (query) =\u003e filterItems(query),\n)\n```\n\n### 🎴 Cards \u0026 Containers\n\n```dart\n// Simple card\nACUICard(\n  child: Text('Card content'),\n)\n\n// Custom container\nACUIContainer(\n  color: Colors.blue,\n  borderRadius: BorderRadius.circular(20),\n  padding: EdgeInsets.all(16),\n  child: Text('Custom box!'),\n)\n```\n\n### 📢 Feedback\n\n```dart\n// Banners\nACUIBanner(\n  type: ACUIBannerType.success,\n  message: 'Island rating: 5 stars! 🌟',\n)\n\n// Loading\nconst ACUILoadingSpinner()\n\n// Empty state\nACUIEmptyState(\n  icon: const Text('🏝️', style: TextStyle(fontSize: 80)),\n  title: 'No islands yet!',\n  message: 'Create your first island to get started!',\n  actionLabel: 'Create Island',\n  action: () =\u003e createIsland(),\n)\n```\n\n## 🛠️ Powerful Utilities\n\n### 📏 Responsive Design\n\n```dart\n// Check device type\nif (ACUIResponsive.isMobile(context)) {\n  // Show mobile layout\n}\n\n// Pick value by screen size\nfinal fontSize = ACUIResponsive.value(\n  context: context,\n  mobile: 14.0,\n  tablet: 16.0,\n  desktop: 18.0,\n);\n\n// Responsive padding\nEdgeInsets padding = ACUIResponsive.padding(context);\n```\n\n### ✅ Form Validation\n\n```dart\n// Email validation\nif (ACUIValidators.isValidEmail(email)) {\n  print('Email is valid! 📧');\n}\n\n// Password strength (0-4)\nint strength = ACUIValidators.passwordStrength(password);\n\n// With error messages\nString? error = ACUIValidators.email(emailInput);\nif (error != null) {\n  showError(error);  // \"That doesn't look like a valid email! 🤔\"\n}\n```\n\n### 🎨 Layout Presets\n\n```dart\n// Form layout\nACUILayouts.form(\n  children: [\n    ACUITextField(placeholder: 'Name'),\n    ACUITextField(placeholder: 'Email'),\n    ACUIButton(child: Text('Submit')),\n  ],\n)\n\n// Card grid\nACUILayouts.cardGrid(\n  itemCount: items.length,\n  columns: 3,\n  itemBuilder: (context, index) =\u003e ACUICard(\n    child: Text(items[index]),\n  ),\n)\n\n// Sectioned list\nACUILayouts.sectionedList(\n  sections: [\n    ACUILayoutSection(\n      title: 'ISLAND SETTINGS',\n      items: [\n        ACUIListTile(title: Text('Island Name')),\n        ACUIListTile(title: Text('Island Tune')),\n      ],\n    ),\n  ],\n)\n```\n\n## 📚 Documentation\n\n- **[Getting Started Guide](GETTING_STARTED.md)** - Complete beginner-friendly tutorial\n- **[Theme Guide](THEME_GUIDE.md)** - All about themes and customization\n- **[API Documentation](https://pub.dev/documentation/animal_crossing_ui/latest/)** - Full API reference\n- **[Example App](example/)** - See all components in action\n\n## 🎪 Example Patterns\n\n### Login Screen\n\n```dart\nACUILayouts.form(\n  children: [\n    const Text('Welcome Back! 👋', style: TextStyle(fontSize: 32)),\n    ACUICard(\n      child: Column(\n        children: [\n          ACUITextField(placeholder: 'Email'),\n          const SizedBox(height: 16),\n          ACUITextField(placeholder: 'Password', obscureText: true),\n        ],\n      ),\n    ),\n    ACUIButton(\n      onPressed: () =\u003e login(),\n      child: const Text('Log In 🔐'),\n    ),\n  ],\n)\n```\n\n### Settings Screen\n\n```dart\nACUILayouts.sectionedList(\n  sections: [\n    ACUILayoutSection(\n      title: 'ISLAND',\n      items: [\n        ACUIListTile(\n          leading: Text('🏝️'),\n          title: Text('Island Name'),\n          subtitle: Text('Paradise Island'),\n        ),\n      ],\n    ),\n    ACUILayoutSection(\n      title: 'APP',\n      items: [\n        ACUIListTile(\n          leading: Text('🌙'),\n          title: Text('Dark Mode'),\n          trailing: ACUISwitch(value: dark, onChanged: setDark),\n        ),\n      ],\n    ),\n  ],\n)\n```\n\n## 🎯 Component Catalog\n\n### Basic Components (20+)\n- ✅ ACUIButton (primary, secondary, text)\n- ✅ ACUICard\n- ✅ ACUIContainer\n- ✅ ACUIAppBar\n- ✅ ACUITextField\n- ✅ ACUISearchBar\n- ✅ ACUICheckbox\n- ✅ ACUISwitch\n- ✅ ACUIRadio \u0026 ACUIRadioListTile\n- ✅ ACUISlider\n- ✅ ACUIDropdown\n\n### Lists \u0026 Navigation (10+)\n- ✅ ACUIListTile \u0026 ACUIListView\n- ✅ ACUIGridView\n- ✅ ACUITabBar \u0026 ACUITabView\n- ✅ ACUIBottomNavigationBar\n- ✅ ACUINavigationDrawer\n- ✅ ACUISection\n- ✅ ACUIExpansionPanel\n\n### Feedback \u0026 Display (10+)\n- ✅ ACUIDialog \u0026 ACUIAlert\n- ✅ ACUIBanner\n- ✅ ACUISnackbar\n- ✅ ACUITooltip\n- ✅ ACUIMenu\n- ✅ ACUILoadingSpinner\n- ✅ ACUIProgressIndicator\n- ✅ ACUILinearProgress\n- ✅ ACUIEmptyState\n- ✅ ACUIBadge\n- ✅ ACUIAvatar\n- ✅ ACUIChip\n\n### Pickers \u0026 Input (4+)\n- ✅ ACUIDatePicker\n- ✅ ACUITimePicker\n- ✅ ACUIDivider\n\n### Utilities (10+)\n- ✅ ACUIThemePresets (16+ themes)\n- ✅ ACUIResponsive\n- ✅ ACUIValidators\n- ✅ ACUILayouts\n- ✅ ACUIShadows\n- ✅ ACUIAnimations\n- ✅ ACUISpacing\n- ✅ ACUIBorderRadius\n- ✅ ACUIColors\n- ✅ ACUITextStyles\n\n**Total: 44+ components + 10+ utilities = 54+ tools!** 🎉\n\n## 🤝 Contributing\n\nWe welcome contributions! Whether it's:\n\n- 🐛 Bug reports\n- 💡 Feature suggestions\n- 📝 Documentation improvements\n- 🎨 New themes or components\n\nPlease open an issue or pull request on [GitHub](https://github.com/sazardev/animal_crossing_ui)!\n\n## 📄 License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n## 🌟 Show Your Support\n\nIf you love Animal Crossing UI, give it a ⭐ on GitHub!\n\n---\n\n**Built with 💚 for the Flutter community**\n\n*May your code be as delightful as a 5-star island!* 🏝️✨\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsazardev%2Fanimal_crossing_ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsazardev%2Fanimal_crossing_ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsazardev%2Fanimal_crossing_ui/lists"}