WineROI Component Library

Design System Foundation

Design Tokens

The WineROI component library implements our visual identity through a comprehensive token system that ensures consistent application of our brand across all digital touchpoints:

Color Tokens

/* Primary Colors */
--color-deep-navy: #1A2A47;      /* Primary background, key UI elements */
--color-burgundy: #7D2E46;       /* Wine-inspired accent */
--color-gold: #D4B96A;           /* Value indicators, ratings, key interactions */

/* Secondary Colors */
--color-slate-gray: #4A5568;     /* Secondary text, icons */
--color-warm-white: #F8F5F0;     /* Light mode background, content areas */
--color-merlot: #5E1F30;         /* Deeper wine tone for secondary accents */

/* Accent Colors */
--color-value-green: #2D8A6D;    /* Good value indicator */
--color-alert-red: #C53F3F;      /* Poor value indicator */
--color-neutral-taupe: #B2A89D;  /* Fair value indicator */

/* Semantic Tokens */
--color-background-primary: var(--color-deep-navy);
--color-background-secondary: rgba(26, 42, 71, 0.9);
--color-text-primary: var(--color-warm-white);
--color-text-secondary: rgba(248, 245, 240, 0.8);
--color-interactive-primary: var(--color-gold);
--color-interactive-secondary: rgba(212, 185, 106, 0.8);
--color-border-default: rgba(74, 85, 104, 0.3);
--color-value-positive: var(--color-value-green);
--color-value-negative: var(--color-alert-red);
--color-value-neutral: var(--color-neutral-taupe);
--color-focus-ring: rgba(212, 185, 106, 0.5);

Typography Tokens

/* Font Families */
--font-heading: 'Playfair Display', serif;
--font-body: 'Work Sans', sans-serif;

/* Font Weights */
--font-weight-regular: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;

/* Font Sizes */
--font-size-xs: 12px;
--font-size-sm: 14px;
--font-size-md: 16px;
--font-size-lg: 18px;
--font-size-xl: 20px;
--font-size-2xl: 24px;
--font-size-3xl: 30px;

/* Line Heights */
--line-height-tight: 120%;
--line-height-normal: 140%;
--line-height-relaxed: 160%;

/* Letter Spacing */
--letter-spacing-tight: -0.01em;
--letter-spacing-normal: 0;
--letter-spacing-wide: 0.02em;

/* Semantic Typography */
--text-primary-heading: var(--font-heading);
--text-body: var(--font-body);
--text-value-verdict: var(--font-heading);

Spacing Tokens

/* Base Spacing Units (8-point grid) */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;
--space-24: 96px;

/* Semantic Spacing */
--space-component-padding: var(--space-4);
--space-container-margin: var(--space-4);
--space-section-gap: var(--space-6);
--space-card-padding: var(--space-4);
--space-button-padding-x: var(--space-4);
--space-button-padding-y: var(--space-3);
--space-input-padding-x: var(--space-3);
--space-input-padding-y: var(--space-2);
--space-list-item-gap: var(--space-3);

Border Tokens

/* Border Radius */
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-xl: 16px;
--radius-full: 9999px;

/* Border Width */
--border-width-thin: 1px;
--border-width-medium: 2px;
--border-width-thick: 3px;

/* Semantic Borders */
--border-radius-card: var(--radius-md);
--border-radius-button: var(--radius-md);
--border-radius-input: var(--radius-sm);
--border-radius-badge: var(--radius-full);
--border-width-default: var(--border-width-thin);
--border-width-focus: var(--border-width-medium);

Shadow Tokens

/* Elevation System */
--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
--shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);

/* Semantic Shadows */
--shadow-card: var(--shadow-md);
--shadow-dropdown: var(--shadow-lg);
--shadow-modal: var(--shadow-xl);
--shadow-button: var(--shadow-sm);

Animation Tokens

/* Duration */
--duration-instant: 100ms;
--duration-quick: 200ms;
--duration-moderate: 300ms;
--duration-slow: 500ms;

/* Easing */
--ease-standard: cubic-bezier(0.2, 0.0, 0.2, 1);
--ease-decelerate: cubic-bezier(0.0, 0.0, 0.2, 1);
--ease-accelerate: cubic-bezier(0.4, 0.0, 1, 1);

/* Semantic Animation */
--transition-interactive: var(--duration-quick) var(--ease-standard);
--transition-appearance: var(--duration-moderate) var(--ease-decelerate);
--transition-disappearance: var(--duration-quick) var(--ease-accelerate);
--transition-emphasis: var(--duration-moderate) var(--ease-standard);

Grid System

The WineROI component library utilizes a responsive grid system that ensures consistent spacing and alignment across all interfaces:

Base Grid

• 8-point grid system for consistent spacing and alignment
• Responsive breakpoints to accommodate different device sizes:
  • Mobile: 0-639px
  • Tablet: 640px-1023px
  • Desktop: 1024px+

graph TD
    Grid["8-point Grid System"] --> Columns["Column Structure"]
    Grid --> Spacing["Spacing System"]
    Grid --> Breakpoints["Responsive Breakpoints"]
    
    Columns --> Mobile["Mobile: 4 columns"]
    Columns --> Tablet["Tablet: 8 columns"]
    Columns --> Desktop["Desktop: 12 columns"]
    
    Spacing --> Margins["Margins: 16px (mobile) / 24px (tablet+)"]
    Spacing --> Gutters["Gutters: 16px standard"]
    
    Breakpoints --> BpMobile["Mobile: < 640px"]
    Breakpoints --> BpTablet["Tablet: 640px - 1023px"]
    Breakpoints --> BpDesktop["Desktop: ≥ 1024px"]

Layout Structure

• Container width: 100% with max-width of 1200px on larger screens
• Margins: 16px minimum on mobile, increasing to 24px on tablet and desktop
• Columns: 4-column grid on mobile, 8-columns on tablet, 12-columns on desktop
• Gutters: 16px standard width between columns

Responsive Behavior

• Components adapt to different screen sizes through:
  • Reflow: Elements reposition based on available space
  • Scaling: Typography and spacing adjust proportionally
  • Stacking: Horizontal layouts convert to vertical on smaller screens
  • Prioritization: Critical content remains visible while secondary content may be hidden

Visual Style

The WineROI visual style embodies our brand personality as a sophisticated yet approachable wine value assessment tool. The visual language balances expertise with accessibility, creating interfaces that feel authoritative without being intimidating.

Shape Language

• Soft corners (8px radius standard) create an approachable, refined aesthetic
• Clean geometric forms with subtle organic touches
• Consistent proportions across related elements
• Generous white space to enhance focus and readability

Material Treatment

• Subtle depth through strategic use of shadows
• Layered interface with clear visual hierarchy
• Minimal use of decorative elements
• Strategic use of opacity to create depth

Visual Hierarchy

• Clear distinction between primary, secondary, and tertiary elements
• Size, color, and position used to establish importance
• Consistent visual patterns for similar information types
• Strategic use of contrast to direct attention to key elements

Component Architecture

The WineROI component architecture follows a modular, composable approach that enables consistent implementation while allowing for contextual adaptation:

graph TD
    Foundations["Design Foundations"] --> Atoms["Atoms"]
    Atoms --> Molecules["Molecules"]
    Molecules --> Organisms["Organisms"]
    Organisms --> Templates["Templates"]
    Templates --> Pages["Pages"]
    
    Foundations --> Tokens["Design Tokens"]
    Foundations --> Grid["Grid System"]
    Foundations --> Typography["Typography System"]
    Foundations --> Colors["Color System"]
    
    Atoms --> Buttons["Buttons"]
    Atoms --> Inputs["Inputs"]
    Atoms --> Icons["Icons"]
    Atoms --> Labels["Labels"]
    
    Molecules --> Cards["Cards"]
    Molecules --> FormGroups["Form Groups"]
    Molecules --> ValueIndicators["Value Indicators"]
    Molecules --> Navigation["Navigation Elements"]
    
    Organisms --> WineDetails["Wine Details"]
    Organisms --> SearchResults["Search Results"]
    Organisms --> ValueAssessment["Value Assessment"]
    Organisms --> ContributionForm["Contribution Form"]
    
    Templates --> HomeTemplate["Home Template"]
    Templates --> DetailTemplate["Detail Template"]
    Templates --> SearchTemplate["Search Template"]
    Templates --> ProfileTemplate["Profile Template"]

Inheritance Model

• Base components establish foundational styling and behavior
• Specialized components extend base components with specific functionality
• Variants provide controlled customization while maintaining consistency
• State variations are systematically applied across component types

Composition Strategy

• Components are designed to be combined in predictable ways
• Clear parent-child relationships define how components nest
• Slot-based architecture allows for flexible content insertion
• Props and configuration options enable contextual adaptation

Core Components

Input Controls

Input controls enable users to enter data, make selections, and interact with the WineROI application. These components prioritize ease of use in restaurant environments, with special consideration for one-handed operation.

Text Field

The text field component allows users to input text data with a clean, minimal design optimized for restaurant lighting conditions.

States:

• Default: Subtle bottom border with placeholder text
• Focus: Gold accent on bottom border with subtle animation
• Filled: Maintains subtle styling with entered text
• Error: Red bottom border with error message below
• Disabled: Reduced opacity with non-interactive appearance

Variants:

• Standard: Basic text input with single line
• Search: Includes search icon and clear button
• Numeric: Optimized for price entry with currency symbol
• Multiline: Expandable for longer text entry

<div class="wineroi-text-field">
  <label class="wineroi-text-field__label">Wine Name</label>
  <div class="wineroi-text-field__input-container">
    <input type="text" class="wineroi-text-field__input" placeholder="Enter wine name" />
  </div>
  <div class="wineroi-text-field__helper-text">Enter the full name as shown on the label</div>
</div>

Selection Controls

Selection controls allow users to make choices from predefined options, with designs optimized for quick, confident selection.

Checkbox

Used for multiple selection options or toggle states.

States:

• Unchecked: Empty square with border
• Checked: Filled with Gold background and white checkmark
• Indeterminate: Partial fill with horizontal line
• Disabled: Reduced opacity with non-interactive appearance
• Error: Red border to indicate validation issues

Radio Button

Used for single selection from a set of options.

States:

• Unselected: Empty circle with border
• Selected: Gold outer ring with Gold dot in center
• Disabled: Reduced opacity with non-interactive appearance
• Error: Red border to indicate validation issues

Toggle Switch

Used for binary on/off settings with a physical switch metaphor.

States:

• Off: Slate Gray track with handle positioned left
• On: Gold track with handle positioned right
• Disabled: Reduced opacity with non-interactive appearance

Dropdown Menu

The dropdown component provides a space-efficient way to select from multiple options, with a design optimized for wine selection scenarios.

States:

• Closed: Displays selected value with dropdown indicator
• Open: Expands to show available options
• Option Selected: Highlights selected option with checkmark
• Disabled: Reduced opacity with non-interactive appearance
• Error: Red border to indicate validation issues

Variants:

• Standard: Basic dropdown with text options
• Search: Includes search functionality for filtering options
• Image: Includes thumbnail images alongside text options
• Multi-select: Allows selection of multiple options

Slider

The slider component enables selection from a continuous or stepped range of values, useful for price range filtering.

States:

• Default: Track with handle at selected position
• Active: Enlarged handle with value tooltip
• Disabled: Reduced opacity with non-interactive appearance

Variants:

• Single: One handle for selecting a single value
• Range: Two handles for selecting a value range
• Stepped: Discrete steps with optional value labels
• Price Range: Specialized for wine price range selection

Navigation Elements

Navigation components enable users to move through the WineROI application efficiently, with special attention to one-handed operation and discreet use in restaurant settings.

Navigation Bar

The primary navigation component that provides access to main sections of the application.

States:

• Default: Icons with labels in neutral state
• Active: Current section highlighted with Gold accent
• Disabled: Reduced opacity for unavailable sections

Variants:

• Bottom Bar: Fixed at bottom of screen for thumb access (mobile default)
• Side Bar: Expandable side navigation for larger screens
• Minimal: Icon-only for maximum content space

<nav class="wineroi-nav-bar">
  <a href="#" class="wineroi-nav-bar__item wineroi-nav-bar__item--active">
    <div class="wineroi-nav-bar__icon">
      <!-- Home icon SVG -->
    </div>
    <span class="wineroi-nav-bar__label">Home</span>
  </a>
  <a href="#" class="wineroi-nav-bar__item">
    <div class="wineroi-nav-bar__icon">
      <!-- Search icon SVG -->
    </div>
    <span class="wineroi-nav-bar__label">Search</span>
  </a>
  <a href="#" class="wineroi-nav-bar__item">
    <div class="wineroi-nav-bar__icon">
      <!-- Scan icon SVG -->
    </div>
    <span class="wineroi-nav-bar__label">Scan</span>
  </a>
  <a href="#" class="wineroi-nav-bar__item">
    <div class="wineroi-nav-bar__icon">
      <!-- Saved icon SVG -->
    </div>
    <span class="wineroi-nav-bar__label">Saved</span>
  </a>
  <a href="#" class="wineroi-nav-bar__item">
    <div class="wineroi-nav-bar__icon">
      <!-- Profile icon SVG -->
    </div>
    <span class="wineroi-nav-bar__label">Profile</span>
  </a>
</nav>

Tabs

Tabs organize content into separate views that users can switch between without changing screens.

States:

• Inactive: Neutral styling with clear label
• Active: Gold underline with emphasized label
• Disabled: Reduced opacity with non-interactive appearance

Variants:

• Text Tabs: Label-only for content categorization
• Icon Tabs: Icon with label for visual recognition
• Scrollable: Horizontally scrollable for many options
• Segmented: Full-width with equal segments

Buttons

Buttons trigger actions or navigation events with clear visual affordance.

Primary Button

The main call-to-action button for key actions.

States:

• Default: Gold background with Deep Navy text
• Hover/Focus: Slightly lighter Gold with subtle glow
• Active/Pressed: Slightly darker Gold with inset appearance
• Disabled: Reduced opacity with non-interactive appearance
• Loading: Animated indicator showing action in progress

Secondary Button

Used for important but not primary actions.

States:

• Default: Transparent with Gold border and Gold text
• Hover/Focus: Subtle Gold background
• Active/Pressed: Darker Gold border with inset appearance
• Disabled: Reduced opacity with non-interactive appearance
• Loading: Animated indicator showing action in progress

Tertiary Button

Used for less prominent actions.

States:

• Default: Text-only in Gold with no background
• Hover/Focus: Subtle underline
• Active/Pressed: Slightly darker text
• Disabled: Reduced opacity with non-interactive appearance

Icon Button

Compact button using only an icon for space efficiency.

States:

• Default: Icon in neutral color
• Hover/Focus: Icon with subtle background
• Active/Pressed: Darker icon with inset appearance
• Disabled: Reduced opacity with non-interactive appearance

Links

Links navigate to other screens or external resources with minimal visual weight.

States:

• Default: Gold text with optional subtle underline
• Hover/Focus: Darker Gold with more prominent underline
• Visited: Slightly desaturated Gold
• Active/Pressed: Darker Gold
• Disabled: Reduced opacity with non-interactive appearance

Variants:

• Inline: Within text content
• Standalone: Independent link element
• Icon Link: Includes icon for additional context
• External: Indicates link leads outside the app

Information Displays

Information display components present content to users in a clear, scannable format optimized for quick comprehension in restaurant settings.

Wine Card

The wine card component displays essential wine information in a compact, scannable format.

States:

• Default: Standard appearance with wine details
• Selected: Subtle highlight indicating selection
• Interactive: Hover/focus state for clickable cards
• Expanded: Additional details visible

Variants:

• Compact: Minimal information for list views
• Standard: Complete information for detailed views
• Value Focused: Emphasizes value assessment
• Contribution: Specialized for user contributions

<div class="wineroi-wine-card">
  <div class="wineroi-wine-card__value-indicator wineroi-value-indicator--good">
    <span class="wineroi-value-indicator__label">Good Value</span>
  </div>
  <div class="wineroi-wine-card__content">
    <h3 class="wineroi-wine-card__name">Château Margaux 2015</h3>
    <div class="wineroi-wine-card__details">
      <span class="wineroi-wine-card__vintage">2015</span>
      <span class="wineroi-wine-card__region">Bordeaux, France</span>
    </div>
    <div class="wineroi-wine-card__pricing">
      <div class="wineroi-wine-card__restaurant-price">
        <span class="wineroi-wine-card__price-label">Restaurant</span>
        <span class="wineroi-wine-card__price-value">$195</span>
      </div>
      <div class="wineroi-wine-card__retail-price">
        <span class="wineroi-wine-card__price-label">Retail</span>
        <span class="wineroi-wine-card__price-value">$85</span>
      </div>
    </div>
  </div>
  <div class="wineroi-wine-card__actions">
    <button class="wineroi-button wineroi-button--tertiary">Save</button>
    <button class="wineroi-button wineroi-button--primary">View Details</button>
  </div>
</div>

Value Indicator

The signature component of WineROI that visually communicates wine value assessment.

States:

• Good Value: Green indicator with upward arrow
• Fair Value: Neutral Taupe indicator with horizontal line
• Poor Value: Red indicator with downward arrow

Variants:

• Badge: Compact circular indicator for list views
• Banner: Prominent horizontal indicator for detail views
• Inline: Text-based indicator within content
• Animated: Reveals assessment with signature animation

Lists

Lists present collections of related items in a structured format.

Wine List

Displays multiple wines in a scrollable, scannable format.

States:

• Empty: Placeholder with action prompt
• Loading: Skeleton screens indicating content loading
• Populated: Complete list with wine items
• Error: Message indicating loading failure

Variants:

• Compact: Minimal information for dense lists
• Detailed: More comprehensive information
• Grid: Card-based layout for visual browsing
• Sortable: User can change sort order

Restaurant Wine List

Specialized list showing wines available at a specific restaurant.

States:

• Empty: Placeholder with contribution prompt
• Loading: Skeleton screens indicating content loading
• Populated: Complete list with wine items
• Error: Message indicating loading failure

Variants:

• By Category: Grouped by wine categories
• By Value: Sorted by value assessment
• By Price: Organized by price points
• Featured: Highlighting special selections

Data Visualization

Components that present numerical data in visual formats.

Price Comparison Chart

Visualizes the difference between restaurant and retail pricing.

States:

• Loading: Animated placeholder
• Populated: Complete visualization
• Empty: No data available message
• Error: Error message with retry option

Variants:

• Bar Chart: Side-by-side comparison
• Percentage Display: Markup percentage visualization
• Historical Trend: Price changes over time
• Value Distribution: Showing value across price points

Status Indicators

Components that communicate system status, progress, or state.

Loading Indicator

Communicates that content is being loaded or processed.

States:

• Active: Animated indicator showing activity
• Success: Transition to success state
• Error: Transition to error state

Variants:

• Spinner: Circular loading animation
• Progress Bar: Linear indication of completion percentage
• Skeleton Screen: Content placeholder during loading
• Wine Glass: Branded loading animation (wine glass filling)

Empty State

Provides context and guidance when no content is available.

States:

• New User: Tailored for first-time experience
• No Results: When search or filter returns nothing
• Error: When content failed to load
• Contribution Needed: Encouraging user input

Variants:

• Simple: Minimal text-only message
• Illustrated: Includes visual element
• Action-Oriented: Prominently features call-to-action
• Educational: Includes tips or guidance

Feedback Mechanisms

Feedback components communicate system responses to user actions, providing clarity and confirmation in a discreet manner suitable for restaurant environments.

Alerts

Alerts provide important information, warnings, or error messages.

States:

• Information: Neutral styling for general updates
• Success: Green styling for positive outcomes
• Warning: Gold/amber styling for potential issues
• Error: Red styling for problems requiring attention
• Dismissible: Can be closed by user
• Persistent: Remains visible until condition resolves

Variants:

• Toast: Temporary notification that appears briefly
• Banner: Full-width alert at screen top/bottom
• Inline: Contextual alert within content
• Dialog: Modal alert requiring acknowledgment

<div class="wineroi-alert wineroi-alert--success">
  <div class="wineroi-alert__icon">
    <!-- Success icon SVG -->
  </div>
  <div class="wineroi-alert__content">
    <div class="wineroi-alert__title">Contribution Received</div>
    <div class="wineroi-alert__message">Thank you for adding this wine price. Your contribution helps the community.</div>
  </div>
  <button class="wineroi-alert__close-button">
    <!-- Close icon SVG -->
  </button>
</div>

Tooltips

Tooltips provide additional context or explanation for UI elements.

States:

• Hidden: Not visible until triggered
• Visible: Displayed on hover/focus
• Interactive: Can contain interactive elements

Variants:

• Simple: Text-only explanation
• Rich: Includes formatting or multiple elements
• Educational: Provides feature explanation
• Contextual: Content varies based on application state

Modal Dialogs

Modal dialogs focus user attention on specific content or actions.

States:

• Opening: Entrance animation
• Open: Fully visible and interactive
• Closing: Exit animation
• Error: Indicates problem with requested action

Variants:

• Confirmation: Verifies user intent for important actions
• Form: Contains input fields for data collection
• Information: Presents detailed content
• Value Verdict: Specialized for wine value assessment reveal

Progress Indicators

Progress indicators show the status of ongoing processes.

States:

• Indeterminate: Unknown completion time
• Determinate: Shows specific percentage complete
• Paused: Indicates temporarily halted process
• Completed: Shows successful completion
• Error: Indicates process failure

Variants:

• Linear: Horizontal bar showing progress
• Circular: Radial progress indicator
• Step Indicator: Shows progress through multi-step process
• Contribution Progress: Specialized for tracking user contributions

Value Verdict Reveal

The signature feedback component that presents wine value assessment results with a distinctive animation.

States:

• Loading: Indicates assessment in progress
• Reveal: Animated presentation of verdict
• Complete: Fully visible assessment
• Updated: Indicates reassessment with changed result

Variants:

• Good Value: Green styling with celebratory elements
• Fair Value: Neutral styling with balanced presentation
• Poor Value: Red styling with cautionary elements
• Detailed: Includes comprehensive price comparison

Component Patterns

State Variations

WineROI components implement a consistent state system that communicates component status and interactive possibilities to users.

Interactive States

All interactive components implement these core states:

• Default: The standard appearance when not interacted with
• Hover: Visual feedback when pointer is over the element
• Focus: Distinct appearance when element receives keyboard focus
• Active/Pressed: Momentary state during interaction (click/tap)
• Disabled: Indicates the element cannot be interacted with

graph LR
    Default --> Hover
    Hover --> Active
    Active --> Default
    Default --> Focus
    Focus --> Active
    Active --> Focus
    Default --> Disabled
    Disabled --> Default

Content States

Components displaying content implement these states:

• Loading: Indicates content is being retrieved
• Empty: Displays when no content is available
• Error: Communicates when content cannot be loaded
• Partial: Shows when only some content is available
• Complete: Displays when all content is successfully loaded

graph TD
    Loading --> Complete
    Loading --> Error
    Loading --> Empty
    Loading --> Partial
    Error --> Loading
    Empty --> Loading
    Partial --> Loading
    Partial --> Complete

Selection States

Components allowing selection implement these states:

• Unselected: Default state before selection
• Selected: Indicates the item is currently selected
• Indeterminate: Represents partial selection (where applicable)
• Invalid Selection: Indicates a problematic selection

Value Assessment States

The specialized states for value assessment components:

• Good Value: Indicates wine priced below typical markup
• Fair Value: Indicates standard restaurant markup
• Poor Value: Indicates excessive markup
• Insufficient Data: When assessment cannot be made
• Updating: When reassessment is in progress

Responsive Behavior

WineROI components adapt to different screen sizes and orientations to maintain usability across devices, with special attention to discreet use in restaurant settings.

Breakpoint System

Components respond to these standard breakpoints:

• Mobile (Small): 0-639px

  • Single-column layouts
  • Touch-optimized tap targets
  • Reduced information density
  • Bottom navigation

• Tablet (Medium): 640px-1023px

  • Two-column layouts
  • Increased information density
  • Side navigation option
  • Enhanced data visualization

• Desktop (Large): 1024px+

  • Multi-column layouts
  • Maximum information density
  • Persistent side navigation
  • Advanced interactions

Component Adaptations

Key components transform across breakpoints:

Navigation Bar

• Mobile: Bottom-fixed tab bar with icons and labels
• Tablet: Bottom or side navigation based on orientation
• Desktop: Persistent side navigation with expanded labels

Wine Cards

• Mobile: Full-width cards with essential information
• Tablet: Grid layout with 2-3 cards per row
• Desktop: Grid layout with 3-4 cards per row, enhanced information

Wine Detail View

• Mobile: Stacked sections with progressive disclosure
• Tablet: Two-column layout with value assessment prominent
• Desktop: Multi-column layout with expanded comparisons

Search Interface

• Mobile: Full-screen with progressive filtering
• Tablet: Split view with filters and results
• Desktop: Advanced filtering alongside results

Touch Optimization

Components are designed for one-handed mobile use:

• Primary interactive elements positioned in thumb-friendly zones
• Minimum touch target size of 44×44px
• Increased spacing between touch targets in critical flows
• Swipe gestures for common actions

Composition Patterns

Guidelines for combining components into cohesive, effective interfaces that support the WineROI user experience.

Value-First Pattern

The primary composition pattern places value assessment at the forefront:

┌─────────────────────────────┐
│ Navigation Bar              │
├─────────────────────────────┤
│ ┌─────────────────────────┐ │
│ │ Value Indicator (Large) │ │
│ └─────────────────────────┘ │
│ ┌─────────────────────────┐ │
│ │ Wine Information Card   │ │
│ └─────────────────────────┘ │
│ ┌─────────────────────────┐ │
│ │ Price Comparison        │ │
│ └─────────────────────────┘ │
│ ┌─────────────────────────┐ │
│ │ Similar Wines           │ │
│ └─────────────────────────┘ │
│ ┌─────────────────────────┐ │
│ │ User Actions            │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘

Search and Discovery Pattern

Pattern for finding and exploring wines:

┌─────────────────────────────┐
│ Search Bar                  │
├─────────────────────────────┤
│ Filter Controls             │
├─────────────────────────────┤
│ ┌───────────┐ ┌───────────┐ │
│ │ Wine Card │ │ Wine Card │ │
│ └───────────┘ └───────────┘ │
│ ┌───────────┐ ┌───────────┐ │
│ │ Wine Card │ │ Wine Card │ │
│ └───────────┘ └───────────┘ │
├─────────────────────────────┤
│ Load More / Pagination      │
└─────────────────────────────┘

Contribution Pattern

Pattern for user input of wine pricing:

┌─────────────────────────────┐
│ Progress Indicator          │
├─────────────────────────────┤
│ Step Instructions           │
├─────────────────────────────┤
│ ┌─────────────────────────┐ │
│ │ Input Form (Current)    │ │
│ └─────────────────────────┘ │
├─────────────────────────────┤
│ Navigation Controls         │
└─────────────────────────────┘

Restaurant Context Pattern

Pattern for viewing wines in restaurant context:

┌─────────────────────────────┐
│ Restaurant Header           │
├─────────────────────────────┤
│ Category Navigation         │
├─────────────────────────────┤
│ Value Filter                │
├─────────────────────────────┤
│ ┌─────────────────────────┐ │
│ │ Wine List (By Category) │ │
│ └─────────────────────────┘ │
├─────────────────────────────┤
│ Contribution Prompt         │
└─────────────────────────────┘

Accessibility Implementations

WineROI components implement accessibility features to ensure the application is usable by people with diverse abilities, particularly in challenging restaurant environments.

Color and Contrast

• All text maintains minimum contrast ratio of 4.5:1 (WCAG AA)
• Primary text achieves 7:1 ratio (WCAG AAA) for optimal readability
• Interactive elements have visible focus states
• Color is never the sole indicator of meaning
• Value indicators use both color and shape to convey information

Keyboard Navigation

• All interactive elements are keyboard accessible
• Logical tab order follows visual layout
• Focus states are clearly visible
• Custom keyboard shortcuts for power users
• Skip links for efficient navigation

Screen Reader Support

• Semantic HTML structure for logical content hierarchy
• ARIA labels and descriptions for complex components
• Live regions for dynamic content updates
• Status messages announced appropriately
• Value assessments have clear textual equivalents

Touch and Motor Considerations

• Minimum touch target size of 44×44px
• Sufficient spacing between interactive elements
• Reduced motion option for animation-sensitive users
• Alternative input methods supported
• Forgiving gesture recognition

Implementation Guide

Code Architecture

The WineROI component library follows a structured architecture that enables consistent implementation while supporting the specific needs of a wine value assessment application.

Component Structure

graph TD
    Base["Base Component"] --> Specialized["Specialized Components"]
    Specialized --> Variants["Component Variants"]
    
    Base --> Props["Props Interface"]
    Base --> Styles["Styling System"]
    Base --> Behavior["Behavior Logic"]
    
    Props --> DefaultProps["Default Props"]
    Props --> PropValidation["Prop Validation"]
    
    Styles --> Tokens["Design Tokens"]
    Styles --> States["State Styles"]
    
    Behavior --> EventHandlers["Event Handlers"]
    Behavior --> StateManagement["State Management"]
    Behavior --> Accessibility["Accessibility Logic"]

Naming Conventions

• Component names: PascalCase (e.g., WineCard)
• Props and variables: camelCase (e.g., wineData)
• CSS classes: kebab-case with namespace (e.g., wineroi-wine-card)
• State classes: modifier pattern (e.g., wineroi-button--disabled)
• Event handlers: on + Event pattern (e.g., onClick)

File Organization

/components
  /atoms
    /Button
      Button.jsx
      Button.styles.js
      Button.test.js
      index.js
  /molecules
    /WineCard
      WineCard.jsx
      WineCard.styles.js
      WineCard.test.js
      index.js
  /organisms
    /WineDetail
      WineDetail.jsx
      WineDetail.styles.js
      WineDetail.test.js
      index.js
/tokens
  colors.js
  typography.js
  spacing.js
  ...
/utils
  /hooks
  /helpers
  /contexts

Framework Integration

The WineROI component library is implemented using React Native for cross-platform mobile development, with specific adaptations for iOS and Android.

React Native Implementation

• Components use functional approach with hooks
• Styling uses React Native StyleSheet
• Theme provider context for design token access
• Platform-specific adaptations where needed

Example Component Implementation:

// WineCard.jsx
import React from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { useTheme } from '../../contexts/ThemeContext';
import styles from './WineCard.styles';
import ValueIndicator from '../ValueIndicator';

const WineCard = ({ 
  wine, 
  valueAssessment, 
  onPress, 
  style, 
  ...props 
}) => {
  const theme = useTheme();
  
  return (
    <TouchableOpacity 
      style={[styles.container, style]} 
      onPress={onPress}
      accessible={true}
      accessibilityLabel={`${wine.name}, ${valueAssessment.label} value`}
      {...props}
    >
      <ValueIndicator 
        type={valueAssessment.type} 
        style={styles.valueIndicator} 
      />
      <View style={styles.content}>
        <Text style={styles.wineName}>{wine.name}</Text>
        <View style={styles.details}>
          <Text style={styles.vintage}>{wine.vintage}</Text>
          <Text style={styles.region}>{wine.region}</Text>
        </View>
        <View style={styles.pricing}>
          <View style={styles.priceContainer}>
            <Text style={styles.priceLabel}>Restaurant</Text>
            <Text style={styles.priceValue}>${wine.restaurantPrice}</Text>
          </View>
          <View style={styles.priceContainer}>
            <Text style={styles.priceLabel}>Retail</Text>
            <Text style={styles.priceValue}>${wine.retailPrice}</Text>
          </View>
        </View>
      </View>
    </TouchableOpacity>
  );
};

export default WineCard;

Platform-Specific Considerations

• iOS: Adapts to Human Interface Guidelines
• Android: Follows Material Design patterns where appropriate
• Dark mode optimized by default for restaurant environments
• Responsive to device orientation changes
• Adapts to notches and safe areas

State Management

• Local component state for UI interactions
• Redux for application-wide state
• Context API for theme and user preferences
• Async storage for offline data persistence

Performance Optimization

The WineROI component library implements performance optimizations to ensure smooth operation in variable connectivity restaurant environments.

Rendering Optimization

• Component memoization to prevent unnecessary re-renders
• List virtualization for efficient handling of long wine lists
• Lazy loading of off-screen content
• Image optimization with appropriate sizing and caching
• Debounced event handlers for performance-intensive interactions

Data Management

• Efficient data structures for wine and pricing information
• Local caching for frequently accessed data
• Incremental loading for large datasets
• Background data prefetching for anticipated user paths
• Optimistic UI updates with background synchronization

Animation Performance

• Hardware-accelerated animations
• Simplified animations in low-power mode
• Animation throttling for performance-constrained devices
• Reduced motion option for accessibility
• Performance monitoring and fallbacks

Offline Capabilities

• Persistent storage of critical wine data
• Offline search and filtering
• Queued contributions for sync when connectivity returns
• Clear indication of offline status
• Graceful degradation of connectivity-dependent features

Documentation System

Comprehensive documentation ensures consistent implementation and usage of the WineROI component library.

Component Documentation

Each component includes:

• Purpose and usage guidelines
• Props API with types and descriptions
• State variations with visual examples
• Accessibility considerations
• Code examples for common use cases
• Performance considerations
• Related components and patterns

Example Documentation Format:

# Wine Card

## Purpose
The Wine Card component displays essential wine information with value assessment in a compact, scannable format.

## Usage
Use Wine Cards in lists, search results, and saved wines sections to provide users with a quick overview of wine details and value assessment.

## Props
| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| wine | WineObject | Yes | - | Wine data object containing name, vintage, region, and pricing |
| valueAssessment | ValueObject | Yes | - | Value assessment object with type and label |
| onPress | Function | No | null | Function called when card is pressed |
| style | Object | No | {} | Additional styles to apply to the container |

## States
- Default: Standard appearance
- Pressed: Visual feedback when touched
- Disabled: Used for wines that cannot be selected

## Accessibility
- Includes appropriate accessibilityLabel combining wine name and value assessment
- Touch target meets minimum size requirements
- Ensures sufficient color contrast for all text elements

## Examples
```jsx
<WineCard
  wine={{
    name: "Château Margaux 2015",
    vintage: "2015",
    region: "Bordeaux, France",
    restaurantPrice: 195,
    retailPrice: 85
  }}
  valueAssessment={{
    type: "good",
    label: "Good Value"
  }}
  onPress={() => navigateToWineDetail(wineId)}
/>

#### Interactive Documentation

- Component playground for interactive testing
- Storybook integration for component exploration
- Visual regression testing examples
- Theming and customization examples
- Mobile device preview mode

#### Decision Guides

- Component selection flowcharts
- Pattern implementation guidelines
- Accessibility compliance checklists
- Performance optimization guides
- Anti-pattern documentation with alternatives

## Conclusion

The WineROI Component Library provides a comprehensive system of UI elements designed specifically for a wine value assessment application used in restaurant settings. The library balances sophisticated visual design with practical usability considerations, creating an experience that feels authoritative yet approachable.

By implementing this component library, WineROI will deliver a consistent, intuitive user experience that enables diners to quickly and discreetly assess wine values, make confident selections, and contribute to a growing database of wine pricing information.

The design system foundation ensures visual consistency with the WineROI brand, while the core components provide the building blocks for all user interactions. The component patterns establish clear guidelines for combining these elements effectively, and the implementation guide ensures technical excellence in the final product.

This component library will evolve alongside the WineROI product, with regular updates to address new features, user feedback, and emerging platform capabilities.