zhongwei/gh-prateekmedia-claude-dev-skills-figma-to-flutter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:48:22 +08:00
commit f1ea3fd33b
6 changed files with 1032 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

390
skills/figma-to-flutter/SKILL.md Normal file
View File

@@ -0,0 +1,390 @@
---
name: figma-to-flutter
description: This skill should be used when converting Figma designs to Flutter code. Trigger this skill when users say "convert this Figma design to Flutter", "run Figma workflow", "implement this Figma screen", or provide Figma links requesting Flutter UI implementation. The skill handles the complete workflow from extracting Figma metadata to implementing pixel-perfect Flutter UIs with iterative testing.
---
# Figma to Flutter Workflow
## Overview
Convert Figma designs into Flutter code through an automated workflow that extracts design metadata, generates reference code, exports assets, implements the UI, and iteratively tests until the implementation matches the design pixel-perfectly.
## When to Use This Skill
Trigger this workflow when users:
- Provide Figma design links and request Flutter implementation
- Say "convert this Figma design to Flutter code"
- Say "run Figma workflow" or "trigger flutter ui workflow"
- Say "implement this Figma screen"
- Request UI implementation from Figma designs
## Workflow Process
### Step 1: Preparation
#### Determine Feature Name
If not provided by the user, infer the feature name from:
- Branch name
- Conversation context
- Design content
- User's working directory
Ask the user if unclear.
#### Set Up Workspace Directory
Create the workspace structure at git repository root:
```bash
mkdir -p .ui-workspace/$FEATURE/{figma_screenshots,figma_images,figma_code,app_screenshots}
```
Ensure `.ui-workspace/` is in `.git/info/exclude`:
```bash
grep -q "^\.ui-workspace/$" .git/info/exclude || echo ".ui-workspace/" >> .git/info/exclude
```
#### Verify API Server
Check if the Figma API server is running:
```bash
curl -s http://localhost:3001/health
```
If server is not running, set it up (one-time):
```bash
# Check if already cloned
if [ ! -d ~/Documents/figma-api ]; then
mkdir -p ~/Documents
git clone https://github.com/prateekmedia/FigmaToCode-RestApi ~/Documents/figma-api
echo "API server cloned. Please follow ~/Documents/figma-api/README to install dependencies and start the server."
else
echo "API server exists but not running. Please start it: cd ~/Documents/figma-api && [start command from README]"
fi
```
Wait for user to start the server before proceeding.
### Step 2: Extract Figma Metadata
#### Analyze Asset Requirements First
Before making API calls, analyze the app's asset structure to determine which scales to download:
1. Check `assets/` directory structure
2. Search for `Image.asset` calls to identify scale parameters
3. Determine which scales are actually needed
See **Step 3: Asset Management** for detailed analysis instructions.
#### Run API Calls
Execute both API calls **in parallel** to extract all metadata from the Figma design.
**Screenshot API**:
```bash
curl -X POST http://localhost:3001/api/screenshot \
-H "Content-Type: application/json" \
-d "{
\"url\": \"$FIGMA_URL\",
\"format\": \"png\",
\"scale\": 2,
\"saveToFile\": true,
\"directory\": \".ui-workspace/$FEATURE/figma_screenshots\"
}"
```
**Convert API** (customize `scales` based on asset analysis):
```bash
# Default: Download all scales
curl -X POST http://localhost:3001/api/convert \
-H "Content-Type: application/json" \
-d "{
\"url\": \"$FIGMA_URL\",
\"settings\": {
\"framework\": \"Flutter\"
},
\"exportImages\": true,
\"exportImagesOptions\": {
\"scales\": [\"1x\", \"2x\", \"3x\", \"4x\"],
\"directory\": \".ui-workspace/$FEATURE/figma_images\"
},
\"output\": {
\"saveToFile\": true,
\"directory\": \".ui-workspace/$FEATURE/figma_code\"
}
}"
```
**Customize scales**: Modify the `scales` array based on your analysis (e.g., `[\"2x\", \"3x\"]` if app only uses those).
**Results**:
- Design screenshot: `.ui-workspace/$FEATURE/figma_screenshots/`
- Generated Flutter code: `.ui-workspace/$FEATURE/figma_code/`
- Exported assets: `.ui-workspace/$FEATURE/figma_images/{requested_scales}/`
### Step 3: Implementation
#### Review Reference Materials
Examine the extracted materials:
1. **Figma screenshot**: Visual reference for the design
2. **Generated code**: Reference for text styles, dimensions, colors, layout
3. **Assets**: Images to integrate into the app
#### Implement Flutter UI
Using the reference materials:
**Text Styles**: Extract font families, sizes, weights, and colors from generated code
**Layout**: Reference container dimensions, padding, margins, and widget hierarchy
**Colors**: Use exact hex values from the design
**Spacing**: Match padding, margin, and gap values
**Important**: Write proper Flutter code following app conventions. Do not copy generated code directly—use it as a reference.
#### Asset Management
**1. Analyze Existing Asset Structure**
Before downloading or copying assets, examine the app's current asset organization:
- Check if `assets/` directory exists and how it's structured
- Identify the scaling strategy used in the codebase:
- **Multi-directory approach**: Separate directories for each scale (e.g., `assets/`, `assets/2x/`, `assets/3x/`, `assets/4x/`)
- **Single directory with scale parameter**: Single `assets/` directory with explicit `scale` parameter in `Image.asset()` calls
- **No standard structure**: May need to establish one
**2. Determine Required Asset Scales**
Based on the analysis:
- **If multi-directory structure exists**: Check which scale directories are present (e.g., only `assets/2x/` and `assets/3x/`)
- **If using scale parameter**: Search for `Image.asset` calls to identify what scale values are used (e.g., `scale: 4`)
- **If no standard exists**: Default to downloading 3x scale assets
Only download the scales actually needed by the app to avoid unnecessary files.
**3. Download Required Scales from API**
Modify the Convert API call to download only necessary scales:
```bash
# Example: If app uses only 2x and 3x
curl -X POST http://localhost:3001/api/convert \
-H "Content-Type: application/json" \
-d "{
\"url\": \"$FIGMA_URL\",
\"settings\": {\"framework\": \"Flutter\"},
\"exportImages\": true,
\"exportImagesOptions\": {
\"scales\": [\"2x\", \"3x\"],
\"directory\": \".ui-workspace/$FEATURE/figma_images\"
},
\"output\": {
\"saveToFile\": true,
\"directory\": \".ui-workspace/$FEATURE/figma_code\"
}
}"
```
**4. Identify Required Assets**
Review generated code to find referenced image assets.
**5. Copy and Rename Assets**
Copy assets from `.ui-workspace/$FEATURE/figma_images/` following the app's existing structure:
**Multi-directory structure**:
```bash
# Copy to matching scale directories
cp .ui-workspace/$FEATURE/figma_images/2x/asset.png assets/2x/new_name.png
cp .ui-workspace/$FEATURE/figma_images/3x/asset.png assets/3x/new_name.png
```
**Single directory with scale parameter**:
```bash
# Copy only the required scale (e.g., 4x)
cp .ui-workspace/$FEATURE/figma_images/4x/asset.png assets/new_name.png
# Then use: Image.asset('assets/new_name.png', scale: 4)
```
**No standard structure**:
```bash
# Default to 3x scale in single directory
cp .ui-workspace/$FEATURE/figma_images/3x/asset.png assets/new_name.png
# Use with explicit scale: Image.asset('assets/new_name.png', scale: 3)
```
Rename assets to meaningful names using snake_case (e.g., `profile_avatar.png`, `feed_background.png`).
**6. Create Asset Mapping**
Maintain `.ui-workspace/$FEATURE/figma_images/mapping.json`:
```json
{
"123:456_user_avatar.png": "assets/profile_avatar.png",
"789:012_background.png": "assets/feed_background.png"
}
```
**7. Update pubspec.yaml**
Ensure assets are declared according to the app's structure:
**Multi-directory**:
```yaml
flutter:
assets:
- assets/
- assets/2x/
- assets/3x/
```
**Single directory**:
```yaml
flutter:
assets:
- assets/
```
### Step 4: Testing
#### Create Golden Tests
Write golden tests to capture widget screenshots:
```dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('FeatureName screen golden test', (WidgetTester tester) async {
// Set device size to match Figma design
await tester.binding.setSurfaceSize(Size(375, 812)); // Example: iPhone X
await tester.pumpWidget(
MaterialApp(
home: YourImplementedScreen(),
),
);
await expectLater(
find.byType(MaterialApp),
matchesGoldenFile('goldens/feature_name.png'),
);
});
}
```
**Important Considerations**:
- Match device size to Figma design dimensions
- Ensure images render (use test image data)
- Ensure text is not obscured
- For scrollable content with finite height: capture complete area if possible
- For infinite/long scrollable content: capture multiple scroll states
Generate golden files:
```bash
flutter test --update-goldens
```
#### Capture App Screenshots
Take screenshots from the running app:
**iOS Simulator**:
```bash
xcrun simctl io booted screenshot .ui-workspace/$FEATURE/app_screenshots/ss_$(date +%Y-%m-%d_%H-%M-%S)_$description.png
```
**Android Emulator**:
```bash
adb shell screencap -p > .ui-workspace/$FEATURE/app_screenshots/ss_$(date +%Y-%m-%d_%H-%M-%S)_$description.png
```
**Real iOS Device**:
```bash
~/Documents/scripts/ios_screenshot.sh .ui-workspace/$FEATURE/app_screenshots/ss_$(date +%Y-%m-%d_%H-%M-%S)_$description.png
```
Replace `$description` with a brief description (e.g., `Feed_View`, `Profile_Edit`).
### Step 5: Comparison and Iteration
#### Compare Screenshots
Open side-by-side:
- **Figma screenshot**: `.ui-workspace/$FEATURE/figma_screenshots/`
- **App screenshot**: `.ui-workspace/$FEATURE/app_screenshots/`
#### Identify Differences
Check for discrepancies in:
- **Layout**: Widget positioning, alignment, constraints
- **Text**: Font family, size, weight, color, line height
- **Colors**: Exact hex values, opacity
- **Spacing**: Padding, margins, gaps
- **Assets**: Image rendering, scaling, paths
- **Styling**: Borders, shadows, border radius
#### Fix Issues
Update Flutter implementation based on identified differences.
Common issues:
- Incorrect constraints (Expanded/Flexible usage)
- Wrong font properties
- Color mismatches
- Padding/margin discrepancies
- Asset resolution or path errors
#### Retest
Hot reload or restart the app:
```bash
# Hot reload
kill -SIGUSR1 $(cat /tmp/flutter-figma-workflow.pid)
# Hot restart
kill -SIGUSR2 $(cat /tmp/flutter-figma-workflow.pid)
```
Take new app screenshots and compare again.
#### Iterate Until Perfect
Repeat the comparison → fix → retest cycle until app screenshots match Figma screenshots **exactly**.
**Iteration Strategy**:
1. Fix major layout and positioning issues first
2. Address styling (colors, fonts, sizes)
3. Fine-tune details (shadows, borders, spacing)
4. Test after each round of fixes
## Additional Resources
For detailed information, refer to the bundled references:
- **`references/api_setup.md`**: Complete API documentation, setup instructions, troubleshooting
- **`references/workflow_details.md`**: In-depth workflow details, asset management, testing strategies, common issues
## Tips for Success
**Use Reference Code Wisely**: Treat generated code as a reference for values (colors, sizes, spacing), not as production-ready code.
**Asset Organization**: Keep asset naming consistent and maintain the mapping file for future reference.
**Incremental Testing**: Test frequently during implementation rather than waiting until the end.
**Device Consistency**: Use the same device/simulator dimensions throughout testing for accurate comparison.
**Pixel-Perfect Goal**: The workflow is complete only when app screenshots and Figma screenshots are visually identical.

174
skills/figma-to-flutter/references/api_setup.md Normal file
View File

@@ -0,0 +1,174 @@
# Figma API Server Setup
## Prerequisites Check
Before starting the workflow, verify the Figma API server is running at `http://localhost:3001`.
Test with:
```bash
curl -s http://localhost:3001/health || echo "Server not running"
```
## Initial Setup (One-Time)
If the server is not running, set it up:
### 1. Clone Repository
```bash
mkdir -p ~/Documents
git clone https://github.com/prateekmedia/FigmaToCode-RestApi ~/Documents/figma-api
```
### 2. Launch Server
```bash
cd ~/Documents/figma-api
# Follow the README instructions to:
# - Install dependencies
# - Set up FIGMA_TOKEN in .env
# - Start the server on port 3001
```
## API Endpoints
### Screenshot API
Captures Figma design screenshots.
**Endpoint**: `POST http://localhost:3001/api/screenshot`
**Request Body**:
```json
{
"url": "$FIGMA_URL",
"format": "png",
"scale": 2,
"saveToFile": true,
"directory": ".ui-workspace/$FEATURE/figma_screenshots"
}
```
**Parameters**:
- `url`: Full Figma design URL
- `format`: Output format (png/svg/jpg)
- `scale`: Screenshot scale (0.5-4, recommend 2)
- `saveToFile`: Always true for this workflow
- `directory`: Relative path from git repo root
### Convert API
Converts Figma designs to Flutter code and exports assets.
**Endpoint**: `POST http://localhost:3001/api/convert`
**Request Body (Default - All Scales)**:
```json
{
"url": "$FIGMA_URL",
"settings": {
"framework": "Flutter"
},
"exportImages": true,
"exportImagesOptions": {
"scales": ["1x", "2x", "3x", "4x"],
"directory": ".ui-workspace/$FEATURE/figma_images"
},
"output": {
"saveToFile": true,
"directory": ".ui-workspace/$FEATURE/figma_code"
}
}
```
**Request Body (Customized Scales)**:
```json
{
"url": "$FIGMA_URL",
"settings": {
"framework": "Flutter"
},
"exportImages": true,
"exportImagesOptions": {
"scales": ["2x", "3x"],
"directory": ".ui-workspace/$FEATURE/figma_images"
},
"output": {
"saveToFile": true,
"directory": ".ui-workspace/$FEATURE/figma_code"
}
}
```
**Parameters**:
- `settings.framework`: Must be "Flutter"
- `exportImages`: Always true to get asset images
- `exportImagesOptions.scales`: Array of scales to export (e.g., `["1x", "2x", "3x", "4x"]` or subset like `["3x"]`)
- `exportImagesOptions.directory`: Where to save exported assets
- `output.directory`: Where to save generated Flutter code
**Customizing Scales**:
Before calling this API, analyze the app's asset structure to determine which scales are needed:
1. **Multi-directory structure** (e.g., `assets/`, `assets/2x/`, `assets/3x/`):
- Check which scale directories exist
- Request only those scales: `["1x", "2x", "3x"]`
2. **Single directory with scale parameter** (e.g., `Image.asset('img.png', scale: 4)`):
- Search codebase for `Image.asset` calls with scale parameters
- Request only the scale value used: `["4x"]` or `["3x"]`
3. **No standard or new project**:
- Default to 3x scale: `["3x"]`
**Benefits of Customizing Scales**:
- Reduces download size and time
- Avoids cluttering workspace with unused resolutions
- Matches app's existing conventions
**Output Structure**:
- Code files saved to `figma_code/`
- Assets exported to `figma_images/` with subdirectories based on requested scales:
- `1x/` - Base resolution assets (if requested)
- `2x/` - 2x resolution assets (if requested)
- `3x/` - 3x resolution assets (if requested)
- `4x/` - 4x resolution assets (if requested)
### Image Export API (Optional)
For re-exporting specific images or different scales.
**Endpoint**: `POST http://localhost:3001/api/export-images`
**Request Body**:
```json
{
"url": "$FIGMA_URL",
"exportOptions": {
"scales": ["1x", "2x", "3x", "4x"],
"directory": ".ui-workspace/$FEATURE/figma_images"
}
}
```
## Image Naming Convention
Exported images use the format: `{nodeId}_{originalName}` to prevent conflicts.
Example: `123:456_user_avatar.png`
## Troubleshooting
### Server Not Responding
- Check if process is running: `lsof -i :3001`
- Review server logs in the figma-api directory
- Verify FIGMA_TOKEN is set in .env
### Authentication Errors
- Ensure FIGMA_TOKEN is valid
- Check token has access to the Figma file
- Verify file URL is correct and accessible
### Export Failures
- Confirm directory paths are relative to git repo root
- Ensure sufficient disk space
- Check file permissions for target directories

401
skills/figma-to-flutter/references/workflow_details.md Normal file
View File

@@ -0,0 +1,401 @@
# Figma to Flutter Workflow Details
## Directory Structure
All workflow files are stored in `.ui-workspace/{FeatureName}/` at the git repository root:
```
.ui-workspace/{FeatureName}/
├── app_screenshots/ # Screenshots from running Flutter app
├── figma_screenshots/ # Design screenshots from Figma
├── figma_images/ # Exported assets (scales vary based on app needs)
│ ├── 1x/ # Only if requested
│ ├── 2x/ # Only if requested
│ ├── 3x/ # Only if requested
│ ├── 4x/ # Only if requested
│ └── mapping.json # Asset mapping (figma → app assets)
├── figma_code/ # Generated Flutter code from Figma
└── flutter-run.log # Debug logs (optional)
```
**Important**:
- Create `.ui-workspace/` in the git repo root
- Add `.ui-workspace/` to `.git/info/exclude` if not already present (should not be committed)
- Only download the asset scales your app actually uses (see Asset Management section)
## Implementation Phase
### Using Reference Code
The generated Figma code serves as a reference for:
- **Text styles**: Font families, sizes, weights, colors
- **Container dimensions**: Width, height, padding, margins
- **Colors**: Exact color values from design
- **Layout structure**: Widget hierarchy and positioning
- **Spacing**: Gaps, padding values
**Important**: Do not copy the generated code directly. Use it as a reference while writing proper Flutter code that follows app conventions.
### Asset Management
#### 1. Analyze Existing Asset Structure
Before downloading or copying assets, analyze the app's current asset organization to understand the scaling strategy.
**Check Directory Structure**:
```bash
# List asset directories
ls -la assets/
```
**Common Patterns**:
**Pattern A: Multi-directory approach**
```
assets/
assets/2x/
assets/3x/
assets/4x/
```
Each scale has its own directory. Flutter automatically picks the appropriate resolution.
**Pattern B: Single directory with scale parameter**
```
assets/
```
Single directory with explicit `scale` parameter in code:
```dart
Image.asset('assets/image.png', scale: 4)
```
**Pattern C: No standard structure**
New project or inconsistent structure. Need to establish conventions.
#### 2. Search for Scale Usage in Code
Identify how the app currently handles image scaling:
```bash
# Search for Image.asset calls with scale parameter
grep -r "Image\.asset.*scale:" lib/
# Examples you might find:
# Image.asset('assets/icon.png', scale: 4)
# Image.asset('assets/background.png', scale: 3)
```
**Analysis**:
- If you find `scale: 4` frequently → app uses 4x assets in single directory
- If you find `scale: 3` → app uses 3x assets
- If you find multiple values → mixed approach, need to understand context
- If you find no scale parameters → likely uses multi-directory approach
#### 3. Determine Required Scales
Based on analysis, decide which scales to download:
**Multi-directory structure**: Check which directories exist
```bash
# Example: Only 2x and 3x exist
ls -d assets/*/ # Shows: assets/2x/ assets/3x/
# Download only: ["2x", "3x"]
```
**Single directory with scale parameter**: Match the scale values used
```bash
# If code uses scale: 4 consistently
# Download only: ["4x"]
```
**No standard or new project**:
- Default to **3x scale** as a good balance
- Download only: ["3x"]
**Important**: Only download scales actually needed to avoid unnecessary files.
#### 4. Download Assets with Correct Scales
Modify the Convert API call to request only needed scales:
```bash
# Example: App uses only 2x and 3x
curl -X POST http://localhost:3001/api/convert \
-H "Content-Type: application/json" \
-d "{
\"url\": \"$FIGMA_URL\",
\"settings\": {\"framework\": \"Flutter\"},
\"exportImages\": true,
\"exportImagesOptions\": {
\"scales\": [\"2x\", \"3x\"],
\"directory\": \".ui-workspace/$FEATURE/figma_images\"
},
\"output\": {
\"saveToFile\": true,
\"directory\": \".ui-workspace/$FEATURE/figma_code\"
}
}"
```
#### 5. Identify Required Assets
Review the generated Figma code to identify which image assets are referenced in the design.
#### 6. Copy and Rename Assets
Copy assets from `.ui-workspace/$FEATURE/figma_images/` following the app's structure:
**Multi-directory structure**:
```bash
# Copy each scale to corresponding directory
cp .ui-workspace/Feed/figma_images/2x/123:456_user_avatar.png assets/2x/profile_avatar.png
cp .ui-workspace/Feed/figma_images/3x/123:456_user_avatar.png assets/3x/profile_avatar.png
# Usage in code (Flutter picks resolution automatically):
Image.asset('assets/2x/profile_avatar.png')
```
**Single directory with scale parameter (4x example)**:
```bash
# Copy only the required scale
cp .ui-workspace/Feed/figma_images/4x/123:456_user_avatar.png assets/profile_avatar.png
# Usage in code with explicit scale:
Image.asset('assets/profile_avatar.png', scale: 4)
```
**Single directory with scale parameter (3x example)**:
```bash
# Copy only 3x scale
cp .ui-workspace/Feed/figma_images/3x/123:456_background.png assets/background.png
# Usage in code:
Image.asset('assets/background.png', scale: 3)
```
**No standard structure (establishing 3x default)**:
```bash
# Use 3x as default
cp .ui-workspace/Feed/figma_images/3x/123:456_icon.png assets/icon.png
# Usage in code with explicit scale:
Image.asset('assets/icon.png', scale: 3)
```
**Renaming Guidelines**:
- Use snake_case
- Be specific and descriptive (e.g., `profile_avatar.png` not `image1.png`)
- Include context if needed (e.g., `feed_empty_state_illustration.png`)
#### 7. Maintain Asset Mapping
Create/update `.ui-workspace/$FEATURE/figma_images/mapping.json` to track renamed assets:
```json
{
"123:456_user_avatar.png": "assets/profile_avatar.png",
"789:012_background.png": "assets/background.png",
"345:678_icon.png": "assets/feed_icon.png"
}
```
This mapping helps track which Figma assets correspond to which app assets for future reference.
#### 8. Update pubspec.yaml
Ensure assets are declared according to the app's structure.
**Multi-directory**:
```yaml
flutter:
assets:
- assets/
- assets/2x/
- assets/3x/
# Add other scales if used
```
**Single directory**:
```yaml
flutter:
assets:
- assets/
```
#### 9. Verify Asset Usage
After copying assets, verify they're being used correctly in the code:
**Multi-directory**: Check that Flutter is finding the right resolution
```dart
// Flutter automatically selects from assets/, assets/2x/, assets/3x/
Image.asset('assets/2x/profile_avatar.png')
```
**Single directory with scale**: Ensure scale parameter matches downloaded resolution
```dart
// If you downloaded 4x, use scale: 4
Image.asset('assets/profile_avatar.png', scale: 4)
// If you downloaded 3x, use scale: 3
Image.asset('assets/background.png', scale: 3)
```
## Testing Phase
### Golden Tests
Golden tests capture widget screenshots for visual regression testing.
#### Test Structure
```dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('UserProfile screen golden test', (WidgetTester tester) async {
await tester.pumpWidget(
MaterialApp(
home: UserProfileScreen(), // Your implementation
),
);
await expectLater(
find.byType(MaterialApp),
matchesGoldenFile('goldens/user_profile.png'),
);
});
}
```
#### Important Considerations
1. **Device Size**: Match the Figma design dimensions
```dart
await tester.binding.setSurfaceSize(Size(375, 812)); // iPhone X
```
2. **Rendering**: Ensure all content is visible
- Images must load (use fake image data in tests)
- Text should not be obscured
- No overflow errors
3. **Scrollable Content**:
- **Finite height**: Capture complete scrollable area if possible
- **Infinite/long lists**: Capture multiple scroll states for comparison
```dart
// Capture initial state
await expectLater(find.byType(MaterialApp), matchesGoldenFile('screen_top.png'));
// Scroll and capture
await tester.drag(find.byType(ListView), Offset(0, -300));
await tester.pumpAndSettle();
await expectLater(find.byType(MaterialApp), matchesGoldenFile('screen_scrolled.png'));
```
#### Running Golden Tests
```bash
# Generate golden files
flutter test --update-goldens
# Run tests against golden files
flutter test
```
### App Screenshots
Capture screenshots from the running app for visual comparison.
#### iOS Simulator
```bash
xcrun simctl io booted screenshot .ui-workspace/$FEATURE/app_screenshots/ss_$(date +%Y-%m-%d_%H-%M-%S)_$description.png
```
#### Android Emulator
```bash
adb shell screencap -p > .ui-workspace/$FEATURE/app_screenshots/ss_$(date +%Y-%m-%d_%H-%M-%S)_$description.png
```
#### Real iOS Device
```bash
~/Documents/scripts/ios_screenshot.sh .ui-workspace/$FEATURE/app_screenshots/ss_$(date +%Y-%m-%d_%H-%M-%S)_$description.png
```
**Naming Convention**:
- Prefix: `ss_`
- Timestamp: `$(date +%Y-%m-%d_%H-%M-%S)`
- Description: Brief description of what's captured (e.g., `Feed_View`, `Profile_Edit`)
## Comparison & Iteration
### Visual Comparison Process
1. **Open Side-by-Side**:
- Figma screenshot: `.ui-workspace/$FEATURE/figma_screenshots/`
- App screenshot: `.ui-workspace/$FEATURE/app_screenshots/`
2. **Check for Differences**:
- Layout positioning
- Text sizes and weights
- Colors (exact match)
- Spacing (padding, margins)
- Asset rendering
- Shadows and borders
- Border radius values
3. **Document Issues**: Note specific differences to fix
4. **Implement Fixes**: Update Flutter code based on identified issues
5. **Retest**: Take new app screenshots and compare again
6. **Repeat**: Continue until app screenshots match Figma screenshots exactly
### Common Issues
**Layout Problems**:
- Incorrect constraints (Expanded, Flexible usage)
- Wrong alignment values
- Missing or excessive padding
**Text Rendering**:
- Font family mismatch
- Wrong font weight
- Incorrect font size
- Text color differences
- Line height issues
**Asset Issues**:
- Wrong asset resolution
- Incorrect asset path
- Asset scaling problems
- Missing assets
**Color Mismatches**:
- Hex color typos
- Opacity values incorrect
- Wrong color references
**Spacing Issues**:
- Padding values don't match design
- Margin inconsistencies
- Gap sizes incorrect
- Container dimensions wrong
### Iteration Strategy
1. **Fix highest-impact differences first** (layout, major positioning)
2. **Then address styling** (colors, fonts, sizes)
3. **Finally tune details** (shadows, borders, spacing fine-tuning)
4. **Test each round of fixes** before moving to next category
5. **Keep comparing** until pixel-perfect match achieved
## Debug Logs (Optional)
If debugging Flutter app issues during workflow:
**Global logs**: `.special/logs.txt`
**Feature-specific logs**: `.special/{FeatureName}/logs.txt`
Contains output from `flutter run` commands for diagnosing errors.