@floto/designqa-widget

A powerful React component for visual design comparison and QA. Compare your implementation against design files from Figma or uploaded references with AI-powered analysis.

Features

• 📸 One-Click Screenshots - Capture your React application instantly
• 🎨 Design Comparison - Compare against Figma designs or uploaded files
• 🤖 AI-Powered Analysis - Get intelligent feedback on design accuracy
• 🔄 Real-Time Testing - Test and iterate quickly during development
• 🎯 Pixel-Perfect QA - Ensure your implementation matches the design
• 📊 Detailed Reports - View comprehensive comparison results

Installation

Install as a dev dependency (recommended for development/testing environments):

npm install --save-dev @floto/designqa-widget

or

yarn add -D @floto/designqa-widget

Quick Start

1. Import the Component

import { DesignQA } from '@floto/designqa-widget';

2. Add to Your App

Important: Only include this widget in development environments, not in production.

function App() {
  return (
    <div>
      {/* Your app content */}
      <YourComponents />

      {/* Add DesignQA Widget - Only in development */}
      {process.env.NODE_ENV === 'development' && (
        <DesignQA apiKey="your-api-key-here" />
      )}
    </div>
  );
}

3. Start Using

1. Click the floating "Yo!" button in the bottom-right corner
2. Click "Take Screenshot" to capture your UI
3. Click "Select Design" to choose a reference design from Figma or uploaded files
4. Click "Start Comparison" to analyze the differences
5. Click "View Results" to see the detailed comparison report

API Reference

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | apiKey | string | Yes | - | Your Floto API key for authentication | | position | 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | No | 'bottom-right' | Position of the floating button | | apiUrl | string | No | Floto API URL | Custom API endpoint (if using self-hosted) | | comparisonMode | 'smart' | 'strict' | 'relaxed' | No | 'smart' | Comparison sensitivity mode | | processingMode | 'quality' | 'fast' | No | 'quality' | Processing speed vs quality trade-off |

Example with All Props

{process.env.NODE_ENV === 'development' && (
  <DesignQA
    apiKey="your-api-key-here"
    position="bottom-left"
    comparisonMode="strict"
    processingMode="quality"
  />
)}

Usage Examples

Basic Setup

import React from 'react';
import { DesignQA } from '@floto/designqa-widget';

function App() {
  return (
    <div className="app">
      <header>
        <h1>My Awesome App</h1>
      </header>
      <main>
        {/* Your application content */}
      </main>

      {/* Only render in development */}
      {process.env.NODE_ENV === 'development' && (
        <DesignQA apiKey={process.env.REACT_APP_FLOTO_API_KEY} />
      )}
    </div>
  );
}

export default App;

Custom Position

{process.env.NODE_ENV === 'development' && (
  <DesignQA
    apiKey="your-api-key"
    position="top-right"
  />
)}

Different Comparison Modes

{process.env.NODE_ENV === 'development' && (
  <>
    {/* Strict mode - Catches even minor differences */}
    <DesignQA
      apiKey="your-api-key"
      comparisonMode="strict"
    />

    {/* Or Relaxed mode - Focuses on major differences */}
    <DesignQA
      apiKey="your-api-key"
      comparisonMode="relaxed"
    />
  </>
)}

Getting Your API Key

1. Visit Floto Dashboard
2. Sign up or log in to your account
3. Navigate to API Settings
4. Generate a new API key
5. Copy and use it in your application

How It Works

1. Capture: The widget captures a screenshot of your current UI
2. Select: Choose a reference design from Figma or your uploaded library
3. Compare: AI analyzes both images and identifies differences
4. Review: View detailed results with highlighted discrepancies and recommendations

Production vs Development

⚠️ Important: This widget is designed for development and testing environments only.

Recommended Setup

Always wrap the component with an environment check:

{process.env.NODE_ENV === 'development' && (
  <DesignQA apiKey={process.env.REACT_APP_FLOTO_API_KEY} />
)}

Why Dev-Only?

• Reduces production bundle size
• Prevents unnecessary API calls in production
• Keeps your API key secure
• Avoids exposing internal QA tools to end users

Build Optimization

Most bundlers (Webpack, Vite, etc.) will automatically remove the widget from production builds when using process.env.NODE_ENV checks through tree-shaking.

Comparison Modes

• Smart (Default): Balanced analysis focusing on meaningful differences
• Strict: Detects even minor pixel differences for pixel-perfect implementations
• Relaxed: Focuses on major layout and visual differences

Processing Modes

• Quality (Default): Higher accuracy, takes slightly longer
• Fast: Quicker results, suitable for rapid iteration

TypeScript Support

This package includes TypeScript definitions out of the box.

import { DesignQA, DesignQAProps } from '@floto/designqa-widget';

const config: DesignQAProps = {
  apiKey: 'your-api-key',
  position: 'bottom-right',
  comparisonMode: 'smart',
};

function App() {
  return (
    <>
      {process.env.NODE_ENV === 'development' && <DesignQA {...config} />}
    </>
  );
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Development

Prerequisites

• Node.js >= 16
• React >= 17.0.0
• React DOM >= 17.0.0

Building

npm run build

Development Mode

npm run dev

Troubleshooting

Widget Not Appearing

Make sure:

1. You've provided a valid API key
2. The component is rendered in your app
3. There are no z-index conflicts with other elements

Screenshots Not Capturing Correctly

• Ensure the widget is rendered after your main app content
• Check that no elements have higher z-index than 99999
• Verify your app doesn't use iframe-based rendering

API Errors

Common errors and solutions:

• 401/403 Errors: Check your API key is valid and active
• Network Errors: Verify your internet connection
• 500 Errors: The service may be temporarily unavailable, try again

Support

For issues, questions, or feature requests:

• GitHub Issues: https://github.com/pphproto/floto-designqa-widget/issues
• Documentation: https://docs.floto.ai

License

MIT © Floto

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Made with ❤️ by Floto