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

# Brave Search Frontend Redesign — Design Specification

## Overview

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

## Design Principles

1. **Brave-like layout** — Three-column results, full-page preferences, homepage tiles
2. **Preserve existing design tokens** — Keep current CSS variables (colors, spacing, radii)
3. **CSS Grid for layout** — Three-column grid for results, flexible layouts elsewhere
4. **Hybrid preferences** — Quick popover for common settings (theme + engines), full `/preferences` page for all options
5. **Minimal HTML changes** — Restructure templates where needed for layout, reuse existing partials
6. **localStorage-only preferences** — No server-side persistence; all preferences stored in browser localStorage

---

## 1. Homepage Redesign

### Current State
- Centered hero with logo, tagline, and search box
- No visual categorization of search types

### New Layout
```
┌─────────────────────────────────────────────────────────────┐
│  [Logo]                                      [⚙ Preferences]│
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                      [🔍 Search Box]                        │
│                                                             │
│    ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐            │
│    │  News  │ │ Images │ │ Videos │ │  Maps  │  ...       │
│    └────────┘ └────────┘ └────────┘ └────────┘            │
│                                                             │
│              "Search the web privately..."                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Implementation
- **File:** `internal/views/templates/index.html`
- **Structure:** Search hero + category tiles grid
- **Tiles:** Static links to `/search?q=...` with category parameter (e.g., `&category=images`)
- **Styling:** Grid of icon+label cards below search box, subtle hover effects

### Category Tiles
| Category | Icon | Notes |
|----------|------|-------|
| All | 🌐 | Default, no category param |
| News | 📰 | |
| Images | 🖼️ | |
| Videos | 🎬 | |
| Maps | 🗺️ | |
| Shopping | 🛒 | Future: connect to shopping engine |
| Music | 🎵 | Future: connect to music engine |
| Weather | 🌤️ | Future: connect to weather API |
| Sports | ⚽ | Future |
| Cryptocurrency | ₿ | Future |

Categories marked "Future" are included in the UI but may not have backend support yet. Category tiles that lack backend support display grayed out with a "Coming soon" tooltip.

---

## 2. Results Page — Three-Column Layout

### Current State
- Two columns: compact search bar spanning top, main results + right sidebar

### New Layout
```
┌─────────────────────────────────────────────────────────────┐
│  [Logo]                                      [⚙ Preferences]│
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌────────────────────────────┐  ┌──────────┐│
│  │ Nav     │  │ 🔍 [    Search Input     ]  │  │ Related  ││
│  │ ───────  │  └────────────────────────────┘  │ Searches ││
│  │ All     │  About 1,240 results (0.42s)    │          ││
│  │ Images  │  ┌──────────────────────────┐ │  │ ───────  ││
│  │ Videos  │  │ Result Card             │ │  │ Suggestions│
│  │ News    │  │ Title, URL, Description  │ │  │          ││
│  │ Maps    │  └──────────────────────────┘ │  └──────────┘│
│  │ Shopping│  ┌──────────────────────────┐ │              │
│  │ ...     │  │ Result Card             │ │              │
│  │         │  │ ...                     │ │              │
│  │ ───────  │  └──────────────────────────┘ │              │
│  │ Filters │  ...                            │              │
│  │ Time    │                                │              │
│  │ Type    │  [Pagination]                  │              │
│  └─────────┘                                │              │
└─────────────────────────────────────────────────────────────┘
```

### Implementation
- **Files:** `internal/views/templates/results.html`, `internal/views/templates/base.html`
- **Left Sidebar (desktop, sticky):**
  - Category navigation links (All, Images, Videos, News, Maps, Shopping, Music, Weather)
  - Filters section (Time range, Result type) — collapsible
  - Hidden on mobile (< 768px)

- **Center Column:**
  - Compact search bar
  - Results count meta: "About {n} results ({time}s)"
  - Result cards (unchanged markup)
  - Pagination

- **Right Sidebar:**
  - Related searches (existing suggestions)
  - Additional panels as needed

### Filters
**Time Range Options:**
| Label | Query Param |
|-------|-------------|
| Any time | (none) |
| Past hour | `&time=h` |
| Past 24 hours | `&time=d` |
| Past week | `&time=w` |
| Past month | `&time=m` |
| Past year | `&time=y` |

**Result Type Options:**
| Label | Query Param |
|-------|-------------|
| All results | (none) |
| News | `&type=news` |
| Videos | `&type=video` |
| Images | `&type=image` |

Filter state persists in URL query params and is preserved across HTMX navigation via `hx-include`.

### Mobile Behavior
| Breakpoint | Layout |
|------------|--------|
| < 768px | Single column, no left sidebar |
| 768px - 1024px | Two columns (center + right sidebar), no left nav |
| > 1024px | Full three columns |

On mobile (< 768px):
- Category filters accessible via a horizontal scrollable chip row above results
- Both sidebars hidden
- Search bar full-width

---

## 3. Preferences Page — Full-Page Hybrid

### Current State
- Popover triggered by gear icon in header
- JavaScript-rendered from localStorage
- Sections: Appearance, Engines, Search Defaults

### New Layout
```
┌─────────────────────────────────────────────────────────────┐
│  [Logo]                                      [⚙ Preferences]│
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────┐  ┌─────────────────────────────────────┐│
│  │ Nav            │  │ Content                            ││
│  │ ─────────────  │  │                                    ││
│  │ Search         │  │ [Section Content]                   ││
│  │ Privacy        │  │                                    ││
│  │ Tabs           │  │                                    ││
│  │ Appearance     │  │                                    ││
│  │ Sidebar        │  │                                    ││
│  │ Content        │  │                                    ││
│  │ Languages      │  │                                    ││
│  │ Regional       │  │                                    ││
│  └────────────────┘  └─────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

### Sections (Brave-style)
1. **Search** — Default engine, safe search, language
2. **Privacy** — Tracking protection toggle (UI only, always on), request DNT header toggle
3. **Tabs** — New tab behavior (placeholder section)
4. **Appearance** — Theme (Light/Dark/System), results font size
5. **Sidebar** — Sidebar visibility toggle
6. **Content** — Filter explicit results (SafeSearch), auto-play media toggle
7. **Languages** — UI language (English only for now), search language
8. **Regional** — Region/Country, timezone (placeholder)

### Implementation
- **Route:** Add `GET /preferences` and `POST /preferences` to `internal/httpapi/`
- **Template:** `internal/views/templates/preferences.html`
- **Storage:** localStorage-only. GET handler renders page shell, JavaScript populates form values from localStorage. POST handler receives form data, writes to localStorage, re-renders page.
- **Quick Settings Popover:** Keep existing popover for **theme toggle and engine toggles only** (lightweight, localStorage). SafeSearch and Format settings move exclusively to full preferences page.
- **Styling:** Match existing design tokens, section headers, form controls

### Preferences Nav (Mobile)
- Horizontal scrollable nav on mobile (< 768px)
- Active section highlighted

---

## 4. Component Changes

### Header
- Logo + site name (unchanged)
- Preferences button (unchanged)

### Search Box
- Homepage: Larger, prominent, centered
- Results page: Compact, full-width within center column

### Result Cards
- Keep existing structure
- Consider subtle styling improvements (spacing, typography)

### Category Tiles (Homepage)
- Icon + label per category
- Hover: slight scale + shadow

### Left Sidebar (Results Page)
- Sticky positioning (`position: sticky; top: calc(var(--header-height) + 1rem)`)
- Category links with active state indicator
- Collapsible filter sections

### Preferences Nav
- Vertical nav with section icons
- Active state indicator
- Mobile: horizontal scroll

---

## 5. CSS Architecture

### Existing (Retain)
- CSS custom properties (design tokens)
- Component-level styles
- Dark mode via `[data-theme="dark"]`

### New

**Layout Grid for three-column results:**
```css
.results-layout {
  display: grid;
  grid-template-columns: 200px 1fr 240px;
  gap: 2rem;
  align-items: start;
}
```

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

**Preferences page layout:**
```css
.preferences-layout {
  display: grid;
  grid-template-columns: 200px 1fr;
  gap: 2rem;
}
```

**Category tiles grid:**
```css
.category-tiles {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(100px, 1fr));
  gap: 1rem;
}
```

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

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

---

## 6. Files to Modify

| File | Change |
|------|--------|
| `internal/views/templates/index.html` | Add category tiles |
| `internal/views/templates/results.html` | Add left sidebar, restructure for three columns |
| `internal/views/templates/base.html` | Minimal changes (no structural changes needed) |
| `internal/views/templates/preferences.html` | **New** — full preferences page |
| `internal/views/static/css/kafka.css` | Add layout grids, category tiles, sidebar styles, sticky positioning, mobile breakpoints |
| `internal/views/static/js/settings.js` | Reduce popover to theme + engines; add preferences page JS |
| `internal/httpapi/httpapi.go` | Add `/preferences` route (GET + POST) |
| `internal/views/views.go` | Add preferences template rendering |

---

## 7. Priority Order

1. **Phase 1:** CSS layout framework (three-column grid, new variables, breakpoints)
2. **Phase 2:** Results page three-column layout
3. **Phase 3:** Homepage category tiles
4. **Phase 4:** Preferences page (quick popover first, then full page)
5. **Phase 5:** Polish and mobile responsiveness

---

## Out of Scope

- Backend search logic changes
- New engine implementations (category tiles for future engines are UI placeholders only)
- Caching or performance improvements
- User authentication/account system
- Server-side preference storage