TimeTracker/docs/UI_GUIDELINES.md

TimeTracker UI Guidelines

This document describes design principles, component usage, layout structure, and styling conventions for the TimeTracker web UI. Use it when adding or changing templates and static assets.

Design principles

• Clarity — One primary action per block; labels and hierarchy make the next step obvious.
• Consistency — Use the same components and patterns across pages (page header, cards, empty states, buttons).
• Minimal friction — Reduce steps for the core flow: start timer → monitor → stop → review. First-class navigation for Timer and Time entries.
• Professional appearance — Clean spacing, readable typography, semantic color use, and accessible contrast.
• Accessibility — Keyboard navigation, focus visibility, ARIA where needed, and semantic HTML. See Frontend Quality Gates for a11y checks.

Component usage

Page header

Use the page_header macro from app/templates/components/ui.html on every main page:

• Parameters: icon_class, title_text, subtitle_text (optional), actions_html (optional), breadcrumbs (optional).
• Usage: One h1-level title per page; put primary actions in actions_html; use breadcrumbs for deep pages (e.g. list → detail → edit).

Stat cards and info cards

• Stat cards: Use stat_card from components/ui.html or components/cards.html for numeric summaries (e.g. total hours, entry count). Prefer a single row of compact stat cards on dashboards.
• Info cards: Use info_card for short text summaries when needed.

Empty states

• Full empty state: Use empty_state or empty_state_with_features from components/ui.html for list or section-level “no data” (icon, title, message, primary action).
• Compact empty state: Use empty_state_compact for table body or inline “no results” (smaller icon and text, same structure).
• Always provide a clear primary action (e.g. “Start timer”, “Create project”, “View all”).

Buttons

• Primary: One main action per block (btn btn-primary) — e.g. “Start Timer”, “Save”, “Log Time”.
• Secondary: Alternative or cancel (btn btn-secondary).
• Danger: Destructive actions (btn btn-danger).
• Ghost: Low emphasis (btn btn-ghost). Use for tertiary actions.
• Sizes: btn-sm, btn-lg when needed. Use consistent padding and touch targets (e.g. ≥ 44px for mobile).

Forms

• Labels: Use form-label; mark required fields with * and optional with “(optional)” in helper text.
• Inputs: Use form-input from app/static/src/input.css. Add form-input-error for validation error state.
• Validation: Show inline errors below fields; use the existing toast system for submit/API errors.

Modals and dialogs

• Pattern: Overlay + content panel; close on overlay click and Escape. Primary button submits; secondary/cancel closes.
• Components: Use modal and confirm_dialog from components/ui.html. Ensure focus is trapped inside when open and restored on close.
• Start Timer modal: Same pattern; single primary “Start” action; progressive disclosure (project/client → task → notes/tags) where possible.

Notifications

• Use the existing toast system for success, error, warning, and info. Support optional actionLink and actionLabel for follow-up (e.g. “View time entries” after stopping the timer).
• Document types and behavior in this file; avoid ad-hoc alert() for user feedback.

Layout structure

• Content width: Main content is wrapped in a max-width container (max-w-7xl, 1280px) and centered (mx-auto) so lines don’t stretch on large screens. Applied in base.html to the main content area.
• Grid: Use Tailwind grid for dashboards and two-column layouts: e.g. grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3; main content often lg:col-span-2, sidebar lg:col-span-1.
• Spacing: Use the design tokens in app/static/src/input.css (--spacing-xs through --spacing-3xl). Prefer gap-4 for card groups, gap-6 for sections, p-6 for card padding.

Styling conventions

• Tailwind: Prefer Tailwind utility classes. Design tokens and component classes live in app/static/src/input.css (e.g. form-input, btn, text-h1…text-caption, status and action classes).
• Colors: Use semantic tokens and classes: primary, text-text-light / text-text-dark, text-text-muted-light / text-text-muted-dark, bg-card-light / bg-card-dark, border-border-light / border-border-dark. Use status/action classes (status-active, action-success, etc.) for badges and feedback.
• Typography: Use .text-h1….text-h6 for headings, .text-body / .text-body-sm for body text, .text-label / .text-caption for labels and captions. Page title = h1; section = h2; card title = h3.
• Dark mode: Supported via dark: variants and darkMode: 'class' in Tailwind config. Test both themes when changing UI.

Keyboard and focus

• Escape: Closes modals and dropdowns. Implement in base-init.js and feature scripts.
• Enter: Submits the primary form in modals and dialogs.
• Tab order: Logical and visible; ensure focus ring is visible (e.g. focus:ring-2 focus:ring-primary).
• Skip link: “Skip to content” is present in base.html; keep it and ensure the target is the main content anchor.

File reference

Area	Files
Base layout	app/templates/base.html
Design tokens / Tailwind	app/static/src/input.css, tailwind.config.js
Components	app/templates/components/ui.html, app/templates/components/cards.html
Dashboard	app/templates/main/dashboard.html
Timer flow	app/templates/timer/timer_page.html, Start Timer modal (dashboard), app/static/floating-timer-bar.js
Time entries	app/templates/timer/time_entries_overview.html, app/templates/timer/_time_entries_list.html

For accessibility and quality checks, see FRONTEND_QUALITY_GATES.md.