baldart 3.6.2

package/framework/.claude/skills/ui-design/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: ui-design
+description: "UI design workflow. Generates context-aware mockups with GAN-inspired generator/evaluator separation, visual verification via Playwright, and structured sprint contracts. Use when: (1) designing new pages or components, (2) the /prd skill reaches its UI design phase (Step 3), (3) redesigning existing pages, (4) creating design options for user review, (5) any task involving 'design UI', 'mockup', 'opzioni di design', 'progetta interfaccia', '3 opzioni', 'design page', 'UI design'. Not for: bug fixes, small tweaks, copy-only changes, or implementing an already-chosen design."
+---
+
+# UI Design Skill
+
+Design workflow that produces context-aware mockup options, evaluates them with
+separated generator/evaluator agents (GAN pattern), and delivers an approved
+design with a structured UI Element Inventory.
+
+**Architecture principle:** The generator never evaluates its own output.
+Evaluation is always performed by a separate agent with fresh context.
+(Ref: Anthropic "Harness Design for Long-Running Apps")
+
+## Project Context
+
+**Reads from `baldart.config.yml`:**
+`paths.design_system`, `paths.ui_guidelines`, `paths.components_primitives`,
+`paths.components_root`, `paths.global_styles`, `paths.prd_dir`,
+`identity.design_philosophy`, `identity.language`, `identity.audience_segments`,
+`stack.charting.canonical`, `stack.charting.forbidden`, `stack.charting.wrappers_root`.
+
+**Gated by features:**
+`features.has_design_system` (when `true`, design-system reads are BLOCKING; when `false`, skip step 1 of Prerequisites and rely on `paths.ui_guidelines` alone).
+
+**Overlay:** loads `.baldart/overlays/ui-design.md` if present — extends base by default; sections marked `## [OVERRIDE] <topic>` replace base sections. See `framework/agents/project-context.md` § 5.
+
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+---
+
+## Prerequisites — BLOCKING reads before ANY design work
+
+These reads are BLOCKING. Resolve paths from `baldart.config.yml` before opening files. If `features.has_design_system: true`, item 1 is the mandatory entry point and skipping it is a protocol violation.
+
+1. **MANDATORY / BLOCKING when `features.has_design_system: true`** — read `${paths.design_system}/INDEX.md` (the design-system entry point: component index, authority matrix, token contract, any project-specific theming pairing rules and overlay decision tree).
+2. **MANDATORY / BLOCKING** — read `${paths.ui_guidelines}` for canonical visual language, typography, accessibility, and brand voice. If the project has a `identity.design_philosophy` set, that philosophy is the lens through which the guidelines apply.
+3. **MANDATORY when `features.has_design_system: true`** — read `${paths.design_system}/tokens-reference.md` (if present): token contract. Never hardcode values that bypass this SSOT.
+4. **MANDATORY when `features.has_design_system: true`** — read the relevant `${paths.design_system}/components/<Name>.md` for every primitive you will touch, and the relevant `${paths.design_system}/patterns/*.md` for the pattern involved.
+5. **MANDATORY for chart / data-viz tasks** — apply `stack.charting`:
+   - Propose only libraries in `stack.charting.canonical`. Refuse libraries listed in `stack.charting.forbidden`.
+   - If `stack.charting.wrappers_root` is set, propose those project wrappers over raw library usage.
+   - If both lists are empty, ask the user which charting library to use before proposing one.
+6. **MUST** run `ui-ux-pro-max` skill for design intelligence (bounded by the design-system SSOT above — advisory only).
+7. **MUST** identify the audience segment for the work, using `identity.audience_segments` as the menu of valid choices. If segments are empty, treat the work as undifferentiated.
+8. If brand inputs are missing (e.g. logo, accent palette), ask — never invent.
+
+## Design System Alignment
+
+- Token consumption follows the project's chosen mechanism (CSS custom properties in `${paths.global_styles}`, Tailwind config, theme provider, etc.). The base skill assumes nothing; defer to the design-system docs above for the project's mechanism.
+- Canonical sources (resolve via `baldart.config.yml`):
+  - `${paths.design_system}/INDEX.md` — component index + authority matrix (when `features.has_design_system: true`)
+  - `${paths.design_system}/tokens-reference.md` — human-readable token contract
+  - `${paths.design_system}/components/<Name>.md` — per-component specs
+  - `${paths.design_system}/patterns/*.md` — pattern docs (e.g. theming, overlays, motion)
+- NEVER hardcode hex colors, shadow tuples, or border-width values when the project has a token contract. Use the tokens listed in the contract.
+- If the project uses multi-tenant theming (`features.multi_tenant_theming: true`), themed-surface text/bg pairing is mandatory per the project's theming pattern doc — consult `.baldart/overlays/ui-design.md` for the exact pairing rule.
+
+---
+
+## Workflow Steps
+
+### Step A — Component Discovery
+
+Read [references/component-discovery.md](references/component-discovery.md).
+
+Before running the cascade, consult `${paths.design_system}/INDEX.md` (when present) and the relevant per-component doc in `${paths.design_system}/components/`. This is the authoritative inventory of tokens-compliant primitives.
+
+Run the full cascade: design-system INDEX → project search (`${paths.components_primitives}/*`, `${paths.components_root}/shared/*` if applicable) → 21st.dev catalog → create from scratch. Document which existing components to reuse and which need creation. Any new component must consume the project's design tokens.
+
+### Step B — Context Capture
+
+Read [references/generation.md](references/generation.md) § Context Capture.
+
+1. Identify 1-3 pages where the feature will live.
+2. Capture screenshots via Playwright. Save to `/tmp/prd-design-<slug>/context/`.
+3. Invoke `codebase-architect` to analyze adjacent UI components, layout patterns, and design tokens. Report file paths and rendered structure.
+
+### Step C — Generate 3 Options (GENERATOR)
+
+Read [references/generation.md](references/generation.md).
+
+**MANDATORY:** invoke the `huashu-design` skill before generating any HTML. It provides the HTML prototype engine (React+Babel or vanilla+Tailwind CDN, Tweaks panel, App Prototype shell with AppPhone state manager, Playwright click validation, animated output). Follow its rules for the prototype type in scope.
+
+**Filesystem rule (ABSOLUTE):** every HTML file MUST be written to disk with the `Write` tool at `/tmp/prd-design-<slug>/option-X.html` BEFORE opening in a browser. Outputting inline code blocks is not sufficient.
+
+Invoke `ui-expert` agent with:
+- Feature description and discovery answers
+- Context screenshots (Read the image files)
+- Codebase-architect findings
+- 21st.dev catalog categories
+- Full generation rules from the reference
+- `huashu-design` prototype rules loaded above
+- `identity.design_philosophy` and `identity.language` to drive aesthetic and copy register
+
+Output: 3 HTML files written to `/tmp/prd-design-<slug>/` via `Write` tool.
+
+### Step D — Evaluate Options (EVALUATOR — separate agent)
+
+Read [references/evaluation.md](references/evaluation.md).
+
+Invoke a **separate** `code-reviewer` agent (NOT the same agent that generated):
+- Pass the 3 HTML files
+- Pass the context screenshots as reference
+- Pass the evaluation rubric (7 criteria, scoring 1-5, hard thresholds)
+- Request: produce evaluation report at `/tmp/prd-design-<slug>/evaluation-report.md`
+
+**If any option FAIL:** send feedback to generator, re-generate, re-evaluate. Max 5 iterations per option.
+
+**If PASS:** proceed to Step E.
+
+### Step E — Present to User
+
+1. **Open all 3 options in the user's default browser (MANDATORY):**
+   ```bash
+   open /tmp/prd-design-<slug>/option-a.html
+   open /tmp/prd-design-<slug>/option-b.html
+   open /tmp/prd-design-<slug>/option-c.html
+   ```
+   (On non-macOS hosts, substitute `xdg-open` / `start`.)
+2. Show screenshots inline as supplement.
+3. For each option: approach name, reused vs. new components. **DO NOT give evaluation scores, rankings, or recommendations on which to pick.**
+
+**STOP.** Wait for user choice.
+
+### Step F — Iterate on Feedback
+
+1. User chooses option or requests changes.
+2. Generator applies changes (with context screenshots as reference).
+3. Evaluator re-evaluates (same rubric, fresh context).
+4. Open updated HTML + show screenshot.
+5. Repeat until explicit user approval.
+
+### Step G — Save & Produce Inventory
+
+Read [references/inventory.md](references/inventory.md).
+
+1. Copy approved HTML to `${paths.prd_dir}/<slug>/design.html` (if `features.has_prd_workflow: true`; otherwise ask the user where to persist the design).
+2. Extract UI Element Inventory (sprint contract).
+3. Update state file with chosen option, design decisions, component lists.
+4. Clean up `/tmp/prd-design-<slug>/`.
+
+---
+
+## Design Principles (quick reference)
+
+These are enforced — read `${paths.ui_guidelines}` for full spec.
+
+- **Minimalism**: every control justifies its existence
+- **Mobile-first**: 320px upward, 44px touch targets, 200% text scaling
+- **Contrast**: every `bg-*` MUST have explicit `text-*` (WCAG 4.5:1)
+- **Multi-tenant theming pairing**: when `features.multi_tenant_theming: true`, themed text-token paired with themed bg-token per the project's theming pattern doc
+- **View State Trinity**: loading (skeletons), error (localized message + retry), empty (CTA). The error language follows `identity.language`.
+- **Separation of concerns**: UI / business logic / data layers stay separate
+
+---
+
+## When This Skill is Called by /prd
+
+The `/prd` skill invokes this skill for its Step 3 (UI Design Phase).
+The flow maps directly:
+
+| /prd Step | This skill Step |
+|-----------|-----------------|
+| 3a — UI Context Analysis | Steps A + B |
+| 3b — 3 Design Options | Steps C + D + E |
+| 3c — Design Iteration | Step F |
+| 3d — Save & Inventory | Step G |
+
+The `/prd` skill should invoke `ui-design` and follow its output rather than duplicating the design workflow internally.
+
+---
+
+## Delegation
+
+### To `visual-designer` agent
+
+For: hero illustrations, custom icons, empty state artwork, decorative backgrounds, onboarding visuals, campaign assets.
+
+Provide: asset type, purpose, relevant section, style-guideline reference, brand colors, aspect ratio. Use `identity.design_philosophy` to set the aesthetic direction.
+
+### To `motion-expert` agent
+
+For: hover states, page transitions, expand/collapse motion, micro-interactions, reduced-motion-safe specs.
+
+Provide: triggering action, affected element, desired feedback, accessibility requirements. If `stack.animation.canonical` is set, the motion-expert proposes specs targeting those libraries.
+
+---
+
+## Linked Skills
+
+| Skill | When |
+|-------|------|
+| `huashu-design` | **MANDATORY in Step C** — HTML prototype engine, App Prototype shell, Tweaks, Playwright validation, MP4/GIF export |
+| `ui-ux-pro-max` | Before substantial design for design intelligence |
+| `frontend-design` | To translate design into production code |
+| `webapp-testing` | For browser verification with Playwright |
+| `playwright-skill` | For quick screenshots and responsive checks |

package/framework/.claude/skills/ui-design/references/component-discovery.md

@@ -0,0 +1,54 @@
+# Component Discovery
+
+Cascade obbligatoria prima di proporre o creare qualsiasi componente UI.
+
+> Paths in this file resolve from `baldart.config.yml`. See
+> `framework/agents/project-context.md` § 4.
+
+## Step 1 — Cerca nel progetto
+
+1. Cerca in `${paths.components_root}` componenti riutilizzabili.
+2. Controlla `${paths.components_primitives}` per primitive (Button, Card, Badge, etc.).
+3. Controlla cartelle di dominio derivate da `identity.audience_segments` (es. `${paths.components_root}/<segment>/`). Se `audience_segments` è vuoto, salta questo passaggio.
+4. Preferisci estendere o comporre un componente esistente piuttosto che duplicare.
+
+## Step 2 — Cerca nel catalogo 21st.dev
+
+Prima di creare un componente da zero, controlla la libreria community.
+
+1. Se il progetto traccia un catalogo locale (per esempio `${paths.references_dir}/21st-dev-catalog.md`), leggilo. Altrimenti vai direttamente al sito.
+2. **Freshness check:** confronta `last_updated` nel frontmatter con oggi.
+   - Se più vecchio di 15 giorni → esegui il **Catalog Refresh** (sotto).
+   - Se fresco → continua.
+3. Trova la categoria rilevante e naviga l'URL 21st.dev linkato.
+4. Se esiste un componente adatto, installa:
+   ```bash
+   npx shadcn@latest add "https://21st.dev/r/<author>/<component-slug>"
+   ```
+5. Dopo l'installazione, **adatta al design system del progetto**:
+   - Token-compliance: usa i token definiti in `${paths.design_system}/tokens-reference.md` (quando `features.has_design_system: true`).
+   - Stilistica: applica le regole estetiche di `identity.design_philosophy` come specificate in `${paths.ui_guidelines}` e nell'overlay `.baldart/overlays/ui-design.md` (se presente).
+   - Multi-tenant: se `features.multi_tenant_theming: true`, applica la regola di pairing themed text/bg del progetto.
+   - Touch target: minimo 44x44px.
+6. Per **pagine landing/marketing**: i componenti possono essere usati con adattamento minimo perché in genere non richiedono il design system completo. Consulta l'overlay del progetto per la regola esatta.
+
+## Step 3 — Crea da zero (ultima risorsa)
+
+Solo se non esiste né nel progetto né su 21st.dev:
+
+- Posiziona il nuovo componente nella cartella shared o di dominio corretta (sotto `${paths.components_root}`).
+- Segui `${paths.ui_guidelines}` per tutte le decisioni stilistiche.
+- Consuma i token definiti in `${paths.design_system}/tokens-reference.md` (quando `features.has_design_system: true`).
+
+## Catalog Refresh Protocol
+
+Quando il catalogo è stale (>15 giorni da `last_updated`):
+
+1. Usa `playwright-skill` per aprire gli URL delle categorie ad alta rilevanza (buttons, cards, tables, forms, heroes, charts, calendars).
+2. Screenshot di ogni pagina ed estrai conteggi aggiornati e nuovi componenti notevoli.
+3. Aggiorna il catalogo locale (es. `${paths.references_dir}/21st-dev-catalog.md`):
+   - Aggiorna numeri "Est. Count".
+   - Aggiungi nuovi componenti notevoli con comandi di installazione diretti.
+   - Aggiorna `last_updated` a oggi.
+   - Imposta `next_refresh_due` a oggi + 15 giorni.
+4. Procedi con la ricerca dopo il refresh.

package/framework/.claude/skills/ui-design/references/evaluation.md

@@ -0,0 +1,171 @@
+# Evaluation Phase — Criteri e Rubric per il Valutatore
+
+> Stylistic identity (design philosophy, theming pairing rules) and project
+> language resolve from `baldart.config.yml`. See
+> `framework/agents/project-context.md` § 4. Project-specific stricter
+> thresholds live in `.baldart/overlays/ui-design.md` § Evaluation.
+
+Questo file definisce come valutare i mockup HTML. Il valutatore è un agente SEPARATO dal generatore (pattern GAN — ref: Anthropic "Harness Design for Long-Running Apps").
+
+**Principio fondamentale:** chi genera non si auto-valuta. La separazione generatore/valutatore
+elimina il bias sistematico di auto-approvazione.
+
+## Ruolo del Valutatore
+
+1. Riceve i file HTML generati (`option-a.html`, `option-b.html`, `option-c.html`).
+2. Apre ciascuno in browser via Playwright (`webapp-testing` skill).
+3. Prende screenshot e valuta contro i criteri sotto.
+4. Produce un report strutturato con punteggi e verdetto.
+5. Se FAIL: rimanda al generatore con feedback specifico.
+
+## Criteri di Valutazione (7 dimensioni)
+
+Ogni criterio ha un punteggio 1-5 con soglie hard.
+
+### C1 — Context Fidelity
+
+Lo shell UI circostante (sidebar, header, nav) e fedele alle screenshot reali della piattaforma.
+
+| Score | Descrizione |
+|-------|-------------|
+| 1 | Shell completamente assente o inventato |
+| 2 | Shell presente ma layout/colori significativamente diversi |
+| 3 | Shell riconoscibile, alcune discrepanze di dettaglio |
+| 4 | Shell fedele, differenze minori trascurabili |
+| 5 | Shell indistinguibile dagli screenshot reali |
+
+### C2 — Layout & Spacing
+
+Spacing, allineamento, nessun overflow/clipping, proporzioni responsive.
+
+| Score | Descrizione |
+|-------|-------------|
+| 1 | Overflow visibile, elementi sovrapposti, layout rotto |
+| 2 | Allineamento inconsistente, spacing irregolare |
+| 3 | Layout funzionale, qualche disallineamento minore |
+| 4 | Layout pulito, spacing coerente, nessun overflow |
+| 5 | Layout perfetto, gerarchia visiva chiara, breathing room bilanciato |
+
+### C3 — Design System Compliance
+
+`identity.design_philosophy` applicato secondo `${paths.ui_guidelines}` e le regole di `${paths.design_system}/` (quando `features.has_design_system: true`). Se `design_philosophy` è vuoto, valuta solo l'aderenza alle linee guida del progetto.
+
+| Score | Descrizione |
+|-------|-------------|
+| 1 | Sembra un template generico, nessuna aderenza alla design philosophy |
+| 2 | Tracce di philosophy ma applicazione parziale o sbagliata |
+| 3 | Philosophy parziale, mix di elementi corretti e generici |
+| 4 | Philosophy coerente, dettagli minori fuori spec |
+| 5 | Perfettamente aderente a `${paths.ui_guidelines}` in ogni elemento |
+
+### C4 — Typography & Readability
+
+Gerarchia leggibile, dimensioni font corrette, nessuna riga orfana o testo tagliato.
+
+| Score | Descrizione |
+|-------|-------------|
+| 1 | Testo illeggibile, gerarchia assente |
+| 2 | Testo leggibile ma gerarchia piatta o inconsistente |
+| 3 | Gerarchia base presente, qualche problema di peso/dimensione |
+| 4 | Gerarchia chiara, font scale corretto, buona leggibilita |
+| 5 | Tipografia impeccabile, gerarchia enfatizza il contenuto giusto |
+
+### C5 — Completeness
+
+Tutti gli elementi UI presenti e correttamente renderizzati. No icone mancanti, placeholder rotti, sezioni vuote, o lorem ipsum dove dovrebbe esserci testo reale nella lingua del progetto (`identity.language`).
+
+| Score | Descrizione |
+|-------|-------------|
+| 1 | Sezioni mancanti, placeholder visibili, layout incompleto |
+| 2 | La maggior parte degli elementi presenti, alcuni placeholder/mancanze |
+| 3 | Tutto presente, qualche dettaglio visivamente grezzo |
+| 4 | Completo e curato, tutti gli stati rappresentati |
+| 5 | Ogni elemento e pixel-perfect, inclusi empty/loading/error states |
+
+### C6 — Integration Clarity
+
+Elementi nuovi/modificati chiaramente marcati e visivamente coerenti con gli elementi
+circostanti esistenti.
+
+| Score | Descrizione |
+|-------|-------------|
+| 1 | Impossibile distinguere cosa e nuovo vs esistente |
+| 2 | Marker presenti ma confusi, nuovo sembra disconnesso |
+| 3 | Marker chiari, integrazione visiva accettabile |
+| 4 | Marker chiari, nuovo si integra naturalmente con l'esistente |
+| 5 | Perfetta integrazione + distinzione: nuovo e ovvio ma coerente |
+
+### C7 — Polish (production-readiness)
+
+Sembra production-ready, non un wireframe grezzo. Qualcuno vedendo questo dovrebbe
+pensare "e un design reale" non "e una bozza".
+
+| Score | Descrizione |
+|-------|-------------|
+| 1 | Wireframe grezzo, box grigi, nessun dettaglio visivo |
+| 2 | Aspetto da prototipo, manca rifinitura |
+| 3 | Decente, sembra un mockup funzionale ma non rifinito |
+| 4 | Curato, sembra quasi pronto per la produzione |
+| 5 | Indistinguibile da un design professionale finito |
+
+## Soglie Hard (FAIL se violate)
+
+- **Nessun criterio sotto 2** — qualsiasi 1 = FAIL immediato
+- **Media complessiva >= 3.5** — sotto = FAIL
+- **C1 (Context Fidelity) >= 3** — il mockup DEVE essere in-context
+- **C3 (Design System) >= 3** quando `identity.design_philosophy` è impostato — DEVE rispettare la philosophy del progetto
+
+L'overlay del progetto può aggiungere soglie più strette (es. C3 >= 4) — vedi `.baldart/overlays/ui-design.md` § Evaluation.
+
+## Contrast Check (MUST — ZERO TOLERANCE)
+
+Oltre ai 7 criteri, il valutatore DEVE eseguire un check contrasto:
+
+- Per ogni elemento con `bg-*`, verificare che esista un `text-*` esplicito
+- Se `features.multi_tenant_theming: true`: themed primary bg DEVE usare il text-token accoppiato per il tenant secondo la regola di pairing del progetto (vedi `${paths.design_system}/patterns/` o overlay)
+- Ratio minimo: 4.5:1 testo normale, 3:1 testo grande
+
+Violazione contrasto = FAIL indipendentemente dai punteggi.
+
+## Formato Report di Valutazione
+
+Salva in `/tmp/prd-design-<slug>/evaluation-report.md`:
+
+```markdown
+# Evaluation Report — <slug>
+
+Data: YYYY-MM-DD
+Iterazione: N
+
+## Option A — <nome approccio>
+
+| Criterio | Score | Note |
+|----------|-------|------|
+| C1 Context Fidelity | X/5 | ... |
+| C2 Layout & Spacing | X/5 | ... |
+| C3 Design System | X/5 | ... |
+| C4 Typography | X/5 | ... |
+| C5 Completeness | X/5 | ... |
+| C6 Integration Clarity | X/5 | ... |
+| C7 Polish | X/5 | ... |
+| **Media** | **X.X/5** | |
+| Contrast Check | PASS/FAIL | ... |
+
+**Verdetto: PASS / FAIL**
+Feedback per il generatore: [se FAIL, cosa correggere specificamente]
+
+## Option B — ...
+(stessa struttura)
+
+## Option C — ...
+(stessa struttura)
+```
+
+## Loop di Iterazione
+
+1. Generatore produce/aggiorna i file HTML.
+2. Valutatore li apre in Playwright, screenshot, valuta.
+3. Se FAIL: report con feedback → torna al generatore.
+4. Se PASS: report finale → si procede con presentazione all'utente.
+5. **Max 5 iterazioni per opzione.** Se ancora sotto soglia dopo 5, procedi con
+   la versione migliore e annota i problemi residui nel report.

package/framework/.claude/skills/ui-design/references/generation.md

@@ -0,0 +1,109 @@
+# Generation Phase — Regole per il Generatore
+
+Questo file definisce come produrre i mockup HTML. Il generatore è l'agente (o persona) che crea le opzioni di design. NON si auto-valuta — la valutazione spetta a un agente separato (vedi [evaluation.md](evaluation.md)).
+
+> Paths and stylistic identity in this file resolve from `baldart.config.yml`.
+> See `framework/agents/project-context.md` § 4. Project-specific stylistic
+> defaults (e.g. forced design philosophy, hard-coded UI language) live in
+> `.baldart/overlays/ui-design.md`.
+
+## Regola del Filesystem (ASSOLUTA — rispettare prima di tutto)
+
+Ogni file HTML generato DEVE essere scritto su disco con il tool `Write` PRIMA di aprirlo nel browser. Non è sufficiente mostrare il codice in un blocco inline.
+
+- Path di destinazione: `/tmp/prd-design-<slug>/option-a.html` (e varianti b, c).
+- Dopo la scrittura, apri nel browser di default (macOS):
+  ```bash
+  open /tmp/prd-design-<slug>/option-a.html
+  ```
+  (Linux: `xdg-open`. Windows: `start`.)
+- Il file esiste su disco → l'utente può interagire, ispezionare, condividere.
+- Solo codice inline → non verificabile, non apribile, non consegnabile.
+
+## Skill HTML (OBBLIGATORIA)
+
+Invocare la skill `huashu-design` all'inizio della fase di generazione. Essa fornisce:
+
+- Junior Designer workflow (assunzioni + reasoning + placeholder → iterazioni)
+- App Prototype shell: per ogni iPhone include AppPhone state manager interattivo
+- Immagini reali da Wikimedia/Met/Unsplash (default per app prototype)
+- Tweaks panel per varianti di design in-page
+- Validazione Playwright click-test prima della consegna
+- Export animazioni → MP4/GIF quando necessario
+
+## Prerequisiti
+
+1. **MUST** invocare skill `huashu-design` (vedi sopra).
+2. **MUST** leggere `${paths.ui_guidelines}` prima di generare qualsiasi cosa.
+3. **MUST** eseguire il [Component Discovery](component-discovery.md) cascade completo.
+4. **MUST** avere screenshot delle pagine reali dove la feature vivrà (context capture).
+
+## Context Capture (obbligatorio)
+
+Prima di generare mockup:
+
+1. Identifica 1-3 pagine dove la feature sarà integrata o adiacente.
+2. Se `npm run dev` non è in esecuzione, avvialo.
+3. Usa `webapp-testing` skill (Playwright CLI) per navigare e fare screenshot. Salva in `/tmp/prd-design-<slug>/context/`.
+4. Questi screenshot sono il **riferimento visivo** — i mockup DEVONO integrarsi con sidebar, header, navigazione, theming e stile dei componenti reali.
+5. Se le pagine richiedono auth, usa credenziali di test (verifica `MEMORY.md` o chiedi all'utente).
+
+## Regole di Generazione dei 3 Mockup
+
+Produce 3 file HTML distinti con approcci di design diversi.
+
+### Requisiti obbligatori per ogni file
+
+- **In-context**: ogni file DEVE includere lo shell UI esistente (sidebar, header, nav) che circonda l'area della feature. Riprodurre fedelmente il chrome della piattaforma basandosi sugli screenshot catturati.
+- **Contenuto nuovo nell'area principale**: chiaramente distinguibile dal chrome esistente.
+- **Stili reali**: usa gli stili dei componenti visibili negli screenshot (border radius, shadow style, button style, card style, colori, spacing).
+- **Pagina esistente modificata**: se la feature modifica una pagina esistente, mostra la pagina INTERA con le modifiche evidenziate (bordo tratteggiato attorno ai nuovi elementi).
+- **Self-contained**: CSS inline, Tailwind CDN, nessuna dipendenza esterna.
+- **Nomi file**: `option-a.html`, `option-b.html`, `option-c.html`.
+- **Rationale**: commento HTML in cima a ogni file che spiega l'approccio e come si integra con la UI esistente.
+- **Design philosophy**: applica `identity.design_philosophy` (es. "Neo-Brutalism", "Minimalist", "Glassmorphism") come definito in `${paths.ui_guidelines}` e nell'overlay del progetto. Se `design_philosophy` è vuoto, mantieni uno stile neutro coerente con gli screenshot.
+- **Lingua**: usa `identity.language` (BCP-47) per tutti i testi UI. Default `en` se non impostato.
+- **Marker**: segna aree nuove/cambiate con label floating in lingua del progetto, es. `NUOVO`/`MODIFICATO` (it) o `NEW`/`CHANGED` (en).
+- **3 differenze significative**: le opzioni devono differire in layout, gerarchia o pattern di interazione — non solo in colori.
+
+### Scheletro HTML minimo
+
+```html
+<!DOCTYPE html>
+<html lang="<identity.language>">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>UI Design — <Feature Name></title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    html { scroll-behavior: smooth; }
+  </style>
+</head>
+<body>
+  <!-- Existing UI shell (sidebar, header, nav) reproduced from screenshots -->
+  <!-- New feature content in main area -->
+</body>
+</html>
+```
+
+## Presentazione all'Utente
+
+Dopo che il valutatore ha approvato (vedi [evaluation.md](evaluation.md)):
+
+1. **Apri tutti e 3 i file nel browser di default (OBBLIGATORIO):**
+   ```bash
+   open /tmp/prd-design-<slug>/option-a.html
+   open /tmp/prd-design-<slug>/option-b.html
+   open /tmp/prd-design-<slug>/option-c.html
+   ```
+2. Mostra screenshot inline come supplemento.
+3. Per ogni opzione, elenca solo: nome dell'approccio e quali componenti esistenti riusa vs. crea nuovi. **NON dare valutazioni, punteggi, o suggerimenti su quale opzione scegliere. La scelta spetta all'utente.**
+
+## Iterazione su Feedback Utente
+
+1. L'utente sceglie un'opzione o chiede modifiche.
+2. Applica le modifiche all'opzione scelta, passando gli screenshot di contesto come riferimento.
+3. Sottometti al valutatore per ri-valutazione.
+4. Una volta approvato dal valutatore, apri nel browser e mostra screenshot.
+5. Ripeti fino ad approvazione esplicita dell'utente.

package/framework/.claude/skills/ui-design/references/inventory.md

@@ -0,0 +1,59 @@
+# 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 |
+|---|---------|------|---------|----------------|----------|
+| 1 | <name>  | page / section / component / modal / form / button / endpoint | <what it does> | <fields, props, API params> | <interactions, states, validation> |
+| 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.
+
+## 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>/`.