npm package: @floto/designqa-widget
Description: Development tool for visual design comparison and QA in React applications. Compare implementations against Figma designs with AI-powered analysis.
Author: Floto
Latest version: 1.1.2

# @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):

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

or

```bash
yarn add -D @floto/designqa-widget
```

## Quick Start

### 1. Import the Component

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

### 2. Add to Your App

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

```tsx
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

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

## Usage Examples

### Basic Setup

```tsx
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

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

### Different Comparison Modes

```tsx
{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](https://test-app.floto.ai)
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:

```tsx
{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.

```tsx
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

```bash
npm run build
```

### Development Mode

```bash
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](https://github.com/pphproto/floto-designqa-widget/issues)
- Documentation: [https://docs.floto.ai](https://test-app.floto.ai)

## License

MIT © Floto

## Contributing

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

---

Made with ❤️ by [Floto](https://floto.ai)