raffina 0.2.0

package/docs/verification.md

@@ -0,0 +1,500 @@
+# Raffina verifier reference
+
+This document describes the verifier implemented in Raffina `0.2.0` and report schema `1.0.0`. It is a code-level reference for people integrating Raffina, interpreting a score, or building an agent loop around its output.
+
+The source of truth is [`packages/core/src/verify.ts`](../packages/core/src/verify.ts) and the eight `verify-*.ts` category modules beside it.
+
+## What verification does
+
+Given a previously extracted brand system and a target, Raffina:
+
+1. renders the target at an explicit viewport;
+2. observes the same evidence families collected during extraction;
+3. selects the reference capture for that exact viewport and default state;
+4. runs eight category verifiers;
+5. combines their scores according to the selected profile;
+6. calculates evidence coverage and load-bearing gate failures;
+7. returns a verdict, findings, caveats, and up to five ranked repairs.
+
+For a URL or local HTML file, the target observation contains:
+
+- body colors and typography;
+- counted colors, backgrounds, fonts, font sizes, radii, borders, shadows, spacing, and content widths;
+- heading styles and action copy;
+- loaded and unloaded font faces;
+- images, videos, icons, inline SVGs, backgrounds, and available SHA-256 fingerprints;
+- animations, transitions, keyframes, and reduced-motion behavior;
+- component-style snapshots and large layout regions;
+- a regional screenshot fingerprint and composition-density map;
+- capture-state evidence for consent, locale, and modal overlays.
+
+The verifier does not compare an arbitrary target against a generic desktop average. Screenshot, composition, color, typography, assets, motion, shape, components, and voice use viewport-scoped evidence when it is available.
+
+## Check result states
+
+Every category returns:
+
+```ts
+{
+  score: number; // 0–100
+  status: "measured" | "partial" | "not-measured";
+  summary: string;
+  details: Record<string, unknown>;
+}
+```
+
+The status affects evidence coverage:
+
+| Status | Coverage factor | Meaning |
+| --- | ---: | --- |
+| `measured` | 1.0 | The required reference and target evidence was available. |
+| `partial` | 0.5 | The check is useful but intrinsically incomplete. Voice is currently partial. |
+| `not-measured` | 0.0 | Evidence was missing, invalid, or incompatible. This is not a pass. |
+
+Scores are rounded to whole numbers and clamped to `0–100`.
+
+## Category weights
+
+The default `brand` profile uses all eight categories:
+
+| Category | Overall weight | Load-bearing minimum |
+| --- | ---: | ---: |
+| Visual | 30% | 80 |
+| Composition | 15% | 70 |
+| Color | 12% | 65 |
+| Typography | 13% | 75 |
+| Assets | 10% | 70 when fingerprinted reference assets exist |
+| Motion | 7% | 65 when motion is measured |
+| Shape | 5% | 65 when shape is measured |
+| Voice | 8% | No separate gate |
+
+The `visual-system` profile includes visual, composition, color, typography, motion, and shape. Asset identity and voice are still calculated and returned as diagnostics, but they are excluded from the score, verdict, findings, action order, and gates. The remaining weights are re-normalized across their active total of `0.82`.
+
+## Overall score, coverage, and verdict
+
+For the active profile:
+
+```text
+weighted score = Σ(category score × category weight) / Σ(active weights)
+
+coverage = Σ(category weight × status factor) / Σ(active weights)
+
+available-evidence score =
+  Σ(category score × category weight × status factor)
+  / Σ(category weight × status factor)
+```
+
+When coverage is at least `0.8`, Raffina uses the weighted score. Below `0.8`, it reports the available-evidence score so missing evidence is not silently converted into zeros—but the result cannot be `on-brand`.
+
+After scoring, the load-bearing gates are evaluated. Any failed gate caps the displayed score at `84`, even when the weighted average is higher. This prevents a strong palette or voice score from hiding a structural, typographic, motion, or identity failure.
+
+Verdicts are assigned exactly as follows:
+
+| Condition | Verdict |
+| --- | --- |
+| Coverage is `0` | `needs-review` |
+| Score is at least `85`, coverage is at least `0.8`, and every applicable gate passes | `on-brand` |
+| Otherwise, score is at least `60` | `needs-review` |
+| Otherwise | `off-brand` |
+
+Finding severity is separate from the final verdict:
+
+- `pass` at `85+`;
+- `warning` at `65–84`;
+- `fail` below `65`;
+- a `not-measured` check is always a warning.
+
+## Capture-state guard
+
+Raffina refuses to score a target capture that is interrupted by a consent overlay, locale selector, or modal. Every category becomes `not-measured`, coverage and score become `0`, the verdict becomes `needs-review`, and the first action asks the caller to reach the intended canonical state without accepting optional tracking.
+
+This guard runs before all category verifiers. A visually plausible screenshot contaminated by an overlay is never treated as brand truth.
+
+## 1. Visual verifier
+
+Source: [`verify-visual.ts`](../packages/core/src/verify-visual.ts)
+
+### Evidence
+
+- the exact default-state screenshot fingerprint for the target viewport;
+- a fixed regional grid of RGB color, luma, contrast, and edge density;
+- full luma and edge maps;
+- rendered image width and height.
+
+The check becomes `not-measured` when the viewport has no reference, dimensions differ, grid dimensions differ, or any fingerprint map is incomplete.
+
+### Score
+
+For every grid cell, Raffina calculates normalized RGB distance plus absolute luma, contrast, and edge-density error. It then calculates luma-map Pearson correlation across the complete screenshot.
+
+```text
+visual =
+  similarity(mean cell RGB distance, sensitivity 5) × 22%
+  + similarity(luma-map MAE, sensitivity 6) × 22%
+  + similarity(edge-map MAE, sensitivity 7) × 18%
+  + similarity(mean contrast error, sensitivity 7) × 13%
+  + max(0, luma Pearson correlation) × 25%
+```
+
+`similarity(distance, sensitivity)` is `exp(-distance × sensitivity)`.
+
+The report retains the three worst grid regions, including target→reference color, luma, contrast, edge density, and normalized page coordinates. Repair output uses those regions to say where the rendered page diverges.
+
+## 2. Composition verifier
+
+Source: [`verify-composition.ts`](../packages/core/src/verify-composition.ts)
+
+### Evidence
+
+- regional element, text, and asset density maps;
+- screenshot luma and edge structure;
+- counted spacing and content-width values;
+- component roles with background, foreground, border, radius, shadow, padding, and typography;
+- salient large regions with bounds, position, z-index, clipping, background, radius, and shadow.
+
+Like the visual check, composition requires an exact viewport, compatible dimensions, compatible grid shape, and complete maps.
+
+### Density and rendered structure
+
+Each density map is scored as:
+
+```text
+map score = max(0, cosine similarity) × 55%
+          + similarity(MAE, sensitivity 5) × 45%
+
+spatial = elements × 40% + text × 35% + assets × 25%
+
+rendered structure = max(0, luma Pearson correlation) × 65%
+                   + similarity(edge MAE, sensitivity 7) × 35%
+
+rendered base = spatial × 50% + rendered structure × 50%
+```
+
+If valid visual maps are unavailable, `rendered structure` falls back to `spatial`.
+
+### Supporting grammars
+
+The rendered base is reduced—never increased—by supporting evidence in this order:
+
+1. spacing-token grammar, 20% penalty weight;
+2. content-width grammar, 35%;
+3. component-role grammar, 20%;
+4. layered layout-region geometry, 25%.
+
+The penalty function is:
+
+```text
+supportingPenalty(base, evidence, weight) =
+  evidence is absent ? base
+  : min(base, base × (1 - weight) + evidence × weight)
+```
+
+This prevents copying spacing tokens or component colors from compensating for a wrong hero layout.
+
+Component grammar uses Jaccard set similarity for seven properties within each role, then averages across roles. Consent-related components are excluded. Transparent and translucent colors retain alpha whenever either side uses alpha.
+
+Layout-region matching considers only salient reference regions—positioned, layered, or shadowed surfaces. Geometry compares normalized `x`, `y`, width, and height. Quality is geometry multiplied by `70% + feature coverage × 20% + role match × 10%`. Candidate pairs below `0.45` geometry are ignored, the globally optimal one-to-one assignment is selected, and a region counts as matched at `0.65` quality.
+
+The report includes the three worst density regions, weakest component role and property scores, unmatched layout regions, closest candidates, and the selected global assignments.
+
+## 3. Color verifier
+
+Source: [`verify-color.ts`](../packages/core/src/verify-color.ts)
+
+### Evidence
+
+- viewport-scoped semantic roles when available;
+- the 24 highest-occurrence reference palette rows;
+- generated neutral tonal steps between semantic ink and canvas;
+- the 30 highest-occurrence parseable target foreground and background colors.
+
+CSS colors are parsed and compared in OKLab. Target observations are weighted by rendered occurrence count.
+
+### Score
+
+Raffina calculates two directions:
+
+- **target precision:** how close rendered target colors are to the reference candidates;
+- **reference coverage:** whether the required reference palette and semantic roles appear in the target.
+
+Both convert weighted mean OKLab distance to a score using `100 × exp(-distance × 8)`.
+
+If reference coverage is below `85`, the intermediate bidirectional score is `75% target precision + 25% reference coverage`. The final score cannot exceed:
+
+- the target-precision score;
+- the bidirectional score;
+- `64` when reference coverage is below `50`;
+- `64` when fewer than `50%` of rendered color occurrences are parseable.
+
+Low-saturation neutral reference colors may match another low-saturation rendered target color so an evidenced tonal scale is not penalized for small neutral shifts.
+
+The repair output identifies missing reference colors or the target color with the largest `distance × rendered share` contribution.
+
+## 4. Typography verifier
+
+Source: [`verify-typography.ts`](../packages/core/src/verify-typography.ts)
+
+### Evidence
+
+- reference body family and viewport-scoped heading roles;
+- body, heading, and whole-page font usage;
+- heading sizes, weights, line heights, and letter spacing;
+- declared font faces, actual load status, and SHA-256 font fingerprints.
+
+The body family must lead the rendered CSS stack. A differently named local family can count as equivalent only when its loaded bytes uniquely match one reference family. An ambiguous fingerprint alias is recorded but not trusted.
+
+### Score
+
+Declared use combines available evidence and re-normalizes missing usage sources:
+
+- body family match: 40%;
+- heading usage-share alignment: 35%;
+- whole-page element-share alignment: 25%.
+
+Usage-share differences use exponential similarity with sensitivity `2`. Heading hierarchy compares every observed size with its closest reference size by relative error, then uses sensitivity `4`.
+
+```text
+raw typography =
+  declared usage × 55%
+  + heading hierarchy × 20%
+  + actual loaded face × 25%
+```
+
+When hierarchy is unavailable, the formula re-normalizes over the remaining `80%`. If no acceptable face is actually present, the score is capped at `35%` before style grammar is applied.
+
+Role-specific style grammar compares exact normalized size, weight, resolved line height, and letter spacing. Family grammar compares the leading family per heading role, including only byte-verified aliases. Both grammars are supporting penalties with 20% weight each.
+
+The final typography score is capped at `74` when:
+
+- style grammar is exactly zero; or
+- the weakest reference family role scores below `0.5`.
+
+The `75` load-bearing gate therefore cannot pass through family declarations alone.
+
+## 5. Asset verifier
+
+Source: [`verify-assets.ts`](../packages/core/src/verify-assets.ts)
+
+### Evidence classes and internal weights
+
+| Asset class | Asset-check weight |
+| --- | ---: |
+| Logo | 35% |
+| Fonts | 20% |
+| Images | 20% |
+| Icons and inline SVGs | 10% |
+| Videos | 7.5% |
+| Textures/backgrounds | 7.5% |
+
+Only classes present in the viewport-scoped reference are included; their weights are re-normalized. Assets with the same fingerprint are counted once.
+
+A target logo candidate must match an expected source, carry a brand-relevant label, or match expected bytes. Unrelated root-link or technology icons do not count merely because they appear near the header.
+
+### Presence and identity
+
+Presence compares expected and observed counts logarithmically. When the reference has fingerprints:
+
+- identity precision is the share of observed fingerprint rows matching reference bytes;
+- identity coverage is the share of reference fingerprint rows found in the target;
+- identity score is `min(precision, coverage)`;
+- identity confidence is `(1 + identity score) / 2` when any identity matches, otherwise zero;
+- class score is `presence × identity confidence`.
+
+If the reference is fingerprinted but the target exposes no fingerprints, the class receives only `presence × 0.35`.
+
+The measured class scores are combined by weight. A weak class creates a balance penalty when identity is explicitly wrong, identity coverage is below `35%`, or presence is below `50%`. Any measured identity mismatch or identity coverage below `35%` caps the complete asset score at `60`.
+
+The report retains precision, coverage, matched counts, the weak classes, identity ceilings, and representative reference assets.
+
+## 6. Motion verifier
+
+Source: [`verify-motion.ts`](../packages/core/src/verify-motion.ts)
+
+### Evidence
+
+- counted animations, transitions, and keyframes;
+- duration tokens converted to milliseconds;
+- easing functions;
+- animated properties;
+- delay, iteration, direction, and fill cadence annotations;
+- normalized keyframe trajectories;
+- CSS `prefers-reduced-motion` support when extraction measured it.
+
+If a viewport-scoped reference explicitly contains no motion, a static target scores `100` and any target motion scores `0`. Without viewport-scoped evidence, an empty motion inventory is `not-measured` rather than assumed static.
+
+### Score
+
+```text
+count score = animation count similarity × 40%
+            + transition count similarity × 50%
+            + keyframe count similarity × 10%
+
+grammar = count score × 30%
+        + duration grammar × 25%
+        + easing-set similarity × 20%
+        + animated-property similarity × 25%
+```
+
+Count similarity uses the ratio of `log1p` counts. Duration grammar is the minimum of target precision and reference coverage; individual duration similarity is based on `abs(log(target/reference))` with sensitivity `1.3`.
+
+Cadence, measured reduced-motion alignment, and keyframe trajectory each apply a supporting penalty with 20% weight. `from`/`to` keyframe stops normalize to `0%`/`100%`, and animation names and formatting are removed before trajectory comparison.
+
+If duration grammar is below `0.6`, the entire motion score is capped at `60`.
+
+## 7. Shape verifier
+
+Source: [`verify-shape.ts`](../packages/core/src/verify-shape.ts)
+
+### Evidence
+
+- viewport-scoped radii;
+- counted box and text shadows;
+- counted border grammar.
+
+Radius parsing preserves percentage radii, multi-corner geometry, and browser-normalized pill radii. CSS Color 4 values inside shadows and borders are normalized to comparable colors; fully transparent shadow layers are ignored.
+
+### Score
+
+Radius precision occurrence-weights each target radius against its closest reference. Radius coverage scores each expected radius against its closest target. The radius score is the lower of precision and coverage.
+
+Shadow similarity combines:
+
+- distinct value coverage: 60%;
+- occurrence/usage overlap: 40%.
+
+When radii and shadows both exist, they contribute `60%` and `40%`; otherwise the available family carries the rendered shape score. Border grammar then applies a 20% supporting penalty.
+
+If viewport-scoped evidence explicitly describes a flat system, a target with no visible radius, shadow, or border treatments scores `100`; adding any of those treatments scores `0`. Without scoped evidence, an empty shape inventory is `not-measured`.
+
+## 8. Voice verifier
+
+Source: [`verify-voice.ts`](../packages/core/src/verify-voice.ts)
+
+Voice is intentionally heuristic and always returns `partial` when reference copy exists.
+
+### Evidence
+
+- reference and target headings;
+- reference and target calls to action;
+- exclamation rate;
+- median heading word count;
+- a fixed hype-language vocabulary;
+- CTA terminology overlap after stop-word removal.
+
+### Score
+
+```text
+heuristic =
+  exclamation-rate alignment × 35%
+  + median heading-length alignment × 35%
+  + hype-rate alignment × 30%
+```
+
+The component penalties are linear:
+
+- exclamation difference: `250` points per unit difference;
+- median heading difference: `7` points per word;
+- hype-rate difference: `220` points per unit difference.
+
+When the heuristic score is at least `85`, CTA term Jaccard similarity can reduce it through a 35% supporting penalty. Copy sample count similarity creates a confidence ceiling of `60 + sample coverage × 40`.
+
+No reference copy produces `not-measured`. Reference copy with no target copy produces a partial score of `0`.
+
+Voice has no load-bearing gate and the standard report caveat explicitly requires human review.
+
+## Image-only verification
+
+Passing a PNG or other supported raster file does not run the eight rendered-page verifiers. Raffina captures only a raster palette and deliberately returns a guarded compatibility report:
+
+- score `40`;
+- verdict `off-brand`;
+- coverage `0.25`;
+- partial palette evidence;
+- typography, shape, and voice marked unavailable;
+- a repair asking for a rendered HTML target.
+
+Image-only mode must not be used as proof that an implementation is on-brand.
+
+## Repair action ordering
+
+For checks below `85`, Raffina ranks at most five actions:
+
+1. categories failing an applicable load-bearing gate;
+2. weighted repair impact: `(85 - category score) × category weight`;
+3. lower score as the tie-breaker.
+
+Category repair functions use the measurement details rather than emitting only generic advice. Examples include:
+
+- exact worst screenshot grid regions and target→reference measurements;
+- missing or misassigned layout regions and closest target candidates;
+- target→reference content widths and component properties;
+- the loaded font face or role that failed identity/style grammar;
+- mismatched fingerprinted asset classes and representatives;
+- target→reference durations, easings, animated properties, and cadence;
+- unmatched shadow, border, radius, palette, and CTA samples.
+
+When an iteration reaches its requested numerical target but still has no required repair and is not fully polished, Raffina ranks polish actions by `(100 - category score) × category weight`.
+
+## Iteration semantics
+
+`raffina iterate` stores the report's category scores, score delta, category deltas, regressions, evidence coverage, verdict, next actions, and optional screenshot/report paths.
+
+- A category regression is recorded when its delta is less than `-2` points.
+- A target is met only when the score reaches `--target-score` **and** the report verdict is `on-brand`.
+- Histories cannot mix brand, target, viewport, profile, target score, or a different extracted observation.
+- Best runs rank complete `on-brand` results above evidence-rich `needs-review`, evidence-rich `off-brand`, low-coverage `needs-review`, and low-coverage `off-brand`; score and then coverage break ties.
+
+## Report shape
+
+A full report contains:
+
+```ts
+{
+  schemaVersion: "1.0.0";
+  profile?: "brand" | "visual-system";
+  target: string;
+  brand: string;
+  verifiedAt: string;
+  score: number;
+  verdict: "on-brand" | "needs-review" | "off-brand";
+  coverage: number;
+  checks: Record<string, CheckResult>;
+  findings: Array<{
+    category: string;
+    severity: "pass" | "warning" | "fail";
+    message: string;
+  }>;
+  nextActions: Array<{
+    category: string;
+    priority: 1 | 2 | 3 | 4 | 5;
+    instruction: string;
+    evidence: string;
+  }>;
+  caveats: string[];
+}
+```
+
+Use `raffina verify ... --json` for the complete report. `raffina iterate ... --json --summary` returns only the current run and bounded history metadata while the full typed history and optional verification report remain on disk.
+
+## How the verifier is tested
+
+The deterministic suites use frozen observations rather than changing live websites:
+
+- [`verify-foundation.test.ts`](../packages/core/test/verify-foundation.test.ts) covers profiles, viewport selection, missing evidence, screenshot integrity, determinism, and color evidence;
+- [`verify-composition.test.ts`](../packages/core/test/verify-composition.test.ts) covers density, content width, global region assignment, spacing, borders, component roles, and interrupted captures;
+- [`verify-typography.test.ts`](../packages/core/test/verify-typography.test.ts) covers loaded font bytes, aliases, usage, hierarchy, fallbacks, and secondary families;
+- [`verify-assets-shape.test.ts`](../packages/core/test/verify-assets-shape.test.ts) covers logos, responsive assets, identity coverage, icons, shadows, radii, and textures;
+- [`verify-motion-voice.test.ts`](../packages/core/test/verify-motion-voice.test.ts) covers timing, easing, properties, trajectories, reduced motion, copy coverage, tone, and repair ranking.
+
+The frozen Cursor, adversarial depth, and Expo benchmarks assert separation between genuine source captures and hard negatives. They are release gates, not examples tuned at runtime.
+
+## Known boundaries
+
+- Screenshot and composition verification is specific to the captured viewport and state.
+- Interaction sequences, routes, dark mode, and modal states must be extracted separately.
+- Fingerprints require both sides to expose fetchable bytes; otherwise asset evidence is weaker.
+- Motion compares CSS grammar and normalized trajectories, not recorded animation frames.
+- Voice remains a bounded heuristic.
+- Public-web evidence cannot supply private brand rules, asset licenses, trademark permission, accessibility approval, or brand-owner intent.
+
+An `on-brand` verdict means the measured target passed Raffina's evidence and gate model for that capture. It does not replace design, legal, accessibility, or product review.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "raffina",
+  "version": "0.2.0",
+  "description": "Refine AI-generated software with evidence-backed design extraction and verification",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "raffina": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "skills"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "keywords": [
+    "ai",
+    "brand",
+    "design-system",
+    "visual-regression",
+    "verification",
+    "agents",
+    "cli",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zvadaadam/raffina.git"
+  },
+  "homepage": "https://github.com/zvadaadam/raffina#readme",
+  "bugs": {
+    "url": "https://github.com/zvadaadam/raffina/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/raffina-design-loop/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: raffina-design-loop
+description: Run evidence-backed design reproduction and brand-adherence loops with the Raffina CLI. Use when an agent needs to extract a visual system from a URL, inspect responsive brand evidence, implement that system in a web or mobile-app harness, verify rendered output, diagnose an off-brand result, or iterate across viewports until both the score and load-bearing gates pass.
+---
+
+# Raffina Design Loop
+
+Use Raffina as the measurement engine in an agent-led implementation loop. Preserve the target app's behavior and architecture while making its rendered design follow the extracted source of truth.
+
+Read [references/cli-contract.md](references/cli-contract.md) before running commands or interpreting JSON.
+
+## 1. Define the evaluation boundary
+
+Confirm these inputs from the request or infer conservative defaults:
+
+- Reference URL and target app path or URL.
+- Required viewports. Default to desktop and mobile when the source is responsive.
+- Identity policy: exact reproduction/adherence, or visual-system transfer that preserves the target product's name, logo, and copy.
+- Whether edits are authorized. Verification alone does not authorize target changes.
+- Target score. Default to `85`, but never use score alone as completion.
+- Target start command and stable local URL for rendered verification.
+
+Keep generated evidence under `.raffina/` in the target project unless the user requests another location. Use distinct iteration histories per viewport.
+
+Use `--profile brand` for exact reproduction/adherence. Use `--profile visual-system` for transfer: source asset identity and voice remain diagnostic checks but are excluded from score, verdict, and action ordering. Never describe a visual-system `on-brand` verdict as certification of source logo, asset, copy, or voice adherence.
+
+For native mobile apps, verify a deterministic browser-visible harness such as Expo web, Storybook, or a component gallery at the intended device viewport. State that this measures visual brand adherence, not native gestures, platform rendering, or device behavior.
+
+## 2. Extract the reference
+
+Prefer the local rendered-browser provider. Use Firecrawl or hybrid acquisition only when the user authorized it and a key is already available in the environment. Never print, persist, or copy a secret into commands, reports, or source files.
+
+```sh
+raffina extract <reference-url> \
+  --provider local \
+  --viewport 1440x1000 \
+  --viewport 390x844 \
+  --output .raffina/reference.brand.json \
+  --screenshot '.raffina/reference-{viewport}.png' \
+  --json
+```
+
+Inspect the artifact before implementing:
+
+```sh
+raffina inspect .raffina/reference.brand.json --json --summary
+```
+
+Inspect every saved reference PNG with an available image viewer before choosing assets or composition. Evaluate evidence quality, not just command success. Check coverage and the extracted color scheme, CSS variables, fonts, logos/assets, spacing, content widths, shape, shadows, motion, voice, component styles, layout regions, and responsive captures. Use layout regions to reconstruct large panels and overlays from their selector, bounds, positioning, z-index, background, border, radius, shadow, and overflow. Use asset roles with their viewport, rendered dimensions, and position to distinguish prominent, navigation, card, avatar, and ordinary content media; confirm both surfaces against the reference PNG. Request focused fields from the full inspection only after choosing a category to implement.
+
+If a load-bearing category is absent or `not-measured`, re-extract with an appropriate viewport/provider or report the limitation. Do not fabricate a design rule from missing evidence.
+
+## 3. Translate evidence into an implementation plan
+
+Inspect the target codebase before editing. Find its theme/token entry points, global styles, layout primitives, reusable components, asset pipeline, route structure, and development command.
+
+Prioritize changes in this order:
+
+1. Page composition, content widths, responsive structure, and whitespace rhythm.
+2. Real fonts, logos, illustrations, icons, and other distinctive assets.
+3. Theme polarity, palette, CSS variables, typography hierarchy, and shape language.
+4. Component styles, borders, shadows, textures, interaction states, and motion.
+5. Voice and representative content density.
+
+Treat layout maps as composition signals rather than literal CSS grids. Preserve functional behavior. Do not imitate copyrighted copy or proprietary functionality when structure and representative content are sufficient.
+
+Use `apply` as a planning aid where useful. It is a dry run unless `--write` is supplied:
+
+```sh
+raffina apply .raffina/reference.brand.json <target-path> --json
+```
+
+Review its plan before using `--write`. Manual code changes are normally still required; a generated token layer is not a complete reproduction.
+
+## 4. Record a rendered baseline
+
+Start the target app and wait for its stable local URL. Verify the actual rendered page, not source files alone.
+
+```sh
+raffina iterate <target-url> \
+  --brand .raffina/reference.brand.json \
+  --profile <brand|visual-system> \
+  --history .raffina/iterations-1440x1000.json \
+  --viewport 1440x1000 \
+  --target-score 85 \
+  --label baseline \
+  --screenshot .raffina/baseline-1440x1000.png \
+  --report .raffina/baseline-1440x1000.report.json \
+  --json --summary
+```
+
+Read the per-check scores, verdict, coverage, regressions, and ordered `nextActions`. A high overall score can hide a failed content-width, typography, layout, asset, or motion gate.
+
+After choosing a category, read its full details from the run's `--report` artifact. It comes from the same stabilized observation as the compact history and screenshot, so do not re-measure merely to recover deep evidence.
+
+When composition reports `layoutRegionGrammar`, treat unmatched layered-region guidance as a structural hypothesis before component polish. Reshape the named `closestObserved` target candidate, or add/split a region when that candidate is already assigned elsewhere; then match bounds, stacking, clipping, radius, and elevation and inspect the measured PNG. Reference selectors identify evidence but do not need to be copied into the target.
+
+## 5. Iterate one hypothesis at a time
+
+Treat ordered `nextActions` as the default shortlist, not as a substitute for the exact reference and target frames. Choose the highest-priority action that is supported by the focused check details and relevant to the declared identity policy, viewport, visible state, and requested outcome. If whole-page inventory or exact byte identity ranks above a larger visible structural mismatch, keep that debt unresolved but select the screenshot-grounded hypothesis; never erase the debt or claim completion.
+
+Before editing, state one hypothesis with its active category, measured evidence, expected check/gate improvement, preservation constraints, and visual success condition. Make only that coherent change, then record another run with a specific label:
+
+```sh
+raffina iterate <target-url> \
+  --brand .raffina/reference.brand.json \
+  --profile <brand|visual-system> \
+  --history .raffina/iterations-1440x1000.json \
+  --viewport 1440x1000 \
+  --target-score 85 \
+  --label tighten-content-width \
+  --screenshot .raffina/tighten-content-width-1440x1000.png \
+  --report .raffina/tighten-content-width-1440x1000.report.json \
+  --json --summary
+```
+
+Keep a change when it improves the intended check without an unacceptable regression elsewhere. If the score drops or `regressions` identifies a meaningful loss, diagnose the category and revise the change. Do not destructively reset unrelated user work.
+
+`missingLayoutRegions` means the optimal one-to-one assignment did not give that reference region a target profile above the match threshold; it does not prove the target lacks a visible panel. Each entry may include `closestObserved` geometry, similarity, and its current reference assignment; `layoutRegionAssignments` shows the complete selected pairing. Use both before adding markup so the loop reshapes an available candidate or deliberately splits one instead of duplicating it accidentally.
+
+Repeat separately for every required viewport. Never reuse one viewport's history for another viewport. Re-extract when the reference changed or when iteration reveals that the stored evidence is insufficient.
+
+Use `--screenshot` to save the exact stabilized PNG measured by each milestone run, then inspect it with an available image viewer or browser-control facility. If no visual inspection facility is available, preserve the PNG and state that final human review is pending. The verifier measures observable rules and similarity signals; it does not replace design judgment, content review, accessibility testing, or functional testing.
+
+## 6. Apply strict completion gates
+
+Declare the visual loop complete only when every required viewport has:
+
+- `targetMet: true`.
+- `verdict: on-brand` under the declared profile.
+- Score at or above the requested target.
+- Acceptable coverage with no critical category silently unmeasured.
+- No unresolved load-bearing `nextActions` or material regressions.
+- A final human screenshot review that finds no obvious structural mismatch.
+
+If the score target is reached while the verdict is not `on-brand`, continue. Report limitations precisely when a category cannot be measured.
+
+Finish by reporting the reference artifact, viewport histories, before/after scores, meaningful check deltas, remaining caveats, and the exact validation commands used.

package/skills/raffina-design-loop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Raffina Design Loop"
+  short_description: "Extract, implement, verify, and improve brands"
+  default_prompt: "Use $raffina-design-loop to rebuild this app from a reference website and iterate until its rendered brand gates pass."