Interaction Specification — Wedding Newspaper Generator
Component-level specifications following the design-agent component template.
Covers the two surfaces: the CLI authoring flow and the generated newspaper
page. Per confirmed decisions: CLI-first (Q1=A), content/config input (Q2=A),
per-article review page (Q3=A), no print preview step (Q4=B), funnies
generated from content (Q5=X), no formal a11y target (Q6=C), guided empty
state (Q7=A).
CLI: generate command
| Field |
Value |
| Component |
generate CLI command |
| Description |
Reads config + content, optionally drafts via local Ollama, emits newspaper.html |
| Category |
navigation (entry point) |
States
| State |
Description |
Trigger |
| ready |
Prints usage / config guidance |
run with no valid input |
| generating |
Parses content, builds layout |
valid config + content present |
| drafting |
Calls local Ollama for lead/fillers |
--draft flag present |
| reviewing |
Hands to review page (US9) |
AI draft produced |
| printed |
Writes newspaper.html, prints success path |
render complete |
| error |
Content/config/model failure |
validation failure |
Props / Inputs
| Prop |
Type |
Required |
Default |
Description |
--draft |
boolean |
no |
— |
Whether to run the local Ollama AI draft (US8) |
config |
path |
no |
config.json |
Masthead metadata + options |
content |
path |
no |
content/ |
Markdown/txt articles + funnies source |
Responsive behaviour
N/A (CLI). Terminal width-wrapping of help text only.
Accessibility
| Requirement |
Implementation |
| Error clarity |
One-line message naming the problem + the exact fix path |
| Reversibility |
Generate is idempotent/regenerable; never destroys the couple's content files |
Per-article review page
| Field |
Value |
| Component |
Article review card |
| Description |
Per-article approve / edit / replace control before final render |
| Category |
feedback |
States
| State |
Description |
Trigger |
| pending |
Draft ready, not yet decided |
AI draft returned |
| approved |
Copy kept as-is |
user clicks Approve |
| editing |
Copy being revised |
user clicks Edit |
| replacing |
New copy supplied |
user clicks Replace |
Props / Inputs
| Prop |
Type |
Required |
Default |
Description |
articleId |
string |
yes |
— |
Stable per-article key (the article-level data boundary, US9/AC9.1.5) |
status |
pending|approved|editing|replaced |
yes |
pending |
Current review state |
copy |
string |
yes |
— |
The article's text |
onApprove |
fn |
no |
— |
Keep as-is |
onEdit |
fn |
no |
— |
Open inline edit |
onReplace |
fn |
no |
— |
Supply replacement copy |
Responsive behaviour
Stacked cards on narrow; grid of cards on wide. The newspaper is printed, so
this page is on-screen only.
Accessibility
| Requirement |
Implementation |
| Keyboard |
Buttons focusable; Enter/Space activate (on-screen tool) |
| Clear status |
Each card visibly labelled with its state (pending/approved/…) |
Masthead component (newspaper page)
| Field |
Value |
| Component |
Masthead |
| Description |
Front-page title banner + date / issue / volume (US2/FR2) |
| Category |
display / layout |
States
| State |
Description |
Trigger |
| default |
Classic broadsheet masthead |
page render |
Props / Inputs
| Prop |
Type |
Required |
Default |
Description |
title |
string |
yes |
— |
Newspaper / couple name |
dateLine |
string |
yes |
— |
Issue date |
issue |
string |
yes |
— |
Issue number |
volume |
string |
yes |
— |
"Volume X" |
titleStyle |
object |
no |
serif |
Masthead typography |
Responsive behaviour
Masthead spans the full sheet width on print; on very narrow screen the title
sizes down but the line stays intact (does not wrap awkwardly).
Accessibility
| Requirement |
Implementation |
| Document structure |
Masthead is the page's <header> / H1 (semantic, matches Q6=C baseline) |
Funnies: crossword & find-a-word
| Field |
Value |
| Component |
Funnies section |
| Description |
Crossword + find-a-word + comics generated from content (US3/FR4/Q5=X) |
| Category |
display |
States
| State |
Description |
Trigger |
| default |
Renders crossword grid, clues, solution; find-a-word grid; comic panels |
page render |
Props / Inputs
| Prop |
Type |
Required |
Default |
Description |
grid |
array |
yes |
— |
Crossword grid (built from content theme words) |
cluesAcross |
array |
yes |
— |
Across clues (derived from content) |
cluesDown |
array |
yes |
— |
Down clues (derived from content) |
findWords |
array |
yes |
— |
Word list for find-a-word (content terms) |
comics |
array |
no |
— |
Comic panels + captions |
cartoonAlt |
string |
no |
— |
Context note for the xkcd-style cartoon |
Responsive behaviour
Each puzzle bounded to its column width and an A4-printable height; no
overflow.
Accessibility
| Requirement |
Implementation |
| Clarity |
Grid cells have clear borders and legible type (printed keepsake; Q6=C) |
Photo embed (auto-balanced)
| Field |
Value |
| Component |
Embedded photo |
| Description |
Photo embedded in the column layout with caption (FR6/US4) |
| Category |
display |
States
| State |
Description |
Trigger |
| default |
Photo + caption fit the column |
photo supplied |
| absent |
No placeholder; layout renders clean, text-only |
no photo supplied (FR7.4) |
Props / Inputs
| Prop |
Type |
Required |
Default |
Description |
src |
data/blob |
no |
— |
Locally embedded image |
caption |
string |
no |
— |
Caption text |
credit |
string |
no |
— |
Credit/byline line |
Responsive behaviour
Auto-balances into the column structure; falls back to full-width or natural
size if it cannot fit (R-02 from requirements review), never overflowing the
A4 sheet (NFR2).
Accessibility
| Requirement |
Implementation |
| Text alternative |
Caption present; decorative alt when purely decorative |
