Mobile UI Component Library

You are a mobile design systems architect who has built and maintained component libraries used across multiple applications and teams. Create a comprehensive UI component library specification for the following mobile application ecosystem.

Project Details:
App Ecosystem: [SINGLE APP/MULTI-APP SUITE/WHITE-LABEL]
Design Language: [MATERIAL DESIGN/IOS HUMAN INTERFACE/CUSTOM]
Framework: [REACT NATIVE/FLUTTER/SWIFTUI/JETPACK COMPOSE/NATIVE BOTH]
Theming Requirements: [LIGHT ONLY/DARK MODE/MULTIPLE THEMES/BRAND CUSTOMIZABLE]
Accessibility Level: [WCAG AA/WCAG AAA/PLATFORM DEFAULT]
Team Size Using Library: [NUMBER OF DEVELOPERS]

Section 1 - Design Token System:
Define the design token architecture using a three-tier system of global tokens, alias tokens, and component tokens that enables systematic theming and brand customization. Specify the color token system including primary, secondary, surface, background, error, and semantic colors with their light and dark mode variants plus contrast ratios that meet the target accessibility level. Create the typography token scale defining font families, sizes, weights, line heights, and letter spacing for headings, body text, captions, and labels with responsive scaling for different device sizes. Define the spacing and sizing token system using a consistent base unit that creates harmonious spacing throughout the application. Address how tokens are stored, distributed, and consumed across platforms including whether to use a tool like Style Dictionary to generate platform-specific token files from a single source of truth.

Section 2 - Core Component Specifications:
Define the component inventory starting with atomic components including buttons, text inputs, icons, badges, and avatars, then composing them into molecular components like search bars, list items, and card layouts. Specify each component with its props or parameters, visual states including default, focused, pressed, disabled, loading, and error, and the interaction behavior for each state. Create the button component specification in detail as a reference pattern including all variants such as primary, secondary, outline, text, and icon-only with size options and loading state behavior. Define the text input component family covering single-line inputs, multi-line text areas, password fields, search inputs, and OTP entry with validation states, helper text, and character count display. Address the component composition guidelines explaining how atomic components combine to create consistent complex components while remaining individually testable and reusable.

Section 3 - Navigation and Layout Components:
Design the navigation component set including top app bars, bottom navigation bars, tab bars, side drawers, and breadcrumbs with their responsive behaviors across screen sizes. Specify the modal and overlay component system including bottom sheets, dialog boxes, snackbars, tooltips, and action sheets with their presentation animations and dismissal interactions. Create the list and grid layout components including infinite scroll behavior, pull-to-refresh, section headers, swipe actions, and empty state placeholders. Define the form layout components including form sections, field groups, inline validation display, and step-by-step form wizards with progress indicators. Address the safe area handling and edge-to-edge display components that account for notches, dynamic islands, navigation bars, and system overlays across different device models.

Section 4 - Animation and Interaction Patterns:
Define the animation token system specifying duration curves, easing functions, and motion principles that create a consistent feel across all component transitions. Specify the micro-interaction patterns for common actions including button press feedback, toggle switches, checkbox animations, pull-to-refresh indicators, and skeleton loading states. Create the page transition specifications for different navigation types including push transitions, modal presentations, and tab switches. Design the gesture interaction library including swipe-to-delete, drag-to-reorder, pinch-to-zoom, and long-press context menus with the haptic feedback patterns for each gesture. Address the reduced motion support ensuring that all animations respect the system accessibility setting for users who are sensitive to motion.

Section 5 - Accessibility Implementation:
Define the accessibility requirements for every component including semantic labels, roles, traits, and the expected screen reader announcement for each state change. Specify the focus management rules including tab order for keyboard navigation, focus trapping in modals, and focus restoration when modals are dismissed. Create the minimum touch target sizes following platform guidelines of 44 by 44 points on iOS and 48 by 48 density-independent pixels on Android with guidelines for spacing between interactive elements. Define the color contrast requirements and the testing methodology for verifying contrast ratios in both light and dark modes. Address the dynamic type and text scaling support ensuring that all text components resize appropriately up to the largest accessibility text size without layout breaking or text truncation.

Section 6 - Documentation, Testing, and Governance:
Define the component documentation standard including usage guidelines, do and do-not examples, code snippets for each platform, and interactive demos using Storybook for React Native or Widgetbook for Flutter. Specify the testing strategy for components including visual regression testing using snapshot comparisons, interaction testing for all component states, accessibility testing using automated scanners, and performance testing for list and grid components with large datasets. Create the component release and versioning process including how breaking changes are communicated, the deprecation timeline for old component versions, and the migration guides provided to consuming teams. Design the contribution guidelines for teams requesting new components or modifications to existing ones including the proposal process, design review, accessibility review, and approval workflow. Address the metrics to track for library adoption including component usage analytics, developer satisfaction surveys, and the percentage of custom versus library components in each application.