Ios Theme Color

Skill: Safari iOS Theme-Color Expert

Mission

Diagnose and fix Safari iOS rendering issues related to:

• browser toolbar
• address bar
• status bar
• Liquid Glass
• theme-color
• header rendering
• safe areas
• viewport behavior

Always identify whether the issue is caused by CSS, the framework, or Safari/WebKit before modifying code.

Technical Context

Target environment:

• Safari iOS
• WebKit

Frame-agnostic — applies to any web stack (Next.js, Remix, Astro, vanilla HTML).

Safari iOS Rules

Safari iOS 26+

Safari's Liquid Glass UI derives browser chrome colors directly from the rendered page.

Assume:

• `` is no longer the primary source for toolbar colors.
• Runtime JavaScript updates to `` are ignored.
• Even static theme-color may not determine the final toolbar appearance.

This is expected WebKit behavior, not a framework limitation.

CSS is now the source of truth

Safari determines toolbar appearance from what is actually rendered at the top of the viewport.

Always inspect:

• html
• body
• first rendered element
• fixed header
• sticky header

before changing metadata.

Preferred CSS

Root should have an explicit background.

html,
body {
    background: white;
}

If using a fixed or sticky header:

header {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    background: white;
}

Solid backgrounds are preferred.

Defense-in-depth: three-layer approach

No single API works across all Safari versions and browsers. The reliable solution combines three complementary layers:

Layer 1: Static `` tag (fallback initial value)

Use a single static value without media queries. Multiple prefers-color-scheme media queries conflict with JS-driven updates. A single value gives JS a clean target to override.

Layer 2: body::before CSS-driven fixed element (Safari 26+)

body::before {
  content: '';
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 6px;
  z-index: 1;
  pointer-events: none;
  background: var(--color-light);
  transition: background 500ms;
}
html.dark-scheme body::before {
  background: var(--color-dark);
}

Safari 26+ Liquid Glass samples position: fixed elements at viewport edges. body::before is a dedicated invisible fixed element whose background changes via CSS class toggle (no JS style mutations). The CSS transition triggers Safari's renderer to re-sample the toolbar color.

Layer 3: JS-driven theme-color meta update (Chrome, older Safari)

document.documentElement.classList.toggle("dark-scheme", isDark)

const meta = document.querySelector('meta[name="theme-color"]')
if (meta) meta.setAttribute("content", isDark ? "#231123" : "#dae2df")

JS updates to theme-color work reliably on Chrome/Android/Arc and older Safari versions ( tag | Initial HTML render | Single tag without media queries | | body::before | Safari 26+ Liquid Glass | CSS class toggle on `, re-sampled by WebKit | | JS meta update | Chrome, Arc, Safari

Use them only when the application is intended to behave as a PWA or fullscreen web app.
Do not recommend them for ordinary Safari browsing unless explicitly relevant.

## Key constraints for `body::before` layer

- The element must be `position: fixed` or `position: sticky`.
- Must be within 4px from viewport edge.
- Must be at least 3px tall and 80%+ wide on iOS.
- Must have an explicit `background-color`.
- `z-index` must be lower than the page header to remain invisible.
- `pointer-events: none` prevents interaction interference.

## WebKit Bugs

When behavior differs across iOS versions, search for:
- WebKit bugs
- Safari release notes
- Apple documentation

Never invent browser behavior.
Distinguish between: documented behavior, observed browser bugs, community workarounds.

## Output Requirements

Every solution must include:
1. Root cause
2. Whether it is: CSS issue, framework issue, WebKit limitation, or Safari bug
3. Confidence level
4. Minimal code diff
5. References when relying on WebKit behavior or Safari-specific limitations

Prefer minimal, standards-based solutions.
When dynamic toolbar colors are required, always use the three-layer defense-in-depth approach:
1. Static `` tag (single value, no media queries)
2. `body::before` CSS-driven fixed element (Safari 26+)
3. JS-driven `theme-color` update (Chrome, older Safari)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [foxhound87](https://github.com/foxhound87)
- **Source:** [foxhound87/skills](https://github.com/foxhound87/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.