baldart 5.1.0 → 5.2.0

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

@@ -1,171 +1,131 @@
-# 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`:
+# Evaluation — Step D: deterministic gate + two independent lenses
+
+The generator never grades its own output. Step D runs three independent
+checks per iteration; none of them is performed by the generating agent:
+
+| # | Check | Who | What it judges |
+|---|---|---|---|
+| Gate 0 | `scripts/craft-check.mjs` | deterministic script | The mechanical anti-slop/craft subset — binary, zero model cost |
+| Lens A | Design quality | **`ui-quality-critic`** agent (multimodal, per option) | *Is this good design?* — the 10-dimension Design Quality Rubric (SSOT: `framework/agents/design-system-protocol.md` § "Design Quality Rubric") |
+| Lens B | Brief & context conformance | **fresh `ui-expert` instance** (NOT the generator) | *Is this the right design for THIS brief in THIS product?* — rubric below |
+
+This split exists because a mockup can be beautiful and wrong (Lens B
+catches it), correct and mediocre (Lens A catches it), or both and still
+mechanically sloppy (Gate 0 catches it). Lens A uses a *different agent
+definition* than the generator — real evaluator diversity, not just a fresh
+context of the same taste (the self-grading antipattern, framework v4.61.0).
+
+## Pipeline per iteration
+
+1. **Gate 0 — craft-check (fail-fast).** Run
+   `node <skill_dir>/scripts/craft-check.mjs option-*.html [--strict-palette]`
+   (strict in exploration regime). Any blocker → straight back to the
+   generator with the JSON findings; do NOT spend model evaluation on a
+   mechanically failing option. Gate 0 output is **not shown to the lenses**
+   (they judge clean candidates without anchoring).
+2. **Screenshot capture.** Playwright CLI headless (`webapp-testing` /
+   `playwright-skill`): per option, 1440×900 AND 375×812
+   (`viewport_role: mobile`). Capture the states strip too when present.
+   Read every screenshot you capture — a screenshot you didn't read doesn't
+   count.
+3. **Lens A — `ui-quality-critic`, one spawn per option** (parallel where
+   the runtime allows; sequentially by name on Codex — spawn mapping per
+   `framework/agents/runtime-portability-protocol.md`). Payload (its input
+   contract, mockup-flavored):
+
+   ```json
+   {
+     "card_id": "mockup:<slug>",
+     "route": "mockup:<slug>/option-<x>",
+     "viewport": { "width": 1440, "height": 900 },
+     "implementation_screenshot_path": "/tmp/prd-design-<slug>/shots/option-<x>-1440.png",
+     "states_screenshots": { "mobile": ".../option-<x>-375.png" },
+     "tolerance": "<features.e2e_review.fidelity_tolerance || 'balanced'>"
+   }
+   ```
+
+   Plus `design_system_index_path` / `tokens_reference_path` /
+   `ui_guidelines_path` when configured. It returns per-dimension scores +
+   severity-tagged findings (JSON).
+4. **Lens B — fresh `ui-expert` instance** with the context screenshots, the
+   Design Read, the discovery excerpt, the reuse list, and the rubric below.
+   It reads the mockup screenshots AND the HTML source (Lens B is the
+   conformance reviewer — reading source is allowed here, unlike the critic).
+5. **Merge + verdict** (orchestrator, criteria below). FAIL → one
+   consolidated, actionable feedback packet to the generator (findings only,
+   each with region anchor via `data-region` and a concrete fix hint).
+   Re-generate → re-evaluate. **Max 5 iterations per option**; after 5,
+   proceed with the best iteration and record residual findings honestly in
+   the report.
+
+## Lens B rubric (mockup-specific, 1–5 each)
+
+| Criterion | Judges | Hard floor |
+|---|---|---|
+| **B1 Context fidelity** *(in-context regime only)* | Shell (sidebar/header/nav) faithful to the real screenshots; new work visually native to the platform | ≥ 4 |
+| **B2 Brief completeness** | Everything the discovery/brief scopes is present; required states rendered; no orphan interactive element (Functional Traceability, `design-system-protocol.md`); every `data-region` maps to scoped content | ≥ 3 |
+| **B3 Integration clarity** | NEW/CHANGED markers present and precise; changed-page runs show the whole page | ≥ 3 |
+| **B4 Direction execution** | The option executes ITS declared direction/hypothesis with conviction — judged against the C.0 Design Read, not against the evaluator's taste. A timid half-direction fails; deliberate restraint in product register does not | ≥ 3 |
+| **B5 Copy & language** | Copy self-audit clean (`anti-slop.md` § Copy tells), correct `identity.language`, register-appropriate voice | ≥ 3 |
+
+Scoring discipline (binding):
+
+- **Cite evidence for every score** — "B1=3 because the sidebar collapses the
+  workspace switcher that exists in context-2.png" beats "feels off".
+  Numbers without evidence are rejected by the orchestrator.
+- **The score is the worst sustained band, never the average-up.**
+- **No grade inflation**: 4 means strong, not acceptable.
+- **Don't punish appropriate conservatism** (product register earns
+  familiarity; see `design-brief.md` § Register).
+- **Don't invent defects to demonstrate iteration.** A confident "first pass
+  clean, shipping" beats a fake fix.
+
+## Verdict (per option)
+
+**PASS** requires ALL of:
+
+1. Gate 0: zero blockers (warnings are allowed but listed in the report).
+2. Lens A: `quality_score ≥ 0.70`, zero `critical` findings, and the
+   color/contrast dimension carries no `major`+ finding (contrast is
+   zero-tolerance — it also surfaces via Gate 0 and B1).
+3. Lens B: every criterion ≥ its hard floor.
+
+Anything else → FAIL with the consolidated feedback packet.
+
+## Degraded mode (no multimodal lens available)
+
+On a runtime where screenshots cannot be judged visually (e.g. a
+non-multimodal Codex session), do not fake the lenses:
+
+- Run Gate 0 (unchanged — it is deterministic).
+- Replace Lens A+B with a **source-level review** by a fresh `ui-expert`
+  instance against `craft-standards.md` + `anti-slop.md` + the Design Read
+  (token compliance, structure, states presence, copy audit — everything
+  legible from HTML).
+- Prefix the report AND the user presentation with the mandatory banner:
+  `⚠️ DEGRADED: source-level evaluation only (no visual lens) — review the
+  options visually in the browser before choosing.`
+
+A silent degraded evaluation is a failed evaluation.
+
+## Report format
+
+Save to `/tmp/prd-design-<slug>/evaluation-report.md`:
 
 ```markdown
-# Evaluation Report — <slug>
+# Evaluation Report — <slug> · iteration N · <date>
 
-Data: YYYY-MM-DD
-Iterazione: N
+## Option A — <direction name>
+- Gate 0: PASS (2 warnings: off-scale-spacing ×1, img-no-dimensions ×1)
+- Lens A (ui-quality-critic): quality_score 0.81 — findings: [1 major: spacing]
+- Lens B: B1 4 · B2 4 · B3 5 · B4 4 · B5 4 (evidence per score)
+- **Verdict: PASS**
 
-## 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)
+## Option B — …
+- **Verdict: FAIL** → feedback packet: [each finding: region, expected,
+  actual, fix hint]
 ```
 
-## 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.
+The report is internal quality control: per the presentation rule (SKILL.md
+Step E) the user sees the options WITHOUT scores, rankings, or
+recommendations — except the DEGRADED banner, which is always surfaced.

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

@@ -1,72 +1,52 @@
-# 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
+# Generation — rules for the Generator (Step C.1)
+
+How to produce the mockup prototypes. The generator (the `ui-expert` agent,
+spawned per `AGENTS.md` § delegation) creates the options; it NEVER evaluates
+its own output — evaluation belongs to Step D
+([evaluation.md](evaluation.md)).
+
+> Paths and stylistic identity resolve from `baldart.config.yml`
+> (`framework/agents/project-context.md` § 4). Project-specific mandates live
+> in `.baldart/overlays/ui-design.md`.
+
+## Prerequisites (all BLOCKING)
+
+1. Step C.0 completed — the Design Read is locked
+   ([design-brief.md](design-brief.md)) and each option has its assigned
+   direction (exploration) or layout/IA hypothesis (in-context).
+2. [craft-standards.md](craft-standards.md) and [anti-slop.md](anti-slop.md)
+   read — they are binding on every line of markup you write.
+3. Component Discovery cascade completed
+   ([component-discovery.md](component-discovery.md)) — the reuse list is the
+   authority on what exists.
+4. Context screenshots captured (Step B) for in-context runs.
+
+## Filesystem rule (ABSOLUTE)
+
+Every HTML file MUST be written to disk with the `Write` tool at
+`/tmp/prd-design-<slug>/option-<x>.html` BEFORE being opened in a browser or
+screenshotted. Inline code blocks are not a deliverable: not verifiable, not
+openable, not shareable.
+
+## Token-first scaffold
+
+The mockup must speak the project's token language — this is what makes the
+downstream implement step (`/ui-implement`) near-1:1, exactly like a Claude
+Design mockup authored against the project's tokens.
+
+- **`features.has_design_system: true`**: extract the real tokens (colors,
+  spacing, radius, shadows, type) from `${paths.design_system}/tokens-reference.md`
+  / `${paths.global_styles}` and embed them as CSS custom properties in a
+  `:root` block at the top of each file. Style the mockup THROUGH those
+  variables — a value that bypasses an existing token is a defect
+  (`DS_TOKENS_DRIFT`).
+- **No design system**: define the option's direction tokens in `:root` with
+  **semantic names** (`--accent`, `--surface-2`, `--fg-muted` — never
+  `--blue-500`), derived from the chosen direction in
+  [design-directions.md](design-directions.md). This makes the option's
+  palette auditable and portable.
+
+Scaffold skeleton:
 
 ```html
 <!DOCTYPE html>
@@ -74,36 +54,89 @@ Produce 3 file HTML distinti con approcci di design diversi.
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>UI Design — <Feature Name></title>
+  <title>UI Design — <Feature> — Option <X>: <direction name></title>
   <script src="https://cdn.tailwindcss.com"></script>
   <style>
-    html { scroll-behavior: smooth; }
+    :root { /* project tokens OR direction tokens — see above */ }
   </style>
 </head>
 <body>
-  <!-- Existing UI shell (sidebar, header, nav) reproduced from screenshots -->
-  <!-- New feature content in main area -->
+  <!--
+    OPTION <X> — <direction / layout hypothesis name>
+    Design Read: <the locked one-liner from C.0>
+    Reuses: <components from discovery> · New: <proposed primitives>
+    Deliberate overrides of anti-slop bans (if any): <name them, or "none">
+  -->
+  ...
 </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
+## Structural rules (every file)
+
+- **`data-region` on every distinct region** (`<section data-region="order-list">`,
+  `data-region="filters-bar"`). This is the join key used by iteration
+  feedback ("change the filters-bar"), by the Step G inventory, and by
+  `/prd` Component Reconciliation → `component_bindings`. Region names are
+  stable across options and iterations.
+- **In-context runs**: reproduce the existing UI shell (sidebar, header, nav)
+  faithfully from the context screenshots — the platform chrome frames the
+  new work. New/changed areas are clearly marked with a floating label in the
+  project language (`NUOVO`/`MODIFICATO` for `it`, `NEW`/`CHANGED` for `en`).
+  If the feature modifies an existing page, show the WHOLE page with changes
+  outlined (dashed border).
+- **Self-contained**: inline CSS (+ Tailwind CDN), no build step. External
+  requests limited to fonts, Tailwind CDN, and image sources listed below.
+- **Responsive by construction**: the evaluator screenshots 1440px AND 375px
+  (`viewport_role: mobile`, framework v4.71). Use fluid grids
+  (`auto-fit/minmax`), container-friendly layouts, `min-h-[100dvh]`. A mockup
+  that collapses at 375px FAILS evaluation — design it, don't hope.
+- **Three genuinely different options**: exploration regime → three different
+  named directions; in-context regime → three different layout / hierarchy /
+  interaction structures. Color-only variations are a FAIL.
+
+## Content discipline (real content, no slop)
+
+- **Copy is real**: written in `identity.language`, plausible for the domain,
+  audience-correct. Run the Copy Self-Audit (`anti-slop.md` § Copy tells)
+  before handing off. Realistic data, not `99.9%` (the Jane Doe rule).
+  **When `features.has_i18n: true`** the copy is a realistic *placeholder,
+  never the final string* — externalization happens at implement time
+  (`framework/agents/i18n-protocol.md`); the mockup is throwaway.
+- **Images are real or honestly absent** — in priority order: (1) actual
+  project assets; (2) generated assets via the `visual-designer` agent /
+  `kie-ai` skill when configured; (3) seeded placeholders
+  `https://picsum.photos/seed/<descriptive-seed>/<w>/<h>`; (4) a labelled
+  placeholder block + one line telling the user what asset is needed.
+  **Verify every remote URL you didn't construct** — a guessed URL that 404s
+  ships as a broken image. Even minimalist pages need real imagery: a
+  pure-text page is not minimalism, it is incomplete work.
+- **Logos**: real SVG marks (e.g. `https://cdn.simpleicons.org/<slug>`),
+  never text wordmarks styled to look like logos.
+- **Icons**: monoline SVG (1.6–1.8px stroke) with `currentColor` — never
+  emoji.
+- **States are content**: the primary surface of each option shows the
+  populated state; key components additionally show the states that carry
+  design decisions (empty / loading / error at minimum — the full 8-state
+  taxonomy in `craft-standards.md` § States). Render them inline (a states
+  strip below the main canvas is acceptable) so the evaluator and the
+  inventory can see them.
+- **Section rhythm**: a section earns its place with a short headline
+  (≤ 8 words) + short support (≤ 25 words) + one visual OR one CTA. No data
+  dumps, no decoration-only sections.
+
+## Generator self-check (before submitting to Step D)
+
+Run the deterministic gate yourself and fix every blocker — do not spend the
+evaluator's pass on mechanical failures:
+
+```bash
+node <skill_dir>/scripts/craft-check.mjs /tmp/prd-design-<slug>/option-*.html \
+  [--strict-palette]   # exploration regime only
+```
 
-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.
+Then re-read each file once against the Pre-Flight essentials: hero fits the
+viewport · H1 ≤ 2 lines · one spacing scale · accent ≤ 2 visible uses ·
+every `bg-*` has its `text-*` · states present · copy self-audited · every
+anti-slop override declared in the rationale comment. If a box cannot be
+honestly ticked, the option is not done — fix it before handing off.

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

@@ -12,7 +12,10 @@ 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.
+2. Cammina le annotazioni `data-region` (ogni regione distinta del mockup ne
+   porta una — regola di generazione, v2.0.0) e dentro ciascuna identifica
+   OGNI elemento UI distinto. Le regioni sono la join key verso i
+   `component_bindings` della card (`agents/card-schema.md`).
 3. Produci l'inventario strutturato nel formato sotto.
 
 ## Formato
@@ -65,5 +68,9 @@ Source: ${paths.prd_dir}/<slug>/design.html (option <X>, approved <date>)
 ## Artefatti prodotti
 
 1. Copia l'HTML approvato in `${paths.prd_dir}/<slug>/design.html`.
-2. Aggiorna il state file del PRD con l'inventario.
+2. Aggiorna il state file del PRD con l'inventario + il Design Read
+   dell'opzione scelta (direzione, register, dial — alimenta la rotation rule
+   della prossima esplorazione). **Run standalone** (nessun state file PRD):
+   scrivi inventario + Design Read in `<design-dir>/design-session.md`
+   accanto a `design.html`.
 3. Pulisci `/tmp/prd-design-<slug>/`.