cv-site/doc/HTMX-PRODUCTION-RECOMMENDATIONS.md

HTMX CV Site - Production Readiness Review

Executive Summary

Current Status: 85% Production Ready Performance: Exceptional (0.8-1ms response times, well below 85-120ms target) Core Implementation: Solid HTMX patterns, clean architecture Priority Focus: Accessibility, Error Handling, SEO, Security

---

1. HTMX Implementation Analysis

✅ Strengths

1. Excellent Performance

   • Initial page load: 0.8ms
   • HTMX partial swap: 1.0ms
   • Well below recommended 85-120ms target
   • Go backend provides exceptional speed

2. Clean HTMX Patterns

   • Proper use of hx-get for language switching
   • Targeted swaps with hx-target="#cv-content"
   • Loading indicators with hx-indicator
   • Locality of behavior maintained

3. Good Progressive Enhancement

   • Functional without JavaScript (direct URL access works)
   • Links are actual HTTP GET requests
   • No JavaScript frameworks required

⚠️ Critical Issues to Address

1.1 Missing Browser History Management

Problem: Language changes don't update browser URL Impact: Back button doesn't work, bookmarks don't preserve language Priority: HIGH

Solution:

<button
    class="lang-btn {{if eq .Lang "en"}}active{{end}}"
    hx-get="/cv?lang=en"
    hx-target="#cv-content"
    hx-swap="innerHTML"
    hx-push-url="/?lang=en"  <!-- ADD THIS -->
    hx-indicator="#loading">
    🇬🇧 English
</button>

1.2 No Error Handling

Problem: Failed HTMX requests show no feedback to users Impact: Poor UX when network fails or server errors Priority: HIGH

Solution: Add global error handler

document.body.addEventListener('htmx:responseError', function(evt) {
    // Show user-friendly error message
    showErrorToast('Failed to load content. Please try again.');
});

document.body.addEventListener('htmx:timeout', function(evt) {
    showErrorToast('Request timed out. Please check your connection.');
});

1.3 Missing ARIA Live Regions

Problem: Screen readers don't announce dynamic content changes Impact: Accessibility violation (WCAG 2.1 Level A) Priority: HIGH

Solution:

<main id="cv-content"
      class="cv-paper"
      role="main"
      aria-live="polite"
      aria-atomic="false">  <!-- ADD THESE -->
    {{template "cv-content.html" .}}
</main>

1.4 No Transition Effects

Problem: Instant swaps feel jarring Impact: Poor UX, no visual feedback during changes Priority: MEDIUM

Solution:

hx-swap="innerHTML swap:200ms settle:200ms"

CSS:

.cv-paper {
    transition: opacity 200ms;
}

.cv-paper.htmx-swapping {
    opacity: 0;
}

1.5 No Request Timeout Configuration

Problem: Requests wait indefinitely on slow connections Impact: Hanging UI, poor UX Priority: MEDIUM

Solution:

<meta name="htmx-config" content='{"timeout":5000}'>

1.6 Language Preference Not Persisted

Problem: Users must reselect language on each visit Impact: Inconvenience for repeat visitors Priority: LOW

Solution:

// Save preference on language change
document.body.addEventListener('htmx:afterRequest', function(evt) {
    const url = new URL(evt.detail.xhr.responseURL);
    const lang = url.searchParams.get('lang');
    if (lang) localStorage.setItem('cv-lang', lang);
});

// Load saved preference on page load
window.addEventListener('DOMContentLoaded', function() {
    const savedLang = localStorage.getItem('cv-lang');
    if (savedLang) {
        // Trigger HTMX request for saved language
    }
});

---

2. Accessibility (WCAG 2.1 Level AA)

⚠️ Critical Issues

2.1 Missing ARIA Attributes

Current State: Minimal ARIA usage Required for WCAG 2.1:

<!-- Language toggle -->
<div class="language-toggle" role="group" aria-label="Language selection">
    <button
        class="lang-btn"
        aria-label="Switch to English"
        aria-pressed="true|false"
        aria-busy="true|false">  <!-- During loading -->
        🇬🇧 English
    </button>
</div>

<!-- Loading indicator -->
<span id="loading"
      class="htmx-indicator"
      role="status"
      aria-live="polite"
      aria-label="Loading">
    <span class="loader" aria-hidden="true"></span>
    <span class="sr-only">Loading...</span>  <!-- Screen reader text -->
</span>

<!-- Error messages -->
<div role="alert" aria-live="assertive">
    <!-- Error content -->
</div>

2.2 Missing Focus Management

Problem: Focus doesn't move to updated content Solution: Add focus management after swap

document.body.addEventListener('htmx:afterSwap', function(evt) {
    if (evt.detail.target.id === 'cv-content') {
        // Focus on main heading
        const heading = evt.detail.target.querySelector('h1');
        if (heading) heading.focus();
    }
});

2.3 Insufficient Keyboard Navigation

Recommendations:

• Add keyboard shortcuts (Ctrl+E for English, Ctrl+S for Spanish)
• Ensure all interactive elements are keyboard accessible
• Add skip-to-content link

<a href="#cv-content" class="skip-link">Skip to content</a>

.skip-link {
    position: absolute;
    top: -40px;
    left: 0;
    background: var(--accent-blue);
    color: white;
    padding: 8px;
    z-index: 100;
}

.skip-link:focus {
    top: 0;
}

2.4 Color Contrast Issues

Check Required:

• .text-light (#6a6a6a) on white might not meet WCAG AA (4.5:1 ratio)
• Test all color combinations with contrast checker

Tool: https://webaim.org/resources/contrastchecker/

---

3. SEO Optimization

⚠️ Missing SEO Elements

3.1 Missing Meta Tags

Add to <head>:

<!-- Essential SEO -->
<meta name="author" content="{{.CV.Personal.Name}}">
<meta name="robots" content="index, follow">
<link rel="canonical" href="{{.CV.Personal.Website}}">

<!-- Open Graph (Social Media) -->
<meta property="og:title" content="{{.CV.Personal.Name}} - Curriculum Vitae">
<meta property="og:description" content="{{.CV.Personal.Title}}">
<meta property="og:type" content="profile">
<meta property="og:url" content="{{.CV.Personal.Website}}">
<meta property="og:image" content="{{.CV.Personal.Website}}/static/og-image.jpg">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="{{.CV.Personal.Name}}">
<meta name="twitter:description" content="{{.CV.Personal.Title}}">

<!-- Professional Profile -->
<meta property="profile:first_name" content="Juan Andrés">
<meta property="profile:last_name" content="Moreno Rubio">
<meta property="profile:username" content="txeo">

3.2 Missing Structured Data (JSON-LD)

Add before </head>:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "{{.CV.Personal.Name}}",
  "jobTitle": "{{.CV.Personal.Title}}",
  "url": "{{.CV.Personal.Website}}",
  "sameAs": [
    "{{.CV.Personal.LinkedIn}}",
    "{{.CV.Personal.GitHub}}"
  ],
  "address": {
    "@type": "PostalAddress",
    "addressLocality": "{{.CV.Personal.Location}}"
  },
  "email": "{{.CV.Personal.Email}}",
  "telephone": "{{.CV.Personal.Phone}}"
}
</script>

3.3 Missing Sitemap

Create /sitemap.xml:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://yoursite.com/?lang=en</loc>
    <lastmod>2025-10-18</lastmod>
    <changefreq>monthly</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://yoursite.com/?lang=es</loc>
    <lastmod>2025-10-18</lastmod>
    <changefreq>monthly</changefreq>
    <priority>1.0</priority>
  </url>
</urlset>

3.4 Missing robots.txt

Create /static/robots.txt:

User-agent: *
Allow: /
Sitemap: https://yoursite.com/sitemap.xml

---

4. Security Enhancements

⚠️ Missing Security Headers

4.1 Add Security Middleware in Go

Create middleware/security.go:

func SecurityHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Prevent clickjacking
        w.Header().Set("X-Frame-Options", "DENY")
        w.Header().Set("X-Content-Type-Options", "nosniff")
        w.Header().Set("X-XSS-Protection", "1; mode=block")

        // Content Security Policy
        w.Header().Set("Content-Security-Policy",
            "default-src 'self'; "+
            "script-src 'self' 'unsafe-inline' https://unpkg.com; "+
            "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; "+
            "font-src 'self' https://fonts.gstatic.com; "+
            "img-src 'self' data:; "+
            "connect-src 'self'")

        // Referrer Policy
        w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")

        // Permissions Policy
        w.Header().Set("Permissions-Policy",
            "geolocation=(), microphone=(), camera=()")

        next.ServeHTTP(w, r)
    })
}

4.2 Add SRI (Subresource Integrity) for HTMX

Update HTMX script tag:

<script src="https://unpkg.com/htmx.org@1.9.10"
        integrity="sha384-D1Kt99CQMDuVetoL1lrYwg5t+9QdHe7NLX/SoJYkXDFfX37iInKRy5xLSi8nO7UC"
        crossorigin="anonymous"></script>

4.3 Rate Limiting

Add to Go middleware:

// Simple rate limiter (use golang.org/x/time/rate in production)
func RateLimit(next http.Handler) http.Handler {
    limiter := rate.NewLimiter(10, 20) // 10 requests/sec, burst of 20

    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if !limiter.Allow() {
            http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
            return
        }
        next.ServeHTTP(w, r)
    })
}

---

5. Performance Optimizations

✅ Already Excellent

• Sub-millisecond response times
• Minimal JavaScript
• Clean HTML structure

🔧 Additional Improvements

5.1 Add Resource Hints

<head>
    <!-- Preconnect to external domains -->
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link rel="preconnect" href="https://unpkg.com">

    <!-- DNS prefetch -->
    <link rel="dns-prefetch" href="https://fonts.googleapis.com">
</head>

5.2 Add Cache Control Headers

In Go handler:

// Static files
w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")

// HTML pages
w.Header().Set("Cache-Control", "public, max-age=3600, must-revalidate")

// HTMX partials
w.Header().Set("Cache-Control", "private, max-age=300")

5.3 Compress Responses

import "compress/gzip"

func GzipHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") {
            next.ServeHTTP(w, r)
            return
        }

        w.Header().Set("Content-Encoding", "gzip")
        gz := gzip.NewWriter(w)
        defer gz.Close()

        gzw := gzipResponseWriter{Writer: gz, ResponseWriter: w}
        next.ServeHTTP(gzw, r)
    })
}

5.4 Optimize Font Loading

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap"
      rel="stylesheet"
      media="print"
      onload="this.media='all'">
<noscript>
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap"
          rel="stylesheet">
</noscript>

---

6. Enhanced User Experience

🔧 Recommended Enhancements

6.1 Add Smooth Scroll to Top

document.body.addEventListener('htmx:afterSwap', function(evt) {
    if (evt.detail.target.id === 'cv-content') {
        window.scrollTo({ top: 0, behavior: 'smooth' });
    }
});

6.2 Add PDF Download with Custom Filename

Update Go handler:

func handlePDFExport(w http.ResponseWriter, r *http.Request) {
    lang := r.URL.Query().Get("lang")
    filename := fmt.Sprintf("CV-%s-%s.pdf", "Juan-Andres-Moreno", lang)

    w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%s", filename))

    // Redirect to print view
    http.Redirect(w, r, fmt.Sprintf("/?lang=%s&print=true", lang), http.StatusSeeOther)
}

6.3 Add Keyboard Shortcuts

document.addEventListener('keydown', function(evt) {
    // Ctrl/Cmd + P for print
    if ((evt.ctrlKey || evt.metaKey) && evt.key === 'p') {
        evt.preventDefault();
        window.print();
    }

    // Ctrl/Cmd + E for English
    if ((evt.ctrlKey || evt.metaKey) && evt.key === 'e') {
        evt.preventDefault();
        document.querySelector('[hx-get="/cv?lang=en"]').click();
    }

    // Ctrl/Cmd + Shift + S for Spanish
    if ((evt.ctrlKey || evt.metaKey) && evt.shiftKey && evt.key === 's') {
        evt.preventDefault();
        document.querySelector('[hx-get="/cv?lang=es"]').click();
    }
});

6.4 Add Loading Skeleton

During HTMX swap, show skeleton:

.cv-content-loading {
    background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
    background-size: 200% 100%;
    animation: loading 1.5s infinite;
}

@keyframes loading {
    0% { background-position: 200% 0; }
    100% { background-position: -200% 0; }
}

---

7. Testing & Monitoring

🧪 Testing Checklist

7.1 Functional Testing

• Language switching works without page reload
• Browser back/forward buttons work correctly
• Bookmarks preserve language selection
• PDF export generates correct filename
• All links are functional
• Form validation (if any future forms)

7.2 Accessibility Testing

Tools:

• WAVE Browser Extension
• axe DevTools
• Lighthouse Accessibility Audit (target: 100)
• Screen reader testing (NVDA, JAWS, VoiceOver)
• Keyboard-only navigation

Checklist:

• All images have alt text
• Form labels are associated
• Color contrast meets WCAG AA (4.5:1)
• Focus indicators are visible
• ARIA attributes are correct
• Headings are hierarchical (h1 → h2 → h3)

7.3 Performance Testing

Tools:

• Lighthouse Performance (target: 95+)
• WebPageTest
• Chrome DevTools Network tab

Metrics:

• First Contentful Paint (FCP): <1.8s
• Largest Contentful Paint (LCP): <2.5s
• First Input Delay (FID): <100ms
• Cumulative Layout Shift (CLS): <0.1
• Time to Interactive (TTI): <3.8s

7.4 Cross-Browser Testing

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile Safari (iOS)
• Chrome Mobile (Android)

7.5 Security Testing

Tools:

• Mozilla Observatory
• Security Headers (securityheaders.com)
• OWASP ZAP

Checklist:

• HTTPS enforced
• Security headers present
• No XSS vulnerabilities
• No SQL injection (if database used)
• CSRF protection (if forms added)

---

8. Production Deployment Checklist

📦 Pre-Deployment

8.1 Code Quality

• All console.log statements removed
• Error handling implemented
• Code comments for complex logic
• No hardcoded credentials
• Environment variables configured

8.2 Build Process

# Minify CSS
npm install -g csso-cli
csso static/css/main.css -o static/css/main.min.css

# Minify JavaScript (if custom JS added)
npm install -g terser
terser static/js/main.js -o static/js/main.min.js -c -m

8.3 Environment Configuration

Create .env.production:

GO_ENV=production
PORT=1999
HOST=0.0.0.0
ALLOWED_ORIGINS=https://yoursite.com
CACHE_CONTROL_MAX_AGE=86400

8.4 Monitoring Setup

Add health check endpoint:

func handleHealth(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]interface{}{
        "status": "healthy",
        "version": "1.0.0",
        "timestamp": time.Now().Unix(),
    })
}

Add logging:

import "log/slog"

logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Info("Request received", "path", r.URL.Path, "method", r.Method)

---

9. Priority Implementation Plan

Phase 1: Critical (Week 1)

1. Accessibility

   • Add ARIA attributes (4 hours)
   • Implement keyboard navigation (2 hours)
   • Test with screen readers (2 hours)

2. Error Handling

   • Global HTMX error handler (2 hours)
   • Error toast component (2 hours)
   • Timeout configuration (1 hour)

3. Browser History

   • Add hx-push-url (1 hour)
   • Test back/forward navigation (1 hour)

Total: ~15 hours

Phase 2: Important (Week 2)

1. SEO

   • Meta tags and Open Graph (2 hours)
   • Structured data (2 hours)
   • Sitemap and robots.txt (1 hour)

2. Security

   • Security headers middleware (2 hours)
   • SRI for external scripts (1 hour)
   • Rate limiting (2 hours)

3. UX Enhancements

   • Transition effects (2 hours)
   • Language preference storage (2 hours)
   • Keyboard shortcuts (1 hour)

Total: ~15 hours

Phase 3: Nice-to-Have (Week 3)

1. Performance

   • Resource hints (1 hour)
   • Gzip compression (2 hours)
   • Font optimization (1 hour)

2. Testing

   • Automated accessibility tests (4 hours)
   • Performance testing (2 hours)
   • Cross-browser testing (4 hours)

Total: ~14 hours

---

10. Files to Update/Create

Update Existing Files

1. /Users/txeo/Git/yo/cv/templates/index.html

   • Add ARIA attributes
   • Add hx-push-url
   • Add error toast HTML
   • Add meta tags

2. /Users/txeo/Git/yo/cv/static/css/main.css

   • Add transition effects
   • Add error toast styles
   • Add focus styles
   • Add reduced motion support

3. /Users/txeo/Git/yo/cv/main.go

   • Add security headers
   • Add rate limiting
   • Add gzip compression
   • Add health check endpoint

Create New Files

1. /Users/txeo/Git/yo/cv/static/js/htmx-enhancements.js (optional)

   • Error handling
   • Keyboard shortcuts
   • Language preference storage
   • Analytics events

2. /Users/txeo/Git/yo/cv/static/robots.txt

   • Search engine directives

3. /Users/txeo/Git/yo/cv/sitemap.xml

   • Site structure for SEO

4. /Users/txeo/Git/yo/cv/middleware/security.go

   • Security headers
   • Rate limiting

---

11. Enhanced Templates (Ready to Use)

I've created two enhanced template files for you:

1. /Users/txeo/Git/yo/cv/templates/index-improved.html

   • All accessibility improvements
   • Error handling
   • Browser history management
   • Keyboard shortcuts
   • Language preference storage
   • Loading states
   • Meta tags and SEO

2. /Users/txeo/Git/yo/cv/static/css/main-enhanced.css

   • Smooth transitions
   • Error toast styles
   • Enhanced focus states
   • Reduced motion support
   • High contrast mode support
   • Improved responsive design

To apply these improvements:

# Backup current files
cp templates/index.html templates/index.html.backup
cp static/css/main.css static/css/main.css.backup

# Apply improvements
mv templates/index-improved.html templates/index.html
mv static/css/main-enhanced.css static/css/main.css

---

12. Testing Commands

Run the site

go run main.go

Test HTMX endpoints

# Test initial load
curl -s 'http://localhost:1999/?lang=en' | head -50

# Test HTMX partial
curl -s 'http://localhost:1999/cv?lang=es' | head -50

# Test performance
curl -o /dev/null -s -w "Time: %{time_total}s\n" 'http://localhost:1999/cv?lang=en'

Run Lighthouse audit

# Install if needed
npm install -g lighthouse

# Run audit
lighthouse http://localhost:1999/?lang=en --view

Test accessibility

# Install axe-cli
npm install -g @axe-core/cli

# Run audit
axe http://localhost:1999/?lang=en

---

13. Summary

Current Score: 85/100

Breakdown:

• Performance: 100/100 ✅ (Exceptional sub-ms responses)
• HTMX Patterns: 90/100 ✅ (Clean, well-structured)
• Accessibility: 60/100 ⚠️ (Missing ARIA, keyboard nav)
• SEO: 50/100 ⚠️ (Missing meta tags, structured data)
• Security: 70/100 ⚠️ (Missing headers, SRI)
• Error Handling: 40/100 ⚠️ (No user feedback)
• UX: 80/100 ✅ (Good, needs transitions)

Target Score: 100/100

With recommended improvements:

• Performance: 100/100 ✅
• HTMX Patterns: 100/100 ✅
• Accessibility: 95/100 ✅
• SEO: 95/100 ✅
• Security: 95/100 ✅
• Error Handling: 90/100 ✅
• UX: 95/100 ✅

---

14. Questions?

If you need help implementing any of these recommendations:

1. Accessibility: Focus on WCAG 2.1 Level AA compliance
2. HTMX: Follow htmx.org best practices
3. Go Backend: Use standard library middleware patterns
4. Testing: Prioritize automated accessibility and performance tests

Resources:

• HTMX Docs: https://htmx.org/docs/
• WCAG Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
• Go Security: https://go.dev/doc/security/
• Lighthouse: https://developers.google.com/web/tools/lighthouse

---

Next Steps:

1. Review this document
2. Apply Phase 1 improvements (critical)
3. Test with real users
4. Iterate based on feedback
5. Deploy to production

Your CV site has an excellent foundation. With these enhancements, it will be a best-in-class example of HTMX implementation! 🚀