@telefonica/mistica 16.66.0 → 16.68.0

package/doc/llms/agents/figma-verifier.md

@@ -0,0 +1,49 @@
+# Figma verifier
+
+Audit a just-completed Figma implementation. Compare the running app against the Figma design visually and
+structurally, then report drift. Re-read [../figma-mcp.md](../figma-mcp.md) for the prime directive and skill
+rules before starting.
+
+## Tasks
+
+1. **Fetch the Figma screenshot** via `mcp__plugin_figma_figma__get_screenshot` for the entry node.
+   `get_metadata` gives the frame's viewport dimensions.
+
+2. **Render the implementation**:
+
+   - Start the dev server in the background, piping output to a log file.
+   - Wait for it to start.
+   - Screenshot via Playwright CLI:
+
+     ```bash
+     npx -y playwright@1.60.0 screenshot \
+       --viewport-size=<width>,<height> \
+       --full-page \
+       <url> \
+       /tmp/verifier-actual.png
+     ```
+
+     Use the Figma frame's dimensions. For responsive designs, repeat per breakpoint.
+
+3. **Compare visually**: open `/tmp/verifier-actual.png` and compare against the Figma screenshot. Catalog
+   drift in: layout, spacing, typography (weight/size/line-height — compare letter forms), colors, assets
+   (missing / wrong), and component primitive choice.
+
+4. **Structural / rule check**:
+
+   - Re-drill every composite component with `get_design_context({ disableCodeConnect: true })` and compare
+     props against the drilled-in DOM.
+   - Read each implementation file. Flag: hex literals or raw `var(--...)`, manual `font-size` /
+     `font-family`, composite props that don't match the non-CodeConnect DOM, spacing values absent from the
+     DOM, mismatched semantic structure (`Stack` vs `Inline`, flat vs nested), native HTML where a Mistica
+     primitive exists, wrong/missing skin/font/body-background for the file's brand.
+
+5. **Report**. One summary line (`clean` or `N issues found, M blocking`), then a bullet list ordered by
+   severity. Each issue:
+
+   - `[VISUAL]` or `[RULE]` prefix
+   - Figma node id (or screenshot region) + what the design specifies
+   - File:line (for `[RULE]`) or screenshot region (for `[VISUAL]`)
+   - What's wrong + proposed fix
+
+   Only flag drift and rule violations — no architectural rewrites or "improvements".

package/doc/{figma-mcp.md → llms/figma-mcp.md}

@@ -4,6 +4,23 @@ Mandatory reading whenever you are implementing UI from Figma through the Figma
 a `figma.com/...` URL. This file only covers the translation layer — the rest of the Mistica docs
 (`patterns.md`, `components.md`, `layout.md`, `design-tokens.md`) still apply.
 
+## Step 0: ask the user whether to run the verifier
+
+Before fetching any Figma node or writing any code, ask the user this question exactly once (use a
+structured-question tool if your harness has one):
+
+- **Question**:
+  `Run the verifier loop after implementing? It compares the rendered app against Figma both visually (Playwright screenshot) and structurally (DOM + rule audit), then iterates fixes.`
+- **Options**:
+  - **Yes, run the verifier** — recommended when fidelity matters. Catches drift the implementer can't see. It
+    will take more time and cost more tokens.
+  - **No, skip the verifier** — faster path. The agent still self-checks and reviews its work, but no
+    independent comparison runs.
+
+Remember the answer for the rest of this task. **One answer covers the whole implementation — do not re-ask
+per section.** If the user opted in, run the [verifier loop](#verifier-loop-run-before-declaring-done). If
+they opted out, do not spawn the verifier; the self-checks are the only gate.
+
 ## Prime directive: read the DOM verbatim
 
 The Figma MCP response gives you two things:
@@ -103,26 +120,6 @@ Every prop value you write — text, enum, aspect ratio, boolean — should be s
 the real (non-CodeConnect) DOM, not something you copied from the snippet. If you can't say which node in the
 drilled-in DOM justifies the value, gather more before committing it.
 
-## Assets: always download, store, and serve locally
-
-Figma MCP asset URLs (`https://www.figma.com/api/mcp/asset/<uuid>`) are valid for only ~7 days. Do **not**
-inline them anywhere. Download the asset first, save it into the project (e.g. `public/images/...` or
-`src/assets/...`), and reference the local path.
-
-Do **not** substitute unrelated stock photos (Unsplash, Picsum, Lorem Picsum, etc.) for the designer's assets.
-The real images are part of the design.
-
-The right workflow for every image in a Figma design:
-
-1. Drill into the node (per the composite section above) to get the real asset URL — initial CodeConnect stubs
-   often use `example.com/image.jpg` placeholders that hide the actual URL.
-2. Download the file (`curl -o public/images/<name>.<ext> <mcp-asset-url>`). Use names that describe the
-   content (`hero-fibra.png`, `partner-eurosport.svg`), not the Figma UUID.
-3. Reference it from code via the local path (e.g. `/images/hero-fibra.png` in Vite projects, `/images/...` or
-   `import heroFibra from './assets/hero-fibra.png'` in bundler-aware setups).
-4. If you cannot resolve an asset — the URL 404s, the node has no fill, the design legitimately has no image
-   there — say so explicitly and ask, rather than inventing a stock replacement.
-
 ## Verification checklist
 
 Before closing out a section always:
@@ -134,3 +131,20 @@ Before closing out a section always:
 
 If you can't check an item off against the DOM, re-read the DOM (with `disableCodeConnect: true` if the node
 is CodeConnect-mapped) before committing the value.
+
+## Verifier loop (run before declaring done)
+
+Skip if the user opted out in [Step 0](#step-0-ask-the-user-whether-to-run-the-verifier).
+
+Spawn a **new** subagent (via your harness's subagent mechanism — e.g. Claude's `Agent` tool with
+`subagent_type: general-purpose`, Codex's equivalent) pointed at
+[agents/figma-verifier.md](./agents/figma-verifier.md). Never reuse a subagent across iterations. Pass in the
+prompt:
+
+- Figma `fileKey` and entry `nodeId`
+- Implementation file paths you wrote or edited
+- Dev-server command and URL (check `package.json`)
+
+If the verifier reports clean, done. Otherwise fix the cited issues — each fix justified by Figma DOM or
+screenshot — and re-run with a fresh subagent. Stop after clean, 3 iterations, or out-of-scope issues (missing
+tokens, designer clarification — surface these instead of fudging).

package/doc/{llms.md → llms/llms.md}

@@ -329,7 +329,7 @@ After reading the minimum set, read any further files that apply to your specifi
 | **Testing (read if you have to implement tests)** | `doc/testing.md`         |
 | **Migrating from older versions**                 | `doc/migration-guide.md` |
 | **Optimizing bundle size with lottie**            | `doc/lottie.md`          |
-| **Implementing a Figma design via Figma MCP**     | `doc/figma-mcp.md`       |
+| **Implementing a Figma design via Figma MCP**     | `doc/llms/figma-mcp.md`  |
 
 ## Docs reference
 

package/doc/patterns.md

@@ -2,8 +2,8 @@
 
 ## Critical rules
 
-See [Critical Rules in `llms.md`](./llms.md#critical-rules) — the single source of truth. These rules apply
-throughout this document.
+See [Critical Rules in `llms.md`](./llms/llms.md#critical-rules) — the single source of truth. These rules
+apply throughout this document.
 
 ## Page layout composition
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@telefonica/mistica",
-    "version": "16.66.0",
+    "version": "16.68.0",
     "license": "MIT",
     "repository": {
         "type": "git",