hireme/docs/ui-guidelines.md

UI Guidelines

Hireme uses a modern, server-rendered UI stack that eliminates the need for heavy JavaScript frameworks (React, Vue, etc.) while maintaining a highly reactive, single-page application (SPA) feel.

Stack

• HTML / Go Templates: Server-side rendering using html/template.
• HTMX (hx-*): Used for all dynamic interactions, form submissions, and UI updates.
• Tailwind CSS: Utility-first CSS framework for styling via CDN.

Architecture & Patterns

1. Template Strings vs Files

Templates are declared as const strings in .go files (e.g., template_layout.go, template_jobs.go) and collected in a TemplateRegistry in templates.go. This keeps the final build as a single executable without requiring external static asset folders.

2. HTMX Updates

Instead of returning JSON and re-rendering via JS, API endpoints return rendered HTML fragments.

• Example: Clicking + Save on a job POSTs to /applications. The handler updates the DB and returns the template_jobs HTML fragment, which HTMX swaps directly into the #jobs-container DOM element.

3. Layout & Navigation (Tab Persistence)

• The main UI uses a tabbed layout (Jobs, Apply, Targets).
• Switching tabs is handled via lightweight Vanilla JS (switchTab(id)) which toggles .hidden classes.
• Tab states are synced to the URL #hash so reloading the page preserves the active tab.

4. Client-Side Filtering & Sorting

• To prevent unnecessary server load for display formatting, table sorting and filtering (e.g., searching by keyword, or filtering by "Qualified") is done purely client-side using Vanilla JS.
• Data attributes (data-sort-val, data-qual, data-app) are embedded in the <tr> elements during server-render to aid the JS filter logic.

5. Design Aesthetics

• Dark Mode Default: The UI uses Tailwind's dark: classes implicitly by having class="dark" on the root <html> tag.
• Micro-interactions: Use hover states (hover:bg-slate-800), transitions (transition-colors), and subtle borders to create a premium feel.
• Indicators: Use badges and color-coded text (Emerald for success/qualified, Rose for rejected/not qualified, Indigo for actions).