tractatus/PERPLEXITY_TECHNICAL_BRIEF_FAQ_SCROLLBAR.md

# Technical Brief: FAQ Modal Scrollbar Issue

**Date**: 2025-10-14
**Project**: Tractatus AI Safety Framework
**URL**: https://agenticgovernance.digital/faq.html
**Requesting AI**: Claude Code (Sonnet 4.5)
**Target AI**: Perplexity or other web-capable AI assistant

---

## PROBLEM STATEMENT

User reports FAQ modal scrollbar is not visible/functional. Modal shows only ~8 FAQ questions when 28+ exist in the DOM. User cannot access remaining content.

**User quote**: "there is no scroll slider showing in production"

---

## CURRENT STATE (2025-10-14 00:30 UTC)

### Modal Structure
```html
<!-- File: public/faq.html line 514-596 -->
<div id="search-modal" class="fixed inset-0 bg-black bg-opacity-50 z-50 hidden items-center justify-center p-4">
  <div class="bg-white rounded-lg shadow-2xl max-w-4xl w-full h-[85vh] flex flex-col">
    <!-- Modal Header -->
    <div class="flex items-center justify-between p-6 border-b border-gray-200 flex-shrink-0">
      <h2 class="text-2xl font-bold text-gray-900">Search FAQ</h2>
      <button id="search-modal-close-btn">Close</button>
    </div>

    <!-- Modal Content - Scrollable Area -->
    <div class="flex-1 modal-scrollable min-h-0">
      <div id="search-modal-content" class="p-6">
        <!-- Search input, filters, etc -->

        <div id="search-results-modal" class="mt-6">
          <div id="faq-container-modal" class="space-y-4">
            <!-- 28+ FAQ items rendered here by JavaScript -->
          </div>
        </div>
      </div>
    </div>
  </div>
</div>
```

### CSS Applied
```css
/* File: public/faq.html lines 295-316 */
.modal-scrollable {
  overflow-y: scroll !important;
  scrollbar-width: thin; /* Firefox */
  scrollbar-color: #9ca3af #f3f4f6; /* Firefox: thumb track */
}

/* Webkit browsers (Chrome, Safari, Edge) */
.modal-scrollable::-webkit-scrollbar {
  width: 10px;
  background-color: #f3f4f6;
}

.modal-scrollable::-webkit-scrollbar-thumb {
  background-color: #9ca3af;
  border-radius: 5px;
  border: 2px solid #f3f4f6;
}

.modal-scrollable::-webkit-scrollbar-thumb:hover {
  background-color: #6b7280;
}
```

### JavaScript Rendering
```javascript
// File: public/js/faq.js lines 3082-3139
function renderFAQs() {
  const container = document.getElementById('faq-container-modal');
  // Filters FAQ_DATA array (28+ items)
  // Renders ALL filtered items to container
  container.innerHTML = filtered.map(faq => createFAQItemHTML(faq)).join('');
  // Event delegation for click handlers
}
```

**Verified**: All 28+ FAQs ARE in the DOM when modal opens (confirmed by previous Claude session).

---

## WHAT HAS BEEN TRIED (All Failed)

1. ❌ Changed `max-h-[85vh]` to `h-[85vh]` on modal container
2. ❌ Added `overflow-hidden` to parent container
3. ❌ Added `flex-shrink-0` to modal header
4. ❌ Added `min-h-0` to scrollable div
5. ❌ Changed `overflow-y-auto` to `overflow-y-scroll`
6. ❌ Added nested scrollable wrapper structure
7. ❌ Added explicit webkit scrollbar CSS (current state)
8. ❌ Combined Tailwind `overflow-y-scroll` with custom `modal-scrollable`
9. ❌ Removed Tailwind class, using only custom `modal-scrollable`

**All changes deployed to production, server restarted, user confirms issue persists.**

---

## TECHNICAL ENVIRONMENT

**Stack**:
- Frontend: Vanilla JavaScript (no framework)
- CSS: Tailwind CSS 3.x + custom styles
- Server: Node.js/Express on Ubuntu 22.04
- Reverse proxy: Nginx 1.18.0

**Browser Cache**:
- Headers: `cache-control: no-cache, no-store, must-revalidate`
- User performing hard refresh (Ctrl+Shift+R)
- HTML last-modified: `2025-10-14 00:20:59 GMT`

**Flexbox Layout**:
- Outer modal: `h-[85vh] flex flex-col` (constrains height)
- Header: `flex-shrink-0` (fixed height)
- Scrollable area: `flex-1 modal-scrollable min-h-0` (should take remaining space)
- Content: `p-6` (padding inside scrollable area)

---

## DIAGNOSTIC QUESTIONS FOR PERPLEXITY

1. **Is there a known CSS issue with Flexbox + overflow-y where the scrollbar doesn't appear despite content overflowing?**

2. **Could the issue be the scrollable div containing BOTH the search inputs AND the FAQ results?**
   - Should the scrollable area be ONLY the `#faq-container-modal` div?
   - Is the padding/margin from search inputs affecting overflow detection?

3. **Is `min-h-0` on a flex item sufficient, or do we need additional flex constraints?**

4. **Could there be a z-index issue where the scrollbar is rendered but not interactive?**

5. **Should we move scrolling from the outer wrapper to the inner container?**
   ```html
   <!-- Option A (current): -->
   <div class="flex-1 modal-scrollable min-h-0">
     <div id="search-modal-content" class="p-6">
       <!-- content -->
     </div>
   </div>

   <!-- Option B (alternative): -->
   <div class="flex-1 overflow-hidden">
     <div id="search-modal-content" class="p-6 h-full overflow-y-scroll modal-scrollable">
       <!-- content -->
     </div>
   </div>
   ```

6. **Are there known issues with Tailwind's arbitrary values like `h-[85vh]` in flex containers?**

7. **Could browser-specific scrollbar hiding (macOS "show scrollbar only when scrolling") be overriding our explicit webkit styles?**

8. **Is there a working example of a similar modal structure (fixed header + scrollable content in flexbox) that we could reference?**

---

## SUCCESS CRITERIA

1. User can SEE a scrollbar in the FAQ modal (or can clearly scroll without a visible bar)
2. User can scroll through all 28+ FAQ questions
3. Works in Chrome, Firefox, Safari
4. Scrollbar is always visible (not just on hover/scroll)

---

## NEXT STEPS REQUESTED

Please provide:
1. **Root cause analysis**: What is actually preventing scrolling?
2. **Working CSS solution**: Exact HTML/CSS structure that will work
3. **Explanation**: Why previous attempts failed
4. **Alternative approaches**: If CSS alone won't work, what else?

---

## REPOSITORY ACCESS

- **Production URL**: https://agenticgovernance.digital/faq.html
- **Local testing**: http://localhost:9000/faq.html
- **Relevant files**:
  - `public/faq.html` (lines 514-596: modal structure, lines 295-316: scrollbar CSS)
  - `public/js/faq.js` (lines 3082-3139: FAQ rendering)

---

## CONTACT

This technical brief was generated by Claude Code (Anthropic) on behalf of user "theflow" who needs to resolve this critical UX issue blocking access to site content.

**User's position**: Ready to consult external AI if Claude cannot resolve after multiple attempts.

---

**Priority**: HIGH - User blocked from accessing 75% of FAQ content