# UI Element Inventory — Sprint Contract

L'inventario degli elementi UI e il **contratto vincolante** tra il design approvato
e l'implementazione. Funziona come uno "sprint contract" (ref: Anthropic
"Harness Design for Long-Running Apps"): generatore e valutatore concordano su cosa
significa "fatto" prima che il codice venga scritto.

## Quando produrlo

Dopo che l'utente ha approvato un'opzione di design (Step 3d nel workflow).

## Come produrlo

1. Apri il `design.html` approvato.
2. Leggi la struttura HTML e identifica OGNI elemento UI distinto.
3. Produci l'inventario strutturato nel formato sotto.

## Formato

Aggiungi al state file del PRD sotto `## UI Element Inventory`:

```markdown
## UI Element Inventory

Source: ${paths.prd_dir}/<slug>/design.html (option <X>, approved <date>)

| # | Element | Type | Purpose | Inputs/Outputs | Behavior | Function ref |
|---|---------|------|---------|----------------|----------|--------------|
| 1 | <name>  | page / section / component / modal / form / button / endpoint | <what it does> | <fields, props, API params> | <interactions, states, validation> | <US-id / AC-id / endpoint — or `decorative`> |
| 2 | ...     | ...  | ...     | ...            | ...      | ...          |

### New components to create
- <ComponentName> — <purpose> (NOT existing in codebase)

### Existing components to reuse
- <ComponentName> at <file:path> — <how it's used in the design>
```

## Regole per l'inventario

- Ogni sezione visibile, form, bottone, modale, card, lista ed elemento interattivo
  ha la sua riga.
- Se il design mostra un'interazione API (submit form, data fetch), elenca l'endpoint
  atteso come riga con tipo `endpoint`.
- Sii specifico: "Save button that calls POST /api/v1/foo/bar" non "a button" (cita l'endpoint reale).
- Includi error states, loading states, e empty states visibili nel design.
- Distingui chiaramente tra componenti da creare e componenti da riusare.
- **Function ref (Functional Traceability):** ogni riga interattiva o iconografica
  DEVE citare la funzione che la giustifica — uno US-id, un AC-id, o l'endpoint
  reale che invoca. Un elemento puramente visivo si marca `decorative` (verrà reso
  statico/`aria-hidden`, mai come controllo vivo). Se un artefatto del design non
  traccia a nulla ed è interattivo (un **orphan**), NON inventargli uno scopo:
  era un orphan già emerso nell'intake del mockup (Discovery) e va risolto lì
  (funzione reale via `/prd-add`, downgrade a `decorative`, o rimozione dal design)
  prima di scrivere l'inventario. Questa colonna è l'allowlist che `ui-expert` e
  `code-reviewer` fanno rispettare con il Functional Traceability Gate
  (`framework/agents/design-system-protocol.md`).

## Cosa NON includere

- Dettagli di implementazione tecnica (nomi di hook, struttura di stato, file path
  del codice sorgente). Quelli vanno nel PRD e nelle backlog cards.
- Scelte architetturali. L'inventario dice COSA c'e nel design, non COME si implementa.

## Artefatti prodotti

1. Copia l'HTML approvato in `${paths.prd_dir}/<slug>/design.html`.
2. Aggiorna il state file del PRD con l'inventario.
3. Pulisci `/tmp/prd-design-<slug>/`.
