SvenHVAC Component Library

Design System Foundation

Design Tokens

This component library implements our visual identity through a comprehensive token system that embodies SvenHVAC's "technical warmth" - balancing innovative technology with human warmth:

Color Tokens

/* Primary Colors */
--color-primary-blue: #0A3D62;     /* Reliability, expertise, trust */
--color-primary-orange: #E67E22;   /* Approachability, energy, warmth */

/* Secondary Colors */
--color-secondary-teal: #2E8B57;   /* Innovation, freshness, clarity */
--color-secondary-light-gray: #F5F7FA; /* Breathing room, readability */
--color-secondary-dark-gray: #2C3E50; /* Stability, professionalism */

/* Functional Colors */
--color-success: #27AE60;          /* Successful operations, completed actions */
--color-alert: #F39C12;            /* Attention, pending states */
--color-error: #C0392B;            /* Errors, failed states */

/* Semantic Mappings */
--color-text-primary: var(--color-secondary-dark-gray);
--color-text-secondary: #4A6378;
--color-text-tertiary: #7F8C8D;
--color-text-inverse: #FFFFFF;
--color-background-primary: #FFFFFF;
--color-background-secondary: var(--color-secondary-light-gray);
--color-background-tertiary: #E5E9F0;
--color-border-default: #D8DEE9;
--color-border-focus: var(--color-primary-blue);
--color-action-primary: var(--color-primary-orange);
--color-action-secondary: var(--color-primary-blue);
--color-action-tertiary: var(--color-secondary-teal);

Typography Tokens

/* Font Families */
--font-family-primary: 'Inter', sans-serif;     /* Headings, interface elements */
--font-family-secondary: 'Source Sans Pro', sans-serif; /* Body text, longer content */

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

/* Font Sizes - Scale Ratio: 1.25 (Major Third) */
--font-size-xs: 0.8rem;     /* 12.8px */
--font-size-sm: 0.875rem;   /* 14px */
--font-size-base: 1rem;     /* 16px */
--font-size-md: 1.125rem;   /* 18px */
--font-size-lg: 1.25rem;    /* 20px */
--font-size-xl: 1.5625rem;  /* 25px */
--font-size-2xl: 1.95rem;   /* 31.25px */
--font-size-3xl: 2.44rem;   /* 39.06px */

/* Line Heights */
--line-height-tight: 1.2;    /* Headings */
--line-height-normal: 1.5;   /* Body text */
--line-height-relaxed: 1.75; /* Extended reading */

/* Letter Spacing */
--letter-spacing-tight: -0.01em;
--letter-spacing-normal: 0;
--letter-spacing-wide: 0.015em;  /* Enhanced readability */
--letter-spacing-heading: 0.02em; /* Headings for clarity */

Spacing Tokens

/* Base Unit: 4px */
--space-unit: 0.25rem;

/* Spacing Scale */
--space-2xs: calc(var(--space-unit) * 1);   /* 4px */
--space-xs: calc(var(--space-unit) * 2);    /* 8px */
--space-sm: calc(var(--space-unit) * 3);    /* 12px */
--space-md: calc(var(--space-unit) * 4);    /* 16px */
--space-lg: calc(var(--space-unit) * 6);    /* 24px */
--space-xl: calc(var(--space-unit) * 8);    /* 32px */
--space-2xl: calc(var(--space-unit) * 12);  /* 48px */
--space-3xl: calc(var(--space-unit) * 16);  /* 64px */

/* Component Spacing */
--space-component-sm: var(--space-xs);      /* Small components */
--space-component-md: var(--space-md);      /* Medium components */
--space-component-lg: var(--space-lg);      /* Large components */
--space-section: var(--space-2xl);          /* Section spacing */
--space-page: var(--space-3xl);             /* Page margins */

Border Tokens

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

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

/* Border Styles */
--border-style-solid: solid;
--border-style-dashed: dashed;

/* Semantic Borders */
--border-input: var(--border-width-thin) var(--border-style-solid) var(--color-border-default);
--border-input-focus: var(--border-width-medium) var(--border-style-solid) var(--color-border-focus);
--border-card: var(--border-width-thin) var(--border-style-solid) var(--color-border-default);
--border-divider: var(--border-width-thin) var(--border-style-solid) var(--color-border-default);

Shadow Tokens

/* Elevation System */
--shadow-xs: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06);
--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-sm);
--shadow-dropdown: var(--shadow-md);
--shadow-modal: var(--shadow-lg);
--shadow-toast: var(--shadow-md);

Animation Tokens

/* Durations */
--duration-instant: 0ms;
--duration-fast: 150ms;
--duration-normal: 300ms;
--duration-slow: 500ms;
--duration-emphasis: 400ms;

/* Timing Functions */
--ease-default: cubic-bezier(0.4, 0, 0.2, 1); /* Standard easing */
--ease-in: cubic-bezier(0.4, 0, 1, 1);        /* Acceleration */
--ease-out: cubic-bezier(0, 0, 0.2, 1);       /* Deceleration */
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);  /* Acceleration then deceleration */

/* Semantic Animations */
--transition-button: all var(--duration-fast) var(--ease-default);
--transition-expand: all var(--duration-normal) var(--ease-out);
--transition-fade: opacity var(--duration-normal) var(--ease-default);
--transition-slide: transform var(--duration-normal) var(--ease-default);
--transition-emphasis: all var(--duration-emphasis) var(--ease-in-out);

Grid System

Components are organized within a responsive 12-column grid system that ensures consistent spacing and alignment across all interfaces:

/* Container Widths */
--container-sm: 640px;
--container-md: 768px;
--container-lg: 1024px;
--container-xl: 1280px;
--container-2xl: 1440px;

/* Grid Configuration */
--grid-columns: 12;
--grid-gutter-sm: var(--space-md);
--grid-gutter-md: var(--space-lg);
--grid-gutter-lg: var(--space-xl);

/* Breakpoints */
--breakpoint-xs: 0;
--breakpoint-sm: 480px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
--breakpoint-xl: 1280px;

The grid system implements the following principles:

• Responsive Behavior: Adapts to different screen sizes with defined breakpoints
• Consistent Gutters: Maintains proportional spacing between columns
• Nested Grids: Supports component nesting while maintaining spatial relationships
• Alignment System: Provides consistent rules for edge alignment and content positioning

Visual Style

All components express SvenHVAC's dual Magician/Caregiver brand archetypes through:

• Clean, Uncluttered Surfaces: Primary surfaces are clean and minimal, creating a sense of order and clarity during potentially stressful situations.
• Subtle Depth: Light shadows and layering create a sense of interface depth without overwhelming complexity.
• Refined Texture: Background elements incorporate subtle texture patterns inspired by HVAC blueprints and technical drawings.
• Balanced Asymmetry: Layouts utilize asymmetrical balance to create visual interest while maintaining order.
• Technical Warmth: The visual approach feels simultaneously advanced and approachable, balancing cool blues with warm orange accents.

Components implement a material quality that establishes a sense of substance and reliability while maintaining digital approachability. Interactive elements have smooth, responsive behaviors that feel substantial rather than flimsy.

Component Architecture

SvenHVAC's component architecture follows these structural principles:

• Atomic Design Methodology: Components are organized in a hierarchy from atoms (basic elements) to molecules (simple combinations) to organisms (complex components)
• Composition over Inheritance: Components are designed for flexible composition rather than deep inheritance hierarchies
• Slot-Based Architecture: Components use slot patterns to allow flexible content insertion
• State Management: Clear patterns for handling component states and variations
• Responsive Adaptation: Built-in responsive behavior based on breakpoint system
• Accessibility Foundation: Core accessibility features built into base components

graph TD
    A[Design Tokens] --> B[Base Components]
    B --> C[Input Components]
    B --> D[Navigation Components]
    B --> E[Display Components]
    B --> F[Feedback Components]
    C --> G[Form Compositions]
    D --> H[Navigation Patterns]
    E --> I[Content Patterns]
    F --> J[Notification Patterns]
    G & H & I & J --> K[Page Templates]

Core Components

Input Controls

Text Fields

Text fields allow users to input and edit text. They are fundamental to collecting information for appointment scheduling, customer details, and HVAC issue descriptions.

Component: TextField

Implementation Details:

• Uses the primary font family (Inter) for input text
• Maintains consistent height (44px) for optimal touch targets
• Features subtle border with increased focus state visibility
• Includes floating label pattern for improved form context
• Supports prefix/suffix icons for additional context

States:

• Default: Light border with subtle background differentiation
• Focus: Blue border emphasis with slight shadow lift
• Filled: Maintains clear visual distinction from empty state
• Error: Red border with error message and icon
• Disabled: Reduced opacity with non-interactive appearance
• Read-only: Visually distinct from editable fields

Variations:

• Single-line: Standard input for short text
• Multi-line: Expandable area for longer descriptions
• Password: With show/hide toggle functionality
• Search: With search icon and clear button
• With character count: For limited input fields
• With helper text: Additional context below field

Selection Controls

Selection controls allow users to select options, toggle features, and make choices.

Component: Checkbox

Implementation Details:

• Custom-styled checkbox with branded check mark
• Maintains 24px × 24px touch target for accessibility
• Features subtle animation for state changes
• Uses appropriate spacing between label and control

States:

• Unchecked: Empty box with border
• Checked: Filled with brand orange and white checkmark
• Indeterminate: Partial state with horizontal line
• Focus: Blue outline indicating keyboard focus
• Disabled: Reduced opacity with non-interactive appearance

Component: RadioButton

Implementation Details:

• Custom-styled radio with branded selection indicator
• Maintains 24px × 24px touch target for accessibility
• Features subtle animation for state changes
• Uses appropriate spacing between label and control

States:

• Unselected: Empty circle with border
• Selected: Outer ring with filled center in brand blue
• Focus: Blue outline indicating keyboard focus
• Disabled: Reduced opacity with non-interactive appearance

Component: Toggle

Implementation Details:

• Pill-shaped toggle switch with sliding indicator
• Size optimized for touch (28px height)
• Features smooth transition animation
• Includes optional labels for on/off states

States:

• Off: Gray track with white indicator positioned left
• On: Orange track with white indicator positioned right
• Focus: Blue outline indicating keyboard focus
• Disabled: Reduced opacity with non-interactive appearance

Dropdown Menus

Dropdown menus allow users to select from a list of options, crucial for service type selection, location selection, and time slot picking.

Component: Dropdown

Implementation Details:

• Clean, minimal design with clear affordance
• Supports grouping and categorization of options
• Features smooth expansion/collapse animation
• Includes search functionality for longer option lists

States:

• Closed: Displays selected value or placeholder
• Open: Expanded list of options with subtle shadow
• Option hover: Light background highlight
• Option selected: Checkmark indicator and highlight
• Disabled: Reduced opacity with non-interactive appearance

Variations:

• Single select: Traditional dropdown behavior
• Multi-select: Allows multiple option selection
• With icons: Options include supporting icons
• Searchable: Includes filtering capability
• Time selector: Specialized for appointment times

Date and Time Pickers

Date and time pickers allow users to select temporal values, essential for appointment scheduling.

Component: DatePicker

Implementation Details:

• Clean calendar interface with month/year navigation
• Highlights today's date for reference
• Shows available/unavailable dates with visual distinction
• Features smooth month transition animations

States:

• Default: Calendar view with current month
• Date hover: Subtle highlight effect
• Date selected: Filled circle highlight in brand orange
• Date range: Visual connection between start/end dates
• Date disabled: Visually muted appearance for unavailable dates

Component: TimePicker

Implementation Details:

• Displays available time slots in an accessible format
• Groups times by morning, afternoon, evening
• Visually indicates high/low availability periods
• Features responsive layout for different screen sizes

States:

• Default: Grid or list of available times
• Time hover: Subtle highlight effect
• Time selected: Filled background in brand blue
• Time unavailable: Visually muted appearance

File Upload

File upload components allow users to share images of HVAC issues for better diagnostics.

Component: FileUpload

Implementation Details:

• Drag and drop target area with clear affordance
• File selection button alternative
• Progress indicator for upload status
• Preview capability for images

States:

• Empty: Inviting drop area with instructions
• Drag over: Highlighted state indicating valid drop target
• Uploading: Progress indicator showing status
• Complete: Thumbnail preview with success indication
• Error: Clear error messaging with retry option

Navigation Elements

Navigation Bar

The navigation bar provides primary navigation for the application, helping users access key functions.

Component: NavigationBar

Implementation Details:

• Fixed position for consistent access
• Compact design that doesn't overwhelm the interface
• Clear visual hierarchy with primary/secondary actions
• Responsive behavior that adapts to screen size

States:

• Default: Standard appearance with current location indicated
• Active item: Visual indication of current section
• Hover/focus: Subtle highlight for interactive elements
• Collapsed: Hamburger menu on smaller screens
• Expanded: Full menu view when hamburger is activated

Variations:

• Primary navigation: Main app navigation
• Secondary navigation: Section-specific sub-navigation
• Stepper navigation: For multi-step processes
• Tab navigation: For switching between related views

Tabs

Tabs allow users to switch between related content views within the same context.

Component: Tabs

Implementation Details:

• Clean, text-based tabs with subtle separators
• Animated indicator that slides to active tab
• Consistent height and padding for touch targets
• Horizontally scrollable on mobile for many tabs

States:

• Inactive: Subdued appearance with clear label
• Active: Bold text with indicator line in brand blue
• Hover: Subtle highlight effect
• Disabled: Muted appearance, non-interactive

Variations:

• Horizontal tabs: Standard horizontal arrangement
• Vertical tabs: Side navigation for deeper hierarchies
• Pill tabs: Rounded button-like appearance
• Icon tabs: Icon with optional text label

Links & Buttons

Links and buttons provide interactive elements for navigation and actions.

Component: Button

Implementation Details:

• Clear visual hierarchy with primary/secondary/tertiary styles
• Consistent height (44px) for optimal touch targets
• Subtle hover and active states for feedback
• Support for icons before or after text

States:

• Default: Standard appearance based on hierarchy
• Hover: Slight darkening/lightening effect
• Active: Pressed state with slight scale reduction
• Focus: Keyboard focus ring for accessibility
• Loading: Spinner indicator replacing text
• Disabled: Reduced opacity, non-interactive

Variations:

• Primary: Orange background, white text - for main actions
• Secondary: Blue background, white text - for important actions
• Tertiary: Transparent with blue text - for less prominent actions
• Danger: Red styling for destructive actions
• Icon button: Circle or square with centered icon
• Text button: Minimal styling for low-emphasis actions

Component: Link

Implementation Details:

• Consistent styling with subtle underline
• Clear distinction from surrounding text
• Appropriate color contrast for accessibility
• Support for external link indication

States:

• Default: Brand blue text with subtle underline
• Hover: Darker shade with full underline
• Active: Pressed state visual feedback
• Focus: Keyboard focus indicator
• Visited: Subtle variation for visited links

Breadcrumbs

Breadcrumbs provide contextual navigation and location awareness.

Component: Breadcrumbs

Implementation Details:

• Compact horizontal display of navigation path
• Clear separators between levels
• Truncation handling for long paths
• Responsive behavior for different screen sizes

States:

• Default: Path display with current location emphasized
• Hover: Subtle highlight for interactive elements
• Active: Pressed state for interactive elements
• Focus: Keyboard focus indicator

Variations:

• Location-based: Shows hierarchy position
• Path-based: Shows navigation history
• With icons: Includes category icons for visual cues
• Responsive: Collapses middle items on small screens

Information Displays

Cards

Cards contain content and actions about a single subject, providing a flexible container for various types of information.

Component: Card

Implementation Details:

• Clean, contained design with subtle shadow
• Consistent padding and border radius
• Flexible content areas with clear hierarchy
• Optional header, footer, and dividers

States:

• Default: Standard appearance with subtle elevation
• Hover: Slight elevation increase (for interactive cards)
• Active: Pressed state (for interactive cards)
• Focus: Keyboard focus indicator
• Disabled: Reduced opacity (for interactive cards)

Variations:

• Basic card: Simple container for content
• Action card: Clickable card leading to more details
• Service card: Specialized for HVAC service display
• Appointment card: For appointment information
• Status card: Shows service status with appropriate indicators

Lists & Tables

Lists and tables organize collections of data in a scannable format.

Component: List

Implementation Details:

• Clean, structured display of items
• Consistent spacing and alignment
• Clear item separation with optional dividers
• Support for icons, avatars, and actions

States:

• Default: Standard list appearance
• Item hover: Subtle background highlight
• Item active: Pressed state visual feedback
• Item focus: Keyboard focus indicator
• Item selected: Visual indication of selection

Variations:

• Basic list: Simple text items
• Icon list: Items with leading icons
• Action list: Items with trailing actions
• Selection list: Supports item selection
• Grouped list: Items organized in categories

Component: Table

Implementation Details:

• Clean, structured display of tabular data
• Consistent column alignment and spacing
• Clear header styling for column identification
• Responsive behavior for different screen sizes

States:

• Default: Standard table appearance
• Row hover: Subtle background highlight
• Row active: Pressed state visual feedback
• Row focus: Keyboard focus indicator
• Row selected: Visual indication of selection

Variations:

• Basic table: Simple data display
• Sortable table: Supports column sorting
• Selectable table: Supports row selection
• Expandable table: Rows expand to show more details
• Responsive table: Adapts to different screen sizes

Status Indicators

Status indicators communicate the state of system processes, appointments, and services.

Component: StatusBadge

Implementation Details:

• Compact, high-contrast design for quick recognition
• Consistent shape and size across variations
• Text and color coding for status communication
• Optional icons for enhanced meaning

States:

• Success: Green background with success text/icon
• Warning: Amber background with warning text/icon
• Error: Red background with error text/icon
• Info: Blue background with info text/icon
• Neutral: Gray background with neutral text/icon

Variations:

• Text badge: Status with text label
• Icon badge: Status with icon only
• Combined badge: Status with icon and text
• Dot indicator: Minimal dot for simple status
• Pulse indicator: Animated for active processes

Component: ProgressIndicator

Implementation Details:

• Clear visual representation of progress
• Appropriate use of brand colors
• Smooth animation for updates
• Accessible through multiple means (visual, text)

States:

• Determinate: Shows specific percentage complete
• Indeterminate: Indicates activity without specific progress
• Success: Indicates completed process
• Error: Indicates failed process
• Paused: Indicates temporarily halted process

Variations:

• Linear progress: Horizontal bar showing progress
• Circular progress: Radial indicator for compact spaces
• Step progress: Shows discrete steps in a process
• Upload progress: Specialized for file uploads
• Loading spinner: Simple activity indicator

Feedback Mechanisms

Alerts

Alerts provide important information, feedback, or warnings to users.

Component: Alert

Implementation Details:

• High-visibility design appropriate to importance level
• Clear iconography reinforcing message type
• Concise, action-oriented text
• Dismissible where appropriate

States:

• Info: Blue styling for general information
• Success: Green styling for positive outcomes
• Warning: Amber styling for potential issues
• Error: Red styling for problems requiring attention
• Dismissed: Smooth exit animation

Variations:

• Toast: Temporary notification that appears and disappears
• Banner: Full-width alert at the top of the interface
• Inline alert: Contextual message within a form or section
• Modal alert: Blocks interaction for critical messages
• Persistent alert: Remains visible until explicitly dismissed

Loading Indicators

Loading indicators communicate that the system is processing or retrieving data.

Component: LoadingIndicator

Implementation Details:

• Clear visual indication of system activity
• Brand-appropriate styling and animation
• Appropriate size for context
• Accessible alternative text

States:

• Active: Animated to show ongoing process
• Complete: Transition to success state when finished
• Error: Transition to error state if process fails

Variations:

• Spinner: Circular animation for general loading
• Linear loader: Horizontal progress for defined processes
• Skeleton loader: Content placeholder during loading
• Button loader: Replaces button text during action processing
• Page loader: Full-page loading state for initial content

Modals & Dialogs

Modals and dialogs present focused content that requires attention or interaction.

Component: Modal

Implementation Details:

• Clear visual separation from background content
• Appropriate use of elevation and focus
• Consistent header, body, and action areas
• Smooth entrance and exit animations

States:

• Opening: Entrance animation from center
• Open: Fully visible with background dimmed
• Closing: Exit animation
• Stacked: Visual indication when multiple modals are open

Variations:

• Information modal: Presents important information
• Confirmation dialog: Requires user confirmation
• Form dialog: Contains form elements for data entry
• Alert dialog: Communicates critical information
• Feature modal: Introduces new features or capabilities

Component: Tooltip

Implementation Details:

• Compact design for contextual information
• Consistent positioning relative to trigger element
• Appropriate timing for appearance/disappearance
• Non-intrusive presence

States:

• Hidden: Not visible to user
• Appearing: Fade in animation
• Visible: Fully displayed
• Disappearing: Fade out animation

Variations:

• Text tooltip: Simple text explanation
• Rich tooltip: Enhanced with icons or formatting
• Interactive tooltip: Contains interactive elements
• Feature tooltip: Highlights new features
• Help tooltip: Provides assistance for complex features

Component Patterns

State Variations

SvenHVAC components implement a comprehensive state system to provide clear feedback and guide user interaction:

Interactive States

• Default: The standard, resting appearance of a component

• Hover: Visual feedback when a pointer is positioned over an interactive element

  • Subtle background color change for most elements
  • Slight elevation increase for card-like components
  • Text decoration changes for links

• Focus: Clear indication when an element receives keyboard focus

  • High-contrast outline (2px blue) for accessibility
  • Never relies solely on color change
  • Persists until focus moves elsewhere

• Active/Pressed: Immediate feedback during interaction

  • Slight scale reduction (95-98% of original size)
  • Darker color shade for buttons
  • Reduced elevation for raised elements

• Disabled: Clear indication that an element is not interactive

  • Reduced opacity (60%)
  • Removal of hover/focus effects
  • Cursor change to not-allowed
  • Maintains sufficient contrast for visibility

Selection States

• Unselected: Default state for selectable elements

• Selected: Clear indication of selection

  • High-contrast visual change (background fill for buttons, checkmark for options)
  • Consistent use of brand colors (primary blue or orange)
  • Maintains selected state until explicitly changed

• Indeterminate/Partial: Indicates partial selection

  • Visually distinct from both selected and unselected states
  • Used primarily in checkbox groups and filters

Validation States

• Neutral: Default state before validation

• Valid: Indicates successfully validated input

  • Subtle success indicator (green checkmark)
  • Minimal visual change to avoid distraction

• Invalid: Indicates validation failure

  • Clear error messaging with specific guidance
  • Red border and icon for immediate recognition
  • Associated helper text explains the issue

• Warning: Indicates potential issues

  • Amber visual indicators
  • Non-blocking but draws attention

Process States

• Idle: Default state before a process begins

• Loading: Indicates ongoing process

  • Appropriate loading indicator for context
  • Disabled interaction where appropriate
  • Maintains context about what's happening

• Success: Indicates successful completion

  • Clear success messaging
  • Green visual indicators
  • Temporary state before returning to idle

• Error: Indicates process failure

  • Clear error messaging with recovery options
  • Red visual indicators
  • Maintains context about what failed

Responsive Behavior

SvenHVAC components adapt to different screen sizes and devices through these consistent patterns:

Breakpoint System

Components respond to these standard breakpoints:

• Mobile: 0-479px
• Tablet Small: 480-767px
• Tablet Large: 768-1023px
• Desktop Small: 1024-1279px
• Desktop Large: 1280px and above

Layout Adaptation

• Stacking: Multi-column layouts stack vertically on smaller screens
• Reflow: Content reflows to maintain readability within viewport
• Priority Content: Critical content maintains prominence across breakpoints
• Progressive Disclosure: Less essential content is progressively revealed as space allows

Component Transformations

• Navigation: Horizontal navigation becomes vertical or hamburger menu
• Tables: Tables transform to cards or lists on small screens
• Forms: Multi-column forms become single column
• Buttons: Button groups stack or use more compact styling
• Modals: Full-screen on mobile, centered dialog on larger screens

Touch Optimization

• Target Sizing: Touch targets maintain minimum 44×44px size
• Spacing Increases: Element spacing increases for touch interfaces
• Gesture Support: Support for touch gestures (swipe, pinch)
• Input Adaptation: Input methods adapt to touch (larger selectors, specialized keyboards)

Specific Component Adaptations

Component: NavigationBar
Mobile: Collapses to hamburger menu with slide-in panel
Tablet: Shows primary items with overflow menu
Desktop: Shows all navigation items horizontally

Component: DataTable
Mobile: Transforms to stacked cards with row data
Tablet: Horizontally scrollable with fixed first column
Desktop: Full table layout with all columns visible

Component: Form
Mobile: Full-width inputs, stacked sections
Tablet: Grouped inputs, side-by-side where appropriate
Desktop: Multi-column layout with logical grouping

Component: Modal
Mobile: Full-screen with bottom sheet actions
Tablet: 80% width with centered position
Desktop: Fixed width (max 600px) with centered position

Composition Patterns

SvenHVAC components are designed to work together in consistent, predictable ways through these composition patterns:

Form Compositions

• Label Positioning: Labels consistently positioned above inputs for clarity
• Validation Messaging: Error messages appear below the relevant input
• Required Fields: Indicated with subtle asterisk, explained at form start
• Field Grouping: Related fields grouped with clear visual boundaries
• Action Alignment: Primary actions right-aligned, secondary actions left-aligned
• Progressive Disclosure: Complex forms use progressive disclosure to manage complexity

Example form composition:

[Form Title]
* Required fields

[Field Group Label]
Label *
[Text Input]
Helper text

Label
[Text Input]
Error message

[Checkbox] Remember this information

[Cancel] [Submit →]

Card Compositions

• Content Hierarchy: Consistent internal structure with clear visual hierarchy
• Action Placement: Primary actions at bottom, icon actions at top right
• Media Handling: Media positioned consistently at top or left
• Status Indication: Status indicators positioned at top right
• Information Density: Appropriate density for content type and importance

Example card composition:

[Card]
  [Header]
    [Title] Card Title
    [Icon Button]
  [Media] Optional image or illustration
  [Content]
    Primary content with consistent typography
    Secondary content with reduced emphasis
  [Status] Status indicator if relevant
  [Actions]
    [Secondary Action] [Primary Action]

Navigation Patterns

• Hierarchy Indication: Clear indication of current location in hierarchy
• Consistent Placement: Navigation elements in consistent locations
• Progressive Disclosure: Complex navigation uses progressive disclosure
• Breadcrumbs: Used for deep hierarchies to show path and enable backtracking
• Section Transitions: Clear visual transitions between sections

Example navigation composition:

[Primary Navigation Bar]
  [Logo] [Nav Item] [Nav Item] [Active Nav Item] [Nav Item] [Profile]

[Breadcrumbs]
  Home > Section > Current Page

[Page Title]

[Secondary Navigation]
  [Tab] [Active Tab] [Tab] [Tab]

[Content Area]

Dashboard Compositions

• Priority Placement: Critical information positioned at top left
• Grouping Logic: Related metrics and information grouped together
• Consistent Card Usage: Similar information presented in consistent card formats
• Action Proximity: Actions positioned near related content
• Scannable Layout: Information arranged to support quick scanning

Example dashboard composition:

[Page Header]
  [Title] Dashboard
  [Date Range Selector] [Actions]

[Summary Metrics]
  [Metric Card] [Metric Card] [Metric Card] [Metric Card]

[Primary Content]
  [Data Visualization Card - 2/3 width]
  [Status Card - 1/3 width]

[Secondary Content]
  [Activity Card]
  [Upcoming Appointments Card]

Accessibility Implementations

SvenHVAC components implement comprehensive accessibility features to ensure inclusive design:

Keyboard Navigation

• Focus Management: Logical tab order following visual layout
• Focus Indicators: High-contrast focus states (2px blue outline)
• Keyboard Shortcuts: Support for standard keyboard interactions
  • Enter/Space to activate buttons and interactive elements
  • Arrow keys for navigation within components
  • Escape to dismiss modals and popups
• Skip Links: Hidden links that appear on focus to bypass repetitive navigation

Screen Reader Support

• Semantic Markup: Proper HTML elements for semantic meaning
• ARIA Attributes: Appropriate ARIA roles, states, and properties
  • aria-label for unlabeled interactive elements
  • aria-expanded for expandable sections
  • aria-controls to associate controls with their targets
  • aria-live regions for dynamic content
• Status Announcements: Important status changes announced to screen readers
• Alternative Text: Meaningful alt text for all images and icons

Color and Contrast

• Contrast Ratios: All text meets WCAG AA standards
  • Normal text: minimum 4.5:1 ratio
  • Large text: minimum 3:1 ratio
  • UI components: minimum 3:1 ratio against adjacent colors
• Color Independence: Information never conveyed by color alone
  • Icons and text reinforce color meaning
  • Patterns used in addition to color for charts and graphs
• Focus Visibility: Focus indicators visible in high-contrast mode

Touch and Pointer Accessibility

• Target Size: Interactive elements minimum 44×44px
• Gesture Alternatives: Alternative methods for gesture-based interactions
• Touch Feedback: Clear visual feedback for touch interactions
• Error Forgiveness: Easy error recovery and confirmation for destructive actions

Specific Component Implementations

Component: Button
- Role: Uses native button element with appropriate type
- States: All states conveyed to assistive technology
- Labels: Clear, action-oriented text describing function

Component: Form Fields
- Association: Labels properly associated with inputs
- Validation: Errors linked to fields with aria-describedby
- Grouping: Related fields grouped with fieldset and legend

Component: Modal
- Focus: Traps focus within modal when open
- Dismissal: Supports Escape key for closing
- Announcement: Announces opening to screen readers

Component: Tabs
- Roles: Uses appropriate role="tablist", role="tab", role="tabpanel"
- Keyboard: Arrow keys navigate between tabs
- State: Current tab indicated with aria-selected

Implementation Guide

Code Architecture

The SvenHVAC component library follows a structured architecture to ensure maintainability, performance, and consistency:

Component Structure

• Atomic Design Methodology: Components organized by complexity

  • Atoms: Basic building blocks (buttons, inputs, icons)
  • Molecules: Simple combinations (form fields, search bars)
  • Organisms: Complex components (navigation bars, appointment cards)
  • Templates: Page-level component arrangements

• File Organization:

  /components
    /atoms
      /Button
        Button.jsx
        Button.styles.js
        Button.test.js
        Button.stories.js
        index.js
    /molecules
      /FormField
        FormField.jsx
        FormField.styles.js
        FormField.test.js
        FormField.stories.js
        index.js
    /organisms
      /...
    /templates
      /...

Styling Approach

• CSS-in-JS Methodology: Styled components for encapsulated styling
• Token-Based Styling: All styles reference design tokens
• Style Composition: Styles composed through theme provider
• Global Styles: Minimal global styles for base elements
• Responsive Utilities: Helper functions for responsive styling

// Example styled component using design tokens
const StyledButton = styled.button`
  background-color: ${props => props.variant === 'primary' 
    ? props.theme.colors.actionPrimary 
    : props.theme.colors.actionSecondary};
  padding: ${props => props.theme.spacing.componentMd};
  border-radius: ${props => props.theme.radii.md};
  font-family: ${props => props.theme.fonts.primary};
  font-weight: ${props => props.theme.fontWeights.medium};
  transition: ${props => props.theme.transitions.button};
  
  &:hover {
    background-color: ${props => props.variant === 'primary'
      ? darken(0.1, props.theme.colors.actionPrimary)
      : darken(0.1, props.theme.colors.actionSecondary)};
  }
  
  &:focus {
    outline: ${props => props.theme.borders.focus};
  }
  
  /* Responsive adjustments */
  ${props => props.theme.media.mobile} {
    width: 100%;
  }
`;

State Management

• Component-Level State: Internal state for UI behavior
• Prop-Driven Design: Component behavior controlled through props
• Context API: For theme and global state
• Controlled vs. Uncontrolled: Support for both patterns
• Event Handling: Consistent patterns for event propagation

// Example component with state management
function Accordion({ items, defaultExpanded, onChange }) {
  const [expandedIndex, setExpandedIndex] = useState(defaultExpanded || -1);
  
  const handleToggle = (index) => {
    const newIndex = index === expandedIndex ? -1 : index;
    setExpandedIndex(newIndex);
    if (onChange) onChange(newIndex);
  };
  
  return (
    <div className="accordion">
      {items.map((item, index) => (
        <AccordionItem
          key={index}
          title={item.title}
          expanded={index === expandedIndex}
          onToggle={() => handleToggle(index)}
        >
          {item.content}
        </AccordionItem>
      ))}
    </div>
  );
}

Testing Architecture

• Unit Tests: Component rendering and behavior
• Integration Tests: Component interactions
• Accessibility Tests: WCAG compliance verification
• Visual Regression: UI appearance consistency
• Storybook Integration: Interactive component documentation

Framework Integration

The SvenHVAC component library is designed for React, with patterns that ensure proper integration:

React Implementation

• Functional Components: Modern React patterns with hooks
• Prop Types: Comprehensive prop validation
• Default Props: Sensible defaults for all components
• Composition Model: Children and render props for flexibility
• Ref Forwarding: Support for ref access to DOM elements

// Example React component implementation
import React, { forwardRef } from 'react';
import PropTypes from 'prop-types';
import { StyledButton } from './Button.styles';

const Button = forwardRef(({
  children,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  onClick,
  type = 'button',
  ...props
}, ref) => {
  return (
    <StyledButton
      ref={ref}
      variant={variant}
      size={size}
      disabled={disabled}
      onClick={onClick}
      type={type}
      {...props}
    >
      {children}
    </StyledButton>
  );
});

Button.propTypes = {
  children: PropTypes.node.isRequired,
  variant: PropTypes.oneOf(['primary', 'secondary', 'tertiary']),
  size: PropTypes.oneOf(['small', 'medium', 'large']),
  disabled: PropTypes.bool,
  onClick: PropTypes.func,
  type: PropTypes.oneOf(['button', 'submit', 'reset']),
};

export default Button;

Theming Integration

• Theme Provider: Context-based theme distribution
• Theme Switching: Support for dynamic theme changes
• Token Access: Consistent access to design tokens
• Component Theming: Component-specific theme overrides

// Example theme provider implementation
import React from 'react';
import { ThemeProvider as StyledThemeProvider } from 'styled-components';
import { theme } from '../theme';

export const ThemeProvider = ({ children, customTheme = {} }) => {
  const mergedTheme = {
    ...theme,
    ...customTheme,
    colors: {
      ...theme.colors,
      ...customTheme.colors,
    },
  };
  
  return (
    <StyledThemeProvider theme={mergedTheme}>
      {children}
    </StyledThemeProvider>
  );
};

Composition Patterns

• Compound Components: Related components grouped logically
• Render Props: Flexible rendering through function props
• Higher-Order Components: For shared functionality
• Custom Hooks: Reusable stateful logic

// Example compound component pattern
import React, { createContext, useContext, useState } from 'react';

const TabContext = createContext();

export function Tabs({ children, defaultIndex = 0, onChange }) {
  const [activeIndex, setActiveIndex] = useState(defaultIndex);
  
  const handleChange = (index) => {
    setActiveIndex(index);
    if (onChange) onChange(index);
  };
  
  return (
    <TabContext.Provider value={{ activeIndex, onChange: handleChange }}>
      {children}
    </TabContext.Provider>
  );
}

export function TabList({ children }) {
  return <div role="tablist">{children}</div>;
}

export function Tab({ children, index }) {
  const { activeIndex, onChange } = useContext(TabContext);
  const isActive = activeIndex === index;
  
  return (
    <button
      role="tab"
      aria-selected={isActive}
      onClick={() => onChange(index)}
    >
      {children}
    </button>
  );
}

export function TabPanel({ children, index }) {
  const { activeIndex } = useContext(TabContext);
  const isActive = activeIndex === index;
  
  if (!isActive) return null;
  
  return <div role="tabpanel">{children}</div>;
}

Event Handling

• Callback Props: Consistent naming (onClick, onChange)
• Event Objects: Standard event object passing
• Accessibility Events: Support for keyboard and focus events
• Custom Events: Consistent pattern for component-specific events

Performance Optimization

The SvenHVAC component library implements performance optimizations to ensure efficient operation:

Rendering Optimization

• Memoization: React.memo for expensive components
• Callback Memoization: useCallback for event handlers
• Derived State: useMemo for computed values
• Virtualization: For long lists and tables
• Code Splitting: Dynamic imports for large components

// Example of optimized component
import React, { useCallback, useMemo } from 'react';

const AppointmentList = React.memo(({ appointments, onSelect }) => {
  // Memoized derived data
  const sortedAppointments = useMemo(() => {
    return [...appointments].sort((a, b) => new Date(a.date) - new Date(b.date));
  }, [appointments]);
  
  // Memoized callback
  const handleSelect = useCallback((id) => {
    onSelect(id);
  }, [onSelect]);
  
  return (
    <ul>
      {sortedAppointments.map(appointment => (
        <AppointmentItem
          key={appointment.id}
          appointment={appointment}
          onSelect={handleSelect}
        />
      ))}
    </ul>
  );
});

Bundle Optimization

• Tree Shaking: ES modules for better dead code elimination
• Dependency Management: Minimal external dependencies
• Code Splitting: Component-level code splitting
• Lazy Loading: Defer loading of non-critical components
• Module Federation: Shared components across applications

// Example of lazy loading
import React, { Suspense, lazy } from 'react';

const ComplexDashboard = lazy(() => import('./ComplexDashboard'));

function App() {
  return (
    <div>
      <Suspense fallback={<LoadingIndicator />}>
        <ComplexDashboard />
      </Suspense>
    </div>
  );
}

Asset Optimization

• Icon System: SVG sprite system for icons
• Image Optimization: Responsive images with srcset
• Font Loading: Optimized font loading strategy
• CSS Optimization: Minimal CSS footprint

// Example of optimized icon system
import React from 'react';
import { iconMap } from './iconMap';

export const Icon = ({ name, size = 'medium', color = 'currentColor', ...props }) => {
  if (!iconMap[name]) {
    console.warn(`Icon "${name}" not found`);
    return null;
  }
  
  const sizeMap = {
    small: 16,
    medium: 24,
    large: 32,
  };
  
  const pixelSize = typeof size === 'string' ? sizeMap[size] : size;
  
  return (
    <svg
      width={pixelSize}
      height={pixelSize}
      fill={color}
      viewBox="0 0 24 24"
      aria-hidden="true"
      {...props}
    >
      <use xlinkHref={`#icon-${name}`} />
    </svg>
  );
};

Runtime Performance

• Debouncing: For high-frequency events
• Throttling: For scroll and resize handlers
• Animation Optimization: Hardware acceleration for animations
• Passive Event Listeners: For scroll performance
• Intersection Observer: For lazy loading and animations

// Example of optimized scroll handling
import { useEffect, useState, useCallback } from 'react';
import { throttle } from 'lodash-es';

function useScrollPosition() {
  const [scrollY, setScrollY] = useState(0);
  
  const handleScroll = useCallback(throttle(() => {
    setScrollY(window.scrollY);
  }, 100), []);
  
  useEffect(() => {
    window.addEventListener('scroll', handleScroll, { passive: true });
    return () => window.removeEventListener('scroll', handleScroll);
  }, [handleScroll]);
  
  return scrollY;
}

Documentation System

The SvenHVAC component library includes a comprehensive documentation system:

Component API Documentation

• Props: Complete prop documentation with types and defaults
• Examples: Usage examples for common scenarios
• Accessibility: Accessibility considerations and requirements
• States: Documentation of all component states
• Variations: All component variations with examples

## Button

Buttons allow users to take actions and make choices with a single tap.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | The button's appearance style |
| size | 'small' \| 'medium' \| 'large' | 'medium' | The button's size |
| disabled | boolean | false | Whether the button is disabled |
| onClick | function | - | Callback fired when button is clicked |
| type | 'button' \| 'submit' \| 'reset' | 'button' | The button's HTML type |
| children | ReactNode | - | The content of the button |

### Examples

```jsx
<Button variant="primary">Primary Action</Button>
<Button variant="secondary">Secondary Action</Button>
<Button variant="tertiary">Tertiary Action</Button>
<Button disabled>Disabled Button</Button>

Accessibility

• Uses native button element for proper semantics
• Maintains minimum touch target size of 44×44px
• Supports keyboard focus with visible focus state
• Disabled state is properly communicated to assistive technology

#### Storybook Integration

- **Interactive Examples**: Manipulate props in real-time
- **Component Playground**: Test components in isolation
- **Docs Page**: Auto-generated documentation from comments
- **Accessibility Tests**: Integrated a11y testing
- **Responsive Testing**: Viewport tools for responsive testing

```javascript
// Example Storybook story
import React from 'react';
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      control: {
        type: 'select',
        options: ['primary', 'secondary', 'tertiary'],
      },
    },
    size: {
      control: {
        type: 'select',
        options: ['small', 'medium', 'large'],
      },
    },
    disabled: {
      control: 'boolean',
    },
    onClick: { action: 'clicked' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  variant: 'primary',
  children: 'Primary Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  variant: 'secondary',
  children: 'Secondary Button',
};

export const Disabled = Template.bind({});
Disabled.args = {
  disabled: true,
  children: 'Disabled Button',
};

Usage Guidelines

• Best Practices: Recommended usage patterns
• Anti-Patterns: Patterns to avoid with explanations
• Composition Examples: How to combine components
• Responsive Behavior: How components adapt to different screens
• Accessibility Guidelines: How to ensure accessible implementation

## Form Field Usage Guidelines

### Best Practices

- Always use labels with form fields
- Group related fields with fieldsets
- Provide helper text for complex inputs
- Use appropriate field types for data (email, tel, etc.)
- Indicate required fields consistently

### Anti-Patterns

- Avoid placeholder text as the only label
- Don't rely solely on color to indicate validation state
- Avoid disabling submit buttons without explaining why
- Don't use fields that automatically advance focus
- Avoid form fields that submit on enter when multiple fields are present

### Composition Example

```jsx
<FormGroup>
  <FormLabel htmlFor="name" required>Full Name</FormLabel>
  <TextField 
    id="name" 
    name="name" 
    required 
    autoComplete="name" 
  />
  <FormHelperText>Enter your legal name as it appears on your ID</FormHelperText>
</FormGroup>

Responsive Behavior

• On mobile, form fields stack vertically and expand full-width
• On tablet and above, related fields may appear side-by-side
• Error messages always appear directly below the relevant field
• Labels appear above fields on all screen sizes

#### Decision Trees

- **Component Selection**: Guides for choosing appropriate components
- **Pattern Selection**: Decision trees for implementation patterns
- **Variant Selection**: When to use different component variants
- **Customization Guidance**: Decision process for customization

```mermaid
graph TD
    A[Need to collect user input] --> B{Multiple options?}
    B -->|Yes| C{How many options?}
    B -->|No| D{What type of input?}
    C -->|Few options| E{Allow multiple selections?}
    C -->|Many options| F{Need filtering?}
    E -->|Yes| G[Checkbox Group]
    E -->|No| H[Radio Group]
    F -->|Yes| I[Searchable Dropdown]
    F -->|No| J[Standard Dropdown]
    D -->|Text| K{Single or multi-line?}
    D -->|Number| L[Number Input]
    D -->|Date| M[Date Picker]
    K -->|Single| N[Text Field]
    K -->|Multi| O[Text Area]

Component Showcase

Below are key component examples that demonstrate the SvenHVAC design system in action:

Appointment Card

The Appointment Card is a core component for displaying scheduled service appointments:

Component: AppointmentCard

Description: A comprehensive card displaying all relevant appointment information with appropriate actions and status indicators.

Visual Characteristics:

• Clean, contained design with subtle shadow
• Clear visual hierarchy emphasizing date, time, and service type
• Status badge in the top-right corner
• Action buttons aligned at bottom

States:

• Upcoming: Blue accent with countdown indicator
• Confirmed: Green accent with technician information
• In Progress: Orange accent with progress indicator
• Completed: Gray accent with summary information
• Cancelled: Red accent with rebooking option

Content Structure:

[AppointmentCard]
  [StatusBadge] Confirmed
  [DateTimeSection]
    [Date] Tuesday, Oct 12
    [Time] 2:00 PM - 4:00 PM
  [ServiceSection]
    [ServiceType] AC Repair
    [ServiceDescription] Not cooling properly, possible refrigerant leak
  [LocationSection]
    [Address] 123 Main St, Worcester, MA
  [TechnicianSection] (if assigned)
    [TechnicianName] John Smith
    [TechnicianContact] (508) 555-1234
  [ActionSection]
    [SecondaryButton] Reschedule
    [PrimaryButton] Get Directions

Responsive Behavior:

• Full width on mobile devices
• Fixed width (400px) on tablet and above
• Maintains all information but adjusts layout for readability

Service Selection

The Service Selection component allows users to choose the type of HVAC service needed:

Component: ServiceSelectionCard

Description: An interactive card-based selection system for choosing between different HVAC service types.

Visual Characteristics:

• Card-based options with clear visual differentiation
• Icon and text combination for each service type
• Clear selection state with brand orange highlight
• Subtle hover effects for interactive feedback

States:

• Default: Neutral appearance with service information
• Hover: Subtle elevation increase and border highlight
• Selected: Orange border, check icon, and background tint
• Disabled: Grayed out appearance with "unavailable" indicator

Content Structure:

[ServiceSelectionGroup]
  [ServiceCard selected]
    [ServiceIcon] AC
    [ServiceTitle] Air Conditioning
    [ServiceDescription] Repairs and maintenance for cooling systems
  [ServiceCard]
    [ServiceIcon] Heat
    [ServiceTitle] Heating
    [ServiceDescription] Furnace and boiler service and repair
  [ServiceCard]
    [ServiceIcon] Maintenance
    [ServiceTitle] Preventative Maintenance
    [ServiceDescription] Regular system check-ups and tune-ups
  [ServiceCard disabled]
    [ServiceIcon] Installation
    [ServiceTitle] New Installation
    [ServiceDescription] Currently unavailable in your area

Responsive Behavior:

• Grid layout (2×2) on tablet and above
• Single column stack on mobile devices
• Maintains touch-friendly sizing across devices

Appointment Scheduler

The Appointment Scheduler allows users to select available time slots:

Component: AppointmentScheduler

Description: A comprehensive scheduling interface for selecting appointment dates and times based on service provider availability.

Visual Characteristics:

• Clear calendar view with available/unavailable date indication
• Time slot selection with availability indicators
• Progressive disclosure of options (date → time → confirmation)
• Consistent use of brand colors to indicate selection and availability

States:

• Date Selection: Calendar view with available dates highlighted
• Time Selection: Available time slots for selected date
• Confirmation: Summary view with selected date and time
• Loading: Loading state while checking availability
• Error: Error state when availability cannot be retrieved

Content Structure:

[AppointmentScheduler]
  [StepIndicator] Step 2 of 3: Select Time
  
  [DateSelection]
    [MonthNavigator] October 2023
    [CalendarGrid]
      [DateCell unavailable] 1
      [DateCell] 2
      [DateCell selected] 3
      ...
  
  [TimeSelection]
    [TimeSlotGroup] Morning
      [TimeSlot unavailable] 8:00 AM
      [TimeSlot] 9:00 AM
      [TimeSlot selected] 10:00 AM
      [TimeSlot] 11:00 AM
    [TimeSlotGroup] Afternoon
      [TimeSlot] 1:00 PM
      [TimeSlot] 2:00 PM
      ...
  
  [ActionSection]
    [SecondaryButton] Back
    [PrimaryButton] Continue

Responsive Behavior:

• Side-by-side date and time selection on desktop
• Stacked date and time selection on mobile
• Touch-optimized date cells and time slots on mobile

Issue Diagnostic Tool

The Issue Diagnostic Tool helps users describe their HVAC problems:

Component: DiagnosticTool

Description: A step-by-step interface that guides users through diagnosing their HVAC issues before scheduling service.

Visual Characteristics:

• Clear question-and-answer format
• Visual aids for technical concepts
• Progressive disclosure of questions based on previous answers
• Summary view of identified issues

States:

• Question: Displays current diagnostic question
• Selection: Shows options relevant to current question
• Summary: Displays diagnostic results and recommendations
• Loading: Shows when processing complex diagnostic logic
• Photo Upload: Interface for uploading issue photos

Content Structure:

[DiagnosticTool]
  [ProgressBar] 2 of 5
  
  [QuestionSection]
    [QuestionText] What type of noise is your system making?
    [HelpText] This helps identify potential mechanical issues
  
  [OptionSection]
    [OptionCard]
      [OptionIcon] Grinding
      [OptionLabel] Grinding or Scraping
    [OptionCard selected]
      [OptionIcon] Whistling
      [OptionLabel] Whistling or Hissing
    [OptionCard]
      [OptionIcon] Banging
      [OptionLabel] Banging or Thumping
    [OptionCard]
      [OptionIcon] Clicking
      [OptionLabel] Clicking or Ticking
  
  [ActionSection]
    [SecondaryButton] Back
    [PrimaryButton] Continue

Responsive Behavior:

• Grid layout for options on tablet and desktop
• Single column for options on mobile
• Maintains clear visual aids across all devices

Payment Summary

The Payment Summary component displays deposit and payment information:

Component: PaymentSummary

Description: A clear summary of service costs, deposit requirements, and payment options.

Visual Characteristics:

• Clean, structured layout with clear cost breakdown
• Prominent call-to-action for payment
• Security indicators to build trust
• Clear distinction between deposit and total cost

States:

• Unpaid: Shows payment options and call-to-action
• Processing: Payment in progress state
• Paid: Confirmation of successful payment
• Failed: Error state with retry options
• Partial: Indicates deposit paid, balance due

Content Structure:

[PaymentSummary]
  [ServiceSummary]
    [ServiceType] AC Repair - Emergency Service
    [AppointmentTime] Tuesday, Oct 12, 2:00 PM - 4:00 PM
  
  [CostBreakdown]
    [LineItem]
      [Label] Diagnostic Fee
      [Amount] $89.00
    [LineItem]
      [Label] Emergency Service Fee
      [Amount] $50.00
    [Divider]
    [TotalLine]
      [Label] Required Deposit
      [Amount] $139.00
    [DepositNote] Full service cost will be determined after diagnosis
  
  [PaymentSection]
    [SecurityIndicator] 🔒 Secure Payment
    [PaymentOptions]
      [PaymentMethod selected] Credit Card
      [PaymentMethod] PayPal
    [PaymentButton] Pay Deposit Now
  
  [LegalText] Deposit is fully refundable if canceled 24+ hours before appointment

Responsive Behavior:

• Maintains full content across all screen sizes
• Adjusts layout for optimal readability on mobile
• Payment options stack vertically on smaller screens

Conclusion

The SvenHVAC Component Library provides a comprehensive set of UI components that embody the brand's "technical warmth" - balancing innovative technology with human reassurance. The library is designed to support the creation of intuitive, accessible interfaces for scheduling HVAC services, particularly during stressful emergency situations.

Key strengths of this component library include:

1. Consistent Brand Expression: All components consistently express SvenHVAC's dual Magician/Caregiver archetypes through visual design, interaction patterns, and feedback mechanisms.

2. Accessibility-First Approach: Comprehensive accessibility implementation ensures the system is usable by all customers, regardless of abilities.

3. Responsive Design: Components adapt seamlessly across devices, critical for emergency situations where users may be on mobile devices.

4. Performance Optimization: Careful attention to rendering efficiency and bundle size ensures fast, responsive experiences.

5. Comprehensive Documentation: Detailed guidelines and examples support consistent implementation across the application.

This component library will serve as the foundation for SvenHVAC's digital presence, ensuring a cohesive, intuitive experience as the service expands from its initial Worcester, MA market to nationwide coverage.