# Cross-browser compatibility is addressed

- **Pattern:** `ab-002175` (`pre-launch.user-facing.cross-browser`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002175
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002175)

## Why it matters

Browser compatibility failures produce silent user exits: a feature that works in Chrome 130 may break in Safari 17 or Firefox ESR without any error visible to the developer. iOS Safari in particular has a distinct rendering engine (WebKit) that diverges from Chrome on CSS `gap` in flexbox, `position: sticky`, smooth scroll behavior, and new Web APIs — all common in modern framework templates. A project that passes QA in Chrome only can fail for a significant fraction of real users, particularly on mobile where Safari dominates iOS.

## Severity rationale

Medium because browser-specific rendering failures silently break the experience for a significant user segment — particularly iOS Safari — without producing errors visible in development.

## Remediation

Verify that a `browserslist` configuration is present and that PostCSS includes `autoprefixer` for CSS vendor prefix handling.

```json
// package.json
{
  "browserslist": ["last 2 versions", "> 1%", "not dead"]
}
```

Most Next.js, Vite, and Create React App setups include a default browserslist — confirm it hasn't been removed. Add `autoprefixer` to `postcss.config.js` if not already present. Test in at minimum Chrome (latest), Firefox (latest), Safari (latest, including iOS Safari), and Edge (latest). For any advanced CSS features — `has()`, `container queries`, `subgrid` — verify support at caniuse.com before shipping.

## Detection

- **ID:** `cross-browser`
- **Severity:** `medium`
- **What to look for:** Count all browser-specific CSS prefixes and polyfills. Enumerate whether CSS features used are supported across major browsers (Chrome, Firefox, Safari, Edge). Check `.browserslistrc` or `browserslist` field in `package.json` for browser target configuration. Check for any polyfills or compatibility shims in the project. Check if the project uses any cutting-edge CSS features (CSS Grid subgrid, container queries, `has()` selector) or JavaScript APIs without fallbacks. Look for postcss config with autoprefixer. Check if the framework's default browserslist config is retained or overridden.
- **Pass criteria:** A browserslist configuration targeting modern browsers is present (framework default counts), or the project uses autoprefixer/postcss for CSS compatibility, or the project documents intentional browser support decisions. At least 95% of CSS features used must be supported in the last 2 versions of major browsers.
- **Fail criteria:** No browserslist configuration and evidence of CSS features or JavaScript APIs used without browser support checks or polyfills, suggesting compatibility has not been considered.
- **Skip (N/A) when:** Skip for API-only projects with no frontend. Skip for projects explicitly targeting Chromium/Electron-only environments.

- **Cross-reference:** For mobile responsiveness, see `mobile-responsive`.
- **Detail on fail:** `"No browserslist configuration found and project uses CSS/JS features that may not be supported in all target browsers"`
- **Remediation:** Modern frameworks handle most compatibility concerns automatically, but it's worth verifying your setup:

  ```json
  // package.json — browserslist for compatibility
  { "browserslist": ["last 2 versions", "> 1%", "not dead"] }
  ```

  1. Most frameworks (Create React App, Next.js, Vite) include a default browserslist targeting modern browsers — verify yours hasn't been removed.
  2. If you use PostCSS, ensure `autoprefixer` is in your PostCSS config to handle CSS vendor prefixes.
  3. Check caniuse.com for any advanced CSS or JavaScript features you're using — particularly CSS Grid subgrid, the `has()` selector, or new Web APIs.
  4. Test in at minimum: Chrome (latest), Firefox (latest), Safari (latest — especially iOS Safari, which has the most web platform gaps), and Edge (latest).
  5. For iOS Safari specifically, be careful with: CSS `gap` in flexbox (well-supported now but verify), smooth scrolling behavior, and `position: sticky` in certain contexts.

---

## External references

- iso-25010 compatibility.co-existence

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-002175