cv-site/doc/06-USER-GUIDE.md

# User Guide - CV Website Features

This guide provides comprehensive documentation for all interactive features of the CV website.

## Table of Contents

- [Zoom Feature](#zoom-feature)
- [Language Switching](#language-switching)
- [CV Customization](#cv-customization)
- [PDF Export](#pdf-export)
- [Navigation](#navigation)
- [Accessibility](#accessibility)

---

## Zoom Feature

The CV includes an intelligent zoom control for comfortable viewing at any size.

### Overview

The zoom feature allows you to adjust the CV display size from 25% (bird's-eye view) to 175% (enhanced readability) while keeping navigation controls at a consistent, accessible size.

### How to Use

#### Visual Control

The zoom control appears as a draggable widget near the bottom of the screen (desktop only).

**Components:**
- **Slider**: Drag anywhere between 25% and 175% zoom
- **Min/Max Labels**: Show the range (25% and 175%)
- **Reset Button**: Circular button showing current zoom percentage
- **Close Button**: Small X button (top-right corner) to hide the control

**Interaction:**
1. **Adjust Zoom**: Click and drag the slider to your preferred zoom level
2. **Reset to Default**: Click the circular button (shows current %) to return to 100%
3. **Reposition Control**: Click and drag the control itself (not the slider/buttons) to move it anywhere on screen
4. **Hide Control**: Click the X button to hide the control
5. **Show Control**: Access from hamburger menu (☰) → Select "Zoom"

#### Keyboard Shortcuts

The zoom feature supports standard browser-style keyboard shortcuts:

| Shortcut | Action | Increment |
|----------|--------|-----------|
| `Ctrl/Cmd + Plus (+)` | Zoom In | +10% |
| `Ctrl/Cmd + Minus (-)` | Zoom Out | -10% |
| `Ctrl/Cmd + 0` | Reset to Default | 100% |

**Note**: These shortcuts work regardless of whether the zoom control is visible.

#### Menu Access

1. Click the **hamburger menu (☰)** in the top-left corner
2. Hover or click **"Zoom"** menu item
3. The zoom control will appear
4. Use the control as described above

### What Zooms vs. What Stays Fixed

#### Elements That Zoom (Content)

The following elements scale according to the zoom level:
- All CV content (text, headings, paragraphs)
- Images and icons within the CV
- CV paper and layout structure
- Section spacing and margins
- All typography and line heights

**Behavior at >100% zoom:**
- Content extends beyond viewport width
- Horizontal scrollbar appears
- Natural overflow allows full-size viewing
- Matches browser zoom behavior

#### Elements That Stay Fixed (UI Controls)

The following elements maintain consistent size regardless of zoom:
- **Action Bar**: Top black bar with all buttons
- **Hamburger Menu**: Navigation menu and all menu items
- **Zoom Control**: The zoom widget itself
- **Back-to-Top Button**: Bottom-right corner button
- **Info Button**: Information modal trigger
- **Footer**: Bottom footer remains at normal size

**Why fixed UI?**
- **Accessibility**: Controls stay at standard touch target size (44x44px)
- **Usability**: Buttons never become too large or too small
- **Consistency**: Predictable interaction at any zoom level
- **Navigation**: Always accessible regardless of content zoom state

### Design Rationale

#### Zoom Range: 25-175%

**25% - Bird's Eye View:**
- See entire CV structure at once
- Great for navigation and overview
- Check layout balance and spacing
- Quick section location
- Ideal for presentations or large screens

**100% - Optimal Reading:**
- Default and recommended setting
- Calibrated for comfortable reading
- Optimal font rendering and line length
- Balanced for most screen sizes
- Professional presentation view

**175% - Enhanced Readability:**
- Enhanced readability for detailed review
- Accessibility support for vision needs
- Close inspection of specific content
- Better for small or high-DPI screens
- Reduced eye strain for long reading sessions

#### Fixed UI Elements (Inverse Zoom Technique)

**Technical Implementation:**
Fixed buttons use `zoom: 1/zoomLevel` to counteract content zoom.

**Example:**
- Content zoom: 150% (`zoom: 1.5`)
- Button inverse: 67% (`zoom: 0.67`)
- Result: Button stays at original size

**Benefits:**
- Buttons remain at accessibility-compliant size (44x44px)
- Prevents unusably large buttons at 175% zoom
- Prevents unusably small buttons at 25% zoom
- Maintains muscle memory for button positions
- Consistent visual hierarchy

#### Horizontal Scroll Behavior

**Why horizontal scroll appears:**
- Content naturally extends beyond viewport at >100% zoom
- Allows viewing full-size content without compression
- Matches expected browser zoom behavior
- Prevents text reflow issues
- Maintains layout integrity

**User Experience:**
- Smooth scrolling on all devices
- Keyboard navigation supported (arrow keys)
- Mouse wheel scrolling (shift + wheel)
- Trackpad gestures work naturally
- Does not interfere with vertical scrolling

### Optimal Viewing Tips

#### Quick Overview (25-75% Zoom)

**Best For:**
- Getting familiar with CV structure
- Locating specific sections quickly
- Checking overall layout balance
- Comparing multiple sections
- Presentation mode on large screens

**Recommended Settings:**
- Zoom: 50-75%
- View: Full screen
- Navigation: Use section links

#### Comfortable Reading (100% Zoom)

**Best For:**
- Primary reading experience
- Professional presentation
- Standard review and evaluation
- Sharing with others
- PDF export preparation

**Recommended Settings:**
- Zoom: 100% (default)
- View: Full screen or windowed
- Font rendering: Optimal

#### Detailed Review (125-175% Zoom)

**Best For:**
- Enhanced readability needs
- Close inspection of content
- Accessibility requirements
- Small screen viewing
- Detailed proofreading

**Recommended Settings:**
- Zoom: 125-150%
- Use horizontal scroll to navigate
- Focus on one section at a time
- Combine with section navigation

### Persistence and Storage

**Automatic Save:**
- Your zoom level is automatically saved to browser's localStorage
- Returns to your preferred zoom when you revisit
- No manual save required

**Per-Device Storage:**
- Each device/browser remembers its own zoom preference
- Desktop and mobile can have different settings
- Private/Incognito mode does not persist zoom

**Storage Keys:**
- `cv-zoom`: Current zoom percentage (25-175)
- `cv-zoom-position`: Custom position if dragged
- `cv-zoom-visible`: Whether control is shown/hidden

**Clear Storage:**
To reset zoom preferences:
1. Browser DevTools → Application → Local Storage
2. Find keys starting with `cv-zoom`
3. Delete to reset to defaults

### Mobile Behavior

**Automatic Handling:**
- Zoom control is **hidden on mobile devices** (screens ≤768px)
- Mobile browsers have native pinch-to-zoom
- Native zoom works better on small screens
- Touch gestures are more intuitive on mobile

**Why hidden on mobile?**
- Limited screen space for controls
- Native pinch-to-zoom is superior
- Touch targets would be too small
- Desktop-oriented feature
- Mobile viewport already optimized

**Mobile Alternatives:**
- Use browser's native pinch-to-zoom
- Double-tap to zoom sections
- Use browser zoom in/out buttons

### Accessibility Features

#### Keyboard Support

**Full Keyboard Navigation:**
- `Tab`: Navigate to zoom control
- `Space`/`Enter`: Activate reset button
- `Arrow Keys`: Adjust slider (when focused)
- `Ctrl/Cmd + Plus/Minus/0`: Global shortcuts
- `Esc`: Close menu/modals

#### Screen Reader Support

**ARIA Attributes:**
```html
<input
  type="range"
  aria-label="Adjust CV zoom level"
  aria-valuemin="25"
  aria-valuemax="175"
  aria-valuenow="100"
  aria-valuetext="100%"
>
```

**Announcements:**
- Current zoom level announced on change
- Reset button announces "Reset zoom to 100%"
- Slider range clearly communicated
- Interactive elements properly labeled

#### Visual Accessibility

**High Contrast:**
- Slider track: Clear contrast ratio
- Button borders: Visible in all modes
- Text labels: White on semi-transparent background
- Focus indicators: 2px white outline

**Focus Indicators:**
- All interactive elements have visible focus
- Keyboard navigation clearly indicated
- Tab order follows logical flow

**Touch Targets:**
- All buttons meet 44x44px minimum
- Slider thumb: 18px diameter
- Close button: 24px diameter
- Reset button: 44px diameter

### Troubleshooting

#### Zoom Not Working

**Symptoms:**
- Slider moves but nothing happens
- Keyboard shortcuts don't work
- Page doesn't zoom

**Solutions:**
1. Check browser console for JavaScript errors
2. Ensure JavaScript is enabled
3. Try hard refresh: `Ctrl/Cmd + Shift + R`
4. Clear browser cache and reload
5. Check if browser zoom is interfering (reset to 100%)

#### Zoom Control Not Visible

**Symptoms:**
- Can't find zoom control on page
- Control disappeared

**Solutions:**
1. Check if you're on mobile (control hidden <768px)
2. Open hamburger menu → Click "Zoom" to show
3. Check localStorage: `cv-zoom-visible` should be `true`
4. Control may be positioned off-screen (drag from edge)
5. Refresh page to reset position

#### Zoom Resets on Refresh

**Symptoms:**
- Zoom goes back to 100% every time
- Preference not saving

**Solutions:**
1. Check if localStorage is enabled in browser
2. Ensure you're not in Private/Incognito mode
3. Check browser privacy settings
4. Try a different browser to isolate issue

#### Horizontal Scroll Issues

**Symptoms:**
- Can't scroll horizontally when zoomed
- Content cut off at edges

**Solutions:**
1. Ensure body overflow-x is set to auto
2. Try Shift + Mouse Wheel for horizontal scroll
3. Use keyboard arrow keys
4. Check if browser extensions are interfering

#### Fixed Buttons Look Wrong

**Symptoms:**
- Buttons too large or too small
- Buttons scaling with content

**Solutions:**
1. Check if CSS zoom property is supported
2. Verify browser compatibility (all modern browsers)
3. Check for conflicting CSS from extensions
4. Try disabling browser themes/extensions

### Technical Details

#### Implementation

**CSS Zoom Property:**
```css
.zoom-wrapper {
  zoom: 1.25; /* 125% zoom example */
}
```

**Inverse Zoom for Fixed Elements:**
```css
.fixed-button {
  zoom: 0.8; /* 1/1.25 = 0.8 to counteract 125% */
}
```

**Horizontal Overflow:**
```css
body {
  overflow-x: auto; /* Allow horizontal scroll */
}

.zoom-wrapper {
  min-width: 100vw; /* When zoomed > 100% */
}
```

#### JavaScript API

**Key Functions:**
```javascript
// Apply zoom level
applyZoom(zoomValue, saveToStorage)

// Increment/decrement zoom
incrementZoom(step)

// Update display
updateZoomDisplay(zoomValue)

// Check mobile view
isMobileView()
```

**Event Listeners:**
- `input`: Real-time slider updates
- `click`: Reset button handler
- `keydown`: Global keyboard shortcuts
- `resize`: Handle viewport changes

#### Browser Compatibility

**Supported Browsers:**
- Chrome/Edge 90+ (Full support)
- Firefox 90+ (Full support)
- Safari 13+ (Full support)
- Opera 76+ (Full support)

**CSS Zoom Support:**
- Webkit/Blink: Native support
- Firefox: Supported since Firefox 90
- All modern browsers support CSS zoom

**Fallback:**
- No fallback needed (all modern browsers)
- For older browsers, zoom would simply not work
- Page remains fully functional without zoom

---

## Language Switching

The CV supports instant language switching between English and Spanish without page reload.

### How to Use

**From Action Bar:**
1. Click language flag icon in top bar
2. Select English or Spanish
3. Content swaps instantly via HTMX

**From Menu:**
1. Open hamburger menu (☰)
2. Hover over "Language" item
3. Select preferred language

**Via URL:**
- English: `?lang=en`
- Spanish: `?lang=es`

**Persistence:**
- Language preference saved to localStorage
- Returns to your preferred language on next visit
- Works across all pages

---

## CV Customization

### CV Length Toggle

**Short Version:**
- Concise overview
- Key highlights only
- 1-2 pages when printed
- Quick review

**Long Version:**
- Complete details
- Full project descriptions
- Comprehensive experience
- In-depth review

**Toggle:**
1. Action bar toggle switch
2. Hamburger menu → "Long Version"
3. Preference persisted to localStorage

### Logo Visibility

**Show Logos:**
- Company and technology logos visible
- Visual brand recognition
- More engaging presentation

**Hide Logos:**
- Text-only presentation
- Cleaner, more formal look
- Better for print

**Toggle:**
1. Action bar toggle switch
2. Hamburger menu → "Show Logos"
3. Preference persisted to localStorage

### Theme Switching

**Default Theme:**
- Gray background with paper texture
- Sidebars with contact info
- Header and footer visible
- Full visual design

**Clean Theme:**
- White background
- No sidebars
- Minimal chrome
- Print-optimized

**Toggle:**
1. Action bar toggle switch
2. Hamburger menu → "Clean Theme"
3. Preference persisted to localStorage

---

## PDF Export

### Server-Side Generation

**Recommended Method:**
1. Click "Download as PDF" in action bar
2. Server generates PDF using headless Chrome
3. File downloads automatically
4. Filename: `CV-Juan-Andres-Moreno-Rubio-{lang}.pdf`

**Advantages:**
- Consistent rendering across platforms
- Perfect font rendering
- No browser compatibility issues
- Professional quality output

### Browser Print

**Alternative Method:**
1. Click "Print Friendly" in action bar
2. Browser print dialog opens
3. Select "Save as PDF"
4. Configure print settings

**Settings:**
- Switches to clean theme
- Forces short version
- Removes interactive elements
- Optimized for printing

---

## Navigation

### Section Navigation

**Table of Contents:**
- Auto-generated from CV sections
- Click any section to scroll smoothly
- Header stays visible during navigation

**Hamburger Menu:**
- Mobile-friendly navigation
- Hover to open on desktop
- Click to open on mobile
- Automatic closing after selection

**Back to Top:**
- Appears after scrolling 300px
- Smooth scroll to top
- Always accessible
- Bottom-right position

### Collapsible Sections

**Details/Summary:**
- Click section headers to expand/collapse
- Mobile accordion style
- Desktop always expanded

**Expand/Collapse All:**
- Action bar buttons
- Hamburger menu options
- Affects all collapsible sections

---

## Accessibility

### Keyboard Navigation

**Tab Order:**
- Logical flow through all interactive elements
- Visible focus indicators
- Skip links for main content
- All features accessible via keyboard

### Screen Readers

**ARIA Labels:**
- All interactive elements labeled
- Form controls properly described
- Dynamic content announcements
- Semantic HTML structure

### Visual Accessibility

**Color Contrast:**
- WCAG AA compliant
- High contrast mode support
- Focus indicators visible

**Font Scaling:**
- Responsive typography
- Works with browser zoom
- Readable at all sizes

**Motion Preferences:**
- Respects prefers-reduced-motion
- Smooth scrolling optional
- Animations can be disabled

### Touch Targets

**Minimum Sizes:**
- All buttons: 44x44px
- Touch-friendly spacing
- No overlapping targets
- Adequate margins

---

## Support

For issues, questions, or feedback:
- GitHub Issues: https://github.com/txemac/cv/issues
- Documentation: See /doc folder
- Live Demo: https://juan.andres.morenorub.io/

**Last Updated:** 2025-11-12