A continuation of Janady13/crawler-signal-reference / framework-html-meta-theme-color.md. The complete source identity, every recorded occurrence, and linked equations are on its first page.
Source transcript · continued
Download complete source text ↓1,870 lines · 60.3 KB
13. [ ] No bright unsuitable yellows checked.
14. [ ] No bright unsuitable greens checked.
### PWA manifest (if applicable)
15. [ ] manifest.json includes theme_color.
16. [ ] manifest theme_color matches meta theme-color.
17. [ ] manifest includes background_color (splash screen).
18. [ ] manifest icons provided (multiple sizes).
### iOS specific tags (if PWA)
19. [ ] `apple-mobile-web-app-capable` present.
20. [ ] `apple-mobile-web-app-status-bar-style` configured.
21. [ ] `apple-mobile-web-app-title` set.
22. [ ] `apple-touch-icon` link present.
### Windows specific tags (optional)
23. [ ] `msapplication-TileColor` if Windows tile important.
24. [ ] `msapplication-TileImage` if Windows tile important.
### Color scheme support
25. [ ] `<meta name="color-scheme">` set to match site capability.
26. [ ] Or CSS `color-scheme: light dark;` equivalent.
### Cross browser verification
27. [ ] Tested on Chrome Android.
28. [ ] Tested on Chrome Desktop.
29. [ ] Tested on iOS 26 Safari.
30. [ ] Tested on iOS pre 26 Safari (legacy).
31. [ ] Tested on Firefox.
32. [ ] Tested on Brave or Edge.
### Brand consistency
33. [ ] Theme color matches documented brand primary.
34. [ ] All pages on a site use same theme color (unless intentionally differentiated).
35. [ ] No conflicting theme-color tags (Yoast or similar plugins).
### Bubbles per client documentation
36. [ ] Brand primary documented per client.
37. [ ] Dark mode variant documented per client.
38. [ ] Apple prohibited color check documented.
39. [ ] PWA manifest decision documented.
### Accessibility
40. [ ] Theme color provides good contrast for chrome UI text.
41. [ ] No accessibility concerns flagged by audit tools.
### Cross cutting
42. [ ] No duplicate theme-color tags (multiple in one page).
43. [ ] Theme-color placement appropriate in head (after charset, viewport).
### CMS migration cleanup
44. [ ] Migrated sites have appropriate brand theme-color (not leftover platform color).
45. [ ] WordPress sites that auto generated theme-color have it audited.
A site that passes all 45 has correctly configured theme color for current 2026 browser coverage including iOS 26 Safari workaround.
---
## 19. COMMON PITFALLS
Fifteen patterns to recognize and avoid.
**Pitfall 1: theme-color works on Chrome but not iOS 26 Safari.**
Symptom: Chrome shows brand color in chrome; iOS 26 Safari shows gray.
Why it breaks: iOS 26 Safari dropped theme-color support.
Fix: also set `body { background-color: <brand color>; }` in CSS.
**Pitfall 2: Pure black theme-color ignored by Safari.**
Symptom: `<meta name="theme-color" content="#000000">` doesn't work in Safari.
Why it breaks: Apple's prohibited color list includes pure black.
Fix: use #0a0a0a or #1a1a1a instead.
**Pitfall 3: Bright red theme-color ignored by Safari.**
Symptom: `<meta name="theme-color" content="#FF0000">` doesn't work in Safari.
Why it breaks: Apple's prohibited color list includes bright pure red.
Fix: use a darker or desaturated red, or test with the Safari color checker tool.
**Pitfall 4: Dark mode produces bad contrast.**
Symptom: dark mode user sees brand purple chrome with light system colors; URL hard to read.
Why it breaks: brand color may not have sufficient contrast against UI text in dark mode.
Fix: add dark mode media variant with appropriate dark color.
**Pitfall 5: Multiple conflicting theme-color tags.**
Symptom: page has theme-color from Yoast AND from custom template; browser uses one.
Why it breaks: plugins or templates duplicate the tag.
Fix: remove duplicates; ensure single canonical theme-color.
**Pitfall 6: theme_color in manifest doesn't match meta tag.**
Symptom: standard browsing shows one color; PWA mode shows different color.
Why it breaks: mismatch between meta tag and manifest.
Fix: align both to same value.
**Pitfall 7: Body background doesn't match theme-color (iOS 26 issue).**
Symptom: chrome color set via meta tag; iOS 26 ignores and uses body background.
Why it breaks: body has different background than theme-color.
Fix: set body background-color to match theme-color value.
**Pitfall 8: Fixed element trick breaks on page reload at scroll position.**
Symptom: fixed element provides theme color when at top of page; doesn't work after reload deeper.
Why it breaks: per Ben Frain's analysis; fixed element approach is fragile.
Fix: use body background-color approach instead.
**Pitfall 9: Apple Mobile Web App Capable tag missing.**
Symptom: iOS users add site to home screen; opens in Safari instead of PWA mode.
Why it breaks: iOS PWA mode requires the tag (pre iOS 26; iOS 26 has simplified add to home).
Fix: include `<meta name="apple-mobile-web-app-capable" content="yes">`.
**Pitfall 10: WordPress site auto generated theme-color from plugin.**
Symptom: page has theme-color set to a non brand color.
Why it breaks: SEO or theme plugin set it automatically.
Fix: remove plugin auto generation; add hand crafted theme-color.
**Pitfall 11: theme-color hex with shorthand vs full.**
Symptom: `#FFF` vs `#FFFFFF`; some browsers parse one but not the other.
Why it breaks: hex shorthand support varies (most browsers accept; consistency matters).
Fix: use full 6 character hex format for consistency.
**Pitfall 12: theme-color is rgba() with transparency.**
Symptom: `rgba(107, 70, 193, 0.5)` doesn't work; browsers use opaque only.
Why it breaks: theme-color requires opaque color.
Fix: use opaque hex or rgb without alpha.
**Pitfall 13: msapplication-TileColor and theme-color mismatch.**
Symptom: Windows tile shows different color than mobile chrome.
Why it breaks: separate tags configured independently.
Fix: align both to brand primary.
**Pitfall 14: Brand color renders too dark for chrome text overlay.**
Symptom: very dark brand color makes URL text hard to read against chrome.
Why it breaks: insufficient contrast.
Fix: choose slightly lighter brand variant for theme-color, or use opposite mode pattern.
**Pitfall 15: theme-color not set for the body background, but iOS works.**
Symptom: iOS 26 Safari shows brand color despite no body background set.
Why it breaks: iOS may pick color from another element near top (header, hero).
Fix: explicitly set body background-color for predictable behavior.
---
## 20. DIAGNOSTIC COMMANDS
Reference of commands useful for theme color investigation.
### Inspect a single URL
```bash
# Get all theme-color tags
curl -s https://example.com/ | grep -oE 'meta name="theme-color"[^>]+'
# Get dark mode variant specifically
curl -s https://example.com/ | grep -oE 'meta name="theme-color" content="[^"]+" media="\(prefers-color-scheme: dark\)"'
# Check for body background-color
curl -s https://example.com/ | grep -oE 'body[^{]*\{[^}]*background-color[^}]*\}' | head -3
```
### Get PWA manifest theme color
```bash
# Find manifest link
MANIFEST_URL=$(curl -s https://example.com/ | grep -oE 'link rel="manifest" href="[^"]+"' | sed 's/.*href="\([^"]*\)".*/\1/')
# Download manifest
curl -s "https://example.com${MANIFEST_URL}" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"theme_color: {data.get('theme_color', 'not set')}\")
print(f\"background_color: {data.get('background_color', 'not set')}\")
"
```
### Bulk audit Bubbles client sites
```bash
theme-color-audit.sh
```
### Check for Apple prohibited colors
```bash
URL=$1
TC=$(curl -s "$URL" | grep -oE 'meta name="theme-color" content="[^"]+"' | head -3 | sed 's/.*content="\([^"]*\)".*/\1/')
for color in $TC; do
# Check for pure black
if [ "$color" = "#000000" ] || [ "$color" = "#000" ]; then
echo "WARNING: pure black ($color) detected; Safari prohibits"
fi
# Check for bright pure red, green, yellow
case "$color" in
"#ff0000"|"#FF0000"|"#f00"|"#F00"|"#ffff00"|"#FFFF00"|"#ff0"|"#FF0"|"#00ff00"|"#00FF00"|"#0f0"|"#0F0")
echo "WARNING: bright pure color ($color) likely on Apple prohibited list"
;;
esac
done
```
### Visual inspection
In browser:
1. **Chrome Android**: open page; look at top of screen (URL bar + status area).
2. **iOS 26 Safari**: open page; look at top of screen (compact tab bar).
3. **Toggle dark mode**: verify color changes appropriately.
4. **Inspect element**: check `<meta name="theme-color">` and body background.
In Lighthouse:
```bash
lighthouse https://example.com/ \
--only-audits=themed-omnibox \
--output=json --output-path=/tmp/lh.json --quiet
```
Lighthouse `themed-omnibox` audit checks for theme-color presence and validity.
### Real device testing
Required for iOS 26 verification:
- iPhone or iPad running iOS 26+.
- Open Safari (not Chrome on iOS; same engine but different behavior).
- Browse to the site.
- Observe compact tab bar color.
- Toggle Safari's "Show color in compact tab bar" if needed.
### After changes
```bash
# Reload nginx if static
nginx -t && systemctl reload nginx
# Or restart FastAPI
systemctl restart fastapi-sidecar
# Verify
theme-color-check.sh https://example.com/
```
---
## 21. CROSS-REFERENCES
* [framework-html-meta-viewport.md](framework-html-meta-viewport.md): viewport-fit=cover for notched displays; combined with theme-color for full bleed mobile experience.
* [framework-html-meta-charset.md](framework-html-meta-charset.md): theme-color placement after charset.
* [framework-html-meta-description.md](framework-html-meta-description.md): aligns with meta description in head order.
* [framework-html-meta-generator.md](framework-html-meta-generator.md): the "Hand coded by ThatDeveloperGuy.com" generator tag pairs with brand color theme-color for full brand reinforcement.
* [framework-http-security-headers.md](framework-http-security-headers.md): the Permissions-Policy header can affect color rendering of certain APIs (rare).
* [UNIVERSAL-RANKING-FRAMEWORK.md](UNIVERSAL-RANKING-FRAMEWORK.md): theme color not a ranking signal but polish affects user behavior signals.
* [SEO-BUILD-REFERENCE.md](SEO-BUILD-REFERENCE.md) v2.4: the build playbook including brand color configuration.
* W3C theme-color spec: https://www.w3.org/TR/appmanifest/#theme_color-member
* MDN meta name=theme-color: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color
* MDN HTMLMetaElement.media: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMetaElement/media
* Web App Manifest theme_color: https://developer.mozilla.org/en-US/docs/Web/Manifest/theme_color
* CSS Tricks Meta Theme Color and Trickery: https://css-tricks.com/meta-theme-color-and-trickery/
* Apple Developer Forums on iOS 26 theme-color: https://developer.apple.com/forums/thread/801239
* Ben Frain iOS 26 Safari theme-color analysis: https://benfrain.com/ios26-safari-theme-color-tab-tinting-with-fixed-position-elements/
* grooovinger Define the Theme Color for Safari 26: https://grooovinger.com/notes/2026-02-27-safari-26-header-background
* WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
* Lighthouse themed-omnibox audit: https://web.dev/articles/themed-omnibox
---
## APPENDIX A: ONE PAGE QUICK REFERENCE
For the person who just wants the answer.
### The Bubbles rule
**Include theme-color for Chrome. Match body background for iOS 26 Safari. Include dark mode variant.**
### The canonical pattern
```html
<head>
<meta name="theme-color" content="#6B46C1">
<meta name="theme-color" content="#0a0a0a" media="(prefers-color-scheme: dark)">
<meta name="color-scheme" content="light dark">
</head>
<style>
body {
background-color: #6B46C1;
}
@media (prefers-color-scheme: dark) {
body {
background-color: #0a0a0a;
}
}
</style>
```
### The critical 2026 note
iOS 26 Safari dropped support for `<meta name="theme-color">`. It now reads body/html background color. The body background-color CSS is REQUIRED for iOS 26 coverage.
### The Apple prohibited list
* NO pure black (#000000); use #0a0a0a.
* NO bright pure reds, yellows, greens; use darker variants.
### Bubbles brand colors
* **ThatDeveloperGuy**: purple (#6B46C1) and green; primary purple.
* **TCB Fight Factory**: purple and black; use #6B46C1 primary, #0a0a0a (not pure black).
* Each local client: per client brand color decision documented.
### Five rules to memorize
1. **Include both meta theme-color AND body background CSS (iOS 26 coverage).**
2. **Add dark mode media variant for dark mode users.**
3. **Avoid Apple's prohibited colors (especially pure black).**
4. **Align manifest.json theme_color with meta theme-color if PWA.**
5. **Test on real Chrome Android AND real iOS 26 Safari (simulators may differ).**
### Five commands every operator should know
```bash
# 1. Get theme-color tags from a URL
curl -s URL | grep -oE 'meta name="theme-color"[^>]+'
# 2. Check for prohibited pure black
curl -s URL | grep -E 'theme-color.*#000000\|theme-color.*#000"'
# 3. Audit across all Bubbles client sites
theme-color-audit.sh
# 4. Get PWA manifest theme_color
MANIFEST=$(curl -s URL | grep -oE 'link rel="manifest" href="[^"]+"' | sed 's/.*href="\([^"]*\)".*/\1/')
curl -s "URL${MANIFEST}" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('theme_color'))"
# 5. Apply CSS or template changes
nginx -t && systemctl reload nginx
```
### Three end to end tests
```bash
# 1. theme-color present
URL=https://example.com/
HAS_TC=$(curl -s "$URL" | grep -c 'meta name="theme-color"')
[ "$HAS_TC" -ge "1" ] && echo "OK: theme-color present" || echo "FAIL"
# 2. Body background-color matches (iOS 26 coverage)
TC_COLOR=$(curl -s "$URL" | grep -oE 'meta name="theme-color" content="[^"]+"' | head -1 | sed 's/.*content="\([^"]*\)".*/\1/')
BODY_BG=$(curl -s "$URL" | grep -oE 'body[^{]*\{[^}]*background-color: *[^;]+' | head -1)
echo "theme-color: $TC_COLOR"
echo "body bg: $BODY_BG"
# 3. No Apple prohibited colors
PROHIBITED=$(curl -s "$URL" | grep -E 'theme-color.*content="(#000|#000000|#FF0000|#FFFF00|#00FF00)"')
[ -z "$PROHIBITED" ] && echo "OK: no prohibited colors" || echo "FAIL: $PROHIBITED"
```
If all three pass AND the chrome color displays correctly on real Chrome Android AND real iOS 26 Safari devices, the theme color layer is correctly wired across the 2026 browser landscape.
---
End of framework-html-meta-theme-color.md.