ADR-024: Live Quality Badges for Performance Transparency

Status

Accepted (amended 2026-08-02: badge wiring updated to match the shipped configuration — the PageSpeed link is now optional and off by default; see the note under Badge Locations)

Context

The template claims “95+ Lighthouse scores” and “100/100” performance, but these claims need verification. Users should be able to:

1. Verify claims instantly – Click a badge to see live Lighthouse results
2. Trust the metrics – See that scores are validated by CI/CD
3. Monitor performance – Check real-world scores on the deployed site

Problem

• Performance claims in marketing copy lack proof
• No easy way for users to verify Lighthouse scores
• CI validates performance but results aren’t surfaced publicly

Requirements

• Zero JavaScript – Badges must work without client-side code
• Accessible – Proper ARIA labels and semantic HTML
• Performant – No external badge services that slow page load
• Verifiable – Link to live PageSpeed Insights results
• Maintainable – No manual score updates required

Decision

Implement hybrid static badges with live verification links:

Implementation Strategy

1. Static badges – Use semantic HTML/CSS (no external badge services)
2. Live verification – Link to PageSpeed Insights for real-time scores
3. CI indicator – Show “Verified by CI” badge for trust signal
4. Multiple placements – Index page, Footer, and README

Badge Locations

Amendment (2026-08-02): the PageSpeed link is now optional configuration: siteLinks.pagespeed in src/config.ts ships as "", which hides it. With the default config the “View Live Scores” button does not render (index.astro gates it on siteLinks.pagespeed), the footer renders a plain non-linked “95+ Lighthouse” span (the 🎯 emoji is gone from both variants), and “Verified by CI” is now a link to ${siteLinks.github}/actions rather than a static badge. The README Shields.io badge links to the README’s own #-performance-budgets anchor instead of PageSpeed Insights. The sections below record the original implementation.

1. Index Page (Primary)

Added to Lighthouse Metrics section (#performance):

• “View Live Scores” button – Links to PageSpeed Insights
• “Verified by CI” badge – Shows CI validation
• Responsive layout (stacks on mobile)
• Hover effects for interactivity

2. Footer (Persistent)

Added to footer badges row:

• ”🎯 95+ Lighthouse” badge – Clickable, links to PageSpeed
• Matches existing badge style (MIT Licensed, Production Ready, etc.)
• Visible on every page

3. README (Discovery)

Added Shields.io badge at top:

[![Lighthouse Score](https://img.shields.io/badge/Lighthouse-95%2B-success?logo=lighthouse&logoColor=white)](https://pagespeed.web.dev/analysis?url=https://YOUR_ORG.github.io/YOUR_REPO/)

• Shows up in GitHub repo
• Clickable for verification
• Uses Lighthouse logo for brand recognition

Implementation Details

Index Page Badge

<!-- Live Quality Badge -->
<div class="flex flex-col sm:flex-row items-center justify-center gap-3 sm:gap-4">
  <a
    href={siteLinks.pagespeed}
    target="_blank"
    rel="noopener noreferrer"
    class="inline-flex items-center gap-2 px-4 py-2 rounded-lg bg-primary-100 hover:bg-primary-200 text-primary-800 transition-colors group"
    aria-label="View live Lighthouse scores on PageSpeed Insights"
  >
    <span class="text-sm font-medium">🎯 View Live Scores</span>
    <svg class="w-4 h-4 group-hover:translate-x-0.5 transition-transform">
      <!-- External link icon -->
    </svg>
  </a>

  <span class="inline-flex items-center gap-2 px-3 py-1.5 rounded-full bg-secondary-100 text-secondary-800 text-xs font-medium">
    <svg class="w-3 h-3"><!-- Checkmark icon --></svg>
    Verified by CI
  </span>
</div>

Footer Badge

<a
  href={siteLinks.pagespeed}
  target="_blank"
  rel="noopener noreferrer"
  class="inline-flex items-center gap-1 px-2 py-1 rounded-full bg-primary-100 text-primary-800 hover:bg-primary-200 transition-colors"
  aria-label="View live Lighthouse scores"
>
  🎯 95+ Lighthouse
</a>

Design Tokens Used

• Colors: bg-primary-100, text-primary-800, hover:bg-primary-200
• Spacing: px-4 py-2, gap-3 sm:gap-4
• Typography: text-sm font-medium, text-xs
• Transitions: transition-colors, transition-transform

Alternatives Considered

1. Lighthouse CI Server (Rejected)

Pros:

• Automated badge generation
• Historical trend tracking
• Official Lighthouse CI integration

Cons:

• Requires external hosting (Heroku, Vercel, etc.)
• Additional infrastructure to maintain
• Potential single point of failure
• Costs for hosting

Why rejected: Too much infrastructure overhead for a starter template.

2. GitHub Actions Badge (Rejected)

Pros:

• Automated from CI workflow
• No external dependencies
• Shows pass/fail status

Cons:

• Only shows pass/fail, not actual scores
• Doesn’t link to detailed results
• Less informative for users

Why rejected: Doesn’t surface actual Lighthouse scores.

3. Embedded Lighthouse Widget (Rejected)

Pros:

• Shows live scores in-page
• No external navigation needed

Cons:

• Requires JavaScript (violates zero-JS principle)
• Adds external dependencies
• Performance impact
• Privacy concerns (external API calls)

Why rejected: Violates zero-JS baseline and adds performance overhead.

4. Manual Score Updates (Rejected)

Pros:

• Simple to implement
• No external dependencies

Cons:

• Requires manual updates after every change
• Easy to forget or become stale
• No verification mechanism

Why rejected: Not maintainable, defeats purpose of “live” badge.

Consequences

Positive

• Transparency – Users can verify performance claims instantly
• Trust – “Verified by CI” badge builds confidence
• Zero overhead – No JavaScript, no external services
• Accessibility – Proper ARIA labels and semantic HTML
• SEO benefit – README badge shows up in GitHub search
• Marketing – Prominent placement reinforces performance-first messaging

Negative

• Manual URL updates – If deployment URL changes, badges need updating
• PageSpeed dependency – Relies on Google’s PageSpeed Insights service
• No automation – Scores aren’t auto-updated (but link shows live data)

Neutral

• Static scores – Badge shows “95+” not exact score (intentional)
• Multiple placements – Increases visibility but adds maintenance points

Monitoring

Success Metrics

• Click-through rate – Track badge clicks to PageSpeed Insights
• User feedback – Monitor for questions about performance claims
• CI validation – Ensure CI continues to enforce performance budgets

Maintenance

• Quarterly review – Verify PageSpeed Insights URL still works
• Score updates – If template performance improves, update badge text
• Deployment changes – Update URLs if deployment location changes

Related Decisions

• ADR 014: Index Page Performance Strategy – Performance optimization approach
• ADR 020: Page Performance Patterns – Performance best practices

References

• PageSpeed Insights API
• Lighthouse CI Documentation
• Shields.io Badge Service
• WCAG 2.1 Link Purpose

Implementation Checklist

• Add badge to index.astro performance section
• Add badge to Footer component
• Add Shields.io badge to README
• Verify PageSpeed Insights URL works (amended 2026-08-02: applies only when siteLinks.pagespeed is set; the shipped default is "")
• Test accessibility (ARIA labels, keyboard navigation)
• Test responsive layout (mobile, tablet, desktop)
• Document in ADR
• Update CI workflow to fail on performance regression (implemented since: Lighthouse CI floors on both form factors + JS/image/font gates)
• Add performance monitoring to deployment pipeline

Future Enhancements

Phase 1 (Optional)

• Add Lighthouse CI workflow step to generate artifacts
• Store historical scores in GitHub Actions artifacts
• Create performance trend visualization

Phase 2 (Advanced)

• Set up Lighthouse CI server for detailed tracking
• Add performance regression detection
• Generate automated performance reports

Phase 3 (Enterprise)

• Integrate with monitoring services (Datadog, New Relic)
• Add Core Web Vitals tracking
• Create performance dashboard

Enforcement

• Not machine-checkable: badge honesty (claimed scores matching reality) is periodically evidenced by the Lighthouse workflow but is not asserted per-commit.
• Graduation log: (empty at creation; entries added when a check changes status)

---

Date: 2026-02-17 (footer backfilled 2026-07-05 from git history; this record predates the footer convention)
Participants: Template maintainers
Outcome: Accepted