Troubleshooting

Common Issues and Solutions

Extraction & Generation

Q: The generation is taking a very long time. Is something wrong?

A: Design system extraction is a complex process. Here's what's happening:

1. Uploading (10-30 seconds): Your references are being uploaded
2. Extraction (1-5 minutes): AI analyzes colors, typography, spacing
3. Expansion (2-10 minutes): AI generates variations and documentation
4. Merging (1-3 minutes): Results are combined and formatted

What to do:

• Wait for the process to complete (normally 5-15 minutes total)
• Don't refresh the page or close the browser
• Check the status page for detailed progress
• If it's taking longer than 20 minutes, refresh and try again

Q: Generation failed. What should I do?

A: Here are the most common causes:

1. File upload failed

   • Check file size (max 10MB per file)
   • Ensure file format is supported (PNG, JPG, WebP)
   • Try uploading again

2. URL is invalid

   • Verify the link is correct and publicly accessible
   • For Figma: share link must be accessible without authentication
   • For websites: check that the site is loading properly

3. References are too unclear

   • Images might be too blurry or low resolution
   • UI might be partially obscured or cropped
   • Try with clearer images

4. Server error

   • This is rare but can happen
   • Try creating a new project
   • If it persists, contact support

What to do:

1. Check error message for specific details
2. Review your references for quality issues
3. Try with different or additional references
4. Contact support if issue persists

Color Extraction Issues

Q: Colors are wrong or inaccurate

Possible causes:

• Image has strong lighting or shadows
• Colors are gradients, not solid colors
• References have inconsistent color usage

Solutions:

1. Use clearer references: Provide images without shadows or special lighting
2. Clean up colors manually: Adjust extracted colors to match your brand
3. Regenerate with better images: Use high-contrast screenshots
4. Provide more references: Show the same color in different contexts

Example:

Q: Too many similar colors extracted

Possible causes:

• References contain color variations (shadows, gradients)
• Different opacity levels are being treated as different colors
• Detailed mockups with many shades

Solutions:

1. Simplify references: Use cleaner, more minimal designs
2. Merge similar colors: Group colors that are close in value
3. Define semantic groups: Organize colors by purpose (primary, accent, etc.)

Example:

Typography Issues

Q: Detected font is incorrect

Important note: AI cannot always identify proprietary fonts perfectly.

Common issues:

• Font is a custom/proprietary font: AI will approximate with similar font
• Font is very new or unusual: AI might misidentify it
• Multiple fonts are used: Only the most dominant is detected

Solutions:

1. Check the font yourself: Verify which font is actually used
2. Update manually: Adjust the detected font to the correct one
3. Use generic alternatives: If specific font isn't available, use similar alternative

Example:

Q: Text sizes are incorrect or inconsistent

Possible causes:

• References have different zoom levels
• Screenshots contain different device sizes
• UI uses dynamic sizing

Solutions:

1. Normalize screenshots: Use consistent zoom level (100%)
2. Provide consistent references: All screenshots at same device size
3. Manually establish scale: Define typography hierarchy clearly

Typography Scale Example:

Spacing & Layout Issues

Q: Spacing values are odd numbers (17px, 25px, etc.)

Possible causes:

• References use non-standard spacing
• Measurements include borders or shadows
• Screenshots at different scales

Solutions:

1. Standardize to grid: Convert to 8px base unit
2. Review originals: Check if spacing is intentionally irregular
3. Regenerate with clearer references: Use designs that follow standard grids

Example:

Q: Some spacing seems to be missing or incorrect

Possible causes:

• Spacing is created with invisible containers
• Layout uses CSS margins that aren't visible
• Responsive design has different spacing at different sizes

Solutions:

1. Provide more detailed references: Include wireframes or mockups showing spacing
2. Manually measure: If you know the spacing, update it manually
3. Use consistent base unit: Establish an 8px grid in your design

Component Issues

Q: Components are missing or incomplete

Possible causes:

• References don't show all component types
• Components are cut off or partially visible
• Component variations aren't captured

Solutions:

1. Provide more references: Show all component types you need
2. Include full components: Ensure nothing is cropped or hidden
3. Show variations: Include hover states, disabled states, different sizes

Checklist:

• [ ] All button types (primary, secondary, etc.)
• [ ] All input types (text, email, password, etc.)
• [ ] Cards, modals, dropdowns
• [ ] Component states (default, hover, active, disabled, focus)
• [ ] Size variations (small, medium, large)

Q: Component descriptions are inaccurate

Possible causes:

• AI misinterpreted the component purpose
• Component is used in multiple ways
• Context isn't clear from screenshots

Solutions:

1. Edit descriptions manually: Update component names and purposes
2. Provide more context: Explain what each component is used for
3. Include component labels: If available in your design, show labels/names

Data & Export Issues

Q: Can I download the design system in different formats?

A: Yes! Supported formats:

• JSON: Full structured data
• CSS: Ready-to-use CSS variables
• Figma: Importable Figma file
• Tailwind: Tailwind configuration
• Code: Raw code snippets

All formats are available in your project dashboard.

Q: Can I edit the extracted system after creation?

A: Currently, you can export the data and edit it manually. Future updates will include in-app editing.

Workaround:

1. Export as JSON
2. Edit the JSON file in your code editor
3. Use the updated file in your project

Account & Project Issues

Q: I can't find my saved project

Solutions:

1. Go to Your Design Systems in the dashboard
2. Check the project list (sorted by creation date)
3. Use the search feature to find by name
4. Check if you're logged into the correct account

Q: Can I share my design system with others?

A: Yes! You can:

1. Make your project Public in settings
2. Share the public link with anyone
3. Others can view and export (but not edit)

Q: Can I delete a project?

A: Yes, in your dashboard:

1. Click on the project
2. Go to Settings
3. Scroll to Danger Zone
4. Click Delete Project (this is permanent)

Technical Issues

Q: I'm getting an error message. What does it mean?

Common error codes:

| Error | Meaning | Solution | |-------|---------|----------| | 400 Bad Request | Invalid input data | Check file format, URL format, prompt | | 401 Unauthorized | Authentication failed | Log in again | | 403 Forbidden | Permission denied | Check project ownership | | 404 Not Found | Resource doesn't exist | Project may have been deleted | | 429 Too Many Requests | Rate limited | Wait a few minutes before trying again | | 500 Server Error | Server problem | Try again later, contact support if persistent |

Q: The website is slow or freezing

Solutions:

1. Clear browser cache: Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)
2. Disable browser extensions: They can slow down the app
3. Use a different browser: Try Chrome, Firefox, or Safari
4. Check your connection: Ensure stable internet

Q: Images won't upload

Possible causes:

• File size too large (max 10MB)
• Unsupported file format
• Slow internet connection
• Browser cache issues

Solutions:

1. Check file size and format (PNG, JPG, WebP)
2. Reduce image size or optimize with image tool
3. Try uploading from a different browser
4. Clear browser cache and try again

Getting Help

Before Contacting Support

Check this troubleshooting guide and:

1. Review the Getting Started guide
2. Check Best Practices for common mistakes
3. Verify all inputs are correct and high quality
4. Try with different references

Contacting Support

If you can't find a solution:

1. Go to Support page
2. Describe your issue in detail
3. Include:
   • What you were trying to do
   • Error messages you received
   • Steps you already tried
   • Your browser and OS

What Information to Share

Helpful details:

• Screenshots of the error
• Your project ID (found in URL)
• References you used (or description)
• Your prompt/description
• Expected vs. actual result

The more details you provide, the faster we can help!

Note: Most issues can be resolved by following the Best Practices guide and using high-quality references. When in doubt, refer back to the Getting Started guide and try again with improved inputs.