Knowledge · Guidelines · sveltekit

Safari Webkit Compatibility

Safari/WebKit compatibility rules for every web page and component — iPad/iPhone Safari is a first-class target, not an afterthought. Any platform API or CSS feature newer than the WebKit baseline ships with a DETECTED fallback, never a silent no-op. "Renders in Chrome" is not done.

Metadata

sveltekit sveltekit

Description

Collected from the 2026-07-10 Safari/iPad review (owner-reported: admin filter popovers stuck always-visible on iPad, image/collection layout shifts) plus every WebKit lesson already paid for in this repo's history. Root cause of the popover bug: web-svelte admin/Popover.svelte drives visibility exclusively through the native Popover API behind optional-chaining guards (`panelEl.showPopover?.()`). On WebKit without the Popover API the guards silently no-op, the UA sheet's `display:none` for `[popover]` does not exist, and the panel renders as a plain always-visible div. The guard pattern that made unit tests pass (jsdom) is the same pattern that broke production Safari — feature-DETECTION must produce a FALLBACK, not a no-op. WebKit baseline (the floor we support): current iPadOS/iOS major MINUS 2 — as of 2026 that means Safari 16. Features newer than the floor are usable ONLY behind detection with a functional fallback. Feature → minimum Safari (verify on caniuse when in doubt): flex gap 14.1 · @supports selector() 14.1 · aspect-ratio 15 · :has() 15.4 · dvh/svh/lvh 15.4 · Popover API (+ToggleEvent, :popover-open) 17 · View Transitions (same-doc) 18 · unprefixed backdrop-filter 18 · scrollbar-gutter 18.2 · CSS anchor positioning 26 (Chrome-only installed base — treat as unavailable)

Rules

  • SWC-1 — Native Popover API only with a full fallback — CSS hide for non-supporting engines PLUS a JS open/close + light-dismiss path when showPopover is absent
  • SWC-2 — CSS anchor positioning (anchor-name, position-anchor, anchor(), @position-try) is prohibited — use @floating-ui/dom
  • SWC-3 — :has() is progressive enhancement only — layout and core interaction must survive without it
  • SWC-4 — Every dvh/svh/lvh declaration is preceded by a vh fallback line
  • SWC-5 — View Transitions are guarded (document.startViewTransition?) and navigation/visibility never depends on them
  • SWC-6 — backdrop-filter always ships with its -webkit-backdrop-filter twin, and never combines with scroll-driven show/hide chrome
  • SWC-7 — No interaction depends on :hover — touch reveals get an explicit tap path; hover-only affordances live behind @media (hover: hover)
  • SWC-8 — Every remote image renders inside a container with a reserved box — CSS aspect-ratio or explicit width/height attributes — BEFORE the image loads
  • SWC-9 — scrollbar-gutter is cosmetic-only — layout must not shift when the property is unsupported
  • SWC-10 — Playwright runs a webkit project over the admin + public smoke paths — a UI change touching any SWC-listed feature is verified in WebKit before done