A continuation of Janady13/crawler-signal-reference / framework-html-meta-color-scheme.md. The complete source identity, every recorded occurrence, and linked equations are on its first page.
Source transcript · continued
Download complete source text ↓1,926 lines · 57.5 KB
# /opt/bubbles/services/example.com/client_config.py
CLIENT_COLOR_SCHEMES = {
"thatdeveloperguy": {
"scheme": "dark light",
"brand_primary": "#6B46C1",
"brand_dark": "#0a0a0a",
},
"tcb_fight_factory": {
"scheme": "dark light",
"brand_primary": "#6B46C1",
"brand_dark": "#0a0a0a",
},
"arkansas_counseling": {
"scheme": "light dark",
"brand_primary": "#calm_color_here",
"brand_dark": "#calm_dark_here",
},
"handled_tax": {
"scheme": "light dark",
"brand_primary": "#prof_color_here",
"brand_dark": "#prof_dark_here",
},
# ... per client
}
```
### 17.3 The Audit Workflow
```bash
# Weekly across all sites
color-scheme-audit.sh
# After template changes
nginx -t && systemctl reload nginx
systemctl restart fastapi-sidecar
```
### 17.4 The Verification Per Page
```bash
# /usr/local/bin/color-scheme-check.sh
URL=$1
echo "=== Color scheme check for $URL ==="
CS=$(curl -s "$URL" | grep -oE 'meta name="color-scheme" content="[^"]+"' | head -1)
echo "color-scheme meta: ${CS:-NOT SET}"
CSS_PROP=$(curl -s "$URL" | grep -oE 'color-scheme: *[a-z ]+' | head -1)
echo "CSS color-scheme property: ${CSS_PROP:-NOT SET}"
DARK_CSS=$(curl -s "$URL" | grep -c "prefers-color-scheme: dark")
echo "Dark mode CSS occurrences: $DARK_CSS"
if [ "$DARK_CSS" -gt "0" ] && [ -z "$CS" ] && [ -z "$CSS_PROP" ]; then
echo "PROBLEM: dark mode CSS without color-scheme declaration"
elif [ -n "$CS" ] || [ -n "$CSS_PROP" ]; then
echo "OK: color-scheme declared"
else
echo "INFO: light only (no dark mode)"
fi
```
---
## 18. AUDIT CHECKLIST
Run through these 35 items for production deployment.
### Core meta tag
1. [ ] `<meta name="color-scheme">` present on dual mode sites.
2. [ ] Value is appropriate per site design.
3. [ ] Value placement is early in `<head>` (after charset and viewport).
### Value choice
4. [ ] `light dark` used for sites with light default.
5. [ ] `dark light` used for sites with dark default (e.g., Joseph's tech sites).
6. [ ] `only light` used only when overriding system dark mode is intentional.
7. [ ] `only dark` used only when overriding system light mode is intentional.
### CSS alignment
8. [ ] CSS dark mode media queries present where color-scheme allows dark.
9. [ ] CSS variables for background, color, brand defined per scheme.
10. [ ] Body uses CSS variables (not hard coded colors).
### Form controls
11. [ ] Native form controls verified to adapt (date picker, scrollbar).
12. [ ] Text inputs and textareas have CSS dark mode rules.
13. [ ] Buttons have CSS dark mode rules.
### Canvas color
14. [ ] Overscroll area adopts dark canvas in dark mode.
15. [ ] No white flash when scrolling past content.
### FOIC prevention
16. [ ] Meta tag in head (parsed early).
17. [ ] Inline critical CSS for above the fold styling.
18. [ ] No flash of incorrect color observed on real device test.
### theme-color coordination
19. [ ] theme-color set for chrome (per framework-html-meta-theme-color.md).
20. [ ] theme-color dark mode variant set.
21. [ ] Body background-color matches theme-color (iOS 26 coverage).
### Browser testing
22. [ ] Chrome Android: scheme works.
23. [ ] iOS Safari: scheme works (form controls, canvas).
24. [ ] Firefox: scheme works.
25. [ ] Brave/Edge: scheme works.
### Color scheme transitions
26. [ ] User toggling system dark mode: page adapts.
27. [ ] No JavaScript required for basic scheme switching.
### Documentation
28. [ ] color-scheme decision documented per client.
29. [ ] Pairing with theme-color documented.
30. [ ] Dark mode design rationale documented.
### CSS conventions
31. [ ] Single canonical CSS for dark mode (no fragments).
32. [ ] CSS variables used (not duplicate selectors per scheme).
### Cross cutting
33. [ ] Pages with no dark mode have appropriate color-scheme (light or omit).
34. [ ] noindex pages don't need elaborate dark mode handling.
35. [ ] Print stylesheet considers neither scheme (light by default).
A site that passes all 35 has correctly configured color-scheme for cross browser dark mode compatibility, FOIC prevention, and native form control consistency.
---
## 19. COMMON PITFALLS
Twelve patterns to recognize and avoid.
**Pitfall 1: Dark mode CSS without color-scheme declaration.**
Symptom: page body turns dark, but scrollbars, date pickers, canvas stay light.
Why it breaks: browser doesn't know page supports dark mode.
Fix: add `<meta name="color-scheme" content="light dark">`.
**Pitfall 2: Confusing color-scheme and theme-color.**
Symptom: `<meta name="color-scheme" content="#6B46C1">` or `<meta name="theme-color" content="light dark">`.
Why it breaks: wrong value type for the wrong meta tag.
Fix: color-scheme takes scheme keywords; theme-color takes color values.
**Pitfall 3: color-scheme value with comma separator.**
Symptom: `<meta name="color-scheme" content="light, dark">` (with comma).
Why it breaks: spec requires space separated, not comma.
Fix: `<meta name="color-scheme" content="light dark">`.
**Pitfall 4: Hard coded background colors throughout CSS.**
Symptom: changing scheme doesn't affect most elements.
Why it breaks: CSS uses `background: white` not `background: var(--bg)`.
Fix: use CSS variables for all themeable colors.
**Pitfall 5: color-scheme with `light` value on a site that supports dark.**
Symptom: site has dark mode CSS but color-scheme says light only.
Why it breaks: contradictory signals; browser confused.
Fix: change color-scheme to `light dark`.
**Pitfall 6: color-scheme on body but expected to affect root.**
Symptom: `<body style="color-scheme: light dark">` instead of root.
Why it breaks: scope is body only; html root and canvas not affected.
Fix: place on `:root` or `html`, or use meta tag.
**Pitfall 7: Force dark on a light only site.**
Symptom: light only site has `color-scheme: dark`. Looks broken.
Why it breaks: form controls and canvas render dark; CSS still light.
Fix: change to `light` or `light dark`.
**Pitfall 8: Color scheme not aligned across iframe boundaries.**
Symptom: iframe content renders in one scheme, parent in another.
Why it breaks: iframes have their own color-scheme; parent doesn't propagate.
Fix: set color-scheme in the iframe content as well.
**Pitfall 9: Print stylesheet doesn't handle color scheme.**
Symptom: printed page renders dark.
Why it breaks: dark mode CSS applies to print.
Fix: explicit print stylesheet with light colors only.
```css
@media print {
body {
background: white !important;
color: black !important;
}
}
```
**Pitfall 10: User's manual override not respected.**
Symptom: user has explicitly chosen dark mode via UI toggle, but system preference overrides.
Why it breaks: CSS uses prefers-color-scheme; ignores user override.
Fix: implement toggle via class or cookie that overrides media query.
**Pitfall 11: color-scheme on multiple roots.**
Symptom: both `<meta name="color-scheme">` and `:root { color-scheme: ... }` with different values.
Why it breaks: undefined behavior; one wins (typically the more specific).
Fix: choose one source of truth; remove the other.
**Pitfall 12: WordPress or CMS auto generating color-scheme.**
Symptom: Yoast or theme plugin sets color-scheme without considering site design.
Why it breaks: plugin doesn't know if dark mode is actually implemented.
Fix: disable plugin auto generation; configure manually.
---
## 20. DIAGNOSTIC COMMANDS
Reference of commands useful for color-scheme investigation.
### Inspect a single URL
```bash
# Get color-scheme meta tag
curl -s https://example.com/ | grep -oE 'meta name="color-scheme" content="[^"]+"'
# Get CSS color-scheme property
curl -s https://example.com/ | grep -oE 'color-scheme: *[a-z]+( +[a-z]+)?' | head -3
# Check for dark mode CSS
curl -s https://example.com/ | grep -c "prefers-color-scheme: dark"
```
### Bulk audit Bubbles client sites
```bash
color-scheme-audit.sh
```
### Verify scheme support coverage
```bash
URL=$1
color-scheme-check.sh "$URL"
```
### Cross check with theme-color
```bash
URL=$1
echo "=== Both schemes coordinated for $URL ==="
CS=$(curl -s "$URL" | grep -oE 'meta name="color-scheme" content="[^"]+"' | head -1)
TC=$(curl -s "$URL" | grep -oE 'meta name="theme-color" content="[^"]+"' | head -1)
echo "color-scheme: ${CS:-MISSING}"
echo "theme-color: ${TC:-MISSING}"
if [ -n "$CS" ] && [ -z "$TC" ]; then
echo "WARNING: color-scheme without theme-color"
fi
if [ -z "$CS" ] && [ -n "$TC" ]; then
echo "WARNING: theme-color without color-scheme"
fi
```
### Browser DevTools verification
In Chrome DevTools:
1. Open the page.
2. Open Rendering panel (More Tools > Rendering).
3. Look for "Emulate CSS media feature prefers-color-scheme".
4. Toggle between light, dark, no-preference.
5. Verify page adapts (or stays per `only` declarations).
In Safari DevTools (for iOS Safari):
1. Open the page in iOS Safari.
2. Connect Mac Safari Web Inspector.
3. Develop > [Device] > [Page].
4. Use the Color Scheme override.
5. Verify scheme adaptation.
### Visual testing
For each Bubbles client site:
1. Set system to dark mode.
2. Load the page.
3. Observe:
- Is there a flash of light content?
- Is the scrollbar dark?
- If forms present: are inputs dark? Are date pickers dark?
- Overscroll to see canvas: is it dark?
4. Toggle to light mode.
5. Verify all of the above switches to light.
### After configuration changes
```bash
nginx -t && systemctl reload nginx
systemctl restart fastapi-sidecar
# Verify
color-scheme-check.sh https://example.com/
```
---
## 21. CROSS-REFERENCES
* [framework-html-meta-theme-color.md](framework-html-meta-theme-color.md): distinct from color-scheme; declares chrome color rather than scheme support. The two work together.
* [framework-html-meta-viewport.md](framework-html-meta-viewport.md): viewport-fit=cover for notched displays; combined with color-scheme for full bleed mobile.
* [framework-html-meta-charset.md](framework-html-meta-charset.md): place color-scheme after charset and viewport.
* [framework-html-meta-description.md](framework-html-meta-description.md): order in head (charset, viewport, color-scheme, description).
* [UNIVERSAL-RANKING-FRAMEWORK.md](UNIVERSAL-RANKING-FRAMEWORK.md): color-scheme not ranking but user experience signals matter.
* [SEO-BUILD-REFERENCE.md](SEO-BUILD-REFERENCE.md) v2.4: the build playbook including color scheme decisions per client.
* W3C CSS Color Adjustment Module Level 1: https://www.w3.org/TR/css-color-adjust-1/
* MDN meta name=color-scheme: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/color-scheme
* MDN CSS color-scheme property: https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme
* MDN prefers-color-scheme media query: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
* Can I Use color-scheme: https://caniuse.com/?search=color-scheme
* CSS Tricks Color Scheme: https://css-tricks.com/come-to-the-light-dark-side/
---
## APPENDIX A: ONE PAGE QUICK REFERENCE
For the person who just wants the answer.
### The Bubbles rule
**Include `<meta name="color-scheme" content="light dark">` on every site with dark mode CSS. Pair with theme-color for chrome.**
### The canonical patterns
```html
<!-- Standard light first (most clients) -->
<meta name="color-scheme" content="light dark">
<!-- Dark first (Joseph's tech sites, TCB) -->
<meta name="color-scheme" content="dark light">
<!-- Light only (no dark support) -->
<meta name="color-scheme" content="light">
<!-- Or omit entirely -->
<!-- Force light on dark mode systems -->
<meta name="color-scheme" content="only light">
<!-- Force dark on light mode systems -->
<meta name="color-scheme" content="only dark">
```
### The relationship with theme-color
| Tag | What it declares | Value type |
|---|---|---|
| `color-scheme` | Which schemes the page supports | scheme keywords (light, dark, both) |
| `theme-color` | Specific chrome color | CSS color value |
Both should be set on dual mode sites.
### Five rules to memorize
1. **color-scheme declares support; theme-color declares chrome color.**
2. **For dual mode sites: `light dark` (or `dark light` for dark first).**
3. **Place in `<head>` early (after charset and viewport).**
4. **Pair with CSS dark mode media queries.**
5. **Use CSS variables for themeable colors (no hard coded backgrounds).**
### Five commands every operator should know
```bash
# 1. Get color-scheme for a URL
curl -s URL | grep -oE 'meta name="color-scheme"[^>]+'
# 2. Check for CSS dark mode
curl -s URL | grep -c "prefers-color-scheme: dark"
# 3. Audit across all Bubbles client sites
color-scheme-audit.sh
# 4. Cross check with theme-color
URL=https://example.com/
echo "color-scheme: $(curl -s "$URL" | grep -oE 'meta name="color-scheme"[^>]+' | head -1)"
echo "theme-color: $(curl -s "$URL" | grep -oE 'meta name="theme-color"[^>]+' | head -1)"
# 5. Apply changes
nginx -t && systemctl reload nginx
systemctl restart fastapi-sidecar
```
### Three end to end tests
```bash
# 1. color-scheme declared
URL=https://example.com/
CS=$(curl -s "$URL" | grep -c 'meta name="color-scheme"')
[ "$CS" -ge "1" ] && echo "OK: color-scheme declared" || echo "FAIL"
# 2. Coordination with theme-color
TC=$(curl -s "$URL" | grep -c 'meta name="theme-color"')
[ "$TC" -ge "1" ] && [ "$CS" -ge "1" ] && echo "OK: both tags present" || echo "FAIL"
# 3. No mismatch (dark CSS without color-scheme)
DARK_CSS=$(curl -s "$URL" | grep -c "prefers-color-scheme: dark")
if [ "$DARK_CSS" -gt "0" ] && [ "$CS" = "0" ]; then
echo "FAIL: dark mode CSS without color-scheme declaration"
else
echo "OK: no mismatch"
fi
```
If all three pass AND form controls (date pickers, scrollbars) verified to adapt to scheme AND no FOIC on real device, the color-scheme layer is correctly wired.
---
End of framework-html-meta-color-scheme.md.