Cross-Browser Compatibility Audit

Static Websites on cPanel

A site that works in Chrome but fails in Safari is not a finished site. Cross-browser compatibility ensures that every user can access content and complete tasks regardless of browser or operating system.

The strategy is progressive enhancement: core content and functionality work in all browsers, advanced features layer on top only when supported.

Target browsers:

Severity Levels

Section 1 — CSS Compatibility

1.1 Properties Requiring Fallbacks

These CSS properties have inconsistent support. Every use must include the fallback shown.

/* ✅ Pattern: fallback on line before, modern on line after */
.hero {
  height: 100vh;
  height: 100dvh;
}

.navbar {
  position: -webkit-sticky;
  position: sticky;
  top: 0;
}

.modal-backdrop {
  background: rgba(0, 0, 0, 0.6);
  -webkit-backdrop-filter: blur(8px);
  backdrop-filter: blur(8px);
}

Flag any use of these properties without their corresponding fallback.

1.2 Vendor Prefixes Required

/* ✅ Multi-line text clamp — full webkit setup required */
.card__description {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

Flag any use of these properties without the -webkit- prefix.

1.3 Safe CSS — No Fallback Needed

These are safe for all target browsers (Chrome 100+, Safari 15+, Firefox 100+, Edge 100+):

clamp(), min(), max(), CSS custom properties (var()), object-fit, env(safe-area-inset-*), CSS Grid (excluding subgrid).

Flag any use of subgrid — verify requirement, not fully safe across targets.

1.4 CSS That Behaves Differently Between Browsers

Full code examples for each issue: see references/browser-differences.md

Form element styling — browsers render form elements differently. Reset with appearance: none before custom styling.

`height: 100%` on flex children in Safari — use flex: 1 instead.

`overflow: hidden` + `border-radius` in Safari — add isolation: isolate to force stacking context.

Scroll snap — behavior differs between browsers. Test manually.

`letter-spacing` on last character in Safari — applies after last character. Usually acceptable, fix only if it causes layout problems.

Individual transform properties (`translate`, `rotate`, `scale`) — use transform shorthand for full compatibility. Individual properties not safe in Safari 14.0.

Section 2 — JavaScript Compatibility

2.1 Safe ES6+ Features

All safe for target browsers (Chrome 100+, Safari 15+, Firefox 100+, Edge 100+):

const/let, arrow functions, template literals, destructuring, spread operator, Promise, async/await, fetch, classList, IntersectionObserver, ResizeObserver, optional chaining (?.), nullish coalescing (??), CSS.supports(), closest(), dataset.

Flag any ES2022+ features not in this list — verify support before using.

2.2 APIs Requiring Feature Detection

These APIs need feature detection or try/catch wrapping:

Full code examples with fallbacks: see references/browser-differences.md

`navigator.clipboard` — requires HTTPS and user gesture. Fallback to execCommand('copy').

`localStorage` — can be blocked in private browsing. Wrap in try/catch.

`scrollIntoView({ behavior: 'smooth' })` — Safari before 15.4 ignores behavior. Check scrollBehavior in document.documentElement.style.

`NodeList` methods — only forEach is available directly. For .map/.filter/.reduce, convert with Array.from() or spread [...nodeList].

2.3 Passive Event Listeners

Passive listeners improve scroll performance. Chrome 51+, Safari 11.1+, Firefox 49+.

element.addEventListener('touchstart', handler, { passive: true });

Section 3 — HTML Feature Support

3.1 Form Attributes

• type="email", type="tel", type="number" — safe, unsupported types fall back to text
• type="date" — renders differently per browser. Flag if visual consistency required
• required, pattern, min, max — supported in all targets. Safari renders validation differently — accept variation
• HTML5 validation: supported but styled differently per browser

3.2 Elements Requiring Verification

`<dialog>` — Chrome 37+, Safari 15.4+, Firefox 98+. Safe for targets but verify Safari version. Use feature detection: typeof modal.showModal === 'function'.

`<details>` / `<summary>` — safe in all targets. Animation on open/close is not consistent.

3.3 Image Formats

Flag any AVIF or WebP without a JPEG/PNG fallback via <picture>.

Section 4 — Safari-Specific Issues

Safari causes the majority of cross-browser failures in Chrome-developed projects.

Full code examples for all Safari issues: see references/browser-differences.md

Critical checks:

• Modal background scroll — overflow: hidden on body does NOT prevent scroll in iOS Safari. Use position: fixed technique
• position: fixed inside transformed elements — fixed positioning breaks if ancestor has transform
• Input zoom on focus — inputs below font-size: 1rem trigger iOS auto-zoom
• 100vh — covered in Audit 07. Always use dvh with vh fallback
• overflow: hidden + border-radius — add isolation: isolate
• Flex children height: 100% — use flex: 1 instead

Custom scrollbar styles:

/* Firefox uses different properties than Chrome/Edge */
.scrollable {
  scrollbar-width: thin;
  scrollbar-color: var(--color-primary) transparent;
}

.scrollable::-webkit-scrollbar { width: 8px; }
.scrollable::-webkit-scrollbar-thumb {
  background: var(--color-primary);
  border-radius: 4px;
}

Section 5 — Progressive Enhancement Strategy

Every feature must be built in three layers:

1. Baseline — core content accessible, layout intact, forms work, navigation works
2. Enhanced — visual improvements, animations, advanced interactions via @supports or JS feature detection
3. Optimal — cutting-edge CSS, fails gracefully to Layer 2

/* ✅ Three-layer example */

/* Layer 1 — Baseline */
.card {
  background: var(--bg-surface);
  border: 1px solid var(--border-default);
  border-radius: var(--radius-lg);
}

/* Layer 2 — Enhanced */
@media (hover: hover) {
  .card:hover { box-shadow: var(--shadow-lg); }
}

/* Layer 3 — Optimal */
@supports (backdrop-filter: blur(8px)) {
  @media (hover: hover) {
    .card:hover {
      transform: translateY(-4px);
      -webkit-backdrop-filter: blur(4px);
      backdrop-filter: blur(4px);
    }
  }
}

Flag advanced CSS features used without @supports guards when targeting browsers that may not support them.

Section 6 — Testing Protocol

Test in all four rendering engines — Chrome and Edge share Blink, so one covers both.

What to verify in each browser:

• Layout matches design at all breakpoints
• Fonts render correctly
• Images and SVGs load and display correctly
• Animations play correctly
• Navigation and forms work
• Dynamic interactions work (chat, toggles, modals)
• No console errors
• No layout shift on load
• Smooth scrolling and animations at 60fps

Safari iOS specific:

• No unwanted zoom on input focus
• Scroll momentum on scrollable containers
• Safe area insets applied correctly
• Fixed elements stay fixed while scrolling

Audit Output Format

Cross-Browser Compatibility Audit — [Project Name]
Date: [Date]
Browsers tested: Chrome [version], Safari [version], Firefox [version], Edge [version]
Safari iOS tested: [iOS version]
Summary

Critical issues: X
High priority: X
Medium priority: X
Low priority: X
Most problematic browser: [browser]
Overall: [Compatible / Partially compatible / Has critical failures]

Critical Issues
[Issue title]

Browser affected: [Chrome / Safari / Firefox / Edge / iOS Safari]
Feature: [CSS property / JS API / HTML element]
File: [filename and line]
Issue: [What fails and how it affects the user]
Fix: [Specific correction with code example]

High Priority
[Same format]
Medium Priority
[Same format]
Low Priority
[Same format]
Recommended Fix Order

Safari critical failures — largest mobile impact
Missing vendor prefixes — quick wins
Missing format fallbacks — images
Progressive enhancement gaps — advanced features
Visual inconsistencies — cosmetic differences

Full quick-reference checklist: see references/checklist.md