Skip to main content

Component Library

The BookWish component library provides a comprehensive set of reusable UI components built with Flutter. These components follow our brand guidelines and are designed to create consistent, accessible, and delightful user experiences.

Overview​

Our component library is organized into distinct categories based on functionality and usage patterns. Each component is designed with flexibility in mind while maintaining consistency across the application.

All components:

  • Follow BookWish brand guidelines
  • Support the Parchment background theme
  • Use the dual typography system (Merriweather for book content, system fonts for UI)
  • Include proper accessibility support
  • Maintain consistent spacing and visual rhythm

Component Categories​

Primitives​

Core building blocks used throughout the application:

  • Buttons - Primary, secondary, and text button variants
  • Text Fields - Input fields with validation states
  • Chips - Compact elements for tags, filters, and metadata
  • Cards - Content containers with consistent styling
  • Avatars - User profile images in various sizes
  • Toggles - Switches and toggleable controls
  • Loading Indicators - Progress feedback
  • Rating - Star-based rating display and input

Book Components​

Specialized components for book-related content:

  • Book Card - Grid display of books with cover images
  • Book List Tile - List view of books with metadata
  • Book Mini Chip - Compact book reference with thumbnail

Social Components​

Components for community and social features:

  • Review Card - User reviews with ratings and interactions
  • Line Card - Shared quotes and passages from books
  • User Chip - User profile chips with avatars
  • Like Button - Animated like/unlike interactions
  • Follow Button - Follow/unfollow user controls

Store Components​

Components for independent bookstore features:

  • Store Chip - Store identification and branding
  • Inventory Item Tile - Book inventory listings with pricing
  • Wishlist Item Tile - User wishlist items with status

Reading Components​

Components for reading tracking and book clubs:

  • Club Card - Book club information and membership
  • Challenge Card - Reading challenge progress and details
  • Notification Tile - Activity notifications

Typography​

Components use the dual typography system defined in the BookWish design system:

  • Merriweather (serif) - Book titles, author names, quotes, literary content
  • System fonts - UI elements, buttons, labels, navigation

Text Styles​

StyleFontSizeWeightUsage
bookTitleMerriweather17pt600Book titles
authorMerriweather14pt400Author names
headingSystem20pt600Section headers
labelSystem16pt500UI labels, buttons
bodySystem16pt400Body text
captionSystem12pt400Metadata, timestamps

See Design Tokens for full details.

Design Principles​

Consistency​

Components maintain visual consistency through:

  • Unified Color Palette: All components use colors from the brand palette
  • Standard Spacing: 4px base unit for spacing (4, 8, 12, 16, 24)
  • Consistent Border Radius: 12px for cards and containers, 24px for buttons, 16px for chips
  • Elevation System: 2-level shadow system for depth
  • Typography System: Merriweather for book content, system fonts for UI

Accessibility​

Every component is designed with accessibility in mind:

  • Color Contrast: Minimum WCAG AA compliance (4.5:1 for text)
  • Touch Targets: Minimum 44x44 points for interactive elements
  • Semantic Structure: Proper use of Flutter semantics
  • Keyboard Navigation: Support for non-touch interaction
  • Screen Reader Support: Descriptive labels and hints

Responsiveness​

Components adapt to different screen sizes:

  • Flexible Layouts: Use of Expanded, Flexible widgets
  • Adaptive Sizing: Text scales with system font settings
  • Orientation Support: Components work in portrait and landscape
  • Safe Areas: Respect device safe areas and notches

Component Structure​

Each component follows a consistent structure:

class ComponentName extends StatelessWidget {
  // Required properties
  final RequiredType requiredProp;

  // Optional properties with defaults
  final OptionalType? optionalProp;
  final VoidCallback? onTap;

  const ComponentName({
    super.key,
    required this.requiredProp,
    this.optionalProp,
    this.onTap,
  });

  @override
  Widget build(BuildContext context) {
    // Component implementation
  }
}

Using Components​

Import Pattern​

import 'package:bookwish/ui/components/component_name.dart';
import 'package:bookwish/config/theme.dart';

Theme Integration​

All components automatically use the app theme:

// Colors from theme
Theme.of(context).colorScheme.primary
Theme.of(context).colorScheme.surface

// Or direct from AppColors
AppColors.inkBlue
AppColors.parchment
AppColors.amberStar

Typography Integration​

Use AppTypography for consistent text styling:

// For book content
Text(book.title, style: AppTypography.bookTitle)
Text(book.author, style: AppTypography.author)

// For UI elements
Text(label, style: AppTypography.label)
Text(description, style: AppTypography.body)

Card System​

Most content components use a consistent card structure:

Padding(
  padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 6),
  child: Material(
    elevation: 2,
    shadowColor: Colors.black.withValues(alpha: 0.08),
    borderRadius: BorderRadius.circular(12),
    color: Colors.white,
    child: // Card content
  ),
)

This provides:

  • Consistent horizontal margins (16px)
  • Vertical spacing (6px) between cards
  • Standard elevation and shadow
  • White background on Parchment
  • 12px border radius

Interaction Patterns​

Tap Handling​

Components that handle taps provide clear feedback:

InkWell(
  onTap: onTap,
  borderRadius: BorderRadius.circular(12),
  child: // Content
)

Loading States​

Interactive components show loading states:

_isLoading
  ? CircularProgressIndicator()
  : // Normal content

Error Handling​

Components gracefully handle missing or invalid data:

book.coverImageUrl != null
  ? CachedNetworkImage(imageUrl: book.coverImageUrl!)
  : Container(
      color: Colors.grey[200],
      child: Icon(CupertinoIcons.book_fill),
    )

Best Practices​

Do's​

  • Use existing components whenever possible
  • Follow the established patterns for new components
  • Maintain consistent spacing and styling
  • Provide proper error states and fallbacks
  • Test components with different content lengths
  • Support system font scaling
  • Use AppColors and AppTypography constants

Don'ts​

  • Don't create one-off custom styles
  • Don't hardcode color values
  • Don't ignore accessibility requirements
  • Don't assume content fits on one line
  • Don't create components without reusability in mind
  • Don't skip error handling for images and network content

Component Documentation​

Detailed documentation for each component includes:

  • Purpose: What the component is used for
  • Props: All available properties and their types
  • Variants: Different visual or behavioral variants
  • Usage Examples: Code examples showing common use cases
  • Visual Examples: Screenshots showing the component in context
  • Accessibility Notes: Specific accessibility considerations

Next Steps​

Explore detailed documentation for each component category:

  • Primitives - Core building blocks
  • Book Components - Book display components (coming soon)
  • Social Components - Community features (coming soon)
  • Store Components - Bookstore features (coming soon)