# Screenshot-Enhanced Design Generation
## Overview
The **generateDesignWithScreenshot** tool combines Figma API data with a screenshot of the actual design to provide more accurate HTML/CSS generation. This gives you visual context that helps create pixel-perfect implementations.
## How It Works
```
┌─────────────────────────────────────────────────┐
│ 1. Fetch Figma Design Data (API) │
│ - Colors, fonts, dimensions │
│ - Component hierarchy │
│ - Layout properties │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ 2. Capture Screenshot (Image) │
│ - Visual appearance │
│ - Actual spacing and alignment │
│ - Real-world rendering │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ 3. Generate HTML/CSS │
│ - API data → Base styles │
│ - Screenshot URL → Reference comments │
│ - Combined → More accurate output │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ 4. Output with Visual Reference │
│ - HTML file with screenshot URL │
│ - CSS comments with tips │
│ - Side-by-side comparison guidance │
└─────────────────────────────────────────────────┘
```
## Usage
### Via MCP Tool
```
Use generateDesignWithScreenshot with:
- fileKey: YwUqmarhRx74Gb4zePtEUx
- nodeId: 8384-4
- includeScreenshot: true (optional, default)
```
### Via Test Script
```bash
# Edit tests/test-screenshot-enhanced.ts with your fileKey and nodeId
npx tsx tests/test-screenshot-enhanced.ts
```
**Output:**
- `output-with-screenshot.html` - HTML/CSS with screenshot reference
- `screenshot-{nodeId}.png` - Downloaded screenshot for comparison
## What You Get
### 1. Enhanced HTML/CSS
The generated HTML includes:
```html
<!DOCTYPE html>
<html>
<head>
<style>
/*
DESIGN REFERENCE SCREENSHOT: screenshot-2168-13148.png
Original URL: https://figma-alpha-api...
📸 A screenshot has been saved locally for visual reference.
Compare the generated HTML with this image for accuracy.
💡 Tips for matching the design:
- Compare element positioning and spacing with screenshot
- Check font sizes and weights against visual appearance
- Verify colors match what you see in the image
- Adjust padding/margins for pixel-perfect alignment
- Consider using flexbox/grid for better layout control
*/
/* ... your styles ... */
</style>
</head>
<body>
<!-- Screenshot reference in comments -->
<div class="component">...</div>
</body>
</html>
```
### 2. Downloaded Screenshot
A high-quality PNG screenshot (2x scale) saved locally for:
- Side-by-side comparison
- Visual verification
- Design reference while coding
- Offline access
### 3. Helpful Comments
CSS comments include:
- Screenshot file location
- Original Figma URL (temporary)
- Tips for matching the design
- Suggested improvements
- Component metadata
## Benefits Over Standard Generation
| Feature | Standard (`generateFullDesign`) | Enhanced (`generateDesignWithScreenshot`) |
|---------|--------------------------------|------------------------------------------|
| **API Data** | ✅ Yes | ✅ Yes |
| **Screenshot** | ❌ No | ✅ Yes - downloaded and referenced |
| **Visual Context** | ❌ No | ✅ Yes - see actual appearance |
| **Comparison Guide** | ❌ No | ✅ Yes - tips in comments |
| **Accuracy** | 🟡 Good | 🟢 Better - visual verification |
| **Use Case** | Quick prototypes | Pixel-perfect implementations |
## Workflow Recommendations
### Step 1: Generate with Screenshot
```bash
npx tsx tests/test-screenshot-enhanced.ts
```
### Step 2: Open Side-by-Side
- Open `output-with-screenshot.html` in browser
- Open `screenshot-{nodeId}.png` in image viewer
- Position windows side-by-side
### Step 3: Compare & Adjust
Look for:
- **Spacing differences** - Adjust margins/padding
- **Font sizes** - May need tweaking for exact match
- **Colors** - Verify RGB values match visual
- **Alignment** - Check element positioning
- **Layout flow** - Consider flexbox/grid
### Step 4: Iterate
- Update CSS in the HTML file
- Refresh browser
- Compare again with screenshot
- Repeat until pixel-perfect
## Use Cases
### 1. Pixel-Perfect Implementation
When design accuracy is critical (landing pages, marketing sites)
```bash
# Generate with screenshot
npx tsx tests/test-screenshot-enhanced.ts
# Compare visually
# Adjust CSS for exact match
# Client/designer approval
```
### 2. Learning Design-to-Code
Understand how designs translate to CSS
```bash
# See both: screenshot + generated code
# Learn what CSS produces each visual effect
# Experiment with adjustments
```
### 3. Complex Layout Verification
For intricate designs where API data alone isn't enough
```bash
# Screenshot shows actual spacing
# API data shows exact values
# Combined = accurate implementation
```
### 4. Design Fidelity Checking
Verify your implementation matches the design
```bash
# Generate HTML/CSS
# Compare with screenshot
# Catch discrepancies early
```
## Technical Details
### Screenshot Parameters
- **Format:** PNG (best for UI)
- **Scale:** 2x (Retina quality)
- **Expiration:** URL valid ~30 minutes
- **Download:** Automatic to local file
### API Calls
1. `GET /v1/files/{fileKey}/nodes?ids={nodeId}` - Design data
2. `GET /v1/images/{fileKey}?ids={nodeId}&format=png&scale=2` - Screenshot
### Output Files
```
output-with-screenshot.html ~120 KB (HTML + CSS)
screenshot-{nodeId}.png ~1.2 MB (2x PNG)
```
## Tips for Best Results
### 1. Choose the Right Node
✅ Select the top-level component or frame
❌ Don't select individual sub-elements
### 2. Compare Systematically
```
1. Overall layout and positioning
2. Typography (font sizes, weights)
3. Colors and backgrounds
4. Spacing (padding, margins)
5. Borders and shadows
6. Interactive states (if any)
```
### 3. Use Developer Tools
```
Browser DevTools → Elements
- Inspect generated HTML
- Adjust CSS live
- Copy working values back to file
```
### 4. Consider Flexbox/Grid
Figma uses absolute positioning, but CSS flexbox/grid often works better for web:
```css
/* Instead of absolute positioning */
.container {
display: flex;
gap: 20px;
align-items: center;
}
```
### 5. Test Responsiveness
The generated CSS is fixed-width. Add media queries:
```css
@media (max-width: 768px) {
.component {
width: 100%;
padding: 10px;
}
}
```
## Comparison with Other Tools
### vs. `generateFullDesign`
- ✅ Adds screenshot reference
- ✅ More guidance in comments
- ✅ Visual verification possible
- ❌ Slightly slower (2 API calls)
### vs. `getImage` alone
- ✅ Gets both image AND code
- ✅ Code already structured
- ✅ No manual HTML/CSS writing
- ❌ Still need CSS adjustments
### vs. Manual design-to-code
- ✅ Much faster baseline
- ✅ Accurate color/font values
- ✅ Structure already created
- 🟡 May need fine-tuning
## Troubleshooting
### Screenshot URL Expired
**Problem:** URL in comments doesn't work
**Solution:** Screenshot is already downloaded locally
### Colors Don't Match Exactly
**Problem:** Visual colors differ from generated CSS
**Solution:**
- Check fill opacity in Figma
- Verify blend modes aren't applied
- Use eyedropper tool on screenshot
### Layout Looks Different
**Problem:** Elements don't align like screenshot
**Solution:**
- Add flexbox/grid instead of absolute positioning
- Adjust margins and padding
- Check for missing container elements
### Screenshot Quality Issues
**Problem:** Screenshot looks pixelated
**Solution:** Test script uses 2x scale (already optimal)
## Examples
### Example Output Structure
```
output-with-screenshot.html
├── HTML Comments
│ └── Screenshot file reference
├── CSS
│ ├── Screenshot URL comment
│ ├── Design tips comment
│ ├── Reset styles
│ └── Component styles (from API)
└── HTML Body
└── Component markup (from API)
screenshot-2168-13148.png
└── Visual reference image
```
### Example Workflow
```bash
# 1. Generate
$ npx tsx tests/test-screenshot-enhanced.ts
🎨 Generating design with screenshot reference...
📊 Step 1: Fetching Figma design data...
✅ Found node: Button Component (COMPONENT)
📸 Step 2: Fetching screenshot...
✅ Screenshot saved: screenshot-123-456.png
🎨 Step 3: Generating CSS and HTML...
✅ HTML/CSS saved: output-with-screenshot.html
# 2. Open files
$ open output-with-screenshot.html
$ open screenshot-123-456.png
# 3. Compare and adjust
# (edit output-with-screenshot.html)
# 4. Refresh and verify
```
## Future Enhancements
Potential improvements for this feature:
- [ ] AI-powered comparison suggestions
- [ ] Automatic CSS adjustment based on screenshot
- [ ] Visual diff highlighting differences
- [ ] Responsive breakpoint detection
- [ ] Animation/interaction extraction
- [ ] Multi-format output (React, Vue, etc.)
## Related Documentation
- [IMAGE-FEATURE.md](./IMAGE-FEATURE.md) - Screenshot capture details
- [CSS-IMPROVEMENTS.md](./CSS-IMPROVEMENTS.md) - CSS generation specifics
- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - Common issues
---
**Best Practice:** Always use `generateDesignWithScreenshot` for production implementations where design fidelity matters!
