docs: add journal entry for modal CSS architecture overhaul

journal.rst

@@ -118,4 +118,112 @@ src/languages/
 - **Developer experience**: Automated verification prevents translation drift
 - **Scalability**: Easy to add new languages following the established pattern
 
-This system supports the full user journey from language detection to dynamic interface updates, ensuring a seamless multilingual experience for all Hermes AI users.
+This system supports the full user journey from language detection to dynamic interface updates, ensuring a seamless multilingual experience for all Hermes AI users.
+
+July 9, 2025
+============
+
+Modal CSS Architecture Overhaul & Translation Page Fix
+-------------------------------------------------------
+
+**The Problem**
+
+User feedback revealed that the PicoCSS version of the UncloseAI modal was filling the entire screen on large laptop displays, which users found jarring. Additionally, translated pages opened in new windows had broken CSS styling, making them unusable.
+
+**Root Cause Analysis**
+
+Two critical issues were identified:
+
+1. **Inconsistent CSS Loading Logic**: Different modal files used different approaches:
+   - Some used ``window.UNCLOSEAI_CUSTOM_STYLING`` flag (fragile)
+   - Others used actual PicoCSS detection via ``document.querySelector('link[href*="pico"]')`` (robust)
+   - Mix of relative paths (``./src/``) and absolute URLs (``https://uncloseai.com/src/``)
+
+2. **Modal Sizing Override Issues**: PicoCSS dialog defaults were overriding our modal sizing with ``!important`` declarations
+
+**Solution Implementation**
+
+**Phase 1: CSS Architecture Refactoring**
+
+Moved all inline styles from JavaScript files into two dedicated CSS files:
+
+- ``src/uncloseai-modal-builtin.css`` - Clean styles for blog versions without PicoCSS
+- ``src/uncloseai-modal-pico.css`` - Override styles with ``!important`` declarations for PicoCSS sites
+
+**Consolidated Modal Styles:**
+- Hermes AI modal (main chat interface)
+- Translation modal (text & page translation)
+- TTS modal (text-to-speech interface)  
+- Widget library components (chat widgets, dropdowns)
+
+**Phase 2: PicoCSS Override Strategy**
+
+Used CSS specificity and ``!important`` declarations to override PicoCSS dialog defaults:
+
+```css
+/* Override PicoCSS positioning that sets top:0, left:0, right:0, bottom:0 */
+dialog#uncloseai-embedded-modal[data-theme] {
+  position: fixed !important;
+  top: 50% !important;
+  left: 50% !important;
+  transform: translate(-50%, -50%) !important;
+  width: 70vw !important;
+  max-width: 800px !important;
+  height: 90vh !important;
+}
+```
+
+**Phase 3: Consistent CSS Loading Pattern**
+
+Standardized all modal files to use:
+
+1. **PicoCSS Detection**: ``document.querySelector('link[href*="pico"]') !== null``
+2. **Absolute URLs**: ``https://uncloseai.com/src/${cssFile}``
+3. **Proper Mobile Handling**: 480px breakpoint instead of 768px
+
+**Phase 4: Translation Page CSS Fix**
+
+Fixed broken CSS in translated pages by:
+
+1. **Base Tag Approach**: Added ``<base href="${baseUrl}">`` to resolve relative URLs
+2. **Consistent Loading**: Updated translate-modal.js to use the same CSS loading pattern
+3. **Cross-Window Compatibility**: Ensured CSS loads properly in new window contexts
+
+**Technical Details**
+
+**Files Modified:**
+- ``src/uncloseai-embed-modal.js`` - Main modal CSS loading
+- ``src/translate-modal.js`` - Translation modal CSS loading  
+- ``src/tts-modal.js`` - TTS modal CSS loading
+- ``src/widget-library.js`` - Widget CSS loading
+- ``src/translation.js`` - Base tag injection for new windows
+
+**CSS Detection Logic:**
+```javascript
+// Detect if PicoCSS is actually present on the page
+const hasPicoCSS = document.querySelector('link[href*="pico"]') !== null;
+
+// Load appropriate CSS based on actual PicoCSS presence
+const cssFile = hasPicoCSS ? 'uncloseai-modal-pico.css' : 'uncloseai-modal-builtin.css';
+
+if (!document.querySelector(`link[href*="${cssFile}"]`)) {
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = `https://uncloseai.com/src/${cssFile}`;
+  document.head.appendChild(link);
+}
+```
+
+**Mobile Responsiveness:**
+- Desktop: Centered modal with 70vw width, 800px max-width
+- Mobile (≤480px): Full-screen modal for touch interfaces
+
+**Results**
+
+✅ **Modal Sizing Fixed**: No more full-screen modals on large displays
+✅ **CSS Architecture Clean**: All inline styles moved to dedicated CSS files  
+✅ **Cross-Site Compatibility**: Consistent behavior on blog sites and PicoCSS sites
+✅ **Translation Pages Fixed**: Proper CSS loading in new window contexts
+✅ **Developer Experience**: Maintainable CSS architecture with clear separation of concerns
+
+This refactoring resolved the immediate user experience issues while establishing a robust, maintainable CSS architecture that prevents similar problems in the future.