# Pricing Page Tooltips Implementation Guide

**Last Updated:** 2026-03-03

## Overview

This guide documents the tooltip implementation for pricing page features on `/preise`. Tooltips replace inline feature descriptions to reduce visual clutter while maintaining accessibility and conversion optimization.

## Architecture

### Component Structure

**Component:** `v2/components/pricing-feature-tooltip.php`
- Accepts: `$feature` (array), `$plan_key` (string), `$index` (int)
- Outputs: Feature title with info icon and tooltip content
- Includes: ARIA attributes for accessibility

**CSS:** `v2/css/pricing-tooltips.css`
- Styles for tooltip trigger, content, and animations
- Responsive breakpoints for mobile/tablet/desktop
- WCAG 2.2 compliant focus states

**JavaScript:** `v2/js/pricing-tooltips.js`
- Hover handlers with delay (300ms)
- Keyboard support (Tab, Enter/Space, Escape)
- Viewport boundary detection for positioning
- Mobile touch handlers (tap to show/hide)

### Integration

**Pricing Card:** `v2/sections/pricing-card-modern.php`
- Uses tooltip component for all feature lists (Starter, Plus, Pro)
- Maintains existing feature structure (checkmarks, platform icons)

**Pricing Page (live `/preise`):** `v2/pages/static_pricing_new.php` (legacy: `static_pricing.php`)
- Includes CSS: `<link rel="stylesheet" href="/v2/css/pricing-tooltips.css">`
- Includes JS: `<script src="/v2/js/pricing-tooltips.js"></script>`

## Usage

### Basic Usage

```php
<?php
$feature = [
    'text' => 'Feature Name',
    'description' => 'Feature description text...',
    'icon' => 'check'
];
$plan_key = 'starter';
$index = 0;
include __DIR__ . '/../components/pricing-feature-tooltip.php';
?>
```

### With Platform Icons

```php
<?php
$feature = [
    'text' => 'Mitarbeiter App',
    'description' => 'Dein Team hat alle wichtigen Infos immer dabei...',
    'icon' => 'check',
    'show_platform_icons' => true
];
$plan_key = 'starter';
$index = 1;
include __DIR__ . '/../components/pricing-feature-tooltip.php';
?>
```

## Accessibility

### WCAG 2.2 Compliance

**1.4.13 Content on Hover or Focus (Level AA):**
- ✅ **Dismissible**: Escape key dismisses tooltip
- ✅ **Hoverable**: Tooltip remains visible when pointer moves over it
- ✅ **Persistent**: Tooltip stays visible until dismissed or focus removed

### ARIA Implementation

- `role="tooltip"` on tooltip content
- `aria-describedby` links trigger to tooltip
- `aria-label` on trigger button ("Mehr Informationen zu [Feature]")
- `aria-expanded` state management
- `aria-hidden` for show/hide state

### Keyboard Navigation

- **Tab**: Navigate to info icons
- **Enter/Space**: Toggle tooltip (mobile/keyboard)
- **Escape**: Dismiss tooltip
- **Focus**: Tooltip appears on focus (desktop)

### Screen Reader Support

- Tooltip content announced via `aria-describedby`
- Screen reader only text: "Mehr Informationen zu [Feature]"
- Proper semantic structure with `role="tooltip"`

## Design Tokens

### Colors
- **Primary**: `#4D8EF3` (Ordio blue)
- **Hover**: `#3B82F6` (darker blue)
- **Icon Default**: `#CBD5E0` (gray-300)
- **Icon Hover**: `#4D8EF3` (Ordio blue)
- **Tooltip Background**: `#FFFFFF` (white)
- **Tooltip Text**: `#374151` (gray-700)

### Typography
- **Tooltip Text**: `0.875rem` (14px)
- **Line Height**: `1.5`
- **Max Width**: `320px` (desktop), `100vw - 2rem` (mobile)

### Spacing
- **Icon Size**: `16px` (desktop), `20px` (mobile)
- **Tooltip Gap**: `8px` above trigger
- **Padding**: `12px 16px` (desktop), `14px 18px` (mobile)

### Animations
- **Duration**: `300ms`
- **Easing**: `cubic-bezier(0.4, 0, 0.2, 1)`
- **Hover Delay**: `300ms` (prevents accidental triggers)

## Responsive Behavior

### Desktop (> 640px)
- Hover to show tooltip
- Tooltip positioned above trigger, centered
- Auto-adjusts for viewport edges

### Mobile (≤ 640px)
- Tap to toggle tooltip
- Full-width tooltip (`100vw - 2rem`)
- Larger touch targets (44px minimum)
- Tap outside to dismiss

### Tablet (641px - 1024px)
- Same as desktop behavior
- Max-width: `280px`

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (macOS and iOS)
- Mobile browsers (iOS Safari, Chrome Android)

## Performance

- **CLS**: < 0.1 (no layout shift)
- **FID**: < 100ms (fast interaction)
- **GPU Acceleration**: CSS transforms for smooth animations
- **Debouncing**: Prevents rapid hover triggers

## Testing Checklist

### Functional Testing
- [ ] Hover over info icon → tooltip appears
- [ ] Move mouse to tooltip → tooltip stays visible
- [ ] Move mouse away → tooltip disappears
- [ ] Click info icon → tooltip toggles (mobile)
- [ ] Press Escape → tooltip dismisses
- [ ] Tab to info icon → tooltip appears (keyboard)
- [ ] Press Enter/Space → tooltip toggles

### Accessibility Testing
- [ ] Keyboard navigation works
- [ ] Screen reader announces tooltip content
- [ ] Color contrast meets WCAG AA (4.5:1)
- [ ] Focus indicators visible
- [ ] No keyboard traps

### Responsive Testing
- [ ] Mobile (320px, 375px, 414px)
- [ ] Tablet (768px, 1024px)
- [ ] Desktop (1280px, 1920px)
- [ ] Tooltip positioning correct at all breakpoints

### Edge Cases
- [ ] Tooltip near viewport edges (auto-reposition)
- [ ] Multiple tooltips (only one visible)
- [ ] Long descriptions (scrollable if needed)
- [ ] Rapid hover movements (debounced)

## Troubleshooting

### Tooltip Not Appearing
1. Check CSS file is loaded: `/v2/css/pricing-tooltips.css`
2. Check JS file is loaded: `/v2/js/pricing-tooltips.js`
3. Verify component includes correct IDs
4. Check browser console for JavaScript errors

### Positioning Issues
1. Verify `.pricing-tooltip-container` has `position: relative`
2. Check tooltip CSS positioning rules
3. Test viewport boundary detection in JS

### Accessibility Issues
1. Verify ARIA attributes are present
2. Test with keyboard only (no mouse)
3. Test with screen reader (NVDA, JAWS, VoiceOver)
4. Check color contrast ratios

## Related Documentation

- `.cursor/rules/pricing-tooltips.mdc` - Cursor rule for tooltip patterns
- `.cursor/rules/pricing-page-copy.mdc` - Pricing page copy guidelines
- `docs/content/pages/static-pages/pricing-documentation.md` - Pricing page docs
- `v2/sections/pricing-data.php` - Feature data structure

## Maintenance

### Adding New Features
1. Add feature to `v2/sections/pricing-data.php`
2. Include description in feature array
3. Tooltip will automatically appear if description exists

### Modifying Tooltip Styles
1. Edit `v2/css/pricing-tooltips.css`
2. Run `npm run minify` to regenerate minified files
3. Test across all breakpoints

### Updating JavaScript Behavior
1. Edit `v2/js/pricing-tooltips.js`
2. Test keyboard and touch interactions
3. Verify accessibility compliance