CompanionPulse Component Library

Design System Foundation

Design Tokens

This component library implements CompanionPulse's visual identity through a comprehensive token system that creates a warm, inviting, and trustworthy presence while maintaining a contemporary feel for both senior users and their adult children.

Color Tokens

/* Primary Colors */
--color-primary-amber: #E8A44C;      /* Amber Glow: warm, golden tone for primary actions and focus */
--color-primary-terracotta: #B85C38; /* Deep Terracotta: grounded, earthy red for stability */
--color-primary-cream: #F7EDE2;      /* Soft Cream: gentle neutral for backgrounds and breathing room */

/* Secondary Colors */
--color-secondary-sage: #7A9E7E;     /* Sage Green: calming, natural green for wellbeing elements */
--color-secondary-blue: #758ECD;     /* Dusty Blue: soft, approachable blue for information */
--color-secondary-gray: #C7C7C7;     /* Warm Gray: neutral for subtle elements and borders */

/* Accent Colors */
--color-accent-orange: #F26C4F;      /* Sunset Orange: vibrant highlight for emphasis */
--color-accent-indigo: #2E294E;      /* Deep Indigo: rich dark tone for contrast and depth */

/* Semantic Colors */
--color-text-primary: #2E294E;       /* Primary text: high contrast for readability */
--color-text-secondary: #5D5766;     /* Secondary text: softer contrast for supporting content */
--color-text-tertiary: #8C8797;      /* Tertiary text: lowest contrast for hints and captions */
--color-text-inverse: #F7EDE2;       /* Inverse text: for dark backgrounds */

--color-background-primary: #F7EDE2; /* Primary background: soft cream for main surfaces */
--color-background-secondary: #FDF8F3; /* Secondary background: lighter shade for cards and sections */
--color-background-tertiary: #FFFFFF; /* Tertiary background: pure white for contrast areas */

--color-border-light: #E5DDD3;       /* Light border: subtle separation */
--color-border-medium: #C7C7C7;      /* Medium border: standard separation */
--color-border-heavy: #9A9A9A;       /* Heavy border: strong separation */

--color-success: #7A9E7E;            /* Success: calming green */
--color-warning: #E8A44C;            /* Warning: attention-grabbing amber */
--color-error: #B85C38;              /* Error: noticeable but not alarming terracotta */
--color-info: #758ECD;               /* Info: approachable blue */

Typography Tokens

/* Font Families */
--font-family-primary: 'Merriweather', serif;      /* Serif for headlines and emphasis */
--font-family-secondary: 'Source Sans Pro', sans-serif; /* Sans-serif for body and UI */

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

/* Font Sizes - Using a scale optimized for aging eyes */
--font-size-xxs: 14px;  /* Minimum size for any text */
--font-size-xs: 16px;   /* Small UI text, captions */
--font-size-s: 18px;    /* Body text, form inputs */
--font-size-m: 20px;    /* Subheadings, important UI elements */
--font-size-l: 24px;    /* Section headers */
--font-size-xl: 28px;   /* Page titles */
--font-size-xxl: 32px;  /* Major headlines */

/* Line Heights - More generous for better readability */
--line-height-tight: 1.3;
--line-height-normal: 1.5;
--line-height-loose: 1.7;

/* Letter Spacing */
--letter-spacing-tight: -0.01em;
--letter-spacing-normal: 0;
--letter-spacing-loose: 0.02em;
--letter-spacing-heading: 0.01em;  /* Slight tracking for headings */

Spacing Tokens

/* Spacing Scale - Based on 8px grid with more options for fine-tuning */
--space-xxs: 4px;
--space-xs: 8px;
--space-s: 16px;
--space-m: 24px;
--space-l: 32px;
--space-xl: 48px;
--space-xxl: 64px;
--space-xxxl: 96px;

/* Component Specific Spacing */
--space-input-padding-vertical: 12px;
--space-input-padding-horizontal: 16px;
--space-button-padding-vertical: 14px;
--space-button-padding-horizontal: 24px;
--space-card-padding: 24px;
--space-section-margin: 40px;

Border Tokens

/* Border Radius - Soft edges for approachable feel */
--radius-s: 4px;     /* Subtle rounding */
--radius-m: 8px;     /* Standard rounding for most components */
--radius-l: 12px;    /* Increased rounding for cards and containers */
--radius-xl: 20px;   /* Pronounced rounding for featured elements */
--radius-circle: 50%; /* Full circle for avatars and icons */

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

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

Shadow Tokens

/* Elevation System - Subtle shadows for depth without overwhelming */
--shadow-xs: 0 1px 2px rgba(46, 41, 78, 0.05);  /* Subtle lift */
--shadow-s: 0 2px 4px rgba(46, 41, 78, 0.08);   /* Light elevation */
--shadow-m: 0 4px 8px rgba(46, 41, 78, 0.1);    /* Medium elevation for cards */
--shadow-l: 0 8px 16px rgba(46, 41, 78, 0.12);  /* Higher elevation for dialogs */
--shadow-xl: 0 12px 24px rgba(46, 41, 78, 0.16); /* Maximum elevation for modals */

/* Inner Shadows */
--shadow-inner-s: inset 0 1px 2px rgba(46, 41, 78, 0.08); /* Subtle inset for pressed states */
--shadow-inner-m: inset 0 2px 4px rgba(46, 41, 78, 0.1);  /* Medium inset for form fields */

Animation Tokens

/* Timing Functions - Gentle easing for comfortable transitions */
--ease-standard: cubic-bezier(0.4, 0.0, 0.2, 1); /* Standard easing for most transitions */
--ease-in: cubic-bezier(0.4, 0.0, 1, 1);         /* Ease-in for elements entering */
--ease-out: cubic-bezier(0.0, 0.0, 0.2, 1);      /* Ease-out for elements exiting */
--ease-in-out: cubic-bezier(0.4, 0.0, 0.6, 1);   /* Balanced for bi-directional animations */

/* Duration - Slightly longer for senior users */
--duration-xs: 100ms;  /* Instant feedback */
--duration-s: 200ms;   /* Quick transitions */
--duration-m: 300ms;   /* Standard transitions */
--duration-l: 500ms;   /* Complex transitions */
--duration-xl: 800ms;  /* Major transitions */

/* Animation Preferences - Respects user preferences */
--motion-reduced: var(--duration-xs) var(--ease-standard); /* For reduced motion settings */

Grid System

CompanionPulse's components are organized within a responsive grid system that ensures consistent spacing and alignment while accommodating the needs of senior users across all interfaces.

Base Grid

• Foundation: 8px base grid for consistent spacing and alignment
• Container Width: Maximum 1200px with responsive padding
• Column System: 12-column grid on desktop, simplifying to 4-columns on mobile
• Gutters: 24px standard gutter width, reducing to 16px on mobile

Breakpoints

/* Breakpoint Tokens */
--breakpoint-xs: 320px;  /* Small mobile */
--breakpoint-s: 480px;   /* Large mobile */
--breakpoint-m: 768px;   /* Tablet */
--breakpoint-l: 1024px;  /* Desktop */
--breakpoint-xl: 1280px; /* Large desktop */

Layout Structure

• Generous Margins: Minimum 24px on mobile, increasing to 48px on desktop
• Consistent Padding: Card and container padding standardized at 24px
• Touch Targets: Minimum 44px × 44px for all interactive elements
• Vertical Rhythm: Based on 8px grid with typography aligned to baseline

Visual Style

CompanionPulse components express a "Warm Sophistication" identity balanced with "Accessible Technology" to create a sense of familiar comfort while incorporating modern design elements.

Shape Language

• Soft Corners: Rounded edges on all components (8px standard radius)
• Organic Forms: Slightly asymmetrical shapes for a more natural feel
• Generous Proportions: Spacious components that avoid crowding
• Horizontal Emphasis: Layouts that favor horizontal organization for easier scanning

Material Treatment

• Subtle Texture: Light, tactile textures inspired by natural materials
• Layered Approach: Clear layering with subtle shadows for depth
• Warm Surfaces: Background colors with slight warmth rather than stark white
• Gentle Contrast: Clear but not harsh distinction between elements

Visual Hierarchy

• Size Contrast: Significant size differences between hierarchical elements
• Weight Variation: Strategic use of bold text for emphasis
• Color Intensity: Primary colors for key actions and information
• Spatial Relationships: Grouping through proximity and alignment

Core Components

Input Controls

Text Fields

Text fields are designed for exceptional clarity and ease of use, with special attention to the needs of senior users.

graph TD
    A[Text Field Component] --> B[Label]
    A --> C[Input Area]
    A --> D[Helper Text]
    A --> E[Error Message]
    
    C --> F[Default State]
    C --> G[Focus State]
    C --> H[Filled State]
    C --> I[Error State]
    C --> J[Disabled State]

Implementation Details:

• Large, clearly defined input areas (minimum 44px height)
• Labels positioned above input fields (not placeholders)
• High contrast between input text and background
• Visible focus states with prominent indication
• Error states with both color and icon indicators
• Optional character counter for length-limited fields

States:

• Default: Light background with medium border
• Focus: Amber Glow border with subtle glow effect
• Filled: Maintained border definition with clear contrast for entered text
• Error: Terracotta border with error icon and message below
• Disabled: Reduced opacity with light gray background

Variations:

• Single-line: For short text entries
• Multi-line: For longer text with adjustable height
• With Icon: Leading or trailing icon for context
• With Action: Trailing action button (clear, show/hide password)
• Search: Specialized with search icon and clear action

Selection Controls

Selection controls provide clear, unambiguous choices with generous touch targets.

Checkboxes:

• Large touch target (24px × 24px visual size, 44px × 44px touch area)
• Clear check mark with high contrast
• Text label aligned with checkbox (vertically centered)
• Optional group layout with consistent spacing

States:

• Unchecked: Empty box with medium border
• Checked: Amber Glow fill with white check mark
• Indeterminate: Amber Glow fill with white dash
• Focused: Blue outline surrounding the control
• Disabled: Reduced opacity with gray fill when checked

Radio Buttons:

• Large touch target (24px × 24px visual size, 44px × 44px touch area)
• Clear visual difference between selected and unselected
• Vertical layout by default for clarity
• Optional horizontal layout for short options

States:

• Unselected: Empty circle with medium border
• Selected: Amber Glow fill with white dot center
• Focused: Blue outline surrounding the control
• Disabled: Reduced opacity with gray fill when selected

Toggle Switches:

• Large, easy-to-target toggle (28px × 16px minimum)
• Clear visual difference between states
• Optional label for current state (On/Off)
• Consistent position (right-aligned) in forms

States:

• Off: Gray track with white knob positioned left
• On: Amber Glow track with white knob positioned right
• Focused: Blue outline surrounding the control
• Disabled: Reduced opacity with gray track

Dropdown Menus

Dropdown menus are designed for clear option presentation with simplified interaction.

Implementation Details:

• Large touch target for dropdown trigger (minimum 44px height)
• Clear open/close affordance with chevron icon
• Generous option height (minimum 44px) for easy selection
• Limited visible options (maximum 5-7) to prevent overwhelming
• Search functionality for longer option lists
• Keyboard navigation support with visible focus states

States:

• Closed: Similar to text field with chevron indicator
• Open: Elevated menu with current selection highlighted
• Option Hover: Light Amber Glow background
• Option Selected: Checkmark icon and/or bold text
• Disabled: Reduced opacity with light gray background

Variations:

• Single Select: Standard dropdown for one selection
• Multi-Select: Allows multiple selections with chips
• Combo Box: Combination of dropdown and text input
• Segmented: Limited options shown as button group

Date and Time Inputs

Date and time inputs are optimized for senior users with simplified interaction.

Implementation Details:

• Clear, structured format for date entry
• Calendar picker with large, easy-to-target dates
• Simplified time selection with hour/minute increments
• Today/Now shortcuts for quick selection
• Clear format guidance and examples

States:

• Default: Similar to text field with calendar icon
• Focus: Opens calendar or time picker interface
• Selected: Displays formatted date/time with clear indication
• Error: Validation for impossible dates with clear message
• Disabled: Reduced opacity with light gray background

Variations:

• Date Only: Calendar-focused interface
• Time Only: Hour and minute selection
• Date and Time: Combined interface with tabs
• Range: Selection of start and end dates/times

Navigation Elements

Navigation Bar

The navigation bar provides clear, consistent access to main sections with simplified options.

Implementation Details:

• High contrast between navigation and content areas
• Text labels accompanying all navigation icons
• Current section clearly indicated
• Limited options to prevent overwhelming choices (4-5 maximum)
• Consistent positioning (bottom on mobile, side or top on larger screens)

States:

• Inactive: Gray icon and text
• Active: Amber Glow icon and text with indicator
• Hover: Lighter Amber Glow with subtle background
• Focused: Blue outline with background highlight

Responsive Behavior:

• Mobile: Bottom navigation with icons and labels
• Tablet: Side navigation with expanded labels
• Desktop: Either side navigation or top navigation bar

Tabs

Tabs organize content into clearly defined sections with intuitive switching.

Implementation Details:

• Large, easy-to-target tab areas
• Clear visual distinction for active tab
• Horizontal scrolling for many tabs on small screens
• Limited number of tabs recommended (3-5 maximum)
• Consistent positioning and behavior across screens

States:

• Inactive: Gray or text-colored label
• Active: Amber Glow text with indicator line or background
• Hover: Lighter Amber Glow with subtle background
• Focused: Blue outline with background highlight
• Disabled: Reduced opacity with gray text

Variations:

• Text Only: Clean, simple text labels
• Icon and Text: Combined for better recognition
• Pill Style: Rounded button-like tabs
• Underlined: Subtle underline indicator only

Buttons & Links

Buttons and links provide clear action affordances with generous sizing.

Primary Buttons:

• Large, clearly defined touch targets (minimum 48px height)
• Amber Glow background with high contrast text
• Centered text with optional leading/trailing icon
• Clear hover and active states

States:

• Default: Amber Glow background with white text
• Hover: Lighter Amber Glow with subtle glow effect
• Active/Pressed: Darker Amber Glow with slight inset effect
• Focused: Blue outline surrounding the button
• Disabled: Reduced opacity with gray overlay

Secondary Buttons:

• Same sizing as primary buttons
• Outlined style with Amber Glow border
• Amber Glow text for clear affordance
• Consistent padding with primary buttons

States:

• Default: Transparent with Amber Glow border and text
• Hover: Light Amber Glow background
• Active/Pressed: Darker border with slight inset effect
• Focused: Blue outline surrounding the button
• Disabled: Reduced opacity with gray border and text

Tertiary Buttons:

• Text-style buttons for less prominent actions
• Amber Glow text with no border
• Optional underline for better affordance
• Consistent height with other buttons

Links:

• Clear distinction from surrounding text
• Amber Glow color with optional underline
• Consistent behavior across content areas
• Large touch target when isolated from text

Button Groups:

• Logical grouping of related actions
• Clear hierarchy between primary and secondary actions
• Consistent spacing and alignment
• Responsive stacking on smaller screens

Breadcrumbs & Back Navigation

Breadcrumbs and back navigation provide clear orientation and navigation paths.

Implementation Details:

• Clear, visible back button on all non-home screens
• Simple breadcrumb trail for deeper navigation
• Current location clearly indicated
• Limited depth display (ellipsis for very deep paths)

States:

• Default: Gray or secondary text color
• Current: Normal text color, non-interactive
• Interactive: Amber Glow color with hover effects
• Focused: Blue outline with background highlight

Responsive Behavior:

• Mobile: Back button only, no breadcrumbs
• Tablet: Simplified breadcrumbs with key points
• Desktop: Full breadcrumb trail

Information Displays

Cards

Cards serve as containers for related content with clear visual boundaries.

Implementation Details:

• Consistent padding (24px) within all cards
• Subtle shadow and border to create depth
• Rounded corners (8px radius) for approachable feel
• Clear content hierarchy within cards
• Optional interactive states for actionable cards

Structure:

• Header: Optional title area with actions
• Media: Optional image, chart, or other visual content
• Content: Primary text content with consistent typography
• Actions: Optional footer with related actions

Variations:

• Basic Card: Simple container for content
• Media Card: Emphasizes visual content
• Action Card: Entire card is interactive
• List Card: Contains structured list items
• Status Card: Shows system or user status information

States (for Interactive Cards):

• Default: Standard elevation
• Hover: Slightly increased elevation
• Active/Pressed: Decreased elevation
• Focused: Blue outline
• Disabled: Reduced opacity

Lists & Tables

Lists and tables present structured information with clarity and sufficient spacing.

List Implementation:

• Generous item height (minimum 60px for interactive lists)
• Clear delineation between items (borders or spacing)
• Consistent structure across items
• Support for icons, avatars, and actions
• Visible selection states

List Variations:

• Simple List: Basic text items
• Detail List: Primary and secondary text
• Avatar List: Items with leading images
• Action List: Items with trailing actions
• Settings List: Option-style list items

Table Implementation:

• Horizontal scrolling on small screens
• Sticky headers for longer tables
• Zebra striping for better row distinction
• Generous cell padding for readability
• Aligned content based on data type

Table Variations:

• Basic Table: Simple data presentation
• Interactive Table: With selection and actions
• Expandable Table: Rows expand for details
• Sortable Table: Columns can be sorted
• Filterable Table: Data can be filtered

States:

• Default: Standard appearance
• Hover: Subtle background highlight
• Selected: Amber Glow background or indicator
• Focused: Blue outline with background highlight

Status Indicators

Status indicators provide clear visual feedback about system and content states.

Implementation Details:

• High color contrast for important statuses
• Supporting icons for color-blind accessibility
• Consistent positioning within components
• Text labels for clarity when space permits

Badge Indicators:

• Small, non-interactive indicators
• Used for counts, status, or categories
• Limited to small amounts of information
• Clear color coding for different meanings

Progress Indicators:

• Determinate: Clear percentage display
• Indeterminate: Animated for unknown duration
• Linear: For process steps or page loading
• Circular: For localized loading or progress
• Step Indicator: For multi-stage processes

Status Pills:

• Medium-sized indicators with text and color
• Used for more prominent status display
• Consistent color coding across the system
• Optional icons for enhanced clarity

States:

• Success: Sage Green (#7A9E7E)
• Warning: Amber Glow (#E8A44C)
• Error: Terracotta (#B85C38)
• Info: Dusty Blue (#758ECD)
• Neutral: Warm Gray (#C7C7C7)

Data Visualization

Data visualizations present information with clarity and simplicity, avoiding unnecessary complexity.

Implementation Details:

• Limited data points to prevent overwhelming
• Clear, large labels and values
• Generous spacing between elements
• Strong color contrast for data distinction
• Legends positioned close to relevant data

Chart Types:

• Bar Charts: For comparison between categories
• Line Charts: For trends over time
• Pie/Donut Charts: Limited to 5-7 segments maximum
• Progress Charts: For completion or goal visualization
• Simple Infographics: For key metrics and statistics

Interactive Elements:

• Large touch targets for interactive charts
• Clear tooltips with large, readable text
• Simple filtering options when necessary
• Zoom and pan controls for detailed exploration

Feedback Mechanisms

Alerts & Notifications

Alerts and notifications provide clear, timely feedback with appropriate urgency levels.

Implementation Details:

• Clear visual distinction between alert types
• Icons reinforcing the message type
• Concise, action-oriented text
• Dismissal controls when appropriate
• Appropriate positioning based on importance

Alert Types:

• Success: Confirmation of completed actions
• Warning: Important information requiring attention
• Error: Problems requiring resolution
• Info: Neutral information or tips

Notification Variants:

• Toast: Temporary, non-blocking notifications
• Banner: Page-level important messages
• Inline: Contextual feedback within forms
• Dialog: Critical information requiring acknowledgment

States:

• New: Full opacity, possibly with animation
• Persistent: Standard appearance
• Dismissing: Fade-out animation
• Actionable: With clearly visible action buttons

Loading States

Loading states provide clear feedback during system processes with appropriate detail level.

Implementation Details:

• Visible within 300ms of operation start
• Clear indication of process status
• Text description for longer operations
• Cancellation option when appropriate
• Fallback content for failed loading

Variants:

• Inline Loader: Within buttons or small areas
• Full Component Loader: Skeleton screens for content
• Page Loader: For initial page loading
• Process Loader: For multi-step operations
• Upload/Download Loader: With progress indication

States:

• Indeterminate: When duration is unknown
• Determinate: With clear progress indication
• Paused: When process is temporarily halted
• Failed: With retry options
• Almost Complete: Final processing indication

Modals & Dialogs

Modals and dialogs present focused interactions with clear purpose and simple decisions.

Implementation Details:

• Clear visual separation from background content
• Limited content focused on single purpose
• Explicit action buttons with clear labeling
• Dismissal through button, escape key, and outside click
• Proper focus management for keyboard users

Dialog Types:

• Confirmation: Verify user intent before action
• Form Dialog: Collect specific information
• Information Dialog: Present important information
• Success Dialog: Confirm completed complex actions
• Error Dialog: Explain problems requiring attention

States:

• Entering: Fade-in animation
• Active: Full opacity with background dimming
• Exiting: Fade-out animation
• Stacked: When multiple dialogs are needed (rare)

Responsive Behavior:

• Mobile: Full-screen or nearly full-screen
• Tablet: Centered with appropriate width
• Desktop: Centered with maximum width constraint

Tooltips & Contextual Help

Tooltips and contextual help provide additional information without overwhelming the interface.

Implementation Details:

• Triggered by hover/focus on desktop, tap on mobile
• Clear relationship to triggering element
• Brief, helpful content with simple language
• Appropriate positioning to avoid obscuring content
• Sufficient display time for reading completion

Variants:

• Simple Tooltip: Brief text explanation
• Rich Tooltip: With icons or simple formatting
• Help Tip: Question mark icon triggering information
• Feature Tip: Introduces new or important features
• Hint: Subtle guidance for form fields

States:

• Hidden: No visual presence
• Appearing: Fade-in animation
• Visible: Full opacity with appropriate positioning
• Disappearing: Fade-out animation

Component Patterns

State Variations

CompanionPulse components implement a consistent state system across all interactive elements to provide clear feedback and affordance.

Interactive States

Default State:

• Neutral appearance with clear affordance
• Sufficient contrast with surrounding elements
• Visual indication of interactivity where appropriate

Hover State:

• Subtle background color change (typically lighter Amber Glow)
• Slight elevation increase for elevated elements
• Cursor change to pointer
• No delay in visual feedback

Focus State:

• Prominent blue outline (2px)
• High contrast to ensure visibility
• Consistent appearance across all components
• Never hidden or disabled

Active/Pressed State:

• Darker color variation
• Slight inset effect or elevation decrease
• Brief animation for feedback (100-150ms)
• Returns to appropriate state after interaction

Disabled State:

• Reduced opacity (typically 40-50%)
• Removal of hover/focus effects
• Cursor change to not-allowed
• Tooltip explaining disabled reason when appropriate

Selection States

Unselected:

• Neutral appearance with clear selection affordance
• Sufficient contrast with selected items
• Visual stability when options change

Selected:

• Amber Glow color application
• Supporting icon (checkmark) when appropriate
• Maintained across view changes
• Clear feedback during selection change

Partially Selected:

• Visually distinct from both selected and unselected
• Used for indeterminate checkboxes or partial filters
• Clear explanation through supporting text when needed

Validation States

Neutral:

• Standard appearance before validation
• Clear affordance for required vs. optional

Valid:

• Subtle success indication (icon or border)
• Minimal visual change to avoid distraction
• Applied after field completion and validation

Invalid:

• Clear error indication (Terracotta color)
• Supporting icon (exclamation mark)
• Descriptive error message below the field
• Applied after field completion and validation

In Progress:

• Indication of ongoing validation
• Neutral appearance with activity indicator
• Brief timeout before showing to prevent flicker

Responsive Behavior

CompanionPulse components adapt thoughtfully across different screen sizes to maintain usability while optimizing for each context.

Adaptation Principles

Maintain Touch Targets:

• Preserve minimum 44px × 44px touch areas across all devices
• Never reduce interactive elements below minimum size
• Prioritize usability over density on smaller screens

Content Prioritization:

• Display essential content first
• Progressively reveal secondary content as space allows
• Use progressive disclosure patterns on smaller screens

Layout Transformation:

• Stack elements vertically on smaller screens
• Utilize horizontal arrangements on larger screens
• Maintain consistent content hierarchy regardless of layout

Breakpoint-Specific Behaviors

Mobile (320px - 767px):

• Single-column layouts
• Bottom navigation with icon and text
• Simplified headers with essential actions
• Full-width buttons and form elements
• Modal dialogs at nearly full-screen width

Tablet (768px - 1023px):

• Two-column layouts where appropriate
• Side navigation option with expanded labels
• Extended headers with additional actions
• Grouped form elements in multi-column layout
• Modal dialogs at approximately 70% screen width

Desktop (1024px and above):

• Multi-column layouts with flexible grids
• Persistent side navigation or top navigation bar
• Full-featured headers with all actions visible
• Optimized form layouts with logical grouping
• Modal dialogs at fixed maximum width (typically 600px)

Component-Specific Adaptations

Navigation:

• Bottom bar on mobile → Side or top navigation on larger screens
• Collapsed menus on mobile → Expanded options on desktop
• Back button prominence on mobile → Breadcrumb trails on desktop

Forms:

• Stacked fields on mobile → Multi-column layout on desktop
• Full-width buttons on mobile → Proportional width on desktop
• Simplified selection on mobile → Enhanced selection on desktop

Content Display:

• List view on mobile → Grid or table view on desktop
• Progressive disclosure on mobile → Expanded view on desktop
• Focused content on mobile → Contextual information on desktop

Composition Patterns

CompanionPulse's composition patterns guide how components combine to create cohesive, usable interfaces.

Layout Structures

Card-Based Layouts:

• Cards as primary content containers
• Consistent spacing between cards (24px standard)
• Logical grouping of related cards
• Progressive complexity within cards

Form Layouts:

• Clear visual sections for related fields
• Consistent label positioning (top-aligned)
• Logical tab order following visual flow
• Action buttons aligned to the reading direction (left-aligned)

List-Based Layouts:

• Consistent item structure throughout list
• Clear section headers for categorization
• Progressive disclosure for complex items
• Pagination or infinite scroll for long lists

Hierarchy Principles

Visual Weight Distribution:

• Primary actions with strongest visual presence
• Secondary actions with reduced prominence
• Tertiary actions as text links or icon buttons
• Consistent application across similar contexts

Content Organization:

• Most important information at the top
• Related items grouped visually
• Clear section boundaries with headers
• Progressive disclosure for complex information

Interactive Priorities:

• Primary path actions most prominent
• Destructive actions visually distinguished
• Cancellation always available but less prominent
• Help and support options consistently positioned

Common Patterns

Header Patterns:

• Page title with consistent positioning
• Key actions in the top-right area
• Back navigation when nested
• Consistent treatment across sections

Action Areas:

• Primary actions on the right or bottom
• Destructive actions separated from primary actions
• Cancellation always available
• Logical grouping of related actions

Information Hierarchy:

• Title → Subtitle → Body content
• Overview → Details → Related information
• Current status → Available actions
• Problem → Solution → Prevention

Accessibility Implementations

CompanionPulse components implement comprehensive accessibility features to ensure inclusive design for all users.

Keyboard Navigation

Focus Management:

• Logical tab order following visual layout
• Visible focus indicator never suppressed
• Focus trapped within modal dialogs
• Return focus to trigger after dialog dismissal

Keyboard Shortcuts:

• Essential functions accessible via keyboard
• Standard patterns (Esc to close, arrows to navigate)
• Documented shortcuts in help section
• No conflicts with assistive technology shortcuts

Interactive Elements:

• All interactive elements operable via keyboard
• Enter/Space to activate buttons and links
• Arrow keys for selection in dropdowns and lists
• Escape to cancel or close overlays

Screen Reader Support

Semantic Structure:

• Proper heading hierarchy (H1-H6)
• Landmark regions (header, main, navigation, etc.)
• List structures for related items
• Table structure for tabular data

ARIA Implementation:

• Appropriate ARIA roles for custom components
• State communication (expanded, selected, etc.)
• Live regions for dynamic content
• Dialog and overlay management

Text Alternatives:

• Alt text for all meaningful images
• Button and link text describing action
• Form labels properly associated with inputs
• Icon-only controls with accessible names

Visual Accessibility

Color and Contrast:

• Minimum 4.5:1 contrast ratio for all text
• No color as the sole means of conveying information
• Additional indicators beyond color (icons, patterns)
• Sufficient contrast for boundaries and separators

Typography Optimization:

• Minimum 14px text size throughout interface
• Adjustable text size without breaking layouts
• Sufficient line spacing (1.5x) for readability
• Left-aligned text for natural reading flow

Motion Sensitivity:

• Essential-only animations
• Respecting reduced motion preferences
• Brief durations for necessary animations
• No flashing content that could trigger seizures

Implementation Guide

Code Architecture

The CompanionPulse component system follows a structured architecture to ensure maintainability, consistency, and performance.

Component Structure

Atomic Design Methodology:

• Atoms: Basic building blocks (buttons, inputs, icons)
• Molecules: Simple component combinations (form fields, search bars)
• Organisms: Complex component combinations (navigation bars, forms)
• Templates: Page-level component arrangements
• Pages: Specific implementations of templates

Component Composition Model:

• Composition over inheritance
• Prop-based customization
• Render prop pattern for complex customization
• Context providers for theme and shared state

Styling Approach

CSS Methodology:

• CSS-in-JS with styled-components
• Theme provider for design token access
• Global styles for base elements
• Component-specific styles with proper scoping

Style Organization:

• Separation of structural and visual styles
• Responsive styles included within components
• Animation definitions in separate files
• Utility styles for common patterns

State Management

Component State:

• Local state for component-specific concerns
• Prop-based state for controlled components
• Context API for shared component state
• Reducers for complex state logic

Accessibility State:

• ARIA states managed consistently
• Focus state handling
• Expanded/collapsed state tracking
• Selected/checked state management

Framework Integration

The CompanionPulse component library is designed for implementation in React, with considerations for integration with other frameworks as needed.

React Implementation

Component API Design:

• Consistent prop naming conventions
• Optional render props for customization
• Forwarded refs for DOM access
• Event handler props with consistent naming

Hooks Usage:

• Custom hooks for shared behavior
• useState for simple state management
• useReducer for complex state logic
• useContext for theme and shared configuration
• useRef for DOM references and instance variables

React Patterns:

• Controlled and uncontrolled component options
• Compound components for complex patterns
• Higher-order components for cross-cutting concerns
• Context providers for theme and configuration

Integration with Other Frameworks

Framework-Agnostic Core:

• Core styles and logic separated from framework specifics
• Design tokens available as plain CSS/JS
• Documentation for implementation in other frameworks

Web Components Option:

• Selected components available as web components
• Custom elements for framework-agnostic use
• Shadow DOM for style encapsulation
• Documented API for cross-framework usage

Performance Optimization

CompanionPulse components are optimized for performance to ensure a smooth experience for all users, especially on lower-powered devices that seniors might use.

Rendering Optimization

Code Splitting:

• Component-level code splitting
• Dynamic imports for large components
• Route-based splitting for page components
• Shared chunks for common dependencies

Lazy Loading:

• Defer loading of off-screen components
• Image lazy loading with placeholders
• On-demand loading of heavy components
• Prioritized loading of critical components

Render Efficiency:

• Memoization of expensive computations
• Pure components to prevent unnecessary renders
• Virtual list rendering for long lists
• Windowing techniques for large datasets

Asset Optimization

Image Optimization:

• Appropriate image formats (WebP with fallbacks)
• Responsive images with srcset
• Optimized SVGs for icons
• Proper image compression

Font Loading:

• Font display swap to prevent invisible text
• Subset fonts to essential characters
• Self-hosted fonts for performance control
• Font loading API usage

CSS Optimization:

• Critical CSS extraction
• Elimination of unused styles
• Minification and compression
• Efficient selector specificity

Documentation System

CompanionPulse's component documentation provides comprehensive guidance for designers and developers to ensure consistent implementation.

Component Documentation Structure

Component Overview:

• Purpose and use cases
• Visual example
• Key features
• Accessibility considerations
• Related components

API Reference:

• Prop documentation with types and defaults
• Event handlers and return values
• Composition options
• Ref forwarding details
• Theming options

Usage Examples:

• Basic implementation
• Common variations
• Responsive behavior
• Accessibility implementation
• Integration examples

Interactive Documentation

Component Playground:

• Live editing of component props
• Real-time preview
• Code snippet generation
• Responsive testing tools
• Accessibility checker

Pattern Examples:

• Complete pattern implementations
• Copy-paste ready code
• Best practice demonstrations
• Anti-pattern warnings
• Responsive behavior demonstrations

Decision Guidance

Component Selection Guides:

• Decision trees for similar components
• Use case recommendations
• Comparison tables
• Performance considerations
• Accessibility implications

Implementation Checklists:

• Required props and configuration
• Accessibility requirements
• Responsive behavior verification
• Performance considerations
• Testing recommendations

Conclusion

The CompanionPulse Component Library provides a comprehensive system of design elements and patterns optimized for senior users while maintaining a contemporary feel that appeals to their adult children. By balancing warm sophistication with accessible technology, the library enables the creation of intuitive, engaging, and trustworthy interfaces that combat elder isolation through meaningful digital connection.

This component system is designed with special attention to the unique needs of aging users, including enhanced readability, generous touch targets, clear navigation, and thoughtful feedback mechanisms. At the same time, it maintains a sophisticated aesthetic that avoids the patronizing or clinical appearance common in products for seniors.

By implementing this component library consistently across all touchpoints, CompanionPulse will deliver a cohesive, accessible, and emotionally resonant experience that empowers seniors to engage confidently with technology that facilitates genuine human connection.