astro-website/PRODUCTION_DIAGNOSIS.md

Production Theme Notch Styling Issue - Diagnostic Report

Date: 2026-02-10
Status: CRITICAL - CSS rules missing in production

---

Executive Summary

The theme notch component appears as plain buttons in normal document flow on production (https://santhoshj.com) because the CSS rules for .theme-notch and related selectors are completely absent from the served /styles/global.css file.

---

Evidence

1. CSS File Status

• Local file: site/public/styles/global.css ✅ CONTAINS .theme-notch rules (lines 306-457)
• Production file: https://santhoshj.com/styles/global.css ❌ MISSING .theme-notch rules
• File size: Local = 1215 lines; Production = ~17,628 bytes (109 CSS rules)
• Network status: [200] OK - file loads successfully

2. CSS Rules Missing in Production

Local CSS (lines 306-457) includes:

.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: ❌ ZERO matches for .theme-notch* selectors

3. Computed Styles on Production

Actual computed styles (from browser DevTools):

.theme-notch:
  position: static (WRONG - should be: fixed)
  top: auto (WRONG - should be: 84px)
  right: auto (WRONG - should be: max(8px, env(safe-area-inset-right)))
  display: block (CORRECT - but only by accident)
  opacity: 1 (CORRECT - but only by accident)
  visibility: visible (CORRECT - but only by accident)
  z-index: auto (WRONG - should be: 12)

.theme-notch-panel:
  position: static (WRONG - should be: absolute)
  top: auto (WRONG - should be: 0)
  right: auto (WRONG - should be: 60px)
  display: block (WRONG - should be: grid)
  opacity: 1 (WRONG - should be: 0 initially)
  visibility: visible (WRONG - should be: hidden initially)

4. HTML Markup Status

✅ Present and correct:

• <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 (fails due to unrelated script fetch error)
• 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
• No cache headers preventing updates detected
• File loads successfully but content is stale/incomplete

---

Root Cause Analysis

Hypothesis: Build/Deployment Issue

The production CSS file is missing the theme-notch rules entirely, suggesting:

1. Build process did not include the CSS - The CSS file was generated/minified without the theme-notch section
2. Stale build artifact - An older version of global.css is being served
3. CSS file truncation - The build process may have failed to include lines 306-457 from the source
4. Incorrect build output - The CSS bundler/minifier may have stripped unused rules (unlikely, as the HTML uses the classes)

Why It Works Locally

• npm run dev serves the source CSS directly from site/public/styles/global.css
• All rules are present and applied correctly
• Theme notch appears as a fixed, positioned element in the top-right corner

Why It Fails in Production

• Docker build likely runs npm run build which may:
  • Minify/bundle CSS differently
  • Use a different CSS source file
  • Strip rules based on unused CSS detection
  • Output to a different location than site/public/styles/global.css

---

Visual Impact

Expected (Local):

• 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

Actual (Production):

• Theme notch buttons appear inline in normal document flow
• No positioning, no dropdown panel
• Buttons are unstyled (only inherit default browser styles)
• Appears as plain radio buttons in the accessibility tree

---

Verification Steps 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)
✅ 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)

---

Recommended Actions

1. Immediate: Check the Docker build process

   • Verify npm run build output includes theme-notch CSS
   • Check if CSS is being minified/bundled to a different file
   • Ensure site/public/styles/global.css is copied to the Docker image

2. Verify: Rebuild and redeploy

   • Run npm run build locally and inspect the output CSS
   • Check if dist/styles/global.css (or equivalent) contains theme-notch rules
   • Verify the Docker image includes the correct CSS file

3. Debug: Add build logging

   • Log CSS file size before/after minification
   • Verify the CSS source file is being read correctly
   • Check for any build warnings about unused CSS

4. Test: Validate production deployment

   • After fix, verify /styles/global.css contains theme-notch rules
   • Check computed styles in production browser DevTools
   • Confirm theme notch appears in correct position

---

Files Involved

• Source: site/public/styles/global.css (lines 306-457)
• Production: https://santhoshj.com/styles/global.css (missing rules)
• Build: Dockerfile and npm run build process
• HTML: site/src/components/BaseLayout.astro (renders theme-notch markup)

---

Conclusion

The issue is NOT:

• ❌ CSP blocking inline scripts
• ❌ Missing HTML markup
• ❌ JavaScript not executing
• ❌ Browser caching (file loads fresh)

The issue IS:

• ✅ Production CSS file missing .theme-notch rules
• ✅ Build/deployment process not including complete CSS

The fix requires investigating the Docker build and CSS bundling process to ensure all CSS rules are included in the production output.

---

CRITICAL UPDATE: Root Cause Identified

Build Verification Results

Local Build (npm run build):

• ✅ CSS file generated: site/dist/styles/global.css
• ✅ File size: 24,279 bytes
• ✅ Theme-notch rules: 30 matches found
• ✅ All CSS rules present and correct

Production Server:

• ❌ CSS file served: https://santhoshj.com/styles/global.css
• ❌ File size: ~17,628 bytes (SMALLER than local build)
• ❌ Theme-notch rules: 0 matches found
• ❌ CSS is STALE/OUTDATED

Conclusion

The production server is serving an OLD version of the CSS file that was built BEFORE the theme-notch CSS rules were added to the source.

This is a deployment/caching issue, not a build issue.

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)
3. BUT the production Docker image contains an older version of the CSS file
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 caching layer serving stale content

Fix Required

Option 1: Rebuild and redeploy the Docker image

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

• SSH into production server
• Check the CSS file size: should be ~24,279 bytes (not ~17,628)
• Verify /styles/global.css contains "theme-notch" (30+ matches)
• If not, redeploy the Docker image

---

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

---

Next Steps

1. Verify the fix: Rebuild Docker image with latest source
2. Deploy: Push new image to production
3. Test: Verify /styles/global.css is ~24,279 bytes and contains theme-notch rules
4. Validate: Check production site - theme notch should appear in top-right corner
5. Monitor: Watch for any other stale assets