kandev/docs/specs/ui/webkit-task-dialog-rendering.md

status, created, owner

status	created	owner
shipped	2026-08-01	product

WebKit Task Dialog Rendering

Why

People opening the Create Task dialog in Safari or a WebKit-backed Tauri app see softer, lower-clarity text and controls than people opening the same Kandev surface in Chromium. The dialog must remain visually sharp without removing the existing Chromium motion that already renders correctly.

What

• Kandev identifies actual WebKit runtimes before the application renders and exposes that result as a non-persistent document rendering-engine marker.
• The Create Task dialog uses opacity-only open and close motion in WebKit; the animation does not apply a transform to the text-bearing dialog surface.
• The Create Task dialog is centered without a transform in WebKit and remains above its overlay.
• Safari, macOS WKWebView, WebKitGTK, and browsers constrained to WebKit on iOS receive the WebKit rendering path.
• Desktop Chromium, Android Chromium, Edge/WebView2, Firefox, and other non-WebKit engines retain the existing Create Task dialog animation and positioning.
• The WebKit rendering path preserves the existing task-creation form, focus behavior, dismissal, keyboard behavior, dimensions, internal scrolling, responsive full-height phone presentation, and safe-area behavior.
• The Create Task dialog omits the generic top-right close control in every browser; the footer Cancel action remains available for dismissal.
• The dialog does not reserve top padding for the removed control while retaining its side and bottom spacing.
• Rendering-engine classification is runtime-only and does not add a user setting or persisted preference.

Failure modes

• If the runtime cannot be classified as WebKit, Kandev uses the existing default dialog rendering rather than applying the workaround broadly.
• User-agent compatibility tokens such as desktop Chromium's AppleWebKit token must not classify Blink as WebKit. iOS browser brands remain classified as WebKit because their underlying engine is WebKit.

Scenarios

• GIVEN Kandev is running in Safari, WKWebView, or WebKitGTK, WHEN the user opens Create Task, THEN the dialog enters with opacity-only motion, has no transform on its text-bearing surface, remains centered, and renders above the overlay.
• GIVEN Kandev is running in desktop Chrome or Edge/WebView2, WHEN the user opens Create Task, THEN the existing scale-and-fade motion and centered geometry remain unchanged.
• GIVEN Kandev is running in an iOS browser, WHEN the user opens Create Task, THEN the WebKit rendering path is selected even when the browser has a non-Safari brand.
• GIVEN Create Task is open in a narrow WebKit viewport, WHEN the user edits or scrolls the form, THEN the dialog remains full-height, contained within the viewport, free of document horizontal overflow, and exposes the same task-creation controls.

Out of scope

• Changing dialog motion in Chromium or Firefox.
• Applying the workaround to dialogs other than Create Task without a separate reproduced need.
• Replacing Tauri's system WebView, changing desktop zoom behavior, or modifying bundled fonts.
• Adding browser-specific font-smoothing, forced GPU compositing, or will-change workarounds.