Add vrt to desktop and mobile libraries

.gitignore

@@ -38,5 +38,7 @@ Temporary Items
 .vscode
 
 # vercel
+.vercel
 
-.vercel
+# VRT reports
+scripts/vrt/reports/

guides/vrt-workflow.md

@@ -0,0 +1,71 @@
+# VRT Workflow for Designers
+
+This document describes how to use Visual Regression Testing (VRT) to catch visual changes when updating Mística components.
+
+## 1. Setup
+
+Before you can run VRT, the Python environment and Figma token need to be configured (one-time setup):
+
+```bash
+# Install dependencies
+pip3 install -r scripts/vrt/requirements.txt
+
+# Verify setup works
+python3 scripts/vrt/vrt.py --help
+```
+
+A valid `FIGMA_TOKEN` must be in the repo root's `.env` file (ask your team if you don't have this).
+
+## 2. Launch VRT to See Changes
+
+When you want to compare your branch changes against the current main library:
+
+1. **Create a Figma branch** and make your component changes
+2. **Add VRT frames** — In your branch, create frames named `VRT - [Component Name]` that contain the component instances you want to test
+3. **From the repository root, run:**
+
+```bash
+python3 scripts/vrt/vrt.py
+```
+
+4. **Paste your Figma branch URL** when prompted:
+
+```
+Paste your Figma branch URL: https://www.figma.com/design/.../branch/.../...
+```
+
+5. **A report opens automatically** with a three-column comparison:
+   - **Baseline** — Current main library
+   - **Branch** — Your changes
+   - **Diff** — Visual differences (red = changed)
+
+## 3. Add or Update VRT Frames
+
+When you modify a component or add a new one, update its VRT frame:
+
+1. **In your Figma branch**, find or create the VRT frame for that component
+2. **Name it** `VRT - [Component Name]` (e.g., `VRT - Button Primary States`)
+3. **Add component instances** showing all the visual states you want to test:
+   - Default, hover, active, disabled states
+   - Different sizes or variants
+   - Edge cases (full text, truncated text, etc.)
+4. **Run VRT** to see how your changes compare to the baseline
+5. **If changes look wrong**, iterate in Figma and run VRT again
+6. **When changes look correct**, you're ready to merge
+
+## 4. Update Baseline After Merging
+
+Once your branch is merged into main, a developer must update the baseline so future VRTs use the new main as reference:
+
+```bash
+# From repository root
+python3 scripts/vrt/vrt.py save-baseline --library mobile
+
+# Or for desktop
+python3 scripts/vrt/vrt.py save-baseline --library desktop
+
+# Or both at once
+python3 scripts/vrt/vrt.py save-baseline --library both
+```
+
+This captures all VRT frames from the current main file and saves them as the new baseline. The files should get committed and pushed to the `production` branch.

scripts/vrt/README.md

@@ -0,0 +1,84 @@
+# VRT — Visual Regression Testing for Figma
+
+Compare Figma branches against the main library to see what changed visually.
+
+## Setup (once)
+
+```bash
+pip3 install -r scripts/vrt/requirements.txt
+```
+
+Make sure your `.env` file at the repo root has a valid `FIGMA_TOKEN`.
+
+## Compare a branch
+
+Run the script and paste your Figma branch URL:
+
+```bash
+python3 scripts/vrt/vrt.py
+```
+
+```
+Paste your Figma branch URL: https://www.figma.com/design/.../branch/.../...
+
+Detected library: mobile
+Diffing branch against mobile baseline...
+Found 12 VRT frames. Rendering PNGs...
+
+Summary: 3 changed, 1 added, 0 removed, 8 unchanged
+Report opened in browser.
+```
+
+The library (mobile/desktop) is auto-detected from the URL. A report opens in the browser showing three columns for each changed component: **Baseline**, **Branch**, and **Diff** (with changes highlighted in red).
+
+## Update baseline
+
+After merging a Figma branch into main, update the baseline so future comparisons are accurate:
+
+```bash
+python3 scripts/vrt/vrt.py save-baseline --library mobile
+python3 scripts/vrt/vrt.py save-baseline --library desktop
+python3 scripts/vrt/vrt.py save-baseline --library both
+```
+
+This captures all VRT frames from the main file and saves them to `baselines/`. Commit and push the updated PNGs.
+
+## How VRT frames work in Figma
+
+For the tool to work, component pages in the Figma libraries need frames with names starting with **`VRT`**.
+
+### Naming
+
+- `VRT - Button Primary`
+- `VRT - Checkbox`
+- `VRT - Card - Aspect Ratio 1:1`
+
+Any frame, component, or instance whose name starts with `VRT` will be captured.
+
+### What to put inside
+
+Each VRT frame should contain component instances showing all relevant visual states — toggle booleans on, show variants, etc. The goal is to capture everything that matters visually so changes don't go unnoticed.
+
+### Supported libraries
+
+| Library | Figma file |
+|---------|-----------|
+| Mobile  | `WCkDDzlXE16R6yXaljxddj` |
+| Desktop | `DSWhPLyJzbliP1fBrLxDUR` |
+
+## CLI reference
+
+```bash
+# Interactive mode — paste a URL, get a report
+python3 scripts/vrt/vrt.py
+
+# Save baseline
+python3 scripts/vrt/vrt.py save-baseline --library mobile|desktop|both
+
+# Diff a branch (non-interactive)
+python3 scripts/vrt/vrt.py diff --branch-key <KEY> --library mobile|desktop|both
+
+# Override file key (for testing with other Figma files)
+python3 scripts/vrt/vrt.py save-baseline --library mobile --file-key <FILE_KEY>
+python3 scripts/vrt/vrt.py diff --branch-key <KEY> --library mobile --file-key <FILE_KEY>
+```

scripts/vrt/capture.py

@@ -0,0 +1,49 @@
+import os
+from figma_api import get_file_tree, get_image_urls, download_image, clean_filename
+
+
+def find_vrt_frames(node):
+    """Recursively find all frames whose name starts with 'VRT'."""
+    vrt_frames = {}
+
+    if "children" in node:
+        for child in node["children"]:
+            vrt_frames.update(find_vrt_frames(child))
+
+    if node.get("type") in ["FRAME", "COMPONENT", "INSTANCE"] and node["name"].startswith("VRT"):
+        vrt_frames[node["id"]] = clean_filename(node["name"])
+
+    return vrt_frames
+
+
+def capture_all(file_key, output_dir):
+    """Capture all VRT frames from a Figma file as PNGs.
+
+    Returns a dict mapping sanitized frame name -> PNG file path.
+    """
+    os.makedirs(output_dir, exist_ok=True)
+
+    print(f"Fetching file tree for {file_key}...")
+    file_data = get_file_tree(file_key)
+    document = file_data["document"]
+
+    vrt_frames = find_vrt_frames(document)
+    if not vrt_frames:
+        print("No VRT frames found.")
+        return {}
+
+    print(f"Found {len(vrt_frames)} VRT frame(s). Rendering PNGs...")
+    image_urls = get_image_urls(file_key, list(vrt_frames.keys()))
+
+    captured = {}
+    for node_id, img_url in image_urls.items():
+        if not img_url:
+            print(f"  Warning: no image for node {node_id}")
+            continue
+        name = vrt_frames.get(node_id, node_id)
+        path = os.path.join(output_dir, f"{name}.png")
+        download_image(img_url, path)
+        captured[name] = path
+        print(f"  Saved: {name}.png")
+
+    return captured