fix(api): eliminate theme flash on docs.warp.dev/api#6
Merged
hongyi-chen merged 2 commits intomainfrom Apr 30, 2026
Merged
Conversation
The /api page flashed white on first load before settling into dark mode. The head script already set <html data-theme> synchronously, but no CSS in <head> keyed off that attribute — the only theme-aware CSS lived inside Scalar's runtime-injected customCss (which keys off body classes .dark-mode / .light-mode), and that CSS only existed after the Scalar bundle (loaded mid-<body>) downloaded, parsed, and mounted. Add an inline <style> in <head> that paints html (and inheriting body) based on data-theme, so the canvas color is correct on the very first frame. Scalar's customCss still drives the rest of the page once it mounts. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The previous fix removed the white-on-first-frame flash but exposed a
deeper timing bug: Scalar booted in light mode on cold loads, briefly
flipped the page to light, then DOMContentLoaded restored dark.
Root cause: the Scalar config sync script reads
`document.body.classList.contains('dark-mode')` synchronously inside
<body>, before the head script's body-class apply runs (which is queued
for DOMContentLoaded because document.body is null in <head>). So
cfg.darkMode was always false on cold load → Scalar mounted light → the
mirror MutationObserver flipped html[data-theme]='light' → the new
canvas CSS painted white → DOMContentLoaded fired and corrected
everything.
Fix:
1. Expose `window.__warpResolveTheme()` — a read-only sibling of the
existing __warpApplyTheme that just resolves localStorage +
prefers-color-scheme to 'dark' or 'light'.
2. Add a top-of-body inline script that calls __warpResolveTheme() and
applies the body class synchronously, before any other body-level
script runs.
3. Switch the Scalar config sync to read __warpResolveTheme() instead
of body.classList, decoupling Scalar's boot value from DOM apply
ordering.
Co-Authored-By: Oz <oz-agent@warp.dev>
bholmesdev
approved these changes
Apr 30, 2026
rachaelrenk
added a commit
that referenced
this pull request
May 5, 2026
- Fix title case → sentence case in titles and sidebar labels: computer-use, web-search, api-keys, mcp-servers, network-log, known-issues - Simplify integration titles: remove 'for Oz' suffix (azure-devops, bitbucket, gitlab, linear, slack) - Add key principle #6 to SEO audit skill with explicit sentence case rule and ✅/❌ examples to prevent future casing mistakes Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
added a commit
that referenced
this pull request
May 5, 2026
…ss 51 pages (#22) * Automated SEO fixes: resolve title length and description issues across 51 pages - Fix 40 title_too_short warnings by adding descriptive frontmatter titles with sidebar.label to preserve nav labels - Fix 4 title_too_long warnings by shortening guide titles - Fix 7 description_too_long info issues by trimming descriptions to ≤160 chars - Skip 5 allowlisted pages (Changelog, Guides, Tabs, Split panes, Tab Configs) - Skip 1 unfixable page (https://docs.warp.dev/api/ - no source file) Co-Authored-By: Oz <oz-agent@warp.dev> * fix: sentence case corrections and skill update for casing rules - Fix title case → sentence case in titles and sidebar labels: computer-use, web-search, api-keys, mcp-servers, network-log, known-issues - Simplify integration titles: remove 'for Oz' suffix (azure-devops, bitbucket, gitlab, linear, slack) - Add key principle #6 to SEO audit skill with explicit sentence case rule and ✅/❌ examples to prevent future casing mistakes Co-Authored-By: Oz <oz-agent@warp.dev> * fix: remove duplicate sidebar key in skills.mdx frontmatter Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
docs.warp.dev/apiflashed white on first load before settling into dark mode. The rest ofdocs.warp.devdoes not flash because Starlight's CSS is keyed off:root[data-theme]and applies synchronously when the head script sets the attribute on<html>.Root cause
The head script in
src/pages/api.astroalready set<html data-theme="dark|light">synchronously, but no CSS in<head>keyed off that attribute. All theme-aware styling for/apilived inside Scalar's runtime-injectedcustomCss(which keys offbody.dark-mode/body.light-mode), and that block only exists after the Scalar bundle (loaded mid-<body>) downloads, parses, and mounts. So between body parse and Scalar mount, the page painted with the browser default white — then repainted dark.Fix
Add a small inline
<style>block in<head>that paintshtml(and inheritingbody) based ondata-theme. The canvas color is now correct on the very first frame, before the Scalar bundle even starts to download. Scalar'scustomCssstill takes over once it mounts.No JS changes — the existing localStorage read +
data-themewrite was already correct.Values mirror
--scalar-background-1from the existing customCss block; comment in the file flags the lockstep dependency.Validation
npm run buildsucceeds;dist/api/index.htmlcontains the newhtml[data-theme=dark]{background-color:#121212;color-scheme:dark}rule.docs.warp.dev/apiin incognito (cold cache) and confirm no white flash in either dark or auto mode.Artifacts
Co-Authored-By: Oz oz-agent@warp.dev