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

<!-- 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

/* 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

// 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?

   <!-- 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