# Frontend Specification — Template

> **How to use this file:** This is a *reference template*. Give it to Claude Code along with your `project-overview.md` and `backend-spec.md`, and ask it to produce a filled-in `frontend-spec.md` for *your* project. Keep the section headings; replace the guidance with real content. It is technology-agnostic — describe *what* the UI must do and how it should feel, and commit to a specific framework where you've chosen one.
>
> The point of writing this before coding: the frontend is where users judge the whole product. If the screens, states, and design language are specified up front, the AI builds something coherent and polished instead of a generic default that you then rework screen by screen.

---

## 1. Stack & conventions

- **Framework:** (e.g. React + Vite, Next.js, Vue, Flutter, SwiftUI)
- **Styling approach:** (e.g. Tailwind, CSS modules, styled-components)
- **State management:** (local state, Context, a store library)
- **Data fetching:** how the frontend talks to the backend (fetch/axios, a query library) and where the base URL comes from
- **Component conventions:** folder structure, naming, one component per file, etc.

---

## 2. Design language

This is what separates a polished product from a generic one. Be specific.

- **Overall feel:** (clean & minimal, dense & professional, warm & friendly…)
- **Color system:** neutral base + accent(s). Give actual values if you have them. Note dark/light mode.
- **Typography:** font family, weight hierarchy, how headings vs body differ.
- **Spacing & shape:** generous vs compact; corner radius; shadow style.
- **Micro-interactions:** hover states, transitions, focus rings — the details that make it feel finished.
- **Anti-patterns:** what to avoid (e.g. "no default browser checkboxes", "no harsh drop shadows", "not cramped").

> If you have a design system or tokens, reference them here so every screen stays consistent.

---

## 3. Screens / pages

List every screen. For each one, specify:

- **Name & purpose** — what the user does here
- **Route/path** (if applicable)
- **Layout** — the main regions and what goes where
- **Data shown** — which backend data it reads, and from which endpoint
- **Actions** — what the user can do, and which endpoint each action calls
- **States** — loading, empty, error, success (see section 5)

*Example:*

### Bookings list
- **Purpose:** business owner sees upcoming bookings
- **Route:** `/bookings`
- **Layout:** header with filters; scrollable list of booking cards; FAB to add
- **Data:** `GET /api/bookings` (upcoming, paginated)
- **Actions:** tap a card → detail; add → create flow; cancel → `DELETE /api/bookings/:id`
- **States:** loading skeleton; empty ("No bookings yet"); error (retry); populated list

Repeat for every screen.

---

## 4. Components (reusable)

List the shared building blocks that appear across screens, so they're built once and reused:

- Component name — what it does, its key props, where it's used

*Examples:* Button, Card, Modal, Input, EmptyState, Toast, Avatar.

Keeping this list explicit prevents the AI from re-inventing the same element five different ways.

---

## 5. UI states (every screen needs these)

Specify how the UI behaves in each state, because these are what get skipped:

- **Loading:** skeletons or spinners — which, where
- **Empty:** a designed, inviting empty state (icon + friendly text + a clear next action), never a blank screen
- **Error:** clear message + a way to recover (retry)
- **Success:** confirmation feedback (toast, inline state change)

---

## 6. Navigation

- The overall navigation model (tabs, sidebar, stack)
- How a user moves between the main areas
- What's reachable from where

---

## 7. Responsiveness & platforms

- Which screen sizes must be supported (mobile, tablet, desktop)
- What changes between them (layout shifts, what collapses)
- Any platform-specific behavior

---

## 8. Accessibility

- Keyboard navigation for all interactive elements
- Focus states visible
- Sufficient color contrast
- Labels/aria for controls and icons

---

## 9. Build order

Suggest a sensible order:
1. Design tokens / theme + base components (Button, Card, Input…)
2. Navigation shell
3. Screen by screen, each with all four states
4. Wire to real backend endpoints
5. Polish: transitions, empty states, responsiveness

---

### Reminder for the AI reading this

When you generate the real `frontend-spec.md`:
- Commit to the project's actual framework and design language.
- Every screen must specify its data source, its actions (with endpoints), and all four UI states.
- Proactively improve UX where there's an obvious opportunity, but stay inside the stated design language.
- Anything undecided goes into an "Open questions" note rather than a silent default.