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, full /preferences page for all options
5. Minimal HTML changes — Restructure templates where needed for layout, reuse existing partials

---

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)
• Categories: News, Images, Videos, Maps, Shopping, Music (or configurable)
• Styling: Grid of icon+label cards below search box, subtle hover effects

---

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     │                               │  │          ││
│  │ Images  │  ┌──────────────────────────┐ │  │ ───────  ││
│  │ Videos  │  │ Result Card             │ │  │ Suggestions│
│  │ News    │  │ Title, URL, Description  │ │  │          ││
│  │ Maps    │  └──────────────────────────┘ │  │          ││
│  │ ...     │  ┌──────────────────────────┐ │  └──────────┘│
│  │         │  │ Result Card             │ │              │
│  │ ───────  │  │ ...                     │ │              │
│  │ Filters │  └──────────────────────────┘ │              │
│  │ Time    │  ...                            │              │
│  │ Type    │                                │              │
│  └─────────┘  [Pagination]                   │              │
└─────────────────────────────────────────────────────────────┘

Implementation

• Files: internal/views/templates/results.html, internal/views/templates/base.html
• Left Sidebar (desktop):
  • Category navigation links (All, Images, Videos, News, Maps, Shopping)
  • Filters section (Time range, Result type) — collapsible
  • Hidden on mobile
• Center Column:
  • Compact search bar
  • Results count meta
  • Result cards (unchanged markup, restyled if needed)
  • Pagination
• Right Sidebar:
  • Related searches (existing suggestions)
  • Additional panels as needed
• CSS: Use display: grid with three columns on desktop, collapse to single column on mobile

---

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]│
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────┐  ┌─────────────────────────────────────┐│
│  │ Sidebar        │  │ 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
• Quick Settings Popover: Keep existing popover for theme toggle and engine toggles only (lightweight, localStorage)
• Full Preferences Page: Server-rendered, form POST saves to localStorage, reads on load
• Styling: Match existing design tokens, section headers, form controls

---

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
• Category links with active state indicator
• Collapsible filter sections

Preferences Sidebar

• Vertical nav with section icons
• Active state indicator
• Mobile: horizontal scroll or accordion

---

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:

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

• Preferences page layout:

  .preferences-layout {
    display: grid;
    grid-template-columns: 200px 1fr;
    gap: 2rem;
  }
  

• Category tiles grid:

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

---

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
internal/views/static/js/settings.js	Keep popover for quick settings, update for preferences page
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)
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
• Caching or performance improvements
• User authentication/account system