1  # Verification: Output Verification Workflow
  2  
  3  Some design-agent native environments (like Claude.ai Artifacts) have a built-in `fork_verifier_agent` that spins up a subagent to screenshot-check via iframe. Most agent environments (Claude Code / Codex / Cursor / Trae / etc.) don't have this built-in capability — using Playwright manually covers the same verification scenarios.
  4  
  5  ## Verification Checklist
  6  
  7  Run through this checklist after every HTML output:
  8  
  9  **Critical rule:** verification is the maker's job. After the final edit, you must inspect the rendered result yourself. Do not declare completion from code inspection alone.
 10  
 11  ### 1. Browser Rendering Check (Required)
 12  
 13  The most basic check: **can the HTML open?** On macOS:
 14  
 15  ```bash
 16  open -a "Google Chrome" "/path/to/your/design.html"
 17  ```
 18  
 19  Or use Playwright screenshots (next section).
 20  
 21  ### 2. Console Error Check
 22  
 23  The most common issue in HTML files is JS errors causing white screens. Run Playwright:
 24  
 25  ```bash
 26  python ~/.claude/skills/cc-design/scripts/verify.py path/to/design.html
 27  ```
 28  
 29  This script will:
 30  1. Open HTML in headless Chromium
 31  2. Save a screenshot to the project directory
 32  3. Capture console errors
 33  4. Report status
 34  
 35  See `scripts/verify.py` for details.
 36  
 37  ### 3. Changed-Region Check
 38  
 39  For edits to an existing page, the most common failure mode is only checking the hero or first viewport.
 40  
 41  After your final edit:
 42  - Capture one full-page screenshot
 43  - Capture targeted screenshots for every section/component you changed
 44  - Review those screenshots yourself before delivery
 45  
 46  ### 4. Multi-Viewport Check
 47  
 48  For responsive designs, capture multiple viewports:
 49  
 50  ```bash
 51  python verify.py design.html --viewports 1920x1080,1440x900,768x1024,375x667
 52  ```
 53  
 54  ### 5. Interaction Check
 55  
 56  Tweaks, animations, button toggles — static screenshots can't capture these. **Recommend users open the browser and click through themselves**, or use Playwright screen recording:
 57  
 58  ```python
 59  page.video.record('interaction.mp4')
 60  ```
 61  
 62  ### 6. Slide-by-Slide Check
 63  
 64  For deck-type HTML, capture each slide:
 65  
 66  ```bash
 67  python verify.py deck.html --slides 10  # Capture first 10 slides
 68  ```
 69  
 70  Generates `deck-slide-01.png`, `deck-slide-02.png`... for quick review.
 71  
 72  ## Playwright Setup
 73  
 74  First-time setup:
 75  
 76  ```bash
 77  # If not yet installed
 78  npm install -g playwright
 79  npx playwright install chromium
 80  
 81  # Or Python version
 82  pip install playwright
 83  playwright install chromium
 84  ```
 85  
 86  If the user already has Playwright installed globally, use it directly.
 87  
 88  ## Screenshot Best Practices
 89  
 90  ### Full Page Screenshot
 91  
 92  ```python
 93  page.screenshot(path='full.png', full_page=True)
 94  ```
 95  
 96  ### Viewport Screenshot
 97  
 98  ```python
 99  page.screenshot(path='viewport.png')  # Default: only visible area
100  ```
101  
102  ### Specific Element Screenshot
103  
104  ```python
105  element = page.query_selector('.hero-section')
106  element.screenshot(path='hero.png')
107  ```
108  
109  Use this for **changed section verification** on long pages. If you edited `#pricing`, `#prompts`, or a footer block, capture that specific region instead of assuming the full-page screenshot is enough.
110  
111  ### High-DPI Screenshot
112  
113  ```python
114  page = browser.new_page(device_scale_factor=2)  # retina
115  ```
116  
117  ### Wait for Animation to Settle
118  
119  ```python
120  page.wait_for_timeout(2000)  # Wait 2s for animation to settle
121  page.screenshot(...)
122  ```
123  
124  ## Sharing Screenshots with Users
125  
126  ### Local Screenshots
127  
128  ```bash
129  open screenshot.png
130  ```
131  
132  Users will view in their Preview/Figma/VSCode/browser.
133  
134  ### Upload for Sharing
135  
136  If remote collaborators need to see (e.g., Slack/WeChat), let users upload with their own image hosting tools or MCP.
137  
138  ## Troubleshooting Verification Errors
139  
140  ### White Screen
141  
142  Console will always have errors. Check first:
143  
144  1. Are the React+Babel script tag integrity hashes correct? (see `react-setup.md`)
145  2. Is there a `const styles = {...}` naming conflict?
146  3. Are cross-file components exported to `window`?
147  4. JSX syntax errors (babel.min.js doesn't report errors — use non-minified babel.js)
148  
149  ### Animation Stuttering
150  
151  - Record with Chrome DevTools Performance tab
152  - Look for layout thrashing (frequent reflows)
153  - Animate `transform` and `opacity` preferentially (GPU-accelerated)
154  
155  ### Wrong Fonts
156  
157  - Check `@font-face` URL accessibility
158  - Check fallback fonts
159  - CJK fonts load slowly: show fallback first, switch when loaded
160  
161  ### Layout Misalignment
162  
163  - Check `box-sizing: border-box` is applied globally
164  - Check `* { margin: 0; padding: 0 }` reset
165  - Open gridlines in Chrome DevTools to see actual layout
166  
167  ## Verification = The Designer's Second Pair of Eyes
168  
169  **Always review yourself.** AI-generated code frequently has issues like:
170  
171  - Looks correct but has interaction bugs
172  - Static screenshot looks good but scroll breaks layout
173  - Hero looks good but a later section is broken
174  - Looks great on wide screens but collapses on narrow
175  - Forgot to test dark mode
176  - Some components don't respond to Tweaks changes
177  
178  **One minute of verification saves one hour of rework.**
179  
180  ## Common Verification Script Commands
181  
182  ```bash
183  # Basic: open + screenshot + capture errors
184  python verify.py design.html
185  
186  # Multi-viewport
187  python verify.py design.html --viewports 1920x1080,375x667
188  
189  # Multi-slide
190  python verify.py deck.html --slides 10
191  
192  # Output to specific directory
193  python verify.py design.html --output ./screenshots/
194  
195  # headless=false, open real browser for you to see
196  python verify.py design.html --show
197  ```