astro-website/DIAGNOSIS_COMPLETE.md

Production Theme Notch Styling Issue - Complete Diagnostic Report

Date: 2026-02-10
Status: ✅ ROOT CAUSE IDENTIFIED
Severity: CRITICAL

---

Quick Summary

The theme notch component on production (https://santhoshj.com) appears as plain buttons in normal document flow instead of a fixed, positioned element in the top-right corner.

Root Cause: The production server is serving a STALE CSS file (17,628 bytes) that was built BEFORE the theme-notch CSS rules were added. The local build correctly generates a 24,279 byte CSS file with all rules.

Fix: Rebuild and redeploy the Docker image with the latest source code.

---

Evidence

1. CSS File Size Mismatch

Metric	Local Build	Production	Status
File size	24,279 bytes	~17,628 bytes	❌ MISMATCH
Difference	-	-6,651 bytes (27% smaller)	❌ CRITICAL
theme-notch rules	30 matches	0 matches	❌ MISSING

2. CSS Rules Comparison

Local CSS (site/dist/styles/global.css):

.theme-notch {
  position: fixed;
  top: var(--theme-notch-top);
  right: max(8px, env(safe-area-inset-right));
  z-index: 12;
  display: flex;
  align-items: center;
  gap: 10px;
  pointer-events: none;
}

.theme-notch-panel {
  position: absolute;
  right: 60px;
  top: 0;
  display: grid;
  gap: 6px;
  padding: 12px;
  border-radius: 16px;
  border: 1px solid var(--stroke-mid);
  background: var(--surface-1);
  opacity: 0;
  transform: translateX(10px) scale(0.98);
  visibility: hidden;
  pointer-events: none;
  transition: opacity 160ms ease, transform 160ms ease, visibility 0s linear 160ms;
}

.theme-notch-handle { ... }
.theme-notch-glyph { ... }
.theme-notch-option { ... }
.theme-notch-dot { ... }
/* + media queries and forced-colors rules */

Production CSS (https://santhoshj.com/styles/global.css):

❌ ZERO matches for .theme-notch*

3. Computed Styles on Production

Property	Actual	Expected	Status
.theme-notch position	static	fixed	❌ WRONG
.theme-notch top	auto	84px	❌ WRONG
.theme-notch right	auto	max(8px, env(...))	❌ WRONG
.theme-notch z-index	auto	12	❌ WRONG
.theme-notch-panel position	static	absolute	❌ WRONG
.theme-notch-panel display	block	grid	❌ WRONG
.theme-notch-panel opacity	1	0 (initially)	❌ WRONG
.theme-notch-panel visibility	visible	hidden (initially)	❌ WRONG

4. HTML Markup Status

✅ Present and correct on both local and production:

• <aside class="theme-notch" aria-label="Theme" data-theme-notch="" data-open="false">
• <div class="theme-notch-panel" id="theme-notch-panel" role="radiogroup" aria-label="Theme selector">
• <button class="theme-notch-option" data-theme-option="dark|light|contrast" role="radio" aria-checked="...">
• SVG glyph present in .theme-notch-glyph

5. JavaScript Execution

✅ Inline scripts ARE executing (no CSP block):

• Theme initialization script runs
• Service worker registration attempted
• Navigation toggle script runs
• Image lazy-load script runs

Console errors (unrelated to theme-notch CSS):

• [ERROR] An unknown error occurred when fetching the script (service worker)
• [ERROR] Failed to load resource: net::ERR_INSUFFICIENT_RESOURCES (analytics)

6. Network & Caching

• ✅ /styles/global.css returns [200] OK
• ✅ File loads successfully
• ❌ Content is stale/outdated

---

What's Working

✅ HTML markup is present and correct
✅ JavaScript is executing without CSP errors
✅ Local development (npm run dev) works perfectly
✅ Local build (npm run build) generates correct CSS
✅ Network requests succeed
✅ Accessibility tree shows correct structure

---

What's Broken

❌ Production CSS file is missing theme-notch rules
❌ CSS file size doesn't match local build
❌ Theme notch appears inline instead of fixed position
❌ Theme notch dropdown panel is not hidden initially
❌ Theme notch styling is completely absent

---

Root Cause Analysis

The Problem

The production Docker image contains an OLDER version of the CSS file that was built BEFORE the theme-notch CSS rules were added to the source.

Why This Happened

1. The theme-notch CSS rules exist in the source (site/public/styles/global.css)
2. The local build correctly includes them in the output (site/dist/styles/global.css - 24,279 bytes)
3. BUT the production Docker image contains an older version of the CSS file (~17,628 bytes)
4. This suggests:
   • The Docker image was built from an older commit
   • OR the CSS file was not updated in the Docker image
   • OR there's a stale build artifact being served

This is a DEPLOYMENT/CACHING issue, not a build issue

---

Verification Performed

✅ Navigated to https://santhoshj.com and /blog
✅ Captured console errors and warnings
✅ Checked network requests (global.css loads with [200])
✅ Fetched and parsed production CSS file
✅ Searched for .theme-notch selectors (0 matches found)
✅ Inspected computed styles via browser DevTools
✅ Verified HTML markup is present and correct
✅ Confirmed inline scripts execute without CSP errors
✅ Compared with local source CSS (rules present locally)
✅ Ran local build and verified CSS includes theme-notch rules
✅ Compared file sizes (24,279 bytes local vs ~17,628 bytes production)

---

Recommended Fix

Option 1: Rebuild and redeploy Docker image (RECOMMENDED)

# In the project root
docker compose build --no-cache
docker compose push
# Deploy new image to production

Option 2: If using CI/CD

• Ensure the latest commit is being built
• Verify the Docker build includes the latest site/dist/ output
• Check that the image is being pushed with the correct tag
• Redeploy the image to production

Option 3: Quick verification before deploying

# SSH into production server
# Check CSS file size
ls -lh /usr/share/nginx/html/styles/global.css
# Should show ~24,279 bytes (not ~17,628)

# Verify theme-notch rules exist
grep -c "theme-notch" /usr/share/nginx/html/styles/global.css
# Should show 30+ matches (not 0)

---

Expected Result After Fix

✅ Theme notch appears as a fixed button in top-right corner
✅ Clicking reveals a dropdown panel with Dark/Light/Contrast options
✅ Smooth animations and hover effects work
✅ CSS file size matches local build (~24,279 bytes)
✅ CSS file contains 30+ matches for "theme-notch"
✅ Computed styles show correct positioning and display properties

---

Files Involved

File	Purpose	Status
site/public/styles/global.css	Source CSS	✅ Contains theme-notch rules (lines 306-457)
site/dist/styles/global.css	Local build output	✅ 24,279 bytes, 30 theme-notch matches
https://santhoshj.com/styles/global.css	Production	❌ ~17,628 bytes, 0 theme-notch matches
Dockerfile	Docker build	⚠️ Copies from site/dist/
site/src/components/BaseLayout.astro	HTML template	✅ Renders theme-notch markup

---

Summary Table

Aspect	Local	Production	Status
CSS file exists	✅ Yes	✅ Yes	OK
File size	24,279 bytes	~17,628 bytes	❌ MISMATCH
theme-notch rules	30 matches	0 matches	❌ MISSING
HTML markup	✅ Present	✅ Present	OK
JavaScript	✅ Executing	✅ Executing	OK
Computed styles	✅ Correct	❌ Wrong	BROKEN
Visual result	✅ Fixed notch	❌ Inline buttons	BROKEN

---

Conclusion

The issue is NOT:

• ❌ CSP blocking inline scripts
• ❌ Missing HTML markup
• ❌ JavaScript not executing
• ❌ Browser caching

The issue IS:

• ✅ Production CSS file missing .theme-notch rules
• ✅ Stale Docker image serving outdated CSS
• ✅ Deployment/caching issue, not a build issue

Action Required:

Rebuild and redeploy Docker image with latest source code.

---

Next Steps

1. Verify the fix: Rebuild Docker image with latest source
2. Deploy: Pu