samsa/docs/superpowers/plans/2026-03-22-brave-search-frontend-redesign.md

# Brave Search Frontend Redesign — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Redesign the kafka frontend to match Brave Search's layout: three-column results page, category tiles on homepage, and a hybrid preferences system with full-page `/preferences` route.

**Architecture:** CSS Grid for page-level layouts (three-column results, two-column preferences). JavaScript popover for quick settings (theme + engines only). Server-rendered full preferences page with localStorage persistence. Category tiles are static links with category query params.

**Tech Stack:** Go (Go templates), CSS Grid/Flexbox, Vanilla JavaScript (HTMX for search), localStorage for preferences

---

## File Map

| File | Responsibility |
|------|----------------|
| `internal/views/static/css/kafka.css` | Add layout grids, category tiles, sidebar styles, mobile breakpoints |
| `internal/views/templates/index.html` | Add category tiles below search box |
| `internal/views/templates/results.html` | Add left sidebar, restructure for three-column grid |
| `internal/views/templates/preferences.html` | **New** — full preferences page with nav |
| `internal/views/templates/base.html` | No structural changes needed |
| `internal/views/static/js/settings.js` | Reduce popover to theme + engines; add preferences page JS |
| `internal/httpapi/handlers.go` | Add `GET /preferences` and `POST /preferences` handlers |
| `internal/views/views.go` | Add `RenderPreferences` and `tmplPreferences` template |

---

## PHASE 1: CSS Layout Framework

### Task 1: Add CSS Grid Layouts and Breakpoints

**Files:**
- Modify: `internal/views/static/css/kafka.css`

- [ ] **Step 1: Add three-column results layout CSS**

Append to end of `kafka.css`, before the `@media print` block:

```css
/* ============================================================
   Three-Column Results Layout
   ============================================================ */

.results-layout {
  display: grid;
  grid-template-columns: 200px 1fr 240px;
  gap: 2rem;
  align-items: start;
}

.results-layout .left-sidebar {
  position: sticky;
  top: calc(var(--header-height) + 1.5rem);
  max-height: calc(100vh - var(--header-height) - 3rem);
  overflow-y: auto;
}

.results-layout .right-sidebar {
  position: sticky;
  top: calc(var(--header-height) + 1.5rem);
  max-height: calc(100vh - var(--header-height) - 3rem);
  overflow-y: auto;
}

.results-layout .results-column {
  min-width: 0;
}
```

- [ ] **Step 2: Add mobile breakpoints**

```css
/* Tablet: hide left sidebar, two columns */
@media (min-width: 769px) and (max-width: 1024px) {
  .results-layout {
    grid-template-columns: 1fr 220px;
  }
  .results-layout .left-sidebar {
    display: none;
  }
}

/* Mobile: single column, no sidebars */
@media (max-width: 768px) {
  .results-layout {
    grid-template-columns: 1fr;
  }
  .results-layout .left-sidebar,
  .results-layout .right-sidebar {
    display: none;
  }
}
```

- [ ] **Step 3: Add preferences page layout CSS**

```css
/* ============================================================
   Preferences Page Layout
   ============================================================ */

.preferences-layout {
  display: grid;
  grid-template-columns: 200px 1fr;
  gap: 2rem;
  align-items: start;
  padding: 2rem 0;
}

.preferences-nav {
  position: sticky;
  top: calc(var(--header-height) + 1.5rem);
}

.preferences-nav-item {
  display: flex;
  align-items: center;
  gap: 0.6rem;
  padding: 0.6rem 0.75rem;
  border-radius: var(--radius-sm);
  color: var(--text-secondary);
  text-decoration: none;
  font-size: 0.9rem;
  transition: background 0.15s, color 0.15s;
  cursor: pointer;
}

.preferences-nav-item:hover {
  background: var(--bg-tertiary);
  color: var(--text-primary);
}

.preferences-nav-item.active {
  background: var(--accent-soft);
  color: var(--accent);
  font-weight: 500;
}

.preferences-content {
  background: var(--bg);
  border: 1px solid var(--border);
  border-radius: var(--radius-lg);
  padding: 1.5rem;
}

@media (max-width: 768px) {
  .preferences-layout {
    grid-template-columns: 1fr;
  }
  .preferences-nav {
    position: static;
    display: flex;
    overflow-x: auto;
    gap: 0.5rem;
    padding-bottom: 0.5rem;
  }
  .preferences-nav-item {
    white-space: nowrap;
  }
}
```

- [ ] **Step 4: Add category tiles CSS**

```css
/* ============================================================
   Category Tiles
   ============================================================ */

.category-tiles {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(100px, 1fr));
  gap: 1rem;
  margin-top: 2rem;
}

.category-tile {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 0.5rem;
  padding: 1rem 0.5rem;
  border-radius: var(--radius-md);
  text-decoration: none;
  color: var(--text-secondary);
  font-size: 0.85rem;
  transition: background 0.15s, color 0.15s, transform 0.15s, box-shadow 0.15s;
}

.category-tile:hover {
  background: var(--bg-tertiary);
  color: var(--text-primary);
  transform: translateY(-2px);
  box-shadow: var(--shadow-sm);
}

.category-tile-icon {
  font-size: 1.5rem;
  line-height: 1;
}

.category-tile.disabled {
  opacity: 0.5;
  cursor: not-allowed;
  pointer-events: none;
}

@media (max-width: 768px) {
  .category-tiles {
    grid-template-columns: repeat(auto-fill, minmax(80px, 1fr));
    gap: 0.75rem;
  }
  .category-tile {
    padding: 0.75rem 0.25rem;
    font-size: 0.75rem;
  }
  .category-tile-icon {
    font-size: 1.25rem;
  }
}
```

- [ ] **Step 5: Add left sidebar navigation styles**

```css
/* ============================================================
   Left Sidebar (Results Page)
   ============================================================ */

.left-sidebar {
  padding: 0;
}

.sidebar-nav {
  display: flex;
  flex-direction: column;
  gap: 0.25rem;
}

.sidebar-nav-title {
  font-size: 0.7rem;
  font-weight: 600;
  text-transform: uppercase;
  letter-spacing: 0.06em;
  color: var(--text-muted);
  padding: 0.5rem 0.75rem;
  margin-top: 0.5rem;
}

.sidebar-nav-item {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.5rem 0.75rem;
  border-radius: var(--radius-sm);
  color: var(--text-secondary);
  text-decoration: none;
  font-size: 0.875rem;
  transition: background 0.15s, color 0.15s;
}

.sidebar-nav-item:hover {
  background: var(--bg-tertiary);
  color: var(--text-primary);
}

.sidebar-nav-item.active {
  background: var(--accent-soft);
  color: var(--accent);
  font-weight: 500;
}

.sidebar-nav-item-icon {
  font-size: 1rem;
  width: 20px;
  text-align: center;
}

.sidebar-filters {
  margin-top: 1rem;
  padding-top: 1rem;
  border-top: 1px solid var(--border);
}

.sidebar-filter-group {
  margin-bottom: 0.75rem;
}

.sidebar-filter-label {
  font-size: 0.75rem;
  font-weight: 500;
  color: var(--text-muted);
  padding: 0 0.75rem;
  margin-bottom: 0.25rem;
}

.sidebar-filter-option {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.35rem 0.75rem;
  font-size: 0.8rem;
  color: var(--text-secondary);
  cursor: pointer;
  border-radius: var(--radius-sm);
  transition: background 0.15s;
}

.sidebar-filter-option:hover {
  background: var(--bg-tertiary);
}

.sidebar-filter-option input[type="radio"] {
  accent-color: var(--accent);
}

/* Mobile filter chips */
.mobile-filter-chips {
  display: none;
  overflow-x: auto;
  gap: 0.5rem;
  padding: 0.75rem 0;
  -webkit-overflow-scrolling: touch;
}

.mobile-filter-chips::-webkit-scrollbar {
  display: none;
}

.mobile-filter-chip {
  display: inline-flex;
  align-items: center;
  padding: 0.4rem 0.75rem;
  border: 1px solid var(--border);
  border-radius: var(--radius-full);
  font-size: 0.8rem;
  color: var(--text-secondary);
  white-space: nowrap;
  text-decoration: none;
  transition: background 0.15s, border-color 0.15s;
}

.mobile-filter-chip:hover,
.mobile-filter-chip.active {
  background: var(--accent-soft);
  border-color: var(--accent);
  color: var(--accent);
}

@media (max-width: 768px) {
  .mobile-filter-chips {
    display: flex;
  }
}
```

- [ ] **Step 6: Verify CSS changes compile**

Run: `go build ./...`
Expected: No errors

- [ ] **Step 7: Commit**

```bash
git add internal/views/static/css/kafka.css
git commit -m "feat(frontend): add CSS layout framework for three-column results and preferences page"
```

---

## PHASE 2: Results Page Three-Column Layout

### Task 2: Restructure Results Template

**Files:**
- Modify: `internal/views/templates/results.html`
- Modify: `internal/views/views.go`

- [ ] **Step 1: Read current results.html to understand exact content**

Current structure has `.results-layout` grid with `.search-compact` spanning full width, `.results-column`, and `.sidebar`. Need to add left sidebar and restructure grid.

- [ ] **Step 2: Replace results.html content**

Replace the entire file content:

```html
{{define "title"}}{{if .Query}}{{.Query}} — {{end}}{{end}}
{{define "content"}}
<div class="results-layout">
  <!-- Left Sidebar -->
  <aside class="left-sidebar" id="left-sidebar">
    <nav class="sidebar-nav">
      <div class="sidebar-nav-title">Categories</div>
      {{range .Categories}}
      <a href="/search?q={{$.Query | urlquery}}&category={{.}}" class="sidebar-nav-item {{if eq $.ActiveCategory .}}active{{end}}">
        <span class="sidebar-nav-item-icon">{{index $.CategoryIcons .}}</span>
        <span>{{.}}</span>
      </a>
      {{end}}
    </nav>

    <div class="sidebar-filters">
      <div class="sidebar-filter-group">
        <div class="sidebar-filter-label">Time</div>
        {{range .TimeFilters}}
        <label class="sidebar-filter-option">
          <input type="radio" name="time" value="{{.Value}}" {{if eq $.ActiveTime .Value}}checked{{end}}>
          <span>{{.Label}}</span>
        </label>
        {{end}}
      </div>
      <div class="sidebar-filter-group">
        <div class="sidebar-filter-label">Type</div>
        {{range .TypeFilters}}
        <label class="sidebar-filter-option">
          <input type="radio" name="type" value="{{.Value}}" {{if eq $.ActiveType .Value}}checked{{end}}>
          <span>{{.Label}}</span>
        </label>
        {{end}}
      </div>
    </div>
  </aside>

  <!-- Center Column -->
  <div class="results-column">
    <!-- Compact search bar -->
    <div class="search-compact">
      <div class="search-box">
        <form method="GET" action="/search" role="search" id="search-form">
          <input type="text" name="q" id="q" value="{{.Query}}" autocomplete="off" autofocus
            hx-get="/search" hx-target="#results" hx-trigger="keyup changed delay:500ms" hx-include="this">
          <button type="submit" class="search-box-submit" aria-label="Search">
            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
              <circle cx="11" cy="11" r="8"/>
              <path d="m21 21-4.35-4.35"/>
            </svg>
          </button>
        </form>
      </div>
    </div>

    <!-- Mobile filter chips -->
    <div class="mobile-filter-chips">
      <a href="/search?q={{.Query | urlquery}}" class="mobile-filter-chip {{if not .ActiveCategory}}active{{end}}">All</a>
      {{range .Categories}}
      <a href="/search?q={{$.Query | urlquery}}&category={{.}}" class="mobile-filter-chip {{if eq $.ActiveCategory .}}active{{end}}">{{.}}</a>
      {{end}}
    </div>

    <!-- Results inner -->
    {{template "results_inner" .}}
  </div>

  <!-- Right Sidebar -->
  <aside class="right-sidebar" id="sidebar">
    {{if .Suggestions}}
    <div class="sidebar-card">
      <div class="sidebar-title">Related Searches</div>
      <div class="suggestion-list">
        {{range .Suggestions}}<span class="suggestion"><a href="/search?q={{. | urlquery}}">{{.}}</a></span>{{end}}
      </div>
    </div>
    {{end}}

    {{if .UnresponsiveEngines}}
    <div class="sidebar-card">
      <div class="sidebar-title">Engines with issues</div>
      <ul class="unresponsive-engines">
        {{range .UnresponsiveEngines}}<li>{{index . 0}}: {{index . 1}}</li>{{end}}
      </ul>
    </div>
    {{end}}
  </aside>
</div>
{{end}}
```

- [ ] **Step 3: Update PageData struct to include new fields**

Modify `internal/views/views.go` — add to `PageData` struct:

```go
type PageData struct {
    // ... existing fields ...

    // New fields for three-column layout
    Categories       []string
    CategoryIcons    map[string]string
    ActiveCategory   string
    TimeFilters      []FilterOption
    TypeFilters      []FilterOption
    ActiveTime       string
    ActiveType       string
}

// FilterOption represents a filter radio option
type FilterOption struct {
    Label string
    Value string
}
```

- [ ] **Step 4: Update FromResponse to populate new fields**

In `views.go`, update `FromResponse` to populate the new fields:

```go
func FromResponse(resp contracts.SearchResponse, query string, pageno int) PageData {
    pd := PageData{
        // ... existing initialization ...

        // New: categories with icons
        Categories: []string{"all", "news", "images", "videos", "maps", "shopping", "music", "weather"},
        CategoryIcons: map[string]string{
            "all":      "🌐",
            "news":     "📰",
            "images":   "🖼️",
            "videos":   "🎬",
            "maps":     "🗺️",
            "shopping": "🛒",
            "music":    "🎵",
            "weather":  "🌤️",
        },
        ActiveCategory: "all",

        // Time filters
        TimeFilters: []FilterOption{
            {Label: "Any time", Value: ""},
            {Label: "Past hour", Value: "h"},
            {Label: "Past 24 hours", Value: "d"},
            {Label: "Past week", Value: "w"},
            {Label: "Past month", Value: "m"},
            {Label: "Past year", Value: "y"},
        },
        ActiveTime: "",

        // Type filters
        TypeFilters: []FilterOption{
            {Label: "All results", Value: ""},
            {Label: "News", Value: "news"},
            {Label: "Videos", Value: "video"},
            {Label: "Images", Value: "image"},
        },
        ActiveType: "",
    }
    // ... rest of function ...
}
```

- [ ] **Step 5: Register new preferences template**

In `views.go`, add to the `init()` function and add `tmplPreferences`:

```go
var (
    tmplFull       *template.Template
    tmplIndex      *template.Template
    tmplFragment   *template.Template
    tmplPreferences *template.Template
)

func init() {
    tmplFS, _ := fs.Sub(templatesFS, "templates")

    funcMap := template.FuncMap{
        "urlquery": template.URLQueryEscaper,
    }

    tmplFull = template.Must(template.New("").Funcs(funcMap).ParseFS(tmplFS,
        "base.html", "results.html", "results_inner.html", "result_item.html", "video_item.html",
    ))
    tmplIndex = template.Must(template.New("").Funcs(funcMap).ParseFS(tmplFS,
        "base.html", "index.html",
    ))
    tmplFragment = template.Must(template.New("").Funcs(funcMap).ParseFS(tmplFS,
        "results_inner.html", "result_item.html", "video_item.html",
    ))
    tmplPreferences = template.Must(template.New("").Funcs(funcMap).ParseFS(tmplFS,
        "base.html", "preferences.html",
    ))
}
```

- [ ] **Step 6: Add RenderPreferences function**

Add to `views.go`:

```go
// RenderPreferences renders the full preferences page.
func RenderPreferences(w http.ResponseWriter, sourceURL string) error {
    w.Header().Set("Content-Type", "text/html; charset=utf-8")
    return tmplPreferences.ExecuteTemplate(w, "base", PageData{ShowHeader: true, SourceURL: sourceURL})
}
```

- [ ] **Step 7: Test compilation**

Run: `go build ./...`
Expected: No errors

- [ ] **Step 8: Commit**

```bash
git add internal/views/views.go internal/views/templates/results.html
git commit -m "feat(frontend): add three-column results layout with left sidebar navigation"
```

---

## PHASE 3: Homepage Category Tiles

### Task 3: Add Category Tiles to Homepage

**Files:**
- Modify: `internal/views/templates/index.html`

- [ ] **Step 1: Read current index.html**

- [ ] **Step 2: Replace index.html with tiles**

```html
{{define "title"}}{{end}}
{{define "content"}}
<div class="search-hero">
  <div class="hero-logo">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <circle cx="11" cy="11" r="8"/>
      <path d="m21 21-4.35-4.35"/>
    </svg>
  </div>
  <p class="hero-tagline">Search the web privately, without tracking or censorship.</p>
  <div class="search-box">
    <form method="GET" action="/search" role="search" id="search-form">
      <input type="text" name="q" id="q" placeholder="Search the web…" autocomplete="off" autofocus>
      <button type="submit" class="search-box-submit" aria-label="Search">
        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
          <circle cx="11" cy="11" r="8"/>
          <path d="m21 21-4.35-4.35"/>
        </svg>
      </button>
    </form>
  </div>

  <!-- Category Tiles -->
  <div class="category-tiles">
    <a href="/search" class="category-tile">
      <span class="category-tile-icon">🌐</span>
      <span>All</span>
    </a>
    <a href="/search?category=images" class="category-tile">
      <span class="category-tile-icon">🖼️</span>
      <span>Images</span>
    </a>
    <a href="/search?category=news" class="category-tile">
      <span class="category-tile-icon">📰</span>
      <span>News</span>
    </a>
    <a href="/search?category=videos" class="category-tile">
      <span class="category-tile-icon">🎬</span>
      <span>Videos</span>
    </a>
    <a href="/search?category=maps" class="category-tile">
      <span class="category-tile-icon">🗺️</span>
      <span>Maps</span>
    </a>
    <a href="/search?category=shopping" class="category-tile disabled" title="Coming soon">
      <span class="category-tile-icon">🛒</span>
      <span>Shopping</span>
    </a>
    <a href="/search?category=music" class="category-tile disabled" title="Coming soon">
      <span class="category-tile-icon">🎵</span>
      <span>Music</span>
    </a>
    <a href="/search?category=weather" class="category-tile disabled" title="Coming soon">
      <span class="category-tile-icon">🌤️</span>
      <span>Weather</span>
    </a>
  </div>
</div>
<div id="results"></div>
{{end}}
```

- [ ] **Step 3: Test compilation**

Run: `go build ./...`
Expected: No errors

- [ ] **Step 4: Commit**

```bash
git add internal/views/templates/index.html
git commit -m "feat(frontend): add category tiles to homepage"
```

---

## PHASE 4: Preferences Page

### Task 4: Create Preferences Template

**Files:**
- Create: `internal/views/templates/preferences.html`

- [ ] **Step 1: Create preferences.html**

```html
{{define "title"}}Preferences{{end}}
{{define "content"}}
<div class="preferences-layout">
  <!-- Preferences Navigation -->
  <nav class="preferences-nav" id="preferences-nav">
    <div class="preferences-nav-title">Settings</div>
    <button class="preferences-nav-item active" data-section="search">🔍 Search</button>
    <button class="preferences-nav-item" data-section="privacy">🔒 Privacy</button>
    <button class="preferences-nav-item" data-section="tabs">📑 Tabs</button>
    <button class="preferences-nav-item" data-section="appearance">🎨 Appearance</button>
    <button class="preferences-nav-item" data-section="sidebar">📐 Sidebar</button>
    <button class="preferences-nav-item" data-section="content">📄 Content</button>
    <button class="preferences-nav-item" data-section="languages">🌍 Languages</button>
    <button class="preferences-nav-item" data-section="regional">📍 Regional</button>
  </nav>

  <!-- Preferences Content -->
  <div class="preferences-content">
    <!-- Search Section -->
    <section class="pref-section" id="section-search">
      <h2 class="pref-section-title">Search</h2>
      <div class="pref-row">
        <label for="pref-default-engine">Default engine</label>
        <select id="pref-default-engine">
          <option value="">All engines</option>
          <option value="wikipedia">Wikipedia</option>
          <option value="arxiv">arXiv</option>
          <option value="braveapi">Brave API</option>
          <option value="duckduckgo">DuckDuckGo</option>
          <option value="github">GitHub</option>
          <option value="reddit">Reddit</option>
          <option value="bing">Bing</option>
        </select>
      </div>
      <div class="pref-row">
        <label for="pref-safesearch">Safe search</label>
        <select id="pref-safesearch">
          <option value="moderate">Moderate</option>
          <option value="strict">Strict</option>
          <option value="off">Off</option>
        </select>
      </div>
      <div class="pref-row">
        <label for="pref-search-lang">Search language</label>
        <select id="pref-search-lang">
          <option value="">All languages</option>
          <option value="en">English</option>
          <option value="de">Deutsch</option>
          <option value="fr">Français</option>
          <option value="es">Español</option>
          <option value="zh">中文</option>
        </select>
      </div>
    </section>

    <!-- Privacy Section -->
    <section class="pref-section" id="section-privacy" style="display:none;">
      <h2 class="pref-section-title">Privacy</h2>
      <div class="pref-row">
        <div class="pref-row-info">
          <label>Tracking protection</label>
          <p class="pref-desc">Block trackers and scripts that follow you across the web.</p>
        </div>
        <input type="checkbox" id="pref-tracking" checked disabled>
      </div>
      <div class="pref-row">
        <div class="pref-row-info">
          <label>Send Do Not Track header</label>
          <p class="pref-desc">Ask websites not to track you.</p>
        </div>
        <input type="checkbox" id="pref-dnt">
      </div>
    </section>

    <!-- Tabs Section -->
    <section class="pref-section" id="section-tabs" style="display:none;">
      <h2 class="pref-section-title">Tabs</h2>
      <div class="pref-row">
        <div class="pref-row-info">
          <label>New tab behavior</label>
          <p class="pref-desc">Choose what happens when you open a new tab.</p>
        </div>
        <select id="pref-newtab">
          <option value="blank">Blank page</option>
          <option value="home">Homepage</option>
        </select>
      </div>
    </section>

    <!-- Appearance Section -->
    <section class="pref-section" id="section-appearance" style="display:none;">
      <h2 class="pref-section-title">Appearance</h2>
      <div class="pref-row">
        <label for="pref-theme">Theme</label>
        <select id="pref-theme">
          <option value="system">System</option>
          <option value="light">Light</option>
          <option value="dark">Dark</option>
        </select>
      </div>
      <div class="pref-row">
        <label for="pref-fontsize">Results font size</label>
        <select id="pref-fontsize">
          <option value="small">Small</option>
          <option value="medium" selected>Medium</option>
          <option value="large">Large</option>
        </select>
      </div>
    </section>

    <!-- Sidebar Section -->
    <section class="pref-section" id="section-sidebar" style="display:none;">
      <h2 class="pref-section-title">Sidebar</h2>
      <div class="pref-row">
        <div class="pref-row-info">
          <label>Show sidebar on results page</label>
          <p class="pref-desc">Display the left navigation sidebar on search results.</p>
        </div>
        <input type="checkbox" id="pref-show-sidebar" checked>
      </div>
    </section>

    <!-- Content Section -->
    <section class="pref-section" id="section-content" style="display:none;">
      <h2 class="pref-section-title">Content</h2>
      <div class="pref-row">
        <div class="pref-row-info">
          <label>Filter explicit results</label>
          <p class="pref-desc">Hide explicit content from search results (SafeSearch).</p>
        </div>
        <input type="checkbox" id="pref-explicit-filter" checked>
      </div>
      <div class="pref-row">
        <div class="pref-row-info">
          <label>Auto-play media</label>
          <p class="pref-desc">Automatically play video content when visible.</p>
        </div>
        <input type="checkbox" id="pref-autoplay">
      </div>
    </section>

    <!-- Languages Section -->
    <section class="pref-section" id="section-languages" style="display:none;">
      <h2 class="pref-section-title">Languages</h2>
      <div class="pref-row">
        <label for="pref-ui-lang">Interface language</label>
        <select id="pref-ui-lang">
          <option value="en" selected>English</option>
        </select>
      </div>
      <div class="pref-row">
        <label for="pref-search-lang-full">Search language</label>
        <select id="pref-search-lang-full">
          <option value="">All languages</option>
          <option value="en">English</option>
          <option value="de">Deutsch</option>
          <option value="fr">Français</option>
          <option value="es">Español</option>
          <option value="zh">中文</option>
        </select>
      </div>
    </section>

    <!-- Regional Section -->
    <section class="pref-section" id="section-regional" style="display:none;">
      <h2 class="pref-section-title">Regional</h2>
      <div class="pref-row">
        <label for="pref-region">Country/Region</label>
        <select id="pref-region">
          <option value="">All regions</option>
          <option value="us">United States</option>
          <option value="uk">United Kingdom</option>
          <option value="de">Germany</option>
          <option value="fr">France</option>
          <option value="cn">China</option>
        </select>
      </div>
      <div class="pref-row">
        <label for="pref-timezone">Timezone</label>
        <select id="pref-timezone">
          <option value="">Auto-detect</option>
          <option value="utc">UTC</option>
          <option value="us-eastern">US/Eastern</option>
          <option value="us-pacific">US/Pacific</option>
          <option value="europe">Europe</option>
        </select>
      </div>
    </section>
  </div>
</div>
{{end}}
```

- [ ] **Step 2: Add preferences section CSS styles**

Append to `kafka.css`:

```css
/* ============================================================
   Preferences Page Styles
   ============================================================ */

.pref-section {
  margin-bottom: 2rem;
}

.pref-section:last-child {
  margin-bottom: 0;
}

.pref-section-title {
  font-size: 1rem;
  font-weight: 600;
  color: var(--text-primary);
  margin-bottom: 1rem;
  padding-bottom: 0.5rem;
  border-bottom: 1px solid var(--border);
}

.pref-row {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 1rem;
  padding: 0.75rem 0;
  border-bottom: 1px solid var(--border);
}

.pref-row:last-child {
  border-bottom: none;
}

.pref-row label {
  font-size: 0.9rem;
  color: var(--text-primary);
}

.pref-row-info {
  flex: 1;
}

.pref-row-info label {
  font-weight: 500;
}

.pref-desc {
  font-size: 0.8rem;
  color: var(--text-muted);
  margin-top: 0.25rem;
}

.pref-row select {
  padding: 0.5rem 0.75rem;
  font-size: 0.85rem;
  font-family: inherit;
  border: 1px solid var(--border);
  border-radius: var(--radius-sm);
  background: var(--bg);
  color: var(--text-primary);
  cursor: pointer;
  min-width: 150px;
}

.pref-row select:focus {
  outline: none;
  border-color: var(--accent);
}

.pref-row input[type="checkbox"] {
  width: 18px;
  height: 18px;
  accent-color: var(--accent);
  cursor: pointer;
  flex-shrink: 0;
}

.pref-row input[type="checkbox"]:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
```

- [ ] **Step 3: Commit**

```bash
git add internal/views/templates/preferences.html internal/views/static/css/kafka.css
git commit -m "feat(frontend): add preferences page template and styles"
```

---

### Task 5: Add Preferences Route

**Files:**
- Modify: `internal/httpapi/handlers.go`
- Modify: `cmd/kafka/main.go`

- [ ] **Step 1: Add GET and POST handlers for /preferences**

Add to `handlers.go`:

```go
// Preferences renders the preferences page.
func (h *Handler) Preferences(w http.ResponseWriter, r *http.Request) {
    if r.URL.Path != "/preferences" {
        http.NotFound(w, r)
        return
    }
    if err := views.RenderPreferences(w, h.sourceURL); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

// PreferencesPOST handles form submission from the preferences page.
func (h *Handler) PreferencesPOST(w http.ResponseWriter, r *http.Request) {
    if r.URL.Path != "/preferences" {
        http.NotFound(w, r)
        return
    }
    // Preferences are stored in localStorage on the client.
    // This handler exists for form submission completeness but
    // the actual save happens via JavaScript.
    // Redirect back to preferences page.
    http.Redirect(w, r, "/preferences", http.StatusFound)
}
```

- [ ] **Step 2: Register the route in main**

Find where routes are registered (likely in `cmd/kafka/main.go`) and add:

```go
mux.HandleFunc("GET /preferences", handler.Preferences)
mux.HandleFunc("POST /preferences", handler.PreferencesPOST)
```

- [ ] **Step 3: Test compilation**

Run: `go build ./...`
Expected: No errors

- [ ] **Step 4: Commit**

```bash
git add internal/httpapi/handlers.go cmd/kafka/main.go
git commit -m "feat: add GET and POST /preferences route"
```

---

### Task 6: Update Settings JavaScript

**Files:**
- Modify: `internal/views/static/js/settings.js`

- [ ] **Step 1: Reduce popover to theme + engines only**

Update the `renderPanel` function to remove SafeSearch and Format options. Keep only theme buttons and engine toggles.

- [ ] **Step 2: Add preferences page navigation JavaScript**

Add to end of `settings.js`:

```javascript
// Preferences page navigation
function initPreferences() {
  var nav = document.getElementById('preferences-nav');
  if (!nav) return;

  var sections = document.querySelectorAll('.pref-section');
  var navItems = nav.querySelectorAll('.preferences-nav-item');

  function showSection(id) {
    sections.forEach(function(sec) {
      sec.style.display = sec.id === 'section-' + id ? 'block' : 'none';
    });
    navItems.forEach(function(item) {
      item.classList.toggle('active', item.getAttribute('data-section') === id);
    });
  }

  navItems.forEach(function(item) {
    item.addEventListener('click', function() {
      showSection(item.getAttribute('data-section'));
    });
  });

  // Load saved preferences
  var prefs = loadPrefs();
  var themeEl = document.getElementById('pref-theme');
  if (themeEl) themeEl.value = prefs.theme || 'system';

  var ssEl = document.getElementById('pref-safesearch');
  if (ssEl) ssEl.value = prefs.safeSearch || 'moderate';

  var fmtEl = document.getElementById('pref-format');
  if (fmtEl) fmtEl.value = prefs.format || 'html';

  // Save handlers
  if (themeEl) {
    themeEl.addEventListener('change', function() {
      prefs.theme = themeEl.value;
      savePrefs(prefs);
      applyTheme(prefs.theme);
    });
  }

  if (ssEl) {
    ssEl.addEventListener('change', function() {
      prefs.safeSearch = ssEl.value;
      savePrefs(prefs);
    });
  }

  if (fmtEl) {
    fmtEl.addEventListener('change', function() {
      prefs.format = fmtEl.value;
      savePrefs(prefs);
    });
  }

  // Show first section by default
  showSection('search');
}

document.addEventListener('DOMContentLoaded', initPreferences);
```

- [ ] **Step 3: Test with browser**

Manual verification needed — cannot test browser JS with `go build`

- [ ] **Step 4: Commit**

```bash
git add internal/views/static/js/settings.js
git commit -m "feat(frontend): reduce popover to theme+engines, add preferences page JS"
```

---

## PHASE 5: Polish and Mobile Responsiveness

### Task 7: Mobile Filter Chips Integration

**Files:**
- Modify: `internal/views/templates/results.html`

- [ ] **Step 1: Ensure mobile filter chips have working category links**

The current results.html has mobile filter chips with category links. These should preserve existing query params for pagination/HTMX navigation.

- [ ] **Step 2: Add filter form submission via HTMX**

Update the filter radio buttons to submit via HTMX when changed.

- [ ] **Step 3: Commit**

```bash
git add internal/views/templates/results.html
git commit -m "fix(frontend): add HTMX filter submission"
```

---

### Task 8: Final Mobile Responsiveness Audit

**Files:**
- Review: `internal/views/static/css/kafka.css`

- [ ] **Step 1: Test all breakpoints manually**

- [ ] **Step 2: Fix any layout issues found**

- [ ] **Step 3: Commit any fixes**

```bash
git add internal/views/static/css/kafka.css
git commit -m "fix(frontend): improve mobile responsiveness"
```

---

## Summary

| Phase | Task | Files |
|-------|------|-------|
| 1 | CSS Layout Framework | `kafka.css` |
| 2 | Results Three-Column | `results.html`, `views.go` |
| 3 | Homepage Tiles | `index.html` |
| 4 | Preferences Page | `preferences.html` (new), `handlers.go`, `settings.js` |
| 5 | Polish | Various |

**Total: 8 tasks across 5 phases**

Run `go test ./...` after each phase to verify nothing is broken.