# Refined Mockups — Wedding Newspaper Generator

> Design-lead refined mockups derived from the user stories (US1–US10),
> requirements (FR1–FR8, NFR1–NFR9), and the seven confirmed design decisions
> (CLI-first authoring, content/config input, per-article review page, no print
> preview, funnies generated from content, no formal a11y target, guided empty
> state). Rough mockups were not produced (classic scope skips Ideation), so
> these are designed directly from requirements + stories.

## M1 — The authoring flow (generator UX)

The generator is **CLI-first** (Q1=A): the couple runs a single command, the
tool reads a content folder + config, optionally invokes local Ollama for the
AI draft, emits `newspaper.html`, and (per US9) presents a per-article review
page before the final render.

```
worktree/
  config.json            # masthead metadata: title, names, date, issue, volume
  content/               # markdown/txt articles + funnies source
  newspaper.html         # the generated, self-contained printable artifact
```

`newspaper generate [--draft]` flows:
1. Read `config.json` + `content/` (Q2=A).
2. If `--draft`, ask local Ollama to draft lead story + fillers (US8), keeping
   everything on-machine (NFR9).
3. If AI used, open the **per-article review page** (US9/Q3=A): approve / edit /
   replace any single article before final render.
4. Emit self-contained `newspaper.html`, zero-network, openable via `file://`,
   printable to A4 (FR7, NFR1–NFR4, US5).

## M2 — The newspaper page (reader UX)

The output is a classic broadsheet (US6/NFR8): black ink on white/cream, serif
headlines + body, column rules. Content flows across multiple A4 pages with
clean page breaks (US1/FR1). Structural regions (US2/US3/US4/US6/US3-funnies):

```
┌─────────────────────────────────────────────┐  ┌─────────────────────────────┐
│  MASTHEAD (title / date · issue · volume)   │  │   interior page header     │
├──────────────┬──────────────┬───────────────┤  ├────────┬────────┬──────────┤
│ lead/ front  │ article      │  xkcd-style   │  │ column │ column │ ads/box  │
│ page story   │ (bylined)    │  cartoon      │  │        │        │          │
├──────────────┼──────────────┼───────────────┤  ├────────┴────────┴──────────┤
│ article 3    │  pull quote  │  schedule /   │  │  photo auto-balanced      │
│              │              │  events block │  │                            │
├──────────────┴──────────────┴───────────────┤  ├──────────────┬─────────────┤
│   funnies: crossword · find-a-word · comics  │  │ article cont.│ well-wishes │
└─────────────────────────────────────────────┘  └──────────────┴─────────────┘
         page 1                                       page 2+
```

- **Page 1**: masthead (US2), lead story (FR3.1), interior articles with
  bylines (FR3.2), xkcd-style cartoon tied to the day (FR5), schedule/events
  block (FR3.4), pull quotes/sidebars (FR3.3).
- **Pages 2+**: flowing interior columns, photo auto-balancing (FR6/FR4/US4),
  the lighter well-wishes corner (FR3.5), and the funnies section (US3/FR4):
  crossword, find-a-word, comics.
- **Funnies generated from content** (Q5=X): the generator builds the puzzles
  from theme words/clues drawn out of the content and uses content-derived
  context to search for / insert a relevant cartoon.

## M3 — AI per-article review page (US9 / Q3=A)

After the AI draft, the couple sees a review page. Present **one article per
card**, each with three actions:

| Card action | Behaviour |
|---|---|
| **Approve** | Keep this article's copy unchanged; others can still be revised |
| **Edit** | Edit this article's copy in place; only it re-renders |
| **Replace** | Supply new copy; it replaces the draft for this article only |

A "Render final newspaper" button appears once every article is approved (or
the couple opts to keep unapproved ones as-is). Approved articles never change
when others are edited (US9/AC9.1.2–3).

## M4 — First-run / empty state (US10 / Q7=A)

With no content yet, the couple sees a friendly guided state:
- A short message ("Welcome — let's make your wedding newspaper").
- A pointer to the `content/` folder + `config.json`.
- A **sample issue** they can generate to see the layout (Q7=A), then replace
  with their real content.

This protects the first-run experience (per the designer contribution in
user-stories) without fabricating content in the real output (FR7.4).

## M5 — States handled

Per stage Step 2, the generator's surface must handle these states:
- **empty** — no content: guided empty state (US10).
- **loading** — AI draft running: simple progress/status line (CLI) or spinner
  (review page).
- **error** — missing content/config, model unavailable, template failure:
  clear one-line message naming the problem + fix path.
- **success** — generated `newspaper.html`, path shown.
- **partial** — AI draft done, some articles reviewed, others pending (the
  review page's natural in-between state).

<!-- refined-mockups-after-confirm -->