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
• Language Switching
• CV Customization
• PDF Export
• Navigation
• 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:

<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:

.zoom-wrapper {
  zoom: 1.25; /* 125% zoom example */
}

Inverse Zoom for Fixed Elements:

.fixed-button {
  zoom: 0.8; /* 1/1.25 = 0.8 to counteract 125% */
}

Horizontal Overflow:

body {
  overflow-x: auto; /* Allow horizontal scroll */
}

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

JavaScript API

Key Functions:

// 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